Security Analytics 8.1.x Reference Guide Updated: Friday, November 15, 2019 Security Analytics Reference Guide Security Analytics 8.1 Copyrights, Trademarks, and Intellectual Property Copyright © 2019 Symantec Corp. All rights reserved. Symantec, the Symantec Logo, the Checkmark Logo, Blue Coat, and the Blue Coat logo are trademarks or registered trademarks of Symantec Corp. or its affiliates in the U.S. and other countries. Other names may be trademarks of their respective owners. This document is provided for informational purposes only and is not intended as advertising. All warranties relating to the information in this document, either express or implied, are disclaimed to the maximum extent allowed by law. The information in this document is subject to change without notice. THE DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. SYMANTEC CORPORATION SHALL NOT BE LIABLE FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES IN CONNECTION WITH THE FURNISHING, PERFORMANCE, OR USE OF THIS DOCUMENTATION. THE INFORMATION CONTAINED IN THIS DOCUMENTATION IS SUBJECT TO CHANGE WITHOUT NOTICE. SYMANTEC CORPORATION PRODUCTS, TECHNICAL SERVICES, AND ANY OTHER TECHNICAL DATA REFERENCED IN THIS DOCUMENT ARE SUBJECT TO U.S. EXPORT CONTROL AND SANCTIONS LAWS, REGULATIONS AND REQUIREMENTS, AND MAY BE SUBJECT TO EXPORT OR IMPORT REGULATIONS IN OTHER COUNTRIES. YOU AGREE TO COMPLY STRICTLY WITH THESE LAWS, REGULATIONS AND REQUIREMENTS, AND ACKNOWLEDGE THAT YOU HAVE THE RESPONSIBILITY TO OBTAIN ANY LICENSES, PERMITS OR OTHER APPROVALS THAT MAY BE REQUIRED IN ORDER TO EXPORT, RE-EXPORT, TRANSFER IN COUNTRY OR IMPORT AFTER DELIVERY TO YOU. 3 Security Analytics Reference Guide Security Analytics 8.1 Table of Contents Recognized Applications 9 Application Groups 9 Backup and Restore 11 Backup 11 Specify the Storage Location Manual Backup Encrypted Backup Scheduled Backup 12 12 12 13 Restore 13 BPF Syntax 15 GRE Encapsulation and BPF Filters 15 Syslog Facilities 17 Standard Syslog Facilities 17 Standard Syslog Levels and Priorities 18 Disable SSH Root Logins 19 MD5-Encrypted Password for Bootloader 20 Command-Line Interface 21 CLI Commands 21 Supported Linux Commands 24 csr.sh 26 dscapture 26 dscapture clearpersist dscapture cleartime dscapture init dscapture map dscapture mapshow dscapture settime dscapture shutdown dscapture start dscapture status dscapture stop dscapture unmap 26 27 27 27 27 28 28 28 29 29 29 dsfilter 29 dsfirewall, dsfirewall6 30 4 Security Analytics Reference Guide Security Analytics 8.1 dslc 32 dslc add 32 dslc del 34 dslc disable 34 dslc enable 35 dslc export 36 dslc factory 37 dslc import 37 dslc set 37 dslc show 39 dslogdump 39 dsmigrate.sh 40 Setup 41 Migrate the Data 42 dsmigratedata 44 Setup 44 Interface Configuration 45 Data-Migration Procedure 45 Operation of dsmigratedata 47 Restarting dsmigratedata 48 Stateful Restart Stateless Restart 48 48 dspcapimport 48 dsportmapping 49 dsregen 50 dszap 51 Actions Performed 53 Running dszap 53 dump_slot 55 dump_slot_chain 55 dump_slot_header slot_<number> 55 dump_slot_elements <filename> 55 dump_slot_pcap <packet_number> 56 dump_slot_trail 56 dump_space_table_entry <slot_id> 56 walk_space_table_journal 57 5 Security Analytics Reference Guide Security Analytics 8.1 dynfilter 57 lsi-rate-tool 58 lsi-show 60 MegaCli | megacli 61 scm pivot_only_provider 62 Add a Pivot-Only Provider 62 Pivot-Only Provider Demonstration 63 Delete a Pivot-Only Provider 66 Sample Pivot-Only Providers 66 scm sessions 68 scm solera_acl elevate 69 scm tally 69 Web Services APIs 71 Install and Test the SoleraConnector Class 71 Session-Based APIs 73 Pivot to Summary Page 73 Single Time-Value Configuration 74 API Changes in Security Analytics 8.1.x 75 New APIs Modified APIs 75 75 Advanced API Queries 77 Example Queries Combining Different Namespaces 77 77 Alerts APIs 79 Anomalies APIs 91 Authentication APIs 100 BPF Filters APIs 111 Capture APIs 116 Central Manager APIs 137 Data Enrichment APIs 158 Date/Time APIs 178 6 Security Analytics Reference Guide Security Analytics 8.1 Drive-Space Management APIs 182 Extractor APIs 186 Geolocation APIs 219 Indicators APIs 226 License APIs 236 Logging and Communication APIs 240 Metadata APIs 265 Network APIs 268 Packet Analyzer APIs 274 PCAP APIs 277 Playback APIs 300 Report and Report Status APIs 302 Rules APIs 338 Security APIs 347 Statistics APIs 367 Summary Page APIs 369 System APIs 378 Upgrades APIs 380 User Account APIs 386 Web Interface Settings APIs 405 API Appendix 414 Using Polling with the APIs 415 Syntax: Identity Path 415 7 Security Analytics Reference Guide Security Analytics 8.1 Syntax: Enhanced Primary Filter Array Syntax: Advanced-Filter Array Syntax: Primary Filter Array Syntax: Timespan Array Syntax: Timespan Date Array Syntax: Geolocation Internal Labels Syntax: Scheduled Events LDAP Schema Values Menu > Analyze > Alerts > Summary Menu > Analyze > Anomalies > Summary Capture Summaries Inputs 415 416 418 419 419 419 419 420 422 422 422 Using the APIs 424 Best Practices 424 Downloading Extracted Artifacts 424 Downloading PCAPs 428 Resources 432 8 Security Analytics Reference Guide Security Analytics 8.1 Recognized Applications 59 New Recognized Applications in Security Analytics 8.1.1. Total: ~2900 To obtain an XLSX or CSV list of recognized applications, select Reference > Recognized Applications in the Help Files, which are located: n In the web interface under About > Help > [language]. n On https://support.symantec.com/content/unifiedweb/en_US/Documentation.1145515.html. Select the appropriate version, and then under Administration Guide open the Security Analytics 8.1.1 WebGuide. The applications in the files can be identified by Security Analytics. The values in these tables appear in the Application, Application Group and Application Group over Time reports and report widgets and are valid for application_group=<application_group> and application_id=<application_id> in the primary filter bar, for example, application_group="Network Service" or application_id=twitter Application Groups Following are sample applications that are included in each application group. Where the last item is preceded by the word "and," all applications for that group are listed: n Antivirus — zonealarm, zonealarm_update, sophos_update, and lookout_ms n Application Service — citrix_pvs, ldap, syslog, perforce, windows_marketplace, xfs n Audio/Video — apple_music, baidu_player, google_play_music, gotomeeting, h245, hulu, iheartradio, itunes, netflix, pplive, qqlive, rtsp, spotify n Authentication — chap, diameter, krb5, pap, radius, tacacs_plus n Behavioral — high_entropy and spid n Compression — ccp and comp n Database — db2, drda, mysql, postgres, sybase, tds, tns n Encrypted — i2p, ipsec, isakmp, ocsp, ssh, ssl, tor, and tor2web n ERP — sap n File Server — afp, ftp, gmail_drive, netbios, nfs, smb, tftp n File Transfer — aim_transfer, bits, filesharepro, imessage_file_download, irc_transfer, irods, jabber_ transfer, mypocket, paltalk_transfer, and ymsg_transfer n Forum — google_groups, ircs, kaskus, linkedin, live_groups, mibbet, nntp, nntps, odnoklassniki, r10, tapatalk, vkontakte, and yahoo_groups 9 Security Analytics Reference Guide Security Analytics 8.1 n Game — all_slots_casino, angry_birds, candy_crush_saga, cstrike, eve_online, poker_stars, qq_r2, quake, runescape, wow n Instant Messaging — aim, badoo, facebook_messenger, gmail_chat, gtalk, irc, jabber, qq, whatsapp, ymsg n Mail — imap, imaps, lotusnotes, mapi, pop3, pop3s, smtp, and smtps n Microsoft Office — groove n Middleware — amqp, dcerpc, diop, giop, iiop, java_rmi, rpc, soap, thrift n Network Management — cdp, cip, enip, lcp, modbus, netflow, rsvp, sccm, snmp, wccp n Network Service — 8021q, arp, crudp, dccp, dhcp, dnp3, dns, eth, fibre_channel, hopopt, icmp, ip, ip6, isis, mux, nbns, ntp, sctp, svn, udp, whois n Peer to Peer — bitcoin, bittorrent, directconnect, edonkey, filetopia, gnutella, kazaa, qqmusic, thunder n Printer — apple_airprint, bjnp, cups, ipp, jetdirect, and lpr n Routing — bgp, eigrp, mpls, ospf, rip1, rip2, stp n Security Service — fsecure, ghostsurf, mcafee, and peerguardian n Standard — established, incomplete, malformed, and unknown n Telephony — bssap and isup n Terminal — rlogin, rsh, telnet, telnets, and tnvip n Thin Client — anydesk, gotomypc, ica, jedi, pcanywhere, radmin, rdp, vmware, x11 n Tunneling — etherip, gre, http_tunnel, l2tp, ppp, pppoe, socks5, teredo n WAP — bxml, mmse, smpp, ucp, wsp, wtls, and wtp n Web — 4chan, abcnews, alibaba, amazon_aws, baidu, bbc, disney_channel, ebay, elpais, facebook, flickr, google, http, https, kaspersky, nytimes, outlook, pandora, reddit, sharepoint, travelocity, tumblr, twitter, wikipedia, windows_update, yahoo, youtube n Webmail — gmail, live_hotmail, mailru, orangemail, owa, yandex_webmail, ymail2, zimbra 10 Security Analytics Reference Guide Security Analytics 8.1 Backup and Restore The backup and restore scripts save system data but not the data on the capture and index drives. To migrate capture data, use dsmigratedata (version 7.x) or dsmigrate.sh (version 8.x). The types of data saved in the backup archive include but are not limited to the following: n Network configuration n Filters n Disk configuration files n Geolocation data n Authentication configuration data n Playback sessions n Local user accounts n Some crontab-related configuration n SSH configuration n GUI-related configuration n Web server configuration and SSL certificates n n List of active extractor-plugins licensing Database tables (system and userdefined) n System time settings Backup n Symantec recommends that you store the backup archives off-appliance — on a network share or a USB drive — so that you do not lose the archives in the event of a local hard-drive failure. n You must back up and restore to the same software version, including the 5digit build version. Do not back up the settings, then upgrade the appliance, and then attempt to restore the settings. n The appliance on which you are restoring the settings must be licensed before running solera-restore.sh. n When restoration is completed all of the user passwords are reset to SymantecPassword123? Security Best Practice Use the backup-passwd script to password-protect and encrypt the backup file. 11 Security Analytics Reference Guide Security Analytics 8.1 Specify the Storage Location If no storage location is specified, the backup archive will be written to the /tmp directory on the appliance's system drive, where it is vulnerable to loss in the event of a system failure. 1. Modify the backup configuration file: vi /etc/solera/config/backup.conf 2. Specify the backup directory on the external storage device: # output directory to store backup archives OUTPUT_DIR=<bdir> where <bdir> is the backup directory. 3. Save backup.conf and exit. The archived files are written to the directory specified in backup.conf or to /tmp if no location is specified. The backup archive is named solera-backup-<appliance_name>-<YYYYMMDD>T<hhmm>Z.tgz, where <appliance_ name> is the appliance hostname. syntax /etc/utils/solera-backup.sh -[d|u] [-h] parameters You must specify either -d or -u. -h Help — Show this message -d Default — Exclude users and groups from the backup -u Include users and groups — user passwords will be reset Manual Backup 1. Log in as root. 2. Run the backup script: /etc/utils/solera-backup.sh -[d|u] Encrypted Backup To encrypt the backup file, follow these steps: 1. Log in as root. 2. Run the backup-password script. /etc/utils/solera-backup-passwd.sh -[d|u] 12 Security Analytics Reference Guide Security Analytics 8.1 3. Provide a password when prompted. The script transforms the plaintext into a base64-encoded and encrypted password, stored in /etc/solera/.backup_passwd. To disable encryption, run the backup-password script again but leave the password blank when prompted. The .backup_passwd file will be deleted. 4. When you run the backup script — manually or scheduled — it appends ENC to the file name: solerabackup-<hostname>-<timestamp>.tgz.enc Scheduled Backup To schedule regular backups, do one of the following: n Put a symlink in one of the pre-scheduled cron directories, for example: ln -s /etc/utils/solera-backup.sh /etc/cron.daily/backup n Put the cron job in root's crontab, for example: crontab -e # back up every four hours at 15 min past the hour 15 */4 * * * /etc/utils/solera-backup.sh # back up once per month on the 2nd at 3:30am 30 3 2 * * /etc/utils/solera-backup.sh Restore To restore backed-up settings to an appliance, verify that the appliance has access to the backup file. If necessary, copy the backup archive to the /tmp directory. If you are restoring the data to a different appliance, you will need to manually adjust all of the settings that are appliance-specific. For example, the license is based on the appliance's MAC address. For further assistance, contact Symantec Support. 1. Run the restore script. If the backup archive was encrypted, you must provide the password when prompted. Unencrypted: /etc/utils/solera-restore.sh solera-backup-<hostname>-<timestamp>.tgz Encrypted: /etc/utils/solera-restore.sh solera-backup-<hostname>-<timestamp>.tgz.enc 2. When prompted, reboot the appliance to initiate the restore process. 13 Security Analytics Reference Guide Security Analytics 8.1 The archive file is copied to the /boot partition. After the reboot, the firstboot process copies the files in the archive to the file system, applies the changes to the database, and reboots one more time to activate all of the system changes. The appliance is then restored to the same point as when the backup file was generated, except for the capture and index data. To cancel a restore, run /etc/utils/solera-restore.sh cancel. To restart the restore, run /etc/utils/solera-restore.sh. 14 Security Analytics Reference Guide Security Analytics 8.1 BPF Syntax On Symantec Security Analytics you can create complex, explicit filters using BPF expressions to specify what to include—or what to exclude, using NOT. BPF expressions are used in capture filters, PCAP downloads, and playback. BPF uses the following operators: n Negation (!, not) n Concatenation (&&, and) n Alternation (||, or) Negation has the highest precedence. Alternation and concatenation have equal precedence and associate left to right. If an identifier is given without a keyword, the most recent keyword is assumed. For example: not port 80 and 443 is short for (not port 80) and (port 443), which should not be confused with not (port 80 and 443). Filters containing net and mask are not valid for IPv6 addresses. For additional information on using BPF, including all available parameters and syntax, see biot.com/capstats/bpf.html. BPF Syntax Description (!port 514) (not port 514) Excludes all syslog traffic (!portrange 8865-8870) Excludes all traffic on ports 8865 through 8870 (host 192.0.2.56) Includes traffic to and from 192.0.2.56 (dst host 203.0.113.3) Includes traffic destined for 203.0.113.3 !(port 443 or port 123 or port 53) Excludes traffic on ports 443, 123, and 53 !(net 203.0.113.0 mask 255.255.255.0) !(net 203.0.113) !(net 203.0.113.0/24) Excludes traffic on network 203.0.113.0 with a 24-bit mask. You can specify a dotted triple, dotted pair, or a single number, and the mask will be automatically assumed as 255.255.255.0 for a dotted triple, 255.255.0.0 for a dotted pair, and 255.0.0.0 for a single. (src net 198.51.100.0/24) Includes traffic originating from the network 198.51.100.0 network (port 80 or port 3389) (port 80 or 3389) Includes all traffic on ports 80 and 3389 only (vlan && host 192.0.2.35) (vlan and host 192.0.2.35) Includes all 802.11Q-tagged traffic to and from 192.0.2.35 GRE Encapsulation and BPF Filters When specifying a capture filter for GRE-encapsulated WCCP, you can filter on the original IP addresses by using packet offsets in the filter. The syntax for the offset is as follows: 15 Security Analytics Reference Guide Security Analytics 8.1 ip[<byte 1 of IP>:<byte length of IP>] = <base10 of IP hex string> In a GRE-encapsulated packet header, the source IPv4 address inside the encapsulation begins on the 40th byte from the beginning, and an IPv4 address consists of 4 bytes. Therefore, the source address is specified thus: ip[40:4] = <base10 of IP hex string> If the original source IP is 198.51.100.10, the IP in hexadecimal is 0xC633640A and in base10 is 3325253714. Therefore, the source IP is specified as follows: ip[40:4] = 3325253714 The destination IP immediately follows the source IP, so if the destination IP is 203.0.113.44, specify it as follows: ip[44:4] = 3405803820 examples Include all GRE-encapsulated traffic from 192.0.2.10 (ip[40:4] = 3232248330) Exclude all GRE-encapsulated traffic that is destined for 203.0.113.44 !(ip[44:4] = 3221225994) 16 Security Analytics Reference Guide Security Analytics 8.1 Syslog Facilities System logs are the product of a communications protocol (RFC 5424) for transmitting event messages and alerts across an IP network. For more information, see www.syslog.org and tools.ietf.org/html/rfc5424. Standard Syslog Facilities Facility is defined by the syslog protocol, and provides a rough clue of where in a system the message originated. Level Facility Function 0 kern Kernel process messages 1 user Regular user process messages 2 mail Mail system process messages 3 daemon 4 auth 5 syslog 6 lpr Line printer system process messages 7 news News subsystem process messages 8 uucp UUCP subsystem process messages 9 cron Cron (clock/timing) subsystem process messages 10 authpriv 11 ftp File Transfer Protocol system process messages 12 ntp Network Time Protocol system process messages 13 log Audit alternate ID for authorization process messages 14 log Alert alternate ID for authorization process messages 15 clock 16–22 local use 0 through 7 Other system daemons process messages Authorization system or programs that ask for user names and passwords ( login, su, getty, ftpd) process messages System log process messages A separate flag for routing authorization messages to a log file that has more restricted permissions than those of auth. Daemon alternate ID for cron (clock/timing) subsystem process messages Reserved for site-specific messages 17 Security Analytics Reference Guide Security Analytics 8.1 Standard Syslog Levels and Priorities Syslog message levels are associated with the urgency or criticality of the event that triggered the message. Level Name Meaning 0 Emergency System is unusable. A "panic" condition, such as an imminent system crash, usually broadcast to all users. 1 Alert Action must be taken immediately. Notify staff who can fix the problem — example is a corrupted system database. 2 Critical Critical conditions, usually hardware errors. Indicates a failure in a primary system that should be corrected immediately. CRITICAL problems should be fixed before ALERT issues. 3 Error Error conditions. Non-urgent failures — these should be relayed to developers or administrators; each item must be resolved within a given time. 4 Warning Warning conditions. Warning messages are not errors but indications that an error will occur if action is not taken, e.g. file system 85% full. Each item must be resolved within a given time. 5 Notice Normal but significant condition. Events that are unusual but not error conditions — might be summarized in an email to developers or admins to spot potential problems. No immediate action required. 6 Informational Informational messages. Normal operational messages — may be harvested for reporting, measuring throughput, etc. No action required. 7 Debug Debug-level messages. Info useful to developers for debugging the application; not useful during operations. 8 None Do not send messages from the indicated facility to the selected file. For example, specifying *.debug;mail.none sends all messages except mail messages to the selected file. 18 Security Analytics Reference Guide Security Analytics 8.1 Disable SSH Root Logins Security Best Practice n Disable root access via SSH. n If you disable SSH root logins, be sure to review log files for root logins and activity. This procedure disables root access over SSH connections but preserves root access via console. 1. Edit the sshd_config file: [root@hostname ~]# vi /etc/ssh/sshd_config 2. Uncomment the line #PermitRootLogin yes and set the value to no: PermitRootLogin no 3. Save and exit sshd_config. 4. Restart the SSH daemon to apply the changes: [root@hostname ~]# systemctl restart sshd To disable the root account entirely, append /settings/initial_config to the appliance's IP address or hostname in the address bar of the browser. Under Root Password, select Lock Root Account. Warning: You cannot re-enable the root account unless you have console access to the appliance, and then you will have to contact Symantec Support for assistance. 19 Security Analytics Reference Guide Security Analytics 8.1 MD5-Encrypted Password for Bootloader This page applies only to Dell-based hardware and virtual machines. Security Best Practice Password-protect the bootloader. 1. Use the grub2-setpassword utility: [root@hostname ~]# grub2-setpassword Enter password: <grub_password> Confirm password: <grub_password> Follow best key-maintenance practices by manually recording this password and keeping a copy in a secure location that is separate from the appliance. 2. When attempting to edit the grub menu the credentials are root and the grub password. Do not use the root system password here. Enter Username: root Enter Password: <grub_password> 20 Security Analytics Reference Guide Security Analytics 8.1 Command-Line Interface The CLI is accessed via an SSH connection to bond0. Root access to the CLI is granted to whomever knows the root-level password, which is established on the Initial Configuration page while setting up Symantec Security Analytics for the first time. Use passwd to change the root password. CLI Commands There are three levels of CLI access to grant via RBAC: n Base—Read-only commands such as ls, pwd, less n Tier 1—Networking and File System Management n Tier 2—File System and Admin Utilities, Process and Drive Management See Group Permissions in the Security Analytics 8.1.x Administration and Central Manager Guide on support.symantec.com for details. The following commands apply specifically to Security Analytics. Click on linked text to see the syntax. With admin permissions, some commands permit sudo access (X in the sudo column). Commands that are shaded in yellow are new in Security Analytics 8.1.1. Commands that are shaded in gray have been deprecated in 8.1.x. Command Use sudo build-ds-capture Constructs capture file system (partition, format, filesystem, fstab, mount, etc.). Ruby script. Uses a config file. build-ds-extras Constructs database/home-apache for JBOD systems (format, filesystem, fstab, mount, etc.). Ruby script. build-ds-index Constructs index file system (partition, format, filesystem, fstab, mount, etc.). Ruby script. Uses a config file. X X X cfg_bond_interface.py A script to set the IP address of bond0. See 8.1.x Setup for instructions. check-services Displays the status of known and expected services check_slot_files Replaces dsfsck. Checks the DPDK file system and does limited repairs. Use when directed by Symantec Support. csr.sh Collects and concatenates log/config/status files into a single output tarball (Customer Service Report). Used for troubleshooting an appliance. BASH script. 21 X Security Analytics Reference Guide Security Analytics 8.1 Command Use sudo dmidecode Intel-based hardware only. Runs -s <chassis-serial-number> to see the appliance serial number or asset tag. For SA-S500 series appliances, run /opt/bluecoat/clp/bin/serial_number to see the appliance serial number. For all hardware, select Settings > About on the web UI in version 7.3.2 and later. dscapture Instructs the appliance to capture network data dsfilter Displays filters assigned to a specified interface dsfirewall Toggles the IPv4 firewall on and off X dsfirewall6 Toggles the IPv6 firewall on and off X dslc Configures the logging mechanisms (syslog, SNMP, email). X dslicenseinfo Displays the license key and the features that are enabled on this appliance. dslogdump Displays the events captured by the system log. dsmigrate Migrates PCAPs from a 7.x or 8.x appliance to an 8.x appliance. dsmigratedata Migrates capture data from one appliance to another. Not for migration to 8.x. dspcapimport Imports PCAP files X dsportmapping Customizes your port-to-application mapping dsregen Retransmits captured network traffic from a virtual network interface to a physical network interface ("playback" on the web UI). dsrinfo Lightweight utility for capture file system config data (number of slots, recycle head location, etc.). X dsseed Generates the seed file used for the license. dsview-text Text-based specialization of dsview. dsvmswitch Switches VM capture configuration: 2 sizes (1 large, 1 small). For the Security Analytics virtual appliance only. dszap Deletes ALL captured data (including indexes and reports) and reinitializes the data storage. Destroys all existing capture and index data. X dump_slot Displays various data points concerning slots. dynfilter Displays and manages the dynamic filters created by autonotchd expand-ds-storage Adds new disk storage subsystems without reinstalling Security Analytics. fix-iosched Script. Sets I/O scheduler options. Called in first boot. getpmap.sh Used by csr.sh. BASH script. gindiag.sh Gathers relevant information to assist in troubleshooting a GIN connection. 22 X Security Analytics Reference Guide Security Analytics 8.1 Command Use sudo ipmitool Runs ipmitool sensor for a highly detailed list of power levels, fan speeds, temperatures, and so on. For a simplified version run ipmitool sdr lhr_flat_to_qdb Uploads flat-file lists of MD5, SHA1, or SHA256 hashes to the Custom Hash List lru_calc.sh Determines the size of the slot cache. BASH script. lsi-classify Wrapper around the LSI RAID controller classification scheme. Ruby script. lsi-make-good Helper utility to set physical disk state back to "good" in an LSI JBOD. BASH script. lsi-rate-tool Sets, resets, or shows rates as a percentage of CPU load for RAID manipulations such as background initialization, foreground initialization, consistency check, reconstructions, etc. BASH script. lsi-show Shows LSI RAID controller data in a condensed and summarized form. Ruby script. X X lspci Shows all hardware attached to the PCI bus megacli SAS RAID-management tool by LSI MegaCli X oomstat.sh Handles out-of-memory conditions. BASH script. parted-report Wraps the parted output system-processing for partition size info. Ruby script. product-matrix-lookup Drive localization file names for the Security Analytics appliance on either Dell or legacy DS-xxxx models (not VMs); control product/modelbased settings such as IRQ balance, serial-line name, X desktop support, management interface. scm migrator Deprecated in 8.1.1. Imported and exported appliance settings as a JSON file. scm pivot_only_provider Adds a pivot-only reputation provider to the View Reputation Provider menus in the UI. scm solera_acl elevate Restores a GUI account to admin status. scm solera_acl shell_only Creates a shell-only user. scm tally Enables GUI user accounts. scm sessions Clears session controls. scotus Gracefully stops system-related services prior to performing other tasks. scsi-devices Wrapper around the SCSI-to-device-name mapping. Ruby script. solera_enet_config.py Orders Ethernet interfaces during first boot. Python script. 23 X Security Analytics Reference Guide Security Analytics 8.1 Command Use sudo solera-affinity Sets CPU affinities. Called from startup on boot for every boot. BASH script. update-sysctl Tunes SYSCTL settings for optimal performance. BASH script. X Supported Linux Commands The CLI provides access to the following Linux commands that do not require root-level permissions. For more information about these commands, including the parameters for each, visit www.tldp.org. Command Effect sudo awk Combines the functions of grep and sed; allows substitution items from an input file's lines for items in a template, or performs calculations on numbers within a file cat Concatenates files and prints to the standard output chkconfig Updates and queries runlevel information for system services cp Copies files and directories date Prints or sets the system date and time dhclient Enables DHCP on an interface. grep Searches files for lines containing specified criteria head Prints the first n lines of files to the standard output (default = 10 lines) hwclock Queries and sets the hardware clock ifconfig Not supported in 8.x for eth0 configuration. Use the cfg_bond_ interface.py script to configure bond0 as shown in Setting Up Security Analytics 8.1.1 in the Security Analytics 8.1.1 WebGuide on support.symantec.com. To see packet and error counts run ds_dpdk_ stats.py --all . You can use ifconfig to see interface information on most 8.0.x virtual machines. ifdown Disables a specified network interface ifup Enables a specified network interface ip To view and edit routing, devices, policy routing, and tunnels X X X jsondiff Usage: jsondiff <left_file>.json <right_file>.json kill Terminates a process X less Enables forward and backward movement while reviewing a text file ln Creates links to target files ls Lists information such as size, date created, and directory for specified files 24 Security Analytics Reference Guide Security Analytics 8.1 Command Effect sudo mii-tool View and edit Media-Independent Interface status X mkdir Creates directories mkfs Builds a Linux file system mount Mounts a file system mv Renames or moves files ngrep Searches for strings across packet data X netstat Prints network connections, routing tables, interface statistics, masquerade connections, and multicast memberships on the standard output nice Runs a command at a lower priority level nohup Suppresses a hang-up signal while running a command ntpdate Sets a system's clock to match the time published by servers running NTP passwd Change the root-level password. Initial root password is set on /settings/initial_config ping Uses ICMP to test host connectivity pkill Looks up or signals processes based on name and other attributes reboot Reboots the appliance X X rm Deletes a file rmdir Deletes a directory route Show or edit the IP routing table X scp Securely copies files between hosts on a network sed Replaces or modifies lines with the specified file systemctl Stops, starts, or restarts a system service X shutdown Shuts down the appliance solo Prevents multiple cron instances from running simultaneously sudo Executes a command as a user with greater privileges sync Synchronizes data on disk with memory X tail Prints the last n lines of files to the standard output (default = 10 lines) top Displays top CPU processes umount Dismounts file systems X uname Prints system information vim Opens the VIMproved programming text editor 25 Security Analytics Reference Guide Security Analytics 8.1 Command Effect sudo whoami Prints the user name/user ID for the current session csr.sh The web interface equivalent for this command is found on the Menu > System page. > Settings The CSR shell script collects several hardware and software log files that contain information useful for troubleshooting an appliance. Typically, you only need to run this script when directed to do so by Symantec Support. syntax csr.sh While the script runs, it posts lists that indicate the status of the information-gathering process. The result of the script is a compressed BZIP file, stored in the /home/csr directory. You can use SCP to retrieve the file and then attach it to your Symantec Support case. dscapture Instructs the system to capture network data. Some of the web interface equivalents to this command are on the Menu Capture > Summary page. > syntax dscapture --<operator> [<parameter1>] [<parameter2>] … [<parameterN>] dscapture clearpersist Clears all persistent captures and maps. syntax dscapture --clearpersist 26 Security Analytics Reference Guide Security Analytics 8.1 dscapture cleartime Clears the time values, defined by the settime operator, that are associated with the specified virtual network interface. syntax dscapture --cleartime <virtual_network_interface> example [root@hostname ~] dscapture --cleartime ifm0 dscapture init Initializes the system’s data store in preparation for receiving captured data. syntax dscapture --init <hostname> example [root@hostname ~] dscapture --init ds1.mydomain.com dscapture map Maps the specified virtual network interface to the specified physical network interface so that it can read captured data from that physical network interface. The persist | nopersist parameter controls whether the mapping automatically resumes after reboot. syntax dscapture --map <virtual_network_interface> <physical_network_interface> [-nopersist| --persist] example [root@hostname ~] dscapture --map ifm0 eth2 eth4 --persist The virtual interface ifm0 is mapped to the physical interfaces eth2 and eth4; this mapping will persist after reboot. Also see Playback. dscapture mapshow Displays a list of all network interfaces, both physical and virtual, and a list of virtual network interface mappings to physical network interfaces. syntax dscapture --mapshow 27 Security Analytics Reference Guide Security Analytics 8.1 dscapture settime Specifies a time at which the specified virtual network interface starts reading captured data. This allows you to select a specific time period as a starting point when reading or regenerating captured data. Specify the time in the following format: MM.DD.YYYY.hh.ii.ss This is not the same format that is used for APIs. By default, the virtual network interface begins reading data from the beginning of the captured data stream. Use the settime operator to specify a point in the data stream at which you want to start sending data to the virtual network interface. Optionally, you can specify an end_time parameter at which the virtual network interface stops reading from the data stream. syntax dscapture --settime <virtual_network_interface> <start_time> [<end_time>] example [root@hostname ~] dscapture --settime ifm0 02.23.2019.16.30.00 02.24.2019.16.30.00 The virtual interface ifm0 plays back data from Feb. 23, 2013, 4:30 p.m. through Feb. 24, 2013, 4:30 p.m. dscapture shutdown Shuts down all capture interfaces. syntax dscapture --shutdown dscapture start Starts capturing network traffic on the specified physical network interface. The persist | nopersist parameter controls whether capture automatically resumes on the interface after reboot. syntax dscapture --start <physical_network_interface> [--nopersist| --persist] example [root@hostname ~] dscapture --start eth2 --persist Starts capture on the physical interface eth2. Capture automatically resumes on the interface after reboot. 28 Security Analytics Reference Guide Security Analytics 8.1 dscapture status Displays the current capture status for all physical network interfaces in the appliance, along with memory statistics and memory usage information for each physical network interface. syntax dscapture --status dscapture stop Stops capturing network traffic on the specified physical network interface. The persist | nopersist parameter controls whether capture automatically resumes on the interface after reboot. syntax dscapture --stop <physical_network_interface> [--nopersist| --persist] example [root@hostname ~] dscapture --stop eth2 --nopersist Stops capture on the physical interface eth2. The persist setting is also cleared from the interface. dscapture unmap Disconnects the specified virtual network interface from its associated physical network interface. syntax dscapture --unmap <virtual_network_interface> example [root@hostname ~] dscapture --unmap ifm0 All physical interfaces that were associated with ifm0 are no longer associated. dsfilter Displays the capture filters assigned to a specific interface, lists the active filters on any given interface, applies a new filter, removes a filter, or tests a filter. Some of the web interface equivalents to this command are on the Menu Capture > Summary page. syntax [sudo] dsfilter <parameters> 29 > Security Analytics Reference Guide Security Analytics 8.1 [sudo] dsfilter -l -i <interface> [-f <bpf_expression_file>] <bpf_expression> [sudo] dsfilter -c [-f <bpf_expression_file>] <bpf_expression> [sudo] dsfilter -usS -i <interface> [sudo] dsfilter -m [-f <bpf_expression_file>] /pfs/merge/<pcap> parameters -i Specifies the interface. This can also be a virtual interface used for playback (e.g., ifm0). -l Loads a filter onto a specified interface. -f BPF expression file. -c Compiles the filter only; does not load it onto the interface. -u Unloads a filter from a specified interface. -s Prints the currently loaded filter from a specified interface. -m Creates a filter snapshot. You must pass in a BPF file as well as the PCAP file in the /pfs/merge directory. -l Loads a filter onto a specified interface. -S Prints the currently loaded structure representation of a filter from a specified interface. examples [root@hostname ~] dsfilter -i eth3 -s Displays the capture filter loaded on interface eth3. [root@hostname ~] dsfilter -i eth5 -u Unloads the capture filter running on interface eth5. [root@hostname ~] dsfilter -i eth4 -l "port 80 || port 443" Applies a capture filter for port 80 and port 443 on interface eth4. [root@hostname ~] dsfilter -l -i eth3 -f <path_to_filter_file> Applies a capture filter from an ASCII text file on interface eth3. The text file should be a plain ASCII text file containing the full BPF filter and nothing else. When you apply or remove a filter from the command line, refresh the browser to see the change in the UI. dsfirewall, dsfirewall6 Toggles the appliance IPv4 or IPv6 firewall on and off. Use iptables to configure individual firewall rules. 30 Security Analytics Reference Guide Security Analytics 8.1 The web interface controls for the firewall are on the Menu page. syntax [sudo] dsfirewall --<parameter> parameters status Displays the status of the firewall start Enables the firewall stop Disables the firewall restart Reboots the firewall examples [root@hostname ~] [sudo] dsfirewall --stop Disables the appliance's IPv4 firewall. [root@hostname ~] [sudo] dsfirewall6 --status Shows IPv6 firewall activity (use of a pipe or paginator is recommended) 31 > Settings > Security Security Analytics Reference Guide Security Analytics 8.1 dslc The web interface equivalents for many of these commands are on the Menu > Settings > Communication pages. Configures the system's communication mechanisms (syslog, SNMP, email): [sudo] dslc <parameters> <subsystem> [<param1>] [<param2>]…[<paramN>] dslc add Adds the specified remote logging server including authentication and encryption, where required. The system supports only SHA for authentication and AES for privacy. syntax [sudo] dslc add snmpv2 <target> <server_ip> <community> [port <port_num>] [sudo] dslc add snmpv3 <target> <server_ip> <security_name> SHA <auth_key> AES <privacy_key> [port <port_num>] [sudo] dslc add syslog <target> <variable> parameters subsystem target snmpv2 trap2sink informsink SNMPv2 trap <community> Read-only community name <server> Server IP address <port> Optional — The server port. Leave blank for the default (162) SNMPv2 inform <community> Read-only community name <server> Server IP address <port> Optional — The server port. Leave blank for the default (162) 32 Security Analytics Reference Guide Security Analytics 8.1 subsystem target snmpv3 trap2sink informsink email syslog SNMPv3 trap; variables must be entered in this order: <server> Server IP address <secname> User name <authkey> SHA-hashed password (hex string) <privkey> AES-hashed password (hex string) <port> Optional — Port number; leave blank for the default (162) SNMPv3 inform; variables must be entered in this order: <server> Server IP address <secname> User name <authkey> SHA-hashed password (hex string) <privkey> AES-hashed password (hex string) <port> Optional — Port number; leave blank for the default (162) <email_ address> Email address; the SMTP server must already be configured using dslc set server <server> Server IP address or hostname <port> Server port; syslog default is 514 <protocol> Transport protocol; default is udp: [tcp | udp | tls | tls-fips] <facility> Syslog facility examples [root@hostname ~] [sudo] dslc add snmpv2 trap2sink 192.0.2.44 rotrapcommunity 5162 [root@hostname ~] [sudo] dslc add snmpv3 informsink 192.0.2.40 usRdewd SHA <hex_string> AES <hex_string> [root@hostname ~] [sudo] dslc add syslog server 192.0.2.189 514 tls-fips kern many-to-many syslog/facility association [root@hostname [root@hostname [root@hostname [root@hostname ~] ~] ~] ~] [sudo] [sudo] [sudo] [sudo] dslc dslc dslc dslc add add add add syslog syslog syslog syslog server server server server 203.0.113.11 203.0.113.11 203.0.113.22 203.0.113.22 33 514 514 514 514 tcp tcp tcp tcp mail daemon cron auth Security Analytics Reference Guide Security Analytics 8.1 [root@hostname ~] [sudo] dslc add syslog server 203.0.113.33 514 tcp cron [root@hostname ~] [sudo] dslc add syslog server 203.0.113.33 514 tcp daemon On the web interface, only the IP address, port number, and protocol for each entry will be visible, and so it will appear that there are duplicate entries when the same server is associated with two or more facilities. Run dslc show syslog to see which facilities are associated with each server. dslc del Deletes the specified remote logging target. syntax [sudo] dslc del <subsystem> <target> [server] parameters subsystem target snmp trap2sink SNMPv2 trap target Press Enter to see SNMP trap servers 0–N server informsink SNMPv2 inform target Press Enter to see SNMP inform servers 0–N server email syslog <email_ address> Email address to delete server Press Enter to see syslog servers 0–N examples [root@hostname ~] [sudo] dslc del snmp trap2sink server [root@hostname ~] [sudo] dslc del email admin@company.com [root@hostname ~] [sudo] dslc del syslog server dslc disable Disables the specified subsystem. syntax [sudo] dslc disable <subsystem><event1> [<eventN>] 34 Security Analytics Reference Guide Security Analytics 8.1 parameters subsystem event category misc All other events system System events user User events playback Network traffic playback events capture Network capture events deepsee Analytical events such as reporting hardware Hardware events alerts Alert actions For each of these events, you must specify at least one of the following targets: snmp syslog local Events are written to the local log (default) snmp Events are sent to an SNMP server email Events are sent to an email account syslog Events are sent to a remote syslog server all Events are sent to all targets authtrap SNMP authorization traps snmpd SNMP daemon coalesce syslogs merged into a single log examples [root@hostname ~] [sudo] dslc disable snmp authtrap [root@hostname ~] [sudo] dslc disable category hardware syslog dslc enable Enables the specified subsystem. syntax [root@hostname ~] [sudo] dslc enable <subsystem> <event1> <event2> [<target1> <target2>] 35 Security Analytics Reference Guide Security Analytics 8.1 parameters subsystem event category misc All other events system System events user User events playback Network traffic playback events capture Network capture events deepsee Analytical events such as reporting hardware Hardware events For each of these events, you must specify at least one of following targets: snmp syslog local Events are written to the local log (default) snmp Events are sent to an SNMP server email Events are sent to an email account syslog Events are sent to a remote syslog server all Events are sent to all targets authtrap SNMP authorization traps snmpd SNMP daemon coalesce Merge syslogs into a single log examples [root@hostname ~] [sudo] dslc enable snmp authtrap [root@hostname ~] [sudo] dslc enable category system syslog dslc export Exports the logging configuration file to stdout. syntax dslc export 36 Security Analytics Reference Guide Security Analytics 8.1 dslc factory Resets the communication system to its default settings. syntax dslc factory defaults subsystem default settings SNMP syslog n rocommunity — public n authproto — SHA n rouser — public n authkey — [empty] n trapcommunity — public n privproto — AES authtrapenable — off n n privkey — [empty] n snmpdenenable — off trap sink server port — 161 n n inform sink server port — 162 n version — 1 n facility — 16 n log coalescing — off n remote syslog server port — 514 dslc import Imports the specified logging configuration file. You can specify either a full path or a file in the current working directory. syntax [sudo] dslc import <import_config_filename> example [root@hostname ~] [sudo] dslc logging_config.dat dslc set Configures the logging subsystem as specified: SNMPv2, SNMPv3, email, or syslog, or specifies an SMTP server. syntax [sudo] dslc set <subsystem> <parameter 1> <value 1> [<parameter 2> <value 2>] parameters subsystem parameter snmp trapcommunity SNMPv2 trap community string version Sets the polling version: 1 = SNMPv2; 3 = SNMPv3 37 Security Analytics Reference Guide Security Analytics 8.1 subsystem parameter snmpv2 snmpv3 email polling polling smtp_server sender syslog Set SNMPv2 authentication <rouser> Read-only user name <rocommunity> Read-only community Set SNMPv3 authentication <username> User name <auth_ protocol> Only SHA is permitted <auth_key> Password hash <privacy_ protocol> Only AES is permitted <privacy_key> Password hash Specify the SMTP server <server> Server IP port Server port; default is 25 Specify the sender information <email_ address> Email address for the From field <smarthost_ username> Username to access the SMTP server <smarthost_ password> Password for the SNMP username from_line_ override [yes | no] Yes = Use the From address specified in the UI, if it exists. usestarttls [yes | no] Yes = Use STARTTLS facility The syslog facility that is generating the message. Find supported values in "Syslog Facilities" on page 1. examples [root@hostname ~] [sudo] dslc set snmp trapcommunity h@km3n0t 38 Security Analytics Reference Guide Security Analytics 8.1 Set the SNMPv2 community string as h@km3n0t. [root@hostname ~] [sudo] dslc set snmp version 3 Set the polling version to SNMPv3. [root@hostname ~] [sudo] dslc set snmpv3 polling solEr@ SHA <hex_string> AES <hex_string> Set the SNMPv3 authentication username as solEr@ and specify the SHA and AES hex strings. [root@hostname ~] [sudo] dslc set email smtp_server 10.20.30.40 sender solera@company.com <smtp_username><smtp_password> usestarttls yes Specify an SMTP server with IP address 10.20.30.40 with server credentials so that it sets the sender address as solera@company.com and uses STARTTLS. [root@hostname ~] [sudo] dslc set syslog facility 2 Set syslog facility 2. dslc show Displays configuration information for the specified subsystem. The specified parameter determines the subsystem information that you want to see. syntax dslc show <parameter> parameters all Displays all logging configuration categories Displays category configuration such as system, user, playback, capture, deepsee, hardware email Displays email notification addresses, SMTP server information snmp Displays SNMP configuration syslog Displays syslog configuration example [root@hostname ~] dslc show category dslogdump Displays the events captured by the system log. The web interface equivalent for this command is on the Settings > Audit Log page. syntax dslogdump 39 Security Analytics Reference Guide Security Analytics 8.1 dsmigrate.sh Use the dsmigrate script to migrate capture data from a Security Analytics appliance to an 8.x appliance. This script can be used to transfer data from versions 7.x or 8.x to a Security Analytics 8.x appliance. n The dsmigrate script replaces dsmigratedata for Security Analytics 8.x and later. n In this procedure, remote refers to the old appliance (version 7.x or 8.x) or external device — the device from which data is migrated (source) — whereas local refers to the new 8.x appliance, or the appliance to which data is migrated (target). The dsmigrate script reads the data from the remote devide in slot order, earliest to latest, and transports it via SCP to the local appliance. On the local appliance the data is imported into the capture system as PCAPs, where indexing takes place in the same way as it does with conventional PCAP imports. If the local device has less disk space than the remote appliance, the data will be overwritten using the standard slot-recycling process. syntax dsmigrate.sh [options] [-7|-8] <remote server or local path> options -t Retain timestamps (default) -T Do not retain timestamps -p Remote SSH port (default: 22) -i<n> Use impt<n> as the import interface (default: 9) -7 Import from 7.x remote device -8 Import from 8.x remote device -h Show this help message -v Enable verbose mode -s Enable compression. Use this option when migrating over a slow link. -n Show how the script would run, but do not copy or import 40 Security Analytics Reference Guide Security Analytics 8.1 n You must specify either -7 or -8 as the remote version. n By default the timestamps from the remote appliance are retained. If you override using the -T option, the timestamps will be the import time. n To run dsmigrate.sh in the background use nohup. Setup 1. Build the local appliance by installing and licensing Security Analytics 8.x on it. 2. Disable capture on both appliances: [root@hostname ~]# dscapture --shutdown 3. On the local machine set up and enable any rules that you want to be triggered by the migrated data. Disable any rules that you do not want to be triggered. (Several rules are active by default.) 4. Connect the remote and local machines by one of the methods shown below: SSH over a LAN or WAN Local Mount over a direct Ethernet connection Local mount of an external device For the fastest migration speed directly connect the appliances. 41 Security Analytics Reference Guide Security Analytics 8.1 Migrate the Data Follow these steps to migrate PCAPs from one Security Analytics appliance or external device to an 8.x appliance. 1. Verify that sufficient space is available on the local appliance. n Run df -h on both appliances to compare /pfs allocation. The allocation size does not represent exactly how much drive space is in use but can help estimate the amount of space needed. n SSH Connection Only — Verify that SSH is enabled on the remote device by going to [Menu >] Settings > Security. Verify which port is specified. If you are specifying a port other than 22, you must pass the -p <port> attribute. n On the local appliance, from a shell with super-user privileges, run dsmigrate.sh. Specify -7 if the remote device has version 7.x data or -8 if the remote appliance is version 8.x. Specify an IP address for LAN/WAN connections or the full path with a leading slash [/] for a local mount: [root@localhostname ~]# dsmigrate.sh [-7|-8] [<remote_IP> | /<local_mount_ path>] Have you disabled capturing on <remote machine>? <YES/NO> YES n SSH Connection Only — The script's first action is to generate and copy an SSH key to the remote device. You may be required to provide the root password for the remote device. ... /usr/bin/ssh-copy-id: INFO: Source of key(s) to be installed: "/root/.ssh/migrate.pub" The authenticity of host <remote machine> can't be established. Are you sure you want to continue connecting? (yes/no)? yes ... <Message of the day for the remote machine> Password: <root password> n The dsmigrate script transfers data from the remote device via SCP to the local appliance one slot at a time. With verbose mode off, these messages indicate the progress for each imported chunk: <<< Generating list of slots to migrate ... >>> <MOTD> (SSH connection only) <<< Slots to transfer: <slots> >>> <<< Slot #1: <name> >>> -transferring<MOTD> -importing<<< Slot #2: <name> >>> n When importing from 7.x, name is <id><remote_hostname>. When importing from 8.x name is slot_<x>. n The list of slots to migrate from the remote device is in /tmp/migrate-slotlist of the local appliance. The list of slots that have already been migrated is in /tmp/migrated. If the migration is interrupted — with Ctrl+C, for example — and then restarted, the script skips the slots that are listed in /tmp/migrated. n When the migration is complete the message <n> slots successfully migrated is displayed and the files in /tmp are deleted. 42 Security Analytics Reference Guide n Security Analytics 8.1 Because the imported PCAPs are not shared, and because they are imported by root, the PCAPs are not visible on Capture > Import PCAP (there would be tens of thousands of entries), nor does the PCAP Import line on the Capture Summary Graph register the imports. If you had rules enabled during import, however, you can see the data by enabling Flows in Progress and Flows Initiated. 43 Security Analytics Reference Guide Security Analytics 8.1 dsmigratedata Use the dsmigratedata command to migrate capture and indexing data from one 7.x Security Analytics appliance to another 7.x appliance. The dsmigratedata command can be used only with Security Analytics 7.x and earlier. To migrate data to version 8.x and later use dsmigrate.sh. Symantec strongly recommends that this data-migration operation be performed only under the direction of Symantec Support or qualified professional services. syntax dsmigratedata -s [<source_IPv4> | [<source_IPv6>]] [options] Setup The dsmigratedata utility offers users the option of encrypted data migration using SSH or of unencrypted migration for cases where security is not an issue, for example, in the case of a direct connection or a secure network. In this procedure, source always refers to the old appliance, or the machine from which data is migrated (the source of the data), whereas target refers to the new appliance, or the machine to which data is migrated (the target of the migration). For the fastest migration speed, directly connect the appliances and remove encryption. Connection Type With Encryption (TB/day) Without Encryption (TB/day) 5.78 32.88 10 Gbps 44 Security Analytics Reference Guide Security Analytics 8.1 With Encryption (TB/day) Without Encryption (TB/day) 1 Gbps 3.67 7.68 LAN 5.44 8.56 Connection Type Interface Configuration To configure the machines for direct migration: 1. Build the target appliance by installing and licensing Security Analytics on it. 2. Disable capture on both appliances: [root@hostname ~]# dscapture --shutdown 3. Connect a cable between one of the interfaces on each of the source and target machines. A 10Gb connection will give the best performance, but a 1Gb copper connection is also acceptable. 4. As the super user on the source machine, assign a non-routable IP address to the Ethernet interface (direct connection) or an unused address on the management LAN. Enclose an IPv6 address in [square brackets] and omit the netmask argument. [root@sourcehostname ~]# ifconfig ethX 198.51.100.2 netmask 255.255.255.0 up where ethX is the migration interface. 5. Repeat the previous step on the target machine, as super-user on that machine, except with a different IP address on the same network: [root@targethostname ~]# ifconfig ethX 198.51.100.3 netmask 255.255.255.0 up 6. Test connectivity between the target and source appliances. To enable ping, run these two commands on the appliance to ping. [root@hostname ~]# sysctl net.ipv4.icmp_echo_ignore_all=0 [root@hostname ~]# sysctl net.ipv4.icmp_echo_ignore_broadcasts=0 Data-Migration Procedure Follow these steps to migrate data from one Security Analytics appliance to another. 1. Verify that sufficient space is available on the target appliance. n Run df -h on both appliances to compare /pfs allocation. The allocation size does not represent exactly how much drive space is in use but can help estimate the amount of space needed. n For simplicity, you can run dszap on the target, although this is not strictly required. n If there is not enough space, the utility returns a warning. If you choose to continue, existing or earlier-migrated data might be overwritten. 45 Security Analytics Reference Guide Security Analytics 8.1 2. Configure passwordless SSH for connections from the target to the source, first by generating a passwordless key on the target: [root@targethostname ~]# ssh-keygen -t rsa Press Enter when prompted for a password. [root@targethostname ~]# vi .ssh/id_rsa.pub Copy the public key. 3. Copy the key to the source: [root@sourcehostname ~]# vi .ssh/authorized_keys Paste the key to the file, then save and exit. 4. On the target, test SSH authentication: [root@targethostname ~]# ssh root@<source_IP> [-v] 5. From a shell with super-user privileges on the target, launch the dsmigratedata utility: [root@targethostname ~]# dsmigratedata -s <source_IP> [-w] where -w means "without encryption." This option removes all the cryptography related mechanisms such as SSH encryption/decryption. If -w is not specified, the script will transfer the data with encryption. Enclose an IPv6 address in [square brackets]. options -c --igraph Migrate capture summary graph data -d --debug Debug messages for developers -h --help Print help -i --interfaces CSV list of interface from which to read slots -n --no-retaintimestamp Migrate data without retaining the timestamps -p --port SSH port -r --restart Restart migration from the first file (stateless restart) -s --remote-server Remote server (source appliance) -v --verbose Enable verbose mode -w --withoutencryption Migrate data without encryption (Use only when there's no danger if data interception.) 46 Security Analytics Reference Guide Security Analytics 8.1 n By default, data is migrated from all of the physical interfaces that are present on the source. Use -i -interfaces to migrate only the data from specified interfaces. n By default, the timestamps from the source are retained. Override using the –n --no-retain-timestamp option. n The default SSH port is 22 for the source. If SSH is running on another port, use the -p --port option to specify the port on both appliances. If you change the default port, and SSH communication between the two appliances is blocked, you can disable the appliance firewall (systemctl stop iptables) or create a rule in the appliance firewall. n The verbose option prints more information on the console. It is advisable to run the script in nonverbose mode for better performance results. n To run dsmigratedata in the background use nohup. Operation of dsmigratedata 1. When the script is launched, it takes a snapshot of existing slots, then displays a message on the console: SLOTS TO MIGRATE: X 2. The script loops through each interface that has captured or imported data and migrates the data for that interface. As the slots are migrated, a message similar to the following is displayed: ************** TOTAL MIGRATED TIME ELAPSED : SLOTS REMAINED STATS ************************** DATA : 292.28 MB 00:01:25 IN CURRENT PASS : Y 3. If capture is still enabled on the source appliance, the script checks for any new slots that were added during migration and displays the message: TOTAL SLOTS TO MIGRATE: Z Symantec strongly recommends that capture be disabled on the source machine during the migration process. a. If Z is greater than zero, the script loops through the interfaces again and migrates the new data. b. If Z is zero but some interfaces on the source machine are still capturing data, the script will go into sleep mode and wake every 5 minutes to check for new slots. If new slots are discovered, the "total slots to migrate" message is displayed again and the data is migrated. 4. When there are no slots left to migrate, or when capture is disabled on the source machine, the following message is displayed: Data Migration Completed 47 Security Analytics Reference Guide Security Analytics 8.1 Restarting dsmigratedata The dsmigratedata utility can be restarted after system crash, user-abort, or termination due to abnormal situations. Stateful Restart To facilitate restart, the migration state is stored in the file /var/state/solera/dsmigratedata/<source_IP>. User Abort When you abort the data migration process manually (Ctrl+C), the -w option affects how data migration resumes: n -w option specified — When you press Ctrl+C, dsmigratedata saves the state and immediately exits. For example, if migration is at slot 1600 when you press Ctrl+C, migration resumes at slot 1601 upon restarting. n -w option not specified — When you press Ctrl+C, dsmigratedata exits migration only after importing the current block of 1024 slots. For example, if migration is at slot 1600 when you press Ctrl+C, migration does not terminate until after dsmigratedata has finished migrating slot 2048. Therefore, dsmigratedata resumes at slot 2049 upon restarting. Abnormal Termination Migration is restarted from the current 1024-block of slots that was being imported. For example, if migration is at slot 1624 when abnormal termination occurs, the last 600 slots are remigrated upon restarting. Stateless Restart To flush the state and restart from scratch, pass the -r --restart flag to the dsmigratedata utility. dspcapimport Imports PCAP and PCAPNG files to the system. Prior to running this command, upload the file to a location on the appliance or to an NFS share that you have mounted on the appliance. On the web interface, the import source for the PCAP will show as USB. For an NFS share, the Import Source column shows the name of the server as configured in Manage Connections. Find the equivalent function on the Menu web interface. > Capture > PCAP Import page of the syntax dspcapimport -f <pcap_file_path> [<parameters>] 48 Security Analytics Reference Guide Security Analytics 8.1 parameters -t 1 = Retain original timestamps; 0 = Use current time for timestamps -i Import interface name: impt0 through impt9; If no interface is specified, the first available interface will be used. If an interface is specified that is not available, an error is returned. -f PCAP filename and path; PCAP and PCAPNG formats are supported -s 1 = shared; 0 = not shared example [root@hostname ~] dspcapimport -f 2019-05-23.pcap -t 1 -s 1 Imports a PCAP file from the root directory, retains the original timestamps, and marks it as shared. dsportmapping Provides customized port-to-application mapping. syntax dsportmapping [list | add <application_name><port> ["<comment>"] | remove <application_name> | import <filepath>] parameters list add Show all customized port-to-application mappings Add a port-to-application mapping: <application_name> <port> <comment> Name of the application Integer between 0–65535 Optional. Add a comment remove Delete a port-to-application mapping. import Import a file that contains port-to-application mappings. Format the data as follows, with one mapping per row: <application_name> <port> <comment> There must be at least one line ending after the last entry. examples [root@hostname ~] dsportmapping add smtp 26 "Internal Mail" Maps SMTP to port 26 and adds the "Internal Mail" comment. [root@hostname ~] dsportmapping import port-mapping.txt Imports a user-created file called port-mapping.txt from the root directory. 49 Security Analytics Reference Guide Security Analytics 8.1 dsregen Takes captured network traffic and retransmits it from a virtual network interface to a physical network interface. This is referred to as "playback," which takes traffic being captured on one interface and replays it to another interface in real time. The web interface equivalent for much of this functionality is on the Menu > Capture > Summary page. Also see "Playback" in the Security Analytics 8.1.x Administration and Central Manager Guide on support.symantec.com. n For the system to play back traffic, you must map a virtual interface to a physical capture interface. (You cannot replay traffic to a physical network interface that is currently capturing network traffic.) n As part of the playback process, you can shape the network traffic to make it more appropriate to your particular application. For example, you can play back traffic at defined packet rates and filter traffic to meet particular criteria. n In addition to retransmitting packets, you can use dsregen to load-balance packet streams across multiple application instances so that you can balance the data stream across multiple devices to keep up with traffic load. n The virtual network interface must be assigned to the physical capture interface before running dsregen. syntax dsregen [--filter=<filename>] <function> [<virt if> <xmit if>] [<interval>] [<pid>] parameters start stop <virt if> The source virtual network interface from which you want to play back network traffic. <xmit if> The destination physical network interface where you want to play back network traffic. <virt if> The source virtual network interface where you want to stop playback. <xmit if> The destination physical network interface where you want to stop playback. <pid> Optional — Specifies the internal process ID (PID) that the system assigns to the playback session. Use the PID when there are multiple sessions using the same source and destination interfaces. Use dsregen show to see the PID. 50 Security Analytics Reference Guide Security Analytics 8.1 save Saves the filter on the virtual interface load Loads a saved playback session show Displays the status of all current playback sessions, including packets aborted due to errors. examples [root@hostname ~] dsregen start ifm0 eth3 Starts playback from virtual network interface ifm0 to eth3. This playback will not be visible on the UI because ifm0 has not been assigned to a physical interface, but Playback Start and Playback Stop will show up in the Audit Log. [root@hostname ~] dsregen --filter=filter.out start ifm0 eth3 Starts playback from virtual network interface ifm0 to eth3, after applying the filter in the binary output file filter.out. [root@hostname ~] dsregen stop ifm0 eth3 4278 Stops the playback session from virtual network interface ifm0 to eth3, which has the PID of 4278. [root@hostname ~] dsregen show Produces a readout similar to the following: [root@hostname ~] dsregen show eth3 snlog_wrapper: User admin called 'dsregen show eth3' ifm0 -> eth3 state: ACTIVE kpid:7253 bytes transmitted :0 packets transmitted :0 packets aborted :0 size errors :0 fault errors :0 retry errors :0 interface errors :0 packet tx retries :0 [root@hostname ~]_ dszap Deletes ALL data from the capture, indexing, and home drives (including saved reports, saved extractions, and capture filters) and reinitializes the datastore. Use this command to perform troubleshooting or free-up disk space. Once this command is executed, the deleted data cannot be recovered. 51 Security Analytics Reference Guide Security Analytics 8.1 syntax [sudo] dszap parameters -h help -v verbose -n noexec -f force -p partition -i ignore -q quick -R recursive Display help. Display all output. This parameter shows every deletion and can include 1000s of lines of output. Output the command without executing it. Proceed without the ZapALLData confirmation. Partition as well as reformat with mkfs.xfs. Omit this parameter to use dd to write 1MB of zeros at the front of the partition to wipe out the partition tables. Pass the ignore flag to scotus stop. Use reformatting to clear the indexing volume. Use rm to clear the the indexing volume (default). 52 Security Analytics Reference Guide Security Analytics 8.1 Actions Performed dszap performs the following actions: Delete Deactivate n Capture and indexing data n Rules n Capture summary graph n Data-enrichment settings n Capture filters n Alerts n Audit log n Saved reports n Authentication settings (LDAP, RADIUS) n Report status entries n CMC settings n Saved extractions n Communication settings (SNMP, syslog) n Extraction status entries n Data enrichment settings (deactivated) n PCAP imports n Date and time n PCAP watch folders n Geolocation settings n Report schedules n Indicators (deactivated live-feeds) n Retrospective jobs n Metadata settings n Customized summary views n Rules (deactivated) n Real-time extractions n Upgrade servers n Statistics n Users and groups n Login Correlation Service agent IPs n Web interface settings Retain Reset n PCAP imports queue n Retrospective jobs ID sequence n Capture interfaces Running dszap After entering dszap you are prompted to confirm the deletion of data: We are about to re-initialize all of your data storage. If this is what you want, please type "ZapALLData" to continue. Confirm by typing ZapALLData While running, this command displays information about the status of the command. 53 Security Analytics Reference Guide Security Analytics 8.1 The dszap process may appear to hang while deleting /home/extractor-live files. If the system has been performing real-time extractions for data-enrichment rules, this process may take an extended amount of time. For the changes to take effect, you must reboot the system after you run this command. You can do this in the UI by selecting Menu > Settings > System > Reboot or by typing reboot on the command line. After you reboot, you will need to re-activate your rules, live-feed indicators, and data-enrichment providers. 54 Security Analytics Reference Guide Security Analytics 8.1 dump_slot Use these commands to view information regarding the slots. n create time — When the system was first installed n update time — Last time data was written n start — First time the slot was written n end — Last time the slot was written dump_slot_chain Information on all interfaces that are capturing. create time: 2019-09-06 17:45:05.534399043 update time: 2019-10-01 15:42:08.135132956 max num files: 42430, slot size: 67108864 total slots: 42432, next slot: 769092, first slot: 726660 total packets: 68914512, total bytes: 39169728525, dropped packets: 0 eth4 (if_index 5): start: 2018-09-30 06:48:33.452971699, end: 2018-10-01 15:42:03.439005038 slot count: 42432, start slot: 726660, end slot: 769091 total packets: 5015086661, total bytes: 2565913192911, dropped packets: 18446462597417917505 dump_slot_header slot_<number> While in /pfs/create/<tab> run this command to get information about the slot header. [root@<hostname> 4C4C4544-0039-4310-8052-B8C04F444232]# dump_slot_header slot_1650747 ****** Slot Header 1650747 ******** iface_id = 6 next_slot = 1650748 slot seq = 1650747 pkts = 95120 bytes = 61781692 dropped_pkts = 0 start_time = 2019-10-02 12:34:41.093743799 end_time = 2019-10-02 12:34:41.207753823 filled = yes, mapped = yes empty = no, init = no mapped_header = no, capturing = no in_regen = no, posted = no in_io = no, recycled = no dump_slot_elements <filename> While in /pfs/create/<tab> run this command to get a list of the packets in the slot. 55 Security Analytics Reference Guide Security Analytics 8.1 [root@<hostname> 4C4C4544-0039-4310-8052-B8C04F444232]# dump_slot_elements slot_1650747 [90832]:flowid=1297604353,offset=46844338,size=114,time=2019-10-01 15:42:08.360844905 [90833]:flowid=1297604353,offset=46844468,size=130,time=2019-10-01 15:42:08.360847742 [90834]:flowid=1297760584,offset=46844534,size=66,time=2019-10-01 15:42:08.360850458 [90835]:flowid=1297766315,offset=46845976,size=1442,time=2019-10-01 15:42:08.360860002 [90836]:flowid=1297410786,offset=46847055,size=1079,time=2019-10-01 15:42:08.360863747 [90837]:flowid=1297250519,offset=46847169,size=114,time=2019-10-01 15:42:08.360867040 [90838]:flowid=1297764691,offset=46848611,size=1442,time=2019-10-01 15:42:08.360869830 [90839]:flowid=1297675483,offset=46848677,size=66,time=2019-10-01 15:42:08.360887154 [90840]:flowid=1297614305,offset=46848743,size=66,time=2019-10-01 15:42:08.360890019 [90841]:flowid=1297767014,offset=46848913,size=170,time=2019-10-01 15:42:08.360911668 [90842]:flowid=1297766218,offset=46850355,size=1442,time=2019-10-01 15:42:08.360923159 [90843]:flowid=1297764237,offset=46851797,size=1442,time=2019-10-01 15:42:08.360944055 dump_slot_pcap <packet_number> While in /pfs/create/<tab> run this command to create a PCAP of one of the packets and write it to /tmp. [root@<hostname> 4C4C4544-0039-4310-8052-B8C04F444232]# dump_slot_pcap 1650747 -d /tmp dump_slot_trail Run this command to see the context for the current slot chain. hostname: 223-dicentra, UUID: 4C4C4544-004E-3110-8033-B9C04F335731, version: 10 create time: 2019-09-06 17:45:05.534399043 update time: 2019-10-01 15:44:26.140642053 max num files: 42430, slot size: 67108864 total slots: 42432, next slot: 769141, first slot: 726709 total packets: 68914512, total bytes: 39169728525, dropped packets: 0 eth4 (if_index 5): first packet seen: yes, imported last slot: no slot trail: (* for last inserted), total inserted: 96864 [0]: slot 769138, generation 19373 [1]: slot 769139, generation 19373 [2]: slot 769140, generation 19373 [3]: slot 769141, generation 19373* [4]: slot 769137, generation 19372 indexer info: [0]: slots indexed 96864, state 6 [1]: slots indexed 96864, state 6 last slot processed:769141, last sequence processed:1277 dump_space_table_entry <slot_id> Run this command for a summary of slot information. Slot 1650747 start Mon Oct 1 15:45:42 2018 (1538430342) end Mon Oct 1 15:45:44 2018 (1538430344) iface 5 flags 2 56 Security Analytics Reference Guide Security Analytics 8.1 walk_space_table_journal Run this command to see a list of slots with start and end dates. Slot 84571 start iface 5 flags 2 Slot 84572 start iface 5 flags 2 Slot 84573 start iface 5 flags 2 Slot 84574 start iface 5 flags 2 Slot 84575 start iface 5 flags 2 Slot 84576 start iface 5 flags 2 Slot 84577 start iface 5 flags 2 Slot 84578 start iface 5 flags 2 Slot 84579 start iface 5 flags 2 Slot 84580 start iface 5 flags 2 Slot 84581 start iface 5 flags 2 Sat Sep 8 12:37:39 2018 (1536431859) end Sat Sep 8 12:37:41 2018 (1536431861) Sat Sep 8 12:37:41 2018 (1536431861) end Sat Sep 8 12:37:43 2018 (1536431863) Sat Sep 8 12:37:43 2018 (1536431863) end Sat Sep 8 12:37:45 2018 (1536431865) Sat Sep 8 12:37:45 2018 (1536431865) end Sat Sep 8 12:37:48 2018 (1536431868) Sat Sep 8 12:37:48 2018 (1536431868) end Sat Sep 8 12:37:49 2018 (1536431869) Sat Sep 8 12:37:49 2018 (1536431869) end Sat Sep 8 12:37:51 2018 (1536431871) Sat Sep 8 12:37:51 2018 (1536431871) end Sat Sep 8 12:37:53 2018 (1536431873) Sat Sep 8 12:37:53 2018 (1536431873) end Sat Sep 8 12:37:55 2018 (1536431875) Sat Sep 8 12:37:55 2018 (1536431875) end Sat Sep 8 12:37:57 2018 (1536431877) Sat Sep 8 12:37:57 2018 (1536431877) end Sat Sep 8 12:37:58 2018 (1536431878) Sat Sep 8 12:37:58 2018 (1536431878) end Sat Sep 8 12:38:00 2018 (1536431880) dynfilter View and manage the dynamic filters. Set up dynamic filter rules on the Menu > Analyze > Rules page. syntax dynfilter --list [<options>] dynfilter --kill --interface=<interface><hash> options -i --interface=ARG Specify interface name (required for --kill); use all for all interfaces -c --config=ARG Use the config file specified by ARG -d --debug Turn debug logging on -h --help Display the usage and help info -n --noexec Do not actually extract, but clear queues in a dry-run manner 57 Security Analytics Reference Guide Security Analytics 8.1 -v --verbose Log additional processing information -V --version Show version information and exit usage List active filters (defaults to all interfaces). Filters are sorted by interface (ascending) and then by the soonest to expire (ascending). [root@hostname ~] dynfilter -l IFNAME SECS RULE UUID eth2 15 561c33b4-ebb8-4cf3-ac6c-1d180a83290b host 203.0.113.112) or (src host 203.0.113.112)))' eth2 80 561c33b4-ebb8-4cf3-ac6c-1d180a83290b host 198.51.100.11) or (src host 198.51.100.11)))' eth2 140 561c33b4-ebb8-4cf3-ac6c-1d180a83290b host 192.0.2.5) or (src host 192.0.2.5)))' HASH 180047451a0357e6 BPF FILTER STRING '(ip and tcp and ((dst a15bdcfd7e9f826c '(ip and tcp and ((dst 882f0612f001f218 '(ip and tcp and ((dst columns n IFNAME — Name of the interface where the filter is applied. Filters are applied only on interfaces where traffic is detected. n SECS — Seconds remaining before the filter expires and is removed. n RULE UUID — UUID for the rule that specified the filter. n HASH — Used only by this tool to specify a filter string, to be used with the kill command. n BPF FILTER STRING — The filter string that is applied to the interface after a NOT, such that (ip and tcp and ((dst host X) or (src host Y)) blocks hosts X and Y that are using TCP/IP. remove a filter To remove a filter, use --kill <hash> --interface <interface> [root@hostname ~] dynfilter -k 882f0612f001f218 -i eth2 eth2 140 561c33b4-ebb8-4cf3-ac6c-1d180a83290b 882f0612f001f218 host 203.0.113.5) or (src host 203.0.133.5)))' '(ip and tcp and ((dst The filter that has been removed is displayed. To remove all filters from all interfaces for a given rule, go to Menu Rules on the web UI and disable then enable lsi-rate-tool View and alter the initialization rate for adapters on the appliance. 58 the rule. > Analyze > Security Analytics Reference Guide Security Analytics 8.1 syntax lsi-rate-tool [<parameter1> <parameter2> --] [<action> <rate>] parameters -h, --host IP address of appliance -P, --port Port ID of port for login -u, --user UserID of login (default = root) -p, --passwd -r, --retries -a, --all -c, --category Password associated with userID Maximum number of login retries: default=3 Apply rate to all adapters including system RAID adapters Category (default is all categories) CCRate ReconRate RebuildRate BGIRate -v, --verbose The rate at which the consistency checks are performed on the RAID sets. The rate at which a damaged virtual drive may be reconstructed. The rate at which a damaged or missing physical disk can be rebuilt. The background initialization rate, which is the rate at which RAIDinitialization operations occur. Display script actions as they run -n, --noExec Show script actions but do not execute them -S, --stderr Redirect standard error messages to /dev/nu... -D, --debug Enable debugging output -H, --help Display help screen -- End of parameters <action> Specify the action: set reset show <rate> 10 = 10%, 90 = 90% Resets the default for the category (default); Displays the current setting Specify the rate in Mbps (0–100); valid only with set action 59 Security Analytics Reference Guide Security Analytics 8.1 examples [root@hostname ~] lsi-rate-tool Shows the local appliance initialization rates and enables all parameters. [root@hostname ~] lsi-rate-tool -h 192.0.2.109 Shows the initialization rates for the specified appliance. [root@hostname ~] lsi-rate-tool -c CCRate set 90 Dedicates 90% of the adapter's cycles to consistency checks. [root@hostname ~] lsi-rate-tool reset Sets the initialization rate to the default. [root@hostname ~] lsi-rate-tool -c ReconRate Displays the virtual disk reconstruction rate for each installed LSI-based adapter: Adapter 0: Reconstruction Rate = 30% Adapter 1: Reconstruction Rate = 30% Adapter 3: Reconstruction Rate = 30% lsi-show View configuration and setup information associated with RAID controllers. syntax lsi-show [<parameter1> <parameter2> --] parameters -h, --host IP address of appliance -P, --port Port ID of port for login -u, --user User ID of login (default = root) -p, --passwd Password associated with userID -r, --retries Maximum number of login retries: default=3 -s, --summary Do not show physical device lists -v, --verbose Display script actions as they run -n, --noExec Show script actions, but do not execute them -S, --stderr Redirect standard error messages to /dev/null -D, --debug Enable debugging output 60 Security Analytics Reference Guide -H, --help -- Security Analytics 8.1 Display the help screen End of parameters examples [root@hostname ~] lsi-show Shows the local RAID controller values. [root@hostname ~] lsi-show -h 192.0.2.109 Shows the RAID controller values for the specified appliance. MegaCli | megacli SAS RAID management tool for Dell hardware. Only a few of the commands are displayed here. syntax [[MegaCli | megacli] [command]] [-Silent] [-AppLogFile filename] [-NoLog] [-page[N]] [root@hostname ~] megacli -encinfo -aall Shows the status of the JBOD enclosures. [root@hostname ~] megacli -AdpAllInfo -aAll Shows the adapter info. [root@hostname ~] MegaCli -CfgDsply -aALL Shows all drive and adapter info. [root@hostname ~] MegaCli -AdpEventLog -GetEvents -f events.log -aALL && cat events.log Shows the log/historical info. [root@hostname ~] megacli -pdlocate [-start|-stop] -physdrv[E:S] -aX Finds a sensor or drive by lighting up the drive-locator LED, where n E — enclosure ID n S —slot number n aX — adapter number example [root@hostname ~] megacli -pdlocate -start -physdrv[25:2] -a2 Finds enclosure 25, slot 2 on controller/adapter 2. Use lsi-show to see the enclosure:slot numbers and adapter/controller ID. 61 Security Analytics Reference Guide Security Analytics 8.1 scm pivot_only_provider Adds a pivot-only reputation provider, which opens the web page of the specified reputation provider with the selected value as the search term. Reputation providers that are added using this method are listed on Settings > Data Enrichment under Third Party On-Demand Reputation Providers and are available in the View Reputation Information menus on the Analyze > Summary, Reports, Extractions, and Geolocation pages. Add pivot-only providersfrom the web UI on Menu Enrichment > Third-Party Integration Providers. > Settings > Data After you have finished adding one or more providers, you must restart the web server using the command systemctl restart httpd Add a Pivot-Only Provider syntax scm pivot_only_provider [insert | refreshData] -v "<provider_name>" <provider_category><pivot_url> parameters provider_name Display name of the reputation provider. Do not use special characters. 62 Security Analytics Reference Guide provider_ category Category of the provider: hash Search on the MD5 hash. Supported only in artifact entries. To invoke the provider in reports and report widgets specify any. sha1 Search on the SHA1 hash. Supported only in artifact entries. To invoke the provider in reports and report widgets specify any. sha256 fuzzy url ip host any pivot_url Security Analytics 8.1 Search on the SHA256 hash. Supported only in artifact entries. To invoke the provider in reports and report widgets specify any. Search on the fuzzy hash. Supported only in artifact entries. To invoke the provider in reports and report widgets specify any. Search on the URL Search on the IP address; enclose an IPv6 address in [square brackets] Search on the hostname Search on any value Pivot URL. Syntax is http://<url>%{TOKEN} or https://<url>%{TOKEN} The %{TOKEN} string will be automatically replaced by the value to search. If the %{TOKEN} string cannot be at the end of the URL, enclose the entire URL in double quotation marks: "http://<url>"%{TOKEN}"<string>" examples [root@hostname ~] scm pivot_only_provider insert -v "CysconSIRT" host http://www.csirt.org/lang/en-us/incidents-on-domain?domain=%{TOKEN} Adds the CysconSIRT reputation provider and specifies that the value to search is hostname. [root@hostname ~] scm pivot_only_provider insert -v "MX Toolbox1" any "http://mxtoolbox.com/SuperTool.aspx?action=blacklist%3a"%{TOKEN}"&run=toolpage" Adds the MX Toolbox1 reputation provider with a URL that requires characters after %{TOKEN}. [root@hostname ~] scm pivot_only_provider refreshData Refreshes the reputation providers data column. Pivot-Only Provider Demonstration For this demonstration, four pivot-only providers will added — one of each type — to show how the providers are available in the web UI. Add the Pivot-Only Providers Log in to the command-line interface as root and enter the following commands: 63 Security Analytics Reference Guide Security Analytics 8.1 scm pivot_only_provider insert -v "Malc0de Hash" hash http://malc0de.com/database/index.php?search=%{TOKEN} scm pivot_only_provider insert -v "hpHosts IP" ip http://hosts-file.net/default.asp?s=% {TOKEN} scm pivot_only_provider insert -v "DShield Domain" host http://www.dshield.org/ipinfo.html?ip=%{TOKEN} scm pivot_only_provider insert -v "McAfee SiteAdvisor" any http://www.siteadvisor.com/sites/%{TOKEN} systemctl restart httpd View the New Providers in the UI 1. In the UI, select Menu Reputation Providers. > Settings > Data Enrichment and scroll to Third-Party On-Demand The new pivot-only providers are displayed in alphabetical order. You can activate or deactivate them on this page, as desired. 2. Select Menu > Analyze > Summary to view captured or PCAP data. Select the IP Layer View. 3. Click a value in an IPv4 widget and select View Reputation Information. 64 Security Analytics Reference Guide Security Analytics 8.1 4. The hpHosts IP provider is available because it is an IP-type provider, and Mnemonic pDNS Host is available because it is an any-type provider. Click either provider to launch the provider's page in a new tab with the selected IP address as the query value. 5. Click the Reports tab and select the Web: HTTP Server report. Click an entry in the results list and select View Reputation Information. 65 Security Analytics Reference Guide Security Analytics 8.1 6. All of the host-type providers are displayed, including the new DShield Domain and Mnemonic pDNS Host providers. 7. Click the Extractions tab. When the extraction has finished, expand an entry, click the MD5 hash, and select View Reputation Information. 8. The Malc0de Hash and Mnemonic pDNS Host providers are available. Hash-type providers are not available for the File: MD5 Hash report or report widget. Delete a Pivot-Only Provider You cannot edit an existing pivot-only provider; you must delete and then re-add the provider. syntax su postgres psql -d dsweb select * from integration_providers; DELETE FROM integration_providers WHERE name = '<provider_name>'; You may omit the line select * from integration_providers; if you already know the provider name. Sample Pivot-Only Providers This list is not maintained by Symantec; it is the responsibility of the user to verify that the URLs are valid. "BFK Passive DNS Hosts" host http://www.bfk.de/bfk_dnslogger_en.html?query=%{TOKEN} "BFK Passive DNS IP" ip http://www.bfk.de/bfk_dnslogger_en.html?query=%{TOKEN} 66 Security Analytics Reference Guide Security Analytics 8.1 "Builtwith Domain Relationships" host https://builtwith.com/relationships/%{TOKEN} "CentralOps Whois Host" host 'https://centralops.net/co/DomainDossier.aspx?&dom_whois=true&dom_ dns=true&net_whois=true&addr='%{TOKEN} "CentralOps Whois IP" ip 'https://centralops.net/co/DomainDossier.aspx?&dom_whois=true&dom_ dns=true&net_whois=true&addr='%{TOKEN} "Domain Tools Host" host https://whois.domaintools.com/%{TOKEN} "Domain Tools IP" ip https://whois.domaintools.com/%{TOKEN} "DShield Domain" host https://secure.dshield.org/ipinfo.html?ip=%{TOKEN} "DShield IP" ip https://secure.dshield.org/ipinfo.html?ip=%{TOKEN} "hpHosts Domain" host https://hosts-file.net/?s=%{TOKEN} "hpHosts IP" ip https://hosts-file.net/?s=%{TOKEN} "hpHosts URL" url https://hosts-file.net/?s=%{TOKEN} "IP Void" ip http://www.ipvoid.com/scan/%{TOKEN} "Is It Hacked Domain" host http://www.isithacked.com/check/%{TOKEN} "Is It Hacked URL" url http://www.isithacked.com/check/%{TOKEN} "Malc0de "Malc0de "Malc0de "Malc0de Domain" host http://malc0de.com/database/index.php?search=%{TOKEN} Hash" hash http://malc0de.com/database/index.php?search=%{TOKEN} IP" ip http://malc0de.com/database/index.php?search=%{TOKEN} URL" url http://malc0de.com/database/index.php?search=%{TOKEN} "Malware Domain List Host" host 'http://www.malwaredomainlist.com/mdl.php?&colsearch=All&quantity=50&search='%{TOKEN} "Malware Domain List IP" ip 'http://www.malwaredomainlist.com/mdl.php?&colsearch=All&quantity=50&search='%{TOKEN} "MalwareZoo Hash" hash https://zoo.mlw.re/samples/%{TOKEN} "McAfee TI Host" host https://www.mcafee.com/threat-intelligence/domain/default.aspx?domain=% {TOKEN} "McAfee TI IP" ip https://www.mcafee.com/threat-intelligence/ip/default.aspx?ip=%{TOKEN} "McAfee TI URL" url https://www.mcafee.com/threat-intelligence/site/default.aspx?url=%{TOKEN} "Mnemonic pDNS Host" host https://passivedns.mnemonic.no/search/%{TOKEN} "MXToolbox Blacklist Domain" host https://mxtoolbox.com/SuperTool.aspx?\&run=toolpage\&action=blacklist:%{TOKEN} "MXToolbox Blacklist IP" ip https://mxtoolbox.com/SuperTool.aspx?\&run=toolpage\&action=blacklist:%{TOKEN} "RIPE IP" ip https://stat.ripe.net/%{TOKEN} "SpamHaus domain" host https://www.spamhaus.org/query/domain/%{TOKEN} "SpamHaus IP" ip https://www.spamhaus.org/query/ip/%{TOKEN} "StopForumSpam IP" ip http://www.stopforumspam.com/ipcheck/%{TOKEN} "Talos Intelligence Domain" host https://www.talosintelligence.com/reputation_ center/lookup?search=%{TOKEN} "Talos Intelligence IP" ip https://www.talosintelligence.com/reputation_center/lookup?search=% {TOKEN} "Threat Crowd Domain" host https://www.threatcrowd.org/domain.php?domain=%{TOKEN} "Threat Crowd Hash" hash https://www.threatcrowd.org/malware.php?md5=%{TOKEN} "Threat Crowd IP" ip https://www.threatcrowd.org/ip.php?ip=%{TOKEN} "ThreatExpert Hash" hash http://www.threatexpert.com/reports.aspx?find\=%{TOKEN} 67 Security Analytics Reference Guide Security Analytics 8.1 "ThreatStream Anomali IP" ip https://ui.threatstream.com/search?status=active&value__re=.*% {TOKEN} "TotalHash "TotalHash "TotalHash "TotalHash Hash" hash https://totalhash.cymru.com/search/?hash:%{TOKEN} Host" host https://totalhash.cymru.com/search/?dnsrr:%{TOKEN} IP" ip https://totalhash.cymru.com/search/?ip:%{TOKEN} URL" hash https://totalhash.cymru.com/search/?url:%{TOKEN} "Twitter Search Term Domain" host 'https://twitter.com/search?f=realtime&q='%{TOKEN} "Twitter Search Term IP" ip 'https://twitter.com/search?f=realtime&q='%{TOKEN} "Twitter Search Term URL" url 'https://twitter.com/search?f=realtime&q='%{TOKEN} "Unmask Parasites" url http://www.UnmaskParasites.com/security-report/?page=%{TOKEN} "URL "URL "URL "URL "URL Query Domain" host http://urlquery.net/search?q=%{TOKEN} Query IP" ip http://urlquery.net/search?q=%{TOKEN} Query URL" url http://urlquery.net/search?q=%{TOKEN} Void Domain" host http://www.urlvoid.com/scan/%{TOKEN} Void IP" ip http://www.urlvoid.com/ip/%{TOKEN} "URLFind URL" url http://urlfind.org/?site=%{TOKEN} "WatchGuard Domain" host http://www.reputationauthority.org/domain_lookup.php?ip=%{TOKEN} "WatchGuard IP" ip http://www.reputationauthority.org/lookup.php?ip=%{TOKEN} "Zeus "Zeus "Zeus "Zeus Tracker Tracker Tracker Tracker Domain" host https://zeustracker.abuse.ch/monitor.php?host=%{TOKEN} Hash" hash 'https://zeustracker.abuse.ch/monitor.php?show=config&hash='%{TOKEN} IP" ip https://zeustracker.abuse.ch/monitor.php?ipaddress=%{TOKEN} URL" url https://zeustracker.abuse.ch/monitor.php?host=%{TOKEN} scm sessions Use the scm sessions command to manage user sessions with respect to the session length and expiration. To manage user authentication use scm tally. syntax scm sessions <subcommand> [-h] [-v] [-q] <user> subcommands summary Shows the status of a user session such as expiration times and time remaining on the session. Valid values for <user>: <id> <username> <null> clear Specify the user's ID. Specify the username. Omit <user> to see all sessions. Clears the user's session from the session DB. This action will log out the user. Valid values for <user>: <id> <username> Specify the user's ID. Specify the username. 68 Security Analytics Reference Guide Security Analytics 8.1 examples [root@hostname ~] scm sessions summary Displays all of the users in the session DB. A "No user" entry indicates one or more unsuccessful login attempts. [root@hostname ~] scm sessions summary 35 Displays session information for user ID 35. [root@hostname ~] scm sessions clear web_user Clears all web_user sessions from the session DB and logs web_user out. scm solera_acl elevate Restores or converts an existing user account on the web UI to admin status. syntax scm solera_acl elevate <username> Places the user in a new group with administrator privileges called elevated-admin-<YYYY-MM-DD>T<hh:ii:ss>. Log on with this account using its original password, and then you can edit the account and the group in Menu > Settings > Users and Groups to restore the original permissions. scm tally Enables user accounts, clears user API keys. To manage user sessions use scm sessions. Find the equivalent settings on the Menu > Settings > Users and Groups and Settings > Security pages of the web interface. syntax scm tally <subcommand> [-h] [-v] [-q] <username> 69 Security Analytics Reference Guide Security Analytics 8.1 subcommands status Shows the status of the user account as follows: User ID ID number of the user account User Full context of username Attempts Current number of unsuccessful authentication attempts Auth Limit User-defined* login-attempt limit Lockout Interval User-defined* lockout interval Session Limit User-defined* session limit Session Count Number of concurrent sessions for this user Lockout Expires Number of seconds before the current lockout expires clear_ auths Clears the number of unsuccessful login attempts clear_keys Zeroizes the user's API key * Defined on the Menu > Settings > Security page of the web interface. examples [root@hostname ~] scm tally clear_auths admin Clears the number of unsuccessful login attempts for the admin account, which then enables the account if it has been locked out. [root@hostname ~] scm tally clear_keys admin Zeroizes the API key for the admin account. To generate a new key for admin, open the web interface and select [Account Name] > Account Settings and click Reset API Key. 70 Security Analytics Reference Guide Security Analytics 8.1 Web Services APIs Symantec Security Analytics provides a robust set of web APIs: n "API Changes in Security Analytics 8.1.x" on page 75 n "Using the APIs" on page 424 — Detailed examples of how to implement the APIs Install and Test the SoleraConnector Class 71 Session-Based APIs 73 Pivot to Summary Page 73 Single Time-Value Configuration 74 If you are running an API on a CMC and need the API to affect one or more connected sensors, you must specify at least one sensor ID, using the appliances attribute in the URL: /favorites/active?appliances=1 /deepsee_reports/report?appliances=1,4,7 If the API has an additional applianceIds or appliances attribute, you must use that attribute to specify which sensors are to be affected by the API and you must specify at least one sensor in the URL. The sensor specified in the URL does not need to be the same as the sensor(s) that are specified in the API's applianceIds/appliances attribute. s.callAPI( "POST", "/favorites/delete?appliances=1", { 'selectedIds': [<uuid1>, <uuid2>] 'applianceIds': [5,6,9] }) Install and Test the SoleraConnector Class To test the Web APIs, obtain the connector class and command-line test files from the online help files, which are available as follows: n On the Security Analytics web interface, select Menu > Settings > Help, and select your language under Online Help Files. In the left pane select Reference > Web APIs. n On the Security Analytics documentation page (support.symantec.com/us/en/documentation.1145515.html) select Administration Guide for Document Type and then select the latest Security Analytics WebGuide. 71 Security Analytics Reference Guide Security Analytics 8.1 1. In the left-side menu of the help files, select Reference > Web APIs. Under Install and Test the SoleraConnector Class, download either the PHP or Python files, as desired. 2. Open the PHP or Python links, save the file to your workstation, and remove the TXT extension: n SoleraConnector.php n SoleraConnector.py n commandLineTest.php n commandLineTest.py 3. Verify that the files are on a device that supports PHP 5.3 or Python 2 or 3. n PHP requires php-curl to be installed. n Python requires python-requests to be installed. n Clients must be running OpenSSL 1.0.1 or later for the Python scripts. Some versions of Mac OS X run a non-supported version of OpenSSL and must be updated: o To see which version of OpenSSL is on your client, run python -c "import ssl;print(ssl.OPENSSL_VERSION)" o To update Python and OpenSSL on OS X, run brew update brew install openssl brew install python --with-brewed-openssl 4. Open commandLineTest and edit the top line as follows: SoleraConnector("admin_account","API_key", "IP_address"); where: o admin_account is an administrative-level account name. o API_key is the API key generated on the web interface under [Account Name Account Settings. o IP_address is the IP address of bond0. Enclose an IPv6 address in [ square brackets ]. ]> 5. On the next line, input the parameters of the API: PHP var_dump($connector->callAPI('method', 'API_path', [array('parameter' => 'value')])); Python print(s.callAPI("method", "API_path", {"parameter": "value"})) where: o method is GET or POST o API_path is the API path o parameter and value are an array of parameters and their values, if any 72 Security Analytics Reference Guide Security Analytics 8.1 6. Save the file. 7. Run the test file: PHP php commandLineTest.php Python python CommandLineTest.py API Example The following examples demonstrate how to use the download artifacts API . PHP var_dump($connector->callAPI('GET','/artifacts/download', array('ids' => '5', 'type' => 'wav', 'mode' => 'synth_audio'))); Python print(s.callAPI("GET","/artifacts/download", {'ids':'5', 'type':'wav', 'mode':'synth_audio'})) Session-Based APIs To reduce API latency, you can configure API authentication to be session-based. 1. Edit the /gui/dsweb/Config/core.php file. Scroll down to this section: Configure::write('pbkdf2', array( 'saltLength' => 128, //length of the cipher key in bits 'minIterations' => 100000, //minimum is 1 'minMilliseconds' => 200 )); 2. Change minMilliseconds to minIterations and then save and exit. 3. Reset the API user’s token by logging in to the web UI as the API user and then selecting [Account Name] > Account Settings and clicking Reset API Key . Pivot to Summary Page To call up the Menu > Analyze > Summary view from another program, use the pivot URL: https://<appliance>/deepsee_reports#pathString=/timespan/<timespan>[/<attribute>/<value>] Where <attribute> is one of the following: ipv4_address ipv6_address ipv4_initiator ipv6_initiator ipv4_responder ipv6_responder tcp_responder tcp_initiator For every host that pivots into the Summary page, add the host to the Allowed Referrers list on Settings > Web Interface. 73 Security Analytics Reference Guide Security Analytics 8.1 Single Time-Value Configuration If desired, you can set <timespan> to a single time-value. Use the time prefix and suffix to automatically set a timespan relative to that single time-value. 1. On the web interface, select [Account Name] > Preferences. 2. For Time Prefix, specify the number of seconds that will be subtracted from the single time-value to calculate the start time. 3. For Time Suffix, specify the number of seconds that will be added to the single time-value to calculate the end time. 4. Click Save. The time prefix and suffix are supported by any API request that accepts a path string: PCAP downloads, pivot to summary page, reports, and extractions. example n Time Prefix = 900 n Time Suffix = 900 https://<appliance>/deepsee_reports#pathString=/timespan/2019-05-22T13:00:00/ipv4_ address/198.51.100.88 This command displays the Menu > Analyze > Summary page with the timespan set for May 22, 2019 from 12:45–1:15 p.m. and with ipv4_address=198.51.100.88 in the primary filter bar. 74 Security Analytics Reference Guide Security Analytics 8.1 API Changes in Security Analytics 8.1.x The Using the APIs page contains detailed instructions for using APIs in sequence to download various data types from the appliance. n Outputs have been added to the GET "Capture APIs" on page 116. New APIs The APIs in this list represent new features in Security Analytics 8.1.x. n GET: /settings/icdx_<x> New Metadata APIs page n GET: /captures/get_billable n POST: /deepsee/delete_map n POST: /deepsee/save_map n GET: /job_queue/job_queue n GET: /job_queue/count n GET: /job_queue/download n GET: /job_queue/filter_options n POST: /job_queue/delete n GET: /settings/cmc_first n GET: /settings/extractor_enable_proxy_data_reconstruction n POST: /settings/extractor_enable_proxy_data_reconstruction n GET: /web_interface/allowed_hosts n POST: /web_interface/allowed_hosts The APIs in this list are newly available: n GET: /shyft/field_data Modified APIs The APIs in this list have been modified in Security Analytics 8.1.x. n GET: /artifacts/artifacts — Reconfigured the state machine. See Extractions API Changes to see how the output has been affected. n POST: /artifacts/save — Was POST: /artifacts/background. 75 Security Analytics Reference Guide Security Analytics 8.1 n POST: /actions/save — Added the discard packets value for type and ICDx and Splunk Phantom offbox values n POST: /cmc_settings/add_appliance — Added mssfix (MTU) attribute n POST: /cmc_settings/cmc_client_toggle — This API has been removed n POST: /cmc_settings/edit_appliance — Added mssfix (MTU) attribute n POST: /deepsee/save_view — Removed the type parameter; to save geolocation map views use POST: /deepsee/save_map n GET: /integration_providers/providers — Added the threatexplorer value for edit_type n POST: /settings/logging_settings — Added parameters for the ICDx remote-notification and Splunk Phantom servers as well as SNMP entries for an additional read-only username and encryption and privacy passwords. n POST: /users/setting — Added the dark parameter n POST: /integration_providers/yara_restore — Was GET. 76 Security Analytics Reference Guide Security Analytics 8.1 Advanced API Queries Use advanced queries to create nested primary filters that combine Boolean AND and OR functions with multiple attributes. These advanced queries for the primary filter are now available in the web UI. The Advanced Filters on the Menu > Analyze > Summary > [Reports | Extractions | Geolocation] pages already support nested queries. To create an advanced query, prepend all or any to an array that contains the arguments: n all = Boolean AND — All items in the array must match. n any = Boolean OR — At least one of the items in the array must match. There is no limit to the number of nested arrays in a single advanced query. Example Queries The following examples represent the same logic: Boolean (application_id=http AND (mime_type~css OR filename~css)) Python { 'all':[ 'application_id=http', 'any':[ 'mime_type~css', 'filename~css' ] ] } PHP array( 'all' => array( 'application_id=http', 'any' => array( 'mime_type~css', 'filename~css' ) ) ) Combining Different Namespaces Each of the attributes occupies one of the following namespaces: flows, groups, packets, verdicts. Attributes that are in different namespaces cannot be combined in the same advanced query. However, separate queries 77 Security Analytics Reference Guide Security Analytics 8.1 can be created for each namespace and then combined into a single array. The operator between each namespace query is always AND. Consult the Metadata Settings tables to see the namespace for each attribute. The following example contains attributes from two different namespaces: groups and flows. Boolean example (md5_hash=AA AND md5_hash=BB) AND (application_id=http AND (mime_type~pdf OR mime_type~bzip2 OR filename~pkg OR filename~mov)) Python example { { 'all':[ 'md5_hash=AA', 'md5_hash=BB' ] }, { 'all':[ 'application_id=http' ], { { 'any':[ 'mime_type~pdf', 'mime_type~bzip2', 'filename~pkg', 'filename~mov' ] } } } } } PHP example array( array( 'all' => array( 'md5_hash=AA', 'md5_hash=BB' ) ), array( 'all' => array( 'application_id=http' ) ), array( 'any' => array( 'mime_type~pdf', 'mime_type~bzip2', 'filename~pkg', 'filename~mov' ) ) ) 78 Security Analytics Reference Guide Security Analytics 8.1 Alerts APIs Use rules to generate alerts. Get alerts list API Path /alerts Description Retrieve a list of alerts with the most recent first GUI Location Menu > Analyze > Alerts > List Parameters REQ Format Default Valid Inputs startDate X datetime — <YYYY-MM-DD>T<hh:ii:ss> [+|-]<zz:zz> Start date/time endDate X datetime — <YYYY-MM-DD>T<hh:ii:ss> [+|-]<zz:zz> End date/time page integer 1 1–<n> Page to retrieve; first page is 1 limit integer 25 1–100 Number of items per page direction string DESC ASC | DESC filters array — <advanced filter for alerts> PHP Example callAPI('GET','/alerts', array( 'startDate' => '2019-11-03T00:00:00-07:00', 'endDate' => '2019-11-03T23:59:59-07:00' 'page' => 10 'limit' => 25 'direction' => 'ASC' 'filters' => array( 'all' => array( array( 'key' => 'destination_ip', 'comp' => '=', 'value' => '203.0.113.5' ) array( 'any' => array( array( 'key' => 'rule', 'comp' => '~', 'value' => 'local' ), 79 Description Sort order Advanced filter attributes Security Analytics Reference Guide Security Analytics 8.1 array( 'key' => 'score', 'comp' => '>', 'value' => 5 ) ) ) ) ) ) ); Python Example s.callAPI("GET","/alerts", { 'startDate': '2019-11-03T00:00:00-07:00', 'endDate': '2019-11-03T23:59:59-07:00', 'page': 10, 'limit': 25, 'direction': 'ASC', 'filters': { 'all': [ { 'key':'destination_ip', 'comp':'=', 'value':'203.0.113.5' } ], { 'any': [ { 'key':'rule', 'comp':'~', 'value':'local' }, { 'key':'score', 'comp':'>', 'value':5 } ] } } } ) Output 'paging': {'NotificationAlert': {'count': <integer>, 'current': <integer>, 'limit': <integer>, 'nextPage': [True|False], 'options': {'order': {'NotificationAlert.modified_date': 'desc'}}, 'order': {'NotificationAlert.modified_date': 'desc'}, 'page': <integer>, 'pageCount': <integer>, 'paramType': '<string>', 'prevPage': [True|False]}}, 'result': {'pageCount': 255, 'rows': [{'action': '<rule name>', 'action_display': '<rule name>', 'action_type': <integer>, 'action_uuid': '<UUID>', 'appliance_id': [None|<integer>], 'description': '', 80 Security Analytics Reference Guide Security Analytics 8.1 'destination_ip': '<ip>', 'destination_mac': '<mac>', 'destination_port': <port>, 'endpoint_providers': <integer>, 'favorite': '<indicator name>', 'favorite_action_uuid': '<UUID>', 'flow_id': <integer>, 'flow_start_time': <epoch>, 'flow_stop_time': <epoch>, 'hasCascadedHits': [True|False], 'hasResponse': [True|False], 'import_id': <integer>, 'importance': <integer>, 'match_criteria': '<open_parser_regex>', 'modified_date': <epoch>, 'name': '<string>', 'object_type': '<string>', 'source_ip': '<ip>', 'source_mac': '<mac>', 'source_port': <port>, 'time': <epoch>, 'user_id': <string>, 'username': <string>, 'uuid': '<UUID>', 'workflow_state': <integer>}, Get alerts timeline API Path /alerts/timeline_data Description Retrieve the alerts histogram GUI Location Alerts Management Dashboard Parameters REQ filters Format Default Valid Inputs array — <advanced filter for alerts> Description Advanced filter attributes startDate X datetime — <YYYY-MM-DD hh:ii:ss> [+|-]<zz:zz> Start time endDate X datetime — <YYYY-MM-DD hh:ii:ss> [+|-]<zz:zz> End time PHP Example callAPI('GET','/alerts/timeline_data', array( 'startDate' => '2019-11-03 10:25:00-07:00', 'endDate' => '2019-11-03 10:40:00-07:00' ) ); 81 Security Analytics Reference Guide Security Analytics 8.1 Python Example s.callAPI("GET","/alerts/timeline_data",{ 'startDate':'2019-11-03 10:25:00-07:00', 'endDate':'2019-11-03 10:40:00-07:00' } ) Output 'result': {'rows': [{'data': [], 'time': <epoch>}, {'data': [], 'time': <epoch>}, ... {'data': [], 'time': <epoch>}, {'data': [], 'time': <epoch>}, {'data': [{'bucket': 18, 'count': 22, 'higher': '<epoch>', 'importance': 2, 'lower': '<epoch>', 'time': '<epoch>'}, {'bucket': 18, 'count': 1, 'higher': '<epoch>', 'importance': 3, 'lower': '<epoch>', 'time': '<epoch>'}], 'time': <epoch>}, {'data': [{'bucket': 19, 'count': 15, 'higher': '<epoch>', 'importance': 1, 'lower': '<epoch>', 'time': '<epoch>'}, {'bucket': 19, 'count': 17, 'higher': '<epoch>', 'importance': 2, 'lower': '<epoch>', 'time': '<epoch>'}], 'time': <epoch>}, {'data': [], 'time': <epoch>}, {'data': [], 'time': <epoch>}, ... {'data': [], 'time': <epoch>}, {'data': [], 'time': <epoch>}]}, 'resultCode': 'API_SUCCESS_CODE', Get alert counts API Path /notifications/alerts Description Retrieve the number of alerts for anomalies (1), critical (2), and warning (3) GUI Location Alerts Notification 82 Security Analytics Reference Guide Security Analytics 8.1 Parameters None PHP Example callAPI('GET','/notifications/alerts'); Python Example s.callAPI("GET","/notifications/alerts") Output 'result': {'1': 0, '2': 57, '3': 53}, Get webtop data API Path /notifications/webtop Description Retrieve system utilization data GUI Location System Utilization Parameters REQ cached Format Default Boolean false Valid Inputs Description true | false Whether to retrieve data from cache PHP Example callAPI('GET','/notifications/webtop'); Python Example s.callAPI("GET","/notifications/webtop") Output 'result': {'cpu': [{'id': 0, 'title': 'All', 'usage': <floating>}, {'id': 1, 'title': 'Core 1', 'usage': <floating>}, {'id': 2, 'title': 'Core 2', 'usage': <floating>}, {'id': 3, 'title': 'Core 3', 'usage': <floating>}, {'id': 4, 'title': 'Core 4', 'usage': <floating>}], 'malwareAppliances': [], 'memory': {'free': <integer>, 'percent_used': <floating>, 'total': <integer>, 'used': <integer>}, 'time': 1536877964.5899, 'uptime': {'idle': 1136103.12, 'total': 97192.04}}, 'resultCode': 'API_SUCCESS_CODE', 83 Security Analytics Reference Guide Security Analytics 8.1 Get alert summary API Path /alerts/summary_data Description Retrieve a summary of the alerts GUI Location Menu > Analyze > Alerts > Summary Parameters REQ Format Default Valid Inputs Description filters array — <advanced filter for alerts> direction string DESC ASC | DESC page integer 1 1–<n> Page number; first page is 1 limit integer 25 1–100 Number of items per page Advanced filter attributes Sort order startDate X datetime — <YYYY-MM-DD hh:ii:ss> [+|-]<zz:zz> Start time endDate X datetime — <YYYY-MM-DD hh:ii:ss> [+|-]<zz:zz> End time array () groupBy integration_provider | Tables on the Alerts > importance | action | favorite | Summary page. Two source_ip | destination_ip | attributes may be specified, type | score such as favorite (indicator) with action (rule). PHP Example callAPI('GET','/alerts/summary_data', array( 'filters' => array( 'all' => array( array( 'key' => 'destination_ip', 'comp' => '=', 'value' => '203.0.113.5' ) ) array( 'any' => array( array( 'key' => 'rule', 'comp' => '~', 'value' => 'local' ), array( 'key' => 'score', 'comp' => '>', 84 Security Analytics Reference Guide Security Analytics 8.1 'value' => 5 ) ) ) ) ) 'page' => 10 'limit' => 20 'direction' => 'ASC' 'groupBy' => array( 'score', 'integration_provider' ) 'startDate' => '2019-11-03T00:00:00-07:00', 'endDate' => '2019-11-03T23:59:59-07:00' ) ); Python Example s.callAPI("GET","/alerts/summary_data", { 'filters': { 'all': [ { 'key':'destination_ip', 'comp':'=', 'value':'203.0.113.5' } ], { 'any': [ { 'key':'rule', 'comp':'~', 'value':'local' }, { 'key':'score', 'comp':'>', 'value':5 } ] } } 'page': 10 'limit': 20 'direction': 'ASC' 'groupBy': [ 'score', 'integration_provider' ], 'startDate': '2019-11-03T00:00:00-07:00', 'endDate': '2019-11-03T23:59:59-07:00' } ) Output 'paging': {'NotificationAlert': {'count': <integer>, 'current': <integer>, 'limit': <integer>, 'nextPage': [True|False], 'options': {'order': {'<groupBy1>.<groupBy2>': ' [ASC|DESC]', 'count': '[ASC|DESC]'}}, 'order': {'<groupBy1>.<groupBy2>': '[ASC|DESC]', 'count': '[ASC|DESC]'}, 85 Security Analytics Reference Guide Security Analytics 8.1 'page': 1, 'pageCount': <integer>, 'paramType': '<string>', 'prevPage': [True|False]}}, 'result': {'pageCount': <integer>, 'rows': [{'count': 1, '<groupBy1>': '<value1>', '<groupBy2>': '<value2>'}, {'count': 1, '<groupBy1>': '<value1>', '<groupBy2>': '<value2>'}, ... {'count': 1, '<groupBy1>': '<value1>', '<groupBy2>': '<value2>'}, }], 'totalAlertsCount': <integer>}, 'resultCode': 'API_SUCCESS_CODE', Get notification list API Path /notifications/notifications Description Retrieve a list of system notifications GUI Location System Notifications Parameters None PHP Example callAPI('GET','/notifications/notifications'); Python Example s.callAPI("GET","/notifications/notifications") Output 'result': {'amount': <integer>, 'notifications': [{'amount': <integer>, 'appliance_id': [None|<integer>], 'foreign_id': <integer>, 'foreign_uuid': [None|<UUID>], 'hidden': [True|False], 'id': <integer>, 'importance': <integer>, 'importance_level': <integer>, 'insert_time': <epoch>, 'title': '<string>' '<string>', 'type': <integer>, 'user_id': <integer>}]}, 'resultCode': 'API_SUCCESS_CODE', 86 Security Analytics Reference Guide Security Analytics 8.1 Set alert state for a selected alert API Path /alerts/update Description Set the workflow state of selected alerts GUI Location Menu > Analyze > Alerts > List > Actions > Set State Output array Parameters REQ Format Default alerts X array — <advanced filter for alerts> alert_uuid X UUID — <GET: /alerts> workflow_state X integer 0 0 | 10 | 20 | 30 | 40 | 50 PHP Example callAPI('POST','/alerts/update', array( 'alerts' => array( 'uuid' => '<UUID>', 'workflow_state' => 10 ) ) ); Python Example s.callAPI("POST","/alerts/update", { 'alerts': { 'uuid': '<UUID>', 'workflow_state': 10 } 87 Valid Inputs Description Array containing alert_ uuid and workflow_state UUID of selected alert Workflow state: n 0 — Unassigned n 10 — Assigned n 20 — In progress n 30 — On hold n 40 — Resolved n 50 — Closed Security Analytics Reference Guide Security Analytics 8.1 } ) Set alert state for a range of alerts API Path /alerts/update Description Set the workflow state or owner for a range of alerts GUI Location Menu > Analyze > Alerts > List > Actions > Set State Output array Parameters REQ Format Default Valid Inputs workflow_state | user_id Description fieldName X string — fieldValue X integer — startDate X datetime — <YYYY-MM-DD> <hh:ii:ss>[+|-]<zz:zz> Start date/time endDate X datetime — <YYYY-MM-DD> <hh:ii:ss>[+|-]<zz:zz> End date/time Attribute to change 0 | 10 | 20 | 30 | 40 | 50 | <GET: /settings/users> Value for the attribute PHP Example callAPI('POST','/alerts/update_field', array( 'fieldName' => 'workflow_state', 'fieldValue' => 10, 'startDate' => '2019-04-28 11:28:25-07:00', 'endDate' => '2019-05-02 11:28:25-07:00' ) ); Python Example s.callAPI("POST","/alerts/update_field", { 'fieldName': 'workflow_state', 'fieldValue': 10, 'startDate': '2019-04-28 11:28:25-07:00', 'endDate': '2019-05-02 11:28:25-07:00' } ) 88 Security Analytics Reference Guide Security Analytics 8.1 Clear alerts API Path /alerts/clear_alerts Description Clear some or all alerts that have been selected by the timespan and advanced filters OR by the check boxes. GUI Location Menu > Analyze > Alerts > List > Actions > Delete Output array Parameters REQ Format Default Valid Inputs array — <advanced filter for alerts> Advanced filter attributes startDate datetime — <YYYY-MM-DD>T<hh:ii:ss> [+|-]<zz:zz> Start date/time endDate datetime — <YYYY-MM-DD>T<hh:ii:ss> [+|-]<zz:zz> End date/time array — <GET: /alerts> filters selectedIDs PHP Example 1 Clear alerts that are selected by the filter and timespan callAPI('POST','/alerts/clear_alerts', array( 'filters' => array( 'all' => array( array( 'key' => 'destination_ip', 'comp' => '=', 'value' => '203.0.113.5' ) ) ), 'startDate' => '2019-11-03T00:00:00-07:00', 'endDate' => '2019-11-03T23:59:59-07:00' ) ); Python Example 1 Clear alerts that are selected by the filter and timespan 89 Description UUIDs of the alerts to delete; use instead of timespan and filter Security Analytics Reference Guide Security Analytics 8.1 s.callAPI("POST","/alerts/clear_alerts", { 'filters': { 'all': { { 'key': 'destination_ip', 'comp': '=', 'value': '203.0.113.5' } } }, 'startDate': '2019-11-03T00:00:00-07:00', 'endDate': '2019-11-03T23:59:59-07:00' } ) PHP Example 2 Clear alerts that are selected by check boxes callAPI('POST','/alerts/clear_alerts', array( 'selectedIDs' => array( <UUID>, <UUID>, <UUID>, <UUID> ) ) ); Python Example 2 Clear alerts that are selected by check boxes s.callAPI("POST","/alerts/clear_alerts", { 'selectedIDs': [ <UUID>, <UUID>, <UUID>, <UUID> ] } ) 90 Security Analytics Reference Guide Security Analytics 8.1 Anomalies APIs Get anomalies API Path /anomalies Description Retrieve a list of anomalies with the highest score first GUI Location Menu > Analyze > Anomalies > List Parameters REQ Format Default Valid Inputs Description page integer 1 1– <n> Page to retrieve; first page is 1 limit integer 25 1–100 Number of items per page sort string score score | create_ time direction string DESC ASC | DESC filters array — <advanced filter for anomalies> timeRange array — <timespan date array> Time of Detection timespan filter anomalyAnalysisWindow array — <timespan date array> Analysis Window timespan filter; if you also use the timeRange filter, anomalyAnalysisWindow should contain timeRange. Python Example s.callAPI("GET","/anomalies", { 'filters': { 'all': { { 'key': 'function', 'comp': '~', 'value': 'count' }, { 'any': { { 'key': 'initiator_ip', 'comp': '=', 'value': '203.0.113.5' }, { 'key': 'field', 91 Sort-by column; corresponds to sortable column headings in the Anomalies List table. Sort order Advanced filter attributes Security Analytics Reference Guide Security Analytics 8.1 'comp': '~', 'value': 'port' } } } } }, 'timeRange': { 'start': '2019-11-03T05:30:00+01:00', 'end': '2019-11-03T05:40:00+01:00' }, 'anomalyAnalysisWindow': { 'start': '2019-11-03T05:10:00+01:00', 'end': '2019-11-03T05:40:00+01:00' } } } PHP Example callAPI('GET','/anomalies', array( 'filters' => array( 'all' => array( array( 'key' => 'function', 'comp' => '~', 'value' => 'count' ), array( 'any' => array( array( 'key' => 'initiator_ip', 'comp' => '=', 'value' => '203.0.113.5' ), array( 'key' => 'field', 'comp' => '~', 'value' => 'port' ) ) ) ) ), 'timeRange' => array( 'start' => '2019-11-03T05:30:00+01:00', 'end' => '2019-11-03T05:40:00+01:00' ), 'anomalyAnalysisWindow' => array( 'start' => '2019-11-03T05:10:00+01:00', 'end' => '2019-11-03T05:40:00+01:00' ) ) ); Output 'paging': {'AnomalyAlert': {'count': <integer>, 'current': <integer>, 'limit': <integer>, 'nextPage': [True|False], 'options': [], 'order': 'score [ASC|DESC],over_field_value ' 'desc,create_time desc', 'page': <integer>, 'pageCount': <integer>, 92 Security Analytics Reference Guide Security Analytics 8.1 'paramType': 'named', 'prevPage': [True|False]}}, 'result': {'pageCount': <integer>, 'recordCount': <integer>, 'rows': [{'actual': '<floating>+06', 'actual_probability': '0', 'anomaly_score': '<floating>', 'appliance_id': None, 'by_field_name': '', 'by_field_value': '', 'create_time': <epoch>, 'end_time': <epoch>, 'field_name': '<string>', 'field_value': '', 'flags': 0, 'function': '<string>', 'gauge_path': '["timespan=<YYYY-MM-DD>T<hh:ii:ss>.000+0000_<YYYY-MMDD>T<hh:ii:ss>.000+0000","<field1>=<value1>","<field2>=<value2>"]', 'id': <integer>, 'old_id': None, 'over_field_name': '<string>', 'over_field_value': '<ip>', 'partition_field_name': '<string>', 'partition_field_value': '<string>', 'probability': '<floating>', 'score': <integer>, 'start_time': <epoch>, 'type': 0, 'typical': '<integer>'}, ... 'resultCode': 'API_SUCCESS_CODE', Get anomaly count API Path /anomalies/count Description Retrieve the number of anomaly records within the specified timespans GUI Location Top navigation, Alerts box Parameters REQ Format Default Valid Inputs Description filters array — <advanced filter for anomalies> Advanced filter attributes timeRange array — <timespan date array> Time of Detection timespan filter 93 Security Analytics Reference Guide Security Analytics 8.1 REQ Format anomalyAnalysisWindow array Default — Valid Inputs <timespan date array> Python Example s.callAPI("GET","/anomalies/count", { 'filters': { 'all': { { 'key': 'function', 'comp': '~', 'value': 'count' }, { 'any': { { 'key': 'initiator_ip', 'comp': '=', 'value': '203.0.113.5' }, { 'key': 'field', 'comp': '~', 'value': 'port' } } } } }, 'timeRange': { 'start': '2019-11-03T05:30:00+01:00', 'end': '2019-11-03T05:40:00+01:00' }, 'anomalyAnalysisWindow': { 'start': '2019-11-03T05:10:00+01:00', 'end': '2019-11-03T05:40:00+01:00' } } } PHP Example callAPI('GET','/anomalies/count', array( 'filters' => array( 'all' => array( array( 'key' => 'function', 'comp' => '~', 'value' => 'count', ), array( 'any' => array( array( 'key' => 'initiator_ip', 'comp' => '=', 'value' => '203.0.113.5' ) array( 94 Description Analysis Window timespan filter; if you also use the timeRange filter, anomalyAnalysisWindow should contain timeRange. Security Analytics Reference Guide Security Analytics 8.1 'key' => 'field', 'comp' => '~', 'value' => 'port' ) ) ) ) ), 'timeRange' => array( 'start' => '2019-11-03T05:30:00+01:00', 'end' => '2019-11-03T05:40:00+01:00' ), 'anomalyAnalysisWindow' => array( 'start' => '2019-11-03T05:10:00+01:00', 'end' => '2019-11-03T05:40:00+01:00' ) ) ); Output 'result': {'Anomalies': {'count': <integer>}}, 'resultCode': 'API_SUCCESS_CODE', Get summary of anomalies API Path /anomalies/summary_data Description Retrieve anomalies, sorted by the tables displayed on the Anomalies Summary page GUI Location Menu > Analyze > Anomalies > Summary Parameters REQ Format Default Valid Inputs Description page integer 1 1– <n> Page to retrieve; first page is 1 limit integer 25 1–100 Number of items per page sort string count <anomaly summary groups> direction string DESC ASC | DESC Sort order filters array — <advanced filter for anomalies> Advanced filter attributes array — <anomaly summary groups> groupBy X 95 Sort-by column; corresponds to sortable column headings in the Anomalies Summary tables Summary groups on the Anomalies > Summary page Security Analytics Reference Guide Security Analytics 8.1 REQ timeRange anomalyAnalysisWindow Format Default Valid Inputs Description array — <timespan date array> Time of Detection timespan filter array — <timespan date array> Analysis Window timespan filter; if you also use the timeRange filter, anomalyAnalysisWindow should contain timeRange. Python Example callAPI("GET","/anomalies/summary_data", { 'filters': { 'all': { { 'key': 'function', 'comp': '~', 'value': 'count' }, { 'any': { { 'key': 'initiator_ip', 'comp': '=', 'value': '203.0.113.5' } { 'key': 'field', 'comp': '~', 'value': 'port' } } } } }, 'groupBy': [ 'applications', 'initiator_ip' ], 'timeRange': { 'start': '2019-11-03T05:30:00+01:00', 'end': '2019-11-03T05:40:00+01:00' }, 'anomalyAnalysisWindow': { 'start' => '2019-11-03T05:10:00+01:00', 'end' => '2019-11-03T05:40:00+01:00' } } } PHP Example callAPI('GET','/anomalies/summary_data', array( 'filters' => array( 'all' => array( array( 'key' => 'function', 'comp' => '~', 'value' => 'count' ), array( 'any' => array( array( 96 Security Analytics Reference Guide Security Analytics 8.1 'key' => 'initiator_ip', 'comp' => '=', 'value' => '203.0.113.5' ) array( 'key' => 'field', 'comp' => '~', 'value' => 'port' ) ) ) ) ), 'groupBy' => array( 'applications', 'initiator_ip' ), 'timeRange' => array( 'start' => '2019-11-03T05:30:00+01:00', 'end' => '2019-11-03T05:40:00+01:00' ), 'anomalyAnalysisWindow' => array( 'start' => '2019-11-03T05:10:00+01:00', 'end' => '2019-11-03T05:40:00+01:00' ) ) ); Output 'paging': {'AnomalyAlert': {'count': <integer>, 'current': <integer>, 'limit': <integer>, 'nextPage': [True|False], 'options': [], 'order': {'<group1>': 'ASC', 'count': 'DESC', '<groupN>': 'ASC'}, 'page': <integer>, 'pageCount': <integer>, 'paramType': 'named', 'prevPage': [True|False]}}, 'result': {'pageCount': <integer>, 'recordCount': <integer>, 'rows': [{'<group1>': '<value1>', 'count': 1, '<groupN>': '<valueN>'}, ... {'<group1>': '<value1>', 'count': 1, '<groupN>': '<valueN>'}]}, 'resultCode': 'API_SUCCESS_CODE', Clear anomalies API Path /anomalies/delete_anomalies Description Clear some or all anomalies that have been selected by the timespan and advanced filters. These anomalies are cleared from the appliance as well as from the GUI display. 97 Security Analytics Reference Guide Security Analytics 8.1 GUI Location Menu > Analyze > Anomalies > List > Clear button Output array Parameters REQ Format Default Valid Inputs Description filters array — <advanced filter for anomalies> timeRange array — <timespan date array> Time of Detection timespan filter array — <timespan date array> Analysis Window timespan filter; if you also use the timeRange filter, anomalyAnalysisWindow should contain timeRange. anomalyAnalysisWindow Python Example callAPI("POST","/anomalies/delete_anomalies", { 'filters': { 'all': { { 'key': 'function', 'comp': '~', 'value': 'count' }, { 'any': { { 'key': 'initiator_ip', 'comp': '=', 'value': '203.0.113.5' } { 'key': 'field', 'comp': '~', 'value': 'port' } } } } }, 'timeRange': { 'start: '2019-11-03T05:30:00+01:00', 'end': '2019-11-03T05:40:00+01:00' }, 'anomalyAnalysisWindow': { 'start': '2019-11-03T05:10:00+01:00', 'end': '2019-11-03T05:40:00+01:00' } } } PHP Example callAPI('POST','/anomalies/delete_anomalies', array( 'filters' => array( 98 Advanced filter attributes Security Analytics Reference Guide Security Analytics 8.1 'all' => array( array( 'key' => 'function', 'comp' => '~', 'value' => 'count' ), array( 'any' => array( array( 'key' => 'initiator_ip', 'comp' => '=', 'value' => '203.0.113.5' ) array( 'key' => 'field', 'comp' => '~', 'value' => 'port' ) ) ) ) ), 'timeRange' => array( 'start' => '2019-11-03T05:30:00+01:00', 'end' => '2019-11-03T05:40:00+01:00' ), 'anomalyAnalysisWindow' => array( 'start' => '2019-11-03T05:10:00+01:00', 'end' => '2019-11-03T05:40:00+01:00' ) ) ); 99 Security Analytics Reference Guide Security Analytics 8.1 Authentication APIs These APIs correspond to the functions on the Authentication Settings page. Also see the "User Account APIs" on page 386. Get LDAP settings API Path /settings/ldap Description Retrieve LDAP server settings from /etc/ldap.conf GUI Location Menu > Settings > Authentication Parameters None Example callAPI('GET','/settings/ldap'); Output {'errors': [], 'messages': [], 'paging': [], 'result': {'SystemSetting': {'ldap_base': 'dc=example,dc=com', 'ldap_bind_dn': '<string>', 'ldap_bind_policy': 'soft', 'ldap_cred_grp_bind': True, 'ldap_enabled': 1, 'ldap_gecos': '<string>', 'ldap_gid_number': '<string>', 'ldap_group_naming_attribute': 'cn', 'ldap_group_object_class': '<string>', 'ldap_home_directory': '<string>', 'ldap_login_name': '<string>', 'ldap_login_shell': '<string>', 'ldap_pam_filter': 'objectclass=<user object class>', 'ldap_pam_login': '<login name attribute>', 'ldap_pam_member': '<group membership attribute>', 'ldap_pam_password_change': '<string>', 'ldap_passwd_encrypt': 'yes', 'ldap_port': 636, 'ldap_sasl_secprops': 'maxssf=0', 'ldap_schema': 'user_defined', 'ldap_scope': 'sub', 100 Security Analytics Reference Guide Security Analytics 8.1 'ldap_server': '<hostname>', 'ldap_shadow_object_class': '<string>', 'ldap_tls_check_peer': True, 'ldap_uid_number': '<string>', 'ldap_unique_member': '<group membership attribute>', 'ldap_uri': 'ldaps://<hostname>:636', 'ldap_use_ssl': 'on', 'ldap_user_object_class': '<string>', 'ldap_user_password': '<string>', 'ldap_version': '3'}}, 'resultCode': 'API_SUCCESS_CODE', 'validationErrors': {'Meta': [], 'Setting': [], 'SystemSetting': [], 'res': []}} Discover LDAP settings API Path /settings/ldap_discover Description Initiate LDAP discovery GUI Location Menu > Settings > Authentication Output integer Parameters domain REQ Format Default Valid Inputs X string — <FQDN> Example callAPI('GET','/settings/ldap_discover', array( 'domain' => 'ldap.company.com' ) ); Get LDAP auto-discovery flag state API Path /settings/get_ldap_discover_flag 101 Description FQDN of LDAP server Security Analytics Reference Guide Security Analytics 8.1 Description Retrieve the state of the LDAP auto-discovery flag GUI Location Menu > Settings > Authentication Parameters None Example callAPI('GET','/settings/get_ldap_discover_flag'); Output {'errors': [], 'messages': [], 'paging': [], 'result': [0|1], 'resultCode': 'API_SUCCESS_CODE', 'validationErrors': {'Meta': [], 'Setting': [], 'SystemSetting': [], 'res': []}} Get LDAP options API Path /settings/ldap_options Description Retrieve LDAP options GUI Location Menu > Settings > Authentication Parameters None Example callAPI('GET','/settings/ldap_options'); Output {'errors': [], 'messages': [], 102 Security Analytics Reference Guide Security Analytics 8.1 'paging': [], 'result': {'ldap_password_change_methods': ['clear', 'clear_remove_old', 'crypt', 'md5', 'ad', 'nds', 'racf', 'exop', 'exop_send_old'], 'ldap_rfc_modes': 'rfc2307bis', 'ldap_schema_map': ['madrfc2307', 'msu35', 'msu20', 'rfc2307bis', 'rfc2307', 'inetorgperson'], 'ldap_scopes': ['sub', 'one', 'base'], 'ldap_ssl_types': ['no', 'on', 'start_tls'], 'ldap_versions': 3}, 'resultCode': 'API_SUCCESS_CODE', 'validationErrors': {'Meta': [], 'SystemSetting': [], 'res': []}} Get LDAP group members API Path /settings/ldap_groups/<group>/<limit> Description Retrieve the members of an LDAP (external) group GUI Location n/a Output array Parameters REQ Format Default Valid Inputs group X string — <GET: /settings/list_ldap_ groups> limit X integer — 1–<n> Example callAPI('GET','/settings/ldap_groups/admins/100'); 103 Description Name of LDAP group Maximum number of users to retrieve Security Analytics Reference Guide Security Analytics 8.1 Get Kerberos settings API Path /settings/kerberos Description Retrieve Kerberos settings GUI Location Menu > Settings > Authentication Output array Parameters None Example callAPI('GET','/settings/kerberos'); Get RADIUS settings API Path /settings/radius_auth Description Retrieve RADIUS settings GUI Location Menu > Settings > Authentication Parameters None Example callAPI('GET','/settings/radius_auth'); Output {'errors': [], 'messages': [], 'paging': [], 'result': {'enable': True, 104 Security Analytics Reference Guide Security Analytics 8.1 'password': '***************************', 'port': '1812', 'server': '<hostname>', 'timeout': '3'}, 'resultCode': 'API_SUCCESS_CODE', 'validationErrors': {'Meta': [], 'Setting': [], 'SystemSetting': [], 'res': []}} Configure LDAP authentication API Path /settings/ldap Description Configure LDAP authentication GUI Location Menu > Settings > Authentication Output ApiResultCode Parameters REQ enable Format Default Valid Inputs Description string true true | false True — Enable LDAP authentication; auto-discover is not launched string 127.0.0.1 <dotted-decimal> | <FQDN> IP address or FQDN of LDAP server number 636 0–65535 username string — <UTF-8 characters> BIND DN password string — <UTF-8 characters> BIND password Boolean false true | false search array — base string — scope string sub server port test X Port number for the secure LDAP server. This default is New in Security Analytics 8.1.x. True — Test the connection to the LDAP server Array contains base, scope, group dc=<domain>,dc=<tld> Search base base | one | sub 105 Search scope Security Analytics Reference Guide REQ Security Analytics 8.1 Format Default Valid Inputs Description group string — <UTF-8 characters> Group DN group_naming_ attribute string — <UTF-8 characters> Group name attribute Boolean | string | array tls true | false | tls | ssl | array:( 'encryption' => [tls | ssl], 'check_peer' => [true | false]) Encryption type: encryption version schema_options integer 3 3 array user_ defined user_defined | inetorgperson | madrfc2307 | msu20 | msu35 | rfc2703 | rfc2307bis n true — Enable TLS mode n false — Disable TLS mode n tls — Enable TLS mode n ssl — Enable SSL mode n encryption — Encryption mode n check_peer o true — Check certificate for valid CA o false — No certificate check; permit self-signed certificates LDAP version; only 3 is valid LDAP schema: n madrfc2307 — Microsoft Active Directory (RFC 2307) n msu20 — Microsoft Services for Unix 2.0 n msu35 — Microsoft Services for Unix 3.5 schema array — user_object_ class string — <UTF-8 characters> User object class login_name string — <UTF-8 characters> Login name attribute gecos string — <UTF-8 characters> Full name (GECOS) attribute user_password string — <UTF-8 characters> User password attribute Required if schema_options=user_ defined; array contains all of the fields below 106 Security Analytics Reference Guide REQ pam_password_ change Security Analytics 8.1 Format string Default md5 Valid Inputs Description clear | clear_ remove_old | crypt | md5 | ad | nds | racf | exop | exop_send_ old Password change method: n clear — Cleartext n clear_remove_old — Cleartext (remove old password first) n crypt — Crypt n nds — Novell NDS n racf — IBM RACF n exop — RFC 3062 n exop_send_old — RFC 3062 (send old and new passwords) uid_number string — <UTF-8 characters> User ID number attribute home_directory string — <UTF-8 characters> Home directory attribute login_shell string — <UTF-8 characters> User shell attribute shadow_object_ class string — <UTF-8 characters> Shadow object class group_object_ class string — <UTF-8 characters> Group object class gid_number string — <UTF-8 characters> Group ID number attribute pam_member string — <UTF-8 characters> Group membership attribute rfc_mode string rfc2307bis rfc2307bis Group membership type; only rfc2307bis is valid Example callAPI('POST','/settings/ldap', array( 'server' => '203.0.113.5', 'port' => '389', 'test' => 'true', 'search' => array( 'base' => 'dc=ldap,dc=symantec,dc=com', 'scope' => 'sub', 'group' => '<group_dn>', 'group_name_attribute' => '<group_name_attribute>' ), 'encryption' => array( 'encryption' => 'ssl', 'check_peer' => 'true' ), 'schema_options' => 'user_defined', 'schema' => array( user_object_class' => '<value>', login_name gecos' => '<value>', user_password' => '<value>', pam_password_change' => 'crypt', 107 Security Analytics Reference Guide Security Analytics 8.1 uid_number' => '<value>', home_directory' => '<value>', login_shell' => '<value>', shadow_object_class' => '<value>', group_object_class' => '<value>', gid_number' => '<value>', pam_member' => '<value>' ) ) ); Initiate LDAP discovery API Path /settings/ldap_discover Description Automatically discover an LDAP server's settings and log in to the server GUI Location Menu > Settings > Authentication Output ApiResultCode Parameters REQ Format Default Valid Inputs domain X string — <FQDN> username X string — <UTF-8 characters> Admin-level account name password X string — <UTF-8 characters> Account password Example callAPI('POST','/settings/ldap_discover', array( 'domain' => 'ldap.company.com', 'username' => 'ldap_admin', 'password' => '55geT!meIn&*' ) ); Configure Kerberos settings API Path /settings/kerberos 108 Description FQDN of LDAP server Security Analytics Reference Guide Security Analytics 8.1 Description Enable and configure Kerberos single sign-on GUI Location Menu > Settings > Authentication Output ApiResultCode Parameters REQ Format enable X kdc Default Valid Inputs Description Boolean true | false True — Enable Kerberos single sign-on X string <dotted-decimal> realm X STRING domain X STRING username X string — <UTF-8 characters> User with authorization to bind a machine to the Kerberos domain password X string — <UTF-8 characters> User password — <FQDN> <BIND_DN> Example callAPI('POST','/settings/kerberos', array( 'enable' => 'true', 'kdc' => '203.0.113.5', 'realm' => 'KERBEROS.COMPANY.COM', 'domain' => '<BIND_DN>', 'username' => 'kerberos_admin', 'password' => '55geT!meIn&*' ) ); Configure RADIUS settings API Path /settings/radius_auth Description Enable and configure RADIUS authentication GUI Location Menu > Settings > Authentication 109 IP of Kerberos domain controller FQDN of the Kerberos domain controller in ALL CAPS Domain of Kerberos server in ALL CAPS Security Analytics Reference Guide Security Analytics 8.1 Output array Parameters REQ Format Default Valid Inputs Description enable X Boolean false true | false True — Enable RADIUS authentication server X string — <dotted-decimal> | <hostname> port X integer 1812 1–65535 password X password — <UTF-8 characters> timeout X integer 3 2–60 Example callAPI('POST','/settings/radius_auth', array( 'enable' => true, 'server' => 'radius.company.com', 'port' => 51812, 'password' => '55geT!meIn&*', 'timeout' => 5 ) ); 110 RADIUS server RADIUS port Shared secret Number of seconds between the three RADIUS-request retransmissions Security Analytics Reference Guide Security Analytics 8.1 BPF Filters APIs Get capture-interface filters API Path /captures/filter/<interface> Description Get the static capture filters for the specified interface. Dynamic filters are not included. GUI Location Menu > Capture > Summary > [interface box] > [Apply | Edit] Filter Output array Parameters REQ Format Default Valid Inputs Description X string — ethX | aggX Ethernet or aggregated interface interface Example callAPI('GET','/captures/filter/eth3'); Get the current user's BPF filters API Path /filters/get_user_filters Description Retrieve all BPF filters that have been created by the current user GUI Location n Menu > Capture > Summary > [interface box] > [Apply | Edit] Filter n Menu > Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > [More Information | Actions > Download PCAP] > PCAP without PCAP Filters download Output array Parameters None 111 Security Analytics Reference Guide Security Analytics 8.1 Example callAPI('GET','/filters/get_user_filters'); Get a BPF filter API Path /filters/get/<id> Description Retrieve a specified BPF filter for PCAP download GUI Location Menu > Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > [More Information | Actions > Download PCAP] > PCAP without PCAP Filters download Output array Parameters REQ Format Default Valid Inputs Description X integer — <GET: /filters/get_user_ filters> ID of the filter id Example callAPI('GET','/filters/get/<id>'); Create a BPF filter API Path /filters/create Description Create a BPF filter for capture interfaces GUI Location n Menu > Capture > Summary > [interface box] > [Apply | Edit] Filter > Create New Filter n Menu > Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > [More Information | Actions > Download PCAP] > PCAP without PCAP Filters type > Create New Filter Output array 112 Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ Format Default Valid Inputs name X string — <UTF-8 characters> filter X BPF — <BPF expression> Description Name for the filter Filter definition Example callAPI('POST','/filters/create', array( 'name' => 'web_only', 'filter' => '(port 80 or 8080 or 443)' ) ); Apply an existing filter to an interface API Path /captures/filter/<interface> Description Apply a saved capture filter to the specified interface GUI Location Menu > Capture > Summary > [interface box] > [Apply | Edit] Filter Output array Parameters REQ Format Default Valid Inputs Description interface X string — ethX | aggX Ethernet or aggregated interface filter X integer — <GET: /filters/get_user_ filters> Example callAPI('POST','/captures/filter/eth3', array( 'filter' => '4' ) ); Remove a filter from an interface API Path /captures/filter/remove/<interface> 113 Filter ID Security Analytics Reference Guide Security Analytics 8.1 Description Remove a BPF filter from a capture interface GUI Location Menu > Capture > Summary > [interface box] > Edit Filter > No Filter Output array Parameters REQ interface X Format Default string — Valid Inputs Description ethX | aggX Ethernet or aggregated interface Example callAPI('POST','/captures/filter/remove/eth3'); Edit a BPF filter API Path /filters/edit_advanced/<id> Description Edit a BPF filter name or definition GUI Location n Menu > Capture > Summary > [interface box] > Edit Filter dialog n Menu > Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > [More Information | Actions > Download PCAP] > PCAP without PCAP Filters download Output array Parameters REQ Format Default Valid Inputs id X integer — name X string — <UTF-8 characters> filter X BPF — <BPF expression> Description <GET: /filters/get_user_filters> ID of the filter 114 Name for the filter Filter definition Security Analytics Reference Guide Security Analytics 8.1 Example callAPI('POST','/filters/edit_advanced/<id>', array( 'name' => 'web_only', 'filter' => '(port 80 or 8080 or 443)' ) ); Delete a BPF filter API Path /filters/delete/<id> Description Delete a BPF filter from the appliance GUI Location Menu > Capture > Summary > [interface box] > Edit Filter > Delete filter Output array Parameters REQ Format Default Valid Inputs Description X integer — <GET: /filters/get_user_filters> ID of the filter ids Example callAPI('POST','/filters/delete/<id>'); 115 Security Analytics Reference Guide Security Analytics 8.1 Capture APIs For capture-interface filters, use "BPF Filters APIs" on page 111. Get the average capture rate — NEW API Path /captures/get_billable Description Retrieve the average capture rate for the past 10 days in various units of measure. GUI Location Output {'errors': [], 'messages': [], 'paging': [], 'result': {'appliance_billing_stats': False, 'billing_stat': {'avg_bytes_per_day': 448930117174.95416, 'avg_gibibytes_per_day': 418.09875254980676, 'avg_gigabytes_per_day': 448.93011717495415, 'avg_kibibytes_per_day': 438408317.5536662, 'avg_kilobytes_per_day': 448930117.1749542, 'avg_mebibytes_per_day': 428133.1226110021, 'avg_megabytes_per_day': 448930.11717495415, 'avg_pebibytes_per_day': 0.00039873004202824284, 'avg_petabytes_per_day': 0.00044893011717495415, 'avg_tebibytes_per_day': 0.40829956303692067, 'avg_terabytes_per_day': 0.4489301171749542}, 'cmc_billing_stat': False}, 'resultCode': 'API_SUCCESS_CODE', 'validationErrors': {'LicenseStat': [], 'Meta': [], 'res': []}} Parameters None Example callAPI('GET','/captures/get_billable'); Get all interfaces API Path /captures/get_all_interfaces Description Retrieve a list of all interfaces and whether each is capturing or playing back 116 Security Analytics Reference Guide Security Analytics 8.1 GUI Location Menu > Capture > Summary > [interface boxes] Parameters None Example callAPI('GET','/captures/get_all_interfaces'); Output {'errors': [], 'messages': [], 'paging': [], 'result': {'aggregate': {'alias': False, 'averageFrameSizeBytes': 60, 'can_filter': True, 'capturing': True, 'capturingCurrentBytes': 0, 'capturingCurrentDroppedBytes': 0, 'capturingCurrentDroppedPackets': 0, 'capturingCurrentExceptionPackets': 0, 'capturingCurrentFilteredBytes': 0, 'capturingCurrentFilteredPackets': 0, 'capturingCurrentPackets': 0, 'capturingMaxBytes': 20, 'capturingMaxDroppedBytes': 0, 'capturingMaxDroppedPackets': 0, 'capturingMaxExceptionPackets': 0, 'capturingMaxFilteredBytes': 0, 'capturingMaxFilteredPackets': 0, 'capturingMaxPackets': 0, 'capturingTotalBytes': 60, 'capturingTotalDroppedBytes': 0, 'capturingTotalDroppedPackets': 0, 'capturingTotalExceptionBytes': 0, 'capturingTotalExceptionPackets': 0, 'capturingTotalFilteredBytes': 0, 'capturingTotalFilteredPackets': 0, 'capturingTotalPackets': 1, 'end_date': 1563979390, 'filter_name': '', 'filtering': False, 'fullDuplex': True, 'id': 610, 'interface': 'aggregate', 'ioctlId': None, 'is_management': True, 'linkSpeed': 20000, 'linkUp': True, 'mappedTo': ['agg0', 'agg1', 'agg2', 'agg3', 'agg4'], 117 Security Analytics Reference Guide Security Analytics 8.1 'name': 'aggregate', 'start_date': 1562638043, 'stats': {'capturing': True, 'capturingCurrent': 0, 'capturingCurrentBits': 0, 'capturingCurrentFiltered': 0, 'capturingCurrentFilteredBits': 0, 'capturingCurrentFilteredPackets': 0, 'capturingCurrentPackets': 0, 'capturingMax': 20, 'capturingMaxBits': 160, 'capturingMaxFiltered': 0, 'capturingMaxFilteredBits': 0, 'capturingMaxFilteredPackets': 0, 'capturingMaxPackets': 0, 'capturingTotal': 60, 'capturingTotalDropped': 0, 'capturingTotalFiltered': 0, 'filtered': False, 'linkSpeed': 20000, 'linkUp': True}}, 'eth1': {'alias': False, 'averageFrameSizeBytes': 60, 'can_filter': True, 'capturing': True, 'capturingCurrentBytes': 0, 'capturingCurrentDroppedBytes': 0, 'capturingCurrentDroppedPackets': 0, 'capturingCurrentExceptionPackets': 0, 'capturingCurrentFilteredBytes': 0, 'capturingCurrentFilteredPackets': 0, 'capturingCurrentPackets': 0, 'capturingMaxBytes': 20, 'capturingMaxDroppedBytes': 0, 'capturingMaxDroppedPackets': 0, 'capturingMaxExceptionPackets': 0, 'capturingMaxFilteredBytes': 0, 'capturingMaxFilteredPackets': 0, 'capturingMaxPackets': 0, 'capturingTotalBytes': 60, 'capturingTotalDroppedBytes': 0, 'capturingTotalDroppedPackets': 0, 'capturingTotalExceptionBytes': 0, 'capturingTotalExceptionPackets': 0, 'capturingTotalFilteredBytes': 0, 'capturingTotalFilteredPackets': 0, 'capturingTotalPackets': 1, 'end_date': 1563979390, 'filter_name': '', 'filtering': False, 'fullDuplex': True, 118 Security Analytics Reference Guide Security Analytics 8.1 'id': 611, 'interface': 'eth1', 'ioctlId': 3, 'is_management': False, 'linkSpeed': 10000, 'linkUp': True, 'mappedTo': None, 'name': 'eth1', 'start_date': 1562638043, 'stats': {'capturing': True, 'capturingCurrent': 0, 'capturingCurrentBits': 0, 'capturingCurrentFiltered': 0, 'capturingCurrentFilteredBits': 0, 'capturingCurrentFilteredPackets': 0, 'capturingCurrentPackets': 0, 'capturingMax': 20, 'capturingMaxBits': 160, 'capturingMaxFiltered': 0, 'capturingMaxFilteredBits': 0, 'capturingMaxFilteredPackets': 0, 'capturingMaxPackets': 0, 'capturingTotal': 60, 'capturingTotalDropped': 0, 'capturingTotalFiltered': 0, 'filtered': False, 'linkSpeed': 10000, 'linkUp': True}}}, 'resultCode': 'API_SUCCESS_CODE', 'validationErrors': {'EthInterface': [], 'Meta': [], 'Regen': [], 'res': []}} Get a list of interfaces API Path /captures/list_interfaces Description Retrieve a list of all interfaces with their active status GUI Location n/a Parameters None Example callAPI('GET','/captures/list_interfaces'); 119 Security Analytics Reference Guide Security Analytics 8.1 Output {'errors': [], 'messages': [], 'paging': [], 'result': {'eth1': True}, 'resultCode': 'API_SUCCESS_CODE', 'validationErrors': {'EthInterface': [], 'Meta': [], 'res': []}} Get interfaces API Path /config/interfaces Description Retrieve a list of interfaces on the device GUI Location Menu > Capture > Summary Parameters None Example callAPI('GET','/config/interfaces'); Output {'errors': [], 'messages': [], 'paging': [], 'result': ['eth0', 'eth1', 'eth2', 'eth3'], 'resultCode': 'API_SUCCESS_CODE', 'validationErrors': {'Meta': [], 'res': []}} Get estimate of data captured per interface API Path /capturesummaries/size Description Estimate the amount of the data in bytes captured per interface 120 Security Analytics Reference Guide Security Analytics 8.1 GUI Location Menu > Capture > Summary Output integer Parameters REQ Format Default Valid Inputs Description array aggregate ethX | aggX Ethernet or aggregated ( aggX) interface; aggregate — Combine data from all interfaces interface startTime X integer — <unix epoch> Begin time stopTime X integer — <unix epoch> End time Example callAPI('GET','/capturesummaries/size', array( 'interface' => 'eth3', 'startTime' => '1563768958', 'stopTime' => '1563787718' ) ); Output {'errors': [], 'messages': [], 'paging': [], 'result': '81134616576', 'resultCode': 'API_SUCCESS_CODE', 'validationErrors': {'Meta': [], 'res': []}} Get system uptime API Path /captures/get_uptime Description Retrieve the amount of time since the last reboot GUI Location Menu > Capture > Summary Parameters None 121 Security Analytics Reference Guide Security Analytics 8.1 Example callAPI('GET','/captures/get_uptime'); Output {'errors': [], 'messages': [], 'paging': [], 'result': {'idle': <float>, 'total': <float>}, 'resultCode': 'API_SUCCESS_CODE', 'validationErrors': {'Meta': [], 'res': []}} Calculate earliest time with statistics API Path /capturesummaries/first_time Description Calculate the earliest time that the specified interfaces have capture data GUI Location Menu > Capture > Summary Parameters interfaces REQ Format Default Valid Inputs Description X array — ethX | aggX Ethernet or aggregated interface Example callAPI('GET','/captures/first_time', array( 'interfaces' => array( 'eth1', 'eth3', 'agg0' ) ) ); Get statistics for capture interface API Path /captures/capture_data/<interface> Description Get capture statistics for the specified interface 122 Security Analytics Reference Guide Security Analytics 8.1 GUI Location Menu > Capture > Summary > [interface box] Parameters REQ interface Format Default Valid Inputs Description string eth0 ethX | aggX Interface name; eth0 — All capture interfaces Example callAPI('GET','/captures/capture_data/eth3'); Output {'errors': [], 'messages': [], 'paging': [], 'result': {'interface': 'eth1', 'stats': {'capturing': False, 'capturingCurrent': 0, 'capturingCurrentBits': 0, 'capturingCurrentFiltered': 0, 'capturingCurrentFilteredBits': 0, 'capturingCurrentFilteredPackets': 0, 'capturingCurrentPackets': 0, 'capturingMax': 20, 'capturingMaxBits': 160, 'capturingMaxFiltered': 0, 'capturingMaxFilteredBits': 0, 'capturingMaxFilteredPackets': 0, 'capturingMaxPackets': 0, 'capturingTotal': 60, 'capturingTotalDropped': 0, 'capturingTotalFiltered': 0, 'filtered': False, 'linkSpeed': 10000, 'linkUp': True}}, 'resultCode': 'API_SUCCESS_CODE', 'validationErrors': {'Meta': [], 'res': []}} Get capture summary graph statistics API Path /capturesummaries Description Retrieve a summary of the capture statistics that are displayed on Capture > Summary 123 Security Analytics Reference Guide Security Analytics 8.1 GUI Location Menu > Capture > Summary Output array Parameters REQ interfaces Format Default Valid Inputs array aggregate <capture summaries inputs> Description n Comma-delimited data items from the Capture > Summary graph; n aggregate — Combine data from all capture interfaces startTime X string — <YYYY-MM-DD>T<hh:ii:ss> [+|-]<zz:zz> Begin time stopTime X string — <YYYY-MM-DD>T<hh:ii:ss> [+|-]<zz:zz> End time integer 1 1 | <integer> numPoints Example callAPI('GET','/capturesummaries', array( 'interfaces' => array( 'eth1', 'cpu', 'ram', 'qsd', 'qfto' ), 'startTime' => '2019-11-03T00:00:00-07:00', 'stopTime' => '2019-11-03T06:59:59-07:00', 'numPoints' => 7 ) ); Output {'errors': [], 'messages': [], 124 n 1 — Average for the entire specified timespan n <integer> — Average for each of <integer> timespans within the specified timespan; that is, if the specified timespan is 12 hours, 12 numPoints will return the average for each hour Security Analytics Reference Guide Security Analytics 8.1 'paging': [], 'result': {'cpu': {'capture_interface': False, 'captured': [35.6111, 24.21, 25.8889, 20.8289, 15.0556, 11.2578, 14.3844], 'interval': 257, 'num_points': 7, 'start_time': 1563775200, 'stop_time': 1563776999}, 'eth1': {'capture_interface': True, 'captured': [88151896, 86922752, 86911192, 78986856, 75270800, 50439008, 83647744], 'interval': 257, 'num_points': 7, 'start_time': 1563775200, 'stop_time': 1563776999}, 'qsd': {'capture_interface': False, 'captured': [1, 0, 0, 0, 0, 0, 0], 'interval': 257, 'num_points': 7, 'start_time': 1563775200, 'stop_time': 1563776999}, 'qtfo': {'capture_interface': False, 'captured': [0, 0, 0, 0, 0, 0, 0], 'interval': 257, 'num_points': 7, 'start_time': 1563775200, 'stop_time': 1563776999}, 'ram': {'capture_interface': False, 'captured': [31.54, 31.45, 31.55, 31.53, 31.14, 31.15, 31.15], 'interval': 257, 'num_points': 7, 'start_time': 1563775200, 'stop_time': 1563776999}}, 'resultCode': 'API_SUCCESS_CODE', 'validationErrors': {'Capturesummary': [], 'Meta': [], 'res': []}} 125 Security Analytics Reference Guide Security Analytics 8.1 Get capture summary graph processes API Path /statistics/igraph_options Description Retrieve a list of items from the View menu on the Capture Summary page that are currently being displayed. If the item is not shown, the value is false. GUI Location Menu > Capture > Summary Parameters None Example callAPI('GET','/statistics/igraph_options'); Output {'errors': [], 'messages': [], 'paging': [], 'result': {'aggregate': {'show_igraph': True}, 'cpu': {'show_igraph': True}, 'dequeued': {'show_igraph': True}, 'eth1': {'show_igraph': True}, 'impt': {'show_igraph': True}, 'qfc': {'show_igraph': True}, 'qnf': {'show_igraph': True}, 'ram': {'show_igraph': True}, 'uxnotlive': {'show_igraph': True}, 'uxqueued': {'show_igraph': True}}, 'resultCode': 'API_SUCCESS_CODE', 'validationErrors': {'DisplayOption': [], 'Meta': [], 'res': []}} Get retrospective jobs API Path /retrospective_jobs/retrospective_jobs Description Retrieve a list of reindexing and reprocessing jobs 126 Security Analytics Reference Guide Security Analytics 8.1 GUI Location Menu > Capture > Summary > Actions > Reprocess Parameters REQ Format Default Valid Inputs page integer 1 1–<n> Page to retrieve; first page is 1 limit integer 25 1–100 Number of items per page direction string DESC ASC | DESC sort integer id id | source | stime | etime | command | status | job_start | job_ end | slot_done array — <advanced filter for retrospective Advanced filter attributes jobs> filters Example callAPI('GET','/retrospective_jobs/retrospective_jobs', array( 'page' => 10, 'sort' => 'stime', 'limit' => 20, 'direction' => 'ASC' 'filters' => array( 'all' => array( array( 'key' => 'status', 'comp' => '=', 'value' => 'reprocessing' ) ) ) ) ); Output {'errors': [], 'messages': [], 'paging': {'rj': {'count': 152, 'current': 25, 'limit': 25, 'nextPage': True, 'options': {'order': {'rj.id': 'desc'}}, 'order': {'rj.id': 'desc'}, 'page': 1, 'pageCount': 7, 'paramType': 'named', 'prevPage': False, 'queryScope': None}}, 'result': {'pageCount': 7, 'rows': [{'command': 1, 'etime': '1564008613 ', 127 Description Sort order Sort-by column Security Analytics Reference Guide Security Analytics 8.1 'id': 1952, 'job_end': '1564008615 ', 'job_start': '1564008615 ', 'source': 1, 'status': 100, 'stime': '1564005013 '}, {'command': 1, 'etime': '1564005013 ', 'id': 1951, 'job_end': '1564005013 ', 'job_start': '1564005013 ', 'source': 1, 'status': 100, 'stime': '1564001412 '}, ... {'command': 1, 'etime': '1563919726 ', 'id': 1928, 'job_end': '1563919728 ', 'job_start': '1563919728 ', 'source': 1, 'status': 100, 'stime': '1563916125 '}]}, 'resultCode': 'API_SUCCESS_CODE', 'validationErrors': {'Meta': [], 'res': [], 'rj': []}} Get oldest report time API Path /captures/first_meta_time/<interface> Description Retrieve the first (oldest) time that has report data for the interface GUI Location Menu > Capture > Summary Parameters interface REQ Format Default Valid Inputs Description X string — ethX | aggX Ethernet or aggregated interface Example callAPI('GET','/captures/first_meta_time/eth3'); Output {'errors': [], 'messages': [], 128 Security Analytics Reference Guide Security Analytics 8.1 'paging': [], 'result': 1560800201, 'resultCode': 'API_SUCCESS_CODE', 'validationErrors': {'Meta': [], 'res': []}} Get newest report time API Path /captures/last_meta_time/<interface> Description Retrieve the last (newest) time for report data on the specified interface GUI Location Menu > Capture > Summary Parameters REQ Format Default Valid Inputs Description X string — ethX | aggX Ethernet or aggregated interface interface Example callAPI('GET','/captures/last_meta_time/eth1'); Output {'errors': [], 'messages': [], 'paging': [], 'result': '1563994198', 'resultCode': 'API_SUCCESS_CODE', 'validationErrors': {'EthInterface': [], 'ManagementInterface': [], 'Meta': [], 'res': []}} Get oldest packet time API Path /captures/first_packet_time/<interface> Description Retrieve the time that the first (oldest) packet traversed the interface GUI Location Menu > Capture > Summary 129 Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ Format Default Valid Inputs Description X string — ethX | aggX Ethernet or aggregated interface interface Example callAPI('GET','/captures/first_packet_time/agg1'); Output {'errors': [], 'messages': [], 'paging': [], 'result': 1560800201, 'resultCode': 'API_SUCCESS_CODE', 'validationErrors': {'Meta': [], 'res': []}} Get newest packet time API Path /captures/last_packet_time/<interface> Description Retrieve the last (newest) time for packet data on the specified interface GUI Location Menu > Capture > Summary Parameters interface REQ Format Default Valid Inputs Description X string — ethX | aggX Ethernet or aggregated interface Example callAPI('GET','/captures/last_packet_time/eth4'); Output {'errors': [], 'messages': [], 'paging': [], 'result': 1564008206, 'resultCode': 'API_SUCCESS_CODE', 'validationErrors': {'Meta': [], 'res': []}} 130 Security Analytics Reference Guide Security Analytics 8.1 Start or stop capture API Path /captures/capture/<interface> Description Start or stop capture on the specified interface GUI Location Menu > Capture > Summary Output array Parameters interface REQ Format Default Valid Inputs Description X string — ethX | aggX Ethernet or aggregated interface; eth0 — All interfaces Boolean false true | false stop Example 1 Start capture on eth3 callAPI('POST','/captures/capture/eth3'); Example 2 Stop capture on all interfaces callAPI('POST','/captures/capture/eth0', array( 'stop' => true ) ); Toggle capture summary graph inputs API Path /captures/save_selected_interface/<interface>/<remove> Description Hide or show items on the Capture Summary Graph 131 n true — Stop capture interface(s) n false — Start capture on interface(s) Security Analytics Reference Guide Security Analytics 8.1 GUI Location Menu > Capture > Summary > View > [menu item] Output array Parameters REQ Format Default Valid Inputs interface X string — <capture summaries inputs> remove X integer — 0 | 1 Description Data items on the Capture > Summary graph n 0 — Hide n 1 — Show Example callAPI('POST','/captures/save_selected_interface/<interface>/<remove>'); Create a reprocessing job API Path /retrospective_jobs/save Description Create a reprocessing job; reindexing is included GUI Location Menu > Capture > Summary > Actions > Reprocess Output array Parameters REQ Format Default Valid Inputs Description startTime X datetime — <YYYY-MM-DD>T<hh:ii:ss>[+|-]<zz:zz> Start time endTime X datetime — <YYYY-MM-DD>T<hh:ii:ss>[+|-]<zz:zz> End time Example callAPI('POST','/retrospective_jobs/save', array( 'startTime' = '2019-11-03T21:33:24-07:00', 'endTime' = '2019-11-03T21:43:41-07:00' ) ); 132 Security Analytics Reference Guide Security Analytics 8.1 Delete retrospective jobs API Path /retrospective_jobs/delete Description Delete reindexing or reprocessing jobs GUI Location Menu > Capture > Summary > Actions > Reprocess Output array Parameters REQ Format Default id integer 0 Valid Inputs Description <GET: /retrospective_jobs/retrospective_jobs> Job to delete Example callAPI('POST','/retrospective_jobs/delete', array( 'id' => 2454, 'id' => 2455, 'id' => 2456 ) ); Truncate capture summaries API Path /settings/truncate_capture_summaries Description Delete the capture summary graph data up to the current moment GUI Location Menu > Capture > Summary Output array Parameters None 133 Security Analytics Reference Guide Security Analytics 8.1 Example callAPI('POST','/settings/truncate_capture_summaries'); Aggregate two interfaces API Path /captures/interface_map Description Merge two capture interfaces into one aggregated interface GUI Location Menu > Capture > Summary Output array Parameters REQ Format Default Valid Inputs interface X string — ethX First Ethernet interface to merge interface2 X string — ethX Second Ethernet interface to merge mappedTo X string — aggX Aggregated (merged) Ethernet interface name Example callAPI('POST','/captures/interface_map', array( 'interface' => 'eth3', 'interface2' => 'eth4', 'mappedTo' => 'agg0' ) ); Separate aggregated interface API Path /captures/interface_unmap Description Separate the aggregated interface into its component interfaces GUI Location Menu > Capture > Summary 134 Description Security Analytics Reference Guide Security Analytics 8.1 Output array Parameters REQ Format Default Valid Inputs X string — aggX interface Description Aggregated interface to separate Example callAPI('POST','/captures/interface_unmap', array( 'interface' => 'agg0' ) ); Change interface name API Path /captures/rename_interface/<interface> Description Name or rename an interface GUI Location Menu > Capture > Summary Output array Parameters REQ Format Default Valid Inputs Description interface X string — ethX | aggX Ethernet or aggregated interface alias X string — <UTF-8 characters> Example callAPI('POST','/captures/rename_interface/eth3', array( 'alias' => 'ZONE-3' ) ); Start reindexing or reprocessing API Path /captures/start_reindex_job 135 Display name of interface Security Analytics Reference Guide Security Analytics 8.1 Description Index the classification discards or reprocess data from a specified timespan; retrospective jobs created with this API call are given priority GUI Location n Menu > Capture > Summary > [select timespan] > Actions > Reprocess > New n Menu > Analyze > Summary > Status bar > [warning icon for classification discards] Output array Parameters REQ Format Default Valid Inputs Description startDate X string — <YYYY-MM-DD>T<hh:ii:ss>[+|-]<zz:zz> Start time endDate X string — <YYYY-MM-DD>T<hh:ii:ss>[+|-]<zz:zz> End time type X string — reindex | enrichment Example callAPI('POST','/captures/start_reindex_job', array( 'startDate' => '2019-11-03T00:00:00-07:00', 'endDate' => '2019-11-03T00:03:59-07:00', 'type' => 'reindex' ) ); 136 n reindex — Classification discards are indexed n enrichment — Data is sent back through the dataenrichment process (reprocess) Security Analytics Reference Guide Security Analytics 8.1 Central Manager APIs These APIs are for use only in CMC environments. For functions that also exist on standalone appliances, see the individual APIs. Get the first CMC that is connected to a sensor — NEW API Path /settings/cmc_first Description Sensor Only. Retrieve the first CMC in the list of CMCs connected to the sensor. GUI Location Menu > Settings > Central Management Output {'errors': [], 'messages': [], 'paging': [], 'result': {'applianceId': <integer>, 'cmcIp': '<cmc_ip>'}, 'resultCode': 'API_SUCCESS_CODE', 'validationErrors': {'Meta': [], 'Vpn': [], 'VpnClientConfig': [], 'res': []}} Parameters None Example callAPI('GET','/settings/cmc_first/'); Download authorization key API Path /cmc_settings/download_appliance_key/<id> Description CMC Only. Download the authorization key for a sensor GUI Location n Menu > Settings > Central Management > Sensors > Download Authorization Key n CMC > Dashboard > Manage Sensors > Download Authorization Key Output array 137 Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ Format Default Valid Inputs X integer — <GET: /cmc_settings/appliances> id Example callAPI('GET','/cmc_settings/download_appliance_key/8'); Get IPv6 VPN settings API Path /cmc_settings/cmc_server_ipv6 Description CMC Only. Retrieve the CMC's IPv6 VPN settings GUI Location Menu > Settings > Central Management > Settings Output array Parameters None Example callAPI('GET','/cmc_settings/cmc_server_ipv6'); Get sensor labels API Path /cmc_settings/labels Description CMC Only. Get all of the labels that are currently applied to sensors GUI Location n Menu > Settings > Central Management > Sensors n CMC > Dashboard > Manage Sensors Output array 138 Description Sensor ID Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ Format Default Valid Inputs Description direction string asc asc | desc page integer 0 0–<n> Page to retrieve; first page is 0 limit integer 25 1–100 Number of items per page sort string name name Sort-by column filter string — <label> Sort order Filter name to search for Example callAPI('GET','/cmc_settings/labels'); Get paginated sensor list API Path /cmc_settings/appliances Description CMC Only. Retrieve a paginated list of sensors GUI Location n Menu > Settings > Central Management > Sensors n Dashboard Output array Parameters REQ Format Default Valid Inputs page integer 0 0–<n> Page to retrieve; first page is 0 limit integer 25 1–100 Number of items per page sort string name name | model | connected | capturing | last_selected direction string asc asc | desc filter JSON — label Example callAPI('GET','/cmc_settings/appliances', array( 'page' => 10, 'limit' => 20, 'sort' => 'model', 139 Description Sort-by column Sort direction Advanced filter attribute Security Analytics Reference Guide Security Analytics 8.1 'direction' => 'desc', 'filter' => array( 'all' => array( array( 'key' => 'label', 'comp' => '=', 'value' => '*' ) ) ) ) ); Get sensor information API Path /cmc_settings/appliances/<ids> Description CMC Only. Retrieve information about selected sensors GUI Location CMC > Sensor Selector Output array Parameters REQ Format Default Valid Inputs X array — <GET: /cmc_settings/appliances> ids Description Sensor IDs, comma-delimited Example callAPI('GET','/cmc_settings/appliances/<id-1>,<id-2>,<id-3>'); Get information about connected sensors API Path /cmc_settings/appliances_info Description CMC Only. Retrieve when the sensor was last selected, assuming that it is currently connected GUI Location CMC > Sensor Selector 140 Security Analytics Reference Guide Security Analytics 8.1 Output array Parameters None Example callAPI('GET','/cmc_settings/appliances_info'); Get VPN status API Path /cmc_settings/vpn_running Description CMC Only. Retrieve whether a VPN is operational GUI Location Menu > Settings > Central Management > Settings Output Boolean Parameters None Example callAPI('GET','/cmc_settings/vpn_running'); Get VPN settings API Path /cmc_settings/vpn_server_config Description CMC Only. Retrieve VPN configuration settings GUI Location Menu > Settings > Central Management > Settings Output array 141 Security Analytics Reference Guide Security Analytics 8.1 Parameters None Example callAPI('GET','/cmc_settings/vpn_server_config'); Get repository file list API Path /cmc_upgrades/load_upgrades Description CMC Only. Retrieve a list of upgrade files in the CMC repository GUI Location n Menu > Settings > Central Management > Upgrades n CMC > Dashboard > Upgrade Repository Output array Parameters None Example callAPI('GET','/cmc_upgrades/load_upgrades'); Get all IPv4 VPN settings for a CMC API Path /cmc_settings/cmc_server Description CMC Only. Retrieve the CMC's VPN settings GUI Location Menu > Settings > Central Management > Settings Output array 142 Security Analytics Reference Guide Security Analytics 8.1 Parameters None Example callAPI('GET','/cmc_settings/cmc_server'); Get all VPN settings for a sensor API Path /cmc_settings/cmc_client Description Sensor Only. Retrieve the VPN settings of all CMCs that are connected to a sensor GUI Location Menu > Settings > Central Management Output array Parameters None Example callAPI('GET','/cmc_settings/cmc_client'); Get sensor capture status API Path /captures/aggregate_status?appliances=<IDs> Description CMC Only. Retrieve the capture status on specified sensors GUI Location CMC > Dashboard Output array 143 Security Analytics Reference Guide Security Analytics 8.1 Parameters appliances REQ Format Default Valid Inputs X integer — <GET: /cmc_ settings/appliances> Description Sensor IDs Example callAPI('GET','/captures/aggregate_status?appliances=1,2,4,5,7'); Get confirmation of sensor disconnect API Path /cmc_settings/acknowledge_disconnected_appliances Description CMC Only. After the web UI for the CMC displays an error message about disconnected sensors, this API prevents the CMC's UI from displaying the error message again. GUI Location Any CMC page Output array Parameters None Example callAPI('GET','/cmc_settings/acknowledge_disconnected_appliances'); Push ICDx server settings — NEW API Path /settings/icdx_cmc_comm_push Description CMC Only. Push saved ICDx server settings to all connected sensors. To save server settings on the CMC use POST: /settings/icdx_set_meta_server. GUI Location Menu > Settings > ICDx Metadata Output array 144 Security Analytics Reference Guide Security Analytics 8.1 Parameters log_icdx_password REQ Format Default Valid Inputs Description X string — <UTF-8 characters> Password for the ICDx server Python Example Push ICDx metadata settings — NEW API Path /settings/icdx_cmc_push_meta Description Push saved ICDx metadata attributes to all connected sensors. To save attributes on the CMC use POST: /settings/icdx_save_meta. GUI Location Menu > Settings > ICDx Metadata Parameters None Python Example s.callAPI("POST","/settings/icdx_cmc_push_meta") PHP Example callAPI('GET','/settings/icdx_save_meta'); Add a sensor to the CMC — MODIFIED API Path /cmc_settings/add_appliance Description CMC Only. Add a sensor to the CMC GUI Location n Menu > Settings > Central Management > Sensors n CMC > Dashboard > Manage Sensors Output array 145 Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ Format Valid Inputs Description X string — <GET: /cmc_ settings/appliances> Sensor name users array — <GET: /settings/users> Authorized usernames groups array — <GET: /settings/groups> Authorized remote groups (groups where remote=true) labels array — <GET: /cmc_ settings/labels> | <UTF8 characters> Label(s) to assign to the sensor; you can get existing labels or create new ones mssfix integer 1400 name Default Maximum transmission unit New in Security Analytics 8.1.1 Example callAPI('POST','/cmc_settings/add_appliance', array( 'name' => 'Sensor-00', 'users' => array( 'fred.user', 'liliana.user', 'admin' ), 'groups' => array( 'sysadmins', 'auditors', 'analysts' ), 'mssfix' => 1500 ) ); Edit sensor settings — MODIFIED API Path /cmc_settings/edit_appliance/<id> Description CMC Only. Edit a sensor; the settings that this API passes will overwrite all previous settings GUI Location n Menu > Settings > Central Management > Sensors n CMC > Dashboard > Manage Sensors Output Boolean 146 Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ Format Default Valid Inputs Description id X integer — <GET: /cmc_settings/appliances> Sensor ID name X string — <GET: /cmc_settings/appliances> Sensor name users array — <GET: /settings/users> Authorized usernames groups array — <GET: /settings/groups> Authorized remote groups (groups where remote=true) labels array — <GET: /cmc_settings/labels> mssfix integer 1400 Label(s) to assign to the sensor Maximum transmission unit New in Security Analytics 8.1.1 Example callAPI('POST','/cmc_settings/edit_appliance/4', array( 'name' => 'Sensor-00', 'users' => array( 'george.user', 'ana.user' ), 'groups' => array( 'subanalysts' ), 'labels' => array( 'bldg1', 'bldg5' ) 'mssfix' => 1500 ) ); Download authorization key API Path /cmc_settings/download_appliance_key/<id> Description CMC Only. Download the authorization key for a sensor 147 Security Analytics Reference Guide Security Analytics 8.1 GUI Location n Menu > Settings > Central Management > Sensors > Download Authorization Key n CMC > Dashboard > Manage Sensors > Download Authorization Key Output array Parameters REQ Format Default Valid Inputs id X integer — <GET: /cmc_ settings/appliances> password X string — <UTF-8 characters> PHP Example callAPI('POST','/cmc_settings/download_appliance_key/8' array => ( 'password' => '3nk0dm3' ), <sensor>.tar.gz.gpg ); Python Example s.callAPI("POST","/cmc_settings/download_appliance_key/8", { 'password': '3nk0dm3' }, '<sensor>.tar.gz.gpg' ) Upload authorization key file to sensor API Path /cmc_settings/cmc_client Description Sensor Only. Upload the authorization key file to the sensor GUI Location Menu > Settings > Central Management Output array 148 Description Sensor ID User-supplied password to encrypt the authorization key file. Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ Format Default Valid Inputs Description server X string — <dotted-decimal> file X filename — <filepath>\<sensor>_auth_ key.tar.gz[.gpg] password X string — <UTF-8 characters> Primary IP address for bond0 on the CMC that generated the authorization key file Path to authorization key file. Password to encrypt the authorization key file that was provided on the CMC when downloading the file. Example callAPI('POST','/cmc_settings/cmc_client', array( 'server' => '203.0.113.5', 'file' => 'sensor-00_auth_key.tar.gz', 'password' => '3nk0dm3' ) ) ); Create the IPv6 CMC VPN API Path /cmc_settings/cmc_server_ipv6 Description CMC Only. Set up the CMC's VPN network over IPv6 GUI Location Menu > Settings > Central Management > Settings > Save Output array Parameters REQ Format Default Valid Inputs Description protocol string udp6 tcp6 | udp6 VPN protocol port integer 1194 1–65536 string fdf9:5fdf:968f:54b9::/64 <IPv6>/64 server-ipv6 X Example callAPI('POST','/cmc_settings/cmc_server_ipv6', array( 'protocol' => 'tcp6', 'port' => '1194', 149 VPN port number Unique Local Address (ULA) subnet Security Analytics Reference Guide Security Analytics 8.1 'server-ipv6' => '2026:3004:fa3:20cd::/64', ) ); Add labels to sensors API Path /cmc_settings/add_appliance_labels Description CMC Only. Add labels to one or more sensors GUI Location n Menu > Settings > Central Management > Sensors n CMC > Dashboard > Manage Sensors Output array Parameters REQ Format Default Valid Inputs Description ids X array — <GET: /cmc_settings/appliances> Sensor ID/s labels X array — <GET: /cmc_settings/labels> | <UTF8 characters> Example callAPI('POST','/cmc_settings/add_appliance_labels', array( 'ids' => array( 5, 6, 11 ), 'labels' => array( 'CANADA', '10G-Fiber' ) ) ); Remove labels from sensors API Path /cmc_settings/remove_appliance_labels 150 Label/s to add to the sensor/s Security Analytics Reference Guide Security Analytics 8.1 Description CMC Only. Delete a label from one or more sensors GUI Location n Menu > Settings > Central Management > Sensors n CMC > Dashboard > Manage Sensors Output Boolean Parameters REQ Format Default Valid Inputs Description ids X array — <GET: /cmc_settings/appliances> Sensor ID/s labels X array — <GET: /cmc_settings/labels> Label/s to remove from the appliance/s Example callAPI('POST','/cmc_settings/remove_appliance_labels', array( 'ids' => <id-1>,<id-2> 'labels' => '<label-1>','<label-2>' ) ); Create mount point on multiple sensors API Path /pcap_import_mount_points/aggregate_save?appliance=<sensor_IDs> Description CMC only. Create a mount point on two or more sensors GUI Location [Selected Sensor/s] > Menu > Capture > Import PCAP > Manage Connections > Add New Server Output array 151 Security Analytics Reference Guide Security Analytics 8.1 Parameters Valid Inputs Description — <UTF-8 characters> Display name string nfs nfs | cifs Server protocol string — <hostname> | <dotteddecimal> Server location integer 0 1–65535 string — /<filepath>/ username string — <UTF-8 characters> Required if protocol=cifs password string — <UTF-8 characters> Required if protocol=cifs array null <GET: /cmc_ settings/appliances> alias REQ Format X string protocol serverName X portNum directory applianceIds X X Default Example callAPI('POST','/pcap_import_mount_points/aggregate_save?appliance=3,6,7', array( 'alias' => 'pcap-server', 'serverName' => 'pcaps.domain.com', 'directory' => '/var/public', 'applianceIds' => array( 3, 6, 7 ) ) ); Create the IPv4 CMC VPN API Path /cmc_settings/cmc_server Description CMC Only. Set up the CMC's VPN network over IPv4 GUI Location Menu > Settings > Central Management > Settings > Save Output array 152 Port number Watch-folder path Sensor ID/s Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ Format Default Valid Inputs Description protocol string udp tcp | udp VPN protocol port integer 1194 1–65536 subnet string 10.8.0.0 <dotted-decimal> VPN subnet netmask string 255.255.255.0 <dotted-decimal> VPN netmask VPN port number Example callAPI('POST','/cmc_settings/cmc_server', array( 'protocol' => 'tcp', 'port' => '1195', 'subnet' => '10.111.0.0', 'netmask' => '255.255.0.0' ) ); Delete sensors API Path /cmc_settings/delete_appliances/<ids> Description CMC Only. Delete the sensor(s) from the CMC; this API does not inform the sensors that they have been disconnected GUI Location n Menu > Settings > Central Management > Sensors n CMC > Dashboard > Manage Sensors Output Boolean Parameters REQ Format Default Valid Inputs X string — <GET: /cmc_settings/appliances> ids Description Sensor IDs Example callAPI('POST','/cmc_settings/delete_appliances/<id-1>,<id-2>,<id-3>'); 153 Security Analytics Reference Guide Security Analytics 8.1 Save the sensors' last-selected status API Path /central_manager/select?appliance=<sensor_IDs> Description CMC Only. Save the last-selected status of specified sensors GUI Location CMC > Sensor Selector Output ApiResultCode Parameters REQ Format Default Valid Inputs X array — <GET: /cmc_settings/appliances> ids Example callAPI('POST','/central_manager/select?appliance=2,4,9', array( 'ids' => array( 2, 4, 9 ) ) ); Remove a CMC from the sensor API Path /cmc_settings/cmc_client_remove/<id> Description Sensor Only. Remove a CMC from the sensor. GUI Location Menu > Settings > Central Management Output array 154 Description Sensor IDs Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ Format Default Valid Inputs X integer — <GET: /cmc_settings/cmc_client> id Description CMC ID Example callAPI('POST','/cmc_settings/cmc_client_remove/<id>'); Reset the VPN API Path /cmc_settings/reset_vpn_settings Description CMC Only. Reset the VPN to default settings, thereby deleting all sensor connections. This API does not inform the sensors that they have been disconnected. GUI Location Menu > Settings > Central Management > Settings > Reset Settings Output ApiResultCode Parameters None Example callAPI('POST','/cmc_settings/reset_vpn_settings'); Download file to upgrade repository API Path /upgrades/start_download/<serverId>/<filename> Description CMC Only. Begin downloading an upgrade file from an upgrade server to the CMC's upgrade repository GUI Location n Menu > Settings > Central Management > Upgrades n CMC > Dashboard > Upgrade Repository 155 Security Analytics Reference Guide Security Analytics 8.1 Output array Parameters REQ Format Default Valid Inputs Description serverId X integer — <GET: /upgrades/list> filename X string — <GET: /upgrades/manifest> Upgrade server ID Name of upgrade file Example callAPI('POST','start_download/2/atpsa-8.1.1-45000-x86_64-DVD.tar'); Initiate a push-upgrade to sensors API Path /cmc_settings/upgrade_appliances Description CMC Only. Initiates a push-upgrade from a CMC to a sensor. GUI Location n Menu > Settings > Central Management > Sensors n CMC > Dashboard > Manage Sensors Output integer Parameters REQ Format Default Valid Inputs ids X array — <GET: /cmc_ settings/appliances> filename X string — <GET: /cmc_upgrades/load_ upgrades> Example callAPI('POST','/cmc_settings/upgrade_appliances', array( 'ids' => array( <id-1>, <id-2>, <id-3> ) 'filename' => 'atpsa-8.1.1-56488-x86_64-DVD.tar' ) ); 156 Description Sensor IDs Name of the upgrade file Security Analytics Reference Guide Security Analytics 8.1 Delete an upgrade file from the repository API Path /cmc_upgrades/upgrade_delete Description CMC Only. Delete an upgrade file from the CMC repository GUI Location n Menu > Settings > Central Management > Upgrades n CMC > Dashboard > Upgrade Repository Output ApiResultCode Parameters REQ Format Default Valid Inputs X string — <GET: /cmc_upgrades/load_ upgrades> file Example callAPI('POST','/cmc_upgrades/upgrade_delete', array( 'file' => 'atpsa-8.1.1-56488-x86_64-DVD.tar' ) ); 157 Description Name of the upgrade file Security Analytics Reference Guide Security Analytics 8.1 Data Enrichment APIs Get the GIN diagnostic test results API Path /health/gin_test Description Run the GIN diagnostic test and get the results GUI Location Menu > Settings > Data Enrichment > Blue Coat File Reputation Service > Test Service Output ApiResultCode Parameters None PHP Example callAPI('GET','/health/gin_test'); Python Example s.callAPI("GET","/health/gin_test") Download GIN diagnostic test results API Path /health/gindiag_download Description Download the PCAPs and log from the GIN test GUI Location Runs the gindiag.sh script Output ApiResultCode Parameters None PHP Example callAPI('GET','/health/gindiag_download',); 158 Security Analytics Reference Guide Security Analytics 8.1 Python Example s.callAPI("GET","/health/gindiag_download",) Download the current YARA file API Path /integration_providers/yara_download Description Download the current YARA rules file GUI Location Menu > Settings > Data Enrichment > YARA File Manager Output ApiResultCode Parameters None PHP Example callAPI('GET','/integration_providers/yara_download', 'rules.yar' ); Python Example s.callAPI("GET","/integration_providers/yara_download", "rules.yar" ) Get the data-enrichment profile API Path /settings/system_services_profile Description Retrieve the current data-enrichment (system-services) profile GUI Location Menu > Settings > Data Enrichment > Data Enrichment Profiles Output array 159 Security Analytics Reference Guide Security Analytics 8.1 Parameters None Example callAPI('GET','/settings/system_services_profile'); Get enrichment providers API Path /integration_providers/providers Description Retrieve a paged set of enrichment provider records GUI Location Menu > Settings > Data Enrichment Output array Parameters REQ Format Default Valid Inputs Description page integer 1 1–<n> Page number to retrieve; first page is 1 limit integer 25 1–100 Number of records per page sort string name name Sort-by column string asc asc | desc direction 160 Sort order Security Analytics Reference Guide REQ edit_type Format string Security Analytics 8.1 Default all Valid Inputs all | none | data | restricted | malware | internal | local | threatexplorer Example callAPI('GET','/integration_providers/providers', array( 'page' => 10, 'limit' => 20, 'sort' => 'name', 'direction' => 'asc', 'edit_type' => 'malware' ) ); Get all enrichment providers API Path /integration_providers/all_providers Description Retrieve a list of all enrichment providers GUI Location Menu > Settings > Data Enrichment Output array Parameters None 161 Description Retrieve enrichment providers of the specified 'edit type': n all — Integration providers, SEP, MATI n none — DeepSight n data — EDR pivot n restricted — Third-party ondemand reputation providers n malware — Analysis providers n internal — Intelligence Services n local — Local File Analysis n threatexplorer — Threat Explorer pivot (new) Security Analytics Reference Guide Security Analytics 8.1 Example callAPI('GET','/integration_providers/all_providers'); Test Malware Analysis connectivity API Path /integration_providers/test_settings Description Test the connection to Malware Analysis GUI Location Menu > Settings > Data Enrichment > Test Connection button in Edit Malware Analysis Appliance dialog Output array Parameters REQ Format Default Valid Inputs uuid X UUID — <GET: /integration_ providers/norman> Array of Malware Analysis UUID and name keys. name X string — <UTF-8 characters> User-defined name for the Malware Analysis appliance. Example callAPI('GET','/integration_providers/test_settings' array( 'uuid' => <UUID>, 'name' => 'MAA-200' ) ); Get Malware Analysis task report API Path /reputations/malware/<serverUuid>/<taskId> Description Retrieve a task report from Malware Analysis 162 Description Security Analytics Reference Guide Security Analytics 8.1 GUI Location n SA — Menu > Analyze > Alerts > List > [malware analysis alert] > Go to MAA n CA — Malware Analysis tab n MA — Analysis Center > View All Tasks > [task id] Output array or error code Parameters REQ Format Default Valid Inputs serverUuid X integer — <GET: /integration_ providers/norman> taskId X integer — <GET: /alerts> Example callAPI('GET','/reputations/malware/<serverUuid>/44355'); Get state of local file analysis providers API Path /integration_providers/local_file_analysis Description Retrieve state information (enabled, disabled) for local file analysis providers GUI Location Menu > Settings > Data Enrichment Output array Parameters None Example callAPI('GET','/integration_providers/local_file_analysis'); 163 Description Malware Analysis identifier Task identifier on Malware Analysis Security Analytics Reference Guide Security Analytics 8.1 Get a data-enrichment filter API Path /integration_providers/derp_filters Description Retrieve the data-enrichment file-type filters for a provide GUI Location Menu > Settings > Data Enrichment > [edit provider] > Data Enrichment File Types Output array Parameters providers IntegrationProvider derp_filters REQ Format Default Valid Inputs X array IntegrationProvider IntegrationProvider X array derp_filters derp_filters array tonic_filter clam_av | cp_mover | cuckoo | file_ reputation_service | fireeye | ftp_mover | icap_cas | jsunpack | lastline | local_ hash_reputation | noop | norman | scp_ mover | tiscale | virustotal | yara | tonic_filter Example callAPI('GET','/integration_providers/derp_filters', array( 'providers' = > array( 'IntegrationProvider' => array( 'derp_filters' => array( 'ftp_mover', 'file_reputation_service' ) ) 164 Description Internal name for the file/hash provider or tonic_filter (default data-enrichment filter) n cp_mover — Local File Mover n local_hash_ reputation — Custom Hash List n noop — Calculate and Store Hashes n norman — Malware Analysis Security Analytics Reference Guide Security Analytics 8.1 ) ) ); Get custom Web Reputation Service update location API Path /web_pulse/location Description Retrieves the custom Web Reputation Service update location GUI Location Menu > Settings > Data Enrichment > Web Reputation Service Update Location Output array Parameters None Example callAPI('GET','/web_pulse/location'); Get third-party integration-provider types API Path /integration_providers/types Description Retrieve all types of third-party integration providers GUI Location Menu > Settings > Data Enrichment > Third-Party Integration Providers Output array Parameters None Example callAPI('GET','/integration_providers/types'); 165 Security Analytics Reference Guide Security Analytics 8.1 Get an artifact's reputation API Path /reputations/artifact/<artifactId> Description Retrieve an artifact's reputation from the specified provider GUI Location Menu > Analyze > Extractions > [artifact entry] > Reputation button Output array Parameters REQ artifactId Format Default Valid Inputs Description integer — <GET: /artifacts/artifacts> provider UUID null null | <GET: /integration_ providers/all_providers> Integration provider UUID; use null to retrieve all providers artifactField string null <advanced filter attributes> Field for the reputation lookup; leave blank for all fields X Artifact ID Example callAPI('GET','/reputations/artifact/<artifactId>', array( 'provider' => '<provider_UUID>', 'artifactField' => 'ip_source' ) ); Get on-demand reputation API Path /reputations/reputation/<provider>/<value> Description Retrieve reputation results from the providers for a specified value GUI Location n Menu > Analyze > Summary > [report value] > View Reputation Information > [on-demand reputation provider] 166 Security Analytics Reference Guide Security Analytics 8.1 n Menu > Analyze > Reports > [report value] > View Reputation Information > [on-demand reputation provider] n Menu > Analyze > Extractions > [artifact field] > View Reputation Information > [on-demand reputation provider] n Menu > Analyze > Geolocation > [ip address] > View Reputation Information > [on-demand reputation provider] Output array Parameters REQ Format Default Valid Inputs provider X UUID — <GET: /integration_ providers/all_providers> value X URL encoding — <URL> | <hash> | <ip_ address> Description UUID of the provider to query URL-encoded value to pass to the provider Example callAPI('GET','/reputations/reputation/529e0f20-9834-406b-b5ee-53e41e1d64a3/203.0.113.5'); Get Malware Analysis entries API Path /integration_providers/norman Description Retrieve the configuration data for the Malware Analysis entries GUI Location Menu > Settings > Data Enrichment > Symantec Analysis Providers > Malware Analysis Appliance Output array Parameters None Example callAPI('GET','/integration_providers/norman'); 167 Security Analytics Reference Guide Security Analytics 8.1 Get Login Correlation Service settings API Path /settings/adlistener Description Retrieve the allowed IP addresses and whether Allow All Agent IPs is true GUI Location Menu > Settings > Security > Login Correlation Service Output array Parameters None Example callAPI('GET','/settings/adlistener'); Get domain filters API Path /integration_providers/domain_filters Description Retrieve all domains that are excluded from data-enrichment lookup GUI Location Menu > Settings > Data Enrichment > Exclude from Lookup > Domains Output array Parameters None Example callAPI('GET','/integration_providers/domain_filters'); 168 Security Analytics Reference Guide Security Analytics 8.1 Get IP filters API Path /integration_providers/ip_filters Description Retrieve all IP subnets that are excluded from data-enrichment lookup GUI Location Menu > Settings > Data Enrichment > Exclude from Lookup > IP Subnets Output array Parameters None Example callAPI('GET','/integration_providers/ip_filters'); Enable the Assemble Partial Content feature Upload the modified YARA file API Path /integration_providers/yara_upload Description Upload a modified YARA rules file GUI Location Menu > Settings > Data Enrichment > YARA File Manager Output ApiResultCode Parameters None PHP Example callAPI('POST','/integration_providers/yara_upload', 'rules.yar' ); 169 Security Analytics Reference Guide Security Analytics 8.1 Python Example s.callAPI("POST","/integration_providers/yara_upload", "rules.yar" ) Restore the default YARA file API Path /integration_providers/yara_restore Description Restore the YARA rule file to its default state GUI Location Menu > Settings > Data Enrichment > YARA File Manager Output ApiResultCode Parameters None PHP Example callAPI('POST','/integration_providers/yara_restore'); Python Example s.callAPI("POST","/integration_providers/yara_restore") Select the data-enrichment profile API Path /settings/system_services_profile Description Select the current data-enrichment (system services) profile GUI Location Menu > Settings > Data Enrichment > Data Enrichment Profiles Output array 170 Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ Format Default Valid Inputs X array () 100 | 90 | 10 settings Description Data enrichment profile to select: n 100 — Full Data Enrichment with Anomaly Detection n 90 — Full Data Enrichment (No Anomaly Detection) n 10 — Packets Only Example callAPI('POST','/settings/system_services_profile', array => ( 'settings' => 90 ); Enable or disable local file analysis providers API Path /integration_providers/local_file_analysis Description Activate or deactivate a local file analysis provider GUI Location Menu > Settings > Data Enrichment > Local File Analysis > [provider entry] Output ApiResultCode Parameters localFileAnalysis active REQ Format Default Valid Inputs X array — <GET: /integration_ providers/local_file_analysis> Boolean 0 or false false | true 0 | 1 Example callAPI('POST','/integration_providers/local_file_analysis', array( 'localFileAnalysis => array( 'clam_av' => array( 171 Description Names of local file analysis providers n False or 0 — Deactivate n True or 1 — Activate Security Analytics Reference Guide Security Analytics 8.1 'active' => 1 ), 'yara' => array( 'active' => false ) ) ) ); Configure custom Web Reputation Service update location API Path /web_pulse/location Description Configure the custom Web Reputation Service update location GUI Location Menu > Settings > Data Enrichment > Web Reputation Service Update Location Output Boolean Parameters REQ interval Format Default Valid Inputs Description integer 300 1–<n> Boolean true true | false url string — <URL> username string — <UTF-8 characters> Username to access the custom update location password string — <UTF-8 characters> Password to access the custom update location custom Example callAPI('POST','/web_pulse/location', array( 'interval' => 900, 'custom' => true, 'url' => 'https://custom.update.com/updates', 'username' => '<username>', 'password' => '<password>' ) ); 172 Number of seconds between updates True = Use the custom update location URL of the custom update location Security Analytics Reference Guide Security Analytics 8.1 Trigger a manual Web Reputation Service update API Path /web_pulse/update Description Trigger an update of the Web Reputation Service database GUI Location Menu > Settings > Data Enrichment > Web Reputation Service Update Location > Update button Output Boolean Parameters None Example callAPI('POST','/web_pulse/update'); Configure an integration provider API Path /integration_providers/save Description Create or edit an integration provider GUI Location Menu > Settings > Data Enrichment > Third-Party Integration Providers Output string Parameters REQ uuid Format Default Valid Inputs UUID | null null null | <GET: /integration_ providers/all_providers> 173 Description n Create new — Use null n Edit entry — UUID required Security Analytics Reference Guide Security Analytics 8.1 REQ Format Default Valid Inputs X string — <UTF-8 characters> | <GET: /integration_providers/all_ providers> name username X string — <UTF-8 characters> address X string — <dotted-decimal> key X string — <hex> Description n Create new — Name required n Edit entry — New name Administrator-level account on the Malware Analysis appliance IP address of the Malware Analysis appliance API key with admin-level privileges, generated on the Malware Analysis appliance Example callAPI( 'POST', '/integration_providers/norman', array( 'uuid' => null, 'name' => 'MAA-03', 'username' => 'maa_admin', 'address' => '203.0.113.5', 'key' => '<API_key_from_MA>' ) ); Delete a Malware Analysis appliance API Path /integration_providers/norman_delete/<uuid> Description Delete the specified Malware Analysis entry GUI Location Menu > Settings > Data Enrichment > Malware Analysis Output array Parameters uuid REQ Format Default Valid Inputs X UUID — <GET: /integration_ providers/norman> Example callAPI('POST','/integration_providers/delete/<provider_UUID>'); 174 Description UUID of the Malware Analysis entry Security Analytics Reference Guide Security Analytics 8.1 Activate or deactivate an enrichment provider API Path /integration_providers/toggle/<uuid> Description Activate or deactivate an enrichment provider GUI Location Menu > Settings > Data Enrichment > [provider entry] Output array Parameters uuid REQ Format Default Valid Inputs X UUID — <GET: /integration_providers/all_ providers> Boolean true true | false active Example callAPI('POST','/integration_providers/toggle/<provider_UUID>', array( 'active' => false ) ); Configure domain filters API Path /integration_providers/domain_filters Description Specify domains to be excluded from data-enrichment lookup GUI Location Menu > Settings > Data Enrichment > Exclude from Lookup > Domains Output ApiResultCode 175 Description UUID of enrichment provider n true — Activate n false — Deactivate Security Analytics Reference Guide Security Analytics 8.1 Parameters domainFilters REQ Format Default Valid Inputs X string — <domain> <domain> <domain> Description List of domains, each on its own line Example callAPI('POST','/integration_providers/domainFilters', *.soleranetworks.com *.bluecoat.com *.symantec.com ); Configure IP filters API Path /integration_providers/ip_filters Description Specify IP addresses to be excluded from data-enrichment lookup; this list completely overwrites the previous list GUI Location Menu > Settings > Data Enrichment > Exclude from Lookup > IP Subnets Output ApiResultCode Parameters ipFilters REQ Format Default Valid Inputs X string — <[cidr]ip_address> <[cidr]ip_address> <[cidr]ip_address> Example callAPI('POST','/integration_providers/ipFilters', 127/8 10/8 172.16/12 169.254/16 192.168/16 ); Set Login Correlation Service IPs API Path /settings/adlistener 176 Description IP addresses, each on its own line; CIDR notation is permitted: 192.168/16 Security Analytics Reference Guide Security Analytics 8.1 Description Configure the allowed IPs for the Login Correlation Service GUI Location Menu > Settings > Security > Login Correlation Service > LCS Agent IP Output ApiResultCode Parameters REQ allowAllIp ipList X Format Default Boolean array Valid Inputs — — true | false <dotted-decimal>,<dotteddecimal> Example callAPI('POST','/settings/adlistener', array( 'allowAllIp' => false, 'ipList' => array( '192.0.2.200', '203.0.113.5', '198.51.100.98' ) ) ); 177 Description n true = Allow all IPs and ignore ipList n false = Allow only IPs in ipList Comma-delimited array of LCS agent IPs to allow Security Analytics Reference Guide Security Analytics 8.1 Date/Time APIs Get date and time settings API Path /settings/time Description Retrieve the date and time settings GUI Location Menu > Settings > Date/Time Output array Parameters None Example callAPI('GET','/settings/time'); Get Greenwich Mean Time offsets API Path /settings/gmt_offsets Description Retrieve offset transition timestamps GUI Location n/a Output array Parameters None Example callAPI('GET','/settings/gmt_offsets'); 178 Security Analytics Reference Guide Security Analytics 8.1 Set the appliance time API Path /settings/time Description Set the time for the appliance GUI Location Menu > Settings > Date/Time Output ApiResultCode Parameters REQ Format Default Valid Inputs X string — <YYYY-MM-DD>T<hh:ii:ss> time Description 24-hour time to set Example callAPI('POST','/settings/time', array( 'time' => '2019-11-03T08:30:00' ) ); Set the time zone API Path /settings/timezone Description Set the time zone for the appliance; changing this setting will reboot the appliance. GUI Location Menu > Settings > Date/Time Output ApiResultCode Parameters timezone REQ Format Default Valid Inputs X string — <IANA tz database> 179 Description Time zone to set Security Analytics Reference Guide Security Analytics 8.1 Example callAPI('POST','/settings/timezone', array( 'timezone' => 'America/Argentina/Cordoba' ) ); Configure NTP API Path /settings/ntp Description Configure Network Time Protocol settings GUI Location Menu > Settings > Date/Time > Network Time Protocol Output ApiResultCode Parameters enable REQ Format Default Valid Inputs X Boolean — true | false servers X array () ntp_address X string — <dotted-decimal> Boolean 0 0| 1 ntp_encrypt password generateKeys Description n True — Enable NTP n False — Disable NTP Array of up to 3 NTP servers; array contains ntp_address and ntp_encrypt string — <UTF8 characters> Boolean false true | false IP address of NTP server Whether to use Autokey encryption n 0 — Do not use Autokey n 1 — Use Autokey Group key password; required if ntp_ encrypt=1 n True — Generate NTP host keys n False — Do not generate keys serverFile1 file null <filepath> Path to primary group key file; valid only if generateKeys=false serverFile2 file null <filepath> Path to secondary group key file; valid only if generateKeys=false 180 Security Analytics Reference Guide REQ serverFile3 Security Analytics 8.1 Format Default Valid Inputs Description file null <filepath> Path to tertiary group key file; valid only if generateKeys=false Example 1 Enable NTP and specify three servers callAPI('POST','/settings/ntp', array( 'enable' => true, 'servers' => array( array( 'ntp_address' 'ntp_encrypt' ) array( 'ntp_address' 'ntp_encrypt' ) array( 'ntp_address' 'ntp_encrypt' ) ), ) ); => '203.0.113.5', => 0 => '203.0.113.6', => 0 => '203.0.113.7', => 0 Example 2 Enable NTP encryption and upload the key files callAPI('POST','/settings/ntp', array( 'servers' => array( array( 'ntp_address' => '203.0.113.5', 'ntp_encrypt' => 1 ) array( 'ntp_address' => '203.0.113.6', 'ntp_encrypt' => 1 ) array( 'ntp_address' => '203.0.113.7', 'ntp_encrypt' => 1 ) ), 'password' => '33aks3snTp@*', 'generateKeys' => false, 'serverFile1' => 'ntpkey_iff_www.trustedserver1.com', 'serverFile2' => 'ntpkey_iff_www.trustedserver2.com', 'serverFile3' => 'ntpkey_iff_www.trustedserver3.com' ) ); 181 Security Analytics Reference Guide Security Analytics 8.1 Drive-Space Management APIs Get saved extractions API Path /saved Description Retrieve a list of saved extractions GUI Location Menu > Analyze > Saved Extractions Output array Parameters REQ Format Default Valid Inputs page integer 1 1–<n> Page to retrieve; first page is 1 pageSize integer 25 1–100 Number of items per page sort string start start | end | name | percent | status direction string desc asc | desc Example callAPI('GET','/saved', array( 'page' => 10, 'pageSize' => 20, 'sort' => 'status', 'direction' => 'asc' ) ); Get URL to a saved extraction API Path /saved/url/<id> Description Generate a URL to access a saved extraction GUI Location Menu > Analyze > Saved Extractions > View extraction icon 182 Description Sort-by field Sort direction Security Analytics Reference Guide Security Analytics 8.1 Output string Parameters REQ id X Format Default string Valid Inputs — <GET: /saved> Example callAPI('GET','/saved/url/255'); Get data retention-settings API Path /settings/data_retention Description Retrieve data-retention settings GUI Location About > Data-Retention Settings Output array Parameters None Example callAPI('GET','/settings/data_retention'); Get home-drive size API Path /home_size Description Retrieve disk space and inode usage of /home GUI Location Menu > Analyze > Saved Extractions 183 Description ID of the saved result Security Analytics Reference Guide Security Analytics 8.1 Output array Parameters None Example callAPI('GET','/home_size'); Delete a saved extraction API Path /saved/delete Description Delete a saved extraction GUI Location Menu > Analyze > Saved Extractions Output ApiResultCode Parameters REQ Format Default Valid Inputs X array — <GET: /saved> ids Example callAPI('POST','/saved/delete', array( 'ids' => array( '<ID-1>', '<ID-2>', '<ID-3>' ) ) ); Configure data-retention settings API Path /settings/data_retention Description Configure data-retention settings 184 Description IDs of results to delete Security Analytics Reference Guide Security Analytics 8.1 GUI Location About > Data-Retention Settings Output ApiResultCode Parameters REQ Format Default Valid Inputs Description integer 0 0–12 Number of months that Capture Summary Chart data is retained. Boolean false true | false True — Enable time-based data deletion time_deletion_limit_days integer 0 0–<n> Number of days to retain data time_deletion_limit_hours string/integer 0 0–<n> Number of hours to retain data Boolean false true | false True — Delete saved reports and artifacts summary_life time_deletion_enabled time_deletion_artifacts Example callAPI('POST','/settings/data_retention', array( 'summary_life' => 6, 'time_deletion_enabled' => true, 'time_deletion_limit_days' => 180, 'time_deletion_limit_hours' => 0, 'time_deletion_artifacts' => true ) ); 185 Security Analytics Reference Guide Security Analytics 8.1 Extractor APIs Get HTTP proxy assembly state — NEW API Path /settings/extractor_enable_partial_content_reconstruction Description Retrieve the state of proxy data reconstruction GUI Location Menu > Settings > System > Enable proxy data Parameters None PHP Example callAPI('GET','/settings/extractor_enable_proxy_data_reconstruction'); Python Example s.callAPI("GET","/settings/extractor_enable_proxy_data_reconstruction") Output 'result': {'ExtractorSetting': {'proxy_data_reconstruction': [0|1]}}, 'resultCode': 'API_SUCCESS_CODE', Initiate extraction — MODIFIED The output for this API has changed. See Extractions API Changes for more information. API Path /artifacts/artifacts Description Initiate artifact extraction on the specified, filtered timespan. GUI Location Menu > Analyze > Summary > Extractions 186 Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ Format Default Valid Inputs X string | integer — <identity path> page integer 1 1–<n> Page to request; first page is 1 pageSize integer 25 1–100 Number of artifacts per page filters array — <advanced filter array> sort string date sortDirection string ASC ASC | DESC restart Boolean false true | false True — Run the extraction again countOnly Boolean false true | false True — Get only the number (count) of artifacts mediapanel string | null null small | medium | large | null identityPath Description One of several identifying values Advanced filter attributes date | source | type | Sort-by column; sender, recipient, size | sender | recipient and subject are valid only for | subject email artifacts Sort order Size of thumbnails: n small — 50 pixels n medium — 100 pixels n large — 150 pixels n null — Do not generate thumbnails PHP Example callAPI('GET','/artifacts/artifacts', array( 'identityPath' => '/timespan/2019-09-17T14:25:00-07:00_2019-09-17T14:30:00-07:00', 'page' => 1, 'pageSize' => 20, 'filters' => array( 'all' => array( array( 'key' => 'ip_address', 'comp' => '=', 'value' => '203.0.113.5' ), array( 'any' => array( array( 'key' => 'port', 'comp' => '=', 'value' => 80 ), array( 'key' => 'keyword', 'comp' => '~', 'value' => 'symantec' ) ) ) ), 187 Security Analytics Reference Guide Security Analytics 8.1 'sort' => 'date' ) ) ); Python Example s.callAPI("GET","/artifacts/artifacts", { 'identityPath': '/timespan/2019-09-17T14:25:00-07:00_2019-09-17T14:30:00-07:00', 'page': 1, 'pageSize': 20, 'filters': { 'all': { { 'key': 'ip_address', 'comp': '=', 'value': '203.0.113.5' }, { 'any': { { 'key': 'port', 'comp': '=', 'value': 80 }, { 'key': 'keyword', 'comp': '~', 'value': 'symantec' } } } }, 'sort': 'date' } } ) Initial Output {'artifact_search_id': <integer>, 'background': [True|False], 'field_counts': {'file_extension': [], 'file_type': []}, 'histogram': {'data': [{'columns': [0], 'extra': {'end_time': <epoch>}, 'time': <epoch>}], 'meta': {'columns': [{'has_total': ['true'|'false'], 'text': 'Artifacts', 'type': 'magnitude'}], 'data_type': {'text': 'Artifacts', 'type': 'magnitude'}}, 'total': [0]}, 'killed': [True|False], 'maxpage': 0, 'numFilteredArtifacts': 0, 'numResults': 0, 'percentcomplete': '0', 'search_status': 'extractor.status.waiting', 'sorted_artifacts': [], 'timeDeleted': [True|False], 'time_place': <epoch>} 188 Security Analytics Reference Guide Security Analytics 8.1 This API does not return data after the first API request. You must poll the appliance in the meantime to incrementally retrieve the data. See "Using Polling with the APIs" on page 415 for more information. Completed Output 'result': {'artifact_search_id': <integer>, 'background': [True|False], 'field_counts': {'file_extension': {'7z': [1], 'apk': [1], ... 'xml': [2], 'zip': [5]}, 'file_type': {'application/bat': [0, 3], 'application/email': [53, 53], ... 'video/x-ms-wmv': [18, 0], 'video/x-msvideo': [0, 1]}}, 'histogram': {'data': [{'columns': [<integer>], 'extra': {'end_time': <epoch>}, 'time': <epoch>}, ... {'columns': [<integer>], 'extra': {'end_time': <epoch>}, 'time': <epoch>}], 'meta': {'columns': [{'has_total': 'true', 'text': 'Artifacts', 'type': 'magnitude'}], 'data_type': {'text': 'Artifacts', 'type': 'magnitude'}}, 'total': [<integer>]}, 'killed': [True|False], 'maxpage': <integer>, 'numFilteredArtifacts': <integer>, 'numResults': <integer>, 'percentcomplete': '100', 'search_status': 'extractor.status.finished', 'sorted_artifacts': [{'Artifact': {'appliance_id': <integer>, 'artifact_search_id': <integer>, 'capture_end_nanoseconds': <integer>, 'capture_end_time': <epoch>, 'capture_start_nanoseconds': <integer>, 'capture_start_time': <epoch>, 'derived_type': '<presented MIME type>', 'destination_ip': '<ip>', 'destination_port': <port>, 'extension': '<ext>', 'filename': '/home/apache/artifacts/<extraction_ id>/<hostname>.dscapture.net_<YYYY-MM-DD>T<hh.mm.ss-zzzz>_<initiator_ip><initiator_port>_<responder_ip>-<responder_port>_<filename>.<ext>', 'filesize': <integer>, 'flow_id': <integer>, 'fuzzy': '<fuzzy_hash>', 'height': <integer>, 'host': '<hostname>', 'hw_ratio': <integer>, 'icon': '<string>', 'id': <integer>, 'magic_type': '<detected_MIME_type>', 'md5': '<md5_hash>', 'meta_info': {'filename': '', 189 Security Analytics Reference Guide Security Analytics 8.1 'response_code': <integer>, 'response_headers': 'HTTP/1.1 ' '<response code>' 'OK\r\n' 'Server: ' 'Apache\r\n' 'ETag: ' '<hex>:<epoch>\r\n' 'Last-Modified: ' '<day>, ' '<DD-mmm-YYYY> ' '<hh:ii:ss> ' 'GMT\r\n' 'Accept-Ranges: ' 'bytes\r\n' 'Content-Length: ' '<integer>\r\n' 'Content-Type: ' '<MIME_type>\r\n' 'Date: ' '<day>, ' '<DD-mmm-YYYY> ' '<hh:ii:ss> ' 'GMT\r\n' 'Connection: ' 'Keep-Alive\r\n' '\r\n'}, 'mime_type': '<presented_MIME_type>', 'pcap_path': '/timespan/<YYYY-MM-DD>T<hh.mm.ss-zzzz>_<YYYY-MMDD>T<hh.mm.ss-zzzz>/flow_id_packet/<integer>', 'protocol': '<protocol>', 'referer': [None|<URL>], 'remote_artifact_id': <integer>, 'session_id': <extraction_ID>, 'sha1': '<SHA1_hash>', 'sha256': '<SHA256_hash>', 'source_ip': '<ip>', 'source_port': <port>, 'title': '<filename>', 'wh_ratio': <integer>, 'width': <integer>}}, ... 'timeDeleted': False, 'time_place': <epoch>}, 'resultCode': 'API_SUCCESS_CODE', Get a list of all extractions API Path /deepsee/all_extractions Description Retrieve a list of all extractions on the Extraction Status page. 190 Security Analytics Reference Guide Security Analytics 8.1 GUI Location Menu > Analyze > Extraction Status Parameters None PHP Example callAPI('GET','/deepsee/all_extractions',); Python Example s.callAPI("GET","/deepsee/all_extractions") Output 'result': {'rows': [{'appliance_ids': '', 'as_status': '<status>', 'bytes_read': <integer>, 'db_size': <size>, 'disk_size': <integer>, 'end': 'YYYY-MM-DD hh:ii:ss.000000', 'id': <integer>, 'name': '<name>', 'pcap': '/pfs/flows/timespan/YYYY-MM-DDThh:ii:ss-zz:zz_YYYY-MMDDThh:ii:ss-zz:zz/data.pcapng', 'percent': <integer>, 'results': <integer>, 'start': 'YYYY-MM-DD hh:ii:ss.999999', 'status': '<status>', 'user_name': '<username>'}]} Get paginated list of extractions API Path /deepsee/status Description Retrieve a paginated list of the fields on the Extraction Status page. GUI Location Menu > Analyze > Extraction Status Parameters REQ Format Default Valid Inputs page integer 1 1–<n> Number of pages to retrieve; first page is 1. pageSize integer 25 1–100 Number of entries per page 191 Description Security Analytics Reference Guide REQ Security Analytics 8.1 Format Default Valid Inputs sort string start start | name | status | percent | created_by | id direction string DESC ASC | DESC Description Sort-by column Sort order PHP Example callAPI('GET','/deepsee/status', array( 'page' => 10, 'pageSize' => 20, 'sort' => 'percent', 'sortDirection' => 'ASC' ) ); Python Example s.callAPI("GET","/deepsee/status", { 'page': 10, 'pageSize': 20, 'sort': 'percent', 'sortDirection': 'ASC' } ) Output 'paging': {'Extraction': {'count': <integer>, 'current': <integer>, 'limit': <integer>, 'nextPage': [True|False], 'options': {'conditions': [], 'order': {'<field>': '[asc|desc]'}}, 'order': {'<field>': '[asc|desc]'}, 'page': <integer>, 'pageCount': <integer>, 'paramType': '<string>', 'prevPage': [True|False]}}, 'result': {'pageCount': <integer>, 'rows': [{'appliance_ids': '', 'as_status': '<status>', 'bytes_read': <integer>, 'db_size': <integer>, 'disk_size': <integer>, 'end': 'YYYY-MM-DD hh:ii:ss.000000', 'id': <integer>, 'name': '<string>', 'pcap': '/pfs/flows/timespan/YYYY-MM-DDThh:ii:ss-zz:zz_YYYY-MMDDThh:ii:ss-zz:zz/data.pcapng', 'percent': <integer>, 'results': <integer>, 'start': 'YYYY-MM-DD hh:ii:ss.999999', 'status': '<string>', 'user_name': '<string>'}]} Get artifact details API Path /artifacts/details 192 Security Analytics Reference Guide Security Analytics 8.1 Description Retrieve details about an artifact GUI Location Menu > Analyze > Summary > Extractions > [artifact entry] Parameters REQ artifactIDs searchID Format Default Valid Inputs array — <GET: /artifacts/artifacts> integer null null | <GET: /artifacts/artifacts> PHP Example callAPI('GET','/artifact/details', array( 'artifactIDs' => array( <artifact_ID-1>, <artifact_ID-2>, <artifact_ID-3> ), 'searchID' => '<search_ID>' ) ); Python Example s.callAPI("GET","/artifact/details", { 'artifactIDs': [ <artifact_ID-1>, <artifact_ID-2>, <artifact_ID-3> ], 'searchID': '<search_ID>' } ) Output array Download artifacts API Path /artifacts/download Description Download one or more artifacts 193 Description An array of artifact IDs Extraction ID Security Analytics Reference Guide Security Analytics 8.1 GUI Location Menu > Analyze > Summary > Extractions > [artifact entry] > Download Parameters REQ ids searchId X type mode Format Default Valid Inputs Description array — <GET: /artifacts/artifacts> Array of artifact IDs integer — <GET: /artifacts/artifacts> Extraction ID string zip zip | ogg | wav | single string — synth_audio PHP Example 1 Download All Artifacts from an Extraction as a ZIP File callAPI('GET','/artifacts/download', array( 'searchId' => <searchId>, ), '<filename>.zip' ); Python Example 1 Download All Artifacts from an Extraction as a ZIP File callAPI("GET","/artifacts/download", { 'searchId': <searchId>, }, '<filename>.zip' ) PHP Example 2 Download Selected VoIP Artifacts in OGG Format callAPI('GET','/artifacts/download', array( 'ids' => array( <id-1>, <id-2>, <id-3> ), 'searchId' => <searchId>, 'type' => 'ogg', 194 File type to download n If there are more ids than one, then type=zip; else type=single n If mode=synth_audio then default type=ogg else default type=single synth_audio — Artifact is a VoIP and will be downloaded with both sides of the conversation included Security Analytics Reference Guide Security Analytics 8.1 'mode' => 'synth_audio' ), '<filename>.ogg' ); Python Example 2 Download Selected VoIP Artifacts in OGG Format s.callAPI("GET","/artifacts/download", { 'ids': [ <id-1>, <id-2>, <id-3> ], 'searchId': <searchId>, 'type': 'ogg', 'mode': 'synth_audio' }, '<filename>.ogg' ) Output <filename>.<ext> Get artifact timeline information API Path /artifacts/timeline Description Retrieve timeline information about the artifacts GUI Location Menu > Analyze > Summary > Extractions > Artifact Timeline Output array Parameters REQ Format Default Valid Inputs identityPath X string | integer — <identity path> filters X array — <advanced filter array> page integer 1 1–<n> Number of pages to retrieve; first page is 1. pageSize integer 25 1–100 Number of entries per page 195 Description One of several identifying values Advanced filter attributes Security Analytics Reference Guide REQ Security Analytics 8.1 Format Default Valid Inputs sort string date date | source | type | size sortDirection string ASC ASC | DESC Boolean false true | false restart Description Sort-by column Sort order True — Run the extraction again PHP Example callAPI('GET','/artifacts/timeline', array( 'identityPath' => <searchID>, 'page' => 10, 'pageSize' => 20, 'filters' => array( 'port=80', 'port=443', 'application_id=tcp,http' ) 'restart' => true, 'sort' => 'type', 'sortDirection' => 'DESC' ) ); Python Example s.callAPI("GET","/artifacts/timeline", { 'identityPath':<searchID>, 'page': 10, 'pageSize': 20, 'filters': [ 'port=80', 'port=443', 'application_id=tcp,http' ] 'restart': True, 'sort': 'type', 'sortDirection': 'DESC' } ) Output 'result': {'artifactGroups': [{'group': '<[ip|port|filetype>', 'history': [{'Artifact': {'capture_start_time': <epoch>, 'destination_ip': '<ip>', 'extension': '<string>', 'host': '<hostname>', 'icon': '<string>', 'id': <integer>, 'magic_type': '<detected_MIME_type>', 'source_ip': '<ip>', 'title': '<filename>'}}], 'numArtifacts': <integer>}, ... 'artifact_search_id': <integer>, 'background': [True|False], 'field_counts': {'file_extension': {'7z': [1], 'apk': [1], ... 'xml': [2], 'zip': [5]}, 196 Security Analytics Reference Guide Security Analytics 8.1 'file_type': {'application/bat': [0, 3], 'application/email': [53, 53], ... 'video/x-ms-wmv': [18, 0], 'video/x-msvideo': [0, 1]}}, 'histogram': {'data': [{'columns': [<integer>], 'extra': {'end_time': <epoch>}, 'time': <epoch>}, ... {'columns': [<integer>], 'extra': {'end_time': <epoch>}, 'time': <epoch>}], 'meta': {'columns': [{'has_total': 'true', 'text': 'Artifacts', 'type': 'magnitude'}], 'data_type': {'text': 'Artifacts', 'type': 'magnitude'}}, 'total': [<integer>]}, 'killed': [True|False], 'maxpage': <integer>, 'numFiltered': <integer>, 'numResults': <integer>, 'percentcomplete': '100', 'searchID': <integer>, 'search_status': 'extractor.status.finished', 'timeDeleted': [True|False], 'time_place': <epoch>}, 'resultCode': 'API_SUCCESS_CODE', Get jsunpack-n preview API Path /preview/jsunpackn Description Run jsunpack-n on one or more artifacts GUI Location Menu > Analyze > Summary > Extractions > [artifact entry] > Preview > jsunpack-n Parameters REQ Format Default Valid Inputs X integer — <GET: /artifacts/artifacts> artifactId PHP Example callAPI('GET','/preview/jsunpackn', array( 'artifactId' => array( <ID1>, <ID2>, <ID3> ) ) 197 Description ID of the artifact(s) to run through jsunpack-n Security Analytics Reference Guide Security Analytics 8.1 ); Python Example s.callAPI("GET","/preview/jsunpackn", { 'artifactId': [ <ID1>, <ID2>, <ID3> ] } ) Output 'result': ['[malicious:<integer>] [<EXT>] <filename>', '<jsunpack-n results>'], 'resultCode': 'API_SUCCESS_CODE', Get signature extraction state API Path /settings/extractor_enable_signature_extractor Description Retrieve the state of signature extraction GUI Location Menu > Settings > System > Extraction Settings > Enable signature-based extraction Output integer | false Parameters None PHP Example callAPI('GET','/settings/extractor_enable_signature_extractor'); Python Example s.callAPI("GET","/settings/extractor_enable_signature_extractor") Output 'result': [0|1], 'resultCode': 'API_SUCCESS_CODE', Get MD5 hash calculation state API Path /settings/extractor_enable_md5 198 Security Analytics Reference Guide Security Analytics 8.1 Description Retrieve the state of MD5 hash calculation GUI Location Menu > Settings > System > Extraction Settings > Hash Computation > MD5 Parameters None PHP Example callAPI('GET','/settings/extractor_enable_md5'); Python Example s.callAPI("GET","/settings/extractor_enable_md5") Output 'result': [0|1], 'resultCode': 'API_SUCCESS_CODE', Get SHA1 hash calculation state API Path /settings/extractor_enable_sha1 Description Retrieve the state of SHA1 hash calculation GUI Location Menu > Settings > System > Extraction Settings > Hash Computation > SHA1 Parameters None PHP Example callAPI('GET','/settings/extractor_enable_sha1'); Python Example s.callAPI("GET","/settings/extractor_enable_sha1") Output 'result': [0|1], 'resultCode': 'API_SUCCESS_CODE', 199 Security Analytics Reference Guide Security Analytics 8.1 Get SHA256 hash calculation state API Path /settings/extractor_enable_sha256 Description Retrieve the state of SHA256 hash calculation GUI Location Menu > Settings > System > Extraction Settings > Hash Computation > SHA256 Output integer | false Parameters None PHP Example callAPI('GET','/settings/extractor_enable_sha256'); Python Example s.callAPI("GET","/settings/extractor_enable_sha256") Output 'result': [0|1], 'resultCode': 'API_SUCCESS_CODE', Get fuzzy hash calculation state API Path /settings/extractor_enable_fuzzy Description Retrieve state of fuzzy hash calculation GUI Location Menu > Settings > System > Extraction Settings > Hash Computation > Fuzzy Parameters None PHP Example callAPI('GET','/settings/extractor_enable_fuzzy'); 200 Security Analytics Reference Guide Security Analytics 8.1 Python Example s.callAPI("GET","/settings/extractor_enable_fuzzy") Output 'result': [0|1], 'resultCode': 'API_SUCCESS_CODE', Get partial-content assembly state API Path /settings/extractor_enable_partial_content_reconstruction Description Retrieve the state of partial content assembly GUI Location Menu > Settings > System > Assemble Partial Content Parameters None PHP Example callAPI('GET','/settings/extractor_enable_partial_content_reconstruction'); Python Example s.callAPI("GET","/settings/extractor_enable_partial_content_reconstruction") Output 'result': {'ExtractorSetting': {'partial_content_reconstruction': [0|1]}}, 'resultCode': 'API_SUCCESS_CODE', Get fragment-display state API Path /settings/extractor_enable_fragment_reconstruction Description Retrieve the state of fragment reconstruction GUI Location Menu > Settings > System > Extraction Settings > Display fragments Parameters None 201 Security Analytics Reference Guide Security Analytics 8.1 PHP Example callAPI('GET','/settings/extractor_enable_fragment_reconstruction'); Python Example s.callAPI("GET","/settings/extractor_enable_fragment_reconstruction") Output 'result': [0|1], 'resultCode': 'API_SUCCESS_CODE', Get extractor tuning parameters API Path /settings/extractor_prototune Description Retrieve the protocol-tuning settings GUI Location Menu > Settings > System > Extraction Settings > Extractor Tuning Parameters Parameters None PHP Example callAPI('GET','/settings/extractor_prototune'); Python Example s.callAPI("GET","/settings/extractor_prototune") Output 'result': {'ExtractorSetting': {'prototune': '<prototune settings>'}, 'validationErrors': []}, 'resultCode': 'API_SUCCESS_CODE', Sanitize CSS API Path /artifacts/sanitize_css/<artifactId> Description Removes external JavaScript URLs from CSSs GUI Location Menu > Analyze > Summary > Extractions > [HTML artifact] > Preview > Web Page > View Options 202 Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ artifactId Format Default X integer — Valid Inputs Description <GET: /artifacts/artifacts> ID of artifact PHP Example callAPI('GET','/artifacts/sanitize_css/<artifactId>'); Python Example s.callAPI("GET","/artifacts/sanitize_css/<artifactId>") Output array Sanitize HTML page by artifact ID API Path /artifacts/sanitize_html/<artifactId> Description Sanitizes HTML artifacts (web pages) so that external scripts, images, and CSSs can be omitted. If the external preview setting is disabled it will force all externals to be hidden. n hide — Completely remove the external URL n captureData — Attempt to show the item as a captured artifact; if none is found, default to hide n external — Use the absolute URL (including host) for the artifact. GUI Location Menu > Analyze > Summary > Extractions > [HTML artifact] > Preview > Web Page > View Options Output string Parameters REQ Format Default Valid Inputs Description artifactId X integer — <GET: /artifacts/artifacts> ID of the artifact cssSource X string — hide | captureData | external Source of CSSs scriptSource X string — hide | captureData | external Source of scripts imageSource X string — hide | captureData | external Source of images PHP Example callAPI('GET','/artifacts/sanitize_html/<artifactId>', 203 Security Analytics Reference Guide Security Analytics 8.1 array( 'cssSource' => 'external', 'scriptSource' => 'captureData', 'imageSource' => 'hide' ) ); Python Example s.callAPI("GET","/artifacts/sanitize_html/<artifactId>", { 'cssSource': 'external', 'scriptSource': 'captureData', 'imageSource': 'hide' } ); Sanitize HTML text API Path /artifacts/sanitize_html_text Description Sanitize HTML text GUI Location Menu > Analyze > Summary > Extractions > [HTML artifact] > Preview > Web Page > View Options Output string Parameters REQ html Format Default X array — Valid Inputs Description <HTML text> HTML text PHP Example callAPI('GET','/artifacts/sanitize_html_text', array( 'html' => '<html><head><title>HTML Page Sample</title></head><body><h1>Sample Heading1</h1><p>text</p></body></html>' ) ); Python Example s.callAPI("GET","/artifacts/sanitize_html_text", { 'html': '<html><head><title>HTML Page Sample</title></head><body><h1>Sample Heading1</h1><p>text</p></body></html>' } ) 204 Security Analytics Reference Guide Security Analytics 8.1 Generate an audio file API Path /artifacts/synth_audio Description Generates an audio file (usually VoIP) from one or more existing audio artifacts. If the target file exists, synth_ audio_artifact will not generate a new one unless force=true. GUI Location Menu > Analyze > Summary > Extractions > [audio artifact] > Download Output array Parameters REQ Format Default files X array — path X string — string ogg type codec force string Boolean Vorbis false Valid Input Description Array of files to combine into a single audio file; contains path, type, codec /home/apache/artifacts/ Path to input file <integer>/<filename>.<ext> ogg | wav | raw ulaw | alaw | Vorbis true | false Requested output file type: n ogg — Output is Vorbis n wav — Output is PCM Signed-Integer Codec used. Supported codecs: n ulaw — raw: pcm μ-law, audio/PCMU n alaw — raw: pcm A-law, audio/PCMA True — Generate a new file even if a file already exists PHP Example callAPI('GET','/artifacts/synth_audio', array( 'files' => array( array( 'path' => '/home/apache/artifacts/25/mysound-00.wav', 'type' => 'wav', 'codec' => 'ulaw' ), array( 'path' => '/home/apache/artifacts/25/mysound-01.wav', 'type' => 'wav', 'codec' => 'ulaw' ) ) ), '<filename>.wav' 205 Security Analytics Reference Guide Security Analytics 8.1 ); Python Example s.callAPI("GET","/artifacts/synth_audio",{ 'files':{ { 'path': '/home/apache/artifacts/25/mysound-00.wav', 'type': 'wav', 'codec': 'ulaw' }, { 'path': '/home/apache/artifacts/25/mysound-01.wav', 'type': 'wav', 'codec': 'ulaw' } } }, '<filename>.wav' ) Get IM conversations API Path /artifacts/im_conversations Description Retrieve reconstructed instant messaging conversations GUI Location Menu > Analyze > Summary > Extractions > IM Conversations Output array Parameters REQ Format Default Valid Inputs X string | integer — <identity path> One of several identifying values page integer 1 1–<n> Number of pages to retrieve; first page is 1 pageSize integer 25 1–100 Number of entries per page filters array — <advanced filter array> restart Boolean false true | false string date date | source | type | size | sender | recipient | subject identityPath sort 206 Description Advanced filter attributes True — Restart the extraction that is associated with the artifact search Sort-by column Security Analytics Reference Guide REQ sortDirection Security Analytics 8.1 Format Default Valid Inputs string ASC ASC | DESC PHP Example callAPI('GET','/artifacts/im_conversations', array( 'identityPath' => <searchID>, 'page' => 10, 'pageSize' => 20, 'filters' => array( 'port=80', 'port=443', 'application_id=tcp,http' ) 'restart' => false, 'sort' => 'size', 'sortDirection' => 'DESC' ) ); Python Example s.callAPI("GET","/artifacts/im_conversations", { 'identityPath': <searchID>, 'page': 10, 'pageSize': 20, 'filters': [ 'port=80', 'port=443', 'application_id=tcp,http' ] 'restart': False, 'sort': 'size', 'sortDirection': 'DESC' } ) Get IM user image API Path /im_user/<userId> Description Retrieve the captured IM image for the user GUI Location Menu > Analyze > Summary > Extractions > IM Conversations > Preview Output ApiResultCode 207 Description Sort order Security Analytics Reference Guide Security Analytics 8.1 Parameters userId REQ Format Default Valid Inputs X integer/string — <GET: /im_conversation> | default Boolean false true | false large Description ID of the user or default for the default image. n True — Full-sized image n False — Thumbnail version PHP Example callAPI('GET','/im_user/<userId>', array( 'large' => true ) ); Python Example s.callAPI("GET",'/im_user/<userId>",{ 'large': True } ) Download thumbnail API Path /thumbnails/<searchId>/<artifactor> Description Download an artifact thumbnail image GUI Location Menu > Analyze > Summary > Extractions > Media Panel Output ApiResultCode Parameters REQ Format Default Valid Inputs Description searchId X integer — <GET: /artifacts/artifacts> Artifact search ID artifactor X string — <artifactID>_<last12SHA1>_ [small | medium | large]. [jpg | gif | tif | png] String made up of the artifact ID, the last 12 characters of the artifact's SHA1 hash, the desired thumbnail size, and the file extension. PHP Example callAPI('GET','/thumbnails/<searchId>/'333_3e5fcb55213c_small.jpg'); 208 Security Analytics Reference Guide Security Analytics 8.1 Python Example s.callAPI("GET","/thumbnails/<searchId>/'333_3e5fcb55213c_small.jpg") Get root cause API Path /rootcause/<id>/<artifactSearchId> Description Retrieve an artifact's referrer chain. It will first find the entire referrer chain for that artifact. If referrers are found then it also searches for IM conversations that contain the referrer URL in the message. GUI Location Menu > Analyze > Summary > Extractions > [artifact entry] > Explore Root Cause Output array Parameters REQ Format Default Valid Inputs id X integer — <GET: /artifacts/artifacts> Artifact ID artifactSearchId X integer — <GET: /artifacts/artifacts> Artifact search ID PHP Example callAPI('GET','/rootcause/<id>/<artifactSearchId>'); Python Example s.callAPI("GET","/rootcause/<id>/<artifactSearchId>") Set HTTP proxy assembly state — NEW API Path /settings/extractor_enable_proxy_data_reconstruction Description Set the state for proxy data assembly. GUI Location Menu > Settings > System 209 Description Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ state Format Default X Boolean — Valid Inputs Description true | false True — Enable proxy data assembly PHP Example callAPI('POST','/settings/extractor_enable_proxy_data_reconstruction', array ( 'state' => true ) ); Python Example s.callAPI("POST","/settings/extractor_enable_proxy_data_reconstruction", { 'state': True } ) Output API_SUCCESS_CODE Save an extraction — MODIFIED API Path /artifacts/save/<id> Description Save an extraction to the Menu > Analyze > Extraction Status page GUI Location Menu > Analyze > Summary > Extractions Output null Parameters REQ Format Default Valid Inputs searchId X integer — <GET: /artifacts/artifacts> name X string — <UTF-8 characters> PHP Example callAPI('POST','/artifacts/background/<searchId>', array( 'name' => 'extraction1' ) ); Python Example s.callAPI("POST","/artifacts/background/<searchId>", { 'name': 'extraction1' 210 Description Artifact search ID Specify a name for the search Security Analytics Reference Guide Security Analytics 8.1 } ) Stop an incomplete extraction API Path /artifacts/stop/<searchId> Description Stop an extraction in progress. GUI Location Menu > Analyze > Summary > Extractions Output null Parameters REQ searchId X Format Default integer — Valid Inputs < GET: /artifacts/artifacts >|<GET: /artifacts/im_ conversations> PHP Example callAPI('POST','/artifacts/stop/<searchId>'); Python Example s.callAPI("POST","/artifacts/stop/<searchId>") Delete a saved extraction API Path /artifacts/delete/<searchId> Description Delete the saved extraction GUI Location Menu > Analyze > Extraction Status Output array 211 Description Artifact search ID Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ searchId Format Default X string — Valid Inputs Description <GET: /artifacts/artifacts> Extraction ID PHP Example callAPI('POST','/artifacts/delete/<searchId>'); Python Example s.callAPI("POST","/artifacts/delete/<searchId>") Delete all extractions API Path /extractions/delete Description Delete all extractions that are on the Extraction Status page. GUI Location Menu > Settings > Upgrade > Update Precheck button > Delete Extractions Parameters None PHP Example callAPI('POST','/extractions/delete'); Python Example s.callAPI("POST","/extractions/delete") Output integer | false Set partial-content assembly state API Path /settings/extractor_enable_partial_content_reconstruction Description Set the state for Assemble Partial Content GUI Location Menu > Settings > System 212 Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ state X Format Default Boolean — Valid Inputs Description true | false True — Enable Assemble Partial Content PHP Example callAPI('POST','/settings/extractor_enable_partial_content_reconstruction', array ( 'state' => true ) ); Python Example s.callAPI("POST","/settings/extractor_enable_partial_content_reconstruction", { 'state': True } ) Output API_SUCCESS_CODE Set signature extraction state API Path /settings/extractor_enable_signature_extractor Description Enable or disable signature extraction GUI Location Menu > Settings > System > Extraction Settings > Enable signature-based extraction Output integer | false Parameters REQ state X Format Default Boolean — Valid Inputs Description true | false True — Enable signature extraction PHP Example callAPI('POST','/settings/extractor_enable_signature_extractor', array ( 'state' => true ) ); Python Example s.callAPI("POST","/settings/extractor_enable_signature_extractor", { 'state': True } 213 Security Analytics Reference Guide Security Analytics 8.1 ) Set MD5 hash calculation state API Path /settings/extractor_enable_md5 Description Enable or disable MD5 hash calculation GUI Location Menu > Settings > System > Extraction Settings > Hash Computation > MD5 Output integer | false Parameters REQ state X Format Default Boolean — Valid Inputs Description true | false True — Enable MD5 hash calculation PHP Example callAPI('POST','/settings/extractor_enable_md5', array ( 'state' => true ) ); Python Example s.callAPI("POST","/settings/extractor_enable_md5", { 'state': True } ) Set SHA1 hash calculation state API Path /settings/extractor_enable_sha1 Description Enable or disable SHA1 hash calculation GUI Location Menu > Settings > System > Extraction Settings > Hash Computation > SHA1 214 Security Analytics Reference Guide Security Analytics 8.1 Output integer | false Parameters REQ state X Format Default Boolean — Valid Inputs Description true | false True — Enable SHA1 hash calculation PHP Example callAPI('POST','/settings/extractor_enable_sha1', array ( 'state' => true ) ); Python Example s.callAPI("POST","/settings/extractor_enable_sha1", { 'state': True } ) Set SHA256 hash calculation state API Path /settings/extractor_enable_sha256 Description Enable or disable SHA256 hash calculation GUI Location Menu > Settings > System > Extraction Settings > Hash Computation > SHA256 Output integer | false Parameters REQ state X Format Default Boolean — Valid Inputs Description true | false True — Enable SHA256 hash calculation PHP Example callAPI('POST','/settings/extractor_enable_sha256', array ( 'state' => true ) ); Python Example s.callAPI("POST","/settings/extractor_enable_sha256", { 'state': True } 215 Security Analytics Reference Guide Security Analytics 8.1 ) Set fuzzy hash calculation state API Path /settings/extractor_enable_fuzzy Description Enable or disable fuzzy hash calculation GUI Location Menu > Settings > System > Extraction Settings > Hash Computation > Fuzzy Output integer | false Parameters REQ state X Format Default Boolean — Valid Inputs Description true | false True — Enable fuzzy hash calculation PHP Example callAPI('POST','/settings/extractor_enable_fuzzy', array ( 'state' => true ) ); Python Example s.callAPI("POST","/settings/extractor_enable_fuzzy", { 'state': True } ) Set fragment-display state API Path /settings/extractor_enable_fragment_reconstruction Description Enable or disable the display of known fragments in the Extractions list GUI Location Menu > Settings > System > Extraction Settings > Display fragments 216 Security Analytics Reference Guide Security Analytics 8.1 Output integer | false Parameters REQ state X Format Default Boolean — Valid Inputs Description true | false True — Display the fragments PHP Example callAPI('POST','/settings/extractor_enable_fragment_reconstruction', array ( 'state' => true ) ); Python Example s.callAPI("POST","/settings/extractor_enable_fragment_reconstruction", { 'state': True } ) Configure extractor-tuning parameters API Path /settings/extractor_prototune Description Input protocol-tuning strings GUI Location Menu > Settings > System > Extraction Settings > Extraction Tuning Parameters Output string | false Parameters state REQ Format Default Valid Inputs X string — <protocol> :<parameter>:<value> Description Contact Symantec Support for tuning parameters PHP Example callAPI('POST','/settings/extractor_prototune', array( 'state' => 'tcp:enable_defrag:1;ip:enable_defrag:1;ip6:enable_defrag:1' ) ); Python Example s.callAPI("POST","/settings/extractor_prototune", { 'state':'tcp:enable_defrag:1;ip:enable_defrag:1;ip6:enable_defrag:1' 217 Security Analytics Reference Guide Security Analytics 8.1 } ) 218 Security Analytics Reference Guide Security Analytics 8.1 Geolocation APIs Also see "Summary Page APIs" on page 369. Get geolocation for an IP API Path /geoip/<ip> Description Retrieve the geolocation information for an IP address GUI Location Menu > Analyze > Summary > Geolocation Output array Parameters REQ Format Default Valid Inputs Description X string — <dotted-decimal> IPv4 address ip Example callAPI('GET','/geoip/203.0.113.5'); Get geolocation settings API Path /settings/geoip Description Retrieve the geolocation settings GUI Location Menu > Settings > Geolocation Output array Parameters None 219 Security Analytics Reference Guide Security Analytics 8.1 Example callAPI('GET','/settings/geoip'); Get countries API Path /settings/geoip_countries Description Retrieve the possible countries for the KML colors GUI Location Menu > Settings > Geolocation > Internal Subnets > Enable Country Colors Output array Parameters None Example callAPI('GET','/settings/geoip_countries'); Get MaxMind status API Path /settings/geoip_files Description ® Retrieve status of MaxMind geolocation files GUI Location Menu > Settings > Geolocation > Upload MaxMind [x] Database Output array Parameters None Example callAPI('GET','/settings/geoip_files'); 220 Security Analytics Reference Guide Security Analytics 8.1 Save Geolocation Map — NEW Note: This API replaces the type parameter in POST: /deepsee/save_view API Path /deepsee/save_map Description Create or edit a geolocation map view GUI Location Menu > Analyze > Summary > Geolocation > Save Current Map as View / Edit Map Output array Parameters REQ Format Default Valid Inputs Description name X string — <UTF-8 characters> id X integer — <GET: /deepsee/summary_views> shared Boolean false true | false True — Map view is shared default Boolean false true | false True — Map view is the default Required for new map. Name of map view Required to edit map. view_data X array — lat X string — <99.9999999> Degrees latitude of the center of the map long X string — <99.9999999> Degrees longitude of the center of the map zoom X integer — 0–5 Amount of magnification 0 — No magnification Array containing lat, lon, and zoom Python Example s.callAPI("POST","/deepsee/save_map", { 'name': 'Australia', 'shared': True, 'default': True 'view_data': { 'lat': '-29.53125', 'lon': '134.82421875', 221 Security Analytics Reference Guide Security Analytics 8.1 'zoom': 1 } }) Delete a Geolocation Map View — NEW API Path /deepsee/delete_map/<ID> Description Delete a geolocation map view GUI Location Menu > Analyze > Summary > Geolocation > [view selector] > Output array Parameters id REQ Format Default Valid Inputs X integer — <GET: /deepsee/summary_views> Python Example s.callAPI("POST","/deepsee/delete_map/7") PHP Example callAPI('POST','/deepsee/delete_map/7'); Configure geolocation settings API Path /settings/geoip Description Create or edit geolocation settings GUI Location Menu > Settings > Geolocation > Internal Subnets Output array 222 Description ID of map view Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ Format Default Valid Inputs Description internal_labels_ enabled Boolean false true | false True = Enable internal subnets internal_labels array () <geolocation internal labels> ip_cidr string — lat string — [-]0–90 Degrees latitude; use a hyphen for negative numbers long string — [-]0–180 Degrees longitude; use a hyphen for negative numbers label string — <UTF-8 characters> default_kml_color string 00FFFF <HEX> Default color for pins in ® Google Earth; use ALL CAPS add_routes Boolean false true | false True = Show routes between nodes kml_colors_ enabled Boolean false true | false True = Enable country colors <dotted-decimal> | 223 <CIDR> Array of subnets and their locations; contains ip_ cidr, lat, long, and label IPv4 address or CIDR of subnetwork Label for location Security Analytics Reference Guide REQ kml_colors color country Security Analytics 8.1 Format Default Valid Inputs array () hex 000000 <HEX> string — <GET: /settings/geoip_countries> Description Array of color/country associations; contains color and country Example callAPI('POST','/settings/geoip', array( 'internal_labels_enabled' => true, 'internal_labels' => array( array( 'ip_cidr' => '192.0.2.0/24', 'long' => -111.92965, 'lat' => 40.56217, 'label' => 'Utah Office' ), ), 'default_kml_color' => 'FF00FF', 'add_routes' => true, 'kml_colors_enabled' => true, 'kml_colors' => array( array( 'color' => 'FFAA77', 'country' => 'CN' ), array( 'color' => 'FF0077', 'country' => 'IN' ), ), ) ); Update the MaxMind files API Path /settings/geoip_file Description Update the MaxMind files: city, country, or country IPv6 224 Use ALL CAPS Use twoletter country designators in ALL CAPS Security Analytics Reference Guide Security Analytics 8.1 GUI Location Menu > Settings > Geolocation > Upload MaxMind [x] Database Output array Parameters REQ Format Default Valid Inputs type X string — city | country | countryv6 file X file — <filepath> Example callAPI('POST','/settings/geoip_file', array( 'type' => 'city', 'file' => 'c:\user\maxmind\GeoLite2-city.mmdb' ) ); 225 Description File type Path to the MMDB file Security Analytics Reference Guide Security Analytics 8.1 Indicators APIs "Favorite" is the internal name for "indicator." Get shared indicators for current user API Path /favorites/active Description Retrieve a list of active (shared) indicators for the logged-in user; does not retrieve non-shared indicators GUI Location Menu > Analyze > Indicators Parameters None Python Example s.callAPI("GET","/favorites/active") PHP Example callAPI('GET','/favorites/active'); Output 'result': [{'appliances': '', 'name': 'Symantec Web Reputation Service', 'sensor_uuids': '', 'uuid': '5b7da23b-116c-496e-8762-794e1e1d64a3'}, ... {'appliances': '', 'name': 'Zeus Tracker - Bad IPs - Live Feed', 'sensor_uuids': '', 'uuid': '5b7da23d-8b70-4a7e-acbb-794e1e1d64a3'}], 'resultCode': 'API_SUCCESS_CODE', Get a list of indicators API Path /favorites Description Retrieve a paginated, detailed list of indicators and their parameters 226 Security Analytics Reference Guide Security Analytics 8.1 GUI Location Menu > Analyze > Indicators Parameters REQ Format Default Valid Inputs Description uuids array — page integer 1 1–<n> Page to retrieve; first page is 1 limit integer — 1–100 Number of items per page sort string name name Sort-by column direction string ASC ASC | DESC filters JSON — <advanced filter for indicators> name string — <UTF-8 characters> Boolean null null | true | false shared chopValues Boolean true <GET: /favorites/active> Array of UUIDs of indicators to retrieve. Omit | <GET: /favorites> this parameter to retrieve all favorites. true | false Sort direction Advanced filter attributes; indicator is the only valid key Substring to filter on exact indicator names n Null — All indicators n True — Shared indicators only n False — Non-shared indicators only True — Restrict the list to <= 2000 items Python Example s.callAPI("GET","/favorites", { 'page': 1, 'limit': 20, 'sort': 'name', 'direction': 'DESC', 'filters': { 'all': { 'key' => 'indicator', 'comp' => '~', 'value' => 'RFC1918' } }, 'name': 'mime', 'uuids': [<UUID-1>,<UUID-2>,<UUID-3>,<UUID-4>,<UUID-5>], 'shared': null, 'chopValues': false } ) PHP Example callAPI('GET','/favorites', array( 'page' => 1, 'limit' => 20, 'sort' => 'name', 'direction' => 'DESC', 'filters' => array( 'all' => array( array( 'key' => 'indicator', 'comp' => '~', 227 Security Analytics Reference Guide Security Analytics 8.1 'value' => 'RFC1918' ) ) ), 'name' => 'mime', 'uuids' => array(<UUID-1>,<UUID-2>,<UUID-3>,<UUID-4>,<UUID-5>), 'shared' => null, 'chopValues' => false ) ); Output 'paging': {'DeepseeFavorite': {'count': 56, 'current': 25, 'limit': 25, 'nextPage': True, 'options': [], 'order': {'DeepseeFavorite.name': 'ASC', 'DeepseeFavorite.ordinal': 'ASC'}, 'page': 1, 'pageCount': 3, 'paramType': 'named', 'prevPage': False}}, 'result': {'pageCount': 3, 'results': [{'active': True, 'aggregate_uuid': '984f2e1b-4366-131a-2773-0e8db7da9d94', 'appliance_id': None, 'appliances': [], 'creatable': True, 'deletable': True, 'edit_type': 'all', 'end_time_of_execution': '23:59:59', 'events': [], 'frequency': None, 'hash_uuid': 'c0e4e7a1-c2cc-7875-c441-2d9c6de5375b', 'linked_uuid': None, 'name': 'Local File Analysis - Live Exploits', 'nested': 0, 'original_params': None, 'sensor_uuids': [], 'shared': True, 'time_of_execution': None, 'user_id': None, 'uuid': '5b7da23b-386c-452b-8579-794e1e1d64a3', 'value': '["mime_type=\\"application\\/java-archive\\"","mime_ type=\\"application\\/x-java-jnlp-file\\"","mime_ type=\\"application\\/pdf\\"","mime_type=\\"application\\/xpdf\\"","mime_type=\\"application\\/acrobat\\"","mime_ type=\\"application\\/vnd.pdf\\"","mime_ type=\\"text\\/pdf\\"","mime_type=\\"text\\/x-pdf\\"","mime_ type=\\"text\\/html\\"","mime_type=\\"application\\/octetstream\\"","mime_type=\\"application\\/octet-strem\\"","mime_ type=\\"application\\/octect-strem\\"","mime_ type=\\"application\\/x-shockwave-flash\\"","mime_ type=\\"application\\/x-shockwave-flash2-preview\\"","mime_ type=\\"application\\/futuresplash\\"","mime_ type=\\"application\\/vnd.rn-realflash\\"","mime_ type=\\"application\\/x-silverlight-2\\"","url_risk_verdict=5"]', 'value_length': 18}]}, 'resultCode': 'API_SUCCESS_CODE', 228 Security Analytics Reference Guide Security Analytics 8.1 Get import-type parameters for indicators API Path /favorites/importers Description Retrieve a list of all valid indicator import types and their input parameters GUI Location Menu > Analyze > Indicators > Tools > Import > Location=Remote Parameters None Python Example s.callAPI("GET","/favorites/importers") PHP Example callAPI('GET','/favorites/importers'); Output 'result': {'deepsee': {'name': 'JSON', 'params': []}, 'dshield': {'name': 'DShield', 'params': {'name': {'label': 'Name', 'type': 'text'}}}, 'simple_list': {'name': 'List', 'params': {'field': {'label': 'Field', 'type': 'list', 'values': 'field_options'}, 'name': {'label': 'Name', 'type': 'text'}}}, 'snort': {'name': 'Snort', 'params': {'keepDirection': {'label': 'Honor rule ' 'directionality', 'type': 'boolean'}, 'name': {'label': 'Name', 'type': 'text'}}}}, 'resultCode': 'API_SUCCESS_CODE', Create or edit an indicator API Path /favorites/save Description Create or edit an indicator GUI Location n Menu > Analyze > Indicators > Tools > New n Menu > Analyze > Indicators > [edit indicator] 229 Security Analytics Reference Guide Security Analytics 8.1 Output array Parameters REQ uuid name value X Format Default Valid Inputs UUID 0 0 | <GET: /favorites> | <GET: /favorites/active> n Create new — Use 0 n Edit entry — UUID required <UTF-8 characters> n Create new — Name required n Edit entry — New name string — Description JSON — <primary filter array> Boolean true true | false applianceIds array null GET: /cmc_ settings/appliances array (<appliance_ id1> => <appliance_ name1>,<appliance_ id2> => <appliance_ name2>) CMC Only. Array of sensors IDs to receive the indicator linked_uuid UUID null null | <GET: /favorites> | <GET: /favorites/active> UUID to link to the main indicator so that changes to a child indicator will update the parent; not visible in GUI shared X Example 1 Create a new indicator (favorite) callAPI('POST','favorites/save', array( 'uuid' => '0', 'name' => 'MiddlewareGroup', 'value' => json_encode( array ( 'application_group='middleware' ) ) ) ); Example 2 Edit an existing indicator on three sensors. Run this API on a CMC. callAPI('POST','favorites/save?appliances=1', 230 Primary-filter attributes; JSONencoded True — Shared Security Analytics Reference Guide Security Analytics 8.1 array( 'uuid' => <UUID>, 'name' => 'Middleware&Management', 'value' => json_encode( array( 'application_group=middleware', 'application_group=network management' ) 'applianceIDs' => array( 1 => 'sensorA', 4 => 'sensorD', 5 => 'sensorE' ) ) ) ); Import indicators from a file; create a live-feed indicator API Path /favorites/import Description Import indicators from a file or create a live-feed indicator GUI Location Menu > Analyze > Indicators > Tools > Import Output array Parameters type importLocation importFile remoteLocation applianceIds REQ Format Default X string — string local Valid Inputs Description GET: /favorites/importers File type to import. local | remote string — <filepath> URI — <URI> array null n Local — Browser upload n Remote — Upload from URI Required if importLocation=local; path of file to import Required if importLocation=remote; URI of remote file GET: /cmc_ CMC Only. Array of sensors IDs to settings/appliances receive the indicator array (<appliance_id1> => <appliance_ name1>,<appliance_id2> => <appliance_name2>) 231 Security Analytics Reference Guide REQ shared Security Analytics 8.1 Format Default Valid Inputs Description true | false True — Shared Boolean true array — name string — <UTF-8 characters> keepDirection integer 0 0 | 1 importTypeParam GET: /favorites/importers Parameters that are required by each type; array +may contain all of the parameters below Required if type!=json; name for the indicator Valid if type=snort 1 — Retain the directionality of the original rule field string — importSchedule array — frequency string null daily | weekly | monthly | hour | minute | once | custom events array null <scheduled_events> Valid only if importLocation=remote; depends on the value of frequency time_of_ execution string null <hh:ii:ss> Valid only if importLocation=remote; first time to re-import the file at remoteLocation end_time_of_ execution string null <hh:ii:ss> | 23:59:59 <primary_filter_ attribute> Required if type=simple_list and importLocation=local; attribute to match to the values in the imported list, such that <primary filter attribute>=<list value> Valid only if importLocation=remote; array contains events, frequency, time_ of_execution, end_time_of_ execution Valid only if importLocation=remote; how often to re-import the file at remoteLocation Valid only if location=remote; n Example 1 Import a list of values for ipv4_address onto three sensors. Run this API on the CMC. callAPI('POST','favorites/import?appliances=1', array( 'type' => 'simple_list', 'importLocation' => 'local', 232 <hh:ii:ss> is valid when frequency=hour or minute, else use 23:59:59 Security Analytics Reference Guide Security Analytics 8.1 'importFile' => 'c:\dox\indicator_list.txt', 'importTypeParams' => array( 'name' => 'BlackListed IPs', 'field' => 'ipv4_address' 'applianceIDs' => array( 1 => 'sensorA', 4 => 'sensorD', 5 => 'sensorE' ) ) ) ); Example 2 Import indicators exported from another appliance callAPI('POST','favorites/import', array( 'type' => 'deepsee', 'importLocation' => 'local', 'importFile' => 'c:\dox\indicators.json' ) ); Example 3 Create a live-feed indicator from a remote Snort list callAPI('POST','favorites/import', array( 'shared' => true, 'type' => 'snort', 'importTypeParams' => array( 'name' => 'SnortRules', 'keepDirection' => true ), 'importLocation' => 'remote', 'remoteLocation' => 'http://rules.emergingthreats.net/blockrules/emergingciarmy.rules', 'importSchedule' => array( 'frequency" => 'minute', 'events' => '01', 'time_of_execution' => '0:0:00', 'end_time_of_execution' => '23:59:00' ) ) ); Delete indicators API Path /favorites/delete Description Delete one or more indicators 233 Security Analytics Reference Guide Security Analytics 8.1 GUI Location Menu > Analyze > Indicators > Tools > Delete Output array Parameters selectedIds REQ Format Default Valid Inputs X array — <GET: /favorites> array null <GET: /cmc_ settings/appliances> applianceIds Description UUID(s) of the indicator(s) to delete CMC only. Sensors to delete the indicator(s) from Example callAPI('POST','favorites/delete', array( 'selectedIds' => array( '<UUID-1>', '<UUID-2>' ), 'applianceIds' => array( <sensor-1>, <sensor-2>, <sensor-3> ) ) ); Activate or deactivate an indicator API Path /favorites/toggle/<UUID> Description Activate or deactivate an indicator GUI Location Menu > Analyze > Indicators > Output array Parameters uuid REQ Format Default Valid Inputs X UUID — <GET: /favorites> | <GET: /favorites/active> 234 Description UUID of indicator to toggle Security Analytics Reference Guide REQ action Security Analytics 8.1 Format Default Valid Inputs Description Boolean true true | false True — Activate Example callAPI('POST','favorites/toggle/<UUID>', array( 'action' => 'false' ) ); 235 Security Analytics Reference Guide Security Analytics 8.1 License APIs Get the serial number of the appliance API Path /settings/machine_details Description Retrieve the serial number of the appliance GUI Location About Output {'result' : {serial_number': '<serial number>' 'resultCode': '<result>'}} Parameters None PHP Example callAPI('GET','/settings/machine_details'); Python Example s.callAPI("GET","/settings/machine_details") Get the DS Seed file API Path /settings/download_seed Description Download dsseed.tgz GUI Location About > License Details > Download DS Seed Output ApiResultCode Parameters None Example callAPI('GET','/settings/download_seed'); 236 Security Analytics Reference Guide Security Analytics 8.1 Get license settings API Path /settings/entitlements Description Retrieve license information GUI Location About > License Details Output ApiResultCode Parameters None Example callAPI('GET','/settings/entitlements'); Get current license file API Path /settings/license Description Download solera-license.dat GUI Location About > License Details > Download Output solera-license.dat Parameters None Example callAPI('GET','/settings/license'); 237 Security Analytics Reference Guide Security Analytics 8.1 Retrieve a license from the server API Path /settings/license_server Description Retrieve a license from the license server GUI Location About > License Details Output array Parameters REQ Format Default Valid Inputs Description serial X string — <license_key> Retrieve your license key from Symantec Support Center, as instructed in your eFulfillment message license X string null <GET: /config> License identifier, if previously licensed Example callAPI('POST','/settings/license_server', array( 'serial' => '<license_key>', 'license' => '<license_ID>' ) ); Upload a license API Path /settings/license Description Upload the license file (license.tgz) to the appliance; successful upload reboots the appliance GUI Location About > License Details > Browse Output ApiResultCode 238 Security Analytics Reference Guide Security Analytics 8.1 Parameters license REQ Format Default Valid Inputs Description X file — <path>\license.tgz License file Example callAPI('POST','/settings/license', array( 'license' => 'c:\documents\user5\downloads\license.tgz' ) ); 239 Security Analytics Reference Guide Security Analytics 8.1 Logging and Communication APIs Get all log entries API Path /statistics/logging Description Retrieve all Audit Log entries GUI Location Menu > Settings > Audit Log Output array Parameters REQ Format Default Valid Inputs Description page integer 1 1–<n> Page to retrieve; first page is 1 limit integer 25 1–100 Number of items per page direction string DESC ASC | DESC filters JSON — <advanced filter for audit log> sort string time Sort order Advanced filter attributes. Only = and != operators are permitted. time | priority | category Sort-by field | event | message Python Example s.callAPI("GET","/statistics/logging", { 'page': 1, 'limit': 20, 'direction': 'ASC', 'filters': { 'all': { { 'key': 'category', 'comp': '=', 'value': 'alerts' }, { 'any': { { 'key': 'event', 'comp': '=', 'value': 'capture stop' }, { 'key': 'priority', 240 Security Analytics Reference Guide Security Analytics 8.1 'comp': '!=', 'value': 'Error' } } } } } } ) PHP Example callAPI('GET','/statistics/logging', array( 'page' => 1, 'limit' => 20, 'direction' => ASC, 'filters' => array( 'all' => array( array( 'key' => 'category', 'comp' => '=', 'value' => 'alerts' ), array( 'any' => array( array( 'key' => 'event', 'comp' => '=', 'value' => 'capture stop' ), array( 'key' => 'priority', 'comp' => '!=', 'value' => 'Error' ) ) ) ) ) ); Output 'paging': {'SysLog': {'count': <integer>, 'current': <integer>, 'limit': <integer>, 'nextPage': [True|False], 'options': {'conditions': [], 'order': {'SysLog.time': '[asc|desc]'}}, 'order': {'SysLog.time': '[asc|desc]'}, 'page': <integer>, 'pageCount': <integer>, 'paramType': 'named', 'prevPage': [True|False]}}, 'result': [{'category': '<category>', 'event': '<event>', 'log_id': <integer>, 'message': '<line 1>' '<line 2>', 'priority': '<priority>', 'time': '<MM/DD/YYYY hh:ii:ss>'}, ... {'category': '<category>', 'event': '<event>', 'log_id': <integer>, 'message': '<line 1>' '<line 2>', 'priority': '<priority>', 241 Security Analytics Reference Guide Security Analytics 8.1 'time': '<MM/DD/YYYY hh:ii:ss>'}], 'resultCode': 'API_SUCCESS_CODE', Get logging settings API Path /settings/logging_settings Description Retrieve all SNMP, SMTP, and syslog settings GUI Location Menu > Settings > Communications > Server Settings Parameters None Python Example s.callAPI("GET","/settings/logging_settings") PHP Example callAPI('GET','/settings/logging_settings'); Output 'result': {'icdx_meta_enabled': '', 'icdx_valid': [True|False], 'log_email_address': '<email_address>', 'log_email_auth_optional': [0|1], 'log_email_sender': '<email_sender>', 'log_email_smtp_password': '***************************', 'log_email_smtp_port': <port>, 'log_email_smtp_server': '<hostname>', 'log_email_smtp_username': '<string>', 'log_email_use_starttls': [True|False], 'log_icdx_exchange': '<string>', 'log_icdx_password': '*************************', 'log_icdx_port': '5672', 'log_icdx_server': '<hostname>', 'log_icdx_username': '<string>', 'log_phantomcyber_key': '*****************', 'log_phantomcyber_server': '<hostname>', 'log_snmp_auth_password': '***************************', 'log_snmp_auth_password2': '', 'log_snmp_auth_protocol': 'SHA', 'log_snmp_auth_protocol2': '', 'log_snmp_authtrap': [True|False], 'log_snmp_encryption_password': '***************************', 'log_snmp_encryption_password2': '', 'log_snmp_encryption_protocol': 'AES', 'log_snmp_encryption_protocol2': '', 'log_snmp_inform_servers': [{'authkey': '<hash>', 'authproto': 'SHA', 'port': <port>, 'privkey': '<hash>', 'privproto': 'AES', 'secname': '<ro username>', 242 Security Analytics Reference Guide Security Analytics 8.1 'server': '<hostname>', 'version': [1|3]}], 'log_snmp_ro_community': 'public', 'log_snmp_ro_user': 'public', 'log_snmp_ro_user2': '', 'log_snmp_snmpdenable': [True|False], 'log_snmp_trap_community': '***************************', 'log_snmp_trap_servers': [{'authkey': '<hash>', 'authproto': 'SHA', 'port': <port>, 'privkey': '<hash>', 'privproto': 'AES', 'secname': '<ro username>', 'server': '<hostname>', 'version': [1|3]}], 'log_snmp_version': '[1|3]', 'log_syslog_coalescing': [0|1], 'log_syslog_facility': <integer>, 'log_syslog_servers': [{'port': <port>, 'protocol': '<protocol>', 'server': '<hostname>'}], 'smtp_valid': [True|False], 'snmp_valid': [True|False], 'syslog_valid': [True|False]}, 'resultCode': 'API_SUCCESS_CODE', Get remote-notification templates for rules API Path /settings/all_templates Description Retrieve all remote-notification templates for the rules GUI Location Menu > Analyze > Rules > [New | Edit Rule] > Remote Notifications > [SNMP | Syslog | SMTP] Output array Parameters None Python Example s.callAPI("GET","/settings/all_templates") PHP Example callAPI('GET','/settings/all_templates'); Output 'result': {'pageCount': 0, 'rows': [{'appliance_id': 0, 'creatable': False, 243 Security Analytics Reference Guide Security Analytics 8.1 'deletable': False, 'last_modified_date': '<YYYY-MM-DD hh:ii:ss>.529927', 'name': 'CEF Template', 'template_format_str': '|,,ipv4_initiator,port_initiator,ipv4_responder,port_ responder,start_time,', 'type': 'Syslog', 'ui_data': '{"uuid":null,"type":"syslog","name":"CEF ' 'Template","ui_data":"","template_format_str":"","email_ subject":"","delimiter":"|","keyvaluepair":["ipv4_initiator","port_initiator","ipv4_ responder","port_responder","start_time"],"templateOutput":"|,ipv4_ initiator=\\"\\",port_initiator=\\"\\",ipv4_responder=\\"\\",port_ responder=\\"\\",start_time=\\"\\",","ext":"json"}', 'uuid': '5b8f0267-7aa0-4941-9338-69307f000001'}, ... {'appliance_id': 0, 'creatable': False, 'deletable': False, 'last_modified_date': '<YYYY-MM-DD hh:ii:ss>.983576', 'name': 'Web Reputation', 'template_format_str': ',,,http_uri,mime_type,application_id,ip_protocol,ipv4_ initiator,ipv4_responder,ipv6_initiator,ipv6_responder,port_initiator,port_ responder,', 'type': 'Syslog', 'ui_data': '{"uuid":null,"type":"syslog","name":"Web ' 'Reputation","ui_data":"","template_format_str":"","email_ subject":"","delimiter":",","keyvaluepair": ' '["http_uri","mime_type","application_id","ip_protocol","ipv4_initiator","ipv4_ responder","ipv6_initiator","ipv6_responder","port_initiator","port_ responder"],"ext":"json"}', 'uuid': '5b8f0293-7b68-4d9e-8253-69307f000001'}]}, 'resultCode': 'API_SUCCESS_CODE', Get global email API Path /settings/global_email Description Retrieve the global communications email GUI Location Menu > Settings > Communication > Server Settings > Default Email Address Output array Parameters None Python Example s.callAPI("GET","/settings/global_email") PHP Example callAPI('GET','/settings/global_email'); 244 Security Analytics Reference Guide Security Analytics 8.1 Output 'result': {'global_communicationi_email': [True|False]}, 'resultCode': 'API_SUCCESS_CODE', Get audit log information API Path /statistics/filter_options Description Get priorities, categories, and events for the Audit Log GUI Location Menu > Settings > Audit Log Output array Parameters None Python Example s.callAPI("GET","/statistics/filter_options") PHP Example callAPI('GET','/statistics/filter_options'); Output 'result': {'category': ['Miscellaneous', 'System Events', ... 'Rule Events', 'Anomaly Events'], 'event': ['Change IP Address', 'Change Gateway', ... 'YARA Rules Default Restored', 'Metadata'], 'priority': ['Emergency', 'Alert', ... 'Informational', 'Debug']}, 'resultCode': 'API_SUCCESS_CODE', Get CSV of log entries API Path /statistics/save_log 245 Security Analytics Reference Guide Security Analytics 8.1 Description Download Audit Log entries as a comma-delimited file (CSV) GUI Location Menu > Settings > Audit Log > Download Log Output ApiResultCode Parameters None Python Example s.callAPI("GET","/statistics/save_log") PHP Example callAPI('GET','/statistics/save_log'); Get MIB file API Path /settings/download_logging_mib Description Download a ZIP of the MIB GUI Location Menu > Settings > Communication > Advanced > Download MIB Output ApiResultCode Parameters None Python Example s.callAPI("GET","/settings/download_logging_mib") PHP Example callAPI('GET','/settings/download_logging_mib'); 246 Security Analytics Reference Guide Security Analytics 8.1 Export logging settings API Path /settings/download_logging_settings Description Download logging_config.dat GUI Location Menu > Settings > Communication > Advanced > Export Settings Output ApiResultCode Parameters None Python Example callAPI('GET','/settings/download_logging_settings'); PHP Example callAPI('GET','/settings/download_logging_settings'); Get remote-notification templates API Path /settings/get_templates Description Retrieve the remote-notification templates; this API retrieves the contents of the templates, including the default templates GUI Location Menu > Settings > Communication > Templates Parameters REQ Format Default Valid Inputs Description page integer 1 1–<n> Page to retrieve; first page is 1 limit integer 25 1–100 Number of items per page sort string name name | type Sort-by field direction string ASC ASC | DESC Sort direction 247 Security Analytics Reference Guide Security Analytics 8.1 Python Example s.callAPI("GET","/settings/get_templates", { 'page': 1, 'limit': 20, 'sort': 'type', 'direction': 'DESC' } ) PHP Example callAPI('GET','/settings/get_templates', array( 'page' => 1, 'limit' => 20, 'sort' => 'type', 'direction' => 'DESC' ) ); Output 'paging': {'AlertTemplates': {'count': <integer>, 'current': <integer>, 'limit': <integer>, 'nextPage': [True|False], 'options': {'conditions': [], 'order': {'AlertTemplates.name': 'asc'}}, 'order': {'AlertTemplates.name': 'asc'}, 'page': <integer>, 'pageCount': <integer>, 'paramType': 'named', 'prevPage': [True|False]}}, 'result': {'pageCount': 1, 'templates': [{'creatable': False, 'deletable': False, 'name': 'CEF Template', 'template_format_str': '|,,ipv4_initiator,port_initiator,ipv4_ responder,port_responder,start_time,', 'type': 'Syslog', 'ui_data': {'delimiter': '|', 'email_subject': '', 'ext': 'json', 'keyvaluepair': ['ipv4_initiator', 'port_initiator', 'ipv4_responder', 'port_responder', 'start_time'], 'name': 'CEF Template', 'templateOutput': '|,ipv4_initiator="",port_ initiator="",ipv4_responder="",port_responder="",start_ time="",', 'template_format_str': '', 'type': 'syslog', 'ui_data': '', 'uuid': None}, 'uuid': '<UUID>'}, ... {'creatable': False, 'deletable': False, 'name': 'Web Reputation', 'template_format_str': ',,,http_uri,mime_type,application_id,ip_ protocol,ipv4_initiator,ipv4_responder,ipv6_initiator,ipv6_ responder,port_initiator,port_responder,', 'type': 'Syslog', 'ui_data': {'delimiter': ',', 'email_subject': '', 248 Security Analytics Reference Guide Security Analytics 8.1 'ext': 'json', 'keyvaluepair': ['http_uri', 'mime_type', 'application_id', 'ip_protocol', 'ipv4_initiator', 'ipv4_responder', 'ipv6_initiator', 'ipv6_responder', 'port_initiator', 'port_responder'], 'name': 'Web Reputation', 'template_format_str': '', 'type': 'syslog', 'ui_data': '', 'uuid': None}, 'uuid': '<UUID>'}]}, 'resultCode': 'API_SUCCESS_CODE', Get logging categories API Path /settings/logging_categories Description Retrieve the categories for the Audit Log GUI Location n Menu > Settings > Communications > Advanced > Remote Notifications n Menu > Settings > Audit Log Parameters None Python Example s.callAPI("GET","/settings/logging_categories") PHP Example callAPI('GET','/settings/logging_categories'); Output 'result': {'categories': {'action': {'email': 0, 'local': 1, 'snmp': 0, 'syslog': 0}, 'alerts': {'email': 0, 'local': 1, 'snmp': 0, 'syslog': 0}, 'anomaly': {'email': 0, 'local': 1, 249 Security Analytics Reference Guide Security Analytics 8.1 'snmp': 0, 'syslog': 0}, 'capture': {'email': 0, 'local': 1, 'snmp': 0, 'syslog': 0}, 'deepsee': {'email': 0, 'local': 1, 'snmp': 0, 'syslog': 0}, 'enrichment': {'email': 0, 'local': 1, 'snmp': 0, 'syslog': 0}, 'favorite': {'email': 0, 'local': 1, 'snmp': 0, 'syslog': 0}, 'hardware': {'email': 0, 'local': 1, 'snmp': 0, 'syslog': 0}, 'indexing': {'email': 0, 'local': 1, 'snmp': 0, 'syslog': 0}, 'misc': {'email': 0, 'local': 1, 'snmp': 0, 'syslog': 0}, 'playback': {'email': 0, 'local': 1, 'snmp': 0, 'syslog': 0}, 'rules': {'email': 0, 'local': 1, 'snmp': 0, 'syslog': 0}, 'system': {'email': 0, 'local': 1, 'snmp': 0, 'syslog': 0}, 'user': {'email': 0, 'local': 1, 'snmp': 0, 'syslog': 0}}}, 'resultCode': 'API_SUCCESS_CODE', Get remote-notification options API Path /settings/logging_options Description Retrieve valid syslog facilities, logging categories, and remote-logging methods for this appliance 250 Security Analytics Reference Guide Security Analytics 8.1 GUI Location Menu > Settings > Communications > Server Settings > Syslog Settings Output array Parameters None Python Example s.callAPI("GET","/settings/logging_options") PHP Example callAPI('GET','/settings/logging_options'); Options 'result': {'logging_categories': ['misc', 'system', 'user', 'playback', 'capture', 'deepsee', 'hardware', 'rules', 'alerts', 'indexing', 'enrichment', 'favorite', 'action', 'anomaly'], 'logging_methods': ['local', 'email', 'snmp', 'syslog'], 'logging_syslog_facilities': {'0': 'Kernel', '1': 'User', '10': 'AuthPriv', '11': 'FTP', '16': 'Local Use 0 (local0)', '18': 'Local Use 2 (local2)', '19': 'Local Use 3 (local3)', '2': 'Mail', '20': 'Local Use 4 (local4)', '21': 'Local Use 5 (local5)', '22': 'Local Use 6 (local6)', '3': 'Daemon', '4': 'Auth', '5': 'SysLog', '6': 'LPR', '7': 'News', '8': 'UUCP', '9': 'Cron'}}, 'resultCode': 'API_SUCCESS_CODE', 251 Security Analytics Reference Guide Security Analytics 8.1 Configure communication settings — MODIFIED For this API, all unspecified fields will reset to default (null, false); therefore, it is recommended that you include a value for all fields during an edit to avoid losing permissions or other essential characteristics. API Path /settings/logging_settings Description Configure settings for SMTP, SNMP, syslog, ICDx remote notifications, and Splunk Phantom GUI Location Menu > Settings > Communication > Server Settings Output Boolean Parameters REQ Format X array — <GET: /settings/logging_ settings> Settings for logging and communication; array must contain all other parameters log_icdx_exchange string — <UTF-8 characters> Name of ICDx exchange (new) log_icdx_password string — <UTF-8 characters> Password for the ICDx server (new) log_icdx_port integer — 5671 | 5672 5672 — If icdx_ ssl = false 5671 — If icdx_ ssl=true log_icdx_server string — <hostname> | <IP_address> Hostname of the ICDx server (new) log_icdx_username string — <UTF-8 characters> Username for the ICDx server (new) settings Default 252 Valid Inputs Description Security Analytics Reference Guide Security Analytics 8.1 REQ Format Default Valid Inputs log_phantomcyber_key string — <hex> API key for the Splunk Phantom server (new) log_phantomcyber_ server string — <hostname> | <IP_address> Hostname or IP of the Splunk Phantom server (new) log_snmp_version integer 1 1 | 3 log_snmp_ro_community string public <UTF-8 characters> Read-only community name log_snmp_ro_user string public <UTF-8 characters> Read-only user name log_snmp_ro_user2 string — <UTF-8 characters> Second readonly user name (new) log_snmp_auth_ protocol string SHA SHA Authentication protocol; valid only if log_ snmp_ version=3; only SHA is valid log_snmp_auth_ protocol2 string SHA SHA Second authentication protocol (new) ; valid only if log_ snmp_ version=3; only SHA is valid log_snmp_auth_ password string — <UTF-8 characters> Authentication password; valid only if log_ snmp_ version=3 log_snmp_auth_ password2 string — <UTF-8 characters> Second authentication password (new) ; valid only if log_snmp_ version=3 253 Description SNMP version; 1=SNMPv2, 3=SNMPv3 Security Analytics Reference Guide Security Analytics 8.1 REQ Format Default log_snmp_encryption_ protocol string AES AES Privacy encryption protocol; valid only if log_ snmp_ version=3; only AES is valid log_snmp_encryption_ protocol2 string AES AES Second privacy encryption protocol (new) ; valid only if log_ snmp_ version=3; only AES is valid log_snmp_encryption_ password string — <UTF-8 characters> Privacy encryption password; valid only if log_ snmp_ version=3 log_snmp_encryption_ password2 string — <UTF-8 characters> Second privacy encryption password (new) ; valid only if log_snmp_ version=3 log_snmp_trap_ community string — <UTF-8 characters> SNMP trap community name log_snmp_authtrap Boolean false true | false True — Enable Authtrap log_snmp_snmpdenable Boolean false true | false True — Enable SNMP polling array — — Inform server; array must contain position, server, port, version, and optionally secname, authproto, authkey, privproto, and privkey log_snmp_inform_ servers 254 Valid Inputs Description Security Analytics Reference Guide Security Analytics 8.1 REQ Format Default Valid Inputs integer — — Position in the list of servers of the same type. First position is 0. server string — <hostname> | <IP_address> SNMP server hostname or IP port integer 162 1—65536 SNMP server port; contained in server arrays version integer 1 1 | 3 SNMP version; 1=SNMPv2; contained in server arrays secname string — <UTF-8 characters> Required if version=3; read-only username; contained in server arrays authproto string SHA SHA Required if version=3; authentication protocol; only SHA is valid; contained in server arrays authkey string — <UTF-8 characters> Required if version=3; authentication password; contained in server arrays privproto string AES AES Required if version=3; privacy protocol; only AES is valid; contained in server arrays position 255 Description Security Analytics Reference Guide Security Analytics 8.1 REQ Format Default Valid Inputs Description privkey string — <UTF-8 characters> Required if version=3; privacy encryption password; contained in server arrays log_snmp_trap_servers array — — Trap server; array must contain position, server, port, version, and optionally secname, authproto, authkey, privproto, and privkey integer 0 <GET: /settings/logging_ settings> Syslog facility Boolean false true | false protocol string udp tcp | udp | tls | tls-fips log_syslog_servers array — — Syslog server; array must contain position, server, port, protocol log_email_address string — <user>@<domain>.<tld> Default email address log_email_smtp_server string — <hostname> | <ip_address> SMTP server log_email_smtp_port integer 25 1–65536 SMTP server port log_email_smtp_ username string — <UTF-8 characters> SMTP username log_email_smtp_ password string — <UTF-8 characters> SMTP password log_syslog_facility log_syslog_coalescing 256 True — Enable syslog coalescing Protocol to send syslog messages Security Analytics Reference Guide Security Analytics 8.1 REQ Format Default log_email_auth_ optional Boolean false true | false True — SMTP authentication required log_email_use_ starttls Boolean false true | false True — Use STARTTLS string — <user>@<domain>.<tld> log_email_sender Valid Inputs Python Example Configure the SMTP server, an SNMP inform server, an SNMP trap server, and two syslog servers. s.callAPI("POST","/settings/logging_settings", { 'settings': { 'log_email_address': 'sysadmin@domain.com', 'log_email_sender': 'SA-24@domain.com', 'log_email_smtp_server': '203.0.113.5', 'log_email_smtp_port': 25, 'log_email_auth_optional': 0, 'log_email_smtp_username': 'admin', 'log_email_smtp_password': 'smtp_password', 'log_email_use_starttls': 1, 'log_global_communication_email': 'SA-27@domain.com', 'log_icdx_username': 'admin', 'log_icdx_password': 'h@ckm3n0t', 'log_icdx_server': '198.51.100.24', 'log_icdx_port': 5671, 'log_icdx_exchange': 'SA-24', 'log_icdx_ssl': True, 'log_icdx_ssl_verify_certificate': False, 'log_phantomcyber_server': '198.51.100.157', 'log_phantomcyber_key': '<key>', 'log_snmp_snmpdenable': 1, 'log_snmp_ro_user': 'public', 'log_snmp_ro_community': 'public', 'log_snmp_version': 1, 'log_snmp_auth_protocol': 'SHA', 'log_snmp_auth_password': 'snmp_auth_password', 'log_snmp_encryption_protocol': 'AES', 'log_snmp_encryption_password': 'snmp_encrypt_password', 'log_snmp_trap_community': 'snmp_trap_name', 'log_snmp_inform_servers': [ { 'position': 0, 'server': '203.0.113.6', 'port': 162, 'community': 'roinform', 'version': 3, 'secname': '444_inform', 'auth_protocol': 'SHA', 'auth_password': 'auth_password', 'encryption_protocol': 'AES', 'encryption_password': 'encrypt_password' } ], 'log_snmp_trap_servers': [ { 'position': 0, 'server': '203.0.113.7', 'port': 162, 257 Description Email address for the FROM field Security Analytics Reference Guide Security Analytics 8.1 'community': '999_inform', 'version': 3, 'secname': '999_trap', 'auth_protocol': 'SHA', 'auth_password': 'auth_password', 'encryption_protocol': 'AES', 'encryption_password': 'encrypt_password' } ], 'log_snmp_authtrap': 1, 'log_syslog_coalescing': 1, 'log_syslog_facility': 16, 'log_syslog_servers': [ { 'position': 0, 'server': '203.0.113.8', 'port': 514, 'protocol': 'tls-fips' }, { 'position': 1, 'server': '203.0.113.9', 'port': 55514, 'protocol': 'udp' } ] } }) PHP Example Configure the SMTP server, an SNMP inform server, an SNMP trap server, and two syslog servers. callAPI('POST','/settings/logging_settings', array('settings'=> array( 'log_email_address' => 'sysadmin@domain.com', 'log_email_sender' => 'SA-24@domain.com', 'log_email_smtp_server' => '203.0.113.5', 'log_email_smtp_port' => 25, 'log_email_auth_optional' => 0, 'log_email_smtp_username' => 'admin', 'log_email_smtp_password' => 'smtp_password', 'log_email_use_starttls' => 1, 'log_global_communication_email' => 'SA-27@domain.com', 'log_snmp_snmpdenable' => 1, 'log_snmp_ro_user' => 'public', 'log_snmp_ro_community' => 'public', 'log_snmp_version' => 1, 'log_snmp_auth_protocol' => 'SHA', 'log_snmp_auth_password' => 'snmp_auth_password', 'log_snmp_encryption_protocol' => 'AES', 'log_snmp_encryption_password' => 'snmp_encrypt_password', 'log_snmp_trap_community' => 'snmp_trap_name', 'log_snmp_inform_servers' => array( array( 'position' => 0, 'server' => '203.0.113.6', 'port' => 162, 'community' => 'roinform', 'version' => 3, 'secname' => '444_inform', 'auth_protocol' => 'SHA', 'auth_password' => 'auth_password', 'encryption_protocol' => 'AES', 'encryption_password' => 'encrypt_password' ) ), 258 Security Analytics Reference Guide Security Analytics 8.1 'log_snmp_trap_servers' => array( array( 'position' => 0, 'server' => '203.0.113.7', 'port' => 162, 'community' => '999_inform', 'version' => 3, 'secname' => '999_trap', 'auth_protocol' => 'SHA', 'auth_password' => 'auth_password', 'encryption_protocol' => 'AES', 'encryption_password' => 'encrypt_password' ) ), 'log_snmp_authtrap' => 1, 'log_syslog_coalescing' => 1, 'log_syslog_facility' => 16, 'log_syslog_servers' => array( array( 'position' => 0, 'server' => '203.0.113.8', 'port' => 514, 'protocol' => 'tls-fips' ), ( 'position' => 1, 'server' => '203.0.113.9', 'port' => 55514, 'protocol' => 'udp' ) ) ) ) )) Enable or disable remote-notification types API Path /settings/logging_categories Description Enable and disable remote notifications per category and method GUI Location Menu > Settings > Communication > Advanced > Remote Notifications Output Boolean 259 Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ Format Default categories X array — Valid Inputs array( 'categories' => array( '<GET: /settings/logging_ categories>' => array( '<method>' => [true | false], '<method>' => [true | false] ), '<GET: /settings/logging_ categories>' => array( '<method>' => [true | false], '<method>' => [true | false] ) ) Description n category — Audit Log categories n method — local, email, snmp, syslog o n Python Example s.callAPI("POST","/settings/logging_categories", { 'categories': { 'system': { 'email': True, 'snmp': True, 'syslog': True, 'local: False }, 'alert': { 'snmp': True, 'syslog': True, 'local': False }, 'capture': array( 'snmp': False, 'syslog': False, 'local': False } } ) PHP Example callAPI('POST','/settings/logging_categories', array( 'categories' => array( 'system' => array( 'email' => true, 'snmp' => true, 'syslog' => true, 'local' => false ), 'alert' => array( 'snmp' => true, 'syslog' => true, 'local' => false ), 'capture' => array( 'snmp' => false, 'syslog' => false, 'local' => false ) ) ) ); 260 email method is not valid for the deepsee (Report Events) category Unspecified categories or methods are set to false Security Analytics Reference Guide Security Analytics 8.1 Configure a remote-notification template API Path /settings/save_template Description Save a remote-notification template GUI Location Menu > Settings > Communications > Templates > New Output array Parameters REQ uuid name type Format UUID | null X string Default null Valid Inputs null | <GET: /settings/get_ templates> <UTF-8 characters> Description n Create new — Use null n Edit entry — UUID required n Create new — Name required n Edit entry — New name X string smtp | snmp | syslog X string <UTF-8 characters> Valid only if type=smtp; subject line of email delimiter X string ; | <> | \ | : | , | {} | "" | / | () | . | | | ' | \s | () | \t Character to delimit key/value pairs keyvaluepair X string <primary_filter_attribute> Attributes from the primary filter email_ subject Python Example s.callAPI("POST","/settings/save_template", { 'uuid': null, 'name': 'snmp-00', 'type': 'snmp', 'email_subject': 'SNMP message', 'delimiter': ';', 'keyvaluepair': [ 'application_id', 'country', 'ipv4_responder', 'port_responder' ] 261 Type of template Security Analytics Reference Guide Security Analytics 8.1 } ) PHP Example callAPI('POST','/settings/save_template', array( 'uuid' => null, 'name' => 'snmp-00', 'type' => 'snmp', 'email_subject' => 'SNMP message', 'delimiter' => ';', 'keyvaluepair'=> array( 'application_id', 'country', 'ipv4_responder', 'port_responder' ) ) ) ); Clear the audit log API Path /settings/erase_log Description Clear all audit log entries GUI Location Menu > Settings > Communication > Advanced > Clear Log Entries Output [null] Parameters None Python Example s.callAPI("POST","/settings/erase_log") PHP Example callAPI('POST','/settings/erase_log'); Upload a new settings file API Path /settings/logging_advanced 262 Security Analytics Reference Guide Security Analytics 8.1 Description Upload a new communication settings file, which overwrites the old settings GUI Location Menu > Settings > Communication > Browse > Import Communication Settings Output Boolean Parameters REQ Format X file file Default Valid Inputs — <filename>.dat Description DAT-formatted settings file Python Example s.callAPI("POST","settings/logging_advanced", { 'file': '<filename>.dat' } ) PHP Example callAPI('POST','settings/logging_advanced', array( 'file' => '<filename>.dat' ) ); Delete template API Path /settings/delete_template/<id> Description Delete a remote-notification template GUI Location Menu > Settings > Communication > Templates Output Boolean Parameters id REQ Format X UUID Default — Valid Inputs Description <GET: /settings/get_templates> Template ID 263 Security Analytics Reference Guide Security Analytics 8.1 Python Example s.callAPI("POST","settings/delete_template/<template_id>") PHP Example callAPI('POST','settings/delete_template/<template_id>'); n placeholder n All Files 264 Security Analytics Reference Guide Security Analytics 8.1 Location: Metadata APIs To see all APIs click the Expand All icon at the top of the page. 265 Security Analytics Reference Guide Security Analytics 8.1 266 Security Analytics Reference Guide Security Analytics 8.1 © 2019 Symantec Corporation | Security Analytics 8.1 | Updated: Wednesday, August 7, 2019 About | Support | Feedback | Forums version of online help might not contain the most up-to-date information. For the current documentation, go to Security Analytics Product Documentation. 267 Security Analytics Reference Guide Security Analytics 8.1 Network APIs Get network settings API Path /settings/network Description Retrieve network settings for the appliance GUI Location n Initial Configuration n Menu > Settings > Network Output array Parameters None Example callAPI('GET','/settings/network'); Configure the management interface API Path /settings/network/management_interfaces Description Configure the bond0 management interface with one or two physical interfaces. GUI Location Menu > Settings > Network > Use Multiple Management Interfaces Parameters management_interfaces REQ Format Default Valid Inputs X string — eth<X> 268 Description Physical interfaces on the appliance (limit:2) Security Analytics Reference Guide Security Analytics 8.1 Example s.callAPI("POST","/settings/network/management_interfaces", { 'management_interfaces': [ 'eth0', 'eth1' ] }) Restart network interfaces API Path /settings/network/restart Description Restart the network interfaces, including the capture interfaces GUI Location n/a Parameters None Example callAPI('POST','/settings/network/restart'); Configure appliance name API Path /settings/network/system_name Description Set or edit system name GUI Location n Initial Configuration n Menu > Settings > Network Output API_REBOOT_CODE Parameters system_name REQ Format Default Valid Inputs X string — <UTF-8 characters> 269 Description Host name of appliance Security Analytics Reference Guide Security Analytics 8.1 Example callAPI('POST','/settings/network/system_name', array( 'system_name' => 'SA-0143' ) ); Configure IP settings API Path /settings/network/ip_address Description Set or edit IP addresses GUI Location n Initial Configuration n Menu > Settings > Network Output ApiResultCode Parameters REQ Format Default Valid Inputs Description Boolean false true | false True — Enable DHCP and ignore the rest of the settings ip_address string — <dotted-decimal> IPv4 address for bond0 ip_address_secondary string — <dotted-decimal> Secondary IPv4 address for bond0 netmask string — <dotted-decimal> Network mask netmask_secondary string — <dotted-decimal> Secondary network masks gateway string — <dotted-decimal> Gateway gateway_secondary string <dotted-decimal> Secondary gateways ipv6_address string — ipv6_secondaries string — ipv6_gateway string — dhcp [<ipv6>] Primary IPv6 address for bond0 [<ipv6>],[<ipv6>] Secondary IPv6 addresses for bond0, comma-delimited [<ipv6>] Example callAPI('POST','/settings/network/ip_address', array( 'dhcp' => false, 'ip_address' => '203.0.113.5', 'netmask' => '255.255.255.0', 270 IPv6 gateway Security Analytics Reference Guide Security Analytics 8.1 'gateway' => '203.0.113.1', 'ipv6_address' => '[2026:fe33:21:a1:a5f7::0a02]' 'ipv6_secondaries' => '[2001:0db8::ff90:0a02]','[fc00::20ad:0045]' 'ipv6_gateway' => '[2026:fe33:21:a1::1]' ) ); Configure DNS API Path /settings/network/dns Description Create or edit DNS settings GUI Location n Initial Configuration n Menu > Settings > Network Output ApiResultCode Parameters REQ Format Default Valid Inputs Description X string — <ip_address> Primary DNS server secondary_dns string — <ip_address> Secondary DNS server tertiary_dns string — <ip_address> Tertiary DNS server override_dns Boolean false true | false True — Override DNS checks and forcesave the settings primary_dns Example callAPI('POST','/settings/network/dns', array( 'primary_dns' => '203.0.113.5', 'secondary_dns' => '203.0.113.6', 'tertiary_dns' => '2620:aa:3001:55:faff::5', 'override_dns' => true ) ); 271 Security Analytics Reference Guide Security Analytics 8.1 Configure HTTP proxy API Path /settings/network/http_proxy Description Create or edit HTTP proxy settings GUI Location n Initial Configuration n Menu > Settings > Network Output API_REBOOT_CODE Parameters http_proxy REQ Format Default X string — Example callAPI('POST','/settings/network/http_proxy', array( 'http_proxy' => 'http://203.0.113.5:8080' ) ); Configure No Proxy settings API Path /settings/network/no_proxy Description Set the No Proxy settings GUI Location n Initial Configuration n Menu > Settings > Network Output API_REBOOT_CODE 272 Valid Inputs Description http:// <hostname> :<port> Web proxy server Security Analytics Reference Guide Security Analytics 8.1 Parameters no_proxy REQ Format Default Valid Inputs X string — <domain> .<tld> | <ip_ address> Example callAPI('POST','/settings/network/no_proxy', array( 'no_proxy' => 'symantec.com,203.0.113.5' ) ); 273 Description Comma-delimited list of domains or IP addresses to bypass the proxy. Security Analytics Reference Guide Security Analytics 8.1 Packet Analyzer APIs Get packet analyzer summary API Path /packet_analyzer/packets Description Retrieve packet analyzer summary data GUI Location n Menu Packets > Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > Actions > Analyze n Menu > Analyze > Summary > Extractions > [artifact entry] > Analyze PCAP Output array Parameters REQ pcap Format Default Valid Inputs Description string — /timespan/<YYYY-MMDD>T<hh:ii:ss> _<YYYY-MMDD>T<hh:ii:ss>/data.pcap[ng] startPacket integer 1 1–<n> Packet number of the first packet to retrieve within the pcap timespan packetCount integer 1000 1–1000 Number of packets to retrieve filter string — <Wireshark display filter> X PCAP path Filter in Wireshark format Example callAPI('GET','/packet_analyzer/packets', array( 'pcap' => '/timespan/2019-11-23T00:00:00_2019-11-23T00:25:59/data.pcapng', 'startPacket' => 25, 'packetCount' => 1000, 'filter' => 'ip.src==192.0.2.0/24 and ip.dst==203.0.113.0/24' ) ); Get packet details API Path /packet_analyzer/detail 274 Security Analytics Reference Guide Security Analytics 8.1 Description Retrieve details about a specific packet. GUI Location n Menu > Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > Actions > Analyze Packets > [click packet; second panel] n Menu > Analyze > Summary > Extractions > [artifact entry] > Analyze PCAP > [click packet; second panel] Output array Parameters REQ pcap X packet Format Default /timespan/<YYYY-MM-DD>T<hh:ii:ss>_ <YYYY-MM-DD>T<hh:ii:ss>/data.pcap [ng] string integer Valid Inputs 1 <GET: /packet_analyzer/packets> Description PCAP path ID of the packet to retrieve Example callAPI('GET','/packet_analyzer/detail' array( 'pcap' => '/timespan/2019-11-23T00:00:00_2019-11-23T00:25:59/data.pcapng', 'packet' => '300' ), ); Get PCAP from packet analyzer API Path /packet_analyzer/download Description Download a PCAP from the packet analyzer GUI Location n Menu > Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > Actions > Analyze Packets > Download PCAP n Menu > Analyze > Summary > Extractions > [artifact entry] > Analyze PCAP > Download PCAP Output ApiResultCode 275 Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ Format Default X string — pcapType string pcapng pcap | pcapng filter string — <Wireshark display filter> pcap Valid Inputs Description /timespan/<YYYY-MM-DD>T<hh:ii:ss>_ PCAP path <YYYY-MM-DD>T<hh:ii:ss>/data.pcap[ng] If filter is specified, pcapType=pcap Filter in Wireshark format Example callAPI('GET','/packet_analyzer/download' array( 'pcap' => '/timespan/2019-11-23T00:00:00_2019-11-23T00:25:59/data.pcap', 'pcapType' => 'pcap' 'filter' => 'ip.src==192.0.2.0/24 and ip.dst==203.0.113.0/24' ) ); 276 Security Analytics Reference Guide Security Analytics 8.1 PCAP APIs Get estimated PCAP size API Path /deepsee_reports/pcapsize Description Retrieve the estimated size of the PCAP GUI Location Menu > Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > [More Information | Actions > Download PCAP] Output array Parameters REQ Format query X array timespan X JSON Default Valid Inputs Description — <primary filter array> Primary filter — <timespan array> Python Example s.callAPI("GET","deepsee_reports/pcapsize", { 'query': [ 'port>50000', 'application_id=dns,http' ], 'timespan': json.dumps({ 'start': '2019-11-03T10:00:00', 'end': '2019-11-03T10:10:00' }) } ) PHP Example callAPI('GET','deepsee_reports/pcapsize', array( 'query' => array( 'port>50000', 'application_id=dns,http' ), 'timespan' => json_encode( array( 'start' => '2019-11-03T10:00:00', 'end' => '2019-11-03T10:10:00' ) ) ) ); 277 Start and end times for the PCAP Security Analytics Reference Guide Security Analytics 8.1 Download a PCAP from indexing drive parameters API Path /pcap/download/deepsee Description Download a PCAP according to Indexing DB parameters GUI Location n/a Output ApiResultCode Parameters REQ Format path X string — <Indexing DB path> PCAP path name X string — <UTF-8 characters> Name for the file pcapType string pcapng pcap | pcapng download array — integer — type mountId string Default — Valid Inputs Description PCAP format Download parameters; array includes type and mountId 1 | 2 | 3 <GET: /pcap_ import/mount_points> Download type n 1 — Browser n 2 — NFS/CIFS n 3 — Prepare download Mount point IDs; valid if type=2 Python Example s.callAPI("GET","/pcap/download/deepsee",{ 'path': '/timespan/2019-11-23T00:00:00_2019-11-23T00:21:59/application_ id/runescape/country/china/ip_responder/48.55.187.0/24', 'name': '2019-11-23_china-runescape', 'pcapType': 'pcap', 'download': { 'type': 2, 'mountId': '<mount_id>' } }, '<filename>.pcap' ) PHP Example callAPI('GET','/pcap/download/deepsee', array( 278 Security Analytics Reference Guide Security Analytics 8.1 'path' => '/timespan/2019-11-23T00:00:00_2019-11-23T00:21:59/application_ id/runescape/country/china/ip_responder/48.55.187.0/24', 'name' => '2019-11-23_china-runescape', 'pcapType' => 'pcap', 'download' => array( 'type' => 2, 'mountId' => '<mount_id>' ) ), <filename>.pcap ); Download PCAP from merge path using path parts API Path /pcap/download/merge Description Download a PCAP from /pfs/merge using path parts GUI Location Menu > Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > [More Information | Actions > Download PCAP] > PCAP without PCAP Filters download Output ApiResultCode Parameters REQ Format X array ethX| aggX| ifbX Capture interface(s) start X string <YYYY-MM-DD>T<hh:ii:ss> Start date and time stop X string <bytes>|<YYYY-MMDD>T<hh:ii:ss> interfaces type string filter string Default date Valid Inputs size | date <BPF expression> Python Example s.callAPI("GET","/pcap/download/merge", { 'interfaces': [ 'eth2', 'eth3', 'agg1' ], 'start': '2019-11-23T00:00:00', 'stop': '2019-11-23T00:07:59', 'type': 'date', 'filter': '(net 203.0.113.0 mask 255.255.248.0)' 279 Description n If type=size then stop=<bytes> n If type=date then stop=<YYYYMM-DD>T<hh:ii:mm> Method to calculate stop Capture filter Security Analytics Reference Guide Security Analytics 8.1 }, '<filename>.pcap' ) PHP Example callAPI('GET','/pcap/download/merge', array( 'interfaces' => array( 'eth3', 'eth3', 'agg1' ), 'start' => '2019-11-23T00:00:00', 'stop' => '2019-11-23T00:07:59', 'type' => 'date', 'filter' => '(net 203.0.113.0 mask 255.255.248.0)' ), <filename>.pcap ); Download a PCAP from merge path API Path /pcap/download/merge_path Description Download a PCAP from /pfs/merge GUI Location n/a Output ApiResultCode Parameters REQ Format Default path filter X merge path string — — Valid Inputs Description [<ethX>:]<ethX>-<MM.DD.YYYY.hh.ii.ss>:d<MM.DD.YYYY.hh.ii.ss>:d Time-delimited end [<ethX>:]<ethX>-<MM.DD.YYYY.hh.ii.ss>:d<bytes>:s Size-delimited end <BPF expression> Python Example s.callAPI("GET","/pcap/download/merge_path",{ 'path': 'eth3:agg1-2019.11.23.00.00.00:d-2019.11.23.00.07.59:d', 'filter': '(net 203.0.113.0 mask 255.255.248.0)' }, '<filename>.pcap' ) 280 Capture filter Security Analytics Reference Guide Security Analytics 8.1 PHP Example callAPI('GET','/pcap/download/merge_path', array( 'path' => 'eth3:agg1-2019.11.23.00.00.00:d-2019.11.23.00.07.59:d', 'filter' => '(net 203.0.113.0 mask 255.255.248.0)' ), <filename>.pcap ); Download PCAP using primary filter path API Path /pcap/download/query Description Download a PCAP using the primary filter path GUI Location Menu > Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > [More Information > Download | Actions > Download PCAP] Output ApiResultCode Parameters REQ Format X JSON — <timespan array> query array — <primary filter array> pcapType string pcapng pcap | pcapng download array — integer — timespan type mountId filter X Default Valid Inputs Description Start and end times for the PCAP Primary bar filters PCAP format Download parameters; array includes type and mountId 1 | 2 | 3 string — <GET: /pcap_ import/connections> string — <BPF expression> Python Example s.callAPI("GET","/pcap/download/query", { 'timespan': { 'start': '2019-11-23T00:00:00', 'end': '2019-11-23T00:07:59' 281 Download type n 1 — Browser n 2 — NFS/CIFS n 3 — Prepare download Mount point IDs; valid if type=2 Capture filter to apply to the PCAP Security Analytics Reference Guide Security Analytics 8.1 }, 'query': [ 'port=80', 'filename~exe' ], 'pcapType': 'pcap', 'download': { 'type': '2', 'mountId': '<mount_id>' } 'filter': '(net 203.0.113.0 mask 255.255.248.0)' }, '<filename>.pcap' ) PHP Example callAPI('GET','/pcap/download/query', array( 'timespan' => json_encode( array( 'start' => '2019-11-23T00:00:00', 'end' => '2019-11-23T00:07:59' ), ), 'query' => array( 'port=80', 'filename~exe' ), 'pcapType' => 'pcap', 'download' => array( 'type' => '2', 'mountId' => '<mount_id>' ) 'filter' => '(net 203.0.113.0 mask 255.255.248.0)' ), <filename>.pcap ); Python Example s.callAPI("GET","/pcap/download/query", { 'timespan': { 'start': '2019-11-23T00:00:00', 'end': '2019-11-23T00:07:59' }, 'query': [ 'port=80', 'filename~exe' ], 'pcapType': 'pcap', 'download': { 'type': '2', 'mountId': '<mount_id>' } 'filter': '(net 203.0.113.0 mask 255.255.248.0)' }, '<filename>.pcap' ) Get list of mount points API Path /pcap_import/connections Description Retrieve a paginated list of mount points 282 Security Analytics Reference Guide Security Analytics 8.1 GUI Location Menu > Capture > Import PCAP > Manage Connections Output array Parameters page REQ Format Default Valid Inputs X integer — 1–<n> Page to retrieve; first page is 1 integer 25 1–100 Number of rows per page string asc asc | desc string null limit direction sort Description Sort order mount_id | server_name | port_num | Sort-by field remote_location | username | password | protocol | alias | active | last_modified_date | refcount | export_refcount Python Example s.callAPI("GET","/pcap_import/connections", { 'page': 10, 'limit': 20, 'direction': 'desc', 'sort': 'protocol' } ) PHP Example callAPI('GET','/pcap_import/connections', array( 'page' => 10, 'limit' => 20, 'direction' => 'desc', 'sort' => 'protocol' ) ); Get USB mount point files and folders API Path /pcap_import/explore_local Description Retrieve a list of files and directories in the attached USB directory 283 Security Analytics Reference Guide Security Analytics 8.1 GUI Location Menu > Capture > Import PCAP > Imports > New > Import from Appliance USB Drive Output array Parameters REQ path Format string Default / Valid Inputs / | /<folder_on_usb_drive>/ Description USB directory to explore Python Example s.callAPI("GET","/pcap_import/explore_local", { 'path': '/temp/PCAPs/' } ) PHP Example callAPI('GET','/pcap_import/explore_local', array( 'path' => '/temp/PCAPs/' ) ); Get remote mount point files and folders API Path /pcap_import/explore_remote/<mountId> Description Get remote mount-point files and folders from a specified mount point GUI Location n Menu > Capture > Import PCAP > Manage Connections > Edit n Menu > Capture > Import PCAP > Watch Folders > New n Menu > Analyze > Rules > [New | Edit] > PCAP Export Server n Menu > Capture > Import PCAP > Imports > New > Import from Remote Server Output array 284 Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ Format Default Valid Inputs X integer — <GET: /pcap_import/connections> string / /<filepath>/ mountId path Description Mount point ID Folder path Python Example s.callAPI("GET","/pcap_import/explore_remote/<mountId>", { 'path': '/<path>/' } ) PHP Example callAPI('GET','/pcap_import/explore_remote/<mountId>', array( 'path' => '/<path>/' ) ); Get list of PCAP import jobs API Path /pcap_import/jobs/<jobStatus> Description Retrieve a paginated list of jobs, by job status GUI Location Menu > Capture > Import PCAP > Imports Output array Parameters jobStatus REQ Format X integer Default — Valid Inputs 0 | 1 | 2 | 3 | 4 | 5 285 Description Status of jobs to retrieve n 0 — Scheduled n 1 — Queued n 2 — Running n 3 — Complete n 4 — Failed n 5 — Canceled Security Analytics Reference Guide REQ Security Analytics 8.1 Format Default Valid Inputs page integer — 1–<n> Page to retrieve; first page is 1 limit integer — 1–100 Number of items per page string desc asc | desc string null direction sort job_id | schedule_id | mount_id | import_type | iface_name | pcap_file | retain_timestamp | import_status | bytes_written | packets_imported | packets_ dropped | file_size | created_ time | start_time | end_time | result_summary | first_packet_ time | last_packet_time | import_failure_reason | start_ slot_id | start_element | end_ slot_id | end_element | user_id | shared | import_version Python Example s.callAPI("GET","/pcap_import/jobs/<jobStatus>", { 'jobStatus': 3, 'page': 2, 'limit': 25, 'direction': 'asc', 'sort': 'file_size' } ) PHP Example callAPI('GET','/pcap_import/jobs/<jobStatus>', array( 'jobStatus' => 3, 'page' => 2, 'limit' => 25, 'direction' => 'asc', 'sort' => 'file_size' ) ) ); Get all mount points API Path /pcap_import/mount_points Description Retrieve a list of mount points. 286 Description Sort order Sort-by field Security Analytics Reference Guide Security Analytics 8.1 GUI Location n Menu > Capture > Import PCAP > Manage Connections n Menu > Capture > Import PCAP > Watch Folders > New n Menu > Analyze > Rules > [New | Edit] > PCAP Export Server Output array Parameters None Python Example s.callAPI("GET","/pcap_import/mount_points") PHP Example callAPI('GET','/pcap_import/mount_points'); Get a list of watch folders API Path /pcap_import/schedules Description Retrieve a paginated list of watch folders GUI Location Capture > Import PCAP > Watch Folders Output array Parameters REQ Format Default Valid Inputs Description page integer — 1–<n> Page to retrieve; first page is 1 limit integer — 1–100 Number of items per page string desc asc | desc direction 287 Sort direction Security Analytics Reference Guide REQ sort Security Analytics 8.1 Format Default null string Valid Inputs Description schedule_id | mount_id | directory Sort-by field | start_date | end_date | run_freq | retain_timestamp | last_ modified_date | active Python Example s.callAPI("GET","/pcap_import/schedules", { 'page': 10, 'limit': 20, 'direction': 'asc', 'sort': 'schedule_id' } ) PHP Example callAPI('GET','/pcap_import/schedules', array( 'page' => 10, 'limit' => 20, 'direction' => 'asc', 'sort' => 'schedule_id' ) ); Get PCAP upload status API Path /pcap_import/upload_progress/<jobid> Description Retrieve the PCAP upload status GUI Location Menu > Capture > PCAP Import > Imports > Status field Output array Parameters jobid REQ Format X integer Default — Valid Inputs Description <GET: /pcap_import/init_ Job ID upload/<pcapFile>/<retainTimestamp>/<shared> > Python Example s.callAPI("GET","/pcap_import/upload_progress/<jobid>") 288 Security Analytics Reference Guide Security Analytics 8.1 PHP Example callAPI('GET','/pcap_import/upload_progress/<jobid>'); Import PCAP from USB drive API Path /pcap_import/import_local Description Creates a new job and begins importing a PCAP from an attached USB drive. GUI Location Menu > Capture > Import PCAP > Imports > New > Import from Appliance USB Drive Output array Parameters REQ Format files X array — <GET: /pcap_import/explore_ local> retain X integer — 0 | 1 shared Boolean Default Valid Inputs true true | false Python Example s.callAPI("POST","/pcap_import/import_local", { 'files':[ '/pcapng/pcap-004.pcapng', '/pcapng/pcap-005.pcapng' ], 'retain': 0, 'shared': False } ) PHP Example callAPI('POST','/pcap_import/import_local', array( 'files' => array( '/pcapng/pcap-004.pcapng', '/pcapng/pcap-005.pcapng' ), 'retain' => 0, 'shared' => false 289 Description Array of PCAP files on the USB drive n 0 — Do not retain timestamps n 1 — Retain original timestamps True — Shared PCAP Security Analytics Reference Guide Security Analytics 8.1 ) ); Import PCAP from mount point API Path /pcap_import/import_remote Description Creates a new job and begins importing a PCAP from a mount point GUI Location Menu > Capture > Import PCAP > Imports > New > Import from Remote Server Output array Parameters REQ Format files X array — <GET: /pcap_import/explore_ remote/<mountId> retain X integer — 0 | 1 startOffset X shared Default Valid Inputs integer — 1–<n> Boolean true true | false Python Example s.callAPI("POST","/pcap_import/import_remote", { 'files': [ '/pcap/pcap-007.pcap', '/pcap/pcap-008.pcap' ], 'retain': 0, 'startOffset': 3600, 'shared': False } ) PHP Example callAPI('POST','/pcap_import/import_remote', array( 'files' => array( '/pcap/pcap-007.pcap', '/pcap/pcap-008.pcap' ), 'retain' => 0, 290 Description Array of remote locations n 0 — Do not retain timestamps n 1 — Retain original timestamps Number of seconds from now before starting the import. True — Shared PCAP Security Analytics Reference Guide Security Analytics 8.1 'startOffset' => 3600, 'shared' => false ) ); Import PCAP from workstation API Path /pcap_import/init_upload/<pcapFile>/<retainTimestamp>/<shared> Description Creates a new job and begins importing a PCAP from the local workstation GUI Location Menu > Capture > Import PCAP > Imports > New > Import from My Computer Output integer Parameters pcapFile retainTimestamp shared REQ Format X URL encoding — <URL-encoding>.pcap | <URL-encoding>.pcapng X integer — 0 | 1 X integer Default Valid Inputs — 0 | 1 Python Example s.callAPI("POST","/pcap_import/init_upload/HTTP%20from%20China.pcapng/0/1") PHP Example callAPI('POST','/pcap_import/init_upload/HTTP%20from%20China.pcapng/0/1'); 291 Description URL-encoded name of the PCAP file n 0 — Do not retain timestamps n 1 — Retain original timestamps n 0 — Nonshared PCAP n 1 — Shared PCAP Security Analytics Reference Guide Security Analytics 8.1 Upload PCAP chunks API Path /pcap_import/upload/<jobid>/<index>/<chunks> Description After you split up a large PCAP into smaller chunks, use this API to upload the chunks in order, for reassembly. To upload a non-chunked file, set index and chunks to 0. GUI Location n/a Output array Parameters REQ Format Default Valid Inputs Description jobid X integer — index X integer — 0–<n> Position in the sequence of chunks. Zero-based count. chunks X integer — 0–<n> Total number of chunks file X string — <UTF-8 characters> The name of the PCAP file chunk. <GET: /pcap_import/init_ Job ID upload/<pcapFile>/<retainTimestamp>/<shared> > Python Example Original PCAP is named extreme-behemoth.pcapng. You have divided the PCAP into 4 chunks. Create the Job ID, discard the original timestamps, and mark it as shared. s.callAPI("POST","/pcap_import/init_upload/extreme-behemoth.pcapng/0/true") Returns job ID 42. s.callAPI("POST","/pcap_import/upload/42/0/4",{ 'file':'extreme-behemoth.pcapng.chunk1' } ) 292 Security Analytics Reference Guide Security Analytics 8.1 s.callAPI("POST","/pcap_import/upload/42/1/4",{ 'file':'extreme-behemoth.pcapng.chunk2' } ) s.callAPI("POST","/pcap_import/upload/42/2/4",{ 'file':'extreme-behemoth.pcapng.chunk3' } ) s.callAPI("POST","/pcap_import/upload/42/3/4",{ 'file':'extreme-behemoth.pcapng.chunk4' } ) PHP Example Original PCAP is named extreme-behemoth.pcapng. You have divided the PCAP into 4 chunks. Create the Job ID, discard the original timestamps, and mark it as shared. callAPI('POST','/pcap_import/init_upload/extreme-behemoth.pcapng/0/true'); Returns job ID 42. callAPI('POST','/pcap_import/upload/42/0/4', array( 'file' => 'extreme-behemoth.pcapng.chunk1' ) ); callAPI('POST','/pcap_import/upload/42/1/4', array( 'file' => 'extreme-behemoth.pcapng.chunk2' ) ); callAPI('POST','/pcap_import/upload/42/2/4', array( 'file' => 'extreme-behemoth.pcapng.chunk3' ) ); callAPI('POST','/pcap_import/upload/42/3/4', array( 'file' => 'extreme-behemoth.pcapng.chunk4' ) ); Cancel PCAP upload API Path /pcap_import/upload_canceled/<jobid> Description Cancel PCAP upload 293 Security Analytics Reference Guide Security Analytics 8.1 GUI Location Menu > Capture > Import PCAP > Imports > [close browser page | reload browser page] Output array Parameters REQ Format Default X integer — jobid Valid Inputs Description <GET: /pcap_import/init_ Job ID upload/<pcapFile>/<retainTimestamp>/<shared> > Python Example s.callAPI("POST","/pcap_import/upload_canceled/<jobid>") PHP Example callAPI('POST','/pcap_import/upload_canceled/<jobid>'); Mark PCAP upload as failed API Path /pcap_import/upload_failed/<jobid>/<error> Description Mark a PCAP upload job as failed GUI Location Menu > Capture > PCAP Import > Imports > Status field Output array Parameters REQ Format Default jobid X integer — error X integer — Valid Inputs Description <GET: /pcap_import/init_ Job ID upload/<pcapFile>/<retainTimestamp>/<shared> > 0 Python Example s.callAPI("POST","/pcap_import/upload_failed/<jobid>/0") 294 Only 0 (zero) is valid Security Analytics Reference Guide Security Analytics 8.1 PHP Example callAPI('POST','/pcap_import/upload_failed/<jobid>/0'); Add watch folder API Path /pcap_import/watch Description Add a new watch folder GUI Location Menu > Capture > Import PCAP > Watch Folders > New Output array Parameters REQ Format folders X array — <GET: /pcap_import/explore_ remote/<mountId>> retain X integer — 0 | 1 runFreq X integer Default — Valid Inputs 1–<n> Python Example s.callAPI("POST","/pcap_import/watch", { 'folders': [ '%2Ftemp%2Fusers%2Fadmin%2Fpcaps%2F', '%2Ftemp%2Fusers%2Fadmin%2FpcapNGS' ] 'retain': 0, 'runFreq': 10800 } ) PHP Example callAPI('POST','/pcap_import/watch', array( 'folders' => array( '%2Ftemp%2Fusers%2Fadmin%2Fpcaps%2F', '%2Ftemp%2Fusers%2Fadmin%2FpcapNGS' ), 'retain' => 0, 'runFreq' => 10800 ) 295 Description Watch-folder paths, URL-encoded n 0 — Do not retain timestamps n 1 — Retain original timestamps Interval in minutes between folder checks Security Analytics Reference Guide Security Analytics 8.1 ); Delete mount points API Path /pcap_import_mount_points/delete/<ids> Description Delete one or more mount points GUI Location Menu > Capture > Import PCAP > Manage Connections Output array Parameters REQ Format X integer ids Default — Valid Inputs <GET: /pcap_import/connections> Description Comma-delimited list of mountpoint IDs. Python Example s.callAPI("POST","/pcap_import_mount_points/delete/<id1>,<id2>,<id3>") PHP Example callAPI('POST','/pcap_import_mount_points/delete/<id1>,<id2>,<id3>'); Create a PCAP mount point API Path /pcap_import_mount_points/save Description Create a PCAP server mount point GUI Location n Menu > Capture > Import PCAP > Manage Connections > Add New Server n Menu > Analyze > Rules > New > PCAP Export Server > Add New Server n Menu > Capture > Import PCAP > Imports > New > Import from Remote Server > New 296 Security Analytics Reference Guide Security Analytics 8.1 Output array Parameters alias REQ Format X string protocol serverName X portNum Default Valid Inputs Description — <UTF-8 characters> Display name string nfs nfs | cifs Server protocol string — <hostname>|<dotted-decimal> Server location integer 0 0–65535 Port number directory X string — /<filepath>/ username X string — <UTF-8 characters> Valid if protocol=cifs password X string — <UTF-8 characters> Valid if protocol=cifs Python Example s.callAPI("POST","/pcap_import_mount_points/save", { 'alias': 'pcap_exports', 'protocol': 'cifs', 'serverName': 'fileserv.domain.com', 'portNum': 22, 'directory': '/pcaps/deepsee-exports/', 'username': 'admin', 'password': '55geT!meIn&*' } ) PHP Example callAPI('POST','/pcap_import_mount_points/save', array( 'alias' => 'pcap_exports', 'protocol' => 'cifs', 'serverName' => 'fileserv.domain.com', 'portNum' => 22, 'directory' => '/pcaps/deepsee-exports/', 'username' => 'admin', 'password' => '55geT!meIn&*' ) ); Edit an existing mount point API Path /pcap_import_mount_points/edit/<id> Description Edit a mount point that has already been configured on the appliance. 297 Watch-folder path Security Analytics Reference Guide Security Analytics 8.1 GUI Location Menu > Capture > Import PCAP > Manage Connections Output array Parameters REQ Format id X integer — <GET: /pcap_import/connections> Mount point ID alias X string — <UTF-8 characters> Display name string nfs nfs | cifs Server protocol string — <hostname>|<dotted-decimal> Server location integer 0 1–66535 protocol serverName X portNum Default Valid Inputs Description Port number; 0 — All ports directory X string — /<filepath>/ username X string — <UTF-8 characters> Valid if protocol=cifs password X string — <UTF-8 characters> Valid if protocol=cifs Python Example s.callAPI("POST","/pcap_import_mount_points/edit/<id>", { 'alias': 'pcap_exports', 'protocol': 'cifs', 'serverName': 'fileserv.domain.com', 'portNum': 22, 'directory': '/pcaps/deepsee-exports/', 'username': 'admin', 'password': '55geT!meIn&*' } ) PHP Example callAPI('POST','/pcap_import_mount_points/edit/<id>', array( 'alias' => 'pcap_exports', 'protocol' => 'cifs', 'serverName' => 'fileserv.domain.com', 'portNum' => 22, 'directory' => '/pcaps/deepsee-exports/', 'username' => 'admin', 'password' => '55geT!meIn&*' ) ); Delete a watch folder API Path /pcap_import_schedules/delete/<id> 298 Watch-folder path Security Analytics Reference Guide Security Analytics 8.1 Description Delete a PCAP-import schedule (watch folder) GUI Location Menu > Capture > Import PCAP > Watch Folders > Delete entry Output array Parameters ids REQ Format Default Valid Inputs X integer — <GET: /pcap_import/schedules> Python Example s.callAPI("POST","/pcap_import_schedules/delete/<id>") PHP Example callAPI('POST','/pcap_import_schedules/delete/<id>'); 299 Description PCAP import ID Security Analytics Reference Guide Security Analytics 8.1 Playback APIs Begin playback session API Path /regens/start Description Start a playback session GUI Location Menu > Capture > Summary > Start Playback Output ApiResultCode Parameters REQ Format Default Valid Inputs Description inputInterfaces X array — ethX | aggX One or more input interfaces outputInterface X string — ethX timeSpan X array | string — all | live | MM/DD/YYYY hh:ii:ss [MM/DD/YYYY hh:ii:ss] filter BPF — <BPF expression> Example callAPI('POST','/regens/start', array( 'inputInterfaces' => array( 'eth1', 'eth3' ), 'outputInterface' => 'eth7', 'timeSpan' => array( '11/03/2019 13:00:00', '11/03/2019 15:59:59' ), 'filter' => '!(port 80 or 8080 or 443)', 300 Output interface n all — Replay the traffic that was already captured on this interface n live — Replay all traffic as it is captured by the input interface(s) n timespan array — Start time for the first slot to play back; omit the end time to never stop (which is "regeneration" rather than "playback") Capture filter Security Analytics Reference Guide Security Analytics 8.1 ) ) ); Delete playback session API Path /regens/delete/<id> Description Delete a playback session GUI Location Menu > Capture > Summary > Stop Playback Output array Parameters id REQ Format Default Valid Inputs X string — <GET: /captures/get_all_ interfaces> Example callAPI('POST','/regens/delete/<id1>,<id2>,<id3>'); 301 Description Comma-delimited list of playback IDs Security Analytics Reference Guide Security Analytics 8.1 Report and Report Status APIs Also see "Summary Page APIs" on page 369. Run a report API Path /deepsee_reports/report Description Run a specified report GUI Location Menu > Analyze > Summary > Reports Parameters REQ Format X string | integer — <identity path> page integer 0 0–<n> Page to retrieve; first page is 0 pageSize integer 25 1–100 Number of items per page column string sessions bytes | packets | sessions | fragments | bad_csums | artifacts direction string desc asc | desc filters array — <advanced report status filter> compType string none bytes | packets | sessions | none compDate array — <timespan array> Timespan for the second report in the comparison metrics array sessions bytes | packets | sessions | fragments | bad_csums | artifacts Data to return. Corresponds to the Results columns on Analyze > Reports. type string ranked ranked | geolocation Report type; If type=geolocation, field in the identityPath must equal ipv4_ conversation sessionId UUID null null | <GET: /deepsee_ reports/start_session> identityPath Default Valid Inputs 302 Description A value to identify the report. Sort-by column. Value must be included in metrics. Sort order Advanced filter attributes Value on which to make the report comparison. Session ID. This value is obtained after running /deepsee_ reports/start_session once Security Analytics Reference Guide REQ restart extraData Security Analytics 8.1 Format Default Boolean false array — Valid Inputs true | false histogram | no_hearbeat | no_data Description True — Run the report again Extra data to return n histogram — Return histogram data n no_heartbeat — Do not update the report heartbeat n no_data — Do not return the report data; only return totals, report ID, and similar information Example 1: Report with Primary and Advanced Filters plus Histogram Python Example 1 Run a UDP Initiator report with primary and advanced filters; also return histogram data s.callAPI("GET","/deepsee_reports/report", { 'identityPath': { 'timespan': { 'start': '2019-11-03T13:45:01-07:00', 'end': '2019-11-03T13:45:04-07:00' }, 'query': [ 'application_id=dns' ], 'field': 'udp_initiator' }, 'column': 'bytes', 'pageSize': 25, 'filters': { 'all': [ { 'key': 'bytes', 'comp': '>=', 'value': 1000 }, { 'any': [ { 'key': 'udp_initiator', 'comp': '>', 'value': 20000 }, { 'key': 'bad_checksums', 'comp': '!=', 'value': 0 } ] } ] }, 'metrics': [ 'sessions', 'bytes', 303 Security Analytics Reference Guide Security Analytics 8.1 'packets' ], 'extraData': [ 'histogram' ] } ) PHP Example1 Run a UDP Initiator report with primary and advanced filters; also return histogram data callAPI('GET','/deepsee_reports/report', array( 'identityPath' => array( 'timespan' => array( 'start' => '2019-11-03T13:45:01-07:00', 'end' => '2019-11-03T13:45:04-07:00' ), 'query' => array( 'application_id=dns' ), 'field' => 'udp_initiator' ), 'column' => 'bytes', 'pageSize' => 25, 'filters' => array( 'all' => array( array( 'key' => 'bytes', 'comp' => '>=', 'value' => 1000 ), array( 'any' => array( array( 'key' => 'udp_initiator', 'comp' => '>', 'value'=> 20000 ), array( 'key' => 'bad_checksums', 'comp' => '!=', 'value'=> 0 ) ) ) ) ), 'metrics' => array( 'sessions', 'bytes', 'packets' ), 'extraData' => array( 'histogram' ) ) ); Initial Output 1 'result': {'result': {'data': [], 'status': {'artifacts_count': <integer>, 'bad_csums_count': <integer>, 'bytes_count': <integer>, 'fidelity_percent': <integer>, 304 Security Analytics Reference Guide Security Analytics 8.1 'fragments_count': <integer>, 'packets_count': <integer>, 'percentage': <integer>, 'report_daemon_id': <integer>, 'report_id': <integer>, 'sessions_count': <integer>, 'state': '<state>', 'timeDeleted': [True|False], 'time_place': <integer>, 'total_size': <integer>}, 'total_count': <integer>}}, 'resultCode': 'API_SUCCESS_CODE', This API does not return data after the first API request. You must poll the appliance in the meantime to incrementally retrieve the data. See "Using Polling with the APIs" on page 415 for more information. Completed Output 1 'result': {'result': {'beacon': None, 'data': [{'columns': ['<field>', <sessions>, <bytes>, <packets>], 'id': 'id_<hex>'}, {'columns': ['<field>', <sessions>, <bytes>, <packets>], 'id': 'id_<hex>'}, ... {'columns': ['<field>', <sessions>, <bytes>, <packets>], 'id': 'id_<hex>'}, {'columns': ['<field>', <sessions>, <bytes>, <packets>], 'id': 'id_<hex>'}], 'geolocation_totals': None, 'histogram': {'data': [{'columns': [0, <integer>, <integer>, <integer>], 'extra': {'end_time': <epoch>, 'start_time': <epoch>}, 'text': '<MM/DD/YYYY hh:ii:ss>', 'time': <epoch>}, ... {'columns': [0, <integer>, <integer>, <integer>], 'extra': {'end_time': <epoch>, 'start_time': <epoch>}, 'text': '<MM/DD/YYYY hh:ii:ss>', 'time': <epoch>}], 'status': {'artifacts_count': <integer>, 'bad_csums_count': <integer>, 'bytes_count': <integer>, 'fidelity_percent': <integer>, 'fragments_count': <integer>, 'packets_count': <integer>, 'percentage': <integer>, 'sessions_count': <integer>, 'state': '<state>', 'timeDeleted': [True|False], 'time_place': <integer>, 'total_size': <integer>}, 'total_count': <integer>}, 'max': <integer>, 'min': <integer>, 'report_totals': [0, <integer>, <integer>, <integer>], 'routes': None, 'status': {'artifacts_count': <integer>, 'bad_csums_count': <integer>>, 'bytes_count': <integer>, 'fidelity_percent': <integer>, 'fragments_count': <integer>, 305 Security Analytics Reference Guide Security Analytics 8.1 'geolocation_max': <integer>, 'geolocation_min': <integer>, 'packets_count': <integer>, 'percentage': <integer>, 'report_daemon_id': <integer>, 'report_id': <integer>, 'sessions_count': <integer>, 'state': '<state>', 'time_place': <integer>}, 'total': [0, <integer>, <integer>, <integer>], 'total_count': <integer>}}, 'resultCode': 'API_SUCCESS_CODE', Example 2: Report Comparison Python Example 2 Run a File Name report comparison with primary filters only s.callAPI("GET","/deepsee_reports/report", { 'identityPath': { 'timespan': { 'start': '2019-11-03T13:40:00-07:00', 'end': '2019-11-03T13:50:00-07:00' }, 'query': [ 'country=china', 'mime_type~pdf' ], 'field': 'filename', }, 'pageSize': 15, 'column': 'bytes', 'direction': 'asc', 'compType': 'bytes', 'compDate': { 'start':'2019-11-02T14:40:00-07:00', 'end':'2019-11-02T14:50:00-07:00' } } ) PHP Example 2 Run a File Name report comparison between two different hours with primary filters but not advanced filters callAPI('GET','/deepsee_reports/report', array( 'identityPath' => array( 'timespan' => array( 'start' => '2019-11-03T13:40:00-07:00', 'end' => '2019-11-03T13:50:00-07:00' ), 'query' => array( 'country=china', 'mime_type~pdf' ), 'field' => 'filename', ), 'pageSize' => 15, 'column' => 'bytes', 'direction' => 'asc', 'compType' => 'bytes', 'compDate' => array( 'start' => '2019-11-03T14:40:00-07:00', 306 Security Analytics Reference Guide Security Analytics 8.1 'end' => '2019-11-03T14:50:00-07:00' ) ) ); Initial Output 2 'result': {'data': [], 'result': {'compType': 'bytes', 'data': [], 'histogram': {'previous_data': []}, 'status': {'artifacts_count': 0, 'bad_csums_count': 0, 'bytes_count': 0, 'fidelity_percent': 0, 'fragments_count': 0, 'packets_count': 0, 'percentage': 0, 'report_daemon_id': <integer>, 'report_id': <integer>, 'sessions_count': 0, 'state': 'new', 'timeDeleted': False, 'time_place': 0, 'total_size': 0}, 'total': [1, 1, 1, 1], 'total_count': 0}, 'status': {'artifacts_count': 0, 'bad_csums_count': 0, 'bytes_count': 0, 'fidelity_percent': 0, 'fragments_count': 0, 'packets_count': 0, 'percentage': 0, 'sessions_count': 0, 'state': 'new', 'timeDeleted': [True|False], 'time_place': 0, 'total_size': 0}, 'total_count': 0}, 'resultCode': 'API_SUCCESS_CODE', This API does not return data after the first API request. You must poll the appliance in the meantime to incrementally retrieve the data. See "Using Polling with the APIs" on page 415 for more information. Completed Output 2 'result': {'data': [], 'result': {'beacon': None, 'compType': 'bytes', 'data': [{'columns': ['<filename>', 0, 1, 1, 123412341234.12], 'id': 'id_<hex>'}, ... {'columns': ['<filename>', 0, 32, 32, 123412341234.12], 'id': 'id_<hex>'}], 307 Security Analytics Reference Guide Security Analytics 8.1 'geolocation_totals': None, 'histogram': {'data': [{'columns': [0, 122], 'extra': {'end_time': <epoch>, 'start_time': <epoch>}, 'text': 'MM/DD/YYYY hh:ii:ss', 'time': <epoch>}, ... {'columns': [0, 0], 'extra': {'end_time': <epoch>, 'start_time': <epoch>}, 'text': 'MM/DD/YYYY hh:ii:ss', 'time': <epoch>}], 'previous_data': [{'columns': [0, 0], 'extra': {'end_time': <epoch>, 'start_time': <epoch>}, 'text': 'MM/DD/YYYY ' 'hh:ii:ss', 'time': <epoch>}, ... {'columns': [0, 0], 'extra': {'end_time': <epoch>, 'start_time': <epoch>}, 'text': 'MM/DD/YYYY ' 'hh:ii:ss', 'time': <epoch>}], 'status': {'artifacts_count': <integer>, 'bad_csums_count': <integer>, 'bytes_count': <integer>, 'fidelity_percent': <integer>, 'fragments_count': <integer>, 'packets_count': <integer>, 'percentage': <integer>, 'sessions_count': <integer>, 'state': '<state>', 'timeDeleted': [True|False], 'time_place': <integer>, 'total_size': <integer>}, 'total_count': <integer>}, 'max': <integer>, 'min': <integer>, 'report_totals': [<integer>, <integer>], 'routes': None, 'status': {'artifacts_count': <integer>, 'bad_csums_count': <integer>, 'bytes_count': <integer>, 'fidelity_percent': <integer>, 'fragments_count': <integer>, 'geolocation_max': <integer>, 'geolocation_min': <integer>, 'packets_count': <integer>, 'percentage': <integer>, 'report_daemon_id': <integer>, 'report_id': <integer>, 'sessions_count': <integer>, 'state': '<state>', 'time_place': <integer>}, 'total': [<integer>, <integer>], 'total_count': <integer>}, 'status': {'artifacts_count': <integer>, 'bad_csums_count': <integer>, 'bytes_count': <integer>, 'fidelity_percent': <integer>, 'fragments_count': <integer>, 'packets_count': <integer>, 'percentage': <integer>, 'sessions_count': <integer>, 308 Security Analytics Reference Guide Security Analytics 8.1 'state': '<state>', 'timeDeleted': [True|False], 'time_place': <integer>, 'total_size': <integer>}, 'total_count': <integer>}, 'resultCode': 'API_SUCCESS_CODE', Example 3: Geolocation Report Python Example 3 Run a Geolocation report s.callAPI("GET","/deepsee_reports/report", { 'identityPath': { 'timespan': { 'start': '2019-11-03T13:40:00-07:00', 'end': '2019-11-03T13:50:00-07:00' }, 'field': 'ipv4_conversation', }, 'type': 'geolocation' } ) PHP Example 3 Run a Geolocation report. callAPI('GET','/deepsee_reports/report', array( 'identityPath' => array( 'timespan' => array( 'start' => '2019-11-03T13:40:00-07:00', 'end' => '2019-11-03T13:50:00-07:00' ), 'field' => 'filename', ), 'type' => 'geolocation' ) ); Initial Output 3 'result': {'result': {'beacon': None, 'data': [], 'geolocation_totals': [], 'histogram': None, 'max': <float>, 'min': <float>, 'report_totals': [], 'routes': [], 'status': {'report1': {'artifacts_count': 0, 'bad_csums_count': 0, 'bytes_count': 0, 'fidelity_percent': 0, 'fragments_count': 0, 'packets_count': 0, 'percentage': 0, 'report_daemon_id': <integer>, 'report_id': <integer>, 'sessions_count': 0, 'state': '<state>', 309 Security Analytics Reference Guide Security Analytics 8.1 'timeDeleted': [True|False], 'time_place': 0, 'total_size': 0}, 'report2': {'artifacts_count': 0, 'bad_csums_count': 0, 'bytes_count': 0, 'fidelity_percent': 0, 'fragments_count': 0, 'packets_count': 0, 'percentage': 0, 'report_daemon_id': <integer>, 'report_id': <integer>, 'sessions_count': 0, 'state': '<state>', 'timeDeleted': [True|False], 'time_place': 0, 'total_size': 0}}, 'total': [], 'total_count': 0}}, 'resultCode': 'API_SUCCESS_CODE', This API does not return data after the first API request. You must poll the appliance in the meantime to incrementally retrieve the data. See "Using Polling with the APIs" on page 415 for more information. Completed Output 3 'result': {'result': {'beacon': None, 'data': [{'columns': ['<location>', <number_of_addresses>, <bytes>], 'id': 'ipv4_conversation_32', 'ids': ['ipv4_conversation_32'], 'latitude': <signed_floating>}, 'longitude': <signed_floating>}}, ... {'columns': ['<location>', <number_of_addresses>, <bytes>], 'id': 'ipv4_conversation_36', 'ids': ['ipv4_conversation_36'], 'latitude': <signed_floating>}, 'longitude': <signed_floating>}}], 'geolocation_totals': [0, <integer>, <integer>], 'histogram': None, 'max': <integer>, 'min': <integer>, 'report_totals': [<integer>, <integer>], 'routes': [{'latitude1': <signed_floating>, 'latitude2': <signed_floating>, 'longitude1': <signed_floating>, 'longitude2': <signed_floating>}, ... {'latitude1': <signed_floating>, 'latitude2': <signed_floating>, 'longitude1': <signed_floating>, 'longitude2': <signed_floating>}], 'status': {'report1': {'artifacts_count': 0, 'bad_csums_count': 0, 'bytes_count': 0, 'fidelity_percent': 100, 'fragments_count': 0, 'geolocation_max': 0, 'geolocation_min': 0, 310 Security Analytics Reference Guide Security Analytics 8.1 'packets_count': 0, 'percentage': 100, 'report_daemon_id': <integer>, 'report_id': <integer>, 'sessions_count': 0, 'state': 'complete', 'time_place': 0}, 'report2': {'artifacts_count': 0, 'bad_csums_count': 0, 'bytes_count': <integer>, 'fidelity_percent': 100, 'fragments_count': 0, 'geolocation_max': 0, 'geolocation_min': 0, 'packets_count': <integer>, 'percentage': 100, 'report_daemon_id': <integer>, 'report_id': <integer>, 'sessions_count': <integer>, 'state': 'complete', 'time_place': 0}}, 'total': [0, <integer>, <integer>], 'total_count': <integer>}}, 'resultCode': 'API_SUCCESS_CODE', Get job queue — NEW API Path /job_queue/job_queue Description Retrieve a list of jobs in the job queue. GUI Location Job Queue page Parameters REQ Format Default Valid Inputs Description page integer 1 1–<n> Page to retrieve; first page is 1 limit integer 25 1–100 Number of items per page sort string create_date create_date | start_date | finish_ date direction string desc asc | desc Sort order filters array — <advanced job queue filter> Advanced filter attributes 311 Sort-by column Security Analytics Reference Guide Security Analytics 8.1 Python Example s.callAPI('GET', '/job_queue/job_queue', { 'page': 1, 'limit': 25, 'sort': 'start_date', 'filters': { 'all': [ { 'key': 'id', 'comp': '>=', 'value': 16 } ] } } ) PHP Example callAPI('GET', '/job_queue/job_queue', array( 'page' => 1, 'limit' => 25, 'sort' => 'start_date', 'filters' => array( 'all' => array( 'key': 'id', 'comp': '>=', 'value': 16 ) ) ) ); Output 'paging': {'JobQueue': {'count': <integer>, 'current': <integer>, 'limit': <integer>, 'nextPage': [True | False], 'options': {'order': {'JobQueue.<field>': '[asc | desc]'}}, 'order': {'JobQueue.<field>': '[asc | desc]'}, 'page': <integer>, 'pageCount': <integer>, 'paramType': 'named', 'prevPage': [True | False], 'queryScope': None}}, 'result': {'pageCount': 1, 'rows': [{'can_download': [True | False], 'create_date': 'YYYY-MM-DD hh:ii:ss.999999-06', 'data': '{"appliances":"","options":{"ac":"Reports","sc":{"Reports":{"rI":"<report_ name>","sv":58, "s":1000,"sc":"sessions","sd":"d"}},"pb":[],"ca":{"start":<epoch>,"end":<epoch>}}, "username":"<username>","file":"\\/tmp\\/<filename>.pdf"}', 'elapsed_time': 'hh:ii:ss', 'finish_date': 'YYYY-MM-DD hh:ii:ss.999999-06', 'id': <integer>, 'message': '', 'queued': [True | False], 'start_date': 'YYYY-MM-DD hh:ii:ss.999999-06', 312 Security Analytics Reference Guide Security Analytics 8.1 'status': <integer>, 'type': <integer>, 'username': '<username>'}, {'can_download': [True | False], 'create_date': 'YYYY-MM-DD hh:ii:ss.999999-06', 'data': '{"appliances":"","timespan":{"start":"<epoch>","end":"<epoch>"},"options": {"polling":false,"threatSummary":false,"field":"threat_summary","timespan": {"start":"<epoch>","end":"<epoch>"}, "delivery":{"email":{"selected":"0"},"download":{"selected":"1"}},"reportlets":[]," _Token":{"key":"<key>","unlockedFields":[]}},"username":"admin","user_ id":1,"outputFile":"\\/home\\/apache\\/tmp\\/ risk_and_visibility_report_<hex>.pdf"}', 'elapsed_time': 'hh:ii:ss', 'finish_date': 'YYYY-MM-DD hh:ii:ss.999999-06', 'id': <integer>, 'message': '', 'queued': [True | False], 'start_date': 'YYYY-MM-DD hh:ii:ss.999999-06', 'status': <integer>, 'type': <integer>, 'username': '<username>'}, ]}, 'resultCode': 'API_SUCCESS_CODE', Download a file from the job queue — NEW API Path /job_queue/download Description Download a file in the job queue. GUI Location Job Queue page Parameters id REQ Format X integer Default — Python Example s.callAPI('GET', '/job_queue/download', { "id": 5 }) PHP Example s.callAPI('GET', '/job_queue/download', array( 313 Valid Inputs Description <GET: /job_queue/job_queue> ID of a job in the queue Security Analytics Reference Guide Security Analytics 8.1 'id' => 5 ) ); Output Get job queue count — NEW API Path /job_queue/count Description Get the number of non-downloaded jobs in the job queue. GUI Location Job Queue icon Parameters None Python Example s.callAPI('GET', '/job_queue/count') PHP Example s.callAPI('GET', '/job_queue/count'); Output 'result': <integer>, 'resultCode': 'API_SUCCESS_CODE' Get filter options for the job queue — NEW API Path /job_queue/filter_options Description Get the advanced filter attributes for the Job Queue page. GUI Location Job Queue icon Parameters None 314 Security Analytics Reference Guide Security Analytics 8.1 Python Example s.callAPI('GET', '/job_queue/filter_options') PHP Example s.callAPI('GET', '/job_queue/filter_options'); Output {'errors': [], 'messages': [], 'paging': [], 'result': {'status': ['Error', 'Queued', 'Running', 'Downloadable', 'Finished'], 'type': ['Error', 'Download PDF', 'Generate PDF', 'Generate CSV', 'Import Favorite', 'Download PCAP', 'Generate Threat Summary', 'Email Threat Summary Report', 'Save Result']}, 'resultCode': 'API_SUCCESS_CODE', 'validationErrors': {'JobQueue': [], 'Meta': [], 'Util': [], 'res': []}} Start session for combining reports API Path /deepsee_reports/start_session Description Starts a session for combining reports together to run simultaneously. GUI Location Menu > Analyze > Summary Example n Run GET: /deepsee_reports/start_session to get a sessionId. n Run GET:/deepsee_reports/report N times, using the same sessionId each time and the same identity path except for field. These reports are queued. n Run GET:/ deepsee_reports/finalize_session to run all of the queued reports as if they were one report. Output 'result': '<UUID>', 'resultCode': 'API_SUCCESS_CODE', 315 Security Analytics Reference Guide Security Analytics 8.1 Finish session for combining reports API Path /deepsee_reports/finalize_session Description Launches all reports that are queued for the session. GUI Location Menu > Analyze > Summary Parameters sessionId REQ Format X UUID Default Valid Inputs — <GET: /deepsee_reports/start_ session> Description Session to launch Output 'resultCode': 'API_SUCCESS_CODE', Download CSV report API Path /deepsee_reports/csv Description Download an existing report in CSV format GUI Location Menu > Analyze > Summary > Reports > Actions > Download CSV Parameters identityPath direction REQ Format X string | integer string Default — DESC Valid Inputs <GET: /deepsee_ reports/report> Description Run /deepsee_reports/report to get the report ID; include no_data in the extraData array for a faster return time <report ID> Use the report ID for identityPath ASC | DESC Sort order 316 Security Analytics Reference Guide REQ column Format Security Analytics 8.1 Default string — Valid Inputs bytes | packets | sessions | fragments | bad_csums | artifacts | risk | item Description Sort-by column PHP Example callAPI('GET','/deepsee_reports/csv', array( 'identityPath' => 3447, 'direction' => 'DESC', 'column' => 'bytes' ), '<filename>.csv' ); Python Example s.callAPI("GET","/deepsee_reports/csv", { 'identityPath': 3447, 'direction': 'DESC', 'column': 'bytes' }, '<filename>.csv' ) Output <filename>.csv Download PDF report API Path /deepsee_reports/pdf/<reportId> Description Download a report in PDF format. GUI Location Menu > Analyze > Summary > Reports > Actions > Download PDF Parameters identityPath REQ Format X string | integer Default — Valid Inputs Description <GET: /deepsee_ reports/report >|<GET: /report_daemons> Run either API to get the report ID <report ID> Use the report ID for identityPath Sort order direction string — ASC | DESC column string — bytes | sessions | packets 317 Sort-by column Security Analytics Reference Guide Security Analytics 8.1 PHP Example callAPI('GET','/deepsee_reports/pdf/3447', array( 'direction' => 'DESC', 'column' => 'bytes' ), '<filename>.pdf' ) Python Example s.callAPI("GET","/deepsee_reports/pdf/3447", { 'direction': 'DESC', 'column': 'bytes' }, '<filename>.pdf' ) Output <filename>.pdf Download a raw TSV file API Path /pcap/download/raw Description Download a raw.tsv file GUI Location Menu > Analyze > [Summary | Reports | Extractions | Geolocation] > Actions > Download Raw TSV Parameters path REQ Format X array — <Indexing DB path> Indexing database path array — <RAW.TSV fields> Omit to specify all fields fields Default Valid Inputs Description Python Example s.callAPI("GET","/pcap/download/raw", { 'path':'/timespan/2019-11-23T00:00:00_2019-11-23T00:23:59/application_ id/runescape/country/china/ip_responder/203.0.113.0/24', 'fields': [ 'aggregate_social_persona_hooks,' 'application_id1', 'application_id2', 'first_slot_id', 'packet_count', 'start_time', 'stop_time' ] }, '<filename>.tsv' ) PHP Example callAPI('GET','/pcap/download/raw', 318 Security Analytics Reference Guide Security Analytics 8.1 array( 'path' => '/timespan/2019-11-23T00:00:00-07:00_2019-11-23T00:23:5907:00/application_id/runescape/country/china/ip_responder/203.0.113.0/24', 'fields' => array( 'aggregate_social_persona_hooks,' 'application_id1', 'application_id2', 'first_slot_id', 'packet_count', 'start_time', 'stop_time' ) ), '<filename>.tsv' ); Output <filename>.tsv Get report status summary API Path /report_daemons/summary_data Description Retrieve the report status summary GUI Location Menu > Analyze > Report Status > Summary Parameters REQ filters Format Default Valid Inputs Description JSON — <advanced report status filter> page integer 1 1–<n> Number of the page to retrieve; first page is 1 limit integer 25 1–100 Number of items per page sort string count count Sort-by column string DESC ASC | DESC array — direction groupBy X Advanced filter attributes Sort order percentage | field | state | Tables on the Report Status Summary username | appliance page Python Example s.callAPI("GET","/report_daemons/summary_data", { 'page': 1, 'limit': 15, 'direction': 'DESC', 'filters': json.dumps({ { 319 Security Analytics Reference Guide Security Analytics 8.1 'all': [ { 'key': 'state', 'comp': '=', 'value': 'complete' }, { 'key': 'username', 'comp': '=', 'value': 'admin' } ] } }), 'groupBy': { ['field'] } } ) PHP Example callAPI('GET','/report_daemons/summary_data', array( 'page' => 1, 'limit' => 15, 'direction' => 'DESC', 'filters' => json_encode( array( 'all' => array( array( 'key' => 'state', 'comp' => '=', 'value' => 'complete' ) array( 'key' => 'username', 'comp' => '=', 'value' => 'admin' ) ) ) ), 'groupBy' => array( 'field' ) ) ); Output 'paging': {'ReportDaemon': {'count': <integer>, 'current': <integer>, 'limit': <integer>, 'nextPage': [True|False], 'options': {'order': {'count': 'desc'}}, 'order': {'count': 'desc'}, 'page': <integer>, 'pageCount': <integer>, 'paramType': 'named', 'prevPage': [True|False]}}, 'result': {'pageCount': <integer>, 'rows': [{'count': <integer>, 'field': '<report_attribute>'}, {'count': <integer>, 'field': '<report_attribute>'}, ... {'count': <integer>, 'field': '<report_attribute>'}, {'count': <integer>, 'field': '<report_attribute>'}]}, 'resultCode': 'API_SUCCESS_CODE', 320 Security Analytics Reference Guide Security Analytics 8.1 Get report status list API Path /report_daemons Description Retrieve the report status list GUI Location Menu > Analyze > Report Status > List Parameters REQ filters Format Default Valid Inputs Description JSON — <advanced report status filter> page integer 1 1–<n> Page to retrieve; first page is 1 limit integer 25 1–100 Number of items per page string DESC ASC | DESC string id id | field | start_time | end_ time | age | run_time | name | disk_usage | timespan_start | timespan_end | percentage direction sort Python Example s.callAPI("GET","/report_daemons", { 'page': 1, 'limit': 15, 'sort': 'percentage', 'direction': 'ASC', 'filters': json.dumps( { 'all': [ { 'key': 'state', 'comp': '=', 'value': 'complete' }, { 'key': 'username', 'comp': '=', 'value': 'admin' } ] } ) } ) 321 Advanced filter attributes Sort order Sort-by column Security Analytics Reference Guide Security Analytics 8.1 PHP Example callAPI('GET','/report_daemons', array( 'page' => 1, 'limit' => 15, 'sort' => 'percentage', 'direction' => 'ASC', 'filters' => json_encode( array( 'all' => array( array( 'key' => 'state', 'comp' => '=', 'value' => 'complete' ) array( 'key' => 'username', 'comp' => '=', 'value' => 'admin' ) ) ) ) ) ); Output 'paging': {'ReportDaemon': {'count': <integer>, 'current': <integer>, 'limit': <integer>, 'nextPage': [True|False], 'options': [], 'order': '"ReportDaemon"."id" [ASC|DESC]', 'page': <integer>, 'pageCount': <integer>, 'paramType': 'named', 'prevPage': [True|False]}}, 'result': {'pageCount': <integer>, 'rows': [{'disk_usage': '<size>', 'end_time': '<YYYY-MM-DD><hh:ii:ss>.003329-06', 'field': '<field>', 'id': <integer>, 'name': '', 'path_bar': '["<report_attribute>"]', 'run_time': '<hh:ii:ss>', 'saved_count': 0, 'start_time': '<YYYY-MM-DD><hh:ii:ss>.387784-06', 'state': 'complete', 'timespan_end': '<YYYY-MM-DD><hh:ii:ss>-06', 'timespan_start': '<YYYY-MM-DD><hh:ii:ss>-06', 'username': '<username>'}, ... 'resultCode': 'API_SUCCESS_CODE', Get scheduled reports API Path /deepsee_reports/schedules Description Retrieve all scheduled reports 322 Security Analytics Reference Guide Security Analytics 8.1 GUI Location Menu > Analyze > Scheduled Reports Parameters REQ Format Default Valid Inputs Description page integer 1 1–<n> Number of the page to retrieve; first page is 1 limit integer 25 1–100 Number of items per page string asc asc | desc Sort order integer 0 0 | 1 | 2 n 0 — Both Shared and Not Shared n 1 — Not Shared n 2 — Shared direction shared sort string name id | name | created_by_userid | Sort-by column frequency | report_types | appliances | time_span | time_ of_execution | recipients | output_format | is_active | shared | created | modified | last_execution | status | end_ time_of_execution Python Example s.callAPI("GET","/deepsee_reports/schedules", { 'page': 3, 'limit': 50, 'direction': 'desc', 'shared': 2, 'sort': 'last_execution' } ) PHP Example callAPI('GET','/deepsee_reports/schedules', array( 'page' => 3, 'limit' => 50, 'direction' => 'desc', 'shared' => 2, 'sort' => 'last_execution' ) ); Output 'paging': {'ReportSchedule': {'count': <integer>, 'current': <integer>, 'limit': <integer>, 'nextPage': [True|False], 'options': {'conditions': [], 'order': {'ReportSchedule.name': '[asc|desc]'}}, 'order': {'ReportSchedule.name': '[asc|desc]'}, 323 Security Analytics Reference Guide Security Analytics 8.1 'page': <integer>, 'pageCount': <integer>, 'paramType': 'named', 'prevPage': [True|False]}}, 'result': {'pageCount': <integer>, 'results': [{'ReportSchedule': {'ReportScheduleEvent': [{'event': '<frequency>', 'id': <integer>, 'nice_event': '<frequency>', 'report_schedule_id': <integer>}], 'appliances': [None|<appliance_ids>], 'created': '<YYYY-MM-DD><hh:ii:ss>-06', 'created_by_userid': <integer>, 'end_time_of_execution': '<hh:ii:ss>', 'frequency': '<frequency>', 'gauge_path_json': '["<primary filter>"]', 'id': <integer>, 'is_active': [True|False], 'last_execution': None, 'massaged_time_span': '<time_span>', 'modified': '<YYYY-MM-DD>' '<hh:ii:mm>.310877-06', 'name': '<report_name>', 'output_format': '[CSV|PDF]', 'recipients': '<email_address>', 'repeat': '<frequency>', 'repeats_every': '<frequency>', 'report_types': '<primary filter attribute>', 'shared': [True|False], 'status': None, 'time_of_execution': '<hh:ii:mm>', 'time_span': '-<time>'}}]}, 'resultCode': 'API_SUCCESS_CODE', Get path API Path /deepsee_reports/gauge_path Description Retrieve an Indexing DB path for the specified query GUI Location Menu > Analyze > Summary pages > More Information dialog Parameters REQ Format Default Valid Inputs query X JSON — <primary filter array> timespan X JSON — <timespan array> Python Example s.callAPI("GET","deepsee_reports/gauge_path", { 'query': json.dumps([ 'port>10000', 324 Description Primary filter attribute/values Start and end times Security Analytics Reference Guide Security Analytics 8.1 'application_id=dns,udp' ]), 'timespan': json.dumps({ 'start': '2019-11-03T10:00:00-07:00', 'end': '2019-11-03T10:15:00-07:00' }) } ) PHP Example callAPI('GET','deepsee_reports/gauge_path', array( 'query' => json_encode( array( 'port>10000', 'application_id=dns,udp' ) ), 'timespan' => json_encode( array( 'start' => '2019-11-03T10:00:00-07:00', 'end' => '2019-11-03T10:15:00-07:00' ) ) ) ); Output 'result': '/timespan/2019-11-03T10:00:00-07:00_2019-11-03T10:15:00-07:00/port/_gt_ 10000/application_id/udp', 'resultCode': 'API_SUCCESS_CODE', Get estimated PCAP size API Path /deepsee_reports/estimate_pcapsize Description Retrieve the estimated size of the report PCAP within a specified timespan GUI Location n Menu dialog > Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > More Information n Menu > Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > Status bar > Search Size field Parameters REQ Format Default Valid Inputs startTime X integer — <unix epoch> Start of timespan stopTime X integer — <unix epoch> End of timespan 325 Description Security Analytics Reference Guide Security Analytics 8.1 Python Example s.callAPI("GET","deepsee_reports/estimate_pcapsize", { 'startTime': 1677980000, 'stopTime': 1678039074 } ) PHP Example callAPI('GET','deepsee_reports/estimate_pcapsize', array( 'startTime' => 1677980000, 'stopTime' => 1678039074 ) ) ); Output 'result': '<bytes>', 'resultCode': 'API_SUCCESS_CODE', Download Google Earth KMZ file API Path /deepsee_reports/kmz Description Download a Google Earth KMZ file of the current report(s) GUI Location Menu > Analyze > Summary pages > Actions > Google Earth Parameters REQ Format Default Valid Inputs query X JSON — <primary filter array> timespan X JSON — <timespan array> Python Example s.callAPI("GET","/deepsee_reports/kmz", { 'query': json.dumps([ 'port>50000', 'application_id=dns,http' ]), 'timespan': json.dumps({ 'start': '2019-11-03T10:00:00-07:00', 'end': '2019-11-03T10:15:00-07:00' }) } ) PHP Example callAPI('GET','/deepsee_reports/kmz', array( 'query' => json_encode( 326 Description Primary filter attributes Timespan Security Analytics Reference Guide Security Analytics 8.1 array( 'port>50000', 'application_id=dns,http' ), ), 'timespan' => json_encode( array( 'start' => '2019-11-03T10:00:00-07:00', 'end' => '2019-11-03T10:15:00-07:00' ) ) ) ); Output <filename>.kmz Get the chart settings on the Reports page API Path /deepsee/ranked_chart_setting Description Retrieve the settings for the chart on the Reports page GUI Location Menu > Analyze > Summary > Reports > Report Summary > Settings Parameters None Python Example s.callAPI("GET","/deepsee/ranked_chart_setting") PHP Example callAPI('GET','/deepsee/ranked_chart_setting'); Output 'result': {'axisScale': '[linear|logarithmic]', 'numResults': <integer>, 'type': ' [pie|bar|column|scatter]'}, 'resultCode': 'API_SUCCESS_CODE', Delete jobs from the job queue — NEW API Path /job_queue/delete Description Delete one or more jobs from the job queue. 327 Security Analytics Reference Guide Security Analytics 8.1 GUI Location Job Queue page Parameters ids REQ Format X integer Default — Valid Inputs Description <GET: /job_queue/job_queue> IDs of jobs in the queue Python Example s.callAPI('POST', '/job_queue/delete', { "id": 5,6 }) PHP Example s.callAPI('POST', '/job_queue/delete', array( 'id' => 5,6 ) ); Generate a Risk and Visibility report API Path /deepsee_reports/threat_summary Description Generate a Risk and Visibility report. The finished report is located in /home/apache/tmp. GUI Location [Account Name] > Risk and Visibility Report Parameters REQ Format Default Valid Inputs reportData X array — Array that contains all other fields delivery X array — Delivery methods: download from the web UI and/or email to specified recipients. At least one delivery method must be specified. download array — Whether the report is to be downloaded from the web UI. selected integer 1 0 | 1 328 Description Whether the option is selected: n 0 — Not selected n 1 — Selected Security Analytics Reference Guide REQ email recipient_ list reportlets X timespan Format Security Analytics 8.1 Default Valid Inputs array — array — <user@domain.tld> Boolean false [] | false array — <timespan array> Description Whether the report is to be emailed to specified recipients. List of email addresses to receive the report Can be false or an empty array Timespan of the data to include in the report Python Example s.callAPI("POST","/deepsee_reports/threat_summary", { 'reportData': { 'delivery': { 'download': { 'selected': 1 }, 'email': { 'selected': 1, 'recipient_list': [ 'joe@nowhere.com' ] } }, 'reportlets': False, 'timespan': { 'start': '2019-09-01T10:00:00-07:00', 'end': '2019-09-02T10:00:00-07:00' } } } ) PHP Example callAPI('POST','/deepsee_reports/threat_summary', array( 'reportData' => array( 'delivery' => array( 'download' => array( 'selected' => 1 ), 'email' => array( 'selected' => 1, 'recipient_list' => array( 'joe@nowhere.com' ) ) ), 'reportlets' => array(), 'timespan' => array( 'start' => '2019-09-01T10:00:00-07:00', 'end' => '2019-09-02T10:00:00-07:00' ) ) ) ); Output 'result': 'API_SUCCESS_CODE', 'resultCode': 'API_SUCCESS_CODE', 329 Security Analytics Reference Guide Security Analytics 8.1 Stop a report API Path /report_daemons/stop Description Stop one or more reports in the active state GUI Location Menu > Analyze > Report Status > List Output IDs of successfully stopped reports Parameters REQ identityPaths X Format Default integer — Valid Inputs <GET: /deepsee_reports/report> | <GET: /report_daemons> Python Example s.callAPI("POST","/report_daemons/stop", { 'identityPaths': [ 375, 383 ] } ) PHP Example callAPI('POST','/report_daemons/stop', array( 'identityPaths' => array( 375, 383 ) ) ); Delete a report API Path /report_daemons/delete Description Delete a report in the stopped, complete, or error state 330 Description Run either API to get the report ID Security Analytics Reference Guide Security Analytics 8.1 GUI Location Menu > Analyze > Report Status > List > [selected reports] > Delete button Output IDs of successfully deleted reports Parameters identityPaths REQ Format X string | integer Default — Valid Inputs <GET: /deepsee_reports/report>| <GET: /report_daemons> <report ID> Python Example s.callAPI("POST","/report_daemons/delete", { 'identityPaths': [ 554, 557, 559 ] } ) PHP Example callAPI('POST','/report_daemons/delete', array( 'identityPaths' => array( 554, 557, 559 ) ) ); Save a report API Path /deepsee_reports/save Description Save a report to the Report Status page GUI Location n Menu > Analyze > Summary > Actions > Save n Menu > Analyze > Summary > Reports > Actions > Save 331 Description Run either API to get the report ID Use the report ID for identityPath Security Analytics Reference Guide n Menu Security Analytics 8.1 > Analyze > Summary > Geolocation > Actions > Save Output ApiResultCode Parameters identityPath name REQ Format X string | integer X string Default — Valid Inputs <GET: /deepsee_ reports/report> | <GET: /report_daemons> Run either API to get the report ID <report ID> Use the report ID for identityPath — <UTF-8 characters> Python Example s.callAPI("POST","/deepsee_reports/save", { 'identityPaths': [ 384 ], 'name': 'Email_Subject-20191103' } ) PHP Example callAPI('POST','/deepsee_reports/save', array( 'identityPaths' => array( 384 ), 'name' => 'Email_Subject-20191103' ) ); Stop a report API Path /deepsee_reports/stop Description Stop a report that is currently running GUI Location Menu Description > Analyze > Summary > (any) Stop button Output ApiResultCode 332 Name for the report Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ Format X string | integer identityPath Default Valid Inputs — Description <GET: /deepsee_ reports/report> | <GET: /report_daemons> <report ID> Run either API to get the report ID Use the report ID for identityPath Python Example s.callAPI('POST','/deepsee_reports/stop', { 'identityPaths': [ 384 ] } ) PHP Example callAPI('POST','/deepsee_reports/stop', array( 'identityPaths' => array( 384 ) ) ); Edit the chart on the Reports page API Path /deepsee/ranked_chart_setting Description Edit the settings for the Selected Totals chart on the Reports page. GUI Location Menu > Analyze > Summary > Reports > Report Summary > Settings Output array Parameters REQ Format Default Valid Inputs type X string — pie | bar | column | scatter axisScale X string — linear | logarithmic 333 Description Chart type Scale for the y-axis; logarithmic is not valid for type=pie Security Analytics Reference Guide REQ Format X integer numResults Security Analytics 8.1 Default Valid Inputs — 1–40 Description Number of results to display Python Example s.callAPI("POST","/deepsee/ranked_chart_setting", { 'type': 'pie', 'axisScale': 'linear', 'numResults': 25 } ) PHP Example callAPI('POST','/deepsee/ranked_chart_setting', array( 'type' => 'pie', 'axisScale' => 'linear', 'numResults' => 25 ) ); Create or edit a scheduled report API Path /deepsee_reports/schedule_create Description Create or edit a scheduled report; completing a new schedule runs the report once GUI Location Menu > Analyze > Scheduled Reports Output array Parameters REQ Format Default id name X X string string — — Valid Inputs null | <GET: /deepsee_ reports/schedules> <UTF-8 characters> 334 Description n New — Use null n Edit — Scheduled report ID required n New — Name for the report required n Edit — New name for the report Security Analytics Reference Guide Security Analytics 8.1 REQ Format Default shared frequency X X events integer Valid Inputs — 0 | 1 Description n 0 — Non-shared report n 1 — Shared report string — daily | weekly | monthly | hour | minute | once | custom array — <scheduled events syntax> When to run the report, according to the value of frequency Time to begin running the schedule How often to run the report timeOfExecution X string — <hh:ii:ss> endTimeOfExecution X string — <hh:ii:ss> | 23:59:59 Time to stop running the schedule; if frequency = hour or minute specify when to stop, else this value is 23:59:59 gaugePathJson X JSON — <primary filter array> Primary filter attribute/value pairs; to specify an indicator, run GET: /favorites timeSpan X string — email — <user>@<domain>.<tld> recipients -<integer> [minutes | hours | Start time for the report's data, days | weeks | months | expressed as years] <hyphen><integer> <unit_of_ |<YYYY-MM-DD>T<hh:ii:ss>_ time>; end time is <YYYY-MM-DD>T<hh:ii:ss> timeOfExecution If frequency=once, specify both start and end times. Email accounts to receive reports, semicolon-delimited outputFormat X string — PDF | CSV reportType X string — <available reports> createdByUserID X integer — <GET: /users/setting> ID of user who created the report integer — <GET: /cmc_ settings/appliances> CMC only. Sensors on which to save this scheduled report appliances Output format for report Report type; use the report's corresponding primary filter attribute Python Example Schedule a Country Responder report to run once every 3 hours beginning at midnight. The report is filtered by the Countries - OFAC indicator and the report timespan is the 15 minutes prior to report execution. A PDF version of the report is sent to two email addresses. s.callAPI("POST","/deepsee_reports/schedule_create", { 'id': None, 'name': '3-Hour High-Risk Countries', 335 Security Analytics Reference Guide Security Analytics 8.1 'shared: 1, 'frequency': 'hour', 'events': { '03' }, 'timeOfExecution': '00:00:00', 'endTimeOfExecution': '23:59:59', 'gaugePathJson': { { 'favorite=581cc1a3-b884-4e39-a2f2-67b31e1d64a3' } }, 'timeSpan': '-15 minutes', 'recipients': 'admin@domain.com;security@domaincom', 'outputFormat': 'PDF', 'reportType': 'country_responder', 'createdByUserID': 1 } ) PHP Example Schedule a Country Responder report to run once every 3 hours beginning at midnight. The report is filtered by the Countries - OFAC indicator and the report timespan is the 15 minutes prior to report execution. A PDF version of the report is sent to two email addresses. callAPI('POST','/deepsee_reports/schedule_create', array( 'id' => null, 'name' => '3-Hour High-Risk Countries', 'shared' => 1, 'frequency' => 'hour', 'events' => array( '03' ), 'timeOfExecution' => '00:00:00', 'endTimeOfExecution' => '23:59:59', 'gaugePathJson' => json_encode( array( 'favorite=581cc1a3-b884-4e39-a2f2-67b31e1d64a3' ) ), 'timeSpan' => '-15 minutes', 'recipients' => 'admin@domain.com;security@domaincom', 'outputFormat' => 'PDF', 'reportType' => 'country_responder', 'createdByUserID' => 1 ) ); Delete a scheduled report API Path /deepsee_reports/schedule_delete/<id> Description Delete a specified scheduled report 336 Security Analytics Reference Guide Security Analytics 8.1 GUI Location Menu > Analyze > Scheduled Reports > [schedule entry] Output array Parameters REQ Format X integer id Default — Valid Inputs <GET: /deepsee_ reports/scheduled> Description ID of scheduled report to be deleted Python Example s.callAPI("POST","/deepsee_reports/schedule_delete/<scheduled_report_id>") PHP Example callAPI('POST','/deepsee_reports/schedule_delete/<scheduled_report_id>'); Activate or deactivate a scheduled report API Path /deepsee_reports/schedule_toggle/<id>/<action> Description Toggle a scheduled report between activate and inactive GUI Location Menu > Analyze > Scheduled Reports > [schedule entry] Output ApiResultCode Parameters REQ Format Default Valid Inputs id X integer — <GET: /deepsee_ reports/schedules> action X string — activate | deactivate Python Example s.callAPI("POST","/deepsee_reports/schedule_toggle/25/deactivate") PHP Example callAPI('POST','/deepsee_reports/schedule_toggle/25/deactivate'); 337 Description ID of the scheduled report Action to perform Security Analytics Reference Guide Security Analytics 8.1 Rules APIs "Action" is the internal name for "rule." Get rules API Path /actions Description Retrieve a list of rules GUI Location Menu > Analyze > Rules Output array Parameters REQ Format Default Valid Inputs page integer 1 1-<n> Page to get. First page is 1 limit integer 25 1–100 Number of rows per page direction string ASC ASC | DESC sort string name name shared integer null null | 0 | 1 | 2 uuid UUID | array null null | UUID | <UUID_ array> Example callAPI('GET','/actions', array( 'page' => 2, 'limit' => 25, 'direction' => 'DESC', 'shared' => 2, 'uuid' => array( 338 Description Sort direction Sort-by column n null — All rules n 0 — All rules n 1 — Non-shared rules n 2 — Shared rules n null — Retrieve all rules n UUID | array — Valid only after this API has been run once Security Analytics Reference Guide Security Analytics 8.1 <uuid1>, <uuid2>, <uuid3> ) ) ); Download rule scripts API Path /actions/download Description Retrieve workflow scripts GUI Location Menu > Analyze > Rules Output download Parameters REQ uuid applianceId Format Default Valid Inputs UUID — <GET: /actions> integer null 1-<n> Example callAPI('GET','/actions/download', array( 'uuid' => <uuid>, 'applianceId' => 4 ) ); Create or edit a rule — MODIFIED API Path /actions/save Description Create or edit a rule GUI Location Menu > Analyze > Rules > [New | Edit] 339 Description UUID of Lua script to download CMC Only. Sensor where rule resides Security Analytics Reference Guide Security Analytics 8.1 Output array Parameters uuid name type REQ Format Default Valid Inputs X uuid null null | <GET: /actions> X string integer — <UTF-8 characters> 1 0 | 1 | 2 | 4 | 8 | 128 | 256 268435<three-digit type> Description n New — Use null to create a new rule n Edit — Required n New — Required n Edit — Optional Valid if open parser is not being used. n 0 — None n 1 — Alert n 2 — Data Enrichment n 4 — PCAP Export n 8 — IPFIX Export n 128 — Dynamic Filter 256 — Discard Packets (new) To enable open parser, use these values: n openParser array — regexes string — n 456 — None n 457 — Alert n 458 — Data Enrichment n 460 — PCAP Export n 464 — IPFIX Export n 584 — Dynamic Filter Open parser attributes; array includes regexes, delimiter, and metaAction <regular expressions> 340 Regular expression(s) Security Analytics Reference Guide Security Analytics 8.1 REQ metaAction delimiter Format Default Valid Inputs Description integer 1 1 | 2 | 3 | 5 Action to take on matching traffic n 1 — Add flag to metadata n 2 — Add matching value to metadata n 3 — Add succeeding value to metadata until this delimiter; requires delimiter n 5 — Take no action string None <RE-compliant delimiter> A delimiter; valid only if metaAction=3 array — <GET: /favorites> | <GET: /favorites/active> Array of indicator UUIDs active Boolean true true | false True — Active shared Boolean true true | false True — Shared offBox array — snmp UUID — null | <GET: /settings/all_ templates> SNMP template UUID smtp UUID — null | <GET: /settings/all_ templates> SMTP template UUID syslog UUID — null | <GET: /settings/all_ templates> syslog template UUID icdx UUID — null | <GET: /settings/all_ templates> ICDx template UUID (new) Boolean false true | false emails array — <user>@<domain>.<tld> Email address(es) applianceId array null null | <GET: /cmc_ settings/appliances> CMC Only. IDs of sensors where the rule is written favorites phantomcyber X Remote notifications; array includes snmp, smtp, syslog, emails, icdx, phantomcyber 341 True — Splunk Phantom output is enabled (new) Security Analytics Reference Guide REQ Security Analytics 8.1 Format Default Valid Inputs alertInterval seconds 900 1-<n> Valid if type=1 or type=268435457 900 = 15 minutes importance integer 1 1 | 2 | 3 Valid if type=1 or type=268435457 integrationProviders Description n 1 — Notice n 2 — Warning n 3 — Critical array — <GET: /integration_ providers/all_ providers> Valid if type=2 or type=268435458; real-time enrichment provider IDs mountId integer 0 <GET: /pcap_ import/connections> Valid if type=4 or type=268435460; PCAP server mount points pcapng Boolean true true | false Valid if type=4 or type=268435460; PCAP export format n True — PCAPNG n False — PCAP ipfix array — ip string — <ipv4 address> | <ipv6 address> port integer — 1–65535 autonotch array — duration integer 300 <seconds> Valid if type=128 or type=268435584; number of seconds before the filter is removed array ip_ responder, ip_port_ responder, protocol ip_initiator | ip_port_ initiator | ip_responder | ip_port_responder | protocol Valid if type=128 or type=268435584; attributes of the flow to use when creating the BPF filter values Valid if type=8 or type=268435464; array contains ip and port IPFIX server address IPFIX port Valid if type=128 or type=268435584; array contains duration and values 342 Security Analytics Reference Guide REQ Security Analytics 8.1 Format Default Valid Inputs array 0 0 | 1 endPointProviders Example 1 Create a new alert on a CMC and write it to two sensors callAPI('POST','/actions/save', array( 'uuid' => null, 'name' => 'Alert_1', 'type' => 1, 'favorites' => array( <indicator_uuid-1>, <indicator_uuid-2> ), 'applianceId' => array( <sensorID-1>, <sensorID-2> ), 'alertInterval' => 3600, 'importance' => 2, 'shared' => true, 'offBox' => array( 'snmp' => <template_id>, 'emails' => array( <email_address-1>, <email_address-2> ) ) ) ); Example 2 Create a new data-enrichment rule callAPI('POST','/actions/save', array( 'uuid' => null, 'name' => 'Enrichment_1', 'type' => 2, 'favorites' => array( <indicator_uuid-1>, <indicator_uuid-2> ), 'integrationProviders' => array( <enrichment_provider-1>, <enrichment_provider-2> ), 'offBox' => array( 'smtp' => <snmp_template_id> 343 Description Valid if type!=128 or type!=268435584 n 0 — Do not send data to endpoint providers n 1 — Send data to endpoint providers Security Analytics Reference Guide Security Analytics 8.1 ) ) ); Example 3 Edit an IPFIX Export rule to change the server IP address callAPI('POST','/actions/save', array( 'uuid' => '<IPFIX_export_rule_uuid>', 'type' => 8, 'favorites' => array( <indicator_uuid-1>, <indicator_uuid-2> ), 'name' => 'PDF to IPFIX', 'ipfix' => array( 'ip' => '<new_ip_address>' ) ) ); Example 4 Create a Dynamic Filter rule callAPI('POST','/actions/save', array( 'uuid' => null, 'name' => 'Netflix Filter', 'type' => 128, 'favorites' => array( '<indicator_uuid-1>' ), 'shared' => true, 'offBox' => array( 'snmp' => '<template_id>', 'emails' => array( '<email_address-1>', '<email_address-2>' ), ), 'autonotch' => array( 'duration' => 30, 'values' => array( 'ip_port_responder', 'protocol' ) ) ) ); Example 5 Create an open-parser rule. 344 Security Analytics Reference Guide Security Analytics 8.1 callAPI('POST','/actions/save', array( 'uuid' => null, 'name' => 'Phone Numbers', 'type' => 268435456, 'favorites' => array( '<indicator_uuid-1>' ), 'openParser' => array( 'regexes' => array( "((?:\+?1[ .-]\s*)?(((\(\s*[2-9]\d{2}\s*\)\s*[ .-]?)|([2-9]\d{2}\s*[ .-])))\s*[2-9]((1[02-9])|([02-9]\d{1}))\s*[ .-]\s*\d{4})" ), 'metaAction' => 2 ) 'shared' => true, 'offBox' => array( 'icdx' => '<template_id>' ) ) ); Example 6 Create a Discard Packets rule. callAPI('POST','/actions/save', array( 'uuid' => null, 'name' => 'Discard Encrypted', 'type' => 256, 'favorites' => array( '<indicator_uuid-1>' ) 'shared' => true, ) ); Activate/deactivate a rule API Path /actions/toggle/<uuid> Description Toggle a rule between active and inactive GUI Location Menu > Analyze > Rules > Activated/Deactivated icon Output array 345 Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ Format Default Valid Inputs X uuid — <GET: /actions> Boolean true true | false uuid action Description UUID of a rule n True — Activate n False — Deactivate Example callAPI('POST','/actions/toggle/<uuid>', array( 'action' => false ) ); Delete a rule API Path /actions/delete Description Delete rules and rule references GUI Location Menu > Analyze > Rules > [delete] Parameters selectedIds REQ Format Default Valid Inputs X array — <GET: /actions> Example callAPI('POST','/actions/delete', array( 'selectedIds' => 'array( '<uuid-1>', '<uuid-2>', '<uuid-3>' ) ) ); 346 Description Array of rule UUIDs to delete Security Analytics Reference Guide Security Analytics 8.1 Security APIs These APIs correspond to remote-access settings that are not specific to a user account, found mostly on the Settings > Security page. Also see: "User Account APIs" on page 386 and "Authentication APIs" on page 100. Generate a Certificate-Signing Request API Path /settings/generate_req Description Generate a certificate-signing request GUI Location Menu > Settings > Security > PKI and SSL Output Boolean Parameters REQ Format Default Valid Inputs countryName X STRING — <2-LETTER DESIGNATOR> Two-letter country designator according to ISO 3166; ALL CAPS stateOrProvinceName X string — <UTF-8 characters> Spelled-out name of state or province localityName X string — <UTF-8 characters> City or town organizationName X string — <UTF-8 characters> Company name organizationalUnitName X string — <UTF-8 characters> Division or department commonName X string — <UTF-8 characters> Domain name (CN) of the server emailAddress X string — <UTF-8 characters> Contact e-mail address Example callAPI('GET','/settings/generate_req', array( 'countryName' => 'US', 'stateOrProvinceName' => 'Utah', 'localityName' => 'Draper', 'organizationName' => 'Symantec', 'organizationalUnitName' => 'Engineering', 'commonName' => 'forensic302.ourcompany.com', 'emailAddress' => 'username@ourcompany.com' ) 347 Description Security Analytics Reference Guide Security Analytics 8.1 ) ); Get the number of passwords to remember API Path /system_security/password_settings Description Configure the PAM CRACKLIB password remember attribute GUI Location Menu > Settings > Security > Password Settings Output array Parameters None Example callAPI('GET','/system_security/password_settings'); Get IPv6 firewall rules API Path /firewall6 Description Retrieve the IPv6 firewall rules GUI Location Menu > Settings > Security > Firewall IPv6 Output array Parameters None 348 Security Analytics Reference Guide Security Analytics 8.1 Example callAPI('GET','/firewall6'); Get IPv4 firewall rules API Path /firewall Description Retrieve the IPv4 firewall rules GUI Location Menu > Settings > Security > Firewall Output array Parameters None Example callAPI('GET','/firewall'); Get password aging API Path /users/password_aging/<id> Description Retrieve how often a user must change the password, in days GUI Location Initial Configuration Output string 349 Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ Format Default Valid Inputs X integer | string — < GET: /settings/users > | admin | root id Example callAPI('GET','/users/password_aging/<id>'); Get password-strength information API Path /system_security/password_strength Description Retrieve the system password-strength attributes. GUI Location n Initial Configuration n Menu > Settings > System > Password Strength Output array Parameters None Example callAPI('GET','/system_security/password_strength'); Get web-access settings API Path /settings/security 350 Description User ID or username Security Analytics Reference Guide Security Analytics 8.1 Description Retrieve an array of remote-access security settings such as maximum authorization attempts, authentication lockout interval GUI Location Menu > Settings > Security > Web Access Output array Parameters None Example callAPI('GET','/settings/security'); Get certificates and keys API Path /settings/pki Description Retrieve certificate and key information GUI Location Menu > Settings > Security > PKI and SSL Output array Parameters None Example callAPI('GET','/settings/pki'); Configure the number of passwords to remember API Path /system_security/password_settings 351 Security Analytics Reference Guide Security Analytics 8.1 Description Configure the PAM CRACKLIB password remember attribute GUI Location Menu > Settings > Security > Password Settings Output integer Parameters remember REQ Format Default Valid Inputs X integer — 0–10 Description Number of passwords to remember Example callAPI('POST','/system_security/password_settings' array( 'remember' => 8 ) ); Configure an IPv6 firewall rule chain API Path /firewall/add_rules6 Description Add one or more rule chains to the IPv6 firewall GUI Location Menu > Settings > Security Output array Parameters REQ Format Default Valid Inputs X array — — chain string INPUT INPUT Type of chain; only INPUT is valid position integer — 0–<n> Position in the rule chain; default is last position rules 352 Description Array of rule objects; array contains all other parameters Security Analytics Reference Guide REQ Security Analytics 8.1 Format Default Valid Inputs match array — comment | state | <service name> Match extension; array may contain comment, state, or a service name; the parameter specified here must be included in the rules array comment string — <ASCII-printable characters> Up to 250 ASCII-printable characters state string — NEW | ESTABLISHED | RELATED | INVALID destination string — <ipv6> | <ipv6:CIDR> destinationport string — 1–65536 | <service name> in-interface string — <GET: /captures/list_ interfaces> | ANY Interface where the packet is received jump string — ACCEPT | DROP | QUEUE | RETURN Policy — The action to take when the rule matches mac string — <ethernet address> Hardware address protocol string — <service name> | all Protocol for the rule source string — <ipv6> | <ipv6:CIDR> Source IP address or CIDR-formatted network source-port string — 1–65536 | <service name> Example callAPI('POST','/firewall/add_rules6', array( 'rules' => array( array => chain => INPUT, position => 0, match => array( 'icmp6', 'in-interface' ), source => '2620:25:0:8a8f::/64', source-port => 'icmp6', in-interface => 'eth3', jump => 'ACCEPT', protocol => 'icmp6', state => 'NEW' ), array => chain => INPUT, position => 0, match => array( 'icmp6', 'in-interface' ), source => '2620:7a:3e:100::/64', source-port => 'icmp6', 353 Description State of the connection Destination IP address or CIDRformatted network Destination port or service name Source port or service name Security Analytics Reference Guide Security Analytics 8.1 in-interface => 'eth3', jump => 'ACCEPT', protocol => 'icmp6', state => 'NEW' ) ) ) ); Update the IPv6 firewall rule chain API Path /firewall/update_chain6 Description Update the IPv6 rule chain GUI Location Menu > Settings > Security Output array Parameters REQ rules Format Default Valid Inputs Description array — <GET: /firewall6> chain string INPUT INPUT Type of chain; only INPUT is valid position integer — 0–<n> Position in the rule chain; default is last position match array — comment | state | <service name> Match extension; array may contain comment, state, or a service name; the parameter specified here must be included in the rules array comment string — <ASCII-printable characters> Up to 250 ASCII-printable characters state string — NEW | ESTABLISHED | RELATED | INVALID destination string — <ipv6> | <ipv6:CIDR> destinationport string — 1–65536 | <service name> X 354 Array of rule objects; array contains all other parameters State of the connection Destination IP address or CIDRformatted network Destination port or service name Security Analytics Reference Guide REQ Format Security Analytics 8.1 Default Valid Inputs Description in-interface string — <GET: /captures/list_ interfaces> | ANY Interface where the packet is received jump string — ACCEPT | DROP | QUEUE | RETURN Policy — The action to take when the rule matches mac string — <ethernet address> Hardware address protocol string — <service name> | all Protocol for the rule source string — <ipv6> | <ipv6:CIDR> Source IP address or CIDR-formatted network source-port string — 1–65536 | <service name> Example callAPI('POST','/firewall/update_chain6', array( 'rules' => array( array => chain => INPUT, position => 5, match => array( 'icmp6', 'in-interface' ), source => '2620:7a:3e:100::/64', source-port => 'icmp6', in-interface => 'eth3', jump => 'ACCEPT', protocol => 'icmp6', state => 'NEW' ) ) ) ); Delete an IPv6 firewall rule chain API Path /firewall/delete_rules6 Description Delete an IPv6 firewall rule GUI Location Menu > Settings > Security > Firewall IPv6 > [delete rule] Output array 355 Source port or service name Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ Format Default rules X array — position X integer — Valid Inputs Description Array of rule objects; only position is valid <GET: /firewall6> Position in the rule chain of the rule to delete Example callAPI('POST','/firewall/delete_rules6', array( 'rules' => array( array => ( position => 9 ), array => ( position => 10 ) ) ) ); Configure an IPv4 firewall rule chain API Path /firewall/add_rules Description Add one or more rule chains to the IPv4 firewall GUI Location Menu > Settings > Security Output array Parameters REQ Format Default Valid Inputs X array — <GET: /firewall> Array of rule objects; array contains all other parameters chain string INPUT INPUT Type of chain; only INPUT is valid position integer — 0–<n> Position in the rule chain; default is last position rules 356 Description Security Analytics Reference Guide Security Analytics 8.1 REQ Format Default Valid Inputs match array — comment | state | <service name> comment string — <ASCII-printable characters> state string — NEW | ESTABLISHED | RELATED | INVALID destination string — <dotteddecimal> | <CIDR> destination-port string — 1–65536 | <service name> Destination port or service name in-interface string — <GET: /captures/list_ interfaces> | ANY Interface where the packet is received jump string — ACCEPT | DROP | QUEUE | RETURN Policy — The action to take when the rule matches mac string — <ethernet address> Hardware address protocol string — <service name> | all Protocol for the rule source string — <dotteddecimal> | <CIDR> source-port string — 1–65536 | <service name> Example callAPI('POST','/firewall/add_rules', array( 'rules' => array( array => chain => INPUT, position => 0, match => array( 'icmp', 'in-interface' ), source => '203.0.113.0/24', source-port => 'icmp', in-interface => 'eth3', jump => 'ACCEPT', protocol => 'icmp', state => 'NEW' ), array => chain => INPUT, position => 1 match => array( 357 Description Match extension; array may contain comment, state, or a service name; the parameter specified here must be included in the rules array Up to 250 ASCII-printable characters State of the connection Destination IP address or CIDR-formatted network Source IP address or CIDRformatted network Source port or service name Security Analytics Reference Guide Security Analytics 8.1 'icmp', 'in-interface' ), source => '192.0.2.0/24', source-port => 'icmp', in-interface => 'eth3', jump => 'ACCEPT', protocol => 'icmp', state => 'NEW' ) ) ) ); Update the IPv4 firewall rule chain API Path /firewall/update_chain Description Replace the existing IPv4 rule chain with the provided chain GUI Location Menu > Settings > Security Output array Parameters REQ Format Default Valid Inputs X array — <GET: /firewall> chain string INPUT INPUT Type of chain; only INPUT is valid position integer — 0–<n> Position in the rule chain; default is last position match array — comment | state | <service name> Match extension; array may contain comment, state, or a service name; the parameter specified here must be included in the rules array comment string — <ASCII-printable characters> Up to 250 ASCII-printable characters rules 358 Description Array of rule objects; array contains all other parameters Security Analytics Reference Guide REQ Security Analytics 8.1 Format Default Valid Inputs state string — NEW | ESTABLISHED | RELATED | INVALID destination string — <dotted-decimal> | <CIDR> Destination IP address or CIDRformatted network destinationport string — 1–65536 | <service name> Destination port or service name in-interface string — <GET: /captures/list_ interfaces> | ANY Interface where the packet is received jump string — ACCEPT | DROP | QUEUE | RETURN Policy — The action to take when the rule matches mac string — <ethernet address> Hardware address protocol string — <service name> | all Protocol for the rule source string — <dotted-decimal> | <CIDR> Source IP address or CIDR-formatted network source-port string — 1–65536 | <service name> Source port or service name Example callAPI('POST','/firewall/update_chain', array( 'rules' => array( array => chain => INPUT, position => 0, match => array( 'icmp', 'in-interface' ), source => '203.0.113.0/24', source-port => 'icmp', in-interface => 'eth3', jump => 'ACCEPT', protocol => 'icmp', state => 'NEW' ) ) ) ); Delete the IPv4 firewall rule chain API Path /firewall/delete_rules 359 Description State of the connection Security Analytics Reference Guide Security Analytics 8.1 Description Delete an IPv4 firewall rule GUI Location Menu > Settings > Security > Firewall Output array Parameters REQ Format Default rules X array — position X integer — Valid Inputs Array of rule objects; only position is valid <GET: /firewall> Example callAPI('POST','/firewall/delete_rules', array( 'rules' => array( array => ( position => 5 ), array => ( position => 6 ) ) ) ); Set password-strength information API Path /system_security/password_strength Description Configure the system password-strength attributes GUI Location n Initial Configuration n Menu Description > Settings > System > Password Strength Output ApiResultCode 360 Position in the rule chain of the rule to delete Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ Format Default Valid Inputs array null 0-96 Number of characters that must be different in the new password dcredit integer null 0 | 1 1 — Numeral required minlen integer null 6–96 Minimum password length maxrepeat integer null 0–96 Frequency of password occurrence ocredit integer null 0 | 1 1 — Require other (special) characters lcredit integer null 0 | 1 1 — Require lower-case ucredit integer null 0 | 1 1 — Require uppercase difok Description Example callAPI('POST','/system_security/password_strength', array( 'difok' => 0, 'dcredit' => 1, 'minlen' => 15, 'maxrepeat' => 10, 'ocredit' => 1, 'ucredit' => 1, 'lcredit' => 1 ) ); Configure password aging API Path /users/password_aging/<id> Description How often users must change the password, in days GUI Location n Initial Configuration n Menu > Settings > Users and Groups > Users > [edit user] > Password Aging Output array 361 Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ Format Default Valid Inputs Description id X integer | string — admin | <GET: User ID or /users/account_ username info> max_days_between_password_change X integer — 0 | 7 | 14 | 30 | Number of 60 | 90 | 120 | days before 365 the password must be changed n Example callAPI('POST','/users/password_aging/root', array( 'max_days_between_password_change' => '90' ) ); Configure global access settings API Path /settings/security Description Configure GUI-access settings GUI Location Menu > Settings > Security Output array Parameters REQ Format Default Valid Inputs params X array — <GET: /settings/security> Array of parameters, listed below SystemSetting X array — <GET: /settings/security> UI-access setting names 362 Description 0— Never Security Analytics Reference Guide REQ Security Analytics 8.1 Format Default Valid Inputs max_auth_ attempts integer 3 1–32767 auth_lockout_ interval integer 1200 1–99999999 max_web_ sessions integer 10 1–32767 Boolean true true | false web_port integer 80 1–65536 HTTP port number web_port_ secure integer 443 1–65536 HTTPS port number allow_ssh Boolean true true | false ssh_port integer 22 1–65536 SSH port number vpn_port integer 1194 1–65536 CMC Only. CMC VPN port fips_mode Boolean false true | false True — Enable FIPS mode respond_to_ ping Boolean false true | false True — Respond to ICMP pings enable_ firewall Boolean true true | false True — Enable IPv4 firewall enable_ firewall6 Boolean true true | false True — Enable IPv6 firewall only_allow_ secure Example callAPI('POST','/settings/security', 'params' => array( 'SystemSetting' => array( 'max_auth_attempts' => 4, 'max_web_sessions' => 20, 'auth_lockout_interval' => 3600, 'only_allow_secure' => true, 'web_port' => 88, 'web_port_secure' => 443, 'allow_ssh' => 'false, 'ssh_port' => 22, 'vpn_port' => 5194, 'fips_mode' => true, 'respond_to_ping' => true, 'enable_firewall' => true, 'enable_firewall6' => true ) ) ); Edit root password API Path /settings/edit_root_password 363 Description Maximum login attempts Unsuccessful login timeout in seconds Maximum concurrent web sessions True — Require HTTPS access True — Allow SSH access Security Analytics Reference Guide Security Analytics 8.1 Description Edit the root password GUI Location Initial Configuration Output ApiResultCode Parameters REQ Format Default X string — password Valid Inputs <conforms to current password requirements> Description Root password Example callAPI('POST','/settings/edit_root_password', array( 'password' => '3030rootMEouT#$#' ) ); Configure PKI settings API Path /settings/pki Description Configure PKI certificate settings GUI Location Menu > Settings > Security Output array Parameters REQ Format Default Valid Inputs Description server_cert_name X filepath — <filepath> Path to the SSL certificate file server_cert_key X filepath — <filepath> Path to the key file for server_cert_name 364 Security Analytics Reference Guide Security Analytics 8.1 REQ client_verification client_verification_ad use_server_cert client_ca client_crl_url Format Default Boolean false Boolean Boolean false true Valid Inputs true | false true | false true | false Description n True — Verify client certificate n False — No verification; any parameters that follow will be ignored n True — Require client certificate for Login Correlation Service n False — Certificate not required for LCS n True — Use existing SSL certificate and key for CMC/sensor communication; client_ca and client_crl_url will be ignored n False — Use the SSL certificate and key that follow for CMC/sensor communication filepath — <filepath> Path to the issuing authority's certificate; valid when client_ verification=cert or use_server_ cert=false string — <URL>.[pem | der | crl] Certificate revocation list for the issuing authority; valid when client_ verification=true or use_server_ cert=false 365 Security Analytics Reference Guide Security Analytics 8.1 REQ Format Default Valid Inputs Description client_cert_name filepath — <filepath> Path to the SSL client certificate for CMC/sensor communication client_cert_key filepath — <filepath> Path to the key for client_cert_name enable_revocation_check Boolean true true | false Example callAPI('POST','/settings/pki', array( 'server_cert_name' => '/etc/pki/tls/certs/mySSLcert.crt', 'server_cert_key' => '/etc/pki/tls/private/mySSLkey.key', 'client_verification' => true, 'client_ca' => '/etc/pki/tls/certs/CAsslCERT.crt', 'client_crl_url' => 'https://issuer.domain.com', 'user_server_cert' => false, 'client_cert_name' => '/etc/pki/tls/certs/myCLIENTcert.crt', 'client_cert_key' => '/etc/pki/tls/private/myCLIENTkey.key' ) ); 366 True — Check for revocation of the Intelligence Services certificates Security Analytics Reference Guide Security Analytics 8.1 Statistics APIs Get all interface statistics API Path /statistics/network Description Get statistics for all Ethernet interfaces GUI Location Menu > Statistics > Network System Output array Parameters None Example callAPI('GET','/statistics/network'); Get statistics for an interface API Path /statistics/network_details/<interface> Description Get statistics for a specified Ethernet interface GUI Location Menu > Statistics > Network System > [interface name] Output array Parameters interface REQ Format Default Valid Inputs Description X string — ethX | aggX Ethernet or aggregated interface Example callAPI('GET','/statistics/network_details/eth3'); 367 Security Analytics Reference Guide Security Analytics 8.1 Get size of data on disk API Path /statistics/size Description Retrieve the size on disk data for all interfaces; data is cumulative since the last reboot of the appliance GUI Location Menu > Statistics > Size on Disk Output array Parameters None Example callAPI('GET','/statistics/size'); Get storage statistics API Path /statistics/storage Description Retrieve information about the storage system GUI Location Menu > Statistics > Storage System Output object | array Parameters None Example callAPI('GET','/statistics/storage'); 368 Security Analytics Reference Guide Security Analytics 8.1 Summary Page APIs Also see "Report and Report Status APIs" on page 302. Get a list of Summary and Geolocation views API Path /deepsee/summary_views Description Retrieve Summary views and their report widgets; return Geolocation views and their properties GUI Location n Menu > Analyze > Summary > [View Selector] n Menu > Analyze > Summary > Geolocation > [View Selector] Parameters None Python Example s.callAPI("GET","/deepsee/summary_views") PHP Example callAPI('GET','/deepsee/summary_views'); Output 'result': {'geolocation_views': [{'defaultView': True, 'id': 8, 'shared': True, 'text': 'World', 'user_id': 1, 'view_data': {'lat': 0, 'lon': 0, 'zoom': 0}}], 'summary_views': [{'defaultView': True, 'format': 1, 'id': 1, 'reportlets': [{'source': 'application_group'}, {'source': 'application_group_time'}, {'requestParams': {'column': 'sessions', 'direction': 'd', 'metrics': ['sessions'], 'type': 'ranked', 'view': ['table']}, 'source': 'application_id'}, {'source': 'country_initiator'}, {'source': 'country_responder'}], 'shared': True, 'text': 'Default View', 'user_id': 1}, ... {'defaultView': False, 'format': 1, 369 Security Analytics Reference Guide Security Analytics 8.1 'id': 7, 'reportlets': [{'source': 'application_group'}, {'source': 'application_group_time'}, {'source': 'application_id'}, {'source': 'ipv4_initiator'}, {'source': 'ipv4_responder'}, {'requestParams': {'column': 'item', 'direction': 'd', 'metrics': ['sessions'], 'type': 'ranked', 'view': ['table']}, 'source': 'flow_duration'}, {'requestParams': {'column': 'item', 'direction': 'd', 'metrics': ['sessions'], 'type': 'ranked', 'view': ['table']}, 'source': 'bytes'}, {'source': 'dns_name'}, {'source': 'country_initiator'}, {'source': 'country_responder'}, {'source': 'port_initiator'}, {'source': 'port_responder'}], 'shared': True, 'text': 'Anomaly Investigation', 'user_id': 1}]}, 'resultCode': 'API_SUCCESS_CODE', Get report field information API Path /deepsee/field_info Description Retrieve all possible report names, all possible filter terms, all fields that can be used with len_* and num_* queries, all fields grouped by namespace, mapping between flow namespace fields and any corresponding packet namespace field, all fields available for remote notification, and all possible custom fields. GUI Location [Various menus and other screen elements throughout the GUI] Parameters None Python Example s.callAPI("GET","/deepsee/field_info") PHP Example callAPI('GET','/deepsee/field_info'); Output 'result': {'aggregate_fields': ['database_query', 'dns_ancount', 'dns_host_ipv4_addr', 'dns_host_ipv6_addr', 370 Security Analytics Reference Guide Security Analytics 8.1 ... 'voip_id', 'web_query', 'web_server'], 'all_report_fields': ['application_group', 'application_id', 'autogenerated_domain', ... 'voip_id', 'web_query', 'web_server'], 'custom_analytic_fields': [], 'flow_only_report_fields': ['application_group', 'application_id', 'autogenerated_domain', 'autogenerated_domain_score', ... 'voip_id', 'web_query', 'web_server'], 'namespace_fields': {'flows': {'application_group': True, 'application_group_time': True, ... 'web_query': True, 'web_server': True}, 'groups': {'fuzzy_hash': True, 'md5_hash': True, 'sha1_hash': True, 'sha256_hash': True}, 'packets': {'ethernet_address_packet': True, 'ethernet_address_vendors_packet': True, 'modbus_function_code': True, 'modbus_function_code_name': True, 'packet_length': True}, 'verdicts': {'file_signature_verdict': True, 'local_file_analysis_verdict': True, ... 'url_categories': True, 'url_risk_verdict': True}}, 'offbox_possible_fields': ['application_group', 'application_id', ... 'web_query', 'web_server'], 'raw_tsv_fields': ['protocol_family', 'application_ids', ... 'aggregate_web_query_hooks', 'aggregate_web_server_hooks'], 'report_fields': ['application_group', 'application_id', ... 'web_query', 'web_server'], 'search_fields': ['application_group', 'application_id', ... 'tcp_port', 'udp_port']}, 'resultCode': 'API_SUCCESS_CODE', Create or edit a Summary view API Path /deepsee/save_view 371 Security Analytics Reference Guide Security Analytics 8.1 Description Create or edit a Summary or Geolocation view GUI Location n Menu > Analyze > Summary > [View Selector] > Add New View n Menu > Analyze > Summary > Geolocation > [View Selector] > Save Current Map as View Output ApiResultCode Parameters id name REQ Format X integer/null X format string integer Default null Valid Inputs null | <GET: /deepsee/summary_ views> — <UTF-8 characters> 1 1 | 2 Description n Create new — Use null n Edit entry — ID required n Create new — Name required n Edit entry — New name n 1 — Use flow-based columns n 2 — Use fixed columns shared Boolean false true | false True — Shared view default Boolean false true | false True — Default view Python Example s.callAPI("POST","/deepsee/save_view", { 'id': null, 'name': 'E-Mail', 'format': 1, 'shared': True, 'default': True } ) PHP Example callAPI('POST','/deepsee/save_view', array( 'id' => null, 'name' => 'E-Mail', 'format' => 1, 'shared' => true, 'default' => true ) ); 372 Security Analytics Reference Guide Security Analytics 8.1 Add a report widget to a Summary view API Path /deepsee/create_reportlet Description Add one or more report widgets to a view GUI Location n Menu > Analyze > Summary > Actions > Add/Edit Widgets n Menu > Analyze > Summary > [View Selector] > Add New View > Save > Add Report Widget Output array Parameters REQ Format id X integer fields X array Default Valid Inputs Description — <GET: /deepsee/summary_views> ID of the view — <GET: /deepsee/field_info> Python Example s.callAPI("POST","/deepsee/create_reportlet", { 'id': 8, 'fields': [ 'dns_ancount', 'dns_name', 'dns_ttl' ] } ) PHP Example callAPI('POST','/deepsee/create_reportlet', array( 'id' => 8, 'fields' => array( 'dns_ancount', 'dns_name', 'dns_ttl' ) ) ); 373 Array of widgets to add Security Analytics Reference Guide Security Analytics 8.1 Edit a report widget API Path /deepsee/edit_reportlet Description Edit one or more report widgets GUI Location Menu > Analyze > Summary > [selected view] > [edit widget] Output array Parameters REQ Format id X integer — <GET: /deepsee/summary_ ID of the view views> field X string — <GET: /deepsee/summary_ Name of report widget views> X array — <GET: /deepsee/summary_ Parameters to edit; array may views> contain all of the parameters below type string ranked ranked direction string d a | d requestParams column view string array Default item table Valid Inputs Description Only ranked is valid Sort order n a — Ascending n d — Descending item | sessions | bytes | Sort-by field packets | fragments | n item — Report attribute bad_csums table | pie | column | bar Python Example s.callAPI("POST","/deepsee/edit_reportlet", { 'id': 3, 'field': 'tcp_initiator', 'requestParams': { 'type' => 'ranked', 'direction' => 'd', 'column' => 'sessions', 374 n fragments — IP fragments n bad_csums — Bad checksums Display mode Security Analytics Reference Guide Security Analytics 8.1 'view' => [ 'pie' ] } } ) PHP Example callAPI('POST','/deepsee/edit_reportlet', array( 'id' => 3, 'field' => 'tcp_initiator', 'requestParams' => array( 'type' => 'ranked', 'direction' => 'd', 'column' => 'sessions', 'view' => array( 'pie' ) ) ) ); Delete a report widget from a Summary view API Path /deepsee/delete_reportlet Description Delete one or more report widgets from a Summary view GUI Location Menu > Analyze > Summary > [Report Widget] > [delete widget] Output array Parameters REQ Format id X integer fields X array Default Valid Inputs Description — <GET: /deepsee/summary_views> ID of the view — <GET: /deepsee/summary_views> Array of report widgets to delete Python Example s.callAPI("POST","/deepsee/delete_reportlet", { 'id': 7, 'fields': [ 'flow_id', 'interface', 'mime_type' ] 375 Security Analytics Reference Guide Security Analytics 8.1 } ) PHP Example callAPI('POST','/deepsee/delete_reportlet', array( 'id' => 7, 'fields' => array( 'flow_id', 'interface', 'mime_type' ) ) ); Edit the report-widget order in a view API Path /deepsee/edit_reportlet_order Description Change the order in which the report widgets appear in a Summary view. Report widgets not in the order array are deleted from the view. Report widgets newly included in the order array are added to the view. GUI Location Menu > Analyze > Summary > [Summary View] Output ApiResultCode Parameters REQ Format id X integer order X array Default Valid Inputs Description — <GET: /deepsee/summary_views> ID of the view — <GET: /deepsee/summary_views> | <GET: /deepsee/field_info> Python Example s.callAPI("POST","/deepsee/edit_reportlet_order", { 'id': 8, 'order': [ '<first_widget>', '<second_widget>', '<third_widget>', '<fourth_widget>', '<nth_widget>' ] } } PHP Example callAPI('POST','/deepsee/edit_reportlet_order', 376 Names of the widgets in the desired sequence Security Analytics Reference Guide Security Analytics 8.1 array( 'id' => 8, 'order' => array( '<first_widget>', '<second_widget>', '<third_widget>', '<fourth_widget>', '<Nth_widget>' ) ) ); Delete a Summary page view API Path /deepsee/delete_view/<viewId> Description Delete a Summary page view GUI Location Menu > Analyze > Summary > [View Selector] > [Delete View] Output ApiResultCode Parameters viewId REQ Format X integer Default — Valid Inputs Description <GET: /deepsee/summary_views> ID of the view Python Example s.callAPI("POST","/deepsee/delete_view/<viewId>") PHP Example callAPI('POST','/deepsee/delete_view/<viewId>'); 377 Security Analytics Reference Guide Security Analytics 8.1 System APIs Get disk health status API Path /disk_health/download Description Download a file that contains information on the health of system disks GUI Location Click system error banner > Download button Output disk_health_<YYYY-MM-DD>T<zz:zz>_<mmiiss>.log.tar.gz Parameters None Example callAPI('GET','/disk_health/download'); Download the CSR API Path /system/csr Description Download the customer-service report GUI Location Menu > Settings > System Output ApiResultCode Parameters None Example callAPI('GET','/system/csr'); 378 Security Analytics Reference Guide Security Analytics 8.1 Reboot the system gracefully API Path /system/reboot Description Reboot the system after all processes have finished GUI Location Menu > Settings > System > Reboot Output ApiResultCode Parameters None Example callAPI('POST','/system/reboot'); Shut down the system gracefully API Path /system/shutdown Description Shut down the system after all processes have finished GUI Location Menu > Settings > System > Shut Down Output ApiResultCode Parameters None Example callAPI('POST','/system/shutdown'); 379 Security Analytics Reference Guide Security Analytics 8.1 Upgrades APIs Perform upgrade precheck API Path /upgrades/check Description Retrieve the usage statistics on /var and /home and the size of extractions on disk. GUI Location Menu > Settings > Upgrade > Upgrade Precheck button Parameters None PHP Example callAPI('GET','/upgrades/check'); Python Example callAPI("GET","/upgrades/check") Output 'result': {'extractorSize': {'data': '<integer>', 'localizedType': 'Size of Extractions on Disk', 'type': 'extractorSize'}, 'fsck': {'data': [[{'mount': '/boot', 'name': 'BOOT'}]], 'localizedType': 'fsck.label', 'type': 'fsck'}, 'homeSize': {'data': 'Using <b><integer>%</b> of <b>/HOME</b> drive: ' '<b><integer>G</b> used; <b><integer>G</b> available.', 'localizedType': '/home Disk Usage', 'type': 'homeSize'}, 'varSize': {'data': 'Using <b><integer>%</b> of <b>/VAR</b> drive: ' '<b><integer>G</b> used; <b><integer>G</b> available.', 'localizedType': '/var Disk Usage', 'type': 'varSize'}}, 'resultCode': 'API_SUCCESS_CODE', Get upgrade servers API Path /upgrades/list Description Retrieve a list of upgrade servers GUI Location Menu > Settings > Upgrades 380 Security Analytics Reference Guide Security Analytics 8.1 Output array Parameters None Example callAPI('GET','/upgrades/list'); Get the manifest API Path /upgrades/manifest Description Retrieve a list of possible upgrades GUI Location Menu > Settings > Upgrades > Upgrade from Server Output string Parameters serverId filter REQ Format Default Valid Inputs X integer — <GET: /upgrades/list> Boolean true true | false Example callAPI('GET','/upgrades/manifest', array( 'serverId' => 2, 'filter' => 'true' ) ); Get download status API Path /upgrades/download_status 381 Description Upgrade server ID n True — Retrieve only applicable upgrades n False — Retrieve all upgrades Security Analytics Reference Guide Security Analytics 8.1 Description Retrieve the status of an upgrade file's download to an appliance GUI Location Menu > Settings > Upgrades > [progress bar] Output array Parameters REQ Format Default Valid Inputs Description serverId X integer — <GET: /upgrades/list> Upgrade server ID fileName X text — <GET: /upgrades/manifest> Upgrade file name Example callAPI('GET','/upgrades/download_status', array( 'serverId' => 2, 'fileName' => 'atpsa-8.1.1-45000-x86_64-DVD.tar' ) ); Configure upgrade server API Path /upgrades/edit_server Description Create or edit an upgrade-server entry GUI Location Menu > Settings > Upgrade > New Output ApiResultCode Parameters REQ Format Default Valid Inputs type X integer — 1 protocol X integer — 0 | 1 host X string — hostname | <ip_address> 382 Description Reserved. Always use 1 0 — HTTP 1 — HTTPS Location of upgrade server Security Analytics Reference Guide Security Analytics 8.1 REQ Format path X string — /<filepath>/ Must begin and end with slash file_name X string — Manifest.xml Must be this filename username X string — <UTF-8 characters> User name to access the server password X string — <UTF-8 characters> Password for the user name integer — <GET: /upgrades/list> id validate_ certificate Default Valid Inputs true Boolean true | false Description n Create new — Omit field n Edit entry — ID required Valid only if protocol=1; validate the update-server certificate Example callAPI('POST','/upgrades/edit_server', array( 'type' => '1', 'protocol' => '0', 'host' => 'upgrades.domain.com', 'file_name' => 'Manifest.xml', 'path' => '/upgrades/' 'username' => 'admin', 'password' => '55geT!meIn&*' ) ); Delete an upgrade server API Path /upgrades/delete/<id> Description Remove an upgrade server GUI Location Menu > Settings > Upgrade > Delete Output ApiResultCode Parameters REQ Format Default Valid Inputs X integer — <GET: /upgrades/list> id Example callAPI('POST','/upgrades/delete/2'); 383 Description Upgrade server ID Security Analytics Reference Guide Security Analytics 8.1 Download an upgrade file API Path /upgrades/select Description Downloads an upgrade file for local installation. GUI Location Menu > Settings > Upgrade > Upgrade from Server Output ApiResultCode Parameters REQ Format Default Valid Inputs serverId X integer — <GET: /upgrades/list> upgradeFile X string — atpsa-<version>-x86_64DVD.tar Example callAPI('POST','/upgrades/select', array( 'serverId' => 3, 'upgradeFile' => 'atpsa-8.1.1-45000-x86_64-DVD.tar' ) ); Initiate upgrade API Path /upgrades/initiate Description Begin upgrading an appliance GUI Location Menu > Settings > Upgrade > Upgrade from Server Output ApiResultCode 384 Description Server ID Name of upgrade file Security Analytics Reference Guide Security Analytics 8.1 Parameters filename REQ Format Default Valid Inputs X string — atpsa-<version>-x86_64-DVD.tar Example callAPI('POST','/upgrades/initiate', array( 'filename' => 'atpsa-8.1.1-45000-x86_64-DVD.tar' ) ); 385 Description Name of upgrade file Security Analytics Reference Guide Security Analytics 8.1 User Account APIs These APIs correspond to the functions on the [Account_Name] > Preferences dialogs and the Users and Groups Settings page. > Account Settings and[Account_Name] Also see "Authentication APIs" on page 100 and "Security APIs" on page 347. Get logged-in user information API Path /users/account_info Description Retrieve the name, email, and ID of the logged-in user GUI Location [Account Name] > Account Settings Output array Parameters None Example callAPI('GET','/users/account_info'); Get paginated list of users API Path /settings/users Description Retrieve a paginated list of users GUI Location Menu > Settings > Users and Groups > Users Output array 386 Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ Format Default Valid Inputs page integer 1 1–<n> Page to retrieve; first page is 1 limit integer 25 1–100 Number of items per page sort string name name | email | id desc string asc asc | desc Boolean, integer false false | <user_id> userId getAuth getGroups filter Boolean false false | true Description Sort-by field Sort direction n User ID — Return a specific user; run this API once with userId=false to obtain values n False — Return all users n False — Only get failed authorization attempts n True — Get all authorization settings, including lockout interval, failure limit, last attempt Boolean false true | false Get group membership string — <UTF-8 characters> Filter for group names Example callAPI('GET','/settings/users', array( 'page' => 2, 'limit' => 20, 'sort' => 'id', 'direction' => 'desc', 'userId' => 5, 'getAuth' => 'true', 'getGroups' => 'true' ) ); Get logged-in user account preferences API Path /users/setting/<setting> Description Retrieve preference settings for the logged-in user 387 Security Analytics Reference Guide Security Analytics 8.1 GUI Location n [Account Name] > Preferences n [Account Name] > Account Settings Output string | integer Parameters REQ Format Default Valid Inputs X string — unit_network | pagination_ limit | language | totp | mime_type_view | api_time_ prefix | api_time_postfix | dark setting Description Settings on the Account Preferences dialog n totp — Time-based one-time password. Example callAPI('GET','/users/setting/unit_network'); Get default group API Path /settings/group_default Description Retrieve the name of the default user group GUI Location Menu > Settings > Users and Groups Parameters REQ remote Format Default Valid Inputs Description Boolean false true | false CMC only True — Retrieve default remote group Example callAPI('GET','/settings/group_default', array( 'remote' => true ) ); Output 388 Security Analytics Reference Guide Security Analytics 8.1 {'errors': [], 'messages': [], 'paging': [], 'result': {'groupname': 'user', 'id': 2}, 'resultCode': 'API_SUCCESS_CODE', 'validationErrors': {'Group': [], 'Meta': [], 'res': []}} Get groups API Path /settings/groups Description Retrieve a paginated list of groups GUI Location Menu > Settings > Users and Groups > Groups Output array Parameters REQ Format Default Valid Inputs Description page mixed 1 1–<n> Page to retrieve; first page is 1 limit mixed 25 1–100 Number of items per page sort string groupname desc string asc asc | desc getPermissions Boolean false true | false True — Include permissions getUsers Boolean false true | false True — Include users remote Boolean false true | false CMC only True — Include remote groups filter string — <UTF-8 characters> groupname | id | Sort-by field description | default | remote Example callAPI('GET','/settings/groups', array( 'page' => '2', 'limit' => '20', 'sort' => 'groupname', 'desc' => 'desc', 'getPermissions' => true, 'getUsers' => true, 'remote' => true, 'filter' => 'audit' 389 Sort direction Filter for group names Security Analytics Reference Guide Security Analytics 8.1 ) ); Get user group permissions API Path /settings/permission_tree Description Retrieve a list of all possible permissions GUI Location Menu > Settings > Users and Groups > Groups Output array Parameters None Example callAPI('GET','/settings/permission_tree'); Get LDAP groups API Path /settings/list_ldap_groups Description Retrieve a list of LDAP (external) group names; valid only when an LDAP server has been configured and activated GUI Location Menu > Settings > Users and Groups > Groups > LDAP Groups column Output array Parameters REQ search Format Default Valid Inputs string — <UTF-8 characters> 390 Description LDAP group name to search Security Analytics Reference Guide Security Analytics 8.1 Example callAPI('GET','/settings/list_ldap_groups'); Configure per-user password aging API Path /settings/edit_user_chage/<id> Description Configure password aging for a user GUI Location Menu > Settings > Users and Groups > [add/edit user account] Output integer Parameters REQ Format Default Valid Inputs id X integer — <GET: /users/account_ info> passwordAging X integer 0 0 | 7 | 14 | 30 | 60 | 90 | 120 | 365 Example callAPI('POST','/settings/edit_user_chage/33' array( 'passwordAging' => 90 ) ); Generate current user's API key API Path /users/generate_api_key Description Generate a new API key for the current user and overwrite any previous key GUI Location [Account Name] > Account Settings > Reset API Key 391 Description User ID Number of days before the user must change the password Security Analytics Reference Guide Security Analytics 8.1 Output string Parameters None Example callAPI('POST','/users/generate_api_key'); Set user information API Path /users/account_info Description Set the display name and email address for the logged-in user GUI Location [Account Name] > Account Settings Output ApiResultCode Parameters REQ Format Default Valid Inputs X string — <GET: /users/account_info> The display name for the current user string — <username>@<domain>.<tld> Associated email address name email Description Example callAPI('POST','/users/account_info array( 'name' => 'LDAP_admin', 'email' => 'LDAPadmin@domain.com' ) ); Edit a current-user preference — MODIFIED API Path /users/setting/<setting> Description Edit one account preference for the logged-in user 392 Security Analytics Reference Guide Security Analytics 8.1 GUI Location [Account Name] > Preferences Output ApiResultCode Parameters REQ Format Default Valid Inputs setting X string — <GET: /users/setting/<setting>> value X array — Name of the setting Value for setting; array contains one value only, from the parameters below unit_ network string b | B | p pagination_ limit integer 5 | 10 | 15 | 20 | 25 | 50 | 75 | 100 language string eng | fra | jpn | kor totp string <QR code> | ' ' dark Description Unit of measurement to display in results tables. b — Bits B — Bytes p — Packets Number of entries per page Language for the web UI Time-based one-time password to synchronize with Google Authenticator. n ' ' (space) — Disable 2FA n <QR code> — Enable 2FA Boolean true | false mime_type_ view string magic | mime | derived api_time_ prefix integer 0–<n> The number of seconds that will be subtracted from a single timevalue in an API path to calculate the start time api_time_ postfix integer 0–<n> The number of seconds that will be added to a single time-value in an API path to calculate the end time Example callAPI('POST','/users/setting/unit_network', array( 'value' => 'p' 393 True — Display the web UI in dark mode (new) Specify how the file type is displayed in the Type column on the Extractions page. Security Analytics Reference Guide Security Analytics 8.1 ) ); Change current-user password API Path /users/change_password Description Change the password of the logged-in user GUI Location [Account Name] > Account Settings > Change Password Output ApiResultCode Parameters REQ Format Default Valid Inputs oldPw X string — <current password> Old password newPw X string — <current password requirements> New password confirmPw X string — <identical to newPw> Example callAPI('POST','/settings/change_password', array( 'oldPw' => '55geT!meIn&*', 'newPw' => '23leT!meoUt&*', 'confirmPw' => '23leT!meoUt&*' ) ); Create a user group API Path /settings/create_group Description Create a new user group and set the permissions GUI Location Menu > Settings > Users and Groups > Groups > Tools > New 394 Description New password again Security Analytics Reference Guide Security Analytics 8.1 Output integer Parameters REQ name Format Default Valid Inputs Description string — <UTF-8 characters> Name for the group string — <UTF-8 characters> Description of the group default Boolean false true | false deepsee array — <primary_filter> Data-access control filter permissions array — <GET: /settings/permission_tree> Group permission attributes; the attribute must begin with a forward slash ( / ) users array — <GET: /settings/users> Users to assign to the group externalGroups array — <GET: /settings/list_ldap_groups> Boolean false true | false string — <GET: /cmc_settings/appliances> description remote cmcCheck X Example callAPI('POST','/settings/create_group', array( 'name' => 'LDAP_auditors', 'description' => 'Auditors in LDAP groups', 'default' => 'false', 395 True — Make default group External (LDAP) group names to map to this group CMC only. Valid only if remote=true ; array of remote group name CMC only. Sensor key Security Analytics Reference Guide Security Analytics 8.1 'deepsee' => array( 'application_group=authentication' ), 'permissions' => array( '/settings/ldap' => true, '/logs' => true ), 'users' => array( 'ldap_user_1', 'ldap_user_2', 'admin' ), 'externalGroups' => array( 'auditors', 'admins' ), 'remote' => true ) ); Create a new user API Path /settings/create_user Description Create a new local user GUI Location Menu > Settings > Users and Groups > Users > Tools > New Output ApiResultCode Parameters REQ Format Default Valid Inputs username X string — <UTF-8 characters> Username password X string — <current password requirements> Password name string — <UTF-8 characters> Display name email email — <username> @<domain>.<tld> 396 Description Email that is associated with the account Security Analytics Reference Guide REQ groups remote remoteGroups Security Analytics 8.1 Format Default Valid Inputs array — <GET: /settings/groups> Boolean false true | false array — <GET: /settings/groups> Example callAPI('POST','/settings/create_user', array( 'username' => 'ursula_user', 'password' => 'changeMEnow12#$', 'name' => 'Ursula User', 'email' => 'ursulau@domain.com', 'groups' => array( 'user', 'auditor' ), 'remote' => true, 'remoteGroups' => array( 'user', 'auditor' ) ) ); Assign LDAP groups to current user API Path /settings/auto_assign_groups Description Retrieve LDAP groups for the logged-in user, if the user is not local 397 Description Array of group designators n user n admin n auditor n security_admin n < user-defined group> CMC only True — Groups are remote groups CMC only. Valid only if remote=true; array of remote group names n user n admin n auditor n security_admin n <user-defined group> Security Analytics Reference Guide Security Analytics 8.1 GUI Location Menu > Settings > Authentication Output ApiResultCode Parameters None Example callAPI('POST','/settings/auto_assign_groups'); Delete user groups API Path /settings/delete_group/<ids> Description Delete one or more user groups GUI Location Menu > Settings > Users and Groups > Groups > [delete group] Output ApiResultCode Parameters REQ Format Default Valid Inputs X integer — <GET: /settings/groups> Boolean false true | false ids remote Description Comma-delimited IDs of the groups n True — CMC Only. Remote group n False — Local group This value must be the same for all groups to be deleted; in other words, all groups to delete must be either local or remote Example callAPI('POST','/settings/delete_group/<id1>,<id2>,<id3>', array( 'remote' => true ) ); 398 Security Analytics Reference Guide Security Analytics 8.1 Delete users API Path /settings/delete_user/<ids> Description Delete one or more users GUI Location Menu > Settings > Users and Groups > Users > [delete users] Output ApiResultCode Parameters ids REQ Format Default Valid Inputs X integer — <GET: /settings/users> Example callAPI('POST','/settings/delete_user/<id1>,<id2>,<id3>'); Disable a user account API Path /settings/disable_user/<id> Description Disable a user account GUI Location n Menu > Settings > Users and Groups > Users > [edit user] n [Unsuccessful login attempts exceeded] Output ApiResultCode 399 Description Comma-delimited IDs of the user accounts Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ Format Default Valid Inputs X integer — <GET: /settings/users> Boolean true true | false id disable Description ID of the user account True — Disable Example callAPI('POST','/settings/disable_user/<id>', array( 'disable' => true ) ); Edit a user group For this API, all unspecified fields will reset to default (null, false); therefore, it is recommended that you include a value for all fields during an edit to avoid losing permissions or other essential characteristics. API Path /settings/edit_group/<id> Description Edit an existing user group GUI Location n Menu > Settings > Users and Groups > Groups > [edit group] n CMC Only. Menu > Settings > Users and Groups > Remote Groups > [edit group] Output ApiResultCode Parameters REQ Format Default Valid Inputs id X integer — <GET: /settings/groups> Group ID name X string — <UTF-8 characters> | <GET: /settings/groups> Name for the group; required both to create and to edit group string null <UTF-8 characters> default Boolean false true | false True — Set as default group deepsee array null <primary_filter> New primary filter attributes description 400 Description Description for the group Security Analytics Reference Guide REQ Security Analytics 8.1 Format Default Valid Inputs Description permissions array null users array null <GET: /settings/users> remote Boolean false true | false CMC only True — Groups are remote groups externalGroups array null <GET: /settings/groups> CMC only. Valid only if remote=true; array of remote group name cmcCheck string null <GET: /cmc_ settings/appliances> < New permissions GET: /settings/permission_ tree> New user list for the group CMC only. Sensor key Example callAPI('POST','/settings/edit_group/5', array( 'name' => 'LDAP_users_2', 'description' => 'Second tier of LDAP users', 'default' => true, 'deepsee' => array( 'application_group=authentication '), 'permissions' => array( 'ldap' => true, 'logs' => true ), 'users' => array( 'ldap_user_500', 'ldap_user_501', 'admin '), 'remote' => true, 'externalGroups' => array( 'auditors', 'admins' ), 'cmcCheck' => 'B603guSqEJM6pOrq90gJjIjcOKcyn8Jv9BJ1zHYHi5KlOFNmjD' ) ); Edit a user by user ID For this API, all unspecified fields will reset to default (null, false); therefore, it is recommended that you include a value for all fields during an edit to avoid losing permissions or other essential characteristics. API Path /settings/edit_user/<id> 401 Security Analytics Reference Guide Security Analytics 8.1 Description Find an account by user ID and then edit its settings GUI Location Menu > Settings > Users and Groups > Users > [edit user] Output ApiResultCode Parameters REQ Format Default Valid Inputs X integer null <GET: /settings/users> username string null <UTF-8 characters> New username password string null <current password requirements> New password name string null <UTF-8 characters> New display name email email null <username>@<domain>.<tld> New email address groups array null <GET: /settings/groups> remote Boolean false true | false array null <GET: /settings/groups> id remoteGroups Description User ID Array of new group names CMC only True — Groups are remote groups CMC only. Valid only if remote=true; array of remote group name Example callAPI('POST','/settings/edit_user/337', array( 'username' => 'newusername337', 'password' => 'newpassword337', 'name' => 'newdisplayname337', 'email' => 'newemail337@domain.com', 'groups' => 'user', 'remoteGroups' => 'user' ) ); Edit a user by username For this API, all unspecified fields will reset to default (null, false); therefore, it is recommended that you include a value for all fields during an edit to avoid losing permissions or other essential characteristics. 402 Security Analytics Reference Guide Security Analytics 8.1 API Path /settings/edit_user_by_username Description Find an account by username and then edit its settings GUI Location Menu > Settings > Users and Groups > Users > [edit user] Output ApiResultCode Parameters REQ Format Default X string null name string null <UTF-8 characters> New display name email email null <username> @<domain>.<tld> New email account groups array null remote Boolean false true | false CMC only True — Groups are remote groups array null <GET: /settings/groups> CMC only. Valid only if remote=true; array of remote group name username remoteGroups Valid Inputs Description <GET: /settings/users> Username of the account < Array of new group names GET: /settings/groups> Example callAPI('POST','/settings/edit_user_by_username', array( 'username' => 'ursula_user', 'name' => 'ursula_user_00', 'email' => 'ursula@domain.com', 'groups' => 'user', 'remoteGroups' => 'user' ) ); Change user password API Path /settings/edit_user_password/<id> 403 Security Analytics Reference Guide Security Analytics 8.1 Description Change a user's password GUI Location Menu > Settings > Users and Groups > Users > [edit user] Output ApiResultCode Parameters REQ Format Default Valid Inputs id X integer — <GET: /settings/users> password X string — <current password requirements> Example callAPI('POST','/settings/edit_user_password/337', array( 'password' => '3030rootMEouT#$#' ) ); 404 Description User ID New password Security Analytics Reference Guide Security Analytics 8.1 Web Interface Settings APIs Get allowed hosts — NEW API Path /web_interface/allowed_hosts Description Retrieve a list of the alternative hostnames for the appliance. GUI Location Menu > Settings > Web Interface Parameters None PHP Example callAPI('GET','/web_interface/allowed_hosts'); Python Example s.callAPI("GET","/web_interface/allowed_hosts") Output {'errors': [], 'messages': [], 'paging': [], 'result': ['<host1>', '<host2>', '<host3>'], 'resultCode': 'API_SUCCESS_CODE', 'validationErrors': {'AllowedHost': [], 'Meta': [], 'res': []}} Get appliance configuration API Path /config Description Retrieve the information for the appliance, such as build number, license, model GUI Location About Output JSON Parameters None 405 Security Analytics Reference Guide Security Analytics 8.1 Example callAPI('GET','/config'); Get web UI idle timeout API Path /web_interface/web_timeout Description Retrieve the automatic idle timeout for the web UI GUI Location Menu > Settings > Web Interface Output integer Parameters None Example callAPI('GET','/web_interface/web_timeout'); Get external preview state API Path /web_interface/external_preview Description Retrieve the Enable External HTML Elements Preview state GUI Location Menu > Settings > Web Interface Output Boolean Parameters None Example callAPI('GET','/web_interface/external_preview'); 406 Security Analytics Reference Guide Security Analytics 8.1 Get usage-tracking state API Path /web_interface/usage_tracking Description Retrieve the usage-tracking state GUI Location Menu > Settings > Web Interface (not valid for beta versions) Output Boolean Parameters None Example callAPI('GET','/web_interface/usage_tracking'); Get message of the day API Path /web_interface/motd Description Retrieve the message of the day GUI Location Menu > Settings > Web Interface Output string Parameters None Example callAPI('GET','/web_interface/motd'); 407 Security Analytics Reference Guide Security Analytics 8.1 Get Universal Connector state API Path /web_interface/uc_allow Description Retrieve the Universal Connector state GUI Location Menu > Settings > Web Interface Output Boolean Parameters None Example callAPI('GET','/web_interface/uc_allow'); Get referrers API Path /web_interface/referers Description Retrieve the list of referrers GUI Location Menu > Settings > Web Interface Output array Parameters None Example callAPI('GET','/web_interface/referers'); 408 Security Analytics Reference Guide Security Analytics 8.1 Set allowed hosts — NEW API Path /web_interface/allowed_hosts Description Add allowed hostnames for the appliance. GUI Location Menu > Settings > Web Interface Parameters None Python Example s.callAPI('POST', '/web_interface/allowed_hosts', { "hosts": { ["<host1>", "<host2>"] } }) Output { "result": true, "errors": [], "messages": [ "Allowed Hosts settings saved successfully." ], "validationErrors": { "res": [], "AllowedHost": [], "Meta": [] }, "paging": [], "resultCode": "API_SUCCESS_CODE" } Set web UI idle timeout API Path /web_interface/web_timeout Description Set the time for automatic idle timeout GUI Location Menu > Settings > Web Interface Output Boolean 409 Security Analytics Reference Guide Security Analytics 8.1 Parameters REQ Format Default Valid Inputs X integer — 5 | 10 | 30 | 60 | 120 | 240 | 480 | 1440 | 4320 | 7200 | 10080 timeout Description Timeout in minutes Example callAPI('POST','/web_interface/web_timeout' array( 'timeout' => 4320 ) ); Set external preview state API Path /web_interface/external_preview Description Toggle the external HTML preview setting GUI Location Menu > Settings > Web Interface Output Boolean Parameters REQ externalPreview X Format Default Valid Inputs Description Boolean true | false True — External preview enabled — Example callAPI('POST','/web_interface/external_preview' atray( 'externalPreview' => false ) ); Set usage tracking state API Path /web_interface/usage_tracking Description Toggle the usage-tracking state 410 Security Analytics Reference Guide Security Analytics 8.1 GUI Location Menu > Settings > Web Interface (not valid for beta versions) Output Boolean Parameters usageTracking REQ Format Default Valid Inputs Description X Boolean — true | false True — Enable usage tracking Example callAPI('POST','/web_interface/usage_tracking' array( 'usageTracking' => false ) ); Edit Message of the Day API Path /web_interface/motd Description Create or edit the Message of the Day GUI Location Menu > Settings > Web Interface Output Boolean Parameters REQ Format Default Valid Inputs X string — <UTF-8 characters> motd Description Example callAPI('POST','/web_interface/motd' array( 'motd' => 'Hello world' ) ); 411 Message of the day Security Analytics Reference Guide Security Analytics 8.1 Set Universal Connector state API Path /web_interface/uc_allow Description Sets whether to allow the Universal Connector bookmarklet referrer exception (dls.soleranetworks.com) GUI Location Menu > Settings > Web Interface Output Boolean Parameters REQ Format Default Valid Inputs Description X Boolean — true | false True — Allow Universal Connector allow Example callAPI('POST','/web_interface/' array( 'allow' => true ) ); Edit referrers list API Path /web_interface/referers Description Edit the list of referrers GUI Location Menu > Settings > Web Interface Output Boolean Parameters referers REQ Format Default Valid Inputs X array — <domain.tld> | <dotteddecimal> 412 Description Comma-delimited list of devices that are allowed to refer to the appliance Security Analytics Reference Guide Security Analytics 8.1 Example callAPI('POST','/web_interface/referers' array( 'upgrades.soleranetworks.com', '203.0.113.5' ) ); Restart the internal web server API Path /system/restart_apache Description Restart the web server after active processes have finished GUI Location n/a Output ApiResultCode Parameters None Example callAPI('POST','/system/restart_apache'); 413 Security Analytics Reference Guide Security Analytics 8.1 API Appendix 414 Security Analytics Reference Guide Security Analytics 8.1 Using Polling with the APIs Some APIs do not return data immediately because they launch a process that takes more than a few seconds to run. Instead, you must poll the appliance to retrieve the data. The APIs for which you should use polling are: n GET: /deepsee_reports/report n GET: /artifacts/artifacts For these APIs the initial run of the API starts the report or extraction, and then you should continue to run the same API every several seconds — with all of the same parameters (timespan, filters) — to retrieve data incrementally as the report or extraction progresses. When state has reached one of the final states — stopped, stopping, error, or complete — there is no more data to retrieve, and so you can stop polling. The stopped, stopping, and error states indicate that the process has stopped running, but the process may not have finished processing all of the data for the timespan. n To restart a report, first run POST: /report_daemons/stop, run POST: /report_daemons/delete, and then run the same API as before. n To restart an extraction, first run POST: /artifacts/stop, run POST: /artifacts/delete, and then run the same API as before. Symantec recommends that you not use the percent_complete or percentage parameters to determine when a report or extraction has finished. The state parameter is the definitive metric for tracking the process state. Syntax: Identity Path Choose one of the following identity-path formats: Source Format Description < enhanced primary filter > array Timespan plus the JSON equivalent of a Primary Filter; supports operators. This identity path permits you to select the report to run on the Reports Page. <existing item ID> string Available only after the API has already been run once, within the last couple of minutes. These values are mutually exclusive. Syntax: Enhanced Primary Filter Array This array type returns the data from the Reports page on Menu > Analyze > Summary > Reports. (For the Geolocation page see the Geolocation Report example for /deepsee_reports/report). 415 Security Analytics Reference Guide Security Analytics 8.1 See "Advanced API Queries" on page 77 to create complex primary filters. You can also use this array for an extraction by omitting the type, field, and sample attributes. Field REQ Default timespan X — Array consisting of 'start' and 'end' with the dates specified as <YYYY-MM-DD>T<hh:ii:ss> [+|-]<zz:zz> ranked Type of report; ranked — Reports page; geoip — Geolocation page type query field sample X Valid Values / Description — Array of attribute/value pairs in the primary filter bar, including operators and using the primary filter attributes; enclose AttributeOperatorValue in the same set of quotes: 'filename~executive_ report' application_id Report selector for the Reports page; values are the primary filter attribute names for reports. Omit this field for an extraction. 100 Session resolution, expressed as a percentage: 1 | 25 | 50 | 75 | 100 PHP array( 'timespan' => array( 'start' => '2019-11-03T10:00:00+05:00', 'end' => '2019-11-03T10:10:00+05:00' ), 'query' => array( 'port_responder=53', 'dns_name!~internal' ), 'field' => 'tcp_initiator' ) Python { 'timespan': { 'start': '2019-11-03T10:00:00+05:00', 'end': '2019-11-03T10:10:00+05:00' }, 'query': [ 'port_responder=53', 'dns_name!~internal' ], 'field': 'tcp_initiator' } Syntax: Advanced-Filter Array Use this syntax to specify the equivalent of an Advanced Filter in the UI. (See "Advanced Filters" in the Security Analytics 8.1.x Administration and Central Manager Guide on support.symantec.com.) 416 Security Analytics Reference Guide Security Analytics 8.1 Field Valid Values / Description key Appropriate advanced filter attribute: Alerts Click to see values Anomalies Click to see values Analyze > Summary > Reports Click to see values Analyze > Report Status Click to see values Audit Log Click to see values Extractions Geolocation Click to see values; initiator_X and responder_X produce the same results Click to see values Indicators indicator Job Queue id | status | type Retrospective Jobs command (1 — Reindexing, 2 — Reprocessing) source (1 — Auto, 2 — Manual) CMC Only. Sensors label comp = != ~ !~ > >= < <= value Any valid value for the corresponding attribute all Boolean AND any Boolean OR The following examples reduced to Boolean logic are ((ip_address=203.0.113.5) && (url~blue || url~coat)) Python [ 'all':[ { 'key':'ip_address', 'comp':'=', 'value':'203.0.113.5' } { 'any':[ { 'key':'url', 'comp':'~', 'value':'blue' }, { 417 Security Analytics Reference Guide Security Analytics 8.1 'key':'url', 'comp':'~', 'value':'coat' } ] } ] ] PHP array( 'all' => array( array( 'key' => 'ip_address', 'comp' => '=', 'value' => '203.0.113.5' ) array( 'any' => array( array( 'key' => 'url', 'comp' => '~', 'value' => 'blue' ), array( 'key' => 'url', 'comp' => '~', 'value' => 'coat' ) ) ) ) ) Syntax: Primary Filter Array Use this syntax to specify the equivalent of a primary filter in the UI, without the timespan. Consult "Advanced API Queries" on page 77 to use Boolean AND and OR in the filter. Field Description array Array of attribute/value pairs for the primary filter, including the operators. To specify an indicator, run GET: /favorites to get the UUID for favorite. Python [ 'port=8080', 'application_id~http', 'favorite=581cc1a3-b884-4e39-a2f2-67b31e1d64a3' ] PHP json_encode( array( 'port=8080', 'application_id~http', 'favorite=581cc1a3-b884-4e39-a2f2-67b31e1d64a3' ) ) 418 Security Analytics Reference Guide Security Analytics 8.1 Syntax: Timespan Array PHP 'timespan' => json_encode( array( 'start' => '<YYYY-MM-DD>T<hh:ii:ss>[+|-]<zz:zz>', 'end' => '<YYYY-MM-DD>T<hh:ii:ss>[+|-]<zz:zz>' ) ) Python 'timespan':json.dumps({ { 'start':'<YYYY-MM-DD>T<hh:ii:ss>[+|-]<zz:zz>', 'end':'<YYYY-MM-DD>T<hh:ii:ss>[+|-]<zz:zz>' } }) Syntax: Timespan Date Array Python { 'startDate':'<YYYY-MM-DD>T<hh:ii:ss>[+|-]<zz:zz>', 'endDate':'<YYYY-MM-DD>T<hh:ii:ss>[+|-]<zz:zz>' } PHP array( 'startDate' => '<YYYY-MM-DD>T<hh:ii:ss>[+|-]<zz:zz>', 'endDate' => '<YYYY-MM-DD>T<hh:ii:ss>[+|-]<zz:zz>' ) Syntax: Geolocation Internal Labels PHP array( 'ip_cidr' => '<ip>/<mask>', 'long' => <float>, 'lat' => <float>, 'label' => '<string>' ) Python { 'ip_cidr':'<ip>/<mask>', 'long':<float>, 'lat':<float>, 'label':'<string>' } Syntax: Scheduled Events Specify only one value for the array. Valid values depend on the value of frequency. $frequency Valid Values Format Definition daily daily single-value array Every day 419 Security Analytics Reference Guide Security Analytics 8.1 $frequency Valid Values Format Definition weekly Mon | Tue | Wed | Thu | Fri | Sat | Sun single-value array Specify the day of the week monthly [01–31] | [1st | 2nd | 3rd | 4th | last][weekday | weekend_day | Mon | Tue | Wed | Thu | Fri | Sat | Sun] single-value array Specify one of the following: hour 00–23 single-value array Numerical hour minute 00–59 single-value array Numerical minute once <YYYY-MM-DD>T<hh:ii:ss> single-value array Date/time custom array(<MMM>-<ordinal><DDD>,<MMM>-<ordinal><DDD>) multiple-value array n n numerical day of month: 06 for the 6th ordinal plus day: 2nd-Tue, 3rdweekday, last-Sun Irregular dates: Feb-2nd-Thu , Jullast-Fri , Oct-3rd-Mon LDAP Schema Values These attributes are valid for the schema field of the POST: /settings/ldap API. To see further explanations of the attributes, see Specify Mapped LDAP Schema in the Security Analytics 8.1.x Administration and Central Manager Guide on support.symantec.com. Atrribute Schema Name inetorgperson InetOrgPerson mad madrfc2307 Microsoft Active Directory Microsoft Active Directory (RFC 2307) msu20 Microsoft Services for Unix 2.0 msu35 Microsoft Services for Unix 3.5 rfc2307 rfc2307bis user_defined RFC 2307 Network Information Service RFC 2307bis Network Information Service User Defined These attributes are valid for the array in the schema field of the POST: /settings/ldap API. To see futher explanations of the attributes, see Define a New LDAP Schema in the Security Analytics 8.1.x Administration and Central Manager Guide on support.symantec.com. Attribute user_object_ class REQ Format Default string — Valid Inputs UI Label User Object Class 420 Security Analytics Reference Guide Attribute REQ Security Analytics 8.1 Format Default login_name string — Login Name Attribute gecos string — Full Name (GECOS) Attribute user_password string — User Password Attribute string — pam_password_ change Valid Inputs ad clear clear_ remove_old crypt exop exop_send_ old UI Label ADSI Cleartext Cleartext, remove old pw first Crypt RFC 3062 RFC 3062 (send old and new pw) md5 MD5 nds Novell NDS racf Password Change Method ® IBM RACF uid_number X integer — User ID Number Attribute home_directory X string — Home Directory Attribute login_shell string — User Shell Attribute group_object_ class string — Group Object Class integer — Group ID Number Attribute string — Group Membership Attribute gid_number pam_member X 421 Security Analytics Reference Guide Attribute REQ Security Analytics 8.1 Format Default string — rfc_mode Valid Inputs UI Label rfc2307 rfc2307bis Menu UID Distinguished Name Group Membership Type > Analyze > Alerts > Summary Specify alert groups as follows: appliance cached description destination_ip destination_mac destination_port endpoint_providers Menu importance integration_provider match_criteria name indicator rule result score source_ip source_mac source_port type > Analyze > Anomalies > Summary Specify anomaly groups as follows: applications country initiator_ip responder_ip url_categories Capture Summaries Inputs See the View menu on Menu > Capture for details. cpu CPU usage qfto Flow-table overflow ram RAM usage impt PCAP imports fts Flow table size nt s_spsd All capture interfaces, aggregated DPI threads ethX Ethernet interface Slot overflow ifbX Accolade interface tmf Cumulative flow maximum qfc Flows in progress qsd Slots in use qp aggregate Packets in progress uxqueued uxprocd ® File analysis jobs in progress Processed file analysis uxmaxqueue File analysis queue discards uxmaxslrg File analysis range discards 422 Security Analytics Reference Guide qnf Flows initiated Security Analytics 8.1 uxnotlive uxprobes 423 File analysis slot discards File analysis requests Security Analytics Reference Guide Security Analytics 8.1 Using the APIs Consult this page for information on how to use the APIs to perform specific tasks. This page contains examples in Python only. To request that a task sequence be added to this page or that a PHP example be provided, send an email to documentation_inbox@symantec.com with "Security Analytics API Examples" in the subject line. Best Practices n Review Best Searching Practices, Flows in Security Analytics, and Detecting File Types in the Security Analytics 8.1.x Administration and Central Manager Guide on support.symantec.com to see how to create the narrowest possible filters so that system resources are not expended in extracting unwanted artifacts. n Because the APIs refer to web UI functions, you can test the sequence of events that is required to perform the desired task in the web UI first, before creating the API sequence. The GUI Location field in the API documentation shows where the web UI calls the API: API Path /report_daemons/summary_data Description Retrieve the report status summary GUI Location Menu > Analyze > Report Status > Summary Downloading Extracted Artifacts This example shows how to download the artifacts that are produced by an extraction session. Download All Suspected Executables from OFAC Countries During a One-Minute Timespan The equivalent tasks on the web UI for this example would be: n manually editing the timespan filter to the desired span n putting two indicators in the primary filter bar n running the extraction 424 Security Analytics Reference Guide Security Analytics 8.1 n applying advanced filters to the results n selecting artifacts of interest n downloading the artifacts as a single ZIP archive This example will isolate the suspected executables from the other artifacts on the appliance by: n Applying the timespan filter — The timespan filter will be set to one minute to avoid excessively long extraction times. Artifacts outside the timespan will not be extracted. n Applying the indicators as primary filters — Existing indicators will be used as primary filters, which produces only the flows that contain values that match the indicators. n Applying advanced filters — Advanced filters isolate specific artifacts in the matching flows. Step 1: Retrieve the UUIDs for the Indicators This example assumes that these indicators exist on the appliance: n The preloaded indicator Countries - OFAC, containing country="X" filters for countries that are sanctioned by the Office of Foreign Assets Control (US Treasury). n A custom indicator called PE File Type, containing the filter file_type="PE (exe)". This indicator detects executables by examining the file signature/magic number. Run GET: /favorites API This API is the equivalent of applying two advanced filters with the OR operator on the Analyze > Indicators page. ("Favorite" is the internal name for "indicator.") pprint.pprint( s.callAPI( "GET","/favorites", { 'filters': { 'any': [ { 'key': 'indicator', 'comp': '~', 'value': 'ofac' }, { 'key': 'indicator', 'comp': '=', 'value': '"PE File Type"' } ] } } 425 Security Analytics Reference Guide Security Analytics 8.1 ) ) Results The desired data is in the uuid field for each indicator. {'errors': [], 'messages': [], ... 'result': {'pageCount': 1, 'results': [{'active': True, ... 'uuid': '59baf513-a2a4-4ff3-9182-061c1e1d64a3', }, {'active': True, ... 'uuid': '59baf513-356c-4605-a533-061c1e1d64a3', Step 2: Apply Filters and Initiate the Extraction For this iteration the timespan filter will be set to one minute, the indicators will filter out all flows that do not match the indicator values, and the advanced filters limit the artifacts that are returned to those that have the specified attributes. Run GET: /artifacts/artifacts API This API is the equivalent of narrowing the timespan to one minute on Analyze > Summary > Extractions, applying two indicators as primary filters with the OR operator, and applying three advanced filters with the AND operator. In this example, the advanced filters eliminate zero-byte artifacts, file chunks, and artifacts that do not have "application" in the artifact's file_type field. pprint.pprint( s.callAPI( "GET", "/artifacts/artifacts", { 'identityPath': { 'timespan': { 'start': '2019-11-03T10:00:00', 'end': '2019-11-03T10:01:00' }, 'query': [ 'favorite=59baf513-a2a4-4ff3-9182-061c1e1d64a3', 'favorite=59baf513-356c-4605-a533-061c1e1d64a3' ], }, 'filters': { 'all': [ { 426 Security Analytics Reference Guide Security Analytics 8.1 'key': 'file_size', 'comp': '!=', 'value': 0 }, { 'key': 'file_type', 'comp': '~', 'value': 'application' }, { 'key': 'file_extension', 'comp': '!=', 'value': 'part' } ] } } ) ) Results The desired data is in the artifact_search_id field. Notice that state shows new. {'errors': [], 'messages': [], 'paging': [], 'result': {'applianceStatuses': [], ... 'status': {'artifact_search_id': 62, ... 'state': 'new'} Step 3: Poll the Appliance until the Extraction Is Finished The GET: /artifacts/artifacts API does not produce artifacts after the first request; instead, you must poll the appliance every few seconds to retrieve the data incrementally, as the extractions are performed. To poll the appliance, send the same API call as you sent the first time. If you change any item in identityPath from the original API call, you will initiate a new extraction instead of retrieving the artifacts from the initial request. When state equals one of the final states (stopping, stopped, error, complete), the extraction process has finished. Do not use percent_complete or percentage to determine whether the extraction has finished. 427 Security Analytics Reference Guide Security Analytics 8.1 After an extraction has finished, it remains in cache for six hours. Step 4: Obtain the Artifact IDs When the extraction has finished, examine the results from the final API call. The desired information is in the id field for each artifact. 'result': {'applianceStatuses': [], ... 'sorted_artifacts': [{'active': False, ... 'id': 1483520, Step 5: Download the Artifacts Now that you have the artifact IDs, you can download them from the appliance. In this example, seven artifact IDs were returned, and all of them will be downloaded as a single archive called artifacts.zip. Run GET: /artifacts/download This API is the equivalent of selecting artifact check boxes on Analyze > Summary > Extractions and clicking Download Artifacts. This example uses the search ID as the identityPath. Alternatively, you can use the identical identityPath values (timespan, primary filters) as in the original API call. pprint.pprint( s.callAPI('GET', '/artifacts/download', { 'searchId': 62, 'ids': [1483520, 1483529, 1483537, 1483555, 1483564, 1483675, 1483701] }, 'artifacts.zip' ) ) Result The file is downloaded to the directory where the API call resides. {'download_file': 'artifacts.zip', 'filesize': 1911630} Process finished with exit code 0 Downloading PCAPs This example shows how to download the PCAPs of selected flows. 428 Security Analytics Reference Guide Security Analytics 8.1 Download PCAPs of All Flows that Contain URLs that Score 9 or 10 from the Web Reputation Service This example demonstrates how to use a data-enrichment alert to select which PCAPs to download. The equivalent tasks on the web UI would be: n enabling the Web Reputation Service service and rule n setting the advanced filter on the Alerts List page to a 10-minute interval n clicking View Report Summary for each alert n selecting Actions > Download PCAP on the Summary view This example will isolate the suspected flows from the other flows by: n Enabling the Web Reputation Service rule — The Web Reputation Service rule posts alerts of verdicts of 7 or higher. n Applying filters to the alerts list — Advanced filters for alerts can isolate the alerts from a particular provider with a particular verdict during a selected timespan. Step 1: Enable the Web Reputation Service Provider and Rule If you have not already done so, verify that the Web Reputation Service provider and rule are enabled. 1. On the web UI, select Settings > Data Enrichment. 2. Under Symantec Intelligence Services, enable the Symantec Web Reputation Service. 3. Select Analyze > Rules. 4. Enable the Symantec Web Reputation Service rule. Step 2: Retrieve a list of alerts during a 10-minute timespan This example uses a 10-minute timespan for alert retrieval. You should adjust the time interval according to the volume of Web Reputation Service (WRS) alerts that you get. Run GET: /alerts This API is the equivalent of applying two advanced filters with the AND operator as well as setting the timespan. pprint.pprint( s.callAPI( "GET", "/alerts", { 'startDate': '2019-10-02T14:00:00', 'endDate': '2019-10-02T14:10:00', 'filters': { 'all': [ 429 Security Analytics Reference Guide Security Analytics 8.1 { 'key': 'integration_provider', 'comp': '~', 'value': '' }, { 'key': 'score', 'comp': '>=', 'value': '9' } ] } } ) ) Results The desired data is in the flow_id field for each alert. The uuid field contains a unique identifier for each alert, which you may want to use as the PCAP file name. 'result': {'pageCount': 5, 'rows': [{'action': 'Symantec Web Reputation Service', ... 'flow_id': 28162095, ... 'uuid': '2ac29727-462e-4ca4-a4f8-98b10bf4aba1', ... {'action': 'Symantec Web Reputation Service', ... 'flow_id': 28162081, ... 'uuid': 'da01fdda-c4f4-4910-9cc7-df4904a6457c', Step 3: Download the PCAP for Each Alert Flow The next step is to download the PCAP that corresponds to the flow_id. Run GET: /pcap/download/deepsee For each alert hit, download the flow by flow_id, and use the date plus the UUID of the alert as the PCAP file name. You must include the timespan from the original API call. s.callAPI( "GET", "/pcap/download/deepsee", { 'path': '/timespan/2019-10-02T16:00:00_2019-10-02T16:10:00/flow_id/28162095', 430 Security Analytics Reference Guide }, Security Analytics 8.1 'download': { 'type': 1, }, 'pcapType': 'pcap' '2019-10-02_2ac29727-462e-4ca4-a4f8-98b10bf4aba1.pcap' ) Results Process finished with exit code 0, and the PCAPs downloaded to the same directory where the API call is located. 431 Security Analytics Reference Guide Security Analytics 8.1 Resources Consult these resources for assistance with your Security Analytics implementation: n Required Ports, Protocols and Services for Symantec Enterprise Security Products (https://www.symantec.com/docs/DOC11287) n All Security Analytics documentation (https://support.symantec.com/us/en/documentation.1145515.html) n Security Analytics support page (https://support.symantec.com/us/en/product.security-analytics.html) n Symantec Support (https://support.symantec.com/us/en/contact-us.html) 432