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 12 Manual Backup 12 Encrypted Backup 12 Scheduled Backup 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 26 dscapture cleartime 27 dscapture init 27 dscapture map 27 dscapture mapshow 27 dscapture settime 28 dscapture shutdown 28 dscapture start 28 dscapture status 29 dscapture stop 29 dscapture unmap 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 48 Stateless Restart 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_
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 75 Modified APIs 75
Advanced API Queries 77 Example Queries 77 Combining Different Namespaces 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 415 Syntax: Advanced-Filter Array 416 Syntax: Primary Filter Array 418 Syntax: Timespan Array 419 Syntax: Timespan Date Array 419 Syntax: Geolocation Internal Labels 419 Syntax: Scheduled Events 419 LDAP Schema Values 420 Menu > Analyze > Alerts > Summary 422 Menu > Analyze > Anomalies > Summary 422 Capture Summaries Inputs 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 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 Database tables (system and user- defined) n List of active extractor-plugins licensing 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 5- digit 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=
where
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-
/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: solera- 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-
Encrypted:
/etc/utils/solera-restore.sh solera-backup-
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) Excludes all syslog traffic (not port 514)
(!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 Excludes traffic on ports 443, 123, and 53 53)
!(net 203.0.113.0 mask Excludes traffic on network 203.0.113.0 with a 24-bit mask. You can specify a 255.255.255.0) dotted triple, dotted pair, or a single number, and the mask will be !(net 203.0.113) automatically assumed as 255.255.255.0 for a dotted triple, 255.255.0.0 for !(net 203.0.113.0/24) 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) Includes all traffic on ports 80 and 3389 only (port 80 or 3389)
(vlan && host 192.0.2.35) Includes all 802.11Q-tagged traffic to and from 192.0.2.35 (vlan and host 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[
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] =
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 Other system daemons process messages
4 auth Authorization system or programs that ask for user names and passwords (login, su, getty, ftpd) process messages
5 syslog System log process messages
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 A separate flag for routing authorization messages to a log file that has more restricted permissions than those of auth.
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 Daemon alternate ID for cron (clock/timing) subsystem process messages
16–22 local use Reserved for site-specific messages 0 through 7
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:
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:
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, X mount, etc.). Ruby script. Uses a config file.
build-ds-extras Constructs database/home-apache for JBOD systems (format, X filesystem, fstab, mount, etc.). Ruby script.
build-ds-index Constructs index file system (partition, format, filesystem, fstab, mount, X etc.). Ruby script. Uses a config file.
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 X tarball (Customer Service Report). Used for troubleshooting an appliance. BASH script.
21 Security Analytics Reference Guide Security Analytics 8.1
Command Use sudo
dmidecode Intel-based hardware only. Runs -s
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, X recycle head location, etc.).
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 X reinitializes the data storage. Destroys all existing capture and index data.
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. X
getpmap.sh Used by csr.sh. BASH script.
gindiag.sh Gathers relevant information to assist in troubleshooting a GIN connection.
22 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 X 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. X Ruby script.
lspci Shows all hardware attached to the PCI bus
megacli SAS RAID-management tool by LSI X MegaCli
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/model- based 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. X
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 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 X
ifup Enables a specified network interface X
ip To view and edit routing, devices, policy routing, and tunnels X
jsondiff Usage: jsondiff
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 X
reboot Reboots the appliance 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 > Settings > System page.
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 --
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
Initializes the system’s data store in preparation for receiving captured data. syntax dscapture --init
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
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
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
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
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
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
29 Security Analytics Reference Guide Security Analytics 8.1
[sudo] dsfilter -l -i
[sudo] dsfilter -c [-f
[sudo] dsfilter -usS -i
[sudo] dsfilter -m [-f
-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
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 > Settings > Security page.
syntax
[sudo] dsfirewall --
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 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
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
subsystem target
snmpv2 trap2sink SNMPv2 trap
informsink SNMPv2 inform
32 Security Analytics Reference Guide Security Analytics 8.1
subsystem target
snmpv3 trap2sink SNMPv3 trap; variables must be entered in this order:
informsink SNMPv3 inform; variables must be entered in this order:
email
syslog server Server IP address or hostname
33 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
snmp trap2sink SNMPv2 trap target
server Press Enter to see SNMP trap servers 0–N
informsink SNMPv2 inform target
server Press Enter to see SNMP inform servers 0–N
email
syslog server Press Enter to see syslog servers 0–N examples [root@hostname ~] [sudo] dslc del snmp trap2sink server [root@hostname ~] [sudo] dslc del email [email protected] [root@hostname ~] [sudo] dslc del syslog server dslc disable
Disables the specified subsystem. syntax [sudo] dslc disable
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:
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
snmp authtrap SNMP authorization traps
snmpd SNMP daemon
syslog 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
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: 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
snmp authtrap SNMP authorization traps
snmpd SNMP daemon
syslog 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 n rocommunity — public n authproto — SHA
n rouser — public n authkey — [empty]
n privproto — AES n trapcommunity — public
n privkey — [empty] n authtrapenable — off n trap sink server port — 161 n snmpdenenable — off n inform sink server port — 162 n version — 1
syslog 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
Configures the logging subsystem as specified: SNMPv2, SNMPv3, email, or syslog, or specifies an SMTP server. syntax
[sudo] dslc set
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 polling Set SNMPv2 authentication
snmpv3 polling Set SNMPv3 authentication
email smtp_server Specify the SMTP server
port Server port; default is 25
sender Specify the sender information
from_line_ [yes | no] Yes = Use the From address specified in the UI, if it override exists.
usestarttls [yes | no] Yes = Use STARTTLS
syslog 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
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 [email protected]
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
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]
-t Retain timestamps (default)
-T Do not retain timestamps
-p Remote SSH port (default: 22)
-i
-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
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] [
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
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 ... >>>
n When importing from 7.x, name is
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
42 Security Analytics Reference Guide Security Analytics 8.1
n 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 [
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.
With Encryption Without Encryption Connection Type (TB/day) (TB/day)
10 Gbps 5.78 32.88
44 Security Analytics Reference Guide Security Analytics 8.1
With Encryption Without Encryption Connection Type (TB/day) (TB/day)
1 Gbps 3.67 7.68
LAN 5.44 8.56
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@
5. From a shell with super-user privileges on the target, launch the dsmigratedata utility:
[root@targethostname ~]# dsmigratedata -s
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-retain- Migrate data without retaining the timestamps timestamp
-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 --without- Migrate data without encryption (Use only when there's no danger if data encryption 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 non- verbose 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:
************** STATS ************************** TOTAL MIGRATED DATA : 292.28 MB TIME ELAPSED : 00:01:25 SLOTS REMAINED 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/
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 > Capture > PCAP Import page of the web interface.
syntax dspcapimport -f
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
list Show all customized port-to-application mappings
add Add a port-to-application mapping:
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:
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=
start
stop
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 Display help.
-v verbose Display all output. This parameter shows every deletion and can include 1000s of lines of output.
-n noexec Output the command without executing it.
-f force Proceed without the ZapALLData confirmation.
-p partition 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.
-i ignore Pass the ignore flag to scotus stop.
-q quick Use reformatting to clear the indexing volume.
-R recursive 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 Retain
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
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_
While in /pfs/create/
[root@
While in /pfs/create/
55 Security Analytics Reference Guide Security Analytics 8.1
[root@
While in /pfs/create/
[root@
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
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 Sat Sep 8 12:37:39 2018 (1536431859) end Sat Sep 8 12:37:41 2018 (1536431861) iface 5 flags 2 Slot 84572 start Sat Sep 8 12:37:41 2018 (1536431861) end Sat Sep 8 12:37:43 2018 (1536431863) iface 5 flags 2 Slot 84573 start Sat Sep 8 12:37:43 2018 (1536431863) end Sat Sep 8 12:37:45 2018 (1536431865) iface 5 flags 2 Slot 84574 start Sat Sep 8 12:37:45 2018 (1536431865) end Sat Sep 8 12:37:48 2018 (1536431868) iface 5 flags 2 Slot 84575 start Sat Sep 8 12:37:48 2018 (1536431868) end Sat Sep 8 12:37:49 2018 (1536431869) iface 5 flags 2 Slot 84576 start Sat Sep 8 12:37:49 2018 (1536431869) end Sat Sep 8 12:37:51 2018 (1536431871) iface 5 flags 2 Slot 84577 start Sat Sep 8 12:37:51 2018 (1536431871) end Sat Sep 8 12:37:53 2018 (1536431873) iface 5 flags 2 Slot 84578 start Sat Sep 8 12:37:53 2018 (1536431873) end Sat Sep 8 12:37:55 2018 (1536431875) iface 5 flags 2 Slot 84579 start Sat Sep 8 12:37:55 2018 (1536431875) end Sat Sep 8 12:37:57 2018 (1536431877) iface 5 flags 2 Slot 84580 start Sat Sep 8 12:37:57 2018 (1536431877) end Sat Sep 8 12:37:58 2018 (1536431878) iface 5 flags 2 Slot 84581 start Sat Sep 8 12:37:58 2018 (1536431878) end Sat Sep 8 12:38:00 2018 (1536431880) iface 5 flags 2 dynfilter
View and manage the dynamic filters.
Set up dynamic filter rules on the Menu > Analyze > Rules page. syntax dynfilter --list [
-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 HASH BPF FILTER STRING eth2 15 561c33b4-ebb8-4cf3-ac6c-1d180a83290b 180047451a0357e6 '(ip and tcp and ((dst host 203.0.113.112) or (src host 203.0.113.112)))' eth2 80 561c33b4-ebb8-4cf3-ac6c-1d180a83290b a15bdcfd7e9f826c '(ip and tcp and ((dst host 198.51.100.11) or (src host 198.51.100.11)))' eth2 140 561c33b4-ebb8-4cf3-ac6c-1d180a83290b 882f0612f001f218 '(ip and tcp and ((dst host 192.0.2.5) or (src host 192.0.2.5)))' 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
[root@hostname ~] dynfilter -k 882f0612f001f218 -i eth2 eth2 140 561c33b4-ebb8-4cf3-ac6c-1d180a83290b 882f0612f001f218 '(ip and tcp and ((dst host 203.0.113.5) or (src host 203.0.133.5)))'
The filter that has been removed is displayed.
To remove all filters from all interfaces for a given rule, go to Menu > Analyze >
Rules on the web UI and disable then enable the rule. lsi-rate-tool
View and alter the initialization rate for adapters on the appliance.
58 Security Analytics Reference Guide Security Analytics 8.1 syntax lsi-rate-tool [
-h, --host IP address of appliance
-P, --port Port ID of port for login
-u, --user UserID of login (default = root)
-p, --passwd Password associated with userID
-r, --retries Maximum number of login retries: default=3
-a, --all Apply rate to all adapters including system RAID adapters
-c, --category Category (default is all categories) CCRate The rate at which the consistency checks are performed on the RAID sets.
ReconRate The rate at which a damaged virtual drive may be reconstructed.
RebuildRate The rate at which a damaged or missing physical disk can be rebuilt.
BGIRate The background initialization rate, which is the rate at which RAID- initialization operations occur.
-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/nu...
-D, --debug Enable debugging output
-H, --help Display help screen
-- End of parameters
reset Resets the default for the category
show (default); Displays the current setting
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 [
-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 Security Analytics 8.1
-H, --help 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 > Settings > Data Enrichment > Third-Party Integration Providers.
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 Display name of the reputation provider. Do not use special characters.
62 Security Analytics Reference Guide Security Analytics 8.1
provider_ Category of the provider: category 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 Search on the SHA256 hash. Supported only in artifact entries. To invoke the provider in reports and report widgets specify any.
fuzzy Search on the fuzzy hash. Supported only in artifact entries. To invoke the provider in reports and report widgets specify any.
url Search on the URL
ip Search on the IP address; enclose an IPv6 address in [square brackets]
host Search on the hostname
any Search on any value
pivot_url Pivot URL. Syntax is http://
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://
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 > Settings > Data Enrichment and scroll to Third-Party On-Demand Reputation Providers.
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 = '
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 Domain" host http://malc0de.com/database/index.php?search=%{TOKEN} "Malc0de Hash" hash http://malc0de.com/database/index.php?search=%{TOKEN} "Malc0de IP" ip http://malc0de.com/database/index.php?search=%{TOKEN} "Malc0de 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 Hash" hash https://totalhash.cymru.com/search/?hash:%{TOKEN} "TotalHash Host" host https://totalhash.cymru.com/search/?dnsrr:%{TOKEN} "TotalHash IP" ip https://totalhash.cymru.com/search/?ip:%{TOKEN} "TotalHash 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 Query Domain" host http://urlquery.net/search?q=%{TOKEN} "URL Query IP" ip http://urlquery.net/search?q=%{TOKEN} "URL Query URL" url http://urlquery.net/search?q=%{TOKEN} "URL Void Domain" host http://www.urlvoid.com/scan/%{TOKEN} "URL 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 Tracker Domain" host https://zeustracker.abuse.ch/monitor.php?host=%{TOKEN} "Zeus Tracker Hash" hash 'https://zeustracker.abuse.ch/monitor.php?show=config&hash='%{TOKEN} "Zeus Tracker IP" ip https://zeustracker.abuse.ch/monitor.php?ipaddress=%{TOKEN} "Zeus Tracker 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
summary Shows the status of a user session such as expiration times and time remaining on the session. Valid values for
clear Clears the user's session from the session DB. This action will log out the user. Valid values for
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
Places the user in a new group with administrator privileges called elevated-admin-
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
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_ Clears the number of unsuccessful login attempts auths
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': [
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://
Where
ipv4_address ipv4_responder ipv6_address ipv6_responder ipv4_initiator tcp_responder ipv6_initiator 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
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://
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_
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 off- box 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 Description
startDate X datetime —
endDate X datetime —
page integer 1 1–
limit integer 25 1–100 Number of items per page
direction string DESC ASC | DESC Sort order
filters array —
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 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':
80 Security Analytics Reference Guide Security Analytics 8.1
'destination_ip': '
Get alerts timeline
API Path /alerts/timeline_data
Description
Retrieve the alerts histogram
GUI Location
Alerts Management Dashboard
Parameters
REQ Format Default Valid Inputs Description
filters array —
startDate X datetime —
endDate X datetime —
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':
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 Format Default Valid Inputs Description
cached Boolean false 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':
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 —
direction string DESC ASC | DESC Sort order
page integer 1 1–
limit integer 25 1–100 Number of items per page
startDate X datetime —
endDate X datetime —
groupBy array () 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':
85 Security Analytics Reference Guide Security Analytics 8.1
'page': 1, 'pageCount':
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':
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 Valid Inputs Description
alerts X array —
alert_uuid X UUID —
workflow_state X integer 0 0 | 10 | 20 | 30 | Workflow state: 40 | 50 n 0 — Unassigned
n 10 — Assigned
n 20 — In progress
n 30 — On hold
n 40 — Resolved
n 50 — Closed
PHP Example callAPI('POST','/alerts/update', array( 'alerts' => array( 'uuid' => '
87 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 Description
fieldName X string — workflow_state | user_id Attribute to change
fieldValue X integer — 0 | 10 | 20 | 30 | 40 | 50 |
startDate X datetime —
endDate X datetime —
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 Description
filters array —
startDate datetime —
endDate datetime —
selectedIDs array —
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 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(
Clear alerts that are selected by check boxes s.callAPI("POST","/alerts/clear_alerts", { 'selectedIDs': [
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–
limit integer 25 1–100 Number of items per page
sort string score score | create_ Sort-by column; corresponds to time sortable column headings in the Anomalies List table.
direction string DESC ASC | DESC Sort order
filters array —
timeRange array —
anomalyAnalysisWindow array —
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 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':
92 Security Analytics Reference Guide Security Analytics 8.1
'paramType': 'named', 'prevPage': [True|False]}}, 'result': {'pageCount':
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 —
timeRange array —
93 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
anomalyAnalysisWindow 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 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':
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–
limit integer 25 1–100 Number of items per page
sort string count
direction string DESC ASC | DESC Sort order
filters array —
groupBy X array —
95 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
timeRange array —
anomalyAnalysisWindow array —
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':
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 —
timeRange array —
anomalyAnalysisWindow array —
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 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': '
100 Security Analytics Reference Guide Security Analytics 8.1
'ldap_server': '
Discover LDAP settings
API Path /settings/ldap_discover
Description
Initiate LDAP discovery
GUI Location
Menu > Settings > Authentication
Output integer
Parameters
REQ Format Default Valid Inputs Description
domain X string —
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 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/
Description
Retrieve the members of an LDAP (external) group
GUI Location n/a
Output array
Parameters
REQ Format Default Valid Inputs Description
group X string —
limit X integer — 1–
Example callAPI('GET','/settings/ldap_groups/admins/100');
103 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': '
Configure LDAP authentication
API Path /settings/ldap
Description
Configure LDAP authentication
GUI Location
Menu > Settings > Authentication
Output
ApiResultCode
Parameters
REQ Format Default Valid Inputs Description
enable string true true | false True — Enable LDAP authentication; auto-discover is not launched
server X string 127.0.0.1
port number 636 0–65535 Port number for the secure LDAP server. This default is New in Security Analytics 8.1.x.
username string —
password string —
test Boolean false true | false True — Test the connection to the LDAP server
search array — Array contains base, scope, group
base string — dc=
scope string sub base | one | sub Search scope
105 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
group string —
group_naming_ string —
encryption Boolean | tls true | false | tls | Encryption type: string | ssl | array:( array 'encryption' => n true — Enable TLS mode [tls | ssl], n false — Disable TLS mode 'check_peer' =>
[true | false]) 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
version integer 3 3 LDAP version; only 3 is valid
schema_options array user_ user_defined | LDAP schema: defined inetorgperson | madrfc2307 | msu20 | n madrfc2307 — Microsoft msu35 | rfc2703 | Active Directory (RFC 2307) rfc2307bis n msu20 — Microsoft Services for Unix 2.0
n msu35 — Microsoft Services for Unix 3.5
schema array — Required if schema_options=user_ defined; array contains all of the fields below
user_object_ string —
login_name string —
gecos string —
user_password string —
106 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
pam_password_ string md5 clear | clear_ Password change method: change remove_old | crypt | md5 | ad | nds | racf n clear — Cleartext | exop | exop_send_ n clear_remove_old — 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 —
home_directory string —
login_shell string —
shadow_object_ string —
group_object_ string —
gid_number string —
pam_member string —
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' => '
107 Security Analytics Reference Guide Security Analytics 8.1
uid_number' => '
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 Description
domain X string —
username X string —
password X string —
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 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 Default Valid Inputs Description
enable X Boolean true | false True — Enable Kerberos single sign-on
kdc X string
realm X STRING —
domain X STRING
username X string —
password X string —
Example callAPI('POST','/settings/kerberos', array( 'enable' => 'true', 'kdc' => '203.0.113.5', 'realm' => 'KERBEROS.COMPANY.COM', 'domain' => '
Configure RADIUS settings
API Path /settings/radius_auth
Description
Enable and configure RADIUS authentication
GUI Location
Menu > Settings > Authentication
109 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 —
port X integer 1812 1–65535 RADIUS port
password X password —
timeout X integer 3 2–60 Number of seconds between the three RADIUS-request retransmissions
Example callAPI('POST','/settings/radius_auth', array( 'enable' => true, 'server' => 'radius.company.com', 'port' => 51812, 'password' => '55geT!meIn&*', 'timeout' => 5 ) );
110 Security Analytics Reference Guide Security Analytics 8.1
BPF Filters APIs Get capture-interface filters
API Path /captures/filter/
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
interface X string — ethX | aggX Ethernet or aggregated 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/
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
id X integer —
Example callAPI('GET','/filters/get/
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 Description
name X string —
filter X BPF —
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/
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 —
Example callAPI('POST','/captures/filter/eth3', array( 'filter' => '4' ) );
Remove a filter from an interface
API Path /captures/filter/remove/
113 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 Format Default Valid Inputs Description
interface X string — ethX | aggX Ethernet or aggregated interface
Example callAPI('POST','/captures/filter/remove/eth3');
Edit a BPF filter
API Path /filters/edit_advanced/
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 Description
id X integer —
name X string —
filter X BPF —
114 Security Analytics Reference Guide Security Analytics 8.1
Example callAPI('POST','/filters/edit_advanced/
Delete a BPF filter
API Path /filters/delete/
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
ids X integer —
Example callAPI('POST','/filters/delete/
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
interface array aggregate ethX | aggX Ethernet or aggregated (aggX) interface; aggregate — Combine data from all interfaces
startTime X integer —
stopTime X integer —
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':
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
REQ Format Default Valid Inputs Description
interfaces 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/
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 Format Default Valid Inputs Description
interface 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 Format Default Valid Inputs Description
interfaces array aggregate
n aggregate — Combine data from all capture interfaces
startTime X string —
stopTime X string —
numPoints integer 1 1 |
n
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 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 Description
page integer 1 1–
limit integer 25 1–100 Number of items per page
direction string DESC ASC | DESC Sort order
sort integer id id | source | stime | etime | Sort-by column command | status | job_start | job_ end | slot_done
filters array —
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 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/
Description
Retrieve the first (oldest) time that has report data for the interface
GUI Location
Menu > Capture > Summary
Parameters
REQ Format Default Valid Inputs Description
interface 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/
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
interface X string — ethX | aggX Ethernet or aggregated 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/
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
interface X string — ethX | aggX Ethernet or aggregated 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/
Description
Retrieve the last (newest) time for packet data on the specified interface
GUI Location
Menu > Capture > Summary
Parameters
REQ Format Default Valid Inputs Description
interface 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/
Description
Start or stop capture on the specified interface
GUI Location
Menu > Capture > Summary
Output array
Parameters
REQ Format Default Valid Inputs Description
interface X string — ethX | aggX Ethernet or aggregated interface; eth0 — All interfaces
stop Boolean false true | false n true — Stop capture interface(s)
n false — Start capture on interface(s)
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/
Description
Hide or show items on the Capture Summary Graph
131 Security Analytics Reference Guide Security Analytics 8.1
GUI Location
Menu > Capture > Summary > View > [menu item]
Output array
Parameters
REQ Format Default Valid Inputs Description
interface X string —
remove X integer — 0 | 1 n 0 — Hide
n 1 — Show
Example callAPI('POST','/captures/save_selected_interface/
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 —
endTime X datetime —
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 Valid Inputs Description
id integer 0
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 Description
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 Security Analytics Reference Guide Security Analytics 8.1
Output array
Parameters
REQ Format Default Valid Inputs Description
interface X string — aggX Aggregated interface to separate
Example callAPI('POST','/captures/interface_unmap', array( 'interface' => 'agg0' ) );
Change interface name
API Path /captures/rename_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 —
Example callAPI('POST','/captures/rename_interface/eth3', array( 'alias' => 'ZONE-3' ) );
Start reindexing or reprocessing
API Path /captures/start_reindex_job
135 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 —
endDate X string —
type X string — reindex | enrichment n reindex — Classification discards are indexed
n enrichment — Data is sent back through the data- enrichment process (reprocess)
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 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':
Parameters
None
Example callAPI('GET','/settings/cmc_first/');
Download authorization key
API Path /cmc_settings/download_appliance_key/
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 Description
id X integer —
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 Security Analytics Reference Guide Security Analytics 8.1
Parameters
REQ Format Default Valid Inputs Description
direction string asc asc | desc Sort order
page integer 0 0–
limit integer 25 1–100 Number of items per page
sort string name name Sort-by column
filter string —
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 Description
page integer 0 0–
limit integer 25 1–100 Number of items per page
sort string name name | model | connected | Sort-by column capturing | last_selected
direction string asc asc | desc Sort direction
filter JSON — label Advanced filter attribute
Example callAPI('GET','/cmc_settings/appliances', array( 'page' => 10, 'limit' => 20, 'sort' => 'model',
139 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/
Description
CMC Only. Retrieve information about selected sensors
GUI Location
CMC > Sensor Selector
Output array
Parameters
REQ Format Default Valid Inputs Description
ids X array —
Example callAPI('GET','/cmc_settings/appliances/
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=
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
REQ Format Default Valid Inputs Description
appliances X integer —
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
REQ Format Default Valid Inputs Description
log_icdx_password X string —
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 Default Valid Inputs Description
name X string —
users array —
groups array —
labels array —
mssfix integer 1400 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/
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 —
name X string —
users array —
groups array —
labels array —
mssfix integer 1400 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/
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 Description
id X integer —
password X string —
PHP Example callAPI('POST','/cmc_settings/download_appliance_key/8' array => ( 'password' => '3nk0dm3' ),
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 Security Analytics Reference Guide Security Analytics 8.1
Parameters
REQ Format Default Valid Inputs Description
server X string —
file X filename —
password X string —
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 VPN port number
server-ipv6 X string fdf9:5fdf:968f:54b9::/64
Example callAPI('POST','/cmc_settings/cmc_server_ipv6', array( 'protocol' => 'tcp6', 'port' => '1194',
149 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 —
labels X array —
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 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 —
labels X array —
Example callAPI('POST','/cmc_settings/remove_appliance_labels', array( 'ids' =>
Create mount point on multiple sensors
API Path /pcap_import_mount_points/aggregate_save?appliance=
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
REQ Format Default Valid Inputs Description
alias X string —
protocol string nfs nfs | cifs Server protocol
serverName X string —
portNum integer 0 1–65535 Port number
directory X string — /
username string —
password string —
applianceIds X array null
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 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 VPN port number
subnet string 10.8.0.0
netmask string 255.255.255.0
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/
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 Description
ids X string —
Example callAPI('POST','/cmc_settings/delete_appliances/
153 Security Analytics Reference Guide Security Analytics 8.1
Save the sensors' last-selected status
API Path /central_manager/select?appliance=
Description
CMC Only. Save the last-selected status of specified sensors
GUI Location
CMC > Sensor Selector
Output
ApiResultCode
Parameters
REQ Format Default Valid Inputs Description
ids X array —
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/
Description
Sensor Only. Remove a CMC from the sensor.
GUI Location
Menu > Settings > Central Management
Output array
154 Security Analytics Reference Guide Security Analytics 8.1
Parameters
REQ Format Default Valid Inputs Description
id X integer —
Example callAPI('POST','/cmc_settings/cmc_client_remove/
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/
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 —
filename X string —
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 Description
ids X array —
filename X string —
Example callAPI('POST','/cmc_settings/upgrade_appliances', array( 'ids' => array(
156 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 Description
file X string —
Example callAPI('POST','/cmc_upgrades/upgrade_delete', array( 'file' => 'atpsa-8.1.1-56488-x86_64-DVD.tar' ) );
157 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–
limit integer 25 1–100 Number of records per page
sort string name name Sort-by column
direction string asc asc | desc Sort order
160 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
edit_type string all all | none | data | Retrieve enrichment providers of the restricted | malware | specified 'edit type': internal | local | threatexplorer n all — Integration providers, SEP, MATI
n none — DeepSight
n data — EDR pivot
n restricted — Third-party on- demand reputation providers
n malware — Analysis providers
n internal — Intelligence Services
n local — Local File Analysis
n threatexplorer — Threat Explorer pivot (new)
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 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 Description
uuid X UUID —
name X string —
Example callAPI('GET','/integration_providers/test_settings' array( 'uuid' =>
Get Malware Analysis task report
API Path /reputations/malware/
Description
Retrieve a task report from Malware Analysis
162 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 Description
serverUuid X integer —
taskId X integer —
Example callAPI('GET','/reputations/malware/
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 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
REQ Format Default Valid Inputs Description
providers X array IntegrationProvider IntegrationProvider
IntegrationProvider X array derp_filters derp_filters
derp_filters array tonic_filter clam_av | cp_mover | Internal name for the cuckoo | file_ file/hash provider or reputation_service | tonic_filter (default fireeye | ftp_mover | data-enrichment filter) icap_cas | jsunpack | lastline | local_ n cp_mover — hash_reputation | Local File noop | norman | scp_ Mover mover | tiscale | n local_hash_ virustotal | yara | reputation — tonic_filter Custom Hash List
n noop — Calculate and Store Hashes
n norman — Malware Analysis
Example callAPI('GET','/integration_providers/derp_filters', array( 'providers' = > array( 'IntegrationProvider' => array( 'derp_filters' => array( 'ftp_mover', 'file_reputation_service' ) )
164 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/
Description
Retrieve an artifact's reputation from the specified provider
GUI Location
Menu > Analyze > Extractions > [artifact entry] > Reputation button
Output array
Parameters
REQ Format Default Valid Inputs Description
artifactId X integer —
provider UUID null null |
artifactField string null
Example callAPI('GET','/reputations/artifact/
Get on-demand reputation
API Path /reputations/reputation/
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 Description
provider X UUID —
value X URL encoding —
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 Description
settings X array () 100 | 90 | 10 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
REQ Format Default Valid Inputs Description
localFileAnalysis X array —
active Boolean 0 or false | true n False or 0 — false 0 | 1 Deactivate
n True or 1 — Activate
Example callAPI('POST','/integration_providers/local_file_analysis', array( 'localFileAnalysis => array( 'clam_av' => array(
171 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 Format Default Valid Inputs Description
interval integer 300 1–
custom Boolean true true | false True = Use the custom update location
url string —
username string —
password string —
Example callAPI('POST','/web_pulse/location', array( 'interval' => 900, 'custom' => true, 'url' => 'https://custom.update.com/updates', 'username' => '
172 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 Format Default Valid Inputs Description
uuid UUID | null null null |
173 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
name X string —
username X string —
address X string —
key X string —
Example callAPI( 'POST', '/integration_providers/norman', array( 'uuid' => null, 'name' => 'MAA-03', 'username' => 'maa_admin', 'address' => '203.0.113.5', 'key' => '
Delete a Malware Analysis appliance
API Path /integration_providers/norman_delete/
Description
Delete the specified Malware Analysis entry
GUI Location
Menu > Settings > Data Enrichment > Malware Analysis
Output array
Parameters
REQ Format Default Valid Inputs Description
uuid X UUID —
Example callAPI('POST','/integration_providers/delete/
174 Security Analytics Reference Guide Security Analytics 8.1
Activate or deactivate an enrichment provider
API Path /integration_providers/toggle/
Description
Activate or deactivate an enrichment provider
GUI Location
Menu > Settings > Data Enrichment > [provider entry]
Output array
Parameters
REQ Format Default Valid Inputs Description
uuid X UUID —
active Boolean true true | false n true — Activate
n false — Deactivate
Example callAPI('POST','/integration_providers/toggle/
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 Security Analytics Reference Guide Security Analytics 8.1
Parameters
REQ Format Default Valid Inputs Description
domainFilters X string —
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
REQ Format Default Valid Inputs Description
ipFilters X string — <[cidr]ip_address> IP addresses, each on its own line; CIDR <[cidr]ip_address> notation is permitted: 192.168/16 <[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 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 Format Default Valid Inputs Description
allowAllIp X Boolean — true | false n true = Allow all IPs and ignore ipList
n false = Allow only IPs in ipList
ipList array —
Example callAPI('POST','/settings/adlistener', array( 'allowAllIp' => false, 'ipList' => array( '192.0.2.200', '203.0.113.5', '198.51.100.98' ) ) );
177 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 Description
time X string —
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
REQ Format Default Valid Inputs Description
timezone X string —
179 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
REQ Format Default Valid Inputs Description
enable X Boolean — true | false n True — Enable NTP
n False — Disable NTP
servers X array () Array of up to 3 NTP servers; array contains ntp_address and ntp_encrypt
ntp_address X string —
ntp_encrypt Boolean 0 0 | 1 Whether to use Autokey encryption
n 0 — Do not use Autokey
n 1 — Use Autokey
password string —
generateKeys Boolean false true | false n True — Generate NTP host keys
n False — Do not generate keys
serverFile1 file null
serverFile2 file null
180 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
serverFile3 file null
Example 1
Enable NTP and specify three servers
callAPI('POST','/settings/ntp', array( 'enable' => true, 'servers' => array( array( 'ntp_address' => '203.0.113.5', 'ntp_encrypt' => 0 ) array( 'ntp_address' => '203.0.113.6', 'ntp_encrypt' => 0 ) array( 'ntp_address' => '203.0.113.7', 'ntp_encrypt' => 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 Description
page integer 1 1–
pageSize integer 25 1–100 Number of items per page
sort string start start | end | name | percent | Sort-by field status
direction string desc asc | desc Sort direction
Example callAPI('GET','/saved', array( 'page' => 10, 'pageSize' => 20, 'sort' => 'status', 'direction' => 'asc' ) );
Get URL to a saved extraction
API Path /saved/url/
Description
Generate a URL to access a saved extraction
GUI Location
Menu > Analyze > Saved Extractions > View extraction icon
182 Security Analytics Reference Guide Security Analytics 8.1
Output string
Parameters
REQ Format Default Valid Inputs Description
id X string —
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 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 Description
ids X array —
Example callAPI('POST','/saved/delete', array( 'ids' => array( '
Configure data-retention settings
API Path /settings/data_retention
Description
Configure data-retention settings
184 Security Analytics Reference Guide Security Analytics 8.1
GUI Location
About > Data-Retention Settings
Output
ApiResultCode
Parameters
REQ Format Default Valid Inputs Description
summary_life integer 0 0–12 Number of months that Capture Summary Chart data is retained.
time_deletion_enabled Boolean false true | false True — Enable time-based data deletion
time_deletion_limit_days integer 0 0–
time_deletion_limit_hours string/integer 0 0–
time_deletion_artifacts Boolean false true | false True — Delete saved reports and 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 Description
identityPath X string | —
page integer 1 1–
pageSize integer 25 1–100 Number of artifacts per page
filters array —
sort string date date | source | type | Sort-by column; sender, recipient, size | sender | recipient and subject are valid only for | subject email artifacts
sortDirection string ASC ASC | DESC Sort order
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 | Size of thumbnails: null 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':
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':
189 Security Analytics Reference Guide Security Analytics 8.1
'response_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': '
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 Description
page integer 1 1–
pageSize integer 25 1–100 Number of entries per page
191 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
sort string start start | name | status | Sort-by column percent | created_by | id
direction string DESC ASC | DESC 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':
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 Format Default Valid Inputs Description
artifactIDs array —
searchID integer null null |
PHP Example callAPI('GET','/artifact/details', array( 'artifactIDs' => array(
Download artifacts
API Path /artifacts/download
Description
Download one or more artifacts
193 Security Analytics Reference Guide Security Analytics 8.1
GUI Location
Menu > Analyze > Summary > Extractions > [artifact entry] > Download
Parameters
REQ Format Default Valid Inputs Description
ids array —
searchId X integer —
type string zip zip | ogg | wav | single 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
mode string — synth_audio synth_audio — Artifact is a VoIP and will be downloaded with both sides of the conversation included
PHP Example 1
Download All Artifacts from an Extraction as a ZIP File
callAPI('GET','/artifacts/download', array( 'searchId' =>
Download All Artifacts from an Extraction as a ZIP File
callAPI("GET","/artifacts/download", { 'searchId':
Download Selected VoIP Artifacts in OGG Format callAPI('GET','/artifacts/download', array( 'ids' => array(
194 Security Analytics Reference Guide Security Analytics 8.1
'mode' => 'synth_audio' ), '
Download Selected VoIP Artifacts in OGG Format s.callAPI("GET","/artifacts/download", { 'ids': [
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 Description
identityPath X string | —
filters X array —
page integer 1 1–
pageSize integer 25 1–100 Number of entries per page
195 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
sort string date date | source | type | Sort-by column size
sortDirection string ASC ASC | DESC Sort order
restart Boolean false true | false True — Run the extraction again
PHP Example callAPI('GET','/artifacts/timeline', array( 'identityPath' =>
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': [
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 Description
artifactId X integer —
PHP Example callAPI('GET','/preview/jsunpackn', array( 'artifactId' => array(
197 Security Analytics Reference Guide Security Analytics 8.1
); Python Example s.callAPI("GET","/preview/jsunpackn", { 'artifactId': [
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': '
Sanitize CSS
API Path /artifacts/sanitize_css/
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 Format Default Valid Inputs Description
artifactId X integer —
PHP Example callAPI('GET','/artifacts/sanitize_css/
Sanitize HTML page by artifact ID
API Path /artifacts/sanitize_html/
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 —
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/
203 Security Analytics Reference Guide Security Analytics 8.1
array( 'cssSource' => 'external', 'scriptSource' => 'captureData', 'imageSource' => 'hide' ) ); Python Example s.callAPI("GET","/artifacts/sanitize_html/
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 Format Default Valid Inputs Description
html X array — HTML text
PHP Example callAPI('GET','/artifacts/sanitize_html_text', array( 'html' => '
Sample Heading1
text
' ) ); Python Example s.callAPI("GET","/artifacts/sanitize_html_text", { 'html': 'Sample Heading1
text
' } )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 Valid Input Description
files X array — Array of files to combine into a single audio file; contains path, type, codec
path X string — /home/apache/artifacts/ Path to input file
type string ogg ogg | wav | raw Requested output file type:
n ogg — Output is Vorbis
n wav — Output is PCM Signed-Integer
codec string Vorbis ulaw | alaw | Vorbis Codec used. Supported codecs:
n ulaw — raw: pcm μ-law, audio/PCMU
n alaw — raw: pcm A-law, audio/PCMA
force Boolean false true | false 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' ) ) ), '
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' } } }, '
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 Description
identityPath X string | —
page integer 1 1–
pageSize integer 25 1–100 Number of entries per page
filters array —
restart Boolean false true | false True — Restart the extraction that is associated with the artifact search
sort string date date | source | type | Sort-by column size | sender | recipient | subject
206 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
sortDirection string ASC ASC | DESC Sort order
PHP Example callAPI('GET','/artifacts/im_conversations', array( 'identityPath' =>
Get IM user image
API Path /im_user/
Description
Retrieve the captured IM image for the user
GUI Location
Menu > Analyze > Summary > Extractions > IM Conversations > Preview
Output
ApiResultCode
207 Security Analytics Reference Guide Security Analytics 8.1
Parameters
REQ Format Default Valid Inputs Description
userId X integer/string —
large Boolean false true | false n True — Full-sized image
n False — Thumbnail version
PHP Example callAPI('GET','/im_user/
Download thumbnail
API Path /thumbnails/
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 —
artifactor X string —
PHP Example callAPI('GET','/thumbnails/
208 Security Analytics Reference Guide Security Analytics 8.1
Python Example s.callAPI("GET","/thumbnails/
Get root cause
API Path /rootcause/
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 Description
id X integer —
artifactSearchId X integer —
PHP Example callAPI('GET','/rootcause/
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 Security Analytics Reference Guide Security Analytics 8.1
Parameters
REQ Format Default Valid Inputs Description
state X Boolean — 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/
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 Description
searchId X integer —
name X string —
PHP Example callAPI('POST','/artifacts/background/
210 Security Analytics Reference Guide Security Analytics 8.1
} )
Stop an incomplete extraction
API Path /artifacts/stop/
Description
Stop an extraction in progress.
GUI Location
Menu > Analyze > Summary > Extractions
Output null
Parameters
REQ Format Default Valid Inputs Description
searchId X integer — < Artifact search ID GET: /artifacts/artifacts >|
PHP Example callAPI('POST','/artifacts/stop/
Delete a saved extraction
API Path /artifacts/delete/
Description
Delete the saved extraction
GUI Location
Menu > Analyze > Extraction Status
Output array
211 Security Analytics Reference Guide Security Analytics 8.1
Parameters
REQ Format Default Valid Inputs Description
searchId X string —
PHP Example callAPI('POST','/artifacts/delete/
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 Format Default Valid Inputs Description
state X Boolean — 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 Format Default Valid Inputs Description
state X Boolean — 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 Format Default Valid Inputs Description
state X Boolean — 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 Format Default Valid Inputs Description
state X Boolean — 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 Format Default Valid Inputs Description
state X Boolean — 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 Format Default Valid Inputs Description
state X Boolean — 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 Format Default Valid Inputs Description
state X Boolean — 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
REQ Format Default Valid Inputs Description
state X string —
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/
Description
Retrieve the geolocation information for an IP address
GUI Location
Menu > Analyze > Summary > Geolocation
Output array
Parameters
REQ Format Default Valid Inputs Description
ip X string —
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 —
id X integer —
shared Boolean false true | false True — Map view is shared
default Boolean false true | false True — Map view is the default
view_data X array — Array containing lat, lon, and zoom
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
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/
Description
Delete a geolocation map view
GUI Location
Menu > Analyze > Summary > Geolocation > [view selector] >
Output array
Parameters
REQ Format Default Valid Inputs Description
id X integer —
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 Security Analytics Reference Guide Security Analytics 8.1
Parameters
REQ Format Default Valid Inputs Description
internal_labels_ Boolean false true | false True = enabled Enable internal subnets
internal_labels array ()
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 —
default_kml_color string 00FFFF
add_routes Boolean false true | false True = Show routes between nodes
kml_colors_ Boolean false true | false True = enabled Enable country colors
223 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
kml_colors array () Array of color/country associations; contains color and country
color hex 000000
country string —
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 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 Description
type X string — city | country | countryv6 File type
file X file —
Example callAPI('POST','/settings/geoip_file', array( 'type' => 'city', 'file' => 'c:\user\maxmind\GeoLite2-city.mmdb' ) );
225 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–
limit integer — 1–100 Number of items per page
sort string name name Sort-by column
direction string ASC ASC | DESC Sort direction
filters JSON —
name string —
shared Boolean null null | true | false n Null — All indicators
n True — Shared indicators only
n False — Non-shared indicators only
chopValues Boolean true true | false 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': [
227 Security Analytics Reference Guide Security Analytics 8.1
'value' => 'RFC1918' ) ) ), 'name' => 'mime', 'uuids' => array(
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 Format Default Valid Inputs Description
uuid UUID 0 0 |
name X string —
n Edit entry — New name
value X JSON —
shared Boolean true true | false True — Shared
applianceIds array null GET: /cmc_ CMC Only. Array of sensors IDs to settings/appliances receive the indicator array (
linked_uuid UUID null null |
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 Security Analytics Reference Guide Security Analytics 8.1
array( 'uuid' =>
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
REQ Format Default Valid Inputs Description
type X string — GET: /favorites/importers File type to import.
importLocation string local local | remote n Local — Browser upload
n Remote — Upload from URI
importFile string —
remoteLocation URI —
applianceIds array null GET: /cmc_ CMC Only. Array of sensors IDs to settings/appliances receive the indicator array (
231 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
shared Boolean true true | false True — Shared
importTypeParam array — GET: /favorites/importers Parameters that are required by each type; array +may contain all of the parameters below
name string —
keepDirection integer 0 0 | 1 Valid if type=snort
1 — Retain the directionality of the original rule
field string —
importSchedule array — Valid only if importLocation=remote; array contains events, frequency, time_ of_execution, end_time_of_ execution
frequency string null daily | weekly | monthly | Valid only if hour | minute | once | importLocation=remote; how often custom to re-import the file at remoteLocation
events array null
time_of_ string null
end_time_of_ string null
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 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/emerging- ciarmy.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
REQ Format Default Valid Inputs Description
selectedIds X array —
applianceIds array null
Example callAPI('POST','favorites/delete', array( 'selectedIds' => array( '
Activate or deactivate an indicator
API Path /favorites/toggle/
Description
Activate or deactivate an indicator
GUI Location
Menu > Analyze > Indicators >
Output array
Parameters
REQ Format Default Valid Inputs Description
uuid X UUID —
234 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
action Boolean true true | false True — Activate
Example callAPI('POST','favorites/toggle/
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': '
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 X string null
Example callAPI('POST','/settings/license_server', array( 'serial' => '
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
REQ Format Default Valid Inputs Description
license X 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–
limit integer 25 1–100 Number of items per page
direction string DESC ASC | DESC Sort order
filters JSON —
sort string time 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':
241 Security Analytics Reference Guide Security Analytics 8.1
'time': '
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': '
242 Security Analytics Reference Guide Security Analytics 8.1
'server': '
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': '
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–
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':
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': '
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 Default Valid Inputs Description
settings X array —
log_icdx_exchange string —
log_icdx_password string —
log_icdx_port integer — 5671 | 5672 5672 — If icdx_ ssl = false 5671 — If icdx_ ssl=true
log_icdx_server string —
log_icdx_username string —
252 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
log_phantomcyber_key string —
log_phantomcyber_ string —
log_snmp_version integer 1 1 | 3 SNMP version; 1=SNMPv2, 3=SNMPv3
log_snmp_ro_community string public
log_snmp_ro_user string public
log_snmp_ro_user2 string —
log_snmp_auth_ string SHA SHA Authentication protocol protocol; valid only if log_ snmp_ version=3; only SHA is valid
log_snmp_auth_ string SHA SHA Second protocol2 authentication protocol (new); valid only if log_ snmp_ version=3; only SHA is valid
log_snmp_auth_ string —
log_snmp_auth_ string —
253 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
log_snmp_encryption_ string AES AES Privacy protocol encryption protocol; valid only if log_ snmp_ version=3; only AES is valid
log_snmp_encryption_ string AES AES Second privacy protocol2 encryption protocol (new); valid only if log_ snmp_ version=3; only AES is valid
log_snmp_encryption_ string —
log_snmp_encryption_ string —
log_snmp_trap_ string —
log_snmp_authtrap Boolean false true | false True — Enable Authtrap
log_snmp_snmpdenable Boolean false true | false True — Enable SNMP polling
log_snmp_inform_ array — — Inform server; servers array must contain position, server, port, version, and optionally secname, authproto, authkey, privproto, and privkey
254 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
position integer — — Position in the list of servers of the same type. First position is 0.
server string —
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 —
authproto string SHA SHA Required if version=3; authentication protocol; only SHA is valid; contained in server arrays
authkey string —
privproto string AES AES Required if version=3; privacy protocol; only AES is valid; contained in server arrays
255 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
privkey string —
log_snmp_trap_servers array — — Trap server; array must contain position, server, port, version, and optionally secname, authproto, authkey, privproto, and privkey
log_syslog_facility integer 0
log_syslog_coalescing Boolean false true | false True — Enable syslog coalescing
protocol string udp tcp | udp | tls | tls-fips Protocol to send syslog messages
log_syslog_servers array — — Syslog server; array must contain position, server, port, protocol
log_email_address string —
log_email_smtp_server string —
log_email_smtp_port integer 25 1–65536 SMTP server port
log_email_smtp_ string —
log_email_smtp_ string —
256 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
log_email_auth_ Boolean false true | false True — SMTP optional authentication required
log_email_use_ Boolean false true | false True — Use starttls STARTTLS
log_email_sender string —
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': '[email protected]', 'log_email_sender': '[email protected]', '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': '[email protected]', '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': '
257 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' => '[email protected]', 'log_email_sender' => '[email protected]', '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' => '[email protected]', '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 Valid Inputs Description
categories X array — array( 'categories' => array( n category — Audit Log '
n Unspecified categories or methods are set to false
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 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 Format Default Valid Inputs Description
uuid UUID | null null null |
name X string
n Edit entry — New name
type X string smtp | snmp | syslog Type of template
email_ X string
delimiter X string ; | <> | \ | : | , | {} | "" | Character to delimit key/value / | () | . | | | ' | \s | () | pairs \t
keyvaluepair X string
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 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 Default Valid Inputs Description
file X file —
Python Example s.callAPI("POST","settings/logging_advanced", { 'file': '
Delete template
API Path /settings/delete_template/
Description
Delete a remote-notification template
GUI Location
Menu > Settings > Communication > Templates
Output
Boolean
Parameters
REQ Format Default Valid Inputs Description
id X UUID —
263 Security Analytics Reference Guide Security Analytics 8.1
Python Example s.callAPI("POST","settings/delete_template/
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
This 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
REQ Format Default Valid Inputs Description
management_interfaces X string — eth
268 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
REQ Format Default Valid Inputs Description
system_name X string —
269 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
dhcp Boolean false true | false True — Enable DHCP and ignore the rest of the settings
ip_address string —
ip_address_secondary string —
netmask string —
netmask_secondary string —
gateway string —
gateway_secondary string
ipv6_address string — [
ipv6_secondaries string — [
ipv6_gateway string — [
Example callAPI('POST','/settings/network/ip_address', array( 'dhcp' => false, 'ip_address' => '203.0.113.5', 'netmask' => '255.255.255.0',
270 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
primary_dns X string —
secondary_dns string —
tertiary_dns string —
override_dns Boolean false true | false True — Override DNS checks and force- save the settings
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
REQ Format Default Valid Inputs Description
http_proxy X string — http:// Web proxy server
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 Security Analytics Reference Guide Security Analytics 8.1
Parameters
REQ Format Default Valid Inputs Description
no_proxy X string —
Example callAPI('POST','/settings/network/no_proxy', array( 'no_proxy' => 'symantec.com,203.0.113.5' ) );
273 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 > Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > Actions > Analyze Packets
n Menu > Analyze > Summary > Extractions > [artifact entry] > Analyze PCAP
Output array
Parameters
REQ Format Default Valid Inputs Description
pcap X string — /timespan/
startPacket integer 1 1–
packetCount integer 1000 1–1000 Number of packets to retrieve
filter string —
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 Format Default Valid Inputs Description
pcap X string /timespan/
packet integer 1
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 Valid Inputs Description
pcap X string — /timespan/
pcapType string pcapng pcap | pcapng If filter is specified, pcapType=pcap
filter string —
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 Default Valid Inputs Description
query X array —
timespan X JSON —
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 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 Default Valid Inputs Description
path X string —
name X string —
pcapType string pcapng pcap | pcapng PCAP format
download array — Download parameters; array includes type and mountId
type integer — 1 | 2 | 3 Download type
n 1 — Browser
n 2 — NFS/CIFS
n 3 — Prepare download
mountId string —
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': '
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' => '
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 Default Valid Inputs Description
interfaces X array ethX| aggX| ifbX Capture interface(s)
start X string
stop X string
type string date size | date Method to calculate stop
filter string
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 Security Analytics Reference Guide Security Analytics 8.1
}, '
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 Valid Inputs Description
path X merge — [
[
filter string —
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)' }, '
280 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)' ),
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 Default Valid Inputs Description
timespan X JSON —
query array —
pcapType string pcapng pcap | pcapng PCAP format
download array — Download parameters; array includes type and mountId
type integer — 1 | 2 | 3 Download type
n 1 — Browser
n 2 — NFS/CIFS
n 3 — Prepare download
mountId string —
filter X string —
Python Example s.callAPI("GET","/pcap/download/query", { 'timespan': { 'start': '2019-11-23T00:00:00', 'end': '2019-11-23T00:07:59'
281 Security Analytics Reference Guide Security Analytics 8.1
}, 'query': [ 'port=80', 'filename~exe' ], 'pcapType': 'pcap', 'download': { 'type': '2', 'mountId': '
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
REQ Format Default Valid Inputs Description
page X integer — 1–
limit integer 25 1–100 Number of rows per page
direction string asc asc | desc Sort order
sort string null 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 Format Default Valid Inputs Description
path string / / | /
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/
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 Description
mountId X integer —
path string / /
Python Example s.callAPI("GET","/pcap_import/explore_remote/
Get list of PCAP import jobs
API Path /pcap_import/jobs/
Description
Retrieve a paginated list of jobs, by job status
GUI Location
Menu > Capture > Import PCAP > Imports
Output array
Parameters
REQ Format Default Valid Inputs Description
jobStatus X integer — 0 | 1 | 2 | 3 | 4 | 5 Status of jobs to retrieve
n 0 — Scheduled
n 1 — Queued
n 2 — Running
n 3 — Complete
n 4 — Failed
n 5 — Canceled
285 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
page integer — 1–
limit integer — 1–100 Number of items per page
direction string desc asc | desc Sort order
sort string null job_id | schedule_id | mount_id Sort-by field | 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/
Get all mount points
API Path /pcap_import/mount_points
Description
Retrieve a list of mount points.
286 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–
limit integer — 1–100 Number of items per page
direction string desc asc | desc Sort direction
287 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
sort string null 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/
Description
Retrieve the PCAP upload status
GUI Location
Menu > Capture > PCAP Import > Imports > Status field
Output array
Parameters
REQ Format Default Valid Inputs Description
jobid X integer —
Python Example s.callAPI("GET","/pcap_import/upload_progress/
288 Security Analytics Reference Guide Security Analytics 8.1
PHP Example callAPI('GET','/pcap_import/upload_progress/
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 Default Valid Inputs Description
files X array —
retain X integer — 0 | 1 n 0 — Do not retain timestamps
n 1 — Retain original timestamps
shared Boolean true true | false True — Shared PCAP
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 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 Default Valid Inputs Description
files X array —
retain X integer — 0 | 1 n 0 — Do not retain timestamps
n 1 — Retain original timestamps
startOffset X integer — 1–
shared Boolean true true | false True — Shared PCAP
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 Security Analytics Reference Guide Security Analytics 8.1
'startOffset' => 3600, 'shared' => false ) );
Import PCAP from workstation
API Path /pcap_import/init_upload/
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
REQ Format Default Valid Inputs Description
pcapFile X URL —
retainTimestamp X integer — 0 | 1 n 0 — Do not retain timestamps
n 1 — Retain original timestamps
shared X integer — 0 | 1 n 0 — Non- shared PCAP
n 1 — Shared PCAP
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 Security Analytics Reference Guide Security Analytics 8.1
Upload PCAP chunks
API Path /pcap_import/upload/
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–
chunks X integer — 0–
file X string —
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/
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 Valid Inputs Description
jobid X integer —
Python Example s.callAPI("POST","/pcap_import/upload_canceled/
Mark PCAP upload as failed
API Path /pcap_import/upload_failed/
Description
Mark a PCAP upload job as failed
GUI Location
Menu > Capture > PCAP Import > Imports > Status field
Output array
Parameters
REQ Format Default Valid Inputs Description
jobid X integer —
error X integer — 0 Only 0 (zero) is valid
Python Example s.callAPI("POST","/pcap_import/upload_failed/
294 Security Analytics Reference Guide Security Analytics 8.1
PHP Example callAPI('POST','/pcap_import/upload_failed/
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 Default Valid Inputs Description
folders X array —
retain X integer — 0 | 1 n 0 — Do not retain timestamps
n 1 — Retain original timestamps
runFreq X integer — 1–
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 Security Analytics Reference Guide Security Analytics 8.1
);
Delete mount points
API Path /pcap_import_mount_points/delete/
Description
Delete one or more mount points
GUI Location
Menu > Capture > Import PCAP > Manage Connections
Output array
Parameters
REQ Format Default Valid Inputs Description
ids X integer —
Python Example s.callAPI("POST","/pcap_import_mount_points/delete/
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
REQ Format Default Valid Inputs Description
alias X string —
protocol string nfs nfs | cifs Server protocol
serverName X string —
portNum integer 0 0–65535 Port number
directory X string — /
username X string —
password X string —
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/
Description
Edit a mount point that has already been configured on the appliance.
297 Security Analytics Reference Guide Security Analytics 8.1
GUI Location
Menu > Capture > Import PCAP > Manage Connections
Output array
Parameters
REQ Format Default Valid Inputs Description
id X integer —
alias X string —
protocol string nfs nfs | cifs Server protocol
serverName X string —
portNum integer 0 1–66535 Port number; 0 — All ports
directory X string — /
username X string —
password X string —
Python Example s.callAPI("POST","/pcap_import_mount_points/edit/
Delete a watch folder
API Path /pcap_import_schedules/delete/
298 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
REQ Format Default Valid Inputs Description
ids X integer —
Python Example s.callAPI("POST","/pcap_import_schedules/delete/
299 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 Output interface
timeSpan X array | — all | live | MM/DD/YYYY n all — Replay the traffic string hh:ii:ss [MM/DD/YYYY that was already hh:ii:ss] 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")
filter BPF —
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 Security Analytics Reference Guide Security Analytics 8.1
) ) );
Delete playback session
API Path /regens/delete/
Description
Delete a playback session
GUI Location
Menu > Capture > Summary > Stop Playback
Output array
Parameters
REQ Format Default Valid Inputs Description
id X string —
Example callAPI('POST','/regens/delete/
301 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 Default Valid Inputs Description
identityPath X string | —
page integer 0 0–
pageSize integer 25 1–100 Number of items per page
column string sessions bytes | packets | sessions Sort-by column. Value must be | fragments | bad_csums | included in metrics. artifacts
direction string desc asc | desc Sort order
filters array —
compType string none bytes | packets | sessions Value on which to make the report | none comparison.
compDate array —
metrics array sessions bytes | packets | sessions Data to return. Corresponds to the | fragments | bad_csums | Results columns on Analyze > Reports. artifacts
type string ranked ranked | geolocation Report type; If type=geolocation, field in the identityPath must equal ipv4_ conversation
sessionId UUID null null |
302 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
restart Boolean false true | false True — Run the report again
extraData array — histogram | no_hearbeat | Extra data to return no_data 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':
304 Security Analytics Reference Guide Security Analytics 8.1
'fragments_count':
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': ['
305 Security Analytics Reference Guide Security Analytics 8.1
'geolocation_max':
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':
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': ['
307 Security Analytics Reference Guide Security Analytics 8.1
'geolocation_totals': None, 'histogram': {'data': [{'columns': [0, 122], 'extra': {'end_time':
308 Security Analytics Reference Guide Security Analytics 8.1
'state': '
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':
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':
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': ['
310 Security Analytics Reference Guide Security Analytics 8.1
'packets_count': 0, 'percentage': 100, 'report_daemon_id':
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–
limit integer 25 1–100 Number of items per page
sort string create_date create_date | start_date | finish_ Sort-by date column
direction string desc asc | desc Sort order
filters array —
311 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':
312 Security Analytics Reference Guide Security Analytics 8.1
'status':
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
REQ Format Default Valid Inputs Description
id X integer —
Python Example s.callAPI('GET', '/job_queue/download', { "id": 5 }) PHP Example s.callAPI('GET', '/job_queue/download', array(
313 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':
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': '
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
REQ Format Default Valid Inputs Description
sessionId X UUID —
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
REQ Format Default Valid Inputs Description
identityPath X string | —
direction string DESC ASC | DESC Sort order
316 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
column string — bytes | packets | sessions | Sort-by column fragments | bad_csums | artifacts | risk | item
PHP Example callAPI('GET','/deepsee_reports/csv', array( 'identityPath' => 3447, 'direction' => 'DESC', 'column' => 'bytes' ), '
Download PDF report
API Path /deepsee_reports/pdf/
Description
Download a report in PDF format.
GUI Location
Menu > Analyze > Summary > Reports > Actions > Download PDF
Parameters
REQ Format Default Valid Inputs Description
identityPath X string | —
direction string — ASC | DESC Sort order
column string — bytes | sessions | packets Sort-by column
317 Security Analytics Reference Guide Security Analytics 8.1
PHP Example callAPI('GET','/deepsee_reports/pdf/3447', array( 'direction' => 'DESC', 'column' => 'bytes' ), '
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
REQ Format Default Valid Inputs Description
path X array —
fields array —
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' ] }, '
318 Security Analytics Reference Guide Security Analytics 8.1
array( 'path' => '/timespan/2019-11-23T00:00:00-07:00_2019-11-23T00:23:59- 07: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' ) ), '
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 Format Default Valid Inputs Description
filters JSON —
page integer 1 1–
limit integer 25 1–100 Number of items per page
sort string count count Sort-by column
direction string DESC ASC | DESC Sort order
groupBy X array — 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':
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 Format Default Valid Inputs Description
filters JSON —
page integer 1 1–
limit integer 25 1–100 Number of items per page
direction string DESC ASC | DESC Sort order
sort string id id | field | start_time | end_ Sort-by column time | age | run_time | name | disk_usage | timespan_start | timespan_end | percentage
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 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':
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–
limit integer 25 1–100 Number of items per page
direction string asc asc | desc Sort order
shared integer 0 0 | 1 | 2 n 0 — Both Shared and Not Shared
n 1 — Not Shared
n 2 — 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':
323 Security Analytics Reference Guide Security Analytics 8.1
'page':
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 Description
query X JSON —
timespan X JSON —
Python Example s.callAPI("GET","deepsee_reports/gauge_path", { 'query': json.dumps([ 'port>10000',
324 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 > Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > More Information dialog
n Menu > Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > Status bar > Search Size field
Parameters
REQ Format Default Valid Inputs Description
startTime X integer —
stopTime X integer —
325 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': '
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 Description
query X JSON —
timespan X JSON —
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 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
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':
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
REQ Format Default Valid Inputs Description
ids X integer —
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 Description
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 Whether the option is selected:
n 0 — Not selected
n 1 — Selected
328 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
email array — Whether the report is to be emailed to specified recipients.
recipient_ array —
reportlets X Boolean false [] | false Can be false or an empty array
timespan array —
Python Example s.callAPI("POST","/deepsee_reports/threat_summary", { 'reportData': { 'delivery': { 'download': { 'selected': 1 }, 'email': { 'selected': 1, 'recipient_list': [ '[email protected]' ] } }, '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( '[email protected]' ) ) ), '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 Format Default Valid Inputs Description
identityPaths X integer —
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 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
REQ Format Default Valid Inputs Description
identityPaths X string | —
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 Security Analytics Reference Guide Security Analytics 8.1
n Menu > Analyze > Summary > Geolocation > Actions > Save
Output
ApiResultCode
Parameters
REQ Format Default Valid Inputs Description
identityPath X string | —
name X string —
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 > Analyze > Summary > (any) Stop button
Output
ApiResultCode
332 Security Analytics Reference Guide Security Analytics 8.1
Parameters
REQ Format Default Valid Inputs Description
identityPath X string | —
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 Description
type X string — pie | bar | column | Chart type scatter
axisScale X string — linear | logarithmic Scale for the y-axis; logarithmic is not valid for type=pie
333 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
numResults X integer — 1–40 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 Valid Inputs Description
id X string — null |
name X string —
n Edit — New name for the report
334 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
shared X integer — 0 | 1 n 0 — Non-shared report
n 1 — Shared report
frequency X string — daily | weekly | monthly | How often to run the report hour | minute | once | custom
events array —
timeOfExecution X string —
endTimeOfExecution X string —
gaugePathJson X JSON —
timeSpan X string — -
recipients email —
outputFormat X string — PDF | CSV Output format for report
reportType X string —
createdByUserID X integer —
appliances integer —
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': '[email protected];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' => '[email protected];security@domaincom', 'outputFormat' => 'PDF', 'reportType' => 'country_responder', 'createdByUserID' => 1 ) );
Delete a scheduled report
API Path /deepsee_reports/schedule_delete/
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 Default Valid Inputs Description
id X integer —
Python Example s.callAPI("POST","/deepsee_reports/schedule_delete/
Activate or deactivate a scheduled report
API Path /deepsee_reports/schedule_toggle/
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 Description
id X integer —
action X string — activate | deactivate Action to perform
Python Example s.callAPI("POST","/deepsee_reports/schedule_toggle/25/deactivate") PHP Example callAPI('POST','/deepsee_reports/schedule_toggle/25/deactivate');
337 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 Description
page integer 1 1-
limit integer 25 1–100 Number of rows per page
direction string ASC ASC | DESC Sort direction
sort string name name Sort-by column
shared integer null null | 0 | 1 | 2 n null — All rules
n 0 — All rules
n 1 — Non-shared rules
n 2 — Shared rules
uuid UUID | array null null | UUID |
Example callAPI('GET','/actions', array( 'page' => 2, 'limit' => 25, 'direction' => 'DESC', 'shared' => 2, 'uuid' => array(
338 Security Analytics Reference Guide Security Analytics 8.1
Download rule scripts
API Path /actions/download
Description
Retrieve workflow scripts
GUI Location
Menu > Analyze > Rules
Output download
Parameters
REQ Format Default Valid Inputs Description
uuid UUID —
applianceId integer null 1-
Example callAPI('GET','/actions/download', array( 'uuid' =>
Create or edit a rule — MODIFIED
API Path /actions/save
Description
Create or edit a rule
GUI Location
Menu > Analyze > Rules > [New | Edit]
339 Security Analytics Reference Guide Security Analytics 8.1
Output array
Parameters
REQ Format Default Valid Inputs Description
uuid X uuid null null |
n Edit — Required
name X string —
n Edit — Optional
type integer 1 0 | 1 | 2 | 4 | 8 | 128 | Valid if open parser is not 256 being used.
268435
n 2 — Data Enrichment
n 4 — PCAP Export
n 8 — IPFIX Export
n 128 — Dynamic Filter
n 256 — Discard Packets (new) To enable open parser, use these values:
n 456 — None
n 457 — Alert
n 458 — Data Enrichment
n 460 — PCAP Export
n 464 — IPFIX Export
n 584 — Dynamic Filter
openParser array — Open parser attributes; array includes regexes, delimiter, and metaAction
regexes string —
340 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
metaAction 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
delimiter string None
favorites X array —
active Boolean true true | false True — Active
shared Boolean true true | false True — Shared
offBox array — Remote notifications; array includes snmp, smtp, syslog, emails, icdx, phantomcyber
snmp UUID — null | SNMP template UUID
smtp UUID — null | SMTP template UUID
syslog UUID — null | syslog template UUID
icdx UUID — null | ICDx template UUID (new)
phantomcyber Boolean false true | false True — Splunk Phantom output is enabled (new)
emails array —
applianceId array null null |
341 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
alertInterval seconds 900 1-
importance integer 1 1 | 2 | 3 Valid if type=1 or type=268435457
n 1 — Notice
n 2 — Warning
n 3 — Critical integrationProviders array —
mountId integer 0
pcapng Boolean true true | false Valid if type=4 or type=268435460; PCAP export format
n True — PCAPNG
n False — PCAP
ipfix array — Valid if type=8 or type=268435464; array contains ip and port
ip string —
port integer — 1–65535 IPFIX port
autonotch array — Valid if type=128 or type=268435584; array contains duration and values
duration integer 300
values array ip_ ip_initiator | ip_port_ Valid if type=128 or responder, initiator | ip_responder type=268435584; ip_port_ | ip_port_responder | attributes of the flow to use responder, protocol when creating the BPF filter protocol
342 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
endPointProviders array 0 0 | 1 Valid if type!=128 or type!=268435584
n 0 — Do not send data to endpoint providers
n 1 — Send data to endpoint providers
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(
Example 2
Create a new data-enrichment rule callAPI('POST','/actions/save', array( 'uuid' => null, 'name' => 'Enrichment_1', 'type' => 2, 'favorites' => array(
343 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' => '
Example 4
Create a Dynamic Filter rule
callAPI('POST','/actions/save', array( 'uuid' => null, 'name' => 'Netflix Filter', 'type' => 128, 'favorites' => array( '
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( '
Example 6
Create a Discard Packets rule. callAPI('POST','/actions/save', array( 'uuid' => null, 'name' => 'Discard Encrypted', 'type' => 256, 'favorites' => array( '
Activate/deactivate a rule
API Path /actions/toggle/
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 Description
uuid X uuid —
action Boolean true true | false n True — Activate
n False — Deactivate
Example callAPI('POST','/actions/toggle/
Delete a rule
API Path /actions/delete
Description
Delete rules and rule references
GUI Location
Menu > Analyze > Rules > [delete]
Parameters
REQ Format Default Valid Inputs Description
selectedIds X array —
Example callAPI('POST','/actions/delete', array( 'selectedIds' => 'array( '
346 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 Description
countryName X STRING — <2-LETTER DESIGNATOR> Two-letter country designator according to ISO 3166; ALL CAPS
stateOrProvinceName X string —
localityName X string —
organizationName X string —
organizationalUnitName X string —
commonName X string —
emailAddress X string —
Example callAPI('GET','/settings/generate_req', array( 'countryName' => 'US', 'stateOrProvinceName' => 'Utah', 'localityName' => 'Draper', 'organizationName' => 'Symantec', 'organizationalUnitName' => 'Engineering', 'commonName' => 'forensic302.ourcompany.com', 'emailAddress' => '[email protected]' )
347 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/
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 Description
id X integer | — < User ID or username string GET: /settings/users > | admin | root
Example callAPI('GET','/users/password_aging/
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 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
REQ Format Default Valid Inputs Description
remember X integer — 0–10 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 Description
rules X array — — Array of rule objects; array contains all other parameters
chain string INPUT INPUT Type of chain; only INPUT is valid
position integer — 0–
352 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
match array — comment | state |
comment string —
state string — NEW State of the connection | ESTABLISHED | RELATED | INVALID
destination string —
destination- string — 1–65536 |
in-interface string —
jump string — ACCEPT | DROP | QUEUE | Policy — The action to take when the RETURN rule matches
mac string —
protocol string —
source string —
source-port string — 1–65536 |
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 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 Format Default Valid Inputs Description
rules X array —
chain string INPUT INPUT Type of chain; only INPUT is valid
position integer — 0–
match array — comment | state |
comment string —
state string — NEW State of the connection | ESTABLISHED | RELATED | INVALID
destination string —
destination- string — 1–65536 |
354 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
in-interface string —
jump string — ACCEPT | DROP | QUEUE | Policy — The action to take when the RETURN rule matches
mac string —
protocol string —
source string —
source-port string — 1–65536 |
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 Security Analytics Reference Guide Security Analytics 8.1
Parameters
REQ Format Default Valid Inputs Description
rules X array — Array of rule objects; only position is valid
position X integer —
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 Description
rules X array —
chain string INPUT INPUT Type of chain; only INPUT is valid
position integer — 0–
356 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
match array — comment Match extension; array may | state |
comment string —
state string — NEW State of the connection | ESTABLISHED | RELATED | INVALID
destination string —
destination-port string — 1–65536 |
in-interface string —
jump string — ACCEPT | DROP | QUEUE | Policy — The action to take RETURN when the rule matches
mac string —
protocol string —
source string —
source-port string — 1–65536 |
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 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 Description
rules X array —
chain string INPUT INPUT Type of chain; only INPUT is valid
position integer — 0–
match array — comment | state |
comment string —
358 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
state string — NEW State of the connection | ESTABLISHED | RELATED | INVALID
destination string —
destination- string — 1–65536 |
in-interface string —
jump string — ACCEPT | DROP | QUEUE | Policy — The action to take when the RETURN rule matches
mac string —
protocol string —
source string —
source-port string — 1–65536 |
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 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 Valid Inputs Description
rules X array — Array of rule objects; only position is valid
position X integer —
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 > Settings > System > Password Strength
Output
ApiResultCode
360 Security Analytics Reference Guide Security Analytics 8.1
Parameters
REQ Format Default Valid Inputs Description
difok 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
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/
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 |
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 0 — Never
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 Description
params X array —
SystemSetting X array —
362 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
max_auth_ integer 3 1–32767 Maximum login attempts attempts
auth_lockout_ integer 1200 1–99999999 Unsuccessful login timeout in seconds interval
max_web_ integer 10 1–32767 Maximum concurrent web sessions sessions
only_allow_ Boolean true true | false True — Require HTTPS access secure
web_port integer 80 1–65536 HTTP port number
web_port_ integer 443 1–65536 HTTPS port number secure
allow_ssh Boolean true true | false True — Allow SSH access
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_ Boolean false true | false True — Respond to ICMP pings ping
enable_ Boolean true true | false True — Enable IPv4 firewall firewall
enable_ Boolean true true | false True — Enable IPv6 firewall firewall6
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 Security Analytics Reference Guide Security Analytics 8.1
Description
Edit the root password
GUI Location
Initial Configuration
Output
ApiResultCode
Parameters
REQ Format Default Valid Inputs Description
password X string —
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 —
server_cert_key X filepath —
364 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
client_verification Boolean false true | false n True — Verify client certificate
n False — No verification; any parameters that follow will be ignored
client_verification_ad Boolean false true | false n True — Require client certificate for Login Correlation Service
n False — Certificate not required for LCS
use_server_cert Boolean true true | false 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
client_ca filepath —
client_crl_url string —
365 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
client_cert_name filepath —
client_cert_key filepath —
enable_revocation_check Boolean true true | false True — Check for revocation of the Intelligence Services certificates
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 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/
Description
Get statistics for a specified Ethernet interface
GUI Location
Menu > Statistics > Network System > [interface name]
Output array
Parameters
REQ Format Default Valid Inputs Description
interface 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
REQ Format Default Valid Inputs Description
id X integer/null null null |
name X string —
n Edit entry — New name
format integer 1 1 | 2 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 Default Valid Inputs Description
id X integer —
fields X array —
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 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 Default Valid Inputs Description
id X integer —
field X string —
requestParams X array —
type string ranked ranked Only ranked is valid
direction string d a | d Sort order
n a — Ascending
n d — Descending
column string item item | sessions | bytes | Sort-by field packets | fragments | bad_csums n item — Report attribute
n fragments — IP fragments
n bad_csums — Bad checksums
view array table table | pie | column | Display mode bar
Python Example s.callAPI("POST","/deepsee/edit_reportlet", { 'id': 3, 'field': 'tcp_initiator', 'requestParams': { 'type' => 'ranked', 'direction' => 'd', 'column' => 'sessions',
374 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 Default Valid Inputs Description
id X integer —
fields X array —
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 Default Valid Inputs Description
id X integer —
order X array —
Python Example s.callAPI("POST","/deepsee/edit_reportlet_order", { 'id': 8, 'order': [ '
376 Security Analytics Reference Guide Security Analytics 8.1
array( 'id' => 8, 'order' => array( '
Delete a Summary page view
API Path /deepsee/delete_view/
Description
Delete a Summary page view
GUI Location
Menu > Analyze > Summary > [View Selector] > [Delete View]
Output
ApiResultCode
Parameters
REQ Format Default Valid Inputs Description
viewId X integer —
Python Example s.callAPI("POST","/deepsee/delete_view/
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_
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': '
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
REQ Format Default Valid Inputs Description
serverId X integer —
filter Boolean true true | false n True — Retrieve only applicable upgrades
n False — Retrieve all upgrades
Example callAPI('GET','/upgrades/manifest', array( 'serverId' => 2, 'filter' => 'true' ) );
Get download status
API Path /upgrades/download_status
381 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 —
fileName X text —
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 Description
type X integer — 1 Reserved. Always use 1
protocol X integer — 0 | 1 0 — HTTP 1 — HTTPS
host X string — hostname |
382 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
path X string — /
file_name X string — Manifest.xml Must be this filename
username X string —
password X string —
id integer —
n Edit entry — ID required
validate_ Boolean true true | false Valid only if protocol=1; validate the certificate 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/
Description
Remove an upgrade server
GUI Location
Menu > Settings > Upgrade > Delete
Output
ApiResultCode
Parameters
REQ Format Default Valid Inputs Description
id X integer —
Example callAPI('POST','/upgrades/delete/2');
383 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 Description
serverId X integer —
upgradeFile X string — atpsa-
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 Security Analytics Reference Guide Security Analytics 8.1
Parameters
REQ Format Default Valid Inputs Description
filename X string — atpsa-
Example callAPI('POST','/upgrades/initiate', array( 'filename' => 'atpsa-8.1.1-45000-x86_64-DVD.tar' ) );
385 Security Analytics Reference Guide Security Analytics 8.1
User Account APIs
These APIs correspond to the functions on the [Account_Name] > Account Settings and[Account_Name] > Preferences dialogs and the Users and Groups Settings page.
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 Description
page integer 1 1–
limit integer 25 1–100 Number of items per page
sort string name name | email | id Sort-by field
desc string asc asc | desc Sort direction
userId Boolean, false false |
n False — Return all users
getAuth Boolean false false | true n False — Only get failed authorization attempts
n True — Get all authorization settings, including lockout interval, failure limit, last attempt
getGroups Boolean false true | false Get group membership
filter string —
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/
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 Description
setting X string — unit_network | pagination_ Settings on the Account Preferences limit | language | totp | dialog mime_type_view | api_time_ prefix | api_time_postfix | n totp — Time-based one-time dark 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 Format Default Valid Inputs Description
remote 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–
limit mixed 25 1–100 Number of items per page
sort string groupname groupname | id | Sort-by field description | default | remote
desc string asc asc | desc Sort direction
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 —
Example callAPI('GET','/settings/groups', array( 'page' => '2', 'limit' => '20', 'sort' => 'groupname', 'desc' => 'desc', 'getPermissions' => true, 'getUsers' => true, 'remote' => true, 'filter' => 'audit'
389 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 Format Default Valid Inputs Description
search string —
390 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/
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 Description
id X integer —
passwordAging X integer 0 0 | 7 | 14 | 30 | 60 | 90 | Number of days before the user 120 | 365 must change the password
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 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 Description
name X string —
email string —
Example callAPI('POST','/users/account_info array( 'name' => 'LDAP_admin', 'email' => '[email protected]' ) );
Edit a current-user preference — MODIFIED
API Path /users/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 Description
setting X string —
value X array — Value for setting; array contains one value only, from the parameters below
unit_ string b | B | p Unit of measurement to display in network results tables. b — Bits B — Bytes p — Packets
pagination_ integer 5 | 10 | 15 | 20 | 25 | 50 | 75 | Number of entries per page limit 100
language string eng | fra | jpn | kor Language for the web UI
totp string
n ' ' (space) — Disable 2FA
n
dark Boolean true | false True — Display the web UI in dark mode (new)
mime_type_ string magic | mime | derived Specify how the file type is view displayed in the Type column on the Extractions page.
api_time_ integer 0–
api_time_ integer 0–
Example callAPI('POST','/users/setting/unit_network', array( 'value' => 'p'
393 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 Description
oldPw X string —
newPw X string —
confirmPw X string —
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 Security Analytics Reference Guide Security Analytics 8.1
Output integer
Parameters
REQ Format Default Valid Inputs Description
name X string —
description string —
default Boolean false true | false True — Make default group
deepsee array —
permissions array —
users array —
externalGroups array —
remote Boolean false true | false CMC only. Valid only if remote=true ; array of remote group name
cmcCheck string —
Example callAPI('POST','/settings/create_group', array( 'name' => 'LDAP_auditors', 'description' => 'Auditors in LDAP groups', 'default' => 'false',
395 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 Description
username X string —
password X string —
name string —
email email —
396 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
groups array —
n user
n admin
n auditor
n security_admin
n < user-defined group>
remote Boolean false true | false CMC only True — Groups are remote groups
remoteGroups array —
n user
n admin
n auditor
n security_admin
n
Example callAPI('POST','/settings/create_user', array( 'username' => 'ursula_user', 'password' => 'changeMEnow12#$', 'name' => 'Ursula User', 'email' => '[email protected]', '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 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/
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 Description
ids X integer —
remote Boolean false true | false 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/
398 Security Analytics Reference Guide Security Analytics 8.1
Delete users
API Path /settings/delete_user/
Description
Delete one or more users
GUI Location
Menu > Settings > Users and Groups > Users > [delete users]
Output
ApiResultCode
Parameters
REQ Format Default Valid Inputs Description
ids X integer —
Example callAPI('POST','/settings/delete_user/
Disable a user account
API Path /settings/disable_user/
Description
Disable a user account
GUI Location
n Menu > Settings > Users and Groups > Users > [edit user]
n [Unsuccessful login attempts exceeded]
Output
ApiResultCode
399 Security Analytics Reference Guide Security Analytics 8.1
Parameters
REQ Format Default Valid Inputs Description
id X integer —
disable Boolean true true | false True — Disable
Example callAPI('POST','/settings/disable_user/
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/
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 Description
id X integer —
name X string —
description string null
default Boolean false true | false True — Set as default group
deepsee array null
400 Security Analytics Reference Guide Security Analytics 8.1
REQ Format Default Valid Inputs Description
permissions array null < New permissions GET: /settings/permission_ tree>
users array null
remote Boolean false true | false CMC only True — Groups are remote groups
externalGroups array null
cmcCheck string null
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/
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 Description
id X integer null
username string null
password string null
name string null
email email null
groups array null
remote Boolean false true | false CMC only True — Groups are remote groups
remoteGroups array null
Example callAPI('POST','/settings/edit_user/337', array( 'username' => 'newusername337', 'password' => 'newpassword337', 'name' => 'newdisplayname337', 'email' => '[email protected]', '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 Valid Inputs Description
username X string null
name string null
email email null
groups array null < Array of new group names GET: /settings/groups>
remote Boolean false true | false CMC only True — Groups are remote groups
remoteGroups array null
Example callAPI('POST','/settings/edit_user_by_username', array( 'username' => 'ursula_user', 'name' => 'ursula_user_00', 'email' => '[email protected]', 'groups' => 'user', 'remoteGroups' => 'user' ) );
Change user password
API Path /settings/edit_user_password/
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 Description
id X integer —
password X string —
Example callAPI('POST','/settings/edit_user_password/337', array( 'password' => '3030rootMEouT#$#' ) );
404 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': ['
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": { ["
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 Description
timeout X integer — 5 | 10 | 30 | 60 | 120 | 240 | 480 | 1440 | Timeout in minutes 4320 | 7200 | 10080
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 Format Default Valid Inputs Description
externalPreview X 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
REQ Format Default Valid Inputs Description
usageTracking 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 Description
motd X string —
Example callAPI('POST','/web_interface/motd' array( 'motd' => 'Hello world' ) );
411 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
allow X Boolean — true | false True — Allow Universal Connector
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
REQ Format Default Valid Inputs Description
referers X array —
412 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
< array Timespan plus the JSON equivalent of a Primary Filter; enhanced primary filter supports operators. This identity path permits you to > select the report to run on the Reports Page.
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 Valid Values / Description
timespan X — Array consisting of 'start' and 'end' with the dates specified as
type ranked Type of report; ranked — Reports page; geoip — Geolocation page
query — 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'
field X application_id Report selector for the Reports page; values are the primary filter attribute names for reports. Omit this field for an extraction.
sample 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 Click to see values > Reports
Analyze > Report Click to see values Status
Audit Log Click to see values
Extractions Click to see values; initiator_X and responder_X produce the same results
Geolocation 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' => '
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 | single-value array Specify the day of the week Fri | Sat | Sun
monthly [01–31] | [1st | 2nd | single-value array Specify one of the following: 3rd | 4th | last]- n numerical day of month: 06 for [weekday | weekend_day | the 6th Mon | Tue | Wed | Thu | n ordinal plus day: 2nd-Tue, 3rd- Fri | Sat | Sun] weekday, last-Sun
hour 00–23 single-value array Numerical hour
minute 00–59 single-value array Numerical minute
once
custom array(
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 Microsoft Active Directory
madrfc2307 Microsoft Active Directory (RFC 2307)
msu20 Microsoft Services for Unix 2.0
msu35 Microsoft Services for Unix 3.5
rfc2307 RFC 2307 Network Information Service
rfc2307bis RFC 2307bis Network Information Service
user_defined 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 REQ Format Default Valid Inputs UI Label
user_object_ string — User Object class Class
420 Security Analytics Reference Guide Security Analytics 8.1
Attribute REQ Format Default Valid Inputs UI Label
login_name string — Login Name Attribute
gecos string — Full Name (GECOS) Attribute
user_password string — User Password Attribute
pam_password_ string — Password ad ADSI change Change Method clear Cleartext
clear_ Cleartext, remove old pw remove_old first
crypt Crypt
exop RFC 3062
exop_send_ RFC 3062 (send old and old new pw)
md5 MD5
® nds Novell NDS
racf 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_ string — Group class Object Class
gid_number X integer — Group ID Number Attribute
pam_member string — Group Membership Attribute
421 Security Analytics Reference Guide Security Analytics 8.1
Attribute REQ Format Default Valid Inputs UI Label
rfc_mode string — Group rfc2307 UID Membership Type rfc2307bis Distinguished Name
Menu > Analyze > Alerts > Summary
Specify alert groups as follows: appliance importance score cached integration_provider source_ip description match_criteria source_mac destination_ip name source_port destination_mac indicator type destination_port rule endpoint_providers result Menu > 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 aggregate All capture interfaces, aggregated
nt DPI threads ethX Ethernet interface
® s_spsd Slot overflow ifbX Accolade interface
tmf Cumulative flow maximum uxqueued File analysis jobs in progress
qfc Flows in progress uxprocd Processed file analysis
qsd Slots in use uxmaxqueue File analysis queue discards
qp Packets in progress uxmaxslrg File analysis range discards
422 Security Analytics Reference Guide Security Analytics 8.1
qnf Flows initiated uxnotlive File analysis slot discards
uxprobes File analysis requests
423 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 [email protected] 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