Security Analytics 8.1.x
Reference Guide
Updated: Friday, November 15, 2019
Security Analytics Reference Guide
Security Analytics 8.1
Copyrights, Trademarks, and Intellectual Property
Copyright © 2019 Symantec Corp. All rights reserved. Symantec, the Symantec Logo, the Checkmark Logo, Blue Coat, and the Blue
Coat logo are trademarks or registered trademarks of Symantec Corp. or its affiliates in the U.S. and other countries. Other names
may be trademarks of their respective owners. This document is provided for informational purposes only and is not intended as
advertising. All warranties relating to the information in this document, either express or implied, are disclaimed to the maximum
extent allowed by law. The information in this document is subject to change without notice.
THE DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES,
INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE
DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. SYMANTEC CORPORATION
SHALL NOT BE LIABLE FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES IN CONNECTION WITH THE FURNISHING, PERFORMANCE,
OR USE OF THIS DOCUMENTATION. THE INFORMATION CONTAINED IN THIS DOCUMENTATION IS SUBJECT TO CHANGE WITHOUT
NOTICE. SYMANTEC CORPORATION PRODUCTS, TECHNICAL SERVICES, AND ANY OTHER TECHNICAL DATA REFERENCED IN THIS
DOCUMENT ARE SUBJECT TO U.S. EXPORT CONTROL AND SANCTIONS LAWS, REGULATIONS AND REQUIREMENTS, AND MAY BE
SUBJECT TO EXPORT OR IMPORT REGULATIONS IN OTHER COUNTRIES. YOU AGREE TO COMPLY STRICTLY WITH THESE LAWS,
REGULATIONS AND REQUIREMENTS, AND ACKNOWLEDGE THAT YOU HAVE THE RESPONSIBILITY TO OBTAIN ANY LICENSES, PERMITS
OR OTHER APPROVALS THAT MAY BE REQUIRED IN ORDER TO EXPORT, RE-EXPORT, TRANSFER IN COUNTRY OR IMPORT AFTER
DELIVERY TO YOU.
3
Security Analytics Reference Guide
Security Analytics 8.1
Table of Contents
Recognized Applications
9
Application Groups
9
Backup and Restore
11
Backup
11
Specify the Storage Location
Manual Backup
Encrypted Backup
Scheduled Backup
12
12
12
13
Restore
13
BPF Syntax
15
GRE Encapsulation and BPF Filters
15
Syslog Facilities
17
Standard Syslog Facilities
17
Standard Syslog Levels and Priorities
18
Disable SSH Root Logins
19
MD5-Encrypted Password for Bootloader
20
Command-Line Interface
21
CLI Commands
21
Supported Linux Commands
24
csr.sh
26
dscapture
26
dscapture clearpersist
dscapture cleartime
dscapture init
dscapture map
dscapture mapshow
dscapture settime
dscapture shutdown
dscapture start
dscapture status
dscapture stop
dscapture unmap
26
27
27
27
27
28
28
28
29
29
29
dsfilter
29
dsfirewall, dsfirewall6
30
4
Security Analytics Reference Guide
Security Analytics 8.1
dslc
32
dslc add
32
dslc del
34
dslc disable
34
dslc enable
35
dslc export
36
dslc factory
37
dslc import
37
dslc set
37
dslc show
39
dslogdump
39
dsmigrate.sh
40
Setup
41
Migrate the Data
42
dsmigratedata
44
Setup
44
Interface Configuration
45
Data-Migration Procedure
45
Operation of dsmigratedata
47
Restarting dsmigratedata
48
Stateful Restart
Stateless Restart
48
48
dspcapimport
48
dsportmapping
49
dsregen
50
dszap
51
Actions Performed
53
Running dszap
53
dump_slot
55
dump_slot_chain
55
dump_slot_header slot_<number>
55
dump_slot_elements <filename>
55
dump_slot_pcap <packet_number>
56
dump_slot_trail
56
dump_space_table_entry <slot_id>
56
walk_space_table_journal
57
5
Security Analytics Reference Guide
Security Analytics 8.1
dynfilter
57
lsi-rate-tool
58
lsi-show
60
MegaCli | megacli
61
scm pivot_only_provider
62
Add a Pivot-Only Provider
62
Pivot-Only Provider Demonstration
63
Delete a Pivot-Only Provider
66
Sample Pivot-Only Providers
66
scm sessions
68
scm solera_acl elevate
69
scm tally
69
Web Services APIs
71
Install and Test the SoleraConnector Class
71
Session-Based APIs
73
Pivot to Summary Page
73
Single Time-Value Configuration
74
API Changes in Security Analytics 8.1.x
75
New APIs
Modified APIs
75
75
Advanced API Queries
77
Example Queries
Combining Different Namespaces
77
77
Alerts APIs
79
Anomalies APIs
91
Authentication APIs
100
BPF Filters APIs
111
Capture APIs
116
Central Manager APIs
137
Data Enrichment APIs
158
Date/Time APIs
178
6
Security Analytics Reference Guide
Security Analytics 8.1
Drive-Space Management APIs
182
Extractor APIs
186
Geolocation APIs
219
Indicators APIs
226
License APIs
236
Logging and Communication APIs
240
Metadata APIs
265
Network APIs
268
Packet Analyzer APIs
274
PCAP APIs
277
Playback APIs
300
Report and Report Status APIs
302
Rules APIs
338
Security APIs
347
Statistics APIs
367
Summary Page APIs
369
System APIs
378
Upgrades APIs
380
User Account APIs
386
Web Interface Settings APIs
405
API Appendix
414
Using Polling with the APIs
415
Syntax: Identity Path
415
7
Security Analytics Reference Guide
Security Analytics 8.1
Syntax: Enhanced Primary Filter Array
Syntax: Advanced-Filter Array
Syntax: Primary Filter Array
Syntax: Timespan Array
Syntax: Timespan Date Array
Syntax: Geolocation Internal Labels
Syntax: Scheduled Events
LDAP Schema Values
Menu > Analyze > Alerts > Summary
Menu > Analyze > Anomalies > Summary
Capture Summaries Inputs
415
416
418
419
419
419
419
420
422
422
422
Using the APIs
424
Best Practices
424
Downloading Extracted Artifacts
424
Downloading PCAPs
428
Resources
432
8
Security Analytics Reference Guide
Security Analytics 8.1
Recognized Applications
59 New Recognized Applications in Security Analytics 8.1.1. Total: ~2900
To obtain an XLSX or CSV list of recognized applications, select Reference > Recognized Applications in the
Help Files, which are located:
n
In the web interface under About
> Help > [language].
n
On https://support.symantec.com/content/unifiedweb/en_US/Documentation.1145515.html.
Select the appropriate version, and then under Administration Guide open the Security Analytics 8.1.1
WebGuide.
The applications in the files can be identified by Security Analytics. The values in these tables appear in the
Application, Application Group and Application Group over Time reports and report widgets and are valid for
application_group=<application_group> and application_id=<application_id> in the primary filter bar, for
example, application_group="Network Service" or application_id=twitter
Application Groups
Following are sample applications that are included in each application group. Where the last item is preceded by
the word "and," all applications for that group are listed:
n
Antivirus — zonealarm, zonealarm_update, sophos_update, and lookout_ms
n
Application Service — citrix_pvs, ldap, syslog, perforce, windows_marketplace, xfs
n
Audio/Video — apple_music, baidu_player, google_play_music, gotomeeting, h245, hulu, iheartradio,
itunes, netflix, pplive, qqlive, rtsp, spotify
n
Authentication — chap, diameter, krb5, pap, radius, tacacs_plus
n
Behavioral — high_entropy and spid
n
Compression — ccp and comp
n
Database — db2, drda, mysql, postgres, sybase, tds, tns
n
Encrypted — i2p, ipsec, isakmp, ocsp, ssh, ssl, tor, and tor2web
n
ERP — sap
n
File Server — afp, ftp, gmail_drive, netbios, nfs, smb, tftp
n
File Transfer — aim_transfer, bits, filesharepro, imessage_file_download, irc_transfer, irods, jabber_
transfer, mypocket, paltalk_transfer, and ymsg_transfer
n
Forum — google_groups, ircs, kaskus, linkedin, live_groups, mibbet, nntp, nntps, odnoklassniki, r10,
tapatalk, vkontakte, and yahoo_groups
9
Security Analytics Reference Guide
Security Analytics 8.1
n
Game — all_slots_casino, angry_birds, candy_crush_saga, cstrike, eve_online, poker_stars, qq_r2, quake,
runescape, wow
n
Instant Messaging — aim, badoo, facebook_messenger, gmail_chat, gtalk, irc, jabber, qq, whatsapp,
ymsg
n
Mail — imap, imaps, lotusnotes, mapi, pop3, pop3s, smtp, and smtps
n
Microsoft Office — groove
n
Middleware — amqp, dcerpc, diop, giop, iiop, java_rmi, rpc, soap, thrift
n
Network Management — cdp, cip, enip, lcp, modbus, netflow, rsvp, sccm, snmp, wccp
n
Network Service — 8021q, arp, crudp, dccp, dhcp, dnp3, dns, eth, fibre_channel, hopopt, icmp, ip, ip6,
isis, mux, nbns, ntp, sctp, svn, udp, whois
n
Peer to Peer — bitcoin, bittorrent, directconnect, edonkey, filetopia, gnutella, kazaa, qqmusic, thunder
n
Printer — apple_airprint, bjnp, cups, ipp, jetdirect, and lpr
n
Routing — bgp, eigrp, mpls, ospf, rip1, rip2, stp
n
Security Service — fsecure, ghostsurf, mcafee, and peerguardian
n
Standard — established, incomplete, malformed, and unknown
n
Telephony — bssap and isup
n
Terminal — rlogin, rsh, telnet, telnets, and tnvip
n
Thin Client — anydesk, gotomypc, ica, jedi, pcanywhere, radmin, rdp, vmware, x11
n
Tunneling — etherip, gre, http_tunnel, l2tp, ppp, pppoe, socks5, teredo
n
WAP — bxml, mmse, smpp, ucp, wsp, wtls, and wtp
n
Web — 4chan, abcnews, alibaba, amazon_aws, baidu, bbc, disney_channel, ebay, elpais, facebook, flickr,
google, http, https, kaspersky, nytimes, outlook, pandora, reddit, sharepoint, travelocity, tumblr, twitter,
wikipedia, windows_update, yahoo, youtube
n
Webmail — gmail, live_hotmail, mailru, orangemail, owa, yandex_webmail, ymail2, zimbra
10
Security Analytics Reference Guide
Security Analytics 8.1
Backup and Restore
The backup and restore scripts save system data but not the data on the capture and index drives. To migrate
capture data, use dsmigratedata (version 7.x) or dsmigrate.sh (version 8.x).
The types of data saved in the backup archive include but are not limited to the following:
n
Network configuration
n
Filters
n
Disk configuration files
n
Geolocation data
n
Authentication configuration data
n
Playback sessions
n
Local user accounts
n
Some crontab-related configuration
n
SSH configuration
n
GUI-related configuration
n
Web server configuration and SSL certificates
n
n
List of active extractor-plugins licensing
Database tables (system and userdefined)
n
System time settings
Backup
n
Symantec recommends that you store the backup archives off-appliance —
on a network share or a USB drive — so that you do not lose the archives in
the event of a local hard-drive failure.
n
You must back up and restore to the same software version, including the 5digit build version. Do not back up the settings, then upgrade the appliance,
and then attempt to restore the settings.
n
The appliance on which you are restoring the settings must be licensed
before running solera-restore.sh.
n
When restoration is completed all of the user passwords are reset to
SymantecPassword123?
Security Best Practice
Use the backup-passwd script to password-protect and encrypt the backup file.
11
Security Analytics Reference Guide
Security Analytics 8.1
Specify the Storage Location
If no storage location is specified, the backup archive will be written to the /tmp directory on the appliance's
system drive, where it is vulnerable to loss in the event of a system failure.
1. Modify the backup configuration file:
vi /etc/solera/config/backup.conf
2. Specify the backup directory on the external storage device:
# output directory to store backup archives
OUTPUT_DIR=<bdir>
where <bdir> is the backup directory.
3. Save backup.conf and exit.
The archived files are written to the directory specified in backup.conf or to /tmp if no location is specified. The
backup archive is named solera-backup-<appliance_name>-<YYYYMMDD>T<hhmm>Z.tgz, where <appliance_
name> is the appliance hostname.
syntax
/etc/utils/solera-backup.sh -[d|u] [-h]
parameters
You must specify either -d or -u.
-h
Help — Show this message
-d
Default — Exclude users and groups from the backup
-u
Include users and groups — user passwords will be reset
Manual Backup
1. Log in as root.
2. Run the backup script:
/etc/utils/solera-backup.sh -[d|u]
Encrypted Backup
To encrypt the backup file, follow these steps:
1. Log in as root.
2. Run the backup-password script.
/etc/utils/solera-backup-passwd.sh -[d|u]
12
Security Analytics Reference Guide
Security Analytics 8.1
3. Provide a password when prompted. The script transforms the plaintext into a base64-encoded and
encrypted password, stored in /etc/solera/.backup_passwd.
To disable encryption, run the backup-password script again but leave the
password blank when prompted. The .backup_passwd file will be deleted.
4. When you run the backup script — manually or scheduled — it appends ENC to the file name: solerabackup-<hostname>-<timestamp>.tgz.enc
Scheduled Backup
To schedule regular backups, do one of the following:
n
Put a symlink in one of the pre-scheduled cron directories, for example:
ln -s /etc/utils/solera-backup.sh /etc/cron.daily/backup
n
Put the cron job in root's crontab, for example:
crontab -e
# back up every four hours at 15 min past the hour
15 */4 * * * /etc/utils/solera-backup.sh
# back up once per month on the 2nd at 3:30am
30 3 2 * * /etc/utils/solera-backup.sh
Restore
To restore backed-up settings to an appliance, verify that the appliance has access to the backup file. If
necessary, copy the backup archive to the /tmp directory.
If you are restoring the data to a different appliance, you will need to manually
adjust all of the settings that are appliance-specific. For example, the license is
based on the appliance's MAC address. For further assistance, contact Symantec
Support.
1. Run the restore script. If the backup archive was encrypted, you must provide the password when
prompted.
Unencrypted:
/etc/utils/solera-restore.sh solera-backup-<hostname>-<timestamp>.tgz
Encrypted:
/etc/utils/solera-restore.sh solera-backup-<hostname>-<timestamp>.tgz.enc
2. When prompted, reboot the appliance to initiate the restore process.
13
Security Analytics Reference Guide
Security Analytics 8.1
The archive file is copied to the /boot partition. After the reboot, the firstboot process copies the files in the
archive to the file system, applies the changes to the database, and reboots one more time to activate all of the
system changes. The appliance is then restored to the same point as when the backup file was generated, except
for the capture and index data.
To cancel a restore, run /etc/utils/solera-restore.sh cancel. To restart the restore,
run /etc/utils/solera-restore.sh.
14
Security Analytics Reference Guide
Security Analytics 8.1
BPF Syntax
On Symantec Security Analytics you can create complex, explicit filters using BPF expressions to specify what to
include—or what to exclude, using NOT. BPF expressions are used in capture filters, PCAP downloads, and
playback.
BPF uses the following operators:
n
Negation (!, not)
n
Concatenation (&&, and)
n
Alternation (||, or)
Negation has the highest precedence. Alternation and concatenation have equal precedence and associate left
to right. If an identifier is given without a keyword, the most recent keyword is assumed. For example: not port
80 and 443 is short for (not port 80) and (port 443), which should not be confused with not (port 80 and 443).
Filters containing net and mask are not valid for IPv6 addresses.
For additional information on using BPF, including all available parameters and syntax, see
biot.com/capstats/bpf.html.
BPF Syntax
Description
(!port 514)
(not port 514)
Excludes all syslog traffic
(!portrange 8865-8870)
Excludes all traffic on ports 8865 through 8870
(host 192.0.2.56)
Includes traffic to and from 192.0.2.56
(dst host 203.0.113.3)
Includes traffic destined for 203.0.113.3
!(port 443 or port 123 or port
53)
Excludes traffic on ports 443, 123, and 53
!(net 203.0.113.0 mask
255.255.255.0)
!(net 203.0.113)
!(net 203.0.113.0/24)
Excludes traffic on network 203.0.113.0 with a 24-bit mask. You can specify a
dotted triple, dotted pair, or a single number, and the mask will be
automatically assumed as 255.255.255.0 for a dotted triple, 255.255.0.0 for
a dotted pair, and 255.0.0.0 for a single.
(src net 198.51.100.0/24)
Includes traffic originating from the network 198.51.100.0 network
(port 80 or port 3389)
(port 80 or 3389)
Includes all traffic on ports 80 and 3389 only
(vlan && host 192.0.2.35)
(vlan and host 192.0.2.35)
Includes all 802.11Q-tagged traffic to and from 192.0.2.35
GRE Encapsulation and BPF Filters
When specifying a capture filter for GRE-encapsulated WCCP, you can filter on the original IP addresses by using
packet offsets in the filter. The syntax for the offset is as follows:
15
Security Analytics Reference Guide
Security Analytics 8.1
ip[<byte 1 of IP>:<byte length of IP>] = <base10 of IP hex string>
In a GRE-encapsulated packet header, the source IPv4 address inside the encapsulation begins on the 40th byte
from the beginning, and an IPv4 address consists of 4 bytes. Therefore, the source address is specified thus:
ip[40:4] = <base10 of IP hex string>
If the original source IP is 198.51.100.10, the IP in hexadecimal is 0xC633640A and in base10 is 3325253714.
Therefore, the source IP is specified as follows:
ip[40:4] = 3325253714
The destination IP immediately follows the source IP, so if the destination IP is 203.0.113.44, specify it as follows:
ip[44:4] = 3405803820
examples
Include all GRE-encapsulated traffic from 192.0.2.10
(ip[40:4] = 3232248330)
Exclude all GRE-encapsulated traffic that is destined for 203.0.113.44
!(ip[44:4] = 3221225994)
16
Security Analytics Reference Guide
Security Analytics 8.1
Syslog Facilities
System logs are the product of a communications protocol (RFC 5424) for transmitting event messages and
alerts across an IP network. For more information, see www.syslog.org and tools.ietf.org/html/rfc5424.
Standard Syslog Facilities
Facility is defined by the syslog protocol, and provides a rough clue of where in a system the message
originated.
Level
Facility
Function
0
kern
Kernel process messages
1
user
Regular user process messages
2
mail
Mail system process messages
3
daemon
4
auth
5
syslog
6
lpr
Line printer system process messages
7
news
News subsystem process messages
8
uucp
UUCP subsystem process messages
9
cron
Cron (clock/timing) subsystem process messages
10
authpriv
11
ftp
File Transfer Protocol system process messages
12
ntp
Network Time Protocol system process messages
13
log
Audit alternate ID for authorization process messages
14
log
Alert alternate ID for authorization process messages
15
clock
16–22
local use
0 through 7
Other system daemons process messages
Authorization system or programs that ask for user names and passwords ( login, su,
getty, ftpd) process messages
System log process messages
A separate flag for routing authorization messages to a log file that has more restricted
permissions than those of auth.
Daemon alternate ID for cron (clock/timing) subsystem process messages
Reserved for site-specific messages
17
Security Analytics Reference Guide
Security Analytics 8.1
Standard Syslog Levels and Priorities
Syslog message levels are associated with the urgency or criticality of the event that triggered the message.
Level
Name
Meaning
0
Emergency
System is unusable. A "panic" condition, such as an imminent system crash, usually broadcast
to all users.
1
Alert
Action must be taken immediately. Notify staff who can fix the problem — example is a
corrupted system database.
2
Critical
Critical conditions, usually hardware errors. Indicates a failure in a primary system that should
be corrected immediately. CRITICAL problems should be fixed before ALERT issues.
3
Error
Error conditions. Non-urgent failures — these should be relayed to developers or
administrators; each item must be resolved within a given time.
4
Warning
Warning conditions. Warning messages are not errors but indications that an error will occur
if action is not taken, e.g. file system 85% full. Each item must be resolved within a given time.
5
Notice
Normal but significant condition. Events that are unusual but not error conditions — might be
summarized in an email to developers or admins to spot potential problems. No immediate
action required.
6
Informational Informational messages. Normal operational messages — may be harvested for reporting,
measuring throughput, etc. No action required.
7
Debug
Debug-level messages. Info useful to developers for debugging the application; not useful
during operations.
8
None
Do not send messages from the indicated facility to the selected file. For example, specifying
*.debug;mail.none sends all messages except mail messages to the selected file.
18
Security Analytics Reference Guide
Security Analytics 8.1
Disable SSH Root Logins
Security Best Practice
n
Disable root access via SSH.
n
If you disable SSH root logins, be sure to review log files for root logins and
activity.
This procedure disables root access over SSH connections but preserves root access via console.
1. Edit the sshd_config file:
[root@hostname ~]# vi /etc/ssh/sshd_config
2. Uncomment the line #PermitRootLogin yes and set the value to no:
PermitRootLogin no
3. Save and exit sshd_config.
4. Restart the SSH daemon to apply the changes:
[root@hostname ~]# systemctl restart sshd
To disable the root account entirely, append /settings/initial_config to the appliance's IP address or
hostname in the address bar of the browser. Under Root Password, select Lock Root Account.
Warning: You cannot re-enable the root account unless you have console
access to the appliance, and then you will have to contact Symantec Support
for assistance.
19
Security Analytics Reference Guide
Security Analytics 8.1
MD5-Encrypted Password for Bootloader
This page applies only to Dell-based hardware and virtual machines.
Security Best Practice
Password-protect the bootloader.
1. Use the grub2-setpassword utility:
[root@hostname ~]# grub2-setpassword
Enter password: <grub_password>
Confirm password: <grub_password>
Follow best key-maintenance practices by manually recording this password
and keeping a copy in a secure location that is separate from the appliance.
2. When attempting to edit the grub menu the credentials are root and the grub password. Do not use the
root system password here.
Enter Username:
root
Enter Password:
<grub_password>
20
Security Analytics Reference Guide
Security Analytics 8.1
Command-Line Interface
The CLI is accessed via an SSH connection to bond0. Root access to the CLI is granted to whomever knows the
root-level password, which is established on the Initial Configuration page while setting up Symantec Security
Analytics for the first time. Use passwd to change the root password.
CLI Commands
There are three levels of CLI access to grant via RBAC:
n
Base—Read-only commands such as ls, pwd, less
n
Tier 1—Networking and File System Management
n
Tier 2—File System and Admin Utilities, Process and Drive Management
See Group Permissions in the Security Analytics 8.1.x Administration and Central Manager Guide on
support.symantec.com for details.
The following commands apply specifically to Security Analytics. Click on linked text to see the syntax.
With admin permissions, some commands permit sudo access (X in the sudo column).
Commands that are shaded in yellow are new in Security Analytics 8.1.1. Commands that are shaded in gray
have been deprecated in 8.1.x.
Command Use
sudo
build-ds-capture Constructs capture file system (partition, format, filesystem, fstab,
mount, etc.). Ruby script. Uses a config file.
build-ds-extras Constructs database/home-apache for JBOD systems (format,
filesystem, fstab, mount, etc.). Ruby script.
build-ds-index Constructs index file system (partition, format, filesystem, fstab, mount,
etc.). Ruby script. Uses a config file.
X
X
X
cfg_bond_interface.py A script to set the IP address of bond0. See 8.1.x Setup for instructions.
check-services Displays the status of known and expected services
check_slot_files Replaces dsfsck. Checks the DPDK file system and does limited repairs.
Use when directed by Symantec Support.
csr.sh Collects and concatenates log/config/status files into a single output
tarball (Customer Service Report). Used for troubleshooting an
appliance. BASH script.
21
X
Security Analytics Reference Guide
Security Analytics 8.1
Command Use
sudo
dmidecode Intel-based hardware only. Runs -s <chassis-serial-number> to see
the appliance serial number or asset tag. For SA-S500 series appliances,
run /opt/bluecoat/clp/bin/serial_number to see the appliance serial
number. For all hardware, select Settings > About on the web UI in
version 7.3.2 and later.
dscapture Instructs the appliance to capture network data
dsfilter Displays filters assigned to a specified interface
dsfirewall Toggles the IPv4 firewall on and off
X
dsfirewall6 Toggles the IPv6 firewall on and off
X
dslc Configures the logging mechanisms (syslog, SNMP, email).
X
dslicenseinfo Displays the license key and the features that are enabled on this
appliance.
dslogdump Displays the events captured by the system log.
dsmigrate Migrates PCAPs from a 7.x or 8.x appliance to an 8.x appliance.
dsmigratedata Migrates capture data from one appliance to another. Not for migration
to 8.x.
dspcapimport Imports PCAP files
X
dsportmapping Customizes your port-to-application mapping
dsregen Retransmits captured network traffic from a virtual network interface to
a physical network interface ("playback" on the web UI).
dsrinfo Lightweight utility for capture file system config data (number of slots,
recycle head location, etc.).
X
dsseed Generates the seed file used for the license.
dsview-text Text-based specialization of dsview.
dsvmswitch Switches VM capture configuration: 2 sizes (1 large, 1 small). For the
Security Analytics virtual appliance only.
dszap Deletes ALL captured data (including indexes and reports) and
reinitializes the data storage. Destroys all existing capture and index
data.
X
dump_slot Displays various data points concerning slots.
dynfilter Displays and manages the dynamic filters created by autonotchd
expand-ds-storage Adds new disk storage subsystems without reinstalling Security
Analytics.
fix-iosched Script. Sets I/O scheduler options. Called in first boot.
getpmap.sh Used by csr.sh. BASH script.
gindiag.sh
Gathers relevant information to assist in troubleshooting a GIN
connection.
22
X
Security Analytics Reference Guide
Security Analytics 8.1
Command Use
sudo
ipmitool Runs ipmitool sensor for a highly detailed list of power levels, fan
speeds, temperatures, and so on. For a simplified version run ipmitool
sdr
lhr_flat_to_qdb Uploads flat-file lists of MD5, SHA1, or SHA256 hashes to the Custom
Hash List
lru_calc.sh Determines the size of the slot cache. BASH script.
lsi-classify Wrapper around the LSI RAID controller classification scheme. Ruby
script.
lsi-make-good Helper utility to set physical disk state back to "good" in an LSI JBOD.
BASH script.
lsi-rate-tool Sets, resets, or shows rates as a percentage of CPU load for RAID
manipulations such as background initialization, foreground initialization,
consistency check, reconstructions, etc. BASH script.
lsi-show Shows LSI RAID controller data in a condensed and summarized form.
Ruby script.
X
X
lspci Shows all hardware attached to the PCI bus
megacli SAS RAID-management tool by LSI
MegaCli
X
oomstat.sh Handles out-of-memory conditions. BASH script.
parted-report Wraps the parted output system-processing for partition size info. Ruby
script.
product-matrix-lookup Drive localization file names for the Security Analytics appliance on
either Dell or legacy DS-xxxx models (not VMs); control product/modelbased settings such as IRQ balance, serial-line name, X desktop support,
management interface.
scm migrator Deprecated in 8.1.1. Imported and exported appliance settings as a JSON
file.
scm pivot_only_provider Adds a pivot-only reputation provider to the View Reputation Provider
menus in the UI.
scm solera_acl elevate Restores a GUI account to admin status.
scm solera_acl shell_only Creates a shell-only user.
scm tally Enables GUI user accounts.
scm sessions Clears session controls.
scotus Gracefully stops system-related services prior to performing other tasks.
scsi-devices Wrapper around the SCSI-to-device-name mapping. Ruby script.
solera_enet_config.py Orders Ethernet interfaces during first boot. Python script.
23
X
Security Analytics Reference Guide
Security Analytics 8.1
Command Use
sudo
solera-affinity Sets CPU affinities. Called from startup on boot for every boot. BASH
script.
update-sysctl Tunes SYSCTL settings for optimal performance. BASH script.
X
Supported Linux Commands
The CLI provides access to the following Linux commands that do not require root-level permissions. For more
information about these commands, including the parameters for each, visit www.tldp.org.
Command Effect
sudo
awk Combines the functions of grep and sed; allows substitution items from
an input file's lines for items in a template, or performs calculations on
numbers within a file
cat Concatenates files and prints to the standard output
chkconfig Updates and queries runlevel information for system services
cp Copies files and directories
date Prints or sets the system date and time
dhclient Enables DHCP on an interface.
grep Searches files for lines containing specified criteria
head Prints the first n lines of files to the standard output (default = 10 lines)
hwclock Queries and sets the hardware clock
ifconfig Not supported in 8.x for eth0 configuration. Use the cfg_bond_
interface.py script to configure bond0 as shown in Setting Up Security
Analytics 8.1.1 in the Security Analytics 8.1.1 WebGuide on
support.symantec.com. To see packet and error counts run ds_dpdk_
stats.py --all . You can use ifconfig to see interface information on
most 8.0.x virtual machines.
ifdown Disables a specified network interface
ifup Enables a specified network interface
ip To view and edit routing, devices, policy routing, and tunnels
X
X
X
jsondiff Usage: jsondiff <left_file>.json <right_file>.json
kill Terminates a process
X
less Enables forward and backward movement while reviewing a text file
ln Creates links to target files
ls Lists information such as size, date created, and directory for specified
files
24
Security Analytics Reference Guide
Security Analytics 8.1
Command Effect
sudo
mii-tool View and edit Media-Independent Interface status
X
mkdir Creates directories
mkfs Builds a Linux file system
mount Mounts a file system
mv Renames or moves files
ngrep Searches for strings across packet data
X
netstat Prints network connections, routing tables, interface statistics,
masquerade connections, and multicast memberships on the standard
output
nice Runs a command at a lower priority level
nohup Suppresses a hang-up signal while running a command
ntpdate Sets a system's clock to match the time published by servers running
NTP
passwd Change the root-level password. Initial root password is set on
/settings/initial_config
ping Uses ICMP to test host connectivity
pkill Looks up or signals processes based on name and other attributes
reboot Reboots the appliance
X
X
rm Deletes a file
rmdir Deletes a directory
route Show or edit the IP routing table
X
scp Securely copies files between hosts on a network
sed Replaces or modifies lines with the specified file
systemctl Stops, starts, or restarts a system service
X
shutdown Shuts down the appliance
solo Prevents multiple cron instances from running simultaneously
sudo Executes a command as a user with greater privileges
sync Synchronizes data on disk with memory
X
tail Prints the last n lines of files to the standard output (default = 10 lines)
top Displays top CPU processes
umount Dismounts file systems
X
uname Prints system information
vim Opens the VIMproved programming text editor
25
Security Analytics Reference Guide
Security Analytics 8.1
Command Effect
sudo
whoami Prints the user name/user ID for the current session
csr.sh
The web interface equivalent for this command is found on the Menu
> System page.
> Settings
The CSR shell script collects several hardware and software log files that contain information useful for
troubleshooting an appliance. Typically, you only need to run this script when directed to do so by Symantec
Support.
syntax
csr.sh
While the script runs, it posts lists that indicate the status of the information-gathering process. The result of the
script is a compressed BZIP file, stored in the /home/csr directory. You can use SCP to retrieve the file and then
attach it to your Symantec Support case.
dscapture
Instructs the system to capture network data.
Some of the web interface equivalents to this command are on the Menu
Capture > Summary page.
>
syntax
dscapture --<operator> [<parameter1>] [<parameter2>] … [<parameterN>]
dscapture clearpersist
Clears all persistent captures and maps.
syntax
dscapture --clearpersist
26
Security Analytics Reference Guide
Security Analytics 8.1
dscapture cleartime
Clears the time values, defined by the settime operator, that are associated with the specified virtual network
interface.
syntax
dscapture --cleartime <virtual_network_interface>
example
[root@hostname ~] dscapture --cleartime ifm0
dscapture init
Initializes the system’s data store in preparation for receiving captured data.
syntax
dscapture --init <hostname>
example
[root@hostname ~] dscapture --init ds1.mydomain.com
dscapture map
Maps the specified virtual network interface to the specified physical network interface so that it can read
captured data from that physical network interface. The persist | nopersist parameter controls whether the
mapping automatically resumes after reboot.
syntax
dscapture --map <virtual_network_interface> <physical_network_interface> [-nopersist| --persist]
example
[root@hostname ~] dscapture --map ifm0 eth2 eth4 --persist
The virtual interface ifm0 is mapped to the physical interfaces eth2 and eth4; this mapping will persist after
reboot.
Also see Playback.
dscapture mapshow
Displays a list of all network interfaces, both physical and virtual, and a list of virtual network interface mappings
to physical network interfaces.
syntax
dscapture --mapshow
27
Security Analytics Reference Guide
Security Analytics 8.1
dscapture settime
Specifies a time at which the specified virtual network interface starts reading captured data. This allows you to
select a specific time period as a starting point when reading or regenerating captured data. Specify the time in
the following format: MM.DD.YYYY.hh.ii.ss
This is not the same format that is used for APIs.
By default, the virtual network interface begins reading data from the beginning of the captured data stream.
Use the settime operator to specify a point in the data stream at which you want to start sending data to the
virtual network interface.
Optionally, you can specify an end_time parameter at which the virtual network interface stops reading from the
data stream.
syntax
dscapture --settime <virtual_network_interface> <start_time> [<end_time>]
example
[root@hostname ~] dscapture --settime ifm0 02.23.2019.16.30.00 02.24.2019.16.30.00
The virtual interface ifm0 plays back data from Feb. 23, 2013, 4:30 p.m. through Feb. 24, 2013, 4:30 p.m.
dscapture shutdown
Shuts down all capture interfaces.
syntax
dscapture --shutdown
dscapture start
Starts capturing network traffic on the specified physical network interface. The persist | nopersist parameter
controls whether capture automatically resumes on the interface after reboot.
syntax
dscapture --start <physical_network_interface> [--nopersist| --persist]
example
[root@hostname ~] dscapture --start eth2 --persist
Starts capture on the physical interface eth2. Capture automatically resumes on the interface after reboot.
28
Security Analytics Reference Guide
Security Analytics 8.1
dscapture status
Displays the current capture status for all physical network interfaces in the appliance, along with memory
statistics and memory usage information for each physical network interface.
syntax
dscapture --status
dscapture stop
Stops capturing network traffic on the specified physical network interface. The persist | nopersist parameter
controls whether capture automatically resumes on the interface after reboot.
syntax
dscapture --stop <physical_network_interface> [--nopersist| --persist]
example
[root@hostname ~] dscapture --stop eth2 --nopersist
Stops capture on the physical interface eth2. The persist setting is also cleared from the interface.
dscapture unmap
Disconnects the specified virtual network interface from its associated physical network interface.
syntax
dscapture --unmap <virtual_network_interface>
example
[root@hostname ~] dscapture --unmap ifm0
All physical interfaces that were associated with ifm0 are no longer associated.
dsfilter
Displays the capture filters assigned to a specific interface, lists the active filters on any given interface, applies a
new filter, removes a filter, or tests a filter.
Some of the web interface equivalents to this command are on the Menu
Capture > Summary page.
syntax
[sudo] dsfilter <parameters>
29
>
Security Analytics Reference Guide
Security Analytics 8.1
[sudo] dsfilter -l -i <interface> [-f <bpf_expression_file>] <bpf_expression>
[sudo] dsfilter -c [-f <bpf_expression_file>] <bpf_expression>
[sudo] dsfilter -usS -i <interface>
[sudo] dsfilter -m [-f <bpf_expression_file>] /pfs/merge/<pcap>
parameters
-i
Specifies the interface. This can also be a virtual interface used for playback (e.g., ifm0).
-l
Loads a filter onto a specified interface.
-f
BPF expression file.
-c
Compiles the filter only; does not load it onto the interface.
-u
Unloads a filter from a specified interface.
-s
Prints the currently loaded filter from a specified interface.
-m
Creates a filter snapshot. You must pass in a BPF file as well as the PCAP file in the /pfs/merge directory.
-l
Loads a filter onto a specified interface.
-S
Prints the currently loaded structure representation of a filter from a specified interface.
examples
[root@hostname ~] dsfilter -i eth3 -s
Displays the capture filter loaded on interface eth3.
[root@hostname ~] dsfilter -i eth5 -u
Unloads the capture filter running on interface eth5.
[root@hostname ~] dsfilter -i eth4 -l "port 80 || port 443"
Applies a capture filter for port 80 and port 443 on interface eth4.
[root@hostname ~] dsfilter -l -i eth3 -f <path_to_filter_file>
Applies a capture filter from an ASCII text file on interface eth3. The text file should be a plain ASCII text file
containing the full BPF filter and nothing else.
When you apply or remove a filter from the command line, refresh the browser to
see the change in the UI.
dsfirewall, dsfirewall6
Toggles the appliance IPv4 or IPv6 firewall on and off. Use iptables to configure individual firewall rules.
30
Security Analytics Reference Guide
Security Analytics 8.1
The web interface controls for the firewall are on the Menu
page.
syntax
[sudo] dsfirewall --<parameter>
parameters
status
Displays the status of the firewall
start
Enables the firewall
stop
Disables the firewall
restart
Reboots the firewall
examples
[root@hostname ~] [sudo] dsfirewall --stop
Disables the appliance's IPv4 firewall.
[root@hostname ~] [sudo] dsfirewall6 --status
Shows IPv6 firewall activity (use of a pipe or paginator is recommended)
31
> Settings > Security
Security Analytics Reference Guide
Security Analytics 8.1
dslc
The web interface equivalents for many of these commands are on the Menu
>
Settings > Communication pages.
Configures the system's communication mechanisms (syslog, SNMP, email):
[sudo] dslc <parameters> <subsystem> [<param1>] [<param2>]…[<paramN>]
dslc add
Adds the specified remote logging server including authentication and encryption, where required. The system
supports only SHA for authentication and AES for privacy.
syntax
[sudo] dslc add snmpv2 <target> <server_ip> <community> [port <port_num>]
[sudo] dslc add snmpv3 <target> <server_ip> <security_name> SHA <auth_key> AES <privacy_key>
[port <port_num>]
[sudo] dslc add syslog <target> <variable>
parameters
subsystem target
snmpv2
trap2sink
informsink
SNMPv2 trap
<community>
Read-only community name
<server>
Server IP address
<port>
Optional — The server port. Leave blank for the
default (162)
SNMPv2 inform
<community>
Read-only community name
<server>
Server IP address
<port>
Optional — The server port. Leave blank for the
default (162)
32
Security Analytics Reference Guide
Security Analytics 8.1
subsystem target
snmpv3
trap2sink
informsink
email
syslog
SNMPv3 trap; variables must be entered in this order:
<server>
Server IP address
<secname>
User name
<authkey>
SHA-hashed password (hex string)
<privkey>
AES-hashed password (hex string)
<port>
Optional — Port number; leave blank for the
default (162)
SNMPv3 inform; variables must be entered in this order:
<server>
Server IP address
<secname>
User name
<authkey>
SHA-hashed password (hex string)
<privkey>
AES-hashed password (hex string)
<port>
Optional — Port number; leave blank for the
default (162)
<email_
address>
Email address; the SMTP server must already be configured using dslc
set
server
<server>
Server IP address or hostname
<port>
Server port; syslog default is 514
<protocol>
Transport protocol; default is udp: [tcp | udp | tls | tls-fips]
<facility>
Syslog facility
examples
[root@hostname ~] [sudo] dslc add snmpv2 trap2sink 192.0.2.44 rotrapcommunity 5162
[root@hostname ~] [sudo] dslc add snmpv3 informsink 192.0.2.40 usRdewd SHA <hex_string> AES
<hex_string>
[root@hostname ~] [sudo] dslc add syslog server 192.0.2.189 514 tls-fips kern
many-to-many syslog/facility association
[root@hostname
[root@hostname
[root@hostname
[root@hostname
~]
~]
~]
~]
[sudo]
[sudo]
[sudo]
[sudo]
dslc
dslc
dslc
dslc
add
add
add
add
syslog
syslog
syslog
syslog
server
server
server
server
203.0.113.11
203.0.113.11
203.0.113.22
203.0.113.22
33
514
514
514
514
tcp
tcp
tcp
tcp
mail
daemon
cron
auth
Security Analytics Reference Guide
Security Analytics 8.1
[root@hostname ~] [sudo] dslc add syslog server 203.0.113.33 514 tcp cron
[root@hostname ~] [sudo] dslc add syslog server 203.0.113.33 514 tcp daemon
On the web interface, only the IP address, port number, and protocol for each entry
will be visible, and so it will appear that there are duplicate entries when the same
server is associated with two or more facilities. Run dslc show syslog to see which
facilities are associated with each server.
dslc del
Deletes the specified remote logging target.
syntax
[sudo] dslc del <subsystem> <target> [server]
parameters
subsystem target
snmp
trap2sink
SNMPv2 trap target
Press Enter to see SNMP trap servers
0–N
server
informsink
SNMPv2 inform target
Press Enter to see SNMP inform
servers 0–N
server
email
syslog
<email_
address>
Email address to delete
server
Press Enter to see syslog servers 0–N
examples
[root@hostname ~] [sudo] dslc del snmp trap2sink server
[root@hostname ~] [sudo] dslc del email admin@company.com
[root@hostname ~] [sudo] dslc del syslog server
dslc disable
Disables the specified subsystem.
syntax
[sudo] dslc disable <subsystem><event1> [<eventN>]
34
Security Analytics Reference Guide
Security Analytics 8.1
parameters
subsystem event
category
misc
All other events
system
System events
user
User events
playback
Network traffic playback events
capture
Network capture events
deepsee
Analytical events such as reporting
hardware
Hardware events
alerts
Alert actions
For each of these events, you must specify at least one of the
following targets:
snmp
syslog
local
Events are written to the local log (default)
snmp
Events are sent to an SNMP server
email
Events are sent to an email account
syslog
Events are sent to a remote syslog server
all
Events are sent to all targets
authtrap
SNMP authorization traps
snmpd
SNMP daemon
coalesce
syslogs merged into a single log
examples
[root@hostname ~] [sudo] dslc disable snmp authtrap
[root@hostname ~] [sudo] dslc disable category hardware syslog
dslc enable
Enables the specified subsystem.
syntax
[root@hostname ~] [sudo] dslc enable <subsystem> <event1> <event2> [<target1> <target2>]
35
Security Analytics Reference Guide
Security Analytics 8.1
parameters
subsystem event
category
misc
All other events
system
System events
user
User events
playback
Network traffic playback events
capture
Network capture events
deepsee
Analytical events such as reporting
hardware
Hardware events
For each of these events, you must specify at least one of following
targets:
snmp
syslog
local
Events are written to the local log (default)
snmp
Events are sent to an SNMP server
email
Events are sent to an email account
syslog
Events are sent to a remote syslog server
all
Events are sent to all targets
authtrap
SNMP authorization traps
snmpd
SNMP daemon
coalesce
Merge syslogs into a single log
examples
[root@hostname ~] [sudo] dslc enable snmp authtrap
[root@hostname ~] [sudo] dslc enable category system syslog
dslc export
Exports the logging configuration file to stdout.
syntax
dslc export
36
Security Analytics Reference Guide
Security Analytics 8.1
dslc factory
Resets the communication system to its default settings.
syntax
dslc factory defaults
subsystem
default settings
SNMP
syslog
n
rocommunity — public
n
authproto — SHA
n
rouser — public
n
authkey — [empty]
n
trapcommunity — public
n
privproto — AES
authtrapenable — off
n
n
privkey — [empty]
n
snmpdenenable — off
trap sink server port — 161
n
n
inform sink server port — 162
n
version — 1
n
facility — 16
n
log coalescing — off
n
remote syslog server port — 514
dslc import
Imports the specified logging configuration file. You can specify either a full path or a file in the current working
directory.
syntax
[sudo] dslc import <import_config_filename>
example
[root@hostname ~] [sudo] dslc logging_config.dat
dslc set
Configures the logging subsystem as specified: SNMPv2, SNMPv3, email, or syslog, or specifies an SMTP server.
syntax
[sudo] dslc set <subsystem> <parameter 1> <value 1> [<parameter 2> <value 2>]
parameters
subsystem parameter
snmp
trapcommunity
SNMPv2 trap community string
version
Sets the polling version: 1 = SNMPv2; 3 = SNMPv3
37
Security Analytics Reference Guide
Security Analytics 8.1
subsystem parameter
snmpv2
snmpv3
email
polling
polling
smtp_server
sender
syslog
Set SNMPv2 authentication
<rouser>
Read-only user name
<rocommunity>
Read-only community
Set SNMPv3 authentication
<username>
User name
<auth_
protocol>
Only SHA is permitted
<auth_key>
Password hash
<privacy_
protocol>
Only AES is permitted
<privacy_key>
Password hash
Specify the SMTP server
<server>
Server IP
port
Server port; default is 25
Specify the sender information
<email_
address>
Email address for the From field
<smarthost_
username>
Username to access the SMTP server
<smarthost_
password>
Password for the SNMP username
from_line_
override
[yes | no]
Yes = Use the From address specified in the UI, if it
exists.
usestarttls
[yes | no]
Yes = Use STARTTLS
facility
The syslog facility that is generating the message. Find supported values
in "Syslog Facilities" on page 1.
examples
[root@hostname ~] [sudo] dslc set snmp trapcommunity h@km3n0t
38
Security Analytics Reference Guide
Security Analytics 8.1
Set the SNMPv2 community string as h@km3n0t.
[root@hostname ~] [sudo] dslc set snmp version 3
Set the polling version to SNMPv3.
[root@hostname ~] [sudo] dslc set snmpv3 polling solEr@ SHA <hex_string> AES <hex_string>
Set the SNMPv3 authentication username as solEr@ and specify the SHA and AES hex strings.
[root@hostname ~] [sudo] dslc set email smtp_server 10.20.30.40 sender solera@company.com
<smtp_username><smtp_password> usestarttls yes
Specify an SMTP server with IP address 10.20.30.40 with server credentials so that it sets the sender address as
solera@company.com and uses STARTTLS.
[root@hostname ~] [sudo] dslc set syslog facility 2
Set syslog facility 2.
dslc show
Displays configuration information for the specified subsystem. The specified parameter determines the
subsystem information that you want to see.
syntax
dslc show <parameter>
parameters
all
Displays all logging configuration
categories
Displays category configuration such as system, user, playback, capture, deepsee, hardware
email
Displays email notification addresses, SMTP server information
snmp
Displays SNMP configuration
syslog
Displays syslog configuration
example
[root@hostname ~] dslc show category
dslogdump
Displays the events captured by the system log.
The web interface equivalent for this command is on the Settings > Audit Log page.
syntax
dslogdump
39
Security Analytics Reference Guide
Security Analytics 8.1
dsmigrate.sh
Use the dsmigrate script to migrate capture data from a Security Analytics appliance to an 8.x appliance. This
script can be used to transfer data from versions 7.x or 8.x to a Security Analytics 8.x appliance.
n
The dsmigrate script replaces dsmigratedata for Security Analytics 8.x and
later.
n
In this procedure, remote refers to the old appliance (version 7.x or 8.x) or
external device — the device from which data is migrated (source) —
whereas local refers to the new 8.x appliance, or the appliance to which data
is migrated (target).
The dsmigrate script reads the data from the remote devide in slot order, earliest to latest, and transports it via
SCP to the local appliance. On the local appliance the data is imported into the capture system as PCAPs, where
indexing takes place in the same way as it does with conventional PCAP imports.
If the local device has less disk space than the remote appliance, the data will be overwritten using the standard
slot-recycling process.
syntax
dsmigrate.sh [options] [-7|-8] <remote server or local path>
options
-t
Retain timestamps (default)
-T
Do not retain timestamps
-p
Remote SSH port (default: 22)
-i<n>
Use impt<n> as the import interface (default: 9)
-7
Import from 7.x remote device
-8
Import from 8.x remote device
-h
Show this help message
-v
Enable verbose mode
-s
Enable compression. Use this option when migrating over a slow link.
-n
Show how the script would run, but do not copy or import
40
Security Analytics Reference Guide
Security Analytics 8.1
n
You must specify either -7 or -8 as the remote version.
n
By default the timestamps from the remote appliance are retained. If you override using the -T option,
the timestamps will be the import time.
n
To run dsmigrate.sh in the background use nohup.
Setup
1. Build the local appliance by installing and licensing Security Analytics 8.x on it.
2. Disable capture on both appliances:
[root@hostname ~]# dscapture --shutdown
3. On the local machine set up and enable any rules that you want to be triggered by the migrated data.
Disable any rules that you do not want to be triggered. (Several rules are active by default.)
4. Connect the remote and local machines by one of the methods shown below:
SSH over a LAN or WAN
Local Mount over a direct Ethernet connection
Local mount of an external device
For the fastest migration speed directly connect the appliances.
41
Security Analytics Reference Guide
Security Analytics 8.1
Migrate the Data
Follow these steps to migrate PCAPs from one Security Analytics appliance or external device to an 8.x appliance.
1. Verify that sufficient space is available on the local appliance.
n
Run df -h on both appliances to compare /pfs allocation. The allocation size does not represent
exactly how much drive space is in use but can help estimate the amount of space needed.
n
SSH Connection Only — Verify that SSH is enabled on the remote device by going to [Menu
>] Settings > Security. Verify which port is specified. If you are specifying a port other than 22,
you must pass the -p <port> attribute.
n
On the local appliance, from a shell with super-user privileges, run dsmigrate.sh. Specify -7 if the
remote device has version 7.x data or -8 if the remote appliance is version 8.x. Specify an
IP address for LAN/WAN connections or the full path with a leading slash [/] for a local mount:
[root@localhostname ~]# dsmigrate.sh [-7|-8] [<remote_IP> | /<local_mount_
path>]
Have you disabled capturing on <remote machine>? <YES/NO> YES
n
SSH Connection Only — The script's first action is to generate and copy an SSH key to the remote
device. You may be required to provide the root password for the remote device.
...
/usr/bin/ssh-copy-id: INFO: Source of key(s) to be installed:
"/root/.ssh/migrate.pub"
The authenticity of host <remote machine> can't be established.
Are you sure you want to continue connecting? (yes/no)? yes
...
<Message of the day for the remote machine>
Password: <root password>
n
The dsmigrate script transfers data from the remote device via SCP to the local appliance one slot
at a time. With verbose mode off, these messages indicate the progress for each imported chunk:
<<< Generating list of slots to migrate ... >>>
<MOTD> (SSH connection only)
<<< Slots to transfer: <slots> >>>
<<< Slot #1: <name> >>>
-transferring<MOTD>
-importing<<< Slot #2: <name> >>>
n
When importing from 7.x, name is <id><remote_hostname>. When importing from 8.x name is
slot_<x>.
n
The list of slots to migrate from the remote device is in /tmp/migrate-slotlist of the local appliance.
The list of slots that have already been migrated is in /tmp/migrated. If the migration is interrupted
— with Ctrl+C, for example — and then restarted, the script skips the slots that are listed in
/tmp/migrated.
n
When the migration is complete the message <n> slots successfully migrated is displayed and the
files in /tmp are deleted.
42
Security Analytics Reference Guide
n
Security Analytics 8.1
Because the imported PCAPs are not shared, and because they are imported by root, the PCAPs are
not visible on Capture > Import PCAP (there would be tens of thousands of entries), nor does the
PCAP Import line on the Capture Summary Graph register the imports. If you had rules enabled
during import, however, you can see the data by enabling Flows in Progress and Flows Initiated.
43
Security Analytics Reference Guide
Security Analytics 8.1
dsmigratedata
Use the dsmigratedata command to migrate capture and indexing data from one 7.x Security Analytics
appliance to another 7.x appliance.
The dsmigratedata command can be used only with Security Analytics 7.x and
earlier. To migrate data to version 8.x and later use dsmigrate.sh.
Symantec strongly recommends that this data-migration operation be performed
only under the direction of Symantec Support or qualified professional services.
syntax
dsmigratedata -s [<source_IPv4> | [<source_IPv6>]] [options]
Setup
The dsmigratedata utility offers users the option of encrypted data migration using SSH or of unencrypted
migration for cases where security is not an issue, for example, in the case of a direct connection or a secure
network.
In this procedure, source always refers to the old appliance, or the machine from which data is migrated (the
source of the data), whereas target refers to the new appliance, or the machine to which data is migrated (the
target of the migration).
For the fastest migration speed, directly connect the appliances and remove encryption.
Connection Type
With Encryption
(TB/day)
Without Encryption
(TB/day)
5.78
32.88
10 Gbps
44
Security Analytics Reference Guide
Security Analytics 8.1
With Encryption
(TB/day)
Without Encryption
(TB/day)
1 Gbps
3.67
7.68
LAN
5.44
8.56
Connection Type
Interface Configuration
To configure the machines for direct migration:
1. Build the target appliance by installing and licensing Security Analytics on it.
2. Disable capture on both appliances:
[root@hostname ~]# dscapture --shutdown
3. Connect a cable between one of the interfaces on each of the source and target machines. A 10Gb
connection will give the best performance, but a 1Gb copper connection is also acceptable.
4. As the super user on the source machine, assign a non-routable IP address to the Ethernet interface
(direct connection) or an unused address on the management LAN. Enclose an IPv6 address in [square
brackets] and omit the netmask argument.
[root@sourcehostname ~]# ifconfig ethX 198.51.100.2 netmask 255.255.255.0 up
where ethX is the migration interface.
5. Repeat the previous step on the target machine, as super-user on that machine, except with a different IP
address on the same network:
[root@targethostname ~]# ifconfig ethX 198.51.100.3 netmask 255.255.255.0 up
6. Test connectivity between the target and source appliances. To enable ping, run these two commands on
the appliance to ping.
[root@hostname ~]# sysctl net.ipv4.icmp_echo_ignore_all=0
[root@hostname ~]# sysctl net.ipv4.icmp_echo_ignore_broadcasts=0
Data-Migration Procedure
Follow these steps to migrate data from one Security Analytics appliance to another.
1. Verify that sufficient space is available on the target appliance.
n
Run df -h on both appliances to compare /pfs allocation. The allocation size does not represent
exactly how much drive space is in use but can help estimate the amount of space needed.
n
For simplicity, you can run dszap on the target, although this is not strictly required.
n
If there is not enough space, the utility returns a warning. If you choose to continue, existing or
earlier-migrated data might be overwritten.
45
Security Analytics Reference Guide
Security Analytics 8.1
2. Configure passwordless SSH for connections from the target to the source, first by generating a
passwordless key on the target:
[root@targethostname ~]# ssh-keygen -t rsa
Press Enter when prompted for a password.
[root@targethostname ~]# vi .ssh/id_rsa.pub
Copy the public key.
3. Copy the key to the source:
[root@sourcehostname ~]# vi .ssh/authorized_keys
Paste the key to the file, then save and exit.
4. On the target, test SSH authentication:
[root@targethostname ~]# ssh root@<source_IP> [-v]
5. From a shell with super-user privileges on the target, launch the dsmigratedata utility:
[root@targethostname ~]# dsmigratedata -s <source_IP> [-w]
where -w means "without encryption." This option removes all the cryptography related mechanisms such
as SSH encryption/decryption. If -w is not specified, the script will transfer the data with encryption.
Enclose an IPv6 address in [square brackets].
options
-c --igraph
Migrate capture summary graph data
-d --debug
Debug messages for developers
-h --help
Print help
-i --interfaces
CSV list of interface from which to read slots
-n --no-retaintimestamp
Migrate data without retaining the timestamps
-p --port
SSH port
-r --restart
Restart migration from the first file (stateless restart)
-s --remote-server
Remote server (source appliance)
-v --verbose
Enable verbose mode
-w --withoutencryption
Migrate data without encryption (Use only when there's no danger if data
interception.)
46
Security Analytics Reference Guide
Security Analytics 8.1
n
By default, data is migrated from all of the physical interfaces that are present on the source. Use -i -interfaces to migrate only the data from specified interfaces.
n
By default, the timestamps from the source are retained. Override using the –n --no-retain-timestamp
option.
n
The default SSH port is 22 for the source. If SSH is running on another port, use the -p --port option to
specify the port on both appliances. If you change the default port, and SSH communication between the
two appliances is blocked, you can disable the appliance firewall (systemctl stop iptables) or create a rule
in the appliance firewall.
n
The verbose option prints more information on the console. It is advisable to run the script in nonverbose mode for better performance results.
n
To run dsmigratedata in the background use nohup.
Operation of dsmigratedata
1. When the script is launched, it takes a snapshot of existing slots, then displays a message on the console:
SLOTS TO MIGRATE: X
2. The script loops through each interface that has captured or imported data and migrates the data for that
interface. As the slots are migrated, a message similar to the following is displayed:
**************
TOTAL MIGRATED
TIME ELAPSED :
SLOTS REMAINED
STATS **************************
DATA : 292.28 MB
00:01:25
IN CURRENT PASS : Y
3. If capture is still enabled on the source appliance, the script checks for any new slots that were added
during migration and displays the message:
TOTAL SLOTS TO MIGRATE: Z
Symantec strongly recommends that capture be disabled on the source
machine during the migration process.
a. If Z is greater than zero, the script loops through the interfaces again and migrates the new
data.
b. If Z is zero but some interfaces on the source machine are still capturing data, the script will
go into sleep mode and wake every 5 minutes to check for new slots. If new slots are
discovered, the "total slots to migrate" message is displayed again and the data is migrated.
4. When there are no slots left to migrate, or when capture is disabled on the source machine, the following
message is displayed:
Data Migration Completed
47
Security Analytics Reference Guide
Security Analytics 8.1
Restarting dsmigratedata
The dsmigratedata utility can be restarted after system crash, user-abort, or termination due to abnormal
situations.
Stateful Restart
To facilitate restart, the migration state is stored in the file /var/state/solera/dsmigratedata/<source_IP>.
User Abort
When you abort the data migration process manually (Ctrl+C), the -w option affects how data migration
resumes:
n
-w option specified — When you press Ctrl+C, dsmigratedata saves the state and immediately exits. For
example, if migration is at slot 1600 when you press Ctrl+C, migration resumes at slot 1601 upon
restarting.
n
-w option not specified — When you press Ctrl+C, dsmigratedata exits migration only after importing
the current block of 1024 slots. For example, if migration is at slot 1600 when you press Ctrl+C, migration
does not terminate until after dsmigratedata has finished migrating slot 2048. Therefore, dsmigratedata
resumes at slot 2049 upon restarting.
Abnormal Termination
Migration is restarted from the current 1024-block of slots that was being imported. For example, if migration is
at slot 1624 when abnormal termination occurs, the last 600 slots are remigrated upon restarting.
Stateless Restart
To flush the state and restart from scratch, pass the -r --restart flag to the dsmigratedata utility.
dspcapimport
Imports PCAP and PCAPNG files to the system. Prior to running this command, upload the file to a location on
the appliance or to an NFS share that you have mounted on the appliance. On the web interface, the import
source for the PCAP will show as USB. For an NFS share, the Import Source column shows the name of the
server as configured in Manage Connections.
Find the equivalent function on the Menu
web interface.
> Capture > PCAP Import page of the
syntax
dspcapimport -f <pcap_file_path> [<parameters>]
48
Security Analytics Reference Guide
Security Analytics 8.1
parameters
-t
1 = Retain original timestamps; 0 = Use current time for timestamps
-i
Import interface name: impt0 through impt9; If no interface is specified, the first available interface
will be used. If an interface is specified that is not available, an error is returned.
-f
PCAP filename and path; PCAP and PCAPNG formats are supported
-s
1 = shared; 0 = not shared
example
[root@hostname ~] dspcapimport -f 2019-05-23.pcap -t 1 -s 1
Imports a PCAP file from the root directory, retains the original timestamps, and marks it as shared.
dsportmapping
Provides customized port-to-application mapping.
syntax
dsportmapping [list | add <application_name><port> ["<comment>"] | remove
<application_name> | import <filepath>]
parameters
list
add
Show all customized port-to-application mappings
Add a port-to-application mapping:
<application_name>
<port>
<comment>
Name of the application
Integer between 0–65535
Optional. Add a comment
remove
Delete a port-to-application mapping.
import
Import a file that contains port-to-application mappings. Format the data as follows, with
one mapping per row:
<application_name> <port> <comment>
There must be at least one line ending after the last entry.
examples
[root@hostname ~] dsportmapping add smtp 26 "Internal Mail"
Maps SMTP to port 26 and adds the "Internal Mail" comment.
[root@hostname ~] dsportmapping import port-mapping.txt
Imports a user-created file called port-mapping.txt from the root directory.
49
Security Analytics Reference Guide
Security Analytics 8.1
dsregen
Takes captured network traffic and retransmits it from a virtual network interface to a physical network
interface. This is referred to as "playback," which takes traffic being captured on one interface and replays it to
another interface in real time.
The web interface equivalent for much of this functionality is on the Menu
>
Capture > Summary page. Also see "Playback" in the Security Analytics 8.1.x
Administration and Central Manager Guide on support.symantec.com.
n
For the system to play back traffic, you must map a virtual interface to a physical capture interface. (You
cannot replay traffic to a physical network interface that is currently capturing network traffic.)
n
As part of the playback process, you can shape the network traffic to make it more appropriate to your
particular application. For example, you can play back traffic at defined packet rates and filter traffic to
meet particular criteria.
n
In addition to retransmitting packets, you can use dsregen to load-balance packet streams across multiple
application instances so that you can balance the data stream across multiple devices to keep up with
traffic load.
n
The virtual network interface must be assigned to the physical capture interface before running dsregen.
syntax
dsregen [--filter=<filename>] <function> [<virt if> <xmit if>] [<interval>]
[<pid>]
parameters
start
stop
<virt if>
The source virtual network interface from which you want to play back
network traffic.
<xmit if>
The destination physical network interface where you want to play back
network traffic.
<virt if>
The source virtual network interface where you want to stop playback.
<xmit if>
The destination physical network interface where you want to stop
playback.
<pid>
Optional — Specifies the internal process ID (PID) that the system
assigns to the playback session. Use the PID when there are multiple
sessions using the same source and destination interfaces. Use dsregen
show to see the PID.
50
Security Analytics Reference Guide
Security Analytics 8.1
save
Saves the filter on the virtual interface
load
Loads a saved playback session
show
Displays the status of all current playback sessions, including packets aborted due to errors.
examples
[root@hostname ~] dsregen start ifm0 eth3
Starts playback from virtual network interface ifm0 to eth3. This playback will not be visible on the UI because
ifm0 has not been assigned to a physical interface, but Playback Start and Playback Stop will show up in the
Audit Log.
[root@hostname ~] dsregen --filter=filter.out start ifm0 eth3
Starts playback from virtual network interface ifm0 to eth3, after applying the filter in the binary output file
filter.out.
[root@hostname ~] dsregen stop ifm0 eth3 4278
Stops the playback session from virtual network interface ifm0 to eth3, which has the PID of 4278.
[root@hostname ~] dsregen show
Produces a readout similar to the following:
[root@hostname ~] dsregen show eth3
snlog_wrapper: User admin called 'dsregen show eth3'
ifm0 -> eth3 state: ACTIVE kpid:7253
bytes transmitted :0
packets transmitted :0
packets aborted :0
size errors :0
fault errors :0
retry errors :0
interface errors :0
packet tx
retries :0
[root@hostname ~]_
dszap
Deletes ALL data from the capture, indexing, and home drives (including saved reports, saved extractions, and
capture filters) and reinitializes the datastore. Use this command to perform troubleshooting or free-up disk
space.
Once this command is executed, the deleted data cannot be recovered.
51
Security Analytics Reference Guide
Security Analytics 8.1
syntax
[sudo] dszap
parameters
-h help
-v verbose
-n noexec
-f force
-p partition
-i ignore
-q quick
-R recursive
Display help.
Display all output. This parameter shows every deletion and can include 1000s
of lines of output.
Output the command without executing it.
Proceed without the ZapALLData confirmation.
Partition as well as reformat with mkfs.xfs. Omit this parameter to use dd to
write 1MB of zeros at the front of the partition to wipe out the partition tables.
Pass the ignore flag to scotus stop.
Use reformatting to clear the indexing volume.
Use rm to clear the the indexing volume (default).
52
Security Analytics Reference Guide
Security Analytics 8.1
Actions Performed
dszap performs the following actions:
Delete
Deactivate
n
Capture and indexing data
n
Rules
n
Capture summary graph
n
Data-enrichment settings
n
Capture filters
n
Alerts
n
Audit log
n
Saved reports
n
Authentication settings (LDAP, RADIUS)
n
Report status entries
n
CMC settings
n
Saved extractions
n
Communication settings (SNMP, syslog)
n
Extraction status entries
n
Data enrichment settings (deactivated)
n
PCAP imports
n
Date and time
n
PCAP watch folders
n
Geolocation settings
n
Report schedules
n
Indicators (deactivated live-feeds)
n
Retrospective jobs
n
Metadata settings
n
Customized summary views
n
Rules (deactivated)
n
Real-time extractions
n
Upgrade servers
n
Statistics
n
Users and groups
n
Login Correlation Service agent IPs
n
Web interface settings
Retain
Reset
n
PCAP imports queue
n
Retrospective jobs ID sequence
n
Capture interfaces
Running dszap
After entering dszap you are prompted to confirm the deletion of data: We are about to re-initialize all of your
data storage. If this is what you want, please type "ZapALLData" to continue.
Confirm by typing ZapALLData
While running, this command displays information about the status of the command.
53
Security Analytics Reference Guide
Security Analytics 8.1
The dszap process may appear to hang while deleting /home/extractor-live files. If
the system has been performing real-time extractions for data-enrichment rules,
this process may take an extended amount of time.
For the changes to take effect, you must reboot the system after you run this command. You can do this in the
UI by selecting Menu
> Settings > System > Reboot or by typing reboot on the command line.
After you reboot, you will need to re-activate your rules, live-feed indicators, and
data-enrichment providers.
54
Security Analytics Reference Guide
Security Analytics 8.1
dump_slot
Use these commands to view information regarding the slots.
n
create time — When the system was first installed
n
update time — Last time data was written
n
start — First time the slot was written
n
end — Last time the slot was written
dump_slot_chain
Information on all interfaces that are capturing.
create time: 2019-09-06 17:45:05.534399043
update time: 2019-10-01 15:42:08.135132956
max num files: 42430, slot size: 67108864
total slots: 42432, next slot: 769092, first slot: 726660
total packets: 68914512, total bytes: 39169728525, dropped packets: 0
eth4 (if_index 5):
start: 2018-09-30 06:48:33.452971699, end: 2018-10-01 15:42:03.439005038
slot count: 42432, start slot: 726660, end slot: 769091
total packets: 5015086661, total bytes: 2565913192911, dropped packets:
18446462597417917505
dump_slot_header slot_<number>
While in /pfs/create/<tab> run this command to get information about the slot header.
[root@<hostname> 4C4C4544-0039-4310-8052-B8C04F444232]# dump_slot_header slot_1650747
****** Slot Header 1650747 ********
iface_id = 6
next_slot = 1650748
slot seq = 1650747
pkts = 95120
bytes = 61781692
dropped_pkts = 0
start_time = 2019-10-02 12:34:41.093743799
end_time = 2019-10-02 12:34:41.207753823
filled = yes, mapped = yes
empty = no, init = no
mapped_header = no, capturing = no
in_regen = no, posted = no
in_io = no, recycled = no
dump_slot_elements <filename>
While in /pfs/create/<tab> run this command to get a list of the packets in the slot.
55
Security Analytics Reference Guide
Security Analytics 8.1
[root@<hostname> 4C4C4544-0039-4310-8052-B8C04F444232]# dump_slot_elements slot_1650747
[90832]:flowid=1297604353,offset=46844338,size=114,time=2019-10-01 15:42:08.360844905
[90833]:flowid=1297604353,offset=46844468,size=130,time=2019-10-01 15:42:08.360847742
[90834]:flowid=1297760584,offset=46844534,size=66,time=2019-10-01 15:42:08.360850458
[90835]:flowid=1297766315,offset=46845976,size=1442,time=2019-10-01 15:42:08.360860002
[90836]:flowid=1297410786,offset=46847055,size=1079,time=2019-10-01 15:42:08.360863747
[90837]:flowid=1297250519,offset=46847169,size=114,time=2019-10-01 15:42:08.360867040
[90838]:flowid=1297764691,offset=46848611,size=1442,time=2019-10-01 15:42:08.360869830
[90839]:flowid=1297675483,offset=46848677,size=66,time=2019-10-01 15:42:08.360887154
[90840]:flowid=1297614305,offset=46848743,size=66,time=2019-10-01 15:42:08.360890019
[90841]:flowid=1297767014,offset=46848913,size=170,time=2019-10-01 15:42:08.360911668
[90842]:flowid=1297766218,offset=46850355,size=1442,time=2019-10-01 15:42:08.360923159
[90843]:flowid=1297764237,offset=46851797,size=1442,time=2019-10-01 15:42:08.360944055
dump_slot_pcap <packet_number>
While in /pfs/create/<tab> run this command to create a PCAP of one of the packets and write it to /tmp.
[root@<hostname> 4C4C4544-0039-4310-8052-B8C04F444232]# dump_slot_pcap 1650747 -d /tmp
dump_slot_trail
Run this command to see the context for the current slot chain.
hostname: 223-dicentra, UUID: 4C4C4544-004E-3110-8033-B9C04F335731, version: 10
create time: 2019-09-06 17:45:05.534399043
update time: 2019-10-01 15:44:26.140642053
max num files: 42430, slot size: 67108864
total slots: 42432, next slot: 769141, first slot: 726709
total packets: 68914512, total bytes: 39169728525, dropped packets: 0
eth4 (if_index 5):
first packet seen: yes, imported last slot: no
slot trail: (* for last inserted), total inserted: 96864
[0]: slot 769138, generation 19373
[1]: slot 769139, generation 19373
[2]: slot 769140, generation 19373
[3]: slot 769141, generation 19373*
[4]: slot 769137, generation 19372
indexer info:
[0]: slots indexed 96864, state 6
[1]: slots indexed 96864, state 6
last slot processed:769141, last sequence processed:1277
dump_space_table_entry <slot_id>
Run this command for a summary of slot information.
Slot 1650747 start Mon Oct 1 15:45:42 2018 (1538430342) end Mon Oct 1 15:45:44 2018 (1538430344)
iface 5 flags 2
56
Security Analytics Reference Guide
Security Analytics 8.1
walk_space_table_journal
Run this command to see a list of slots with start and end dates.
Slot 84571 start
iface 5 flags 2
Slot 84572 start
iface 5 flags 2
Slot 84573 start
iface 5 flags 2
Slot 84574 start
iface 5 flags 2
Slot 84575 start
iface 5 flags 2
Slot 84576 start
iface 5 flags 2
Slot 84577 start
iface 5 flags 2
Slot 84578 start
iface 5 flags 2
Slot 84579 start
iface 5 flags 2
Slot 84580 start
iface 5 flags 2
Slot 84581 start
iface 5 flags 2
Sat Sep 8 12:37:39 2018 (1536431859) end Sat Sep 8 12:37:41 2018 (1536431861)
Sat Sep 8 12:37:41 2018 (1536431861) end Sat Sep 8 12:37:43 2018 (1536431863)
Sat Sep 8 12:37:43 2018 (1536431863) end Sat Sep 8 12:37:45 2018 (1536431865)
Sat Sep 8 12:37:45 2018 (1536431865) end Sat Sep 8 12:37:48 2018 (1536431868)
Sat Sep 8 12:37:48 2018 (1536431868) end Sat Sep 8 12:37:49 2018 (1536431869)
Sat Sep 8 12:37:49 2018 (1536431869) end Sat Sep 8 12:37:51 2018 (1536431871)
Sat Sep 8 12:37:51 2018 (1536431871) end Sat Sep 8 12:37:53 2018 (1536431873)
Sat Sep 8 12:37:53 2018 (1536431873) end Sat Sep 8 12:37:55 2018 (1536431875)
Sat Sep 8 12:37:55 2018 (1536431875) end Sat Sep 8 12:37:57 2018 (1536431877)
Sat Sep 8 12:37:57 2018 (1536431877) end Sat Sep 8 12:37:58 2018 (1536431878)
Sat Sep 8 12:37:58 2018 (1536431878) end Sat Sep 8 12:38:00 2018 (1536431880)
dynfilter
View and manage the dynamic filters.
Set up dynamic filter rules on the Menu
> Analyze > Rules page.
syntax
dynfilter --list [<options>]
dynfilter --kill --interface=<interface><hash>
options
-i
--interface=ARG
Specify interface name (required for --kill); use all for all interfaces
-c
--config=ARG
Use the config file specified by ARG
-d
--debug
Turn debug logging on
-h
--help
Display the usage and help info
-n
--noexec
Do not actually extract, but clear queues in a dry-run manner
57
Security Analytics Reference Guide
Security Analytics 8.1
-v
--verbose
Log additional processing information
-V
--version
Show version information and exit
usage
List active filters (defaults to all interfaces). Filters are sorted by interface (ascending) and then by the soonest to
expire (ascending).
[root@hostname ~] dynfilter -l
IFNAME SECS RULE UUID
eth2
15
561c33b4-ebb8-4cf3-ac6c-1d180a83290b
host 203.0.113.112) or (src host 203.0.113.112)))'
eth2
80
561c33b4-ebb8-4cf3-ac6c-1d180a83290b
host 198.51.100.11) or (src host 198.51.100.11)))'
eth2
140
561c33b4-ebb8-4cf3-ac6c-1d180a83290b
host 192.0.2.5) or (src host 192.0.2.5)))'
HASH
180047451a0357e6
BPF FILTER STRING
'(ip and tcp and ((dst
a15bdcfd7e9f826c
'(ip and tcp and ((dst
882f0612f001f218
'(ip and tcp and ((dst
columns
n
IFNAME — Name of the interface where the filter is applied. Filters are applied only on interfaces where
traffic is detected.
n
SECS — Seconds remaining before the filter expires and is removed.
n
RULE UUID — UUID for the rule that specified the filter.
n
HASH — Used only by this tool to specify a filter string, to be used with the kill command.
n
BPF FILTER STRING — The filter string that is applied to the interface after a NOT, such that (ip and tcp
and ((dst host X) or (src host Y)) blocks hosts X and Y that are using TCP/IP.
remove a filter
To remove a filter, use --kill <hash> --interface <interface>
[root@hostname ~] dynfilter -k 882f0612f001f218 -i eth2
eth2
140
561c33b4-ebb8-4cf3-ac6c-1d180a83290b 882f0612f001f218
host 203.0.113.5) or (src host 203.0.133.5)))'
'(ip and tcp and ((dst
The filter that has been removed is displayed.
To remove all filters from all interfaces for a given rule, go to Menu
Rules on the web UI and disable
then enable
lsi-rate-tool
View and alter the initialization rate for adapters on the appliance.
58
the rule.
> Analyze >
Security Analytics Reference Guide
Security Analytics 8.1
syntax
lsi-rate-tool [<parameter1> <parameter2> --] [<action> <rate>]
parameters
-h, --host
IP address of appliance
-P, --port
Port ID of port for login
-u, --user
UserID of login (default = root)
-p, --passwd
-r, --retries
-a, --all
-c, --category
Password associated with userID
Maximum number of login retries: default=3
Apply rate to all adapters including system RAID adapters
Category (default is all categories)
CCRate
ReconRate
RebuildRate
BGIRate
-v, --verbose
The rate at which the consistency checks are performed on the RAID
sets.
The rate at which a damaged virtual drive may be reconstructed.
The rate at which a damaged or missing physical disk can be rebuilt.
The background initialization rate, which is the rate at which RAIDinitialization operations occur.
Display script actions as they run
-n, --noExec
Show script actions but do not execute them
-S, --stderr
Redirect standard error messages to /dev/nu...
-D, --debug
Enable debugging output
-H, --help
Display help screen
--
End of parameters
<action>
Specify the action:
set
reset
show
<rate>
10 = 10%, 90 = 90%
Resets the default for the category
(default); Displays the current setting
Specify the rate in Mbps (0–100); valid only with set action
59
Security Analytics Reference Guide
Security Analytics 8.1
examples
[root@hostname ~] lsi-rate-tool
Shows the local appliance initialization rates and enables all parameters.
[root@hostname ~] lsi-rate-tool -h 192.0.2.109
Shows the initialization rates for the specified appliance.
[root@hostname ~] lsi-rate-tool -c CCRate set 90
Dedicates 90% of the adapter's cycles to consistency checks.
[root@hostname ~] lsi-rate-tool reset
Sets the initialization rate to the default.
[root@hostname ~] lsi-rate-tool -c ReconRate
Displays the virtual disk reconstruction rate for each installed LSI-based adapter:
Adapter 0: Reconstruction Rate = 30%
Adapter 1: Reconstruction Rate = 30%
Adapter 3: Reconstruction Rate = 30%
lsi-show
View configuration and setup information associated with RAID controllers.
syntax
lsi-show [<parameter1> <parameter2> --]
parameters
-h, --host
IP address of appliance
-P, --port
Port ID of port for login
-u, --user
User ID of login (default = root)
-p, --passwd
Password associated with userID
-r, --retries
Maximum number of login retries: default=3
-s, --summary
Do not show physical device lists
-v, --verbose
Display script actions as they run
-n, --noExec
Show script actions, but do not execute them
-S, --stderr
Redirect standard error messages to /dev/null
-D, --debug
Enable debugging output
60
Security Analytics Reference Guide
-H, --help
--
Security Analytics 8.1
Display the help screen
End of parameters
examples
[root@hostname ~] lsi-show
Shows the local RAID controller values.
[root@hostname ~] lsi-show -h 192.0.2.109
Shows the RAID controller values for the specified appliance.
MegaCli | megacli
SAS RAID management tool for Dell hardware. Only a few of the commands are displayed here.
syntax
[[MegaCli | megacli] [command]] [-Silent] [-AppLogFile filename] [-NoLog]
[-page[N]]
[root@hostname ~] megacli -encinfo -aall
Shows the status of the JBOD enclosures.
[root@hostname ~] megacli -AdpAllInfo -aAll
Shows the adapter info.
[root@hostname ~] MegaCli -CfgDsply -aALL
Shows all drive and adapter info.
[root@hostname ~] MegaCli -AdpEventLog -GetEvents -f events.log -aALL && cat events.log
Shows the log/historical info.
[root@hostname ~] megacli -pdlocate [-start|-stop] -physdrv[E:S] -aX
Finds a sensor or drive by lighting up the drive-locator LED, where
n
E — enclosure ID
n
S —slot number
n
aX — adapter number
example
[root@hostname ~] megacli -pdlocate -start -physdrv[25:2] -a2
Finds enclosure 25, slot 2 on controller/adapter 2.
Use lsi-show to see the enclosure:slot numbers and adapter/controller ID.
61
Security Analytics Reference Guide
Security Analytics 8.1
scm pivot_only_provider
Adds a pivot-only reputation provider, which opens the web page of the specified reputation provider with the
selected value as the search term. Reputation providers that are added using this method are listed on Settings >
Data Enrichment under Third Party On-Demand Reputation Providers and are available in the View Reputation
Information menus on the Analyze > Summary, Reports, Extractions, and Geolocation pages.
Add pivot-only providersfrom the web UI on Menu
Enrichment > Third-Party Integration Providers.
> Settings > Data
After you have finished adding one or more providers, you must restart the web
server using the command systemctl restart httpd
Add a Pivot-Only Provider
syntax
scm pivot_only_provider [insert | refreshData] -v "<provider_name>"
<provider_category><pivot_url>
parameters
provider_name
Display name of the reputation provider. Do not use special characters.
62
Security Analytics Reference Guide
provider_
category
Category of the provider:
hash
Search on the MD5 hash. Supported only in artifact entries. To invoke the
provider in reports and report widgets specify any.
sha1
Search on the SHA1 hash. Supported only in artifact entries. To invoke the
provider in reports and report widgets specify any.
sha256
fuzzy
url
ip
host
any
pivot_url
Security Analytics 8.1
Search on the SHA256 hash. Supported only in artifact entries. To invoke the
provider in reports and report widgets specify any.
Search on the fuzzy hash. Supported only in artifact entries. To invoke the
provider in reports and report widgets specify any.
Search on the URL
Search on the IP address; enclose an IPv6 address in [square brackets]
Search on the hostname
Search on any value
Pivot URL. Syntax is http://<url>%{TOKEN} or https://<url>%{TOKEN}
The %{TOKEN} string will be automatically replaced by the value to search.
If the %{TOKEN} string cannot be at the end of the URL, enclose the entire URL in double
quotation marks: "http://<url>"%{TOKEN}"<string>"
examples
[root@hostname ~] scm pivot_only_provider insert -v "CysconSIRT" host http://www.csirt.org/lang/en-us/incidents-on-domain?domain=%{TOKEN}
Adds the CysconSIRT reputation provider and specifies that the value to search is hostname.
[root@hostname ~] scm pivot_only_provider insert -v "MX Toolbox1" any
"http://mxtoolbox.com/SuperTool.aspx?action=blacklist%3a"%{TOKEN}"&run=toolpage"
Adds the MX Toolbox1 reputation provider with a URL that requires characters after %{TOKEN}.
[root@hostname ~] scm pivot_only_provider refreshData
Refreshes the reputation providers data column.
Pivot-Only Provider Demonstration
For this demonstration, four pivot-only providers will added — one of each type — to show how the providers
are available in the web UI.
Add the Pivot-Only Providers
Log in to the command-line interface as root and enter the following commands:
63
Security Analytics Reference Guide
Security Analytics 8.1
scm pivot_only_provider insert -v "Malc0de Hash" hash
http://malc0de.com/database/index.php?search=%{TOKEN}
scm pivot_only_provider insert -v "hpHosts IP" ip http://hosts-file.net/default.asp?s=%
{TOKEN}
scm pivot_only_provider insert -v "DShield Domain" host
http://www.dshield.org/ipinfo.html?ip=%{TOKEN}
scm pivot_only_provider insert -v "McAfee SiteAdvisor" any
http://www.siteadvisor.com/sites/%{TOKEN}
systemctl restart httpd
View the New Providers in the UI
1. In the UI, select Menu
Reputation Providers.
> Settings > Data Enrichment and scroll to Third-Party On-Demand
The new pivot-only providers are displayed in alphabetical order. You can activate or deactivate them on
this page, as desired.
2. Select Menu
> Analyze > Summary to view captured or PCAP data. Select the IP Layer View.
3. Click a value in an IPv4 widget and select View Reputation Information.
64
Security Analytics Reference Guide
Security Analytics 8.1
4. The hpHosts IP provider is available because it is an IP-type provider, and Mnemonic pDNS Host is
available because it is an any-type provider. Click either provider to launch the provider's page in a new
tab with the selected IP address as the query value.
5. Click the Reports tab and select the Web: HTTP Server report. Click an entry in the results list and select
View Reputation Information.
65
Security Analytics Reference Guide
Security Analytics 8.1
6. All of the host-type providers are displayed, including the new DShield Domain and Mnemonic pDNS
Host providers.
7. Click the Extractions tab. When the extraction has finished, expand an entry, click the MD5 hash, and
select View Reputation Information.
8. The Malc0de Hash and Mnemonic pDNS Host providers are available.
Hash-type providers are not available for the File: MD5 Hash report or report
widget.
Delete a Pivot-Only Provider
You cannot edit an existing pivot-only provider; you must delete and then re-add the provider.
syntax
su postgres
psql -d dsweb
select * from integration_providers;
DELETE FROM integration_providers WHERE name = '<provider_name>';
You may omit the line select * from integration_providers; if you already know the provider name.
Sample Pivot-Only Providers
This list is not maintained by Symantec; it is the responsibility of the user to verify
that the URLs are valid.
"BFK Passive DNS Hosts" host http://www.bfk.de/bfk_dnslogger_en.html?query=%{TOKEN}
"BFK Passive DNS IP" ip http://www.bfk.de/bfk_dnslogger_en.html?query=%{TOKEN}
66
Security Analytics Reference Guide
Security Analytics 8.1
"Builtwith Domain Relationships" host https://builtwith.com/relationships/%{TOKEN}
"CentralOps Whois Host" host 'https://centralops.net/co/DomainDossier.aspx?&dom_whois=true&dom_
dns=true&net_whois=true&addr='%{TOKEN}
"CentralOps Whois IP" ip 'https://centralops.net/co/DomainDossier.aspx?&dom_whois=true&dom_
dns=true&net_whois=true&addr='%{TOKEN}
"Domain Tools Host" host https://whois.domaintools.com/%{TOKEN}
"Domain Tools IP" ip https://whois.domaintools.com/%{TOKEN}
"DShield Domain" host https://secure.dshield.org/ipinfo.html?ip=%{TOKEN}
"DShield IP" ip https://secure.dshield.org/ipinfo.html?ip=%{TOKEN}
"hpHosts Domain" host https://hosts-file.net/?s=%{TOKEN}
"hpHosts IP" ip https://hosts-file.net/?s=%{TOKEN}
"hpHosts URL" url https://hosts-file.net/?s=%{TOKEN}
"IP Void" ip http://www.ipvoid.com/scan/%{TOKEN}
"Is It Hacked Domain" host http://www.isithacked.com/check/%{TOKEN}
"Is It Hacked URL" url http://www.isithacked.com/check/%{TOKEN}
"Malc0de
"Malc0de
"Malc0de
"Malc0de
Domain" host http://malc0de.com/database/index.php?search=%{TOKEN}
Hash" hash http://malc0de.com/database/index.php?search=%{TOKEN}
IP" ip http://malc0de.com/database/index.php?search=%{TOKEN}
URL" url http://malc0de.com/database/index.php?search=%{TOKEN}
"Malware Domain List Host" host
'http://www.malwaredomainlist.com/mdl.php?&colsearch=All&quantity=50&search='%{TOKEN}
"Malware Domain List IP" ip
'http://www.malwaredomainlist.com/mdl.php?&colsearch=All&quantity=50&search='%{TOKEN}
"MalwareZoo Hash" hash https://zoo.mlw.re/samples/%{TOKEN}
"McAfee TI Host" host https://www.mcafee.com/threat-intelligence/domain/default.aspx?domain=%
{TOKEN}
"McAfee TI IP" ip https://www.mcafee.com/threat-intelligence/ip/default.aspx?ip=%{TOKEN}
"McAfee TI URL" url https://www.mcafee.com/threat-intelligence/site/default.aspx?url=%{TOKEN}
"Mnemonic pDNS Host" host https://passivedns.mnemonic.no/search/%{TOKEN}
"MXToolbox Blacklist Domain" host
https://mxtoolbox.com/SuperTool.aspx?\&run=toolpage\&action=blacklist:%{TOKEN}
"MXToolbox Blacklist IP" ip
https://mxtoolbox.com/SuperTool.aspx?\&run=toolpage\&action=blacklist:%{TOKEN}
"RIPE IP" ip https://stat.ripe.net/%{TOKEN}
"SpamHaus domain" host https://www.spamhaus.org/query/domain/%{TOKEN}
"SpamHaus IP" ip https://www.spamhaus.org/query/ip/%{TOKEN}
"StopForumSpam IP" ip http://www.stopforumspam.com/ipcheck/%{TOKEN}
"Talos Intelligence Domain" host https://www.talosintelligence.com/reputation_
center/lookup?search=%{TOKEN}
"Talos Intelligence IP" ip https://www.talosintelligence.com/reputation_center/lookup?search=%
{TOKEN}
"Threat Crowd Domain" host https://www.threatcrowd.org/domain.php?domain=%{TOKEN}
"Threat Crowd Hash" hash https://www.threatcrowd.org/malware.php?md5=%{TOKEN}
"Threat Crowd IP" ip https://www.threatcrowd.org/ip.php?ip=%{TOKEN}
"ThreatExpert Hash" hash http://www.threatexpert.com/reports.aspx?find\=%{TOKEN}
67
Security Analytics Reference Guide
Security Analytics 8.1
"ThreatStream Anomali IP" ip https://ui.threatstream.com/search?status=active&value__re=.*%
{TOKEN}
"TotalHash
"TotalHash
"TotalHash
"TotalHash
Hash" hash https://totalhash.cymru.com/search/?hash:%{TOKEN}
Host" host https://totalhash.cymru.com/search/?dnsrr:%{TOKEN}
IP" ip https://totalhash.cymru.com/search/?ip:%{TOKEN}
URL" hash https://totalhash.cymru.com/search/?url:%{TOKEN}
"Twitter Search Term Domain" host 'https://twitter.com/search?f=realtime&q='%{TOKEN}
"Twitter Search Term IP" ip 'https://twitter.com/search?f=realtime&q='%{TOKEN}
"Twitter Search Term URL" url 'https://twitter.com/search?f=realtime&q='%{TOKEN}
"Unmask Parasites" url http://www.UnmaskParasites.com/security-report/?page=%{TOKEN}
"URL
"URL
"URL
"URL
"URL
Query Domain" host http://urlquery.net/search?q=%{TOKEN}
Query IP" ip http://urlquery.net/search?q=%{TOKEN}
Query URL" url http://urlquery.net/search?q=%{TOKEN}
Void Domain" host http://www.urlvoid.com/scan/%{TOKEN}
Void IP" ip http://www.urlvoid.com/ip/%{TOKEN}
"URLFind URL" url http://urlfind.org/?site=%{TOKEN}
"WatchGuard Domain" host http://www.reputationauthority.org/domain_lookup.php?ip=%{TOKEN}
"WatchGuard IP" ip http://www.reputationauthority.org/lookup.php?ip=%{TOKEN}
"Zeus
"Zeus
"Zeus
"Zeus
Tracker
Tracker
Tracker
Tracker
Domain" host https://zeustracker.abuse.ch/monitor.php?host=%{TOKEN}
Hash" hash 'https://zeustracker.abuse.ch/monitor.php?show=config&hash='%{TOKEN}
IP" ip https://zeustracker.abuse.ch/monitor.php?ipaddress=%{TOKEN}
URL" url https://zeustracker.abuse.ch/monitor.php?host=%{TOKEN}
scm sessions
Use the scm sessions command to manage user sessions with respect to the session length and expiration. To
manage user authentication use scm tally.
syntax
scm sessions <subcommand> [-h] [-v] [-q] <user>
subcommands
summary
Shows the status of a user session such as expiration times and time remaining on the
session. Valid values for <user>:
<id>
<username>
<null>
clear
Specify the user's ID.
Specify the username.
Omit <user> to see all sessions.
Clears the user's session from the session DB. This action will log out the user. Valid values for
<user>:
<id>
<username>
Specify the user's ID.
Specify the username.
68
Security Analytics Reference Guide
Security Analytics 8.1
examples
[root@hostname ~] scm sessions summary
Displays all of the users in the session DB. A "No user" entry indicates one or more unsuccessful login attempts.
[root@hostname ~] scm sessions summary 35
Displays session information for user ID 35.
[root@hostname ~] scm sessions clear web_user
Clears all web_user sessions from the session DB and logs web_user out.
scm solera_acl elevate
Restores or converts an existing user account on the web UI to admin status.
syntax
scm solera_acl elevate <username>
Places the user in a new group with administrator privileges called elevated-admin-<YYYY-MM-DD>T<hh:ii:ss>.
Log on with this account using its original password, and then you can edit the account and the group in Menu
> Settings > Users and Groups to restore the original permissions.
scm tally
Enables user accounts, clears user API keys. To manage user sessions use scm sessions.
Find the equivalent settings on the Menu
> Settings > Users and Groups and
Settings > Security pages of the web interface.
syntax
scm tally <subcommand> [-h] [-v] [-q] <username>
69
Security Analytics Reference Guide
Security Analytics 8.1
subcommands
status
Shows the status of the user account as follows:
User ID
ID number of the user account
User
Full context of username
Attempts
Current number of unsuccessful authentication
attempts
Auth Limit
User-defined* login-attempt limit
Lockout Interval
User-defined* lockout interval
Session Limit
User-defined* session limit
Session Count
Number of concurrent sessions for this user
Lockout Expires
Number of seconds before the current lockout
expires
clear_
auths
Clears the number of unsuccessful login attempts
clear_keys
Zeroizes the user's API key
* Defined on the Menu
> Settings > Security page of the web interface.
examples
[root@hostname ~] scm tally clear_auths admin
Clears the number of unsuccessful login attempts for the admin account, which then enables the account if it
has been locked out.
[root@hostname ~] scm tally clear_keys admin
Zeroizes the API key for the admin account. To generate a new key for admin, open the web interface and select
[Account Name] > Account Settings and click Reset API Key.
70
Security Analytics Reference Guide
Security Analytics 8.1
Web Services APIs
Symantec Security Analytics provides a robust set of web APIs:
n
"API Changes in Security Analytics 8.1.x" on page 75
n
"Using the APIs" on page 424 — Detailed examples of how to implement the APIs
Install and Test the SoleraConnector Class
71
Session-Based APIs
73
Pivot to Summary Page
73
Single Time-Value Configuration
74
If you are running an API on a CMC and need the API to affect one or more
connected sensors, you must specify at least one sensor ID, using the appliances
attribute in the URL:
/favorites/active?appliances=1
/deepsee_reports/report?appliances=1,4,7
If the API has an additional applianceIds or appliances attribute, you must use that
attribute to specify which sensors are to be affected by the API and you must
specify at least one sensor in the URL. The sensor specified in the URL does not
need to be the same as the sensor(s) that are specified in the API's
applianceIds/appliances attribute.
s.callAPI(
"POST",
"/favorites/delete?appliances=1", {
'selectedIds': [<uuid1>, <uuid2>]
'applianceIds': [5,6,9]
})
Install and Test the SoleraConnector Class
To test the Web APIs, obtain the connector class and command-line test files from the online help files, which are
available as follows:
n
On the Security Analytics web interface, select Menu
> Settings > Help, and select your language
under Online Help Files. In the left pane select Reference > Web APIs.
n
On the Security Analytics documentation page
(support.symantec.com/us/en/documentation.1145515.html) select Administration Guide for
Document Type and then select the latest Security Analytics WebGuide.
71
Security Analytics Reference Guide
Security Analytics 8.1
1. In the left-side menu of the help files, select Reference > Web APIs. Under Install and Test the
SoleraConnector Class, download either the PHP or Python files, as desired.
2. Open the PHP or Python links, save the file to your workstation, and remove the TXT extension:
n
SoleraConnector.php
n
SoleraConnector.py
n
commandLineTest.php
n
commandLineTest.py
3. Verify that the files are on a device that supports PHP 5.3 or Python 2 or 3.
n
PHP requires php-curl to be installed.
n
Python requires python-requests to be installed.
n
Clients must be running OpenSSL 1.0.1 or later for the Python scripts. Some versions of Mac OS X
run a non-supported version of OpenSSL and must be updated:
o
To see which version of OpenSSL is on your client, run
python -c "import ssl;print(ssl.OPENSSL_VERSION)"
o
To update Python and OpenSSL on OS X, run
brew update
brew install openssl
brew install python --with-brewed-openssl
4. Open commandLineTest and edit the top line as follows:
SoleraConnector("admin_account","API_key", "IP_address");
where:
o
admin_account is an administrative-level account name.
o
API_key is the API key generated on the web interface under [Account Name
Account Settings.
o
IP_address is the IP address of bond0. Enclose an IPv6 address in [ square brackets ].
]>
5. On the next line, input the parameters of the API:
PHP
var_dump($connector->callAPI('method', 'API_path', [array('parameter' => 'value')]));
Python
print(s.callAPI("method", "API_path", {"parameter": "value"}))
where:
o
method is GET or POST
o
API_path is the API path
o
parameter and value are an array of parameters and their values, if any
72
Security Analytics Reference Guide
Security Analytics 8.1
6. Save the file.
7. Run the test file:
PHP
php commandLineTest.php
Python
python CommandLineTest.py
API Example
The following examples demonstrate how to use the download artifacts API .
PHP
var_dump($connector->callAPI('GET','/artifacts/download', array('ids' => '5', 'type' => 'wav',
'mode' => 'synth_audio')));
Python
print(s.callAPI("GET","/artifacts/download", {'ids':'5', 'type':'wav', 'mode':'synth_audio'}))
Session-Based APIs
To reduce API latency, you can configure API authentication to be session-based.
1. Edit the /gui/dsweb/Config/core.php file. Scroll down to this section:
Configure::write('pbkdf2', array(
'saltLength' => 128, //length of the cipher key in bits
'minIterations' => 100000, //minimum is 1
'minMilliseconds' => 200
));
2. Change minMilliseconds to minIterations and then save and exit.
3. Reset the API user’s token by logging in to the web UI as the API user and then selecting [Account Name] >
Account Settings and clicking Reset API Key .
Pivot to Summary Page
To call up the Menu
> Analyze > Summary view from another program, use the pivot URL:
https://<appliance>/deepsee_reports#pathString=/timespan/<timespan>[/<attribute>/<value>]
Where <attribute> is one of the following:
ipv4_address
ipv6_address
ipv4_initiator
ipv6_initiator
ipv4_responder
ipv6_responder
tcp_responder
tcp_initiator
For every host that pivots into the Summary page, add the host to the Allowed Referrers list on Settings > Web
Interface.
73
Security Analytics Reference Guide
Security Analytics 8.1
Single Time-Value Configuration
If desired, you can set <timespan> to a single time-value. Use the time prefix and suffix to automatically set a
timespan relative to that single time-value.
1. On the web interface, select [Account Name]
> Preferences.
2. For Time Prefix, specify the number of seconds that will be subtracted from the single time-value to
calculate the start time.
3. For Time Suffix, specify the number of seconds that will be added to the single time-value to calculate
the end time.
4. Click Save.
The time prefix and suffix are supported by any API request that accepts a path
string: PCAP downloads, pivot to summary page, reports, and extractions.
example
n
Time Prefix = 900
n
Time Suffix = 900
https://<appliance>/deepsee_reports#pathString=/timespan/2019-05-22T13:00:00/ipv4_
address/198.51.100.88
This command displays the Menu
> Analyze > Summary page with the timespan set for May 22, 2019 from
12:45–1:15 p.m. and with ipv4_address=198.51.100.88 in the primary filter bar.
74
Security Analytics Reference Guide
Security Analytics 8.1
API Changes in Security Analytics 8.1.x
The Using the APIs page contains detailed instructions for using APIs in sequence to download various data
types from the appliance.
n
Outputs have been added to the GET "Capture APIs" on page 116.
New APIs
The APIs in this list represent new features in Security Analytics 8.1.x.
n
GET: /settings/icdx_<x> New Metadata APIs page
n
GET: /captures/get_billable
n
POST: /deepsee/delete_map
n
POST: /deepsee/save_map
n
GET: /job_queue/job_queue
n
GET: /job_queue/count
n
GET: /job_queue/download
n
GET: /job_queue/filter_options
n
POST: /job_queue/delete
n
GET: /settings/cmc_first
n
GET: /settings/extractor_enable_proxy_data_reconstruction
n
POST: /settings/extractor_enable_proxy_data_reconstruction
n
GET: /web_interface/allowed_hosts
n
POST: /web_interface/allowed_hosts
The APIs in this list are newly available:
n
GET: /shyft/field_data
Modified APIs
The APIs in this list have been modified in Security Analytics 8.1.x.
n
GET: /artifacts/artifacts — Reconfigured the state machine. See Extractions API Changes to see how
the output has been affected.
n
POST: /artifacts/save — Was POST: /artifacts/background.
75
Security Analytics Reference Guide
Security Analytics 8.1
n
POST: /actions/save — Added the discard packets value for type and ICDx and Splunk Phantom offbox values
n
POST: /cmc_settings/add_appliance — Added mssfix (MTU) attribute
n
POST: /cmc_settings/cmc_client_toggle — This API has been removed
n
POST: /cmc_settings/edit_appliance — Added mssfix (MTU) attribute
n
POST: /deepsee/save_view — Removed the type parameter; to save geolocation map views use POST:
/deepsee/save_map
n
GET: /integration_providers/providers — Added the threatexplorer value for edit_type
n
POST: /settings/logging_settings — Added parameters for the ICDx remote-notification and Splunk
Phantom servers as well as SNMP entries for an additional read-only username and encryption and
privacy passwords.
n
POST: /users/setting — Added the dark parameter
n
POST: /integration_providers/yara_restore — Was GET.
76
Security Analytics Reference Guide
Security Analytics 8.1
Advanced API Queries
Use advanced queries to create nested primary filters that combine Boolean AND and OR functions with
multiple attributes.
These advanced queries for the primary filter are now available in the web UI. The
Advanced Filters on the Menu
> Analyze > Summary > [Reports | Extractions |
Geolocation] pages already support nested queries.
To create an advanced query, prepend all or any to an array that contains the arguments:
n
all = Boolean AND — All items in the array must match.
n
any = Boolean OR — At least one of the items in the array must match.
There is no limit to the number of nested arrays in a single advanced query.
Example Queries
The following examples represent the same logic:
Boolean
(application_id=http AND (mime_type~css OR filename~css))
Python
{
'all':[
'application_id=http',
'any':[
'mime_type~css',
'filename~css'
]
]
}
PHP
array(
'all' => array(
'application_id=http',
'any' => array(
'mime_type~css',
'filename~css'
)
)
)
Combining Different Namespaces
Each of the attributes occupies one of the following namespaces: flows, groups, packets, verdicts. Attributes
that are in different namespaces cannot be combined in the same advanced query. However, separate queries
77
Security Analytics Reference Guide
Security Analytics 8.1
can be created for each namespace and then combined into a single array. The operator between each
namespace query is always AND. Consult the Metadata Settings tables to see the namespace for each attribute.
The following example contains attributes from two different namespaces: groups and flows.
Boolean example
(md5_hash=AA AND md5_hash=BB) AND (application_id=http AND (mime_type~pdf OR mime_type~bzip2 OR
filename~pkg OR filename~mov))
Python example
{
{
'all':[
'md5_hash=AA',
'md5_hash=BB'
]
},
{
'all':[
'application_id=http'
],
{
{
'any':[
'mime_type~pdf',
'mime_type~bzip2',
'filename~pkg',
'filename~mov'
]
}
}
}
}
}
PHP example
array(
array(
'all' => array(
'md5_hash=AA',
'md5_hash=BB'
)
),
array(
'all' => array(
'application_id=http'
)
),
array(
'any' => array(
'mime_type~pdf',
'mime_type~bzip2',
'filename~pkg',
'filename~mov'
)
)
)
78
Security Analytics Reference Guide
Security Analytics 8.1
Alerts APIs
Use rules to generate alerts.
Get alerts list
API Path
/alerts
Description
Retrieve a list of alerts with the most recent first
GUI Location
Menu
> Analyze > Alerts > List
Parameters
REQ
Format
Default
Valid Inputs
startDate
X
datetime
—
<YYYY-MM-DD>T<hh:ii:ss>
[+|-]<zz:zz>
Start date/time
endDate
X
datetime
—
<YYYY-MM-DD>T<hh:ii:ss>
[+|-]<zz:zz>
End date/time
page
integer
1
1–<n>
Page to retrieve; first page is 1
limit
integer
25
1–100
Number of items per page
direction
string
DESC
ASC | DESC
filters
array
—
<advanced filter for alerts>
PHP Example
callAPI('GET','/alerts',
array(
'startDate' => '2019-11-03T00:00:00-07:00',
'endDate' => '2019-11-03T23:59:59-07:00'
'page' => 10
'limit' => 25
'direction' => 'ASC'
'filters' => array(
'all' => array(
array(
'key' => 'destination_ip',
'comp' => '=',
'value' => '203.0.113.5'
)
array(
'any' => array(
array(
'key' => 'rule',
'comp' => '~',
'value' => 'local'
),
79
Description
Sort order
Advanced filter attributes
Security Analytics Reference Guide
Security Analytics 8.1
array(
'key' => 'score',
'comp' => '>',
'value' => 5
)
)
)
)
)
)
);
Python Example
s.callAPI("GET","/alerts", {
'startDate': '2019-11-03T00:00:00-07:00',
'endDate': '2019-11-03T23:59:59-07:00',
'page': 10,
'limit': 25,
'direction': 'ASC',
'filters': {
'all': [
{
'key':'destination_ip',
'comp':'=',
'value':'203.0.113.5'
}
],
{
'any': [
{
'key':'rule',
'comp':'~',
'value':'local'
},
{
'key':'score',
'comp':'>',
'value':5
}
]
}
}
}
)
Output
'paging': {'NotificationAlert': {'count': <integer>,
'current': <integer>,
'limit': <integer>,
'nextPage': [True|False],
'options': {'order': {'NotificationAlert.modified_date':
'desc'}},
'order': {'NotificationAlert.modified_date': 'desc'},
'page': <integer>,
'pageCount': <integer>,
'paramType': '<string>',
'prevPage': [True|False]}},
'result': {'pageCount': 255,
'rows': [{'action': '<rule name>',
'action_display': '<rule name>',
'action_type': <integer>,
'action_uuid': '<UUID>',
'appliance_id': [None|<integer>],
'description': '',
80
Security Analytics Reference Guide
Security Analytics 8.1
'destination_ip': '<ip>',
'destination_mac': '<mac>',
'destination_port': <port>,
'endpoint_providers': <integer>,
'favorite': '<indicator name>',
'favorite_action_uuid': '<UUID>',
'flow_id': <integer>,
'flow_start_time': <epoch>,
'flow_stop_time': <epoch>,
'hasCascadedHits': [True|False],
'hasResponse': [True|False],
'import_id': <integer>,
'importance': <integer>,
'match_criteria': '<open_parser_regex>',
'modified_date': <epoch>,
'name': '<string>',
'object_type': '<string>',
'source_ip': '<ip>',
'source_mac': '<mac>',
'source_port': <port>,
'time': <epoch>,
'user_id': <string>,
'username': <string>,
'uuid': '<UUID>',
'workflow_state': <integer>},
Get alerts timeline
API Path
/alerts/timeline_data
Description
Retrieve the alerts histogram
GUI Location
Alerts Management Dashboard
Parameters
REQ
filters
Format
Default
Valid Inputs
array
—
<advanced filter for alerts>
Description
Advanced filter
attributes
startDate
X
datetime
—
<YYYY-MM-DD hh:ii:ss>
[+|-]<zz:zz>
Start time
endDate
X
datetime
—
<YYYY-MM-DD hh:ii:ss>
[+|-]<zz:zz>
End time
PHP Example
callAPI('GET','/alerts/timeline_data',
array(
'startDate' => '2019-11-03 10:25:00-07:00',
'endDate' => '2019-11-03 10:40:00-07:00'
)
);
81
Security Analytics Reference Guide
Security Analytics 8.1
Python Example
s.callAPI("GET","/alerts/timeline_data",{
'startDate':'2019-11-03 10:25:00-07:00',
'endDate':'2019-11-03 10:40:00-07:00'
}
)
Output
'result': {'rows': [{'data': [], 'time': <epoch>},
{'data': [], 'time': <epoch>},
...
{'data': [], 'time': <epoch>},
{'data': [], 'time': <epoch>},
{'data': [{'bucket': 18,
'count': 22,
'higher': '<epoch>',
'importance': 2,
'lower': '<epoch>',
'time': '<epoch>'},
{'bucket': 18,
'count': 1,
'higher': '<epoch>',
'importance': 3,
'lower': '<epoch>',
'time': '<epoch>'}],
'time': <epoch>},
{'data': [{'bucket': 19,
'count': 15,
'higher': '<epoch>',
'importance': 1,
'lower': '<epoch>',
'time': '<epoch>'},
{'bucket': 19,
'count': 17,
'higher': '<epoch>',
'importance': 2,
'lower': '<epoch>',
'time': '<epoch>'}],
'time': <epoch>},
{'data': [], 'time': <epoch>},
{'data': [], 'time': <epoch>},
...
{'data': [], 'time': <epoch>},
{'data': [], 'time': <epoch>}]},
'resultCode': 'API_SUCCESS_CODE',
Get alert counts
API Path
/notifications/alerts
Description
Retrieve the number of alerts for anomalies (1), critical (2), and warning (3)
GUI Location
Alerts Notification
82
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
None
PHP Example
callAPI('GET','/notifications/alerts');
Python Example
s.callAPI("GET","/notifications/alerts")
Output
'result': {'1': 0, '2': 57, '3': 53},
Get webtop data
API Path
/notifications/webtop
Description
Retrieve system utilization data
GUI Location
System Utilization
Parameters
REQ
cached
Format
Default
Boolean
false
Valid Inputs
Description
true | false
Whether to
retrieve data
from cache
PHP Example
callAPI('GET','/notifications/webtop');
Python Example
s.callAPI("GET","/notifications/webtop")
Output
'result': {'cpu': [{'id': 0, 'title': 'All', 'usage': <floating>},
{'id': 1, 'title': 'Core 1', 'usage': <floating>},
{'id': 2, 'title': 'Core 2', 'usage': <floating>},
{'id': 3, 'title': 'Core 3', 'usage': <floating>},
{'id': 4, 'title': 'Core 4', 'usage': <floating>}],
'malwareAppliances': [],
'memory': {'free': <integer>,
'percent_used': <floating>,
'total': <integer>,
'used': <integer>},
'time': 1536877964.5899,
'uptime': {'idle': 1136103.12, 'total': 97192.04}},
'resultCode': 'API_SUCCESS_CODE',
83
Security Analytics Reference Guide
Security Analytics 8.1
Get alert summary
API Path
/alerts/summary_data
Description
Retrieve a summary of the alerts
GUI Location
Menu
> Analyze > Alerts > Summary
Parameters
REQ
Format
Default
Valid Inputs
Description
filters
array
—
<advanced filter for alerts>
direction
string
DESC
ASC | DESC
page
integer
1
1–<n>
Page number; first page is 1
limit
integer
25
1–100
Number of items per page
Advanced filter attributes
Sort order
startDate
X
datetime
—
<YYYY-MM-DD hh:ii:ss>
[+|-]<zz:zz>
Start time
endDate
X
datetime
—
<YYYY-MM-DD hh:ii:ss>
[+|-]<zz:zz>
End time
array
()
groupBy
integration_provider |
Tables on the Alerts >
importance | action | favorite | Summary page. Two
source_ip | destination_ip |
attributes may be specified,
type | score
such as favorite (indicator)
with action (rule).
PHP Example
callAPI('GET','/alerts/summary_data',
array(
'filters' => array(
'all' => array(
array(
'key' => 'destination_ip',
'comp' => '=',
'value' => '203.0.113.5'
)
)
array(
'any' => array(
array(
'key' => 'rule',
'comp' => '~',
'value' => 'local'
),
array(
'key' => 'score',
'comp' => '>',
84
Security Analytics Reference Guide
Security Analytics 8.1
'value' => 5
)
)
)
)
)
'page' => 10
'limit' => 20
'direction' => 'ASC'
'groupBy' => array(
'score',
'integration_provider'
)
'startDate' => '2019-11-03T00:00:00-07:00',
'endDate' => '2019-11-03T23:59:59-07:00'
)
);
Python Example
s.callAPI("GET","/alerts/summary_data", {
'filters': {
'all': [
{
'key':'destination_ip',
'comp':'=',
'value':'203.0.113.5'
}
],
{
'any': [
{
'key':'rule',
'comp':'~',
'value':'local'
},
{
'key':'score',
'comp':'>',
'value':5
}
]
}
}
'page': 10
'limit': 20
'direction': 'ASC'
'groupBy': [
'score',
'integration_provider'
],
'startDate': '2019-11-03T00:00:00-07:00',
'endDate': '2019-11-03T23:59:59-07:00'
}
)
Output
'paging': {'NotificationAlert': {'count': <integer>,
'current': <integer>,
'limit': <integer>,
'nextPage': [True|False],
'options': {'order': {'<groupBy1>.<groupBy2>': '
[ASC|DESC]',
'count': '[ASC|DESC]'}},
'order': {'<groupBy1>.<groupBy2>': '[ASC|DESC]',
'count': '[ASC|DESC]'},
85
Security Analytics Reference Guide
Security Analytics 8.1
'page': 1,
'pageCount': <integer>,
'paramType': '<string>',
'prevPage': [True|False]}},
'result': {'pageCount': <integer>,
'rows': [{'count': 1,
'<groupBy1>': '<value1>',
'<groupBy2>': '<value2>'},
{'count': 1,
'<groupBy1>': '<value1>',
'<groupBy2>': '<value2>'},
...
{'count': 1,
'<groupBy1>': '<value1>',
'<groupBy2>': '<value2>'},
}],
'totalAlertsCount': <integer>},
'resultCode': 'API_SUCCESS_CODE',
Get notification list
API Path
/notifications/notifications
Description
Retrieve a list of system notifications
GUI Location
System Notifications
Parameters
None
PHP Example
callAPI('GET','/notifications/notifications');
Python Example
s.callAPI("GET","/notifications/notifications")
Output
'result': {'amount': <integer>,
'notifications': [{'amount': <integer>,
'appliance_id': [None|<integer>],
'foreign_id': <integer>,
'foreign_uuid': [None|<UUID>],
'hidden': [True|False],
'id': <integer>,
'importance': <integer>,
'importance_level': <integer>,
'insert_time': <epoch>,
'title': '<string>'
'<string>',
'type': <integer>,
'user_id': <integer>}]},
'resultCode': 'API_SUCCESS_CODE',
86
Security Analytics Reference Guide
Security Analytics 8.1
Set alert state for a selected alert
API Path
/alerts/update
Description
Set the workflow state of selected alerts
GUI Location
Menu
> Analyze > Alerts > List > Actions > Set State
Output
array
Parameters
REQ
Format
Default
alerts
X
array
—
<advanced filter
for alerts>
alert_uuid
X
UUID
—
<GET: /alerts>
workflow_state
X
integer
0
0 | 10 | 20 | 30 |
40 | 50
PHP Example
callAPI('POST','/alerts/update',
array(
'alerts' => array(
'uuid' => '<UUID>',
'workflow_state' => 10
)
)
);
Python Example
s.callAPI("POST","/alerts/update", {
'alerts': {
'uuid': '<UUID>',
'workflow_state': 10
}
87
Valid Inputs
Description
Array containing alert_
uuid and workflow_state
UUID of selected alert
Workflow state:
n
0 — Unassigned
n
10 — Assigned
n
20 — In progress
n
30 — On hold
n
40 — Resolved
n
50 — Closed
Security Analytics Reference Guide
Security Analytics 8.1
}
)
Set alert state for a range of alerts
API Path
/alerts/update
Description
Set the workflow state or owner for a range of alerts
GUI Location
Menu
> Analyze > Alerts > List > Actions > Set State
Output
array
Parameters
REQ
Format Default
Valid Inputs
workflow_state | user_id
Description
fieldName
X
string
—
fieldValue
X
integer
—
startDate
X
datetime
—
<YYYY-MM-DD> <hh:ii:ss>[+|-]<zz:zz>
Start
date/time
endDate
X
datetime
—
<YYYY-MM-DD> <hh:ii:ss>[+|-]<zz:zz>
End
date/time
Attribute to
change
0 | 10 | 20 | 30 | 40 | 50 | <GET: /settings/users> Value for
the attribute
PHP Example
callAPI('POST','/alerts/update_field',
array(
'fieldName' => 'workflow_state',
'fieldValue' => 10,
'startDate' => '2019-04-28 11:28:25-07:00',
'endDate' => '2019-05-02 11:28:25-07:00'
)
);
Python Example
s.callAPI("POST","/alerts/update_field", {
'fieldName': 'workflow_state',
'fieldValue': 10,
'startDate': '2019-04-28 11:28:25-07:00',
'endDate': '2019-05-02 11:28:25-07:00'
}
)
88
Security Analytics Reference Guide
Security Analytics 8.1
Clear alerts
API Path
/alerts/clear_alerts
Description
Clear some or all alerts that have been selected by the timespan and advanced filters OR by the check boxes.
GUI Location
Menu
> Analyze > Alerts > List > Actions > Delete
Output
array
Parameters
REQ
Format
Default
Valid Inputs
array
—
<advanced filter for alerts>
Advanced filter
attributes
startDate
datetime
—
<YYYY-MM-DD>T<hh:ii:ss>
[+|-]<zz:zz>
Start date/time
endDate
datetime
—
<YYYY-MM-DD>T<hh:ii:ss>
[+|-]<zz:zz>
End date/time
array
—
<GET: /alerts>
filters
selectedIDs
PHP Example 1
Clear alerts that are selected by the filter and timespan
callAPI('POST','/alerts/clear_alerts',
array(
'filters' => array(
'all' => array(
array(
'key' => 'destination_ip',
'comp' => '=',
'value' => '203.0.113.5'
)
)
),
'startDate' => '2019-11-03T00:00:00-07:00',
'endDate' => '2019-11-03T23:59:59-07:00'
)
);
Python Example 1
Clear alerts that are selected by the filter and timespan
89
Description
UUIDs of the alerts to
delete; use instead of
timespan and filter
Security Analytics Reference Guide
Security Analytics 8.1
s.callAPI("POST","/alerts/clear_alerts", {
'filters': {
'all': {
{
'key': 'destination_ip',
'comp': '=',
'value': '203.0.113.5'
}
}
},
'startDate': '2019-11-03T00:00:00-07:00',
'endDate': '2019-11-03T23:59:59-07:00'
}
)
PHP Example 2
Clear alerts that are selected by check boxes
callAPI('POST','/alerts/clear_alerts',
array(
'selectedIDs' => array(
<UUID>,
<UUID>,
<UUID>,
<UUID>
)
)
);
Python Example 2
Clear alerts that are selected by check boxes
s.callAPI("POST","/alerts/clear_alerts", {
'selectedIDs': [
<UUID>,
<UUID>,
<UUID>,
<UUID>
]
}
)
90
Security Analytics Reference Guide
Security Analytics 8.1
Anomalies APIs
Get anomalies
API Path
/anomalies
Description
Retrieve a list of anomalies with the highest score first
GUI Location
Menu
> Analyze > Anomalies > List
Parameters
REQ Format
Default
Valid Inputs
Description
page
integer
1
1– <n>
Page to retrieve; first page is 1
limit
integer
25
1–100
Number of items per page
sort
string
score
score | create_
time
direction
string
DESC
ASC | DESC
filters
array
—
<advanced filter
for anomalies>
timeRange
array
—
<timespan date
array>
Time of Detection timespan filter
anomalyAnalysisWindow
array
—
<timespan date
array>
Analysis Window timespan filter;
if you also use the timeRange
filter, anomalyAnalysisWindow
should contain timeRange.
Python Example
s.callAPI("GET","/anomalies", {
'filters': {
'all': {
{
'key': 'function',
'comp': '~',
'value': 'count'
},
{
'any': {
{
'key': 'initiator_ip',
'comp': '=',
'value': '203.0.113.5'
},
{
'key': 'field',
91
Sort-by column; corresponds to
sortable column headings in
the Anomalies List table.
Sort order
Advanced filter attributes
Security Analytics Reference Guide
Security Analytics 8.1
'comp': '~',
'value': 'port'
}
}
}
}
},
'timeRange': {
'start': '2019-11-03T05:30:00+01:00',
'end': '2019-11-03T05:40:00+01:00'
},
'anomalyAnalysisWindow': {
'start': '2019-11-03T05:10:00+01:00',
'end': '2019-11-03T05:40:00+01:00'
}
}
}
PHP Example
callAPI('GET','/anomalies',
array(
'filters' => array(
'all' => array(
array(
'key' => 'function',
'comp' => '~',
'value' => 'count'
),
array(
'any' => array(
array(
'key' => 'initiator_ip',
'comp' => '=',
'value' => '203.0.113.5'
),
array(
'key' => 'field',
'comp' => '~',
'value' => 'port'
)
)
)
)
),
'timeRange' => array(
'start' => '2019-11-03T05:30:00+01:00',
'end' => '2019-11-03T05:40:00+01:00'
),
'anomalyAnalysisWindow' => array(
'start' => '2019-11-03T05:10:00+01:00',
'end' => '2019-11-03T05:40:00+01:00'
)
)
);
Output
'paging': {'AnomalyAlert': {'count': <integer>,
'current': <integer>,
'limit': <integer>,
'nextPage': [True|False],
'options': [],
'order': 'score [ASC|DESC],over_field_value '
'desc,create_time desc',
'page': <integer>,
'pageCount': <integer>,
92
Security Analytics Reference Guide
Security Analytics 8.1
'paramType': 'named',
'prevPage': [True|False]}},
'result': {'pageCount': <integer>,
'recordCount': <integer>,
'rows': [{'actual': '<floating>+06',
'actual_probability': '0',
'anomaly_score': '<floating>',
'appliance_id': None,
'by_field_name': '',
'by_field_value': '',
'create_time': <epoch>,
'end_time': <epoch>,
'field_name': '<string>',
'field_value': '',
'flags': 0,
'function': '<string>',
'gauge_path': '["timespan=<YYYY-MM-DD>T<hh:ii:ss>.000+0000_<YYYY-MMDD>T<hh:ii:ss>.000+0000","<field1>=<value1>","<field2>=<value2>"]',
'id': <integer>,
'old_id': None,
'over_field_name': '<string>',
'over_field_value': '<ip>',
'partition_field_name': '<string>',
'partition_field_value': '<string>',
'probability': '<floating>',
'score': <integer>,
'start_time': <epoch>,
'type': 0,
'typical': '<integer>'},
...
'resultCode': 'API_SUCCESS_CODE',
Get anomaly count
API Path
/anomalies/count
Description
Retrieve the number of anomaly records within the specified timespans
GUI Location
Top navigation, Alerts box
Parameters
REQ Format
Default
Valid Inputs
Description
filters
array
—
<advanced filter for
anomalies>
Advanced filter attributes
timeRange
array
—
<timespan date array>
Time of Detection
timespan filter
93
Security Analytics Reference Guide
Security Analytics 8.1
REQ Format
anomalyAnalysisWindow
array
Default
—
Valid Inputs
<timespan date array>
Python Example
s.callAPI("GET","/anomalies/count", {
'filters': {
'all': {
{
'key': 'function',
'comp': '~',
'value': 'count'
},
{
'any': {
{
'key': 'initiator_ip',
'comp': '=',
'value': '203.0.113.5'
},
{
'key': 'field',
'comp': '~',
'value': 'port'
}
}
}
}
},
'timeRange': {
'start': '2019-11-03T05:30:00+01:00',
'end': '2019-11-03T05:40:00+01:00'
},
'anomalyAnalysisWindow': {
'start': '2019-11-03T05:10:00+01:00',
'end': '2019-11-03T05:40:00+01:00'
}
}
}
PHP Example
callAPI('GET','/anomalies/count',
array(
'filters' => array(
'all' => array(
array(
'key' => 'function',
'comp' => '~',
'value' => 'count',
),
array(
'any' => array(
array(
'key' => 'initiator_ip',
'comp' => '=',
'value' => '203.0.113.5'
)
array(
94
Description
Analysis Window
timespan filter; if you also
use the timeRange filter,
anomalyAnalysisWindow
should contain
timeRange.
Security Analytics Reference Guide
Security Analytics 8.1
'key' => 'field',
'comp' => '~',
'value' => 'port'
)
)
)
)
),
'timeRange' => array(
'start' => '2019-11-03T05:30:00+01:00',
'end' => '2019-11-03T05:40:00+01:00'
),
'anomalyAnalysisWindow' => array(
'start' => '2019-11-03T05:10:00+01:00',
'end' => '2019-11-03T05:40:00+01:00'
)
)
);
Output
'result': {'Anomalies': {'count': <integer>}},
'resultCode': 'API_SUCCESS_CODE',
Get summary of anomalies
API Path
/anomalies/summary_data
Description
Retrieve anomalies, sorted by the tables displayed on the Anomalies Summary page
GUI Location
Menu
> Analyze > Anomalies > Summary
Parameters
REQ
Format
Default
Valid Inputs
Description
page
integer
1
1– <n>
Page to retrieve; first page is 1
limit
integer
25
1–100
Number of items per page
sort
string
count
<anomaly
summary
groups>
direction
string
DESC
ASC | DESC
Sort order
filters
array
—
<advanced
filter for
anomalies>
Advanced filter attributes
array
—
<anomaly
summary
groups>
groupBy
X
95
Sort-by column; corresponds to
sortable column headings in the
Anomalies Summary tables
Summary groups on the Anomalies >
Summary page
Security Analytics Reference Guide
Security Analytics 8.1
REQ
timeRange
anomalyAnalysisWindow
Format
Default
Valid Inputs
Description
array
—
<timespan
date array>
Time of Detection timespan filter
array
—
<timespan
date array>
Analysis Window timespan filter; if
you also use the timeRange filter,
anomalyAnalysisWindow should
contain timeRange.
Python Example
callAPI("GET","/anomalies/summary_data", {
'filters': {
'all': {
{
'key': 'function',
'comp': '~',
'value': 'count'
},
{
'any': {
{
'key': 'initiator_ip',
'comp': '=',
'value': '203.0.113.5'
}
{
'key': 'field',
'comp': '~',
'value': 'port'
}
}
}
}
},
'groupBy': [
'applications',
'initiator_ip'
],
'timeRange': {
'start': '2019-11-03T05:30:00+01:00',
'end': '2019-11-03T05:40:00+01:00'
},
'anomalyAnalysisWindow': {
'start' => '2019-11-03T05:10:00+01:00',
'end' => '2019-11-03T05:40:00+01:00'
}
}
}
PHP Example
callAPI('GET','/anomalies/summary_data',
array(
'filters' => array(
'all' => array(
array(
'key' => 'function',
'comp' => '~',
'value' => 'count'
),
array(
'any' => array(
array(
96
Security Analytics Reference Guide
Security Analytics 8.1
'key' => 'initiator_ip',
'comp' => '=',
'value' => '203.0.113.5'
)
array(
'key' => 'field',
'comp' => '~',
'value' => 'port'
)
)
)
)
),
'groupBy' => array(
'applications',
'initiator_ip'
),
'timeRange' => array(
'start' => '2019-11-03T05:30:00+01:00',
'end' => '2019-11-03T05:40:00+01:00'
),
'anomalyAnalysisWindow' => array(
'start' => '2019-11-03T05:10:00+01:00',
'end' => '2019-11-03T05:40:00+01:00'
)
)
);
Output
'paging': {'AnomalyAlert': {'count': <integer>,
'current': <integer>,
'limit': <integer>,
'nextPage': [True|False],
'options': [],
'order': {'<group1>': 'ASC',
'count': 'DESC',
'<groupN>': 'ASC'},
'page': <integer>,
'pageCount': <integer>,
'paramType': 'named',
'prevPage': [True|False]}},
'result': {'pageCount': <integer>,
'recordCount': <integer>,
'rows': [{'<group1>': '<value1>',
'count': 1,
'<groupN>': '<valueN>'},
...
{'<group1>': '<value1>',
'count': 1,
'<groupN>': '<valueN>'}]},
'resultCode': 'API_SUCCESS_CODE',
Clear anomalies
API Path
/anomalies/delete_anomalies
Description
Clear some or all anomalies that have been selected by the timespan and advanced filters. These anomalies are
cleared from the appliance as well as from the GUI display.
97
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
Menu
> Analyze > Anomalies > List > Clear button
Output
array
Parameters
REQ
Format
Default
Valid Inputs
Description
filters
array
—
<advanced filter for
anomalies>
timeRange
array
—
<timespan date array> Time of Detection timespan filter
array
—
<timespan date array> Analysis Window timespan filter;
if you also use the timeRange
filter, anomalyAnalysisWindow
should contain timeRange.
anomalyAnalysisWindow
Python Example
callAPI("POST","/anomalies/delete_anomalies", {
'filters': {
'all': {
{
'key': 'function',
'comp': '~',
'value': 'count'
},
{
'any': {
{
'key': 'initiator_ip',
'comp': '=',
'value': '203.0.113.5'
}
{
'key': 'field',
'comp': '~',
'value': 'port'
}
}
}
}
},
'timeRange': {
'start: '2019-11-03T05:30:00+01:00',
'end': '2019-11-03T05:40:00+01:00'
},
'anomalyAnalysisWindow': {
'start': '2019-11-03T05:10:00+01:00',
'end': '2019-11-03T05:40:00+01:00'
}
}
}
PHP Example
callAPI('POST','/anomalies/delete_anomalies',
array(
'filters' => array(
98
Advanced filter attributes
Security Analytics Reference Guide
Security Analytics 8.1
'all' => array(
array(
'key' => 'function',
'comp' => '~',
'value' => 'count'
),
array(
'any' => array(
array(
'key' => 'initiator_ip',
'comp' => '=',
'value' => '203.0.113.5'
)
array(
'key' => 'field',
'comp' => '~',
'value' => 'port'
)
)
)
)
),
'timeRange' => array(
'start' => '2019-11-03T05:30:00+01:00',
'end' => '2019-11-03T05:40:00+01:00'
),
'anomalyAnalysisWindow' => array(
'start' => '2019-11-03T05:10:00+01:00',
'end' => '2019-11-03T05:40:00+01:00'
)
)
);
99
Security Analytics Reference Guide
Security Analytics 8.1
Authentication APIs
These APIs correspond to the functions on the Authentication Settings page. Also see the "User Account APIs" on
page 386.
Get LDAP settings
API Path
/settings/ldap
Description
Retrieve LDAP server settings from /etc/ldap.conf
GUI Location
Menu
> Settings > Authentication
Parameters
None
Example
callAPI('GET','/settings/ldap');
Output
{'errors': [],
'messages': [],
'paging': [],
'result': {'SystemSetting': {'ldap_base': 'dc=example,dc=com',
'ldap_bind_dn': '<string>',
'ldap_bind_policy': 'soft',
'ldap_cred_grp_bind': True,
'ldap_enabled': 1,
'ldap_gecos': '<string>',
'ldap_gid_number': '<string>',
'ldap_group_naming_attribute': 'cn',
'ldap_group_object_class': '<string>',
'ldap_home_directory': '<string>',
'ldap_login_name': '<string>',
'ldap_login_shell': '<string>',
'ldap_pam_filter': 'objectclass=<user object class>',
'ldap_pam_login': '<login name attribute>',
'ldap_pam_member': '<group membership attribute>',
'ldap_pam_password_change': '<string>',
'ldap_passwd_encrypt': 'yes',
'ldap_port': 636,
'ldap_sasl_secprops': 'maxssf=0',
'ldap_schema': 'user_defined',
'ldap_scope': 'sub',
100
Security Analytics Reference Guide
Security Analytics 8.1
'ldap_server': '<hostname>',
'ldap_shadow_object_class': '<string>',
'ldap_tls_check_peer': True,
'ldap_uid_number': '<string>',
'ldap_unique_member': '<group membership attribute>',
'ldap_uri': 'ldaps://<hostname>:636',
'ldap_use_ssl': 'on',
'ldap_user_object_class': '<string>',
'ldap_user_password': '<string>',
'ldap_version': '3'}},
'resultCode': 'API_SUCCESS_CODE',
'validationErrors': {'Meta': [],
'Setting': [],
'SystemSetting': [],
'res': []}}
Discover LDAP settings
API Path
/settings/ldap_discover
Description
Initiate LDAP discovery
GUI Location
Menu
> Settings > Authentication
Output
integer
Parameters
domain
REQ
Format
Default
Valid Inputs
X
string
—
<FQDN>
Example
callAPI('GET','/settings/ldap_discover',
array(
'domain' => 'ldap.company.com'
)
);
Get LDAP auto-discovery flag state
API Path
/settings/get_ldap_discover_flag
101
Description
FQDN of LDAP server
Security Analytics Reference Guide
Security Analytics 8.1
Description
Retrieve the state of the LDAP auto-discovery flag
GUI Location
Menu
> Settings > Authentication
Parameters
None
Example
callAPI('GET','/settings/get_ldap_discover_flag');
Output
{'errors': [],
'messages': [],
'paging': [],
'result': [0|1],
'resultCode': 'API_SUCCESS_CODE',
'validationErrors': {'Meta': [],
'Setting': [],
'SystemSetting': [],
'res': []}}
Get LDAP options
API Path
/settings/ldap_options
Description
Retrieve LDAP options
GUI Location
Menu
> Settings > Authentication
Parameters
None
Example
callAPI('GET','/settings/ldap_options');
Output
{'errors': [],
'messages': [],
102
Security Analytics Reference Guide
Security Analytics 8.1
'paging': [],
'result': {'ldap_password_change_methods': ['clear',
'clear_remove_old',
'crypt',
'md5',
'ad',
'nds',
'racf',
'exop',
'exop_send_old'],
'ldap_rfc_modes': 'rfc2307bis',
'ldap_schema_map': ['madrfc2307',
'msu35',
'msu20',
'rfc2307bis',
'rfc2307',
'inetorgperson'],
'ldap_scopes': ['sub', 'one', 'base'],
'ldap_ssl_types': ['no', 'on', 'start_tls'],
'ldap_versions': 3},
'resultCode': 'API_SUCCESS_CODE',
'validationErrors': {'Meta': [], 'SystemSetting': [], 'res': []}}
Get LDAP group members
API Path
/settings/ldap_groups/<group>/<limit>
Description
Retrieve the members of an LDAP (external) group
GUI Location
n/a
Output
array
Parameters
REQ
Format
Default
Valid Inputs
group
X
string
—
<GET: /settings/list_ldap_
groups>
limit
X
integer
—
1–<n>
Example
callAPI('GET','/settings/ldap_groups/admins/100');
103
Description
Name of LDAP group
Maximum number of users to retrieve
Security Analytics Reference Guide
Security Analytics 8.1
Get Kerberos settings
API Path
/settings/kerberos
Description
Retrieve Kerberos settings
GUI Location
Menu
> Settings > Authentication
Output
array
Parameters
None
Example
callAPI('GET','/settings/kerberos');
Get RADIUS settings
API Path
/settings/radius_auth
Description
Retrieve RADIUS settings
GUI Location
Menu
> Settings > Authentication
Parameters
None
Example
callAPI('GET','/settings/radius_auth');
Output
{'errors': [],
'messages': [],
'paging': [],
'result': {'enable': True,
104
Security Analytics Reference Guide
Security Analytics 8.1
'password': '***************************',
'port': '1812',
'server': '<hostname>',
'timeout': '3'},
'resultCode': 'API_SUCCESS_CODE',
'validationErrors': {'Meta': [],
'Setting': [],
'SystemSetting': [],
'res': []}}
Configure LDAP authentication
API Path
/settings/ldap
Description
Configure LDAP authentication
GUI Location
Menu
> Settings > Authentication
Output
ApiResultCode
Parameters
REQ
enable
Format
Default
Valid Inputs
Description
string
true
true | false
True — Enable LDAP
authentication; auto-discover is not
launched
string
127.0.0.1
<dotted-decimal> |
<FQDN>
IP address or FQDN of LDAP server
number
636
0–65535
username
string
—
<UTF-8 characters>
BIND DN
password
string
—
<UTF-8 characters>
BIND password
Boolean
false
true | false
search
array
—
base
string
—
scope
string
sub
server
port
test
X
Port number for the secure LDAP
server. This default is New in
Security Analytics 8.1.x.
True — Test the connection to the
LDAP server
Array contains base, scope, group
dc=<domain>,dc=<tld> Search base
base | one | sub
105
Search scope
Security Analytics Reference Guide
REQ
Security Analytics 8.1
Format
Default
Valid Inputs
Description
group
string
—
<UTF-8 characters>
Group DN
group_naming_
attribute
string
—
<UTF-8 characters>
Group name attribute
Boolean |
string |
array
tls
true | false | tls |
ssl | array:(
'encryption' =>
[tls | ssl],
'check_peer' =>
[true | false])
Encryption type:
encryption
version
schema_options
integer
3
3
array
user_
defined
user_defined |
inetorgperson |
madrfc2307 | msu20 |
msu35 | rfc2703 |
rfc2307bis
n
true — Enable TLS mode
n
false — Disable TLS mode
n
tls — Enable TLS mode
n
ssl — Enable SSL mode
n
encryption — Encryption
mode
n
check_peer
o
true — Check
certificate for
valid CA
o
false — No
certificate check;
permit self-signed
certificates
LDAP version; only 3 is valid
LDAP schema:
n
madrfc2307 — Microsoft
Active Directory (RFC 2307)
n
msu20 — Microsoft Services
for Unix 2.0
n
msu35 — Microsoft Services
for Unix 3.5
schema
array
—
user_object_
class
string
—
<UTF-8 characters>
User object class
login_name
string
—
<UTF-8 characters>
Login name attribute
gecos
string
—
<UTF-8 characters>
Full name (GECOS) attribute
user_password
string
—
<UTF-8 characters>
User password attribute
Required if schema_options=user_
defined; array contains all of the
fields below
106
Security Analytics Reference Guide
REQ
pam_password_
change
Security Analytics 8.1
Format
string
Default
md5
Valid Inputs
Description
clear | clear_
remove_old | crypt |
md5 | ad | nds | racf
| exop | exop_send_
old
Password change method:
n
clear — Cleartext
n
clear_remove_old —
Cleartext (remove old
password first)
n
crypt — Crypt
n
nds — Novell NDS
n
racf — IBM RACF
n
exop — RFC 3062
n
exop_send_old — RFC 3062
(send old and new
passwords)
uid_number
string
—
<UTF-8 characters>
User ID number attribute
home_directory
string
—
<UTF-8 characters>
Home directory attribute
login_shell
string
—
<UTF-8 characters>
User shell attribute
shadow_object_
class
string
—
<UTF-8 characters>
Shadow object class
group_object_
class
string
—
<UTF-8 characters>
Group object class
gid_number
string
—
<UTF-8 characters>
Group ID number attribute
pam_member
string
—
<UTF-8 characters>
Group membership attribute
rfc_mode
string
rfc2307bis
rfc2307bis
Group membership type; only
rfc2307bis is valid
Example
callAPI('POST','/settings/ldap',
array(
'server' => '203.0.113.5',
'port' => '389',
'test' => 'true',
'search' => array(
'base' => 'dc=ldap,dc=symantec,dc=com',
'scope' => 'sub',
'group' => '<group_dn>',
'group_name_attribute' => '<group_name_attribute>'
),
'encryption' => array(
'encryption' => 'ssl',
'check_peer' => 'true'
),
'schema_options' => 'user_defined',
'schema' => array(
user_object_class' => '<value>',
login_name gecos' => '<value>',
user_password' => '<value>',
pam_password_change' => 'crypt',
107
Security Analytics Reference Guide
Security Analytics 8.1
uid_number' => '<value>',
home_directory' => '<value>',
login_shell' => '<value>',
shadow_object_class' => '<value>',
group_object_class' => '<value>',
gid_number' => '<value>',
pam_member' => '<value>'
)
)
);
Initiate LDAP discovery
API Path
/settings/ldap_discover
Description
Automatically discover an LDAP server's settings and log in to the server
GUI Location
Menu
> Settings > Authentication
Output
ApiResultCode
Parameters
REQ
Format
Default
Valid Inputs
domain
X
string
—
<FQDN>
username
X
string
—
<UTF-8 characters>
Admin-level account name
password
X
string
—
<UTF-8 characters>
Account password
Example
callAPI('POST','/settings/ldap_discover',
array(
'domain' => 'ldap.company.com',
'username' => 'ldap_admin',
'password' => '55geT!meIn&*'
)
);
Configure Kerberos settings
API Path
/settings/kerberos
108
Description
FQDN of LDAP server
Security Analytics Reference Guide
Security Analytics 8.1
Description
Enable and configure Kerberos single sign-on
GUI Location
Menu
> Settings > Authentication
Output
ApiResultCode
Parameters
REQ
Format
enable
X
kdc
Default
Valid Inputs
Description
Boolean
true | false
True — Enable Kerberos single sign-on
X
string
<dotted-decimal>
realm
X
STRING
domain
X
STRING
username
X
string
—
<UTF-8 characters>
User with authorization to bind a machine
to the Kerberos domain
password
X
string
—
<UTF-8 characters>
User password
—
<FQDN>
<BIND_DN>
Example
callAPI('POST','/settings/kerberos',
array(
'enable' => 'true',
'kdc' => '203.0.113.5',
'realm' => 'KERBEROS.COMPANY.COM',
'domain' => '<BIND_DN>',
'username' => 'kerberos_admin',
'password' => '55geT!meIn&*'
)
);
Configure RADIUS settings
API Path
/settings/radius_auth
Description
Enable and configure RADIUS authentication
GUI Location
Menu
> Settings > Authentication
109
IP of Kerberos domain controller
FQDN of the Kerberos domain controller in
ALL CAPS
Domain of Kerberos server in ALL CAPS
Security Analytics Reference Guide
Security Analytics 8.1
Output
array
Parameters
REQ
Format
Default
Valid Inputs
Description
enable
X
Boolean
false
true | false
True — Enable RADIUS authentication
server
X
string
—
<dotted-decimal> |
<hostname>
port
X
integer
1812
1–65535
password
X
password
—
<UTF-8 characters>
timeout
X
integer
3
2–60
Example
callAPI('POST','/settings/radius_auth',
array(
'enable' => true,
'server' => 'radius.company.com',
'port' => 51812,
'password' => '55geT!meIn&*',
'timeout' => 5
)
);
110
RADIUS server
RADIUS port
Shared secret
Number of seconds between the three
RADIUS-request retransmissions
Security Analytics Reference Guide
Security Analytics 8.1
BPF Filters APIs
Get capture-interface filters
API Path
/captures/filter/<interface>
Description
Get the static capture filters for the specified interface. Dynamic filters are not included.
GUI Location
Menu
> Capture > Summary > [interface box] > [Apply | Edit] Filter
Output
array
Parameters
REQ
Format
Default
Valid Inputs
Description
X
string
—
ethX | aggX
Ethernet or aggregated interface
interface
Example
callAPI('GET','/captures/filter/eth3');
Get the current user's BPF filters
API Path
/filters/get_user_filters
Description
Retrieve all BPF filters that have been created by the current user
GUI Location
n
Menu
> Capture > Summary > [interface box] > [Apply | Edit] Filter
n
Menu
> Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > [More Information |
Actions > Download PCAP] > PCAP without PCAP Filters download
Output
array
Parameters
None
111
Security Analytics Reference Guide
Security Analytics 8.1
Example
callAPI('GET','/filters/get_user_filters');
Get a BPF filter
API Path
/filters/get/<id>
Description
Retrieve a specified BPF filter for PCAP download
GUI Location
Menu
> Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > [More Information | Actions >
Download PCAP] > PCAP without PCAP Filters download
Output
array
Parameters
REQ
Format
Default
Valid Inputs
Description
X
integer
—
<GET: /filters/get_user_
filters>
ID of the filter
id
Example
callAPI('GET','/filters/get/<id>');
Create a BPF filter
API Path
/filters/create
Description
Create a BPF filter for capture interfaces
GUI Location
n
Menu
> Capture > Summary > [interface box] > [Apply | Edit] Filter > Create New Filter
n
Menu
> Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > [More Information |
Actions > Download PCAP] > PCAP without PCAP Filters type > Create New Filter
Output
array
112
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
Format
Default
Valid Inputs
name
X
string
—
<UTF-8 characters>
filter
X
BPF
—
<BPF expression>
Description
Name for the filter
Filter definition
Example
callAPI('POST','/filters/create',
array(
'name' => 'web_only',
'filter' => '(port 80 or 8080 or 443)'
)
);
Apply an existing filter to an interface
API Path
/captures/filter/<interface>
Description
Apply a saved capture filter to the specified interface
GUI Location
Menu
> Capture > Summary > [interface box] > [Apply | Edit] Filter
Output
array
Parameters
REQ
Format
Default
Valid Inputs
Description
interface
X
string
—
ethX | aggX
Ethernet or aggregated interface
filter
X
integer
—
<GET: /filters/get_user_
filters>
Example
callAPI('POST','/captures/filter/eth3',
array(
'filter' => '4'
)
);
Remove a filter from an interface
API Path
/captures/filter/remove/<interface>
113
Filter ID
Security Analytics Reference Guide
Security Analytics 8.1
Description
Remove a BPF filter from a capture interface
GUI Location
Menu
> Capture > Summary > [interface box] > Edit Filter > No Filter
Output
array
Parameters
REQ
interface
X
Format Default
string
—
Valid Inputs
Description
ethX | aggX
Ethernet or aggregated interface
Example
callAPI('POST','/captures/filter/remove/eth3');
Edit a BPF filter
API Path
/filters/edit_advanced/<id>
Description
Edit a BPF filter name or definition
GUI Location
n
Menu
> Capture > Summary > [interface box] > Edit Filter dialog
n
Menu
> Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > [More Information |
Actions > Download PCAP] > PCAP without PCAP Filters download
Output
array
Parameters
REQ
Format
Default
Valid Inputs
id
X
integer
—
name
X
string
—
<UTF-8 characters>
filter
X
BPF
—
<BPF expression>
Description
<GET: /filters/get_user_filters> ID of the filter
114
Name for the filter
Filter definition
Security Analytics Reference Guide
Security Analytics 8.1
Example
callAPI('POST','/filters/edit_advanced/<id>',
array(
'name' => 'web_only',
'filter' => '(port 80 or 8080 or 443)'
)
);
Delete a BPF filter
API Path
/filters/delete/<id>
Description
Delete a BPF filter from the appliance
GUI Location
Menu
> Capture > Summary > [interface box] > Edit Filter > Delete filter
Output
array
Parameters
REQ
Format
Default
Valid Inputs
Description
X
integer
—
<GET: /filters/get_user_filters>
ID of the filter
ids
Example
callAPI('POST','/filters/delete/<id>');
115
Security Analytics Reference Guide
Security Analytics 8.1
Capture APIs
For capture-interface filters, use "BPF Filters APIs" on page 111.
Get the average capture rate — NEW
API Path
/captures/get_billable
Description
Retrieve the average capture rate for the past 10 days in various units of measure.
GUI Location
Output
{'errors': [],
'messages': [],
'paging': [],
'result': {'appliance_billing_stats': False,
'billing_stat': {'avg_bytes_per_day': 448930117174.95416,
'avg_gibibytes_per_day': 418.09875254980676,
'avg_gigabytes_per_day': 448.93011717495415,
'avg_kibibytes_per_day': 438408317.5536662,
'avg_kilobytes_per_day': 448930117.1749542,
'avg_mebibytes_per_day': 428133.1226110021,
'avg_megabytes_per_day': 448930.11717495415,
'avg_pebibytes_per_day': 0.00039873004202824284,
'avg_petabytes_per_day': 0.00044893011717495415,
'avg_tebibytes_per_day': 0.40829956303692067,
'avg_terabytes_per_day': 0.4489301171749542},
'cmc_billing_stat': False},
'resultCode': 'API_SUCCESS_CODE',
'validationErrors': {'LicenseStat': [], 'Meta': [], 'res': []}}
Parameters
None
Example
callAPI('GET','/captures/get_billable');
Get all interfaces
API Path
/captures/get_all_interfaces
Description
Retrieve a list of all interfaces and whether each is capturing or playing back
116
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
Menu
> Capture > Summary > [interface boxes]
Parameters
None
Example
callAPI('GET','/captures/get_all_interfaces');
Output
{'errors': [],
'messages': [],
'paging': [],
'result': {'aggregate': {'alias': False,
'averageFrameSizeBytes': 60,
'can_filter': True,
'capturing': True,
'capturingCurrentBytes': 0,
'capturingCurrentDroppedBytes': 0,
'capturingCurrentDroppedPackets': 0,
'capturingCurrentExceptionPackets': 0,
'capturingCurrentFilteredBytes': 0,
'capturingCurrentFilteredPackets': 0,
'capturingCurrentPackets': 0,
'capturingMaxBytes': 20,
'capturingMaxDroppedBytes': 0,
'capturingMaxDroppedPackets': 0,
'capturingMaxExceptionPackets': 0,
'capturingMaxFilteredBytes': 0,
'capturingMaxFilteredPackets': 0,
'capturingMaxPackets': 0,
'capturingTotalBytes': 60,
'capturingTotalDroppedBytes': 0,
'capturingTotalDroppedPackets': 0,
'capturingTotalExceptionBytes': 0,
'capturingTotalExceptionPackets': 0,
'capturingTotalFilteredBytes': 0,
'capturingTotalFilteredPackets': 0,
'capturingTotalPackets': 1,
'end_date': 1563979390,
'filter_name': '',
'filtering': False,
'fullDuplex': True,
'id': 610,
'interface': 'aggregate',
'ioctlId': None,
'is_management': True,
'linkSpeed': 20000,
'linkUp': True,
'mappedTo': ['agg0', 'agg1', 'agg2', 'agg3', 'agg4'],
117
Security Analytics Reference Guide
Security Analytics 8.1
'name': 'aggregate',
'start_date': 1562638043,
'stats': {'capturing': True,
'capturingCurrent': 0,
'capturingCurrentBits': 0,
'capturingCurrentFiltered': 0,
'capturingCurrentFilteredBits': 0,
'capturingCurrentFilteredPackets': 0,
'capturingCurrentPackets': 0,
'capturingMax': 20,
'capturingMaxBits': 160,
'capturingMaxFiltered': 0,
'capturingMaxFilteredBits': 0,
'capturingMaxFilteredPackets': 0,
'capturingMaxPackets': 0,
'capturingTotal': 60,
'capturingTotalDropped': 0,
'capturingTotalFiltered': 0,
'filtered': False,
'linkSpeed': 20000,
'linkUp': True}},
'eth1': {'alias': False,
'averageFrameSizeBytes': 60,
'can_filter': True,
'capturing': True,
'capturingCurrentBytes': 0,
'capturingCurrentDroppedBytes': 0,
'capturingCurrentDroppedPackets': 0,
'capturingCurrentExceptionPackets': 0,
'capturingCurrentFilteredBytes': 0,
'capturingCurrentFilteredPackets': 0,
'capturingCurrentPackets': 0,
'capturingMaxBytes': 20,
'capturingMaxDroppedBytes': 0,
'capturingMaxDroppedPackets': 0,
'capturingMaxExceptionPackets': 0,
'capturingMaxFilteredBytes': 0,
'capturingMaxFilteredPackets': 0,
'capturingMaxPackets': 0,
'capturingTotalBytes': 60,
'capturingTotalDroppedBytes': 0,
'capturingTotalDroppedPackets': 0,
'capturingTotalExceptionBytes': 0,
'capturingTotalExceptionPackets': 0,
'capturingTotalFilteredBytes': 0,
'capturingTotalFilteredPackets': 0,
'capturingTotalPackets': 1,
'end_date': 1563979390,
'filter_name': '',
'filtering': False,
'fullDuplex': True,
118
Security Analytics Reference Guide
Security Analytics 8.1
'id': 611,
'interface': 'eth1',
'ioctlId': 3,
'is_management': False,
'linkSpeed': 10000,
'linkUp': True,
'mappedTo': None,
'name': 'eth1',
'start_date': 1562638043,
'stats': {'capturing': True,
'capturingCurrent': 0,
'capturingCurrentBits': 0,
'capturingCurrentFiltered': 0,
'capturingCurrentFilteredBits': 0,
'capturingCurrentFilteredPackets': 0,
'capturingCurrentPackets': 0,
'capturingMax': 20,
'capturingMaxBits': 160,
'capturingMaxFiltered': 0,
'capturingMaxFilteredBits': 0,
'capturingMaxFilteredPackets': 0,
'capturingMaxPackets': 0,
'capturingTotal': 60,
'capturingTotalDropped': 0,
'capturingTotalFiltered': 0,
'filtered': False,
'linkSpeed': 10000,
'linkUp': True}}},
'resultCode': 'API_SUCCESS_CODE',
'validationErrors': {'EthInterface': [], 'Meta': [], 'Regen': [], 'res': []}}
Get a list of interfaces
API Path
/captures/list_interfaces
Description
Retrieve a list of all interfaces with their active status
GUI Location
n/a
Parameters
None
Example
callAPI('GET','/captures/list_interfaces');
119
Security Analytics Reference Guide
Security Analytics 8.1
Output
{'errors': [],
'messages': [],
'paging': [],
'result': {'eth1': True},
'resultCode': 'API_SUCCESS_CODE',
'validationErrors': {'EthInterface': [], 'Meta': [], 'res': []}}
Get interfaces
API Path
/config/interfaces
Description
Retrieve a list of interfaces on the device
GUI Location
Menu
> Capture > Summary
Parameters
None
Example
callAPI('GET','/config/interfaces');
Output
{'errors': [],
'messages': [],
'paging': [],
'result': ['eth0', 'eth1', 'eth2', 'eth3'],
'resultCode': 'API_SUCCESS_CODE',
'validationErrors': {'Meta': [], 'res': []}}
Get estimate of data captured per interface
API Path
/capturesummaries/size
Description
Estimate the amount of the data in bytes captured per interface
120
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
Menu
> Capture > Summary
Output
integer
Parameters
REQ
Format
Default
Valid Inputs
Description
array
aggregate
ethX | aggX
Ethernet or aggregated ( aggX)
interface; aggregate — Combine data
from all interfaces
interface
startTime
X
integer
—
<unix epoch>
Begin time
stopTime
X
integer
—
<unix epoch>
End time
Example
callAPI('GET','/capturesummaries/size',
array(
'interface' => 'eth3',
'startTime' => '1563768958',
'stopTime' => '1563787718'
)
);
Output
{'errors': [],
'messages': [],
'paging': [],
'result': '81134616576',
'resultCode': 'API_SUCCESS_CODE',
'validationErrors': {'Meta': [], 'res': []}}
Get system uptime
API Path
/captures/get_uptime
Description
Retrieve the amount of time since the last reboot
GUI Location
Menu
> Capture > Summary
Parameters
None
121
Security Analytics Reference Guide
Security Analytics 8.1
Example
callAPI('GET','/captures/get_uptime');
Output
{'errors': [],
'messages': [],
'paging': [],
'result': {'idle': <float>, 'total': <float>},
'resultCode': 'API_SUCCESS_CODE',
'validationErrors': {'Meta': [], 'res': []}}
Calculate earliest time with statistics
API Path
/capturesummaries/first_time
Description
Calculate the earliest time that the specified interfaces have capture data
GUI Location
Menu
> Capture > Summary
Parameters
interfaces
REQ
Format
Default
Valid Inputs
Description
X
array
—
ethX | aggX
Ethernet or aggregated interface
Example
callAPI('GET','/captures/first_time',
array(
'interfaces' => array(
'eth1',
'eth3',
'agg0'
)
)
);
Get statistics for capture interface
API Path
/captures/capture_data/<interface>
Description
Get capture statistics for the specified interface
122
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
Menu
> Capture > Summary > [interface box]
Parameters
REQ
interface
Format
Default
Valid Inputs
Description
string
eth0
ethX | aggX
Interface name; eth0 — All capture
interfaces
Example
callAPI('GET','/captures/capture_data/eth3');
Output
{'errors': [],
'messages': [],
'paging': [],
'result': {'interface': 'eth1',
'stats': {'capturing': False,
'capturingCurrent': 0,
'capturingCurrentBits': 0,
'capturingCurrentFiltered': 0,
'capturingCurrentFilteredBits': 0,
'capturingCurrentFilteredPackets': 0,
'capturingCurrentPackets': 0,
'capturingMax': 20,
'capturingMaxBits': 160,
'capturingMaxFiltered': 0,
'capturingMaxFilteredBits': 0,
'capturingMaxFilteredPackets': 0,
'capturingMaxPackets': 0,
'capturingTotal': 60,
'capturingTotalDropped': 0,
'capturingTotalFiltered': 0,
'filtered': False,
'linkSpeed': 10000,
'linkUp': True}},
'resultCode': 'API_SUCCESS_CODE',
'validationErrors': {'Meta': [], 'res': []}}
Get capture summary graph statistics
API Path
/capturesummaries
Description
Retrieve a summary of the capture statistics that are displayed on Capture > Summary
123
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
Menu
> Capture > Summary
Output
array
Parameters
REQ
interfaces
Format
Default
Valid Inputs
array
aggregate
<capture summaries inputs>
Description
n
Comma-delimited data
items from the Capture >
Summary graph;
n
aggregate — Combine
data from all capture
interfaces
startTime
X
string
—
<YYYY-MM-DD>T<hh:ii:ss>
[+|-]<zz:zz>
Begin time
stopTime
X
string
—
<YYYY-MM-DD>T<hh:ii:ss>
[+|-]<zz:zz>
End time
integer
1
1 | <integer>
numPoints
Example
callAPI('GET','/capturesummaries',
array(
'interfaces' => array(
'eth1',
'cpu',
'ram',
'qsd',
'qfto'
),
'startTime' => '2019-11-03T00:00:00-07:00',
'stopTime' => '2019-11-03T06:59:59-07:00',
'numPoints' => 7
)
);
Output
{'errors': [],
'messages': [],
124
n
1 — Average for the entire
specified timespan
n
<integer> — Average for
each of <integer>
timespans within the
specified timespan; that is,
if the specified timespan is
12 hours, 12 numPoints
will return the average for
each hour
Security Analytics Reference Guide
Security Analytics 8.1
'paging': [],
'result': {'cpu': {'capture_interface': False,
'captured': [35.6111,
24.21,
25.8889,
20.8289,
15.0556,
11.2578,
14.3844],
'interval': 257,
'num_points': 7,
'start_time': 1563775200,
'stop_time': 1563776999},
'eth1': {'capture_interface': True,
'captured': [88151896,
86922752,
86911192,
78986856,
75270800,
50439008,
83647744],
'interval': 257,
'num_points': 7,
'start_time': 1563775200,
'stop_time': 1563776999},
'qsd': {'capture_interface': False,
'captured': [1, 0, 0, 0, 0, 0, 0],
'interval': 257,
'num_points': 7,
'start_time': 1563775200,
'stop_time': 1563776999},
'qtfo': {'capture_interface': False,
'captured': [0, 0, 0, 0, 0, 0, 0],
'interval': 257,
'num_points': 7,
'start_time': 1563775200,
'stop_time': 1563776999},
'ram': {'capture_interface': False,
'captured': [31.54,
31.45,
31.55,
31.53,
31.14,
31.15,
31.15],
'interval': 257,
'num_points': 7,
'start_time': 1563775200,
'stop_time': 1563776999}},
'resultCode': 'API_SUCCESS_CODE',
'validationErrors': {'Capturesummary': [], 'Meta': [], 'res': []}}
125
Security Analytics Reference Guide
Security Analytics 8.1
Get capture summary graph processes
API Path
/statistics/igraph_options
Description
Retrieve a list of items from the View menu on the Capture Summary page that are currently being displayed. If
the item is not shown, the value is false.
GUI Location
Menu
> Capture > Summary
Parameters
None
Example
callAPI('GET','/statistics/igraph_options');
Output
{'errors': [],
'messages': [],
'paging': [],
'result': {'aggregate': {'show_igraph': True},
'cpu': {'show_igraph': True},
'dequeued': {'show_igraph': True},
'eth1': {'show_igraph': True},
'impt': {'show_igraph': True},
'qfc': {'show_igraph': True},
'qnf': {'show_igraph': True},
'ram': {'show_igraph': True},
'uxnotlive': {'show_igraph': True},
'uxqueued': {'show_igraph': True}},
'resultCode': 'API_SUCCESS_CODE',
'validationErrors': {'DisplayOption': [], 'Meta': [], 'res': []}}
Get retrospective jobs
API Path
/retrospective_jobs/retrospective_jobs
Description
Retrieve a list of reindexing and reprocessing jobs
126
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
Menu
> Capture > Summary > Actions > Reprocess
Parameters
REQ
Format
Default
Valid Inputs
page
integer
1
1–<n>
Page to retrieve; first page is 1
limit
integer
25
1–100
Number of items per page
direction
string
DESC
ASC | DESC
sort
integer
id
id | source | stime | etime |
command | status | job_start | job_
end | slot_done
array
—
<advanced filter for retrospective Advanced filter attributes
jobs>
filters
Example
callAPI('GET','/retrospective_jobs/retrospective_jobs',
array(
'page' => 10,
'sort' => 'stime',
'limit' => 20,
'direction' => 'ASC'
'filters' => array(
'all' => array(
array(
'key' => 'status',
'comp' => '=',
'value' => 'reprocessing'
)
)
)
)
);
Output
{'errors': [],
'messages': [],
'paging': {'rj': {'count': 152,
'current': 25,
'limit': 25,
'nextPage': True,
'options': {'order': {'rj.id': 'desc'}},
'order': {'rj.id': 'desc'},
'page': 1,
'pageCount': 7,
'paramType': 'named',
'prevPage': False,
'queryScope': None}},
'result': {'pageCount': 7,
'rows': [{'command': 1,
'etime': '1564008613 ',
127
Description
Sort order
Sort-by column
Security Analytics Reference Guide
Security Analytics 8.1
'id': 1952,
'job_end': '1564008615 ',
'job_start': '1564008615 ',
'source': 1,
'status': 100,
'stime': '1564005013 '},
{'command': 1,
'etime': '1564005013 ',
'id': 1951,
'job_end': '1564005013 ',
'job_start': '1564005013 ',
'source': 1,
'status': 100,
'stime': '1564001412 '},
...
{'command': 1,
'etime': '1563919726 ',
'id': 1928,
'job_end': '1563919728 ',
'job_start': '1563919728 ',
'source': 1,
'status': 100,
'stime': '1563916125 '}]},
'resultCode': 'API_SUCCESS_CODE',
'validationErrors': {'Meta': [], 'res': [], 'rj': []}}
Get oldest report time
API Path
/captures/first_meta_time/<interface>
Description
Retrieve the first (oldest) time that has report data for the interface
GUI Location
Menu
> Capture > Summary
Parameters
interface
REQ
Format
Default
Valid Inputs
Description
X
string
—
ethX | aggX
Ethernet or aggregated interface
Example
callAPI('GET','/captures/first_meta_time/eth3');
Output
{'errors': [],
'messages': [],
128
Security Analytics Reference Guide
Security Analytics 8.1
'paging': [],
'result': 1560800201,
'resultCode': 'API_SUCCESS_CODE',
'validationErrors': {'Meta': [], 'res': []}}
Get newest report time
API Path
/captures/last_meta_time/<interface>
Description
Retrieve the last (newest) time for report data on the specified interface
GUI Location
Menu
> Capture > Summary
Parameters
REQ
Format
Default
Valid Inputs
Description
X
string
—
ethX | aggX
Ethernet or aggregated interface
interface
Example
callAPI('GET','/captures/last_meta_time/eth1');
Output
{'errors': [],
'messages': [],
'paging': [],
'result': '1563994198',
'resultCode': 'API_SUCCESS_CODE',
'validationErrors': {'EthInterface': [], 'ManagementInterface': [], 'Meta': [], 'res': []}}
Get oldest packet time
API Path
/captures/first_packet_time/<interface>
Description
Retrieve the time that the first (oldest) packet traversed the interface
GUI Location
Menu
> Capture > Summary
129
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
Format
Default
Valid Inputs
Description
X
string
—
ethX | aggX
Ethernet or aggregated interface
interface
Example
callAPI('GET','/captures/first_packet_time/agg1');
Output
{'errors': [],
'messages': [],
'paging': [],
'result': 1560800201,
'resultCode': 'API_SUCCESS_CODE',
'validationErrors': {'Meta': [], 'res': []}}
Get newest packet time
API Path
/captures/last_packet_time/<interface>
Description
Retrieve the last (newest) time for packet data on the specified interface
GUI Location
Menu
> Capture > Summary
Parameters
interface
REQ
Format
Default
Valid Inputs
Description
X
string
—
ethX | aggX
Ethernet or aggregated interface
Example
callAPI('GET','/captures/last_packet_time/eth4');
Output
{'errors': [],
'messages': [],
'paging': [],
'result': 1564008206,
'resultCode': 'API_SUCCESS_CODE',
'validationErrors': {'Meta': [], 'res': []}}
130
Security Analytics Reference Guide
Security Analytics 8.1
Start or stop capture
API Path
/captures/capture/<interface>
Description
Start or stop capture on the specified interface
GUI Location
Menu
> Capture > Summary
Output
array
Parameters
interface
REQ
Format
Default
Valid Inputs
Description
X
string
—
ethX | aggX
Ethernet or aggregated interface; eth0 — All
interfaces
Boolean
false
true | false
stop
Example 1
Start capture on eth3
callAPI('POST','/captures/capture/eth3');
Example 2
Stop capture on all interfaces
callAPI('POST','/captures/capture/eth0',
array(
'stop' => true
)
);
Toggle capture summary graph inputs
API Path
/captures/save_selected_interface/<interface>/<remove>
Description
Hide or show items on the Capture Summary Graph
131
n
true — Stop capture interface(s)
n
false — Start capture on interface(s)
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
Menu
> Capture > Summary > View > [menu item]
Output
array
Parameters
REQ
Format
Default
Valid Inputs
interface
X
string
—
<capture summaries
inputs>
remove
X
integer
—
0 | 1
Description
Data items on the Capture > Summary
graph
n
0 — Hide
n
1 — Show
Example
callAPI('POST','/captures/save_selected_interface/<interface>/<remove>');
Create a reprocessing job
API Path
/retrospective_jobs/save
Description
Create a reprocessing job; reindexing is included
GUI Location
Menu
> Capture > Summary > Actions > Reprocess
Output
array
Parameters
REQ Format
Default Valid Inputs
Description
startTime
X
datetime
—
<YYYY-MM-DD>T<hh:ii:ss>[+|-]<zz:zz>
Start time
endTime
X
datetime
—
<YYYY-MM-DD>T<hh:ii:ss>[+|-]<zz:zz>
End time
Example
callAPI('POST','/retrospective_jobs/save',
array(
'startTime' = '2019-11-03T21:33:24-07:00',
'endTime' = '2019-11-03T21:43:41-07:00'
)
);
132
Security Analytics Reference Guide
Security Analytics 8.1
Delete retrospective jobs
API Path
/retrospective_jobs/delete
Description
Delete reindexing or reprocessing jobs
GUI Location
Menu
> Capture > Summary > Actions > Reprocess
Output
array
Parameters
REQ Format Default
id
integer
0
Valid Inputs
Description
<GET: /retrospective_jobs/retrospective_jobs>
Job to delete
Example
callAPI('POST','/retrospective_jobs/delete',
array(
'id' => 2454,
'id' => 2455,
'id' => 2456
)
);
Truncate capture summaries
API Path
/settings/truncate_capture_summaries
Description
Delete the capture summary graph data up to the current moment
GUI Location
Menu
> Capture > Summary
Output
array
Parameters
None
133
Security Analytics Reference Guide
Security Analytics 8.1
Example
callAPI('POST','/settings/truncate_capture_summaries');
Aggregate two interfaces
API Path
/captures/interface_map
Description
Merge two capture interfaces into one aggregated interface
GUI Location
Menu
> Capture > Summary
Output
array
Parameters
REQ
Format
Default
Valid Inputs
interface
X
string
—
ethX
First Ethernet interface to merge
interface2
X
string
—
ethX
Second Ethernet interface to merge
mappedTo
X
string
—
aggX
Aggregated (merged) Ethernet interface
name
Example
callAPI('POST','/captures/interface_map',
array(
'interface' => 'eth3',
'interface2' => 'eth4',
'mappedTo' => 'agg0'
)
);
Separate aggregated interface
API Path
/captures/interface_unmap
Description
Separate the aggregated interface into its component interfaces
GUI Location
Menu
> Capture > Summary
134
Description
Security Analytics Reference Guide
Security Analytics 8.1
Output
array
Parameters
REQ
Format
Default
Valid Inputs
X
string
—
aggX
interface
Description
Aggregated interface to separate
Example
callAPI('POST','/captures/interface_unmap',
array(
'interface' => 'agg0'
)
);
Change interface name
API Path
/captures/rename_interface/<interface>
Description
Name or rename an interface
GUI Location
Menu
> Capture > Summary
Output
array
Parameters
REQ
Format
Default
Valid Inputs
Description
interface
X
string
—
ethX | aggX
Ethernet or aggregated interface
alias
X
string
—
<UTF-8 characters>
Example
callAPI('POST','/captures/rename_interface/eth3',
array(
'alias' => 'ZONE-3'
)
);
Start reindexing or reprocessing
API Path
/captures/start_reindex_job
135
Display name of interface
Security Analytics Reference Guide
Security Analytics 8.1
Description
Index the classification discards or reprocess data from a specified timespan; retrospective jobs created with this
API call are given priority
GUI Location
n
Menu
> Capture > Summary > [select timespan] > Actions > Reprocess > New
n
Menu
> Analyze > Summary > Status bar > [warning icon
for classification discards]
Output
array
Parameters
REQ Format Default
Valid Inputs
Description
startDate
X
string
—
<YYYY-MM-DD>T<hh:ii:ss>[+|-]<zz:zz>
Start time
endDate
X
string
—
<YYYY-MM-DD>T<hh:ii:ss>[+|-]<zz:zz>
End time
type
X
string
—
reindex | enrichment
Example
callAPI('POST','/captures/start_reindex_job',
array(
'startDate' => '2019-11-03T00:00:00-07:00',
'endDate' => '2019-11-03T00:03:59-07:00',
'type' => 'reindex'
)
);
136
n
reindex —
Classification
discards are
indexed
n
enrichment
— Data is
sent back
through the
dataenrichment
process
(reprocess)
Security Analytics Reference Guide
Security Analytics 8.1
Central Manager APIs
These APIs are for use only in CMC environments. For functions that also exist on standalone appliances, see the
individual APIs.
Get the first CMC that is connected to a sensor — NEW
API Path
/settings/cmc_first
Description
Sensor Only. Retrieve the first CMC in the list of CMCs connected to the sensor.
GUI Location
Menu
> Settings > Central Management
Output
{'errors': [],
'messages': [],
'paging': [],
'result': {'applianceId': <integer>, 'cmcIp': '<cmc_ip>'},
'resultCode': 'API_SUCCESS_CODE',
'validationErrors': {'Meta': [], 'Vpn': [], 'VpnClientConfig': [], 'res': []}}
Parameters
None
Example
callAPI('GET','/settings/cmc_first/');
Download authorization key
API Path
/cmc_settings/download_appliance_key/<id>
Description
CMC Only. Download the authorization key for a sensor
GUI Location
n
Menu
> Settings > Central Management > Sensors > Download Authorization Key
n
CMC > Dashboard > Manage Sensors > Download Authorization Key
Output
array
137
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
Format
Default
Valid Inputs
X
integer
—
<GET: /cmc_settings/appliances>
id
Example
callAPI('GET','/cmc_settings/download_appliance_key/8');
Get IPv6 VPN settings
API Path
/cmc_settings/cmc_server_ipv6
Description
CMC Only. Retrieve the CMC's IPv6 VPN settings
GUI Location
Menu
> Settings > Central Management > Settings
Output
array
Parameters
None
Example
callAPI('GET','/cmc_settings/cmc_server_ipv6');
Get sensor labels
API Path
/cmc_settings/labels
Description
CMC Only. Get all of the labels that are currently applied to sensors
GUI Location
n
Menu
> Settings > Central Management > Sensors
n
CMC > Dashboard > Manage Sensors
Output
array
138
Description
Sensor ID
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
Format
Default
Valid Inputs
Description
direction
string
asc
asc | desc
page
integer
0
0–<n>
Page to retrieve; first page is 0
limit
integer
25
1–100
Number of items per page
sort
string
name
name
Sort-by column
filter
string
—
<label>
Sort order
Filter name to search for
Example
callAPI('GET','/cmc_settings/labels');
Get paginated sensor list
API Path
/cmc_settings/appliances
Description
CMC Only. Retrieve a paginated list of sensors
GUI Location
n
Menu
> Settings > Central Management > Sensors
n
Dashboard
Output
array
Parameters
REQ
Format
Default
Valid Inputs
page
integer
0
0–<n>
Page to retrieve; first page
is 0
limit
integer
25
1–100
Number of items per page
sort
string
name
name | model | connected |
capturing | last_selected
direction
string
asc
asc | desc
filter
JSON
—
label
Example
callAPI('GET','/cmc_settings/appliances',
array(
'page' => 10,
'limit' => 20,
'sort' => 'model',
139
Description
Sort-by column
Sort direction
Advanced filter attribute
Security Analytics Reference Guide
Security Analytics 8.1
'direction' => 'desc',
'filter' => array(
'all' => array(
array(
'key' => 'label',
'comp' => '=',
'value' => '*'
)
)
)
)
);
Get sensor information
API Path
/cmc_settings/appliances/<ids>
Description
CMC Only. Retrieve information about selected sensors
GUI Location
CMC > Sensor Selector
Output
array
Parameters
REQ
Format
Default
Valid Inputs
X
array
—
<GET: /cmc_settings/appliances>
ids
Description
Sensor IDs, comma-delimited
Example
callAPI('GET','/cmc_settings/appliances/<id-1>,<id-2>,<id-3>');
Get information about connected sensors
API Path
/cmc_settings/appliances_info
Description
CMC Only. Retrieve when the sensor was last selected, assuming that it is currently connected
GUI Location
CMC > Sensor Selector
140
Security Analytics Reference Guide
Security Analytics 8.1
Output
array
Parameters
None
Example
callAPI('GET','/cmc_settings/appliances_info');
Get VPN status
API Path
/cmc_settings/vpn_running
Description
CMC Only. Retrieve whether a VPN is operational
GUI Location
Menu
> Settings > Central Management > Settings
Output
Boolean
Parameters
None
Example
callAPI('GET','/cmc_settings/vpn_running');
Get VPN settings
API Path
/cmc_settings/vpn_server_config
Description
CMC Only. Retrieve VPN configuration settings
GUI Location
Menu
> Settings > Central Management > Settings
Output
array
141
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
None
Example
callAPI('GET','/cmc_settings/vpn_server_config');
Get repository file list
API Path
/cmc_upgrades/load_upgrades
Description
CMC Only. Retrieve a list of upgrade files in the CMC repository
GUI Location
n
Menu
> Settings > Central Management > Upgrades
n
CMC > Dashboard > Upgrade Repository
Output
array
Parameters
None
Example
callAPI('GET','/cmc_upgrades/load_upgrades');
Get all IPv4 VPN settings for a CMC
API Path
/cmc_settings/cmc_server
Description
CMC Only. Retrieve the CMC's VPN settings
GUI Location
Menu
> Settings > Central Management > Settings
Output
array
142
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
None
Example
callAPI('GET','/cmc_settings/cmc_server');
Get all VPN settings for a sensor
API Path
/cmc_settings/cmc_client
Description
Sensor Only. Retrieve the VPN settings of all CMCs that are connected to a sensor
GUI Location
Menu
> Settings > Central Management
Output
array
Parameters
None
Example
callAPI('GET','/cmc_settings/cmc_client');
Get sensor capture status
API Path
/captures/aggregate_status?appliances=<IDs>
Description
CMC Only. Retrieve the capture status on specified sensors
GUI Location
CMC > Dashboard
Output
array
143
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
appliances
REQ
Format
Default
Valid Inputs
X
integer
—
<GET: /cmc_
settings/appliances>
Description
Sensor IDs
Example
callAPI('GET','/captures/aggregate_status?appliances=1,2,4,5,7');
Get confirmation of sensor disconnect
API Path
/cmc_settings/acknowledge_disconnected_appliances
Description
CMC Only. After the web UI for the CMC displays an error message about disconnected sensors, this API
prevents the CMC's UI from displaying the error message again.
GUI Location
Any CMC page
Output
array
Parameters
None
Example
callAPI('GET','/cmc_settings/acknowledge_disconnected_appliances');
Push ICDx server settings — NEW
API Path
/settings/icdx_cmc_comm_push
Description
CMC Only. Push saved ICDx server settings to all connected sensors. To save server settings on the CMC use
POST: /settings/icdx_set_meta_server.
GUI Location
Menu
> Settings > ICDx Metadata
Output
array
144
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
log_icdx_password
REQ
Format
Default
Valid Inputs
Description
X
string
—
<UTF-8 characters>
Password
for the ICDx
server
Python Example
Push ICDx metadata settings — NEW
API Path
/settings/icdx_cmc_push_meta
Description
Push saved ICDx metadata attributes to all connected sensors. To save attributes on the CMC use POST:
/settings/icdx_save_meta.
GUI Location
Menu
> Settings > ICDx Metadata
Parameters
None
Python Example
s.callAPI("POST","/settings/icdx_cmc_push_meta")
PHP Example
callAPI('GET','/settings/icdx_save_meta');
Add a sensor to the CMC — MODIFIED
API Path
/cmc_settings/add_appliance
Description
CMC Only. Add a sensor to the CMC
GUI Location
n
Menu
> Settings > Central Management > Sensors
n
CMC > Dashboard > Manage Sensors
Output
array
145
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
Format
Valid Inputs
Description
X
string
—
<GET: /cmc_
settings/appliances>
Sensor name
users
array
—
<GET: /settings/users>
Authorized usernames
groups
array
—
<GET: /settings/groups>
Authorized remote groups (groups where
remote=true)
labels
array
—
<GET: /cmc_
settings/labels> | <UTF8 characters>
Label(s) to assign to the sensor; you can
get existing labels or create new ones
mssfix
integer
1400
name
Default
Maximum transmission unit New in
Security Analytics 8.1.1
Example
callAPI('POST','/cmc_settings/add_appliance',
array(
'name' => 'Sensor-00',
'users' => array(
'fred.user',
'liliana.user',
'admin'
),
'groups' => array(
'sysadmins',
'auditors',
'analysts'
),
'mssfix' => 1500
)
);
Edit sensor settings — MODIFIED
API Path
/cmc_settings/edit_appliance/<id>
Description
CMC Only. Edit a sensor; the settings that this API passes will overwrite all previous settings
GUI Location
n
Menu
> Settings > Central Management > Sensors
n
CMC > Dashboard > Manage Sensors
Output
Boolean
146
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
Format Default
Valid Inputs
Description
id
X
integer
—
<GET: /cmc_settings/appliances>
Sensor ID
name
X
string
—
<GET: /cmc_settings/appliances>
Sensor name
users
array
—
<GET: /settings/users>
Authorized
usernames
groups
array
—
<GET: /settings/groups>
Authorized
remote groups
(groups where
remote=true)
labels
array
—
<GET: /cmc_settings/labels>
mssfix
integer
1400
Label(s) to
assign to the
sensor
Maximum
transmission
unit New in
Security
Analytics 8.1.1
Example
callAPI('POST','/cmc_settings/edit_appliance/4',
array(
'name' => 'Sensor-00',
'users' => array(
'george.user',
'ana.user'
),
'groups' => array(
'subanalysts'
),
'labels' => array(
'bldg1',
'bldg5'
)
'mssfix' => 1500
)
);
Download authorization key
API Path
/cmc_settings/download_appliance_key/<id>
Description
CMC Only. Download the authorization key for a sensor
147
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
n
Menu
> Settings > Central Management > Sensors > Download Authorization Key
n
CMC > Dashboard > Manage Sensors > Download Authorization Key
Output
array
Parameters
REQ
Format
Default
Valid Inputs
id
X
integer
—
<GET: /cmc_
settings/appliances>
password
X
string
—
<UTF-8 characters>
PHP Example
callAPI('POST','/cmc_settings/download_appliance_key/8'
array => (
'password' => '3nk0dm3'
), <sensor>.tar.gz.gpg
);
Python Example
s.callAPI("POST","/cmc_settings/download_appliance_key/8", {
'password': '3nk0dm3'
}, '<sensor>.tar.gz.gpg'
)
Upload authorization key file to sensor
API Path
/cmc_settings/cmc_client
Description
Sensor Only. Upload the authorization key file to the sensor
GUI Location
Menu
> Settings > Central Management
Output
array
148
Description
Sensor ID
User-supplied password to encrypt
the authorization key file.
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
Format
Default
Valid Inputs
Description
server
X
string
—
<dotted-decimal>
file
X
filename
—
<filepath>\<sensor>_auth_
key.tar.gz[.gpg]
password
X
string
—
<UTF-8 characters>
Primary IP address for bond0 on the CMC
that generated the authorization key file
Path to authorization key file.
Password to encrypt the authorization key
file that was provided on the CMC when
downloading the file.
Example
callAPI('POST','/cmc_settings/cmc_client',
array(
'server' => '203.0.113.5',
'file' => 'sensor-00_auth_key.tar.gz',
'password' => '3nk0dm3'
)
)
);
Create the IPv6 CMC VPN
API Path
/cmc_settings/cmc_server_ipv6
Description
CMC Only. Set up the CMC's VPN network over IPv6
GUI Location
Menu
> Settings > Central Management > Settings > Save
Output
array
Parameters
REQ
Format
Default
Valid Inputs
Description
protocol
string
udp6
tcp6 | udp6
VPN protocol
port
integer
1194
1–65536
string
fdf9:5fdf:968f:54b9::/64
<IPv6>/64
server-ipv6
X
Example
callAPI('POST','/cmc_settings/cmc_server_ipv6',
array(
'protocol' => 'tcp6',
'port' => '1194',
149
VPN port number
Unique Local Address (ULA)
subnet
Security Analytics Reference Guide
Security Analytics 8.1
'server-ipv6' => '2026:3004:fa3:20cd::/64',
)
);
Add labels to sensors
API Path
/cmc_settings/add_appliance_labels
Description
CMC Only. Add labels to one or more sensors
GUI Location
n
Menu
> Settings > Central Management > Sensors
n
CMC > Dashboard > Manage Sensors
Output
array
Parameters
REQ
Format
Default
Valid Inputs
Description
ids
X
array
—
<GET: /cmc_settings/appliances>
Sensor ID/s
labels
X
array
—
<GET: /cmc_settings/labels> | <UTF8 characters>
Example
callAPI('POST','/cmc_settings/add_appliance_labels',
array(
'ids' => array(
5,
6,
11
),
'labels' => array(
'CANADA',
'10G-Fiber'
)
)
);
Remove labels from sensors
API Path
/cmc_settings/remove_appliance_labels
150
Label/s to add to the
sensor/s
Security Analytics Reference Guide
Security Analytics 8.1
Description
CMC Only. Delete a label from one or more sensors
GUI Location
n
Menu
> Settings > Central Management > Sensors
n
CMC > Dashboard > Manage Sensors
Output
Boolean
Parameters
REQ
Format
Default
Valid Inputs
Description
ids
X
array
—
<GET: /cmc_settings/appliances>
Sensor ID/s
labels
X
array
—
<GET: /cmc_settings/labels>
Label/s to remove from the
appliance/s
Example
callAPI('POST','/cmc_settings/remove_appliance_labels',
array(
'ids' => <id-1>,<id-2>
'labels' => '<label-1>','<label-2>'
)
);
Create mount point on multiple sensors
API Path
/pcap_import_mount_points/aggregate_save?appliance=<sensor_IDs>
Description
CMC only. Create a mount point on two or more sensors
GUI Location
[Selected Sensor/s] > Menu
> Capture > Import PCAP > Manage Connections > Add New Server
Output
array
151
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
Valid Inputs
Description
—
<UTF-8 characters>
Display name
string
nfs
nfs | cifs
Server protocol
string
—
<hostname> | <dotteddecimal>
Server location
integer
0
1–65535
string
—
/<filepath>/
username
string
—
<UTF-8 characters>
Required if
protocol=cifs
password
string
—
<UTF-8 characters>
Required if
protocol=cifs
array
null
<GET: /cmc_
settings/appliances>
alias
REQ
Format
X
string
protocol
serverName
X
portNum
directory
applianceIds
X
X
Default
Example
callAPI('POST','/pcap_import_mount_points/aggregate_save?appliance=3,6,7',
array(
'alias' => 'pcap-server',
'serverName' => 'pcaps.domain.com',
'directory' => '/var/public',
'applianceIds' => array(
3,
6,
7
)
)
);
Create the IPv4 CMC VPN
API Path
/cmc_settings/cmc_server
Description
CMC Only. Set up the CMC's VPN network over IPv4
GUI Location
Menu
> Settings > Central Management > Settings > Save
Output
array
152
Port number
Watch-folder path
Sensor ID/s
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
Format
Default
Valid Inputs
Description
protocol
string
udp
tcp | udp
VPN protocol
port
integer
1194
1–65536
subnet
string
10.8.0.0
<dotted-decimal>
VPN subnet
netmask
string
255.255.255.0
<dotted-decimal>
VPN netmask
VPN port number
Example
callAPI('POST','/cmc_settings/cmc_server',
array(
'protocol' => 'tcp',
'port' => '1195',
'subnet' => '10.111.0.0',
'netmask' => '255.255.0.0'
)
);
Delete sensors
API Path
/cmc_settings/delete_appliances/<ids>
Description
CMC Only. Delete the sensor(s) from the CMC; this API does not inform the sensors that they have been
disconnected
GUI Location
n
Menu
> Settings > Central Management > Sensors
n
CMC > Dashboard > Manage Sensors
Output
Boolean
Parameters
REQ
Format
Default
Valid Inputs
X
string
—
<GET: /cmc_settings/appliances>
ids
Description
Sensor IDs
Example
callAPI('POST','/cmc_settings/delete_appliances/<id-1>,<id-2>,<id-3>');
153
Security Analytics Reference Guide
Security Analytics 8.1
Save the sensors' last-selected status
API Path
/central_manager/select?appliance=<sensor_IDs>
Description
CMC Only. Save the last-selected status of specified sensors
GUI Location
CMC > Sensor Selector
Output
ApiResultCode
Parameters
REQ
Format
Default
Valid Inputs
X
array
—
<GET: /cmc_settings/appliances>
ids
Example
callAPI('POST','/central_manager/select?appliance=2,4,9',
array(
'ids' => array(
2,
4,
9
)
)
);
Remove a CMC from the sensor
API Path
/cmc_settings/cmc_client_remove/<id>
Description
Sensor Only. Remove a CMC from the sensor.
GUI Location
Menu
> Settings > Central Management
Output
array
154
Description
Sensor IDs
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
Format
Default
Valid Inputs
X
integer
—
<GET: /cmc_settings/cmc_client>
id
Description
CMC ID
Example
callAPI('POST','/cmc_settings/cmc_client_remove/<id>');
Reset the VPN
API Path
/cmc_settings/reset_vpn_settings
Description
CMC Only. Reset the VPN to default settings, thereby deleting all sensor connections. This API does not inform
the sensors that they have been disconnected.
GUI Location
Menu
> Settings > Central Management > Settings > Reset Settings
Output
ApiResultCode
Parameters
None
Example
callAPI('POST','/cmc_settings/reset_vpn_settings');
Download file to upgrade repository
API Path
/upgrades/start_download/<serverId>/<filename>
Description
CMC Only. Begin downloading an upgrade file from an upgrade server to the CMC's upgrade repository
GUI Location
n
Menu
> Settings > Central Management > Upgrades
n
CMC > Dashboard > Upgrade Repository
155
Security Analytics Reference Guide
Security Analytics 8.1
Output
array
Parameters
REQ
Format
Default
Valid Inputs
Description
serverId
X
integer
—
<GET: /upgrades/list>
filename
X
string
—
<GET: /upgrades/manifest>
Upgrade server ID
Name of upgrade file
Example
callAPI('POST','start_download/2/atpsa-8.1.1-45000-x86_64-DVD.tar');
Initiate a push-upgrade to sensors
API Path
/cmc_settings/upgrade_appliances
Description
CMC Only. Initiates a push-upgrade from a CMC to a sensor.
GUI Location
n
Menu
> Settings > Central Management > Sensors
n
CMC > Dashboard > Manage Sensors
Output
integer
Parameters
REQ
Format
Default
Valid Inputs
ids
X
array
—
<GET: /cmc_
settings/appliances>
filename
X
string
—
<GET: /cmc_upgrades/load_
upgrades>
Example
callAPI('POST','/cmc_settings/upgrade_appliances',
array(
'ids' => array(
<id-1>,
<id-2>,
<id-3>
)
'filename' => 'atpsa-8.1.1-56488-x86_64-DVD.tar'
)
);
156
Description
Sensor IDs
Name of the upgrade file
Security Analytics Reference Guide
Security Analytics 8.1
Delete an upgrade file from the repository
API Path
/cmc_upgrades/upgrade_delete
Description
CMC Only. Delete an upgrade file from the CMC repository
GUI Location
n
Menu
> Settings > Central Management > Upgrades
n
CMC > Dashboard > Upgrade Repository
Output
ApiResultCode
Parameters
REQ
Format
Default
Valid Inputs
X
string
—
<GET: /cmc_upgrades/load_
upgrades>
file
Example
callAPI('POST','/cmc_upgrades/upgrade_delete',
array(
'file' => 'atpsa-8.1.1-56488-x86_64-DVD.tar'
)
);
157
Description
Name of the upgrade file
Security Analytics Reference Guide
Security Analytics 8.1
Data Enrichment APIs
Get the GIN diagnostic test results
API Path
/health/gin_test
Description
Run the GIN diagnostic test and get the results
GUI Location
Menu
> Settings > Data Enrichment > Blue Coat File Reputation Service > Test Service
Output
ApiResultCode
Parameters
None
PHP Example
callAPI('GET','/health/gin_test');
Python Example
s.callAPI("GET","/health/gin_test")
Download GIN diagnostic test results
API Path
/health/gindiag_download
Description
Download the PCAPs and log from the GIN test
GUI Location
Runs the gindiag.sh script
Output
ApiResultCode
Parameters
None
PHP Example
callAPI('GET','/health/gindiag_download',);
158
Security Analytics Reference Guide
Security Analytics 8.1
Python Example
s.callAPI("GET","/health/gindiag_download",)
Download the current YARA file
API Path
/integration_providers/yara_download
Description
Download the current YARA rules file
GUI Location
Menu
> Settings > Data Enrichment > YARA File Manager
Output
ApiResultCode
Parameters
None
PHP Example
callAPI('GET','/integration_providers/yara_download',
'rules.yar'
);
Python Example
s.callAPI("GET","/integration_providers/yara_download",
"rules.yar"
)
Get the data-enrichment profile
API Path
/settings/system_services_profile
Description
Retrieve the current data-enrichment (system-services) profile
GUI Location
Menu
> Settings > Data Enrichment > Data Enrichment Profiles
Output
array
159
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
None
Example
callAPI('GET','/settings/system_services_profile');
Get enrichment providers
API Path
/integration_providers/providers
Description
Retrieve a paged set of enrichment provider records
GUI Location
Menu
> Settings > Data Enrichment
Output
array
Parameters
REQ
Format
Default
Valid Inputs
Description
page
integer
1
1–<n>
Page number to retrieve; first page is 1
limit
integer
25
1–100
Number of records per page
sort
string
name
name
Sort-by column
string
asc
asc | desc
direction
160
Sort order
Security Analytics Reference Guide
REQ
edit_type
Format
string
Security Analytics 8.1
Default
all
Valid Inputs
all | none | data |
restricted | malware |
internal | local |
threatexplorer
Example
callAPI('GET','/integration_providers/providers',
array(
'page' => 10,
'limit' => 20,
'sort' => 'name',
'direction' => 'asc',
'edit_type' => 'malware'
)
);
Get all enrichment providers
API Path
/integration_providers/all_providers
Description
Retrieve a list of all enrichment providers
GUI Location
Menu
> Settings > Data Enrichment
Output
array
Parameters
None
161
Description
Retrieve enrichment providers of the
specified 'edit type':
n
all — Integration providers, SEP,
MATI
n
none — DeepSight
n
data — EDR pivot
n
restricted — Third-party ondemand reputation providers
n
malware — Analysis providers
n
internal — Intelligence Services
n
local — Local File Analysis
n
threatexplorer — Threat Explorer
pivot (new)
Security Analytics Reference Guide
Security Analytics 8.1
Example
callAPI('GET','/integration_providers/all_providers');
Test Malware Analysis connectivity
API Path
/integration_providers/test_settings
Description
Test the connection to Malware Analysis
GUI Location
Menu
> Settings > Data Enrichment > Test Connection button
in Edit Malware Analysis Appliance dialog
Output
array
Parameters
REQ
Format
Default
Valid Inputs
uuid
X
UUID
—
<GET: /integration_
providers/norman>
Array of Malware Analysis UUID and name
keys.
name
X
string
—
<UTF-8 characters>
User-defined name for the Malware Analysis
appliance.
Example
callAPI('GET','/integration_providers/test_settings'
array(
'uuid' => <UUID>,
'name' => 'MAA-200'
)
);
Get Malware Analysis task report
API Path
/reputations/malware/<serverUuid>/<taskId>
Description
Retrieve a task report from Malware Analysis
162
Description
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
n
SA — Menu
> Analyze > Alerts > List > [malware analysis alert] > Go to MAA
n
CA — Malware Analysis tab
n
MA — Analysis Center > View All Tasks > [task id]
Output
array or error code
Parameters
REQ
Format
Default
Valid Inputs
serverUuid
X
integer
—
<GET: /integration_
providers/norman>
taskId
X
integer
—
<GET: /alerts>
Example
callAPI('GET','/reputations/malware/<serverUuid>/44355');
Get state of local file analysis providers
API Path
/integration_providers/local_file_analysis
Description
Retrieve state information (enabled, disabled) for local file analysis providers
GUI Location
Menu
> Settings > Data Enrichment
Output
array
Parameters
None
Example
callAPI('GET','/integration_providers/local_file_analysis');
163
Description
Malware Analysis identifier
Task identifier on Malware Analysis
Security Analytics Reference Guide
Security Analytics 8.1
Get a data-enrichment filter
API Path
/integration_providers/derp_filters
Description
Retrieve the data-enrichment file-type filters for a provide
GUI Location
Menu
> Settings > Data Enrichment > [edit provider] > Data Enrichment File Types
Output
array
Parameters
providers
IntegrationProvider
derp_filters
REQ
Format
Default
Valid Inputs
X
array
IntegrationProvider
IntegrationProvider
X
array
derp_filters
derp_filters
array
tonic_filter
clam_av | cp_mover |
cuckoo | file_
reputation_service |
fireeye | ftp_mover |
icap_cas | jsunpack |
lastline | local_
hash_reputation |
noop | norman | scp_
mover | tiscale |
virustotal | yara |
tonic_filter
Example
callAPI('GET','/integration_providers/derp_filters',
array(
'providers' = > array(
'IntegrationProvider' => array(
'derp_filters' => array(
'ftp_mover',
'file_reputation_service'
)
)
164
Description
Internal name for the
file/hash provider or
tonic_filter (default
data-enrichment filter)
n
cp_mover —
Local File
Mover
n
local_hash_
reputation —
Custom Hash
List
n
noop —
Calculate and
Store Hashes
n
norman —
Malware
Analysis
Security Analytics Reference Guide
Security Analytics 8.1
)
)
);
Get custom Web Reputation Service update location
API Path
/web_pulse/location
Description
Retrieves the custom Web Reputation Service update location
GUI Location
Menu
> Settings > Data Enrichment > Web Reputation Service Update Location
Output
array
Parameters
None
Example
callAPI('GET','/web_pulse/location');
Get third-party integration-provider types
API Path
/integration_providers/types
Description
Retrieve all types of third-party integration providers
GUI Location
Menu
> Settings > Data Enrichment > Third-Party Integration Providers
Output
array
Parameters
None
Example
callAPI('GET','/integration_providers/types');
165
Security Analytics Reference Guide
Security Analytics 8.1
Get an artifact's reputation
API Path
/reputations/artifact/<artifactId>
Description
Retrieve an artifact's reputation from the specified provider
GUI Location
Menu
> Analyze > Extractions > [artifact entry] > Reputation button
Output
array
Parameters
REQ
artifactId
Format Default
Valid Inputs
Description
integer
—
<GET: /artifacts/artifacts>
provider
UUID
null
null | <GET: /integration_
providers/all_providers>
Integration provider UUID; use
null to retrieve all providers
artifactField
string
null
<advanced filter attributes>
Field for the reputation lookup;
leave blank for all fields
X
Artifact ID
Example
callAPI('GET','/reputations/artifact/<artifactId>',
array(
'provider' => '<provider_UUID>',
'artifactField' => 'ip_source'
)
);
Get on-demand reputation
API Path
/reputations/reputation/<provider>/<value>
Description
Retrieve reputation results from the providers for a specified value
GUI Location
n
Menu
> Analyze > Summary > [report value] > View Reputation Information > [on-demand reputation
provider]
166
Security Analytics Reference Guide
Security Analytics 8.1
n
Menu
> Analyze > Reports > [report value] > View Reputation Information > [on-demand reputation
provider]
n
Menu
> Analyze > Extractions > [artifact field] > View Reputation Information > [on-demand reputation
provider]
n
Menu
> Analyze > Geolocation > [ip address] > View Reputation Information > [on-demand reputation
provider]
Output
array
Parameters
REQ
Format
Default
Valid Inputs
provider
X
UUID
—
<GET: /integration_
providers/all_providers>
value
X
URL encoding
—
<URL> | <hash> | <ip_
address>
Description
UUID of the provider to query
URL-encoded value to pass to the
provider
Example
callAPI('GET','/reputations/reputation/529e0f20-9834-406b-b5ee-53e41e1d64a3/203.0.113.5');
Get Malware Analysis entries
API Path
/integration_providers/norman
Description
Retrieve the configuration data for the Malware Analysis entries
GUI Location
Menu
> Settings > Data Enrichment > Symantec Analysis Providers > Malware Analysis Appliance
Output
array
Parameters
None
Example
callAPI('GET','/integration_providers/norman');
167
Security Analytics Reference Guide
Security Analytics 8.1
Get Login Correlation Service settings
API Path
/settings/adlistener
Description
Retrieve the allowed IP addresses and whether Allow All Agent IPs is true
GUI Location
Menu
> Settings > Security > Login Correlation Service
Output
array
Parameters
None
Example
callAPI('GET','/settings/adlistener');
Get domain filters
API Path
/integration_providers/domain_filters
Description
Retrieve all domains that are excluded from data-enrichment lookup
GUI Location
Menu
> Settings > Data Enrichment > Exclude from Lookup > Domains
Output
array
Parameters
None
Example
callAPI('GET','/integration_providers/domain_filters');
168
Security Analytics Reference Guide
Security Analytics 8.1
Get IP filters
API Path
/integration_providers/ip_filters
Description
Retrieve all IP subnets that are excluded from data-enrichment lookup
GUI Location
Menu
> Settings > Data Enrichment > Exclude from Lookup > IP Subnets
Output
array
Parameters
None
Example
callAPI('GET','/integration_providers/ip_filters');
Enable the Assemble Partial Content feature
Upload the modified YARA file
API Path
/integration_providers/yara_upload
Description
Upload a modified YARA rules file
GUI Location
Menu
> Settings > Data Enrichment > YARA File Manager
Output
ApiResultCode
Parameters
None
PHP Example
callAPI('POST','/integration_providers/yara_upload',
'rules.yar'
);
169
Security Analytics Reference Guide
Security Analytics 8.1
Python Example
s.callAPI("POST","/integration_providers/yara_upload",
"rules.yar"
)
Restore the default YARA file
API Path
/integration_providers/yara_restore
Description
Restore the YARA rule file to its default state
GUI Location
Menu
> Settings > Data Enrichment > YARA File Manager
Output
ApiResultCode
Parameters
None
PHP Example
callAPI('POST','/integration_providers/yara_restore');
Python Example
s.callAPI("POST","/integration_providers/yara_restore")
Select the data-enrichment profile
API Path
/settings/system_services_profile
Description
Select the current data-enrichment (system services) profile
GUI Location
Menu
> Settings > Data Enrichment > Data Enrichment Profiles
Output
array
170
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
Format
Default
Valid Inputs
X
array
()
100 | 90 | 10
settings
Description
Data enrichment profile to select:
n
100 — Full Data Enrichment with
Anomaly Detection
n
90 — Full Data Enrichment (No
Anomaly Detection)
n
10 — Packets Only
Example
callAPI('POST','/settings/system_services_profile',
array => (
'settings' => 90
);
Enable or disable local file analysis providers
API Path
/integration_providers/local_file_analysis
Description
Activate or deactivate a local file analysis provider
GUI Location
Menu
> Settings > Data Enrichment > Local File Analysis > [provider entry]
Output
ApiResultCode
Parameters
localFileAnalysis
active
REQ
Format
Default
Valid Inputs
X
array
—
<GET: /integration_
providers/local_file_analysis>
Boolean
0 or
false
false | true
0 | 1
Example
callAPI('POST','/integration_providers/local_file_analysis',
array(
'localFileAnalysis => array(
'clam_av' => array(
171
Description
Names of local file
analysis providers
n
False or 0 —
Deactivate
n
True or 1 —
Activate
Security Analytics Reference Guide
Security Analytics 8.1
'active' => 1
),
'yara' => array(
'active' => false
)
)
)
);
Configure custom Web Reputation Service update location
API Path
/web_pulse/location
Description
Configure the custom Web Reputation Service update location
GUI Location
Menu
> Settings > Data Enrichment > Web Reputation Service Update Location
Output
Boolean
Parameters
REQ
interval
Format
Default
Valid Inputs
Description
integer
300
1–<n>
Boolean
true
true | false
url
string
—
<URL>
username
string
—
<UTF-8 characters>
Username to access the custom update
location
password
string
—
<UTF-8 characters>
Password to access the custom update
location
custom
Example
callAPI('POST','/web_pulse/location',
array(
'interval' => 900,
'custom' => true,
'url' => 'https://custom.update.com/updates',
'username' => '<username>',
'password' => '<password>'
)
);
172
Number of seconds between updates
True = Use the custom update location
URL of the custom update location
Security Analytics Reference Guide
Security Analytics 8.1
Trigger a manual Web Reputation Service update
API Path
/web_pulse/update
Description
Trigger an update of the Web Reputation Service database
GUI Location
Menu
> Settings > Data Enrichment > Web Reputation Service Update Location > Update button
Output
Boolean
Parameters
None
Example
callAPI('POST','/web_pulse/update');
Configure an integration provider
API Path
/integration_providers/save
Description
Create or edit an integration provider
GUI Location
Menu
> Settings > Data Enrichment > Third-Party Integration Providers
Output
string
Parameters
REQ
uuid
Format
Default
Valid Inputs
UUID | null
null
null | <GET: /integration_
providers/all_providers>
173
Description
n
Create new — Use null
n
Edit entry — UUID
required
Security Analytics Reference Guide
Security Analytics 8.1
REQ
Format
Default
Valid Inputs
X
string
—
<UTF-8 characters> | <GET:
/integration_providers/all_
providers>
name
username
X
string
—
<UTF-8 characters>
address
X
string
—
<dotted-decimal>
key
X
string
—
<hex>
Description
n
Create new — Name
required
n
Edit entry — New name
Administrator-level account on
the Malware Analysis appliance
IP address of the Malware
Analysis appliance
API key with admin-level
privileges, generated on the
Malware Analysis appliance
Example
callAPI(
'POST',
'/integration_providers/norman',
array(
'uuid' => null,
'name' => 'MAA-03',
'username' => 'maa_admin',
'address' => '203.0.113.5',
'key' => '<API_key_from_MA>'
)
);
Delete a Malware Analysis appliance
API Path
/integration_providers/norman_delete/<uuid>
Description
Delete the specified Malware Analysis entry
GUI Location
Menu
> Settings > Data Enrichment > Malware Analysis
Output
array
Parameters
uuid
REQ
Format
Default
Valid Inputs
X
UUID
—
<GET: /integration_
providers/norman>
Example
callAPI('POST','/integration_providers/delete/<provider_UUID>');
174
Description
UUID of the Malware Analysis
entry
Security Analytics Reference Guide
Security Analytics 8.1
Activate or deactivate an enrichment provider
API Path
/integration_providers/toggle/<uuid>
Description
Activate or deactivate an enrichment provider
GUI Location
Menu
> Settings > Data Enrichment > [provider entry]
Output
array
Parameters
uuid
REQ
Format
Default
Valid Inputs
X
UUID
—
<GET: /integration_providers/all_
providers>
Boolean
true
true | false
active
Example
callAPI('POST','/integration_providers/toggle/<provider_UUID>',
array(
'active' => false
)
);
Configure domain filters
API Path
/integration_providers/domain_filters
Description
Specify domains to be excluded from data-enrichment lookup
GUI Location
Menu
> Settings > Data Enrichment > Exclude from Lookup > Domains
Output
ApiResultCode
175
Description
UUID of enrichment
provider
n
true — Activate
n
false — Deactivate
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
domainFilters
REQ
Format
Default
Valid Inputs
X
string
—
<domain>
<domain>
<domain>
Description
List of domains, each on its own line
Example
callAPI('POST','/integration_providers/domainFilters',
*.soleranetworks.com
*.bluecoat.com
*.symantec.com
);
Configure IP filters
API Path
/integration_providers/ip_filters
Description
Specify IP addresses to be excluded from data-enrichment lookup; this list completely overwrites the previous
list
GUI Location
Menu
> Settings > Data Enrichment > Exclude from Lookup > IP Subnets
Output
ApiResultCode
Parameters
ipFilters
REQ
Format
Default
Valid Inputs
X
string
—
<[cidr]ip_address>
<[cidr]ip_address>
<[cidr]ip_address>
Example
callAPI('POST','/integration_providers/ipFilters',
127/8
10/8
172.16/12
169.254/16
192.168/16
);
Set Login Correlation Service IPs
API Path
/settings/adlistener
176
Description
IP addresses, each on its own line; CIDR
notation is permitted: 192.168/16
Security Analytics Reference Guide
Security Analytics 8.1
Description
Configure the allowed IPs for the Login Correlation Service
GUI Location
Menu
> Settings > Security > Login Correlation Service > LCS Agent IP
Output
ApiResultCode
Parameters
REQ
allowAllIp
ipList
X
Format Default
Boolean
array
Valid Inputs
—
—
true | false
<dotted-decimal>,<dotteddecimal>
Example
callAPI('POST','/settings/adlistener',
array(
'allowAllIp' => false,
'ipList' => array(
'192.0.2.200',
'203.0.113.5',
'198.51.100.98'
)
)
);
177
Description
n
true = Allow all IPs and ignore
ipList
n
false = Allow only IPs in ipList
Comma-delimited array of LCS agent
IPs to allow
Security Analytics Reference Guide
Security Analytics 8.1
Date/Time APIs
Get date and time settings
API Path
/settings/time
Description
Retrieve the date and time settings
GUI Location
Menu
> Settings > Date/Time
Output
array
Parameters
None
Example
callAPI('GET','/settings/time');
Get Greenwich Mean Time offsets
API Path
/settings/gmt_offsets
Description
Retrieve offset transition timestamps
GUI Location
n/a
Output
array
Parameters
None
Example
callAPI('GET','/settings/gmt_offsets');
178
Security Analytics Reference Guide
Security Analytics 8.1
Set the appliance time
API Path
/settings/time
Description
Set the time for the appliance
GUI Location
Menu
> Settings > Date/Time
Output
ApiResultCode
Parameters
REQ
Format
Default
Valid Inputs
X
string
—
<YYYY-MM-DD>T<hh:ii:ss>
time
Description
24-hour time to set
Example
callAPI('POST','/settings/time',
array(
'time' => '2019-11-03T08:30:00'
)
);
Set the time zone
API Path
/settings/timezone
Description
Set the time zone for the appliance; changing this setting will reboot the appliance.
GUI Location
Menu
> Settings > Date/Time
Output
ApiResultCode
Parameters
timezone
REQ
Format
Default
Valid Inputs
X
string
—
<IANA tz database>
179
Description
Time zone to set
Security Analytics Reference Guide
Security Analytics 8.1
Example
callAPI('POST','/settings/timezone',
array(
'timezone' => 'America/Argentina/Cordoba'
)
);
Configure NTP
API Path
/settings/ntp
Description
Configure Network Time Protocol settings
GUI Location
Menu
> Settings > Date/Time > Network Time Protocol
Output
ApiResultCode
Parameters
enable
REQ
Format
Default
Valid Inputs
X
Boolean
—
true | false
servers
X
array
()
ntp_address
X
string
—
<dotted-decimal>
Boolean
0
0| 1
ntp_encrypt
password
generateKeys
Description
n
True — Enable NTP
n
False — Disable NTP
Array of up to 3 NTP servers; array contains
ntp_address and ntp_encrypt
string
—
<UTF8 characters>
Boolean
false
true | false
IP address of NTP server
Whether to use Autokey encryption
n
0 — Do not use Autokey
n
1 — Use Autokey
Group key password; required if ntp_
encrypt=1
n
True — Generate NTP host keys
n
False — Do not generate keys
serverFile1
file
null
<filepath>
Path to primary group key file; valid only if
generateKeys=false
serverFile2
file
null
<filepath>
Path to secondary group key file; valid only if
generateKeys=false
180
Security Analytics Reference Guide
REQ
serverFile3
Security Analytics 8.1
Format
Default
Valid Inputs
Description
file
null
<filepath>
Path to tertiary group key file; valid only if
generateKeys=false
Example 1
Enable NTP and specify three servers
callAPI('POST','/settings/ntp',
array(
'enable' => true,
'servers' => array(
array(
'ntp_address'
'ntp_encrypt'
)
array(
'ntp_address'
'ntp_encrypt'
)
array(
'ntp_address'
'ntp_encrypt'
)
),
)
);
=> '203.0.113.5',
=> 0
=> '203.0.113.6',
=> 0
=> '203.0.113.7',
=> 0
Example 2
Enable NTP encryption and upload the key files
callAPI('POST','/settings/ntp',
array(
'servers' => array(
array(
'ntp_address' => '203.0.113.5',
'ntp_encrypt' => 1
)
array(
'ntp_address' => '203.0.113.6',
'ntp_encrypt' => 1
)
array(
'ntp_address' => '203.0.113.7',
'ntp_encrypt' => 1
)
),
'password' => '33aks3snTp@*',
'generateKeys' => false,
'serverFile1' => 'ntpkey_iff_www.trustedserver1.com',
'serverFile2' => 'ntpkey_iff_www.trustedserver2.com',
'serverFile3' => 'ntpkey_iff_www.trustedserver3.com'
)
);
181
Security Analytics Reference Guide
Security Analytics 8.1
Drive-Space Management APIs
Get saved extractions
API Path
/saved
Description
Retrieve a list of saved extractions
GUI Location
Menu
> Analyze > Saved Extractions
Output
array
Parameters
REQ
Format
Default
Valid Inputs
page
integer
1
1–<n>
Page to retrieve; first page is 1
pageSize
integer
25
1–100
Number of items per page
sort
string
start
start | end | name | percent |
status
direction
string
desc
asc | desc
Example
callAPI('GET','/saved',
array(
'page' => 10,
'pageSize' => 20,
'sort' => 'status',
'direction' => 'asc'
)
);
Get URL to a saved extraction
API Path
/saved/url/<id>
Description
Generate a URL to access a saved extraction
GUI Location
Menu
> Analyze > Saved Extractions > View extraction icon
182
Description
Sort-by field
Sort direction
Security Analytics Reference Guide
Security Analytics 8.1
Output
string
Parameters
REQ
id
X
Format
Default
string
Valid Inputs
—
<GET: /saved>
Example
callAPI('GET','/saved/url/255');
Get data retention-settings
API Path
/settings/data_retention
Description
Retrieve data-retention settings
GUI Location
About
> Data-Retention Settings
Output
array
Parameters
None
Example
callAPI('GET','/settings/data_retention');
Get home-drive size
API Path
/home_size
Description
Retrieve disk space and inode usage of /home
GUI Location
Menu
> Analyze > Saved Extractions
183
Description
ID of the saved result
Security Analytics Reference Guide
Security Analytics 8.1
Output
array
Parameters
None
Example
callAPI('GET','/home_size');
Delete a saved extraction
API Path
/saved/delete
Description
Delete a saved extraction
GUI Location
Menu
> Analyze > Saved Extractions
Output
ApiResultCode
Parameters
REQ
Format
Default
Valid Inputs
X
array
—
<GET: /saved>
ids
Example
callAPI('POST','/saved/delete',
array(
'ids' => array(
'<ID-1>',
'<ID-2>',
'<ID-3>'
)
)
);
Configure data-retention settings
API Path
/settings/data_retention
Description
Configure data-retention settings
184
Description
IDs of results to delete
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
About
> Data-Retention Settings
Output
ApiResultCode
Parameters
REQ
Format
Default
Valid Inputs
Description
integer
0
0–12
Number of
months that
Capture
Summary
Chart data
is retained.
Boolean
false
true | false
True —
Enable
time-based
data
deletion
time_deletion_limit_days
integer
0
0–<n>
Number of
days to
retain data
time_deletion_limit_hours
string/integer
0
0–<n>
Number of
hours to
retain data
Boolean
false
true | false
True —
Delete
saved
reports and
artifacts
summary_life
time_deletion_enabled
time_deletion_artifacts
Example
callAPI('POST','/settings/data_retention',
array(
'summary_life' => 6,
'time_deletion_enabled' => true,
'time_deletion_limit_days' => 180,
'time_deletion_limit_hours' => 0,
'time_deletion_artifacts' => true
)
);
185
Security Analytics Reference Guide
Security Analytics 8.1
Extractor APIs
Get HTTP proxy assembly state — NEW
API Path
/settings/extractor_enable_partial_content_reconstruction
Description
Retrieve the state of proxy data reconstruction
GUI Location
Menu
> Settings > System > Enable proxy data
Parameters
None
PHP Example
callAPI('GET','/settings/extractor_enable_proxy_data_reconstruction');
Python Example
s.callAPI("GET","/settings/extractor_enable_proxy_data_reconstruction")
Output
'result': {'ExtractorSetting': {'proxy_data_reconstruction': [0|1]}},
'resultCode': 'API_SUCCESS_CODE',
Initiate extraction — MODIFIED
The output for this API has changed. See Extractions API Changes for more
information.
API Path
/artifacts/artifacts
Description
Initiate artifact extraction on the specified, filtered timespan.
GUI Location
Menu
> Analyze > Summary > Extractions
186
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
Format
Default
Valid Inputs
X
string |
integer
—
<identity path>
page
integer
1
1–<n>
Page to request; first page is 1
pageSize
integer
25
1–100
Number of artifacts per page
filters
array
—
<advanced filter array>
sort
string
date
sortDirection
string
ASC
ASC | DESC
restart
Boolean
false
true | false
True — Run the extraction again
countOnly
Boolean
false
true | false
True — Get only the number
(count) of artifacts
mediapanel
string | null
null
small | medium | large |
null
identityPath
Description
One of several identifying values
Advanced filter attributes
date | source | type |
Sort-by column; sender, recipient,
size | sender | recipient and subject are valid only for
| subject
email artifacts
Sort order
Size of thumbnails:
n
small — 50 pixels
n
medium — 100 pixels
n
large — 150 pixels
n
null — Do not generate
thumbnails
PHP Example
callAPI('GET','/artifacts/artifacts',
array(
'identityPath' => '/timespan/2019-09-17T14:25:00-07:00_2019-09-17T14:30:00-07:00',
'page' => 1,
'pageSize' => 20,
'filters' => array(
'all' => array(
array(
'key' => 'ip_address',
'comp' => '=',
'value' => '203.0.113.5'
),
array(
'any' => array(
array(
'key' => 'port',
'comp' => '=',
'value' => 80
),
array(
'key' => 'keyword',
'comp' => '~',
'value' => 'symantec'
)
)
)
),
187
Security Analytics Reference Guide
Security Analytics 8.1
'sort' => 'date'
)
)
);
Python Example
s.callAPI("GET","/artifacts/artifacts", {
'identityPath': '/timespan/2019-09-17T14:25:00-07:00_2019-09-17T14:30:00-07:00',
'page': 1,
'pageSize': 20,
'filters': {
'all': {
{
'key': 'ip_address',
'comp': '=',
'value': '203.0.113.5'
},
{
'any': {
{
'key': 'port',
'comp': '=',
'value': 80
},
{
'key': 'keyword',
'comp': '~',
'value': 'symantec'
}
}
}
},
'sort': 'date'
}
}
)
Initial Output
{'artifact_search_id': <integer>,
'background': [True|False],
'field_counts': {'file_extension': [], 'file_type': []},
'histogram': {'data': [{'columns': [0],
'extra': {'end_time': <epoch>},
'time': <epoch>}],
'meta': {'columns': [{'has_total': ['true'|'false'],
'text': 'Artifacts',
'type': 'magnitude'}],
'data_type': {'text': 'Artifacts',
'type': 'magnitude'}},
'total': [0]},
'killed': [True|False],
'maxpage': 0,
'numFilteredArtifacts': 0,
'numResults': 0,
'percentcomplete': '0',
'search_status': 'extractor.status.waiting',
'sorted_artifacts': [],
'timeDeleted': [True|False],
'time_place': <epoch>}
188
Security Analytics Reference Guide
Security Analytics 8.1
This API does not return data after the first API request. You must poll the
appliance in the meantime to incrementally retrieve the data. See "Using Polling
with the APIs" on page 415 for more information.
Completed Output
'result': {'artifact_search_id': <integer>,
'background': [True|False],
'field_counts': {'file_extension': {'7z': [1],
'apk': [1],
...
'xml': [2],
'zip': [5]},
'file_type': {'application/bat': [0, 3],
'application/email': [53, 53],
...
'video/x-ms-wmv': [18, 0],
'video/x-msvideo': [0, 1]}},
'histogram': {'data': [{'columns': [<integer>],
'extra': {'end_time': <epoch>},
'time': <epoch>},
...
{'columns': [<integer>],
'extra': {'end_time': <epoch>},
'time': <epoch>}],
'meta': {'columns': [{'has_total': 'true',
'text': 'Artifacts',
'type': 'magnitude'}],
'data_type': {'text': 'Artifacts',
'type': 'magnitude'}},
'total': [<integer>]},
'killed': [True|False],
'maxpage': <integer>,
'numFilteredArtifacts': <integer>,
'numResults': <integer>,
'percentcomplete': '100',
'search_status': 'extractor.status.finished',
'sorted_artifacts': [{'Artifact': {'appliance_id': <integer>,
'artifact_search_id': <integer>,
'capture_end_nanoseconds': <integer>,
'capture_end_time': <epoch>,
'capture_start_nanoseconds': <integer>,
'capture_start_time': <epoch>,
'derived_type': '<presented MIME type>',
'destination_ip': '<ip>',
'destination_port': <port>,
'extension': '<ext>',
'filename': '/home/apache/artifacts/<extraction_
id>/<hostname>.dscapture.net_<YYYY-MM-DD>T<hh.mm.ss-zzzz>_<initiator_ip><initiator_port>_<responder_ip>-<responder_port>_<filename>.<ext>',
'filesize': <integer>,
'flow_id': <integer>,
'fuzzy': '<fuzzy_hash>',
'height': <integer>,
'host': '<hostname>',
'hw_ratio': <integer>,
'icon': '<string>',
'id': <integer>,
'magic_type': '<detected_MIME_type>',
'md5': '<md5_hash>',
'meta_info': {'filename': '',
189
Security Analytics Reference Guide
Security Analytics 8.1
'response_code': <integer>,
'response_headers': 'HTTP/1.1 '
'<response code>'
'OK\r\n'
'Server: '
'Apache\r\n'
'ETag: '
'<hex>:<epoch>\r\n'
'Last-Modified: '
'<day>, '
'<DD-mmm-YYYY> '
'<hh:ii:ss> '
'GMT\r\n'
'Accept-Ranges: '
'bytes\r\n'
'Content-Length: '
'<integer>\r\n'
'Content-Type: '
'<MIME_type>\r\n'
'Date: '
'<day>, '
'<DD-mmm-YYYY> '
'<hh:ii:ss> '
'GMT\r\n'
'Connection: '
'Keep-Alive\r\n'
'\r\n'},
'mime_type': '<presented_MIME_type>',
'pcap_path': '/timespan/<YYYY-MM-DD>T<hh.mm.ss-zzzz>_<YYYY-MMDD>T<hh.mm.ss-zzzz>/flow_id_packet/<integer>',
'protocol': '<protocol>',
'referer': [None|<URL>],
'remote_artifact_id': <integer>,
'session_id': <extraction_ID>,
'sha1': '<SHA1_hash>',
'sha256': '<SHA256_hash>',
'source_ip': '<ip>',
'source_port': <port>,
'title': '<filename>',
'wh_ratio': <integer>,
'width': <integer>}},
...
'timeDeleted': False,
'time_place': <epoch>},
'resultCode': 'API_SUCCESS_CODE',
Get a list of all extractions
API Path
/deepsee/all_extractions
Description
Retrieve a list of all extractions on the Extraction Status page.
190
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
Menu
> Analyze > Extraction Status
Parameters
None
PHP Example
callAPI('GET','/deepsee/all_extractions',);
Python Example
s.callAPI("GET","/deepsee/all_extractions")
Output
'result': {'rows': [{'appliance_ids': '',
'as_status': '<status>',
'bytes_read': <integer>,
'db_size': <size>,
'disk_size': <integer>,
'end': 'YYYY-MM-DD hh:ii:ss.000000',
'id': <integer>,
'name': '<name>',
'pcap': '/pfs/flows/timespan/YYYY-MM-DDThh:ii:ss-zz:zz_YYYY-MMDDThh:ii:ss-zz:zz/data.pcapng',
'percent': <integer>,
'results': <integer>,
'start': 'YYYY-MM-DD hh:ii:ss.999999',
'status': '<status>',
'user_name': '<username>'}]}
Get paginated list of extractions
API Path
/deepsee/status
Description
Retrieve a paginated list of the fields on the Extraction Status page.
GUI Location
Menu
> Analyze > Extraction Status
Parameters
REQ
Format
Default
Valid Inputs
page
integer
1
1–<n>
Number of pages to retrieve; first
page is 1.
pageSize
integer
25
1–100
Number of entries per page
191
Description
Security Analytics Reference Guide
REQ
Security Analytics 8.1
Format
Default
Valid Inputs
sort
string
start
start | name | status |
percent | created_by | id
direction
string
DESC
ASC | DESC
Description
Sort-by column
Sort order
PHP Example
callAPI('GET','/deepsee/status',
array(
'page' => 10,
'pageSize' => 20,
'sort' => 'percent',
'sortDirection' => 'ASC'
)
);
Python Example
s.callAPI("GET","/deepsee/status", {
'page': 10,
'pageSize': 20,
'sort': 'percent',
'sortDirection': 'ASC'
}
)
Output
'paging': {'Extraction': {'count': <integer>,
'current': <integer>,
'limit': <integer>,
'nextPage': [True|False],
'options': {'conditions': [],
'order': {'<field>': '[asc|desc]'}},
'order': {'<field>': '[asc|desc]'},
'page': <integer>,
'pageCount': <integer>,
'paramType': '<string>',
'prevPage': [True|False]}},
'result': {'pageCount': <integer>,
'rows': [{'appliance_ids': '',
'as_status': '<status>',
'bytes_read': <integer>,
'db_size': <integer>,
'disk_size': <integer>,
'end': 'YYYY-MM-DD hh:ii:ss.000000',
'id': <integer>,
'name': '<string>',
'pcap': '/pfs/flows/timespan/YYYY-MM-DDThh:ii:ss-zz:zz_YYYY-MMDDThh:ii:ss-zz:zz/data.pcapng',
'percent': <integer>,
'results': <integer>,
'start': 'YYYY-MM-DD hh:ii:ss.999999',
'status': '<string>',
'user_name': '<string>'}]}
Get artifact details
API Path
/artifacts/details
192
Security Analytics Reference Guide
Security Analytics 8.1
Description
Retrieve details about an artifact
GUI Location
Menu
> Analyze > Summary > Extractions > [artifact entry]
Parameters
REQ
artifactIDs
searchID
Format Default
Valid Inputs
array
—
<GET: /artifacts/artifacts>
integer
null
null | <GET:
/artifacts/artifacts>
PHP Example
callAPI('GET','/artifact/details',
array(
'artifactIDs' => array(
<artifact_ID-1>,
<artifact_ID-2>,
<artifact_ID-3>
),
'searchID' => '<search_ID>'
)
);
Python Example
s.callAPI("GET","/artifact/details", {
'artifactIDs': [
<artifact_ID-1>,
<artifact_ID-2>,
<artifact_ID-3>
],
'searchID': '<search_ID>'
}
)
Output
array
Download artifacts
API Path
/artifacts/download
Description
Download one or more artifacts
193
Description
An array of artifact IDs
Extraction ID
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
Menu
> Analyze > Summary > Extractions > [artifact entry] > Download
Parameters
REQ
ids
searchId
X
type
mode
Format Default Valid Inputs
Description
array
—
<GET: /artifacts/artifacts>
Array of artifact IDs
integer
—
<GET: /artifacts/artifacts>
Extraction ID
string
zip
zip | ogg | wav | single
string
—
synth_audio
PHP Example 1
Download All Artifacts from an Extraction as a ZIP File
callAPI('GET','/artifacts/download',
array(
'searchId' => <searchId>,
),
'<filename>.zip'
);
Python Example 1
Download All Artifacts from an Extraction as a ZIP File
callAPI("GET","/artifacts/download", {
'searchId': <searchId>,
},
'<filename>.zip'
)
PHP Example 2
Download Selected VoIP Artifacts in OGG Format
callAPI('GET','/artifacts/download',
array(
'ids' => array(
<id-1>,
<id-2>,
<id-3>
),
'searchId' => <searchId>,
'type' => 'ogg',
194
File type to download
n
If there are more ids than one,
then type=zip; else type=single
n
If mode=synth_audio then default
type=ogg else default type=single
synth_audio — Artifact is a VoIP and will
be downloaded with both sides of the
conversation included
Security Analytics Reference Guide
Security Analytics 8.1
'mode' => 'synth_audio'
),
'<filename>.ogg'
);
Python Example 2
Download Selected VoIP Artifacts in OGG Format
s.callAPI("GET","/artifacts/download", {
'ids': [
<id-1>,
<id-2>,
<id-3>
],
'searchId': <searchId>,
'type': 'ogg',
'mode': 'synth_audio'
},
'<filename>.ogg'
)
Output
<filename>.<ext>
Get artifact timeline information
API Path
/artifacts/timeline
Description
Retrieve timeline information about the artifacts
GUI Location
Menu
> Analyze > Summary > Extractions > Artifact Timeline
Output
array
Parameters
REQ
Format
Default
Valid Inputs
identityPath
X
string |
integer
—
<identity path>
filters
X
array
—
<advanced filter array>
page
integer
1
1–<n>
Number of pages to retrieve; first
page is 1.
pageSize
integer
25
1–100
Number of entries per page
195
Description
One of several identifying values
Advanced filter attributes
Security Analytics Reference Guide
REQ
Security Analytics 8.1
Format
Default
Valid Inputs
sort
string
date
date | source | type |
size
sortDirection
string
ASC
ASC | DESC
Boolean
false
true | false
restart
Description
Sort-by column
Sort order
True — Run the extraction again
PHP Example
callAPI('GET','/artifacts/timeline',
array(
'identityPath' => <searchID>,
'page' => 10,
'pageSize' => 20,
'filters' => array(
'port=80',
'port=443',
'application_id=tcp,http'
)
'restart' => true,
'sort' => 'type',
'sortDirection' => 'DESC'
)
);
Python Example
s.callAPI("GET","/artifacts/timeline", {
'identityPath':<searchID>,
'page': 10,
'pageSize': 20,
'filters': [
'port=80',
'port=443',
'application_id=tcp,http'
]
'restart': True,
'sort': 'type',
'sortDirection': 'DESC'
}
)
Output
'result': {'artifactGroups': [{'group': '<[ip|port|filetype>',
'history': [{'Artifact': {'capture_start_time': <epoch>,
'destination_ip': '<ip>',
'extension': '<string>',
'host': '<hostname>',
'icon': '<string>',
'id': <integer>,
'magic_type': '<detected_MIME_type>',
'source_ip': '<ip>',
'title': '<filename>'}}],
'numArtifacts': <integer>},
...
'artifact_search_id': <integer>,
'background': [True|False],
'field_counts': {'file_extension': {'7z': [1],
'apk': [1],
...
'xml': [2],
'zip': [5]},
196
Security Analytics Reference Guide
Security Analytics 8.1
'file_type': {'application/bat': [0, 3],
'application/email': [53, 53],
...
'video/x-ms-wmv': [18, 0],
'video/x-msvideo': [0, 1]}},
'histogram': {'data': [{'columns': [<integer>],
'extra': {'end_time': <epoch>},
'time': <epoch>},
...
{'columns': [<integer>],
'extra': {'end_time': <epoch>},
'time': <epoch>}],
'meta': {'columns': [{'has_total': 'true',
'text': 'Artifacts',
'type': 'magnitude'}],
'data_type': {'text': 'Artifacts',
'type': 'magnitude'}},
'total': [<integer>]},
'killed': [True|False],
'maxpage': <integer>,
'numFiltered': <integer>,
'numResults': <integer>,
'percentcomplete': '100',
'searchID': <integer>,
'search_status': 'extractor.status.finished',
'timeDeleted': [True|False],
'time_place': <epoch>},
'resultCode': 'API_SUCCESS_CODE',
Get jsunpack-n preview
API Path
/preview/jsunpackn
Description
Run jsunpack-n on one or more artifacts
GUI Location
Menu
> Analyze > Summary > Extractions > [artifact entry] > Preview > jsunpack-n
Parameters
REQ
Format
Default
Valid Inputs
X
integer
—
<GET:
/artifacts/artifacts>
artifactId
PHP Example
callAPI('GET','/preview/jsunpackn',
array(
'artifactId' => array(
<ID1>,
<ID2>,
<ID3>
)
)
197
Description
ID of the artifact(s) to run through
jsunpack-n
Security Analytics Reference Guide
Security Analytics 8.1
);
Python Example
s.callAPI("GET","/preview/jsunpackn", {
'artifactId': [
<ID1>,
<ID2>,
<ID3>
]
}
)
Output
'result': ['[malicious:<integer>] [<EXT>] <filename>',
'<jsunpack-n results>'],
'resultCode': 'API_SUCCESS_CODE',
Get signature extraction state
API Path
/settings/extractor_enable_signature_extractor
Description
Retrieve the state of signature extraction
GUI Location
Menu
> Settings > System > Extraction Settings > Enable signature-based extraction
Output
integer | false
Parameters
None
PHP Example
callAPI('GET','/settings/extractor_enable_signature_extractor');
Python Example
s.callAPI("GET","/settings/extractor_enable_signature_extractor")
Output
'result': [0|1],
'resultCode': 'API_SUCCESS_CODE',
Get MD5 hash calculation state
API Path
/settings/extractor_enable_md5
198
Security Analytics Reference Guide
Security Analytics 8.1
Description
Retrieve the state of MD5 hash calculation
GUI Location
Menu
> Settings > System > Extraction Settings > Hash Computation > MD5
Parameters
None
PHP Example
callAPI('GET','/settings/extractor_enable_md5');
Python Example
s.callAPI("GET","/settings/extractor_enable_md5")
Output
'result': [0|1],
'resultCode': 'API_SUCCESS_CODE',
Get SHA1 hash calculation state
API Path
/settings/extractor_enable_sha1
Description
Retrieve the state of SHA1 hash calculation
GUI Location
Menu
> Settings > System > Extraction Settings > Hash Computation > SHA1
Parameters
None
PHP Example
callAPI('GET','/settings/extractor_enable_sha1');
Python Example
s.callAPI("GET","/settings/extractor_enable_sha1")
Output
'result': [0|1],
'resultCode': 'API_SUCCESS_CODE',
199
Security Analytics Reference Guide
Security Analytics 8.1
Get SHA256 hash calculation state
API Path
/settings/extractor_enable_sha256
Description
Retrieve the state of SHA256 hash calculation
GUI Location
Menu
> Settings > System > Extraction Settings > Hash Computation > SHA256
Output
integer | false
Parameters
None
PHP Example
callAPI('GET','/settings/extractor_enable_sha256');
Python Example
s.callAPI("GET","/settings/extractor_enable_sha256")
Output
'result': [0|1],
'resultCode': 'API_SUCCESS_CODE',
Get fuzzy hash calculation state
API Path
/settings/extractor_enable_fuzzy
Description
Retrieve state of fuzzy hash calculation
GUI Location
Menu
> Settings > System > Extraction Settings > Hash Computation > Fuzzy
Parameters
None
PHP Example
callAPI('GET','/settings/extractor_enable_fuzzy');
200
Security Analytics Reference Guide
Security Analytics 8.1
Python Example
s.callAPI("GET","/settings/extractor_enable_fuzzy")
Output
'result': [0|1],
'resultCode': 'API_SUCCESS_CODE',
Get partial-content assembly state
API Path
/settings/extractor_enable_partial_content_reconstruction
Description
Retrieve the state of partial content assembly
GUI Location
Menu
> Settings > System > Assemble Partial Content
Parameters
None
PHP Example
callAPI('GET','/settings/extractor_enable_partial_content_reconstruction');
Python Example
s.callAPI("GET","/settings/extractor_enable_partial_content_reconstruction")
Output
'result': {'ExtractorSetting': {'partial_content_reconstruction': [0|1]}},
'resultCode': 'API_SUCCESS_CODE',
Get fragment-display state
API Path
/settings/extractor_enable_fragment_reconstruction
Description
Retrieve the state of fragment reconstruction
GUI Location
Menu
> Settings > System > Extraction Settings > Display fragments
Parameters
None
201
Security Analytics Reference Guide
Security Analytics 8.1
PHP Example
callAPI('GET','/settings/extractor_enable_fragment_reconstruction');
Python Example
s.callAPI("GET","/settings/extractor_enable_fragment_reconstruction")
Output
'result': [0|1],
'resultCode': 'API_SUCCESS_CODE',
Get extractor tuning parameters
API Path
/settings/extractor_prototune
Description
Retrieve the protocol-tuning settings
GUI Location
Menu
> Settings > System > Extraction Settings > Extractor Tuning Parameters
Parameters
None
PHP Example
callAPI('GET','/settings/extractor_prototune');
Python Example
s.callAPI("GET","/settings/extractor_prototune")
Output
'result': {'ExtractorSetting': {'prototune': '<prototune settings>'}, 'validationErrors': []},
'resultCode': 'API_SUCCESS_CODE',
Sanitize CSS
API Path
/artifacts/sanitize_css/<artifactId>
Description
Removes external JavaScript URLs from CSSs
GUI Location
Menu
> Analyze > Summary > Extractions > [HTML artifact] > Preview > Web Page > View Options
202
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
artifactId
Format Default
X
integer
—
Valid Inputs
Description
<GET: /artifacts/artifacts>
ID of artifact
PHP Example
callAPI('GET','/artifacts/sanitize_css/<artifactId>');
Python Example
s.callAPI("GET","/artifacts/sanitize_css/<artifactId>")
Output
array
Sanitize HTML page by artifact ID
API Path
/artifacts/sanitize_html/<artifactId>
Description
Sanitizes HTML artifacts (web pages) so that external scripts, images, and CSSs can be omitted. If the external
preview setting is disabled it will force all externals to be hidden.
n
hide — Completely remove the external URL
n
captureData — Attempt to show the item as a captured artifact; if none is found, default to hide
n
external — Use the absolute URL (including host) for the artifact.
GUI Location
Menu
> Analyze > Summary > Extractions > [HTML artifact] > Preview > Web Page > View Options
Output
string
Parameters
REQ
Format Default
Valid Inputs
Description
artifactId
X
integer
—
<GET: /artifacts/artifacts>
ID of the artifact
cssSource
X
string
—
hide | captureData | external
Source of CSSs
scriptSource
X
string
—
hide | captureData | external
Source of scripts
imageSource
X
string
—
hide | captureData | external
Source of images
PHP Example
callAPI('GET','/artifacts/sanitize_html/<artifactId>',
203
Security Analytics Reference Guide
Security Analytics 8.1
array(
'cssSource' => 'external',
'scriptSource' => 'captureData',
'imageSource' => 'hide'
)
);
Python Example
s.callAPI("GET","/artifacts/sanitize_html/<artifactId>", {
'cssSource': 'external',
'scriptSource': 'captureData',
'imageSource': 'hide'
}
);
Sanitize HTML text
API Path
/artifacts/sanitize_html_text
Description
Sanitize HTML text
GUI Location
Menu
> Analyze > Summary > Extractions > [HTML artifact] > Preview > Web Page > View Options
Output
string
Parameters
REQ
html
Format Default
X
array
—
Valid Inputs
Description
<HTML text>
HTML text
PHP Example
callAPI('GET','/artifacts/sanitize_html_text',
array(
'html' => '<html><head><title>HTML Page
Sample</title></head><body><h1>Sample Heading1</h1><p>text</p></body></html>'
)
);
Python Example
s.callAPI("GET","/artifacts/sanitize_html_text", {
'html': '<html><head><title>HTML Page
Sample</title></head><body><h1>Sample Heading1</h1><p>text</p></body></html>'
}
)
204
Security Analytics Reference Guide
Security Analytics 8.1
Generate an audio file
API Path
/artifacts/synth_audio
Description
Generates an audio file (usually VoIP) from one or more existing audio artifacts. If the target file exists, synth_
audio_artifact will not generate a new one unless force=true.
GUI Location
Menu
> Analyze > Summary > Extractions > [audio artifact] > Download
Output
array
Parameters
REQ
Format Default
files
X
array
—
path
X
string
—
string
ogg
type
codec
force
string
Boolean
Vorbis
false
Valid Input
Description
Array of files to combine into a single audio file;
contains path, type, codec
/home/apache/artifacts/
Path to input file
<integer>/<filename>.<ext>
ogg | wav | raw
ulaw | alaw | Vorbis
true | false
Requested output file type:
n
ogg — Output is Vorbis
n
wav — Output is PCM Signed-Integer
Codec used. Supported codecs:
n
ulaw — raw: pcm μ-law, audio/PCMU
n
alaw — raw: pcm A-law, audio/PCMA
True — Generate a new file even if a file already
exists
PHP Example
callAPI('GET','/artifacts/synth_audio',
array(
'files' => array(
array(
'path' => '/home/apache/artifacts/25/mysound-00.wav',
'type' => 'wav',
'codec' => 'ulaw'
),
array(
'path' => '/home/apache/artifacts/25/mysound-01.wav',
'type' => 'wav',
'codec' => 'ulaw'
)
)
), '<filename>.wav'
205
Security Analytics Reference Guide
Security Analytics 8.1
);
Python Example
s.callAPI("GET","/artifacts/synth_audio",{
'files':{
{
'path': '/home/apache/artifacts/25/mysound-00.wav',
'type': 'wav',
'codec': 'ulaw'
},
{
'path': '/home/apache/artifacts/25/mysound-01.wav',
'type': 'wav',
'codec': 'ulaw'
}
}
}, '<filename>.wav'
)
Get IM conversations
API Path
/artifacts/im_conversations
Description
Retrieve reconstructed instant messaging conversations
GUI Location
Menu
> Analyze > Summary > Extractions > IM Conversations
Output
array
Parameters
REQ
Format
Default
Valid Inputs
X
string |
integer
—
<identity path>
One of several identifying values
page
integer
1
1–<n>
Number of pages to retrieve; first
page is 1
pageSize
integer
25
1–100
Number of entries per page
filters
array
—
<advanced filter array>
restart
Boolean
false
true | false
string
date
date | source | type |
size | sender | recipient
| subject
identityPath
sort
206
Description
Advanced filter attributes
True — Restart the extraction
that is associated with the artifact
search
Sort-by column
Security Analytics Reference Guide
REQ
sortDirection
Security Analytics 8.1
Format
Default
Valid Inputs
string
ASC
ASC | DESC
PHP Example
callAPI('GET','/artifacts/im_conversations',
array(
'identityPath' => <searchID>,
'page' => 10,
'pageSize' => 20,
'filters' => array(
'port=80',
'port=443',
'application_id=tcp,http'
)
'restart' => false,
'sort' => 'size',
'sortDirection' => 'DESC'
)
);
Python Example
s.callAPI("GET","/artifacts/im_conversations", {
'identityPath': <searchID>,
'page': 10,
'pageSize': 20,
'filters': [
'port=80',
'port=443',
'application_id=tcp,http'
]
'restart': False,
'sort': 'size',
'sortDirection': 'DESC'
}
)
Get IM user image
API Path
/im_user/<userId>
Description
Retrieve the captured IM image for the user
GUI Location
Menu
> Analyze > Summary > Extractions > IM Conversations > Preview
Output
ApiResultCode
207
Description
Sort order
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
userId
REQ
Format
Default
Valid Inputs
X
integer/string
—
<GET: /im_conversation> |
default
Boolean
false
true | false
large
Description
ID of the user or default for the
default image.
n
True — Full-sized image
n
False — Thumbnail version
PHP Example
callAPI('GET','/im_user/<userId>',
array(
'large' => true
)
);
Python Example
s.callAPI("GET",'/im_user/<userId>",{
'large': True
}
)
Download thumbnail
API Path
/thumbnails/<searchId>/<artifactor>
Description
Download an artifact thumbnail image
GUI Location
Menu
> Analyze > Summary > Extractions > Media Panel
Output
ApiResultCode
Parameters
REQ
Format
Default
Valid Inputs
Description
searchId
X
integer
—
<GET: /artifacts/artifacts>
Artifact search ID
artifactor
X
string
—
<artifactID>_<last12SHA1>_
[small | medium | large].
[jpg | gif | tif | png]
String made up of the artifact ID, the last
12 characters of the artifact's SHA1
hash, the desired thumbnail size, and
the file extension.
PHP Example
callAPI('GET','/thumbnails/<searchId>/'333_3e5fcb55213c_small.jpg');
208
Security Analytics Reference Guide
Security Analytics 8.1
Python Example
s.callAPI("GET","/thumbnails/<searchId>/'333_3e5fcb55213c_small.jpg")
Get root cause
API Path
/rootcause/<id>/<artifactSearchId>
Description
Retrieve an artifact's referrer chain. It will first find the entire referrer chain for that artifact. If referrers are found
then it also searches for IM conversations that contain the referrer URL in the message.
GUI Location
Menu
> Analyze > Summary > Extractions > [artifact entry] > Explore Root Cause
Output
array
Parameters
REQ
Format
Default
Valid Inputs
id
X
integer
—
<GET:
/artifacts/artifacts>
Artifact ID
artifactSearchId
X
integer
—
<GET:
/artifacts/artifacts>
Artifact search ID
PHP Example
callAPI('GET','/rootcause/<id>/<artifactSearchId>');
Python Example
s.callAPI("GET","/rootcause/<id>/<artifactSearchId>")
Set HTTP proxy assembly state — NEW
API Path
/settings/extractor_enable_proxy_data_reconstruction
Description
Set the state for proxy data assembly.
GUI Location
Menu
> Settings > System
209
Description
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
state
Format Default
X
Boolean
—
Valid Inputs
Description
true | false
True — Enable proxy data assembly
PHP Example
callAPI('POST','/settings/extractor_enable_proxy_data_reconstruction',
array (
'state' => true
)
);
Python Example
s.callAPI("POST","/settings/extractor_enable_proxy_data_reconstruction", {
'state': True
}
)
Output
API_SUCCESS_CODE
Save an extraction — MODIFIED
API Path
/artifacts/save/<id>
Description
Save an extraction to the Menu
> Analyze > Extraction Status page
GUI Location
Menu
> Analyze > Summary > Extractions
Output
null
Parameters
REQ
Format Default
Valid Inputs
searchId
X
integer
—
<GET: /artifacts/artifacts>
name
X
string
—
<UTF-8 characters>
PHP Example
callAPI('POST','/artifacts/background/<searchId>',
array(
'name' => 'extraction1'
)
);
Python Example
s.callAPI("POST","/artifacts/background/<searchId>", {
'name': 'extraction1'
210
Description
Artifact search ID
Specify a name for the search
Security Analytics Reference Guide
Security Analytics 8.1
}
)
Stop an incomplete extraction
API Path
/artifacts/stop/<searchId>
Description
Stop an extraction in progress.
GUI Location
Menu
> Analyze > Summary > Extractions
Output
null
Parameters
REQ
searchId
X
Format Default
integer
—
Valid Inputs
<
GET: /artifacts/artifacts
>|<GET: /artifacts/im_
conversations>
PHP Example
callAPI('POST','/artifacts/stop/<searchId>');
Python Example
s.callAPI("POST","/artifacts/stop/<searchId>")
Delete a saved extraction
API Path
/artifacts/delete/<searchId>
Description
Delete the saved extraction
GUI Location
Menu
> Analyze > Extraction Status
Output
array
211
Description
Artifact search ID
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
searchId
Format Default
X
string
—
Valid Inputs
Description
<GET: /artifacts/artifacts>
Extraction ID
PHP Example
callAPI('POST','/artifacts/delete/<searchId>');
Python Example
s.callAPI("POST","/artifacts/delete/<searchId>")
Delete all extractions
API Path
/extractions/delete
Description
Delete all extractions that are on the Extraction Status page.
GUI Location
Menu
> Settings > Upgrade > Update Precheck button > Delete Extractions
Parameters
None
PHP Example
callAPI('POST','/extractions/delete');
Python Example
s.callAPI("POST","/extractions/delete")
Output
integer | false
Set partial-content assembly state
API Path
/settings/extractor_enable_partial_content_reconstruction
Description
Set the state for Assemble Partial Content
GUI Location
Menu
> Settings > System
212
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
state
X
Format Default
Boolean
—
Valid Inputs
Description
true | false
True — Enable Assemble Partial
Content
PHP Example
callAPI('POST','/settings/extractor_enable_partial_content_reconstruction',
array (
'state' => true
)
);
Python Example
s.callAPI("POST","/settings/extractor_enable_partial_content_reconstruction", {
'state': True
}
)
Output
API_SUCCESS_CODE
Set signature extraction state
API Path
/settings/extractor_enable_signature_extractor
Description
Enable or disable signature extraction
GUI Location
Menu
> Settings > System > Extraction Settings > Enable signature-based extraction
Output
integer | false
Parameters
REQ
state
X
Format Default
Boolean
—
Valid Inputs
Description
true | false
True — Enable signature extraction
PHP Example
callAPI('POST','/settings/extractor_enable_signature_extractor',
array (
'state' => true
)
);
Python Example
s.callAPI("POST","/settings/extractor_enable_signature_extractor", {
'state': True
}
213
Security Analytics Reference Guide
Security Analytics 8.1
)
Set MD5 hash calculation state
API Path
/settings/extractor_enable_md5
Description
Enable or disable MD5 hash calculation
GUI Location
Menu
> Settings > System > Extraction Settings > Hash Computation > MD5
Output
integer | false
Parameters
REQ
state
X
Format Default
Boolean
—
Valid Inputs
Description
true | false
True — Enable MD5 hash calculation
PHP Example
callAPI('POST','/settings/extractor_enable_md5',
array (
'state' => true
)
);
Python Example
s.callAPI("POST","/settings/extractor_enable_md5", {
'state': True
}
)
Set SHA1 hash calculation state
API Path
/settings/extractor_enable_sha1
Description
Enable or disable SHA1 hash calculation
GUI Location
Menu
> Settings > System > Extraction Settings > Hash Computation > SHA1
214
Security Analytics Reference Guide
Security Analytics 8.1
Output
integer | false
Parameters
REQ
state
X
Format Default
Boolean
—
Valid Inputs
Description
true | false
True — Enable SHA1 hash calculation
PHP Example
callAPI('POST','/settings/extractor_enable_sha1',
array (
'state' => true
)
);
Python Example
s.callAPI("POST","/settings/extractor_enable_sha1", {
'state': True
}
)
Set SHA256 hash calculation state
API Path
/settings/extractor_enable_sha256
Description
Enable or disable SHA256 hash calculation
GUI Location
Menu
> Settings > System > Extraction Settings > Hash Computation > SHA256
Output
integer | false
Parameters
REQ
state
X
Format Default
Boolean
—
Valid Inputs
Description
true | false
True — Enable SHA256 hash calculation
PHP Example
callAPI('POST','/settings/extractor_enable_sha256',
array (
'state' => true
)
);
Python Example
s.callAPI("POST","/settings/extractor_enable_sha256", {
'state': True
}
215
Security Analytics Reference Guide
Security Analytics 8.1
)
Set fuzzy hash calculation state
API Path
/settings/extractor_enable_fuzzy
Description
Enable or disable fuzzy hash calculation
GUI Location
Menu
> Settings > System > Extraction Settings > Hash Computation > Fuzzy
Output
integer | false
Parameters
REQ
state
X
Format Default
Boolean
—
Valid Inputs
Description
true | false
True — Enable fuzzy hash calculation
PHP Example
callAPI('POST','/settings/extractor_enable_fuzzy',
array (
'state' => true
)
);
Python Example
s.callAPI("POST","/settings/extractor_enable_fuzzy", {
'state': True
}
)
Set fragment-display state
API Path
/settings/extractor_enable_fragment_reconstruction
Description
Enable or disable the display of known fragments in the Extractions list
GUI Location
Menu
> Settings > System > Extraction Settings > Display fragments
216
Security Analytics Reference Guide
Security Analytics 8.1
Output
integer | false
Parameters
REQ
state
X
Format Default
Boolean
—
Valid Inputs
Description
true | false
True — Display the fragments
PHP Example
callAPI('POST','/settings/extractor_enable_fragment_reconstruction',
array (
'state' => true
)
);
Python Example
s.callAPI("POST","/settings/extractor_enable_fragment_reconstruction", {
'state': True
}
)
Configure extractor-tuning parameters
API Path
/settings/extractor_prototune
Description
Input protocol-tuning strings
GUI Location
Menu
> Settings > System > Extraction Settings > Extraction Tuning Parameters
Output
string | false
Parameters
state
REQ
Format
Default
Valid Inputs
X
string
—
<protocol>
:<parameter>:<value>
Description
Contact Symantec Support for tuning
parameters
PHP Example
callAPI('POST','/settings/extractor_prototune',
array(
'state' => 'tcp:enable_defrag:1;ip:enable_defrag:1;ip6:enable_defrag:1'
)
);
Python Example
s.callAPI("POST","/settings/extractor_prototune", {
'state':'tcp:enable_defrag:1;ip:enable_defrag:1;ip6:enable_defrag:1'
217
Security Analytics Reference Guide
Security Analytics 8.1
}
)
218
Security Analytics Reference Guide
Security Analytics 8.1
Geolocation APIs
Also see "Summary Page APIs" on page 369.
Get geolocation for an IP
API Path
/geoip/<ip>
Description
Retrieve the geolocation information for an IP address
GUI Location
Menu
> Analyze > Summary > Geolocation
Output
array
Parameters
REQ
Format
Default
Valid Inputs
Description
X
string
—
<dotted-decimal>
IPv4 address
ip
Example
callAPI('GET','/geoip/203.0.113.5');
Get geolocation settings
API Path
/settings/geoip
Description
Retrieve the geolocation settings
GUI Location
Menu
> Settings > Geolocation
Output
array
Parameters
None
219
Security Analytics Reference Guide
Security Analytics 8.1
Example
callAPI('GET','/settings/geoip');
Get countries
API Path
/settings/geoip_countries
Description
Retrieve the possible countries for the KML colors
GUI Location
Menu
> Settings > Geolocation > Internal Subnets > Enable Country Colors
Output
array
Parameters
None
Example
callAPI('GET','/settings/geoip_countries');
Get MaxMind status
API Path
/settings/geoip_files
Description
®
Retrieve status of MaxMind geolocation files
GUI Location
Menu
> Settings > Geolocation > Upload MaxMind [x] Database
Output
array
Parameters
None
Example
callAPI('GET','/settings/geoip_files');
220
Security Analytics Reference Guide
Security Analytics 8.1
Save Geolocation Map — NEW
Note: This API replaces the type parameter in POST: /deepsee/save_view
API Path
/deepsee/save_map
Description
Create or edit a geolocation map view
GUI Location
Menu
> Analyze > Summary > Geolocation > Save Current Map as View / Edit Map
Output
array
Parameters
REQ
Format
Default
Valid Inputs
Description
name
X
string
—
<UTF-8 characters>
id
X
integer
—
<GET: /deepsee/summary_views>
shared
Boolean
false
true | false
True — Map view is shared
default
Boolean
false
true | false
True — Map view is the
default
Required for new map. Name
of map view
Required to edit map.
view_data
X
array
—
lat
X
string
—
<99.9999999>
Degrees latitude of the center
of the map
long
X
string
—
<99.9999999>
Degrees longitude of the
center of the map
zoom
X
integer
—
0–5
Amount of magnification
0 — No magnification
Array containing lat, lon, and
zoom
Python Example
s.callAPI("POST","/deepsee/save_map", {
'name': 'Australia',
'shared': True,
'default': True
'view_data': {
'lat': '-29.53125',
'lon': '134.82421875',
221
Security Analytics Reference Guide
Security Analytics 8.1
'zoom': 1
}
})
Delete a Geolocation Map View — NEW
API Path
/deepsee/delete_map/<ID>
Description
Delete a geolocation map view
GUI Location
Menu
> Analyze > Summary > Geolocation > [view selector] >
Output
array
Parameters
id
REQ
Format
Default
Valid Inputs
X
integer
—
<GET: /deepsee/summary_views>
Python Example
s.callAPI("POST","/deepsee/delete_map/7")
PHP Example
callAPI('POST','/deepsee/delete_map/7');
Configure geolocation settings
API Path
/settings/geoip
Description
Create or edit geolocation settings
GUI Location
Menu
> Settings > Geolocation > Internal Subnets
Output
array
222
Description
ID of map view
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
Format
Default
Valid Inputs
Description
internal_labels_
enabled
Boolean
false
true | false
True =
Enable
internal
subnets
internal_labels
array
()
<geolocation internal labels>
ip_cidr
string
—
lat
string
—
[-]0–90
Degrees
latitude; use
a hyphen for
negative
numbers
long
string
—
[-]0–180
Degrees
longitude;
use a hyphen
for negative
numbers
label
string
—
<UTF-8 characters>
default_kml_color
string
00FFFF
<HEX>
Default color
for pins in
®
Google
Earth; use
ALL CAPS
add_routes
Boolean
false
true | false
True = Show
routes
between
nodes
kml_colors_
enabled
Boolean
false
true | false
True =
Enable
country
colors
<dotted-decimal> |
223
<CIDR>
Array of
subnets and
their
locations;
contains ip_
cidr, lat,
long, and
label
IPv4 address
or CIDR of
subnetwork
Label for
location
Security Analytics Reference Guide
REQ
kml_colors
color
country
Security Analytics 8.1
Format
Default
Valid Inputs
array
()
hex
000000
<HEX>
string
—
<GET: /settings/geoip_countries>
Description
Array of
color/country
associations;
contains
color and
country
Example
callAPI('POST','/settings/geoip',
array(
'internal_labels_enabled' => true,
'internal_labels' => array(
array(
'ip_cidr' => '192.0.2.0/24',
'long' => -111.92965,
'lat' => 40.56217,
'label' => 'Utah Office'
),
),
'default_kml_color' => 'FF00FF',
'add_routes' => true,
'kml_colors_enabled' => true,
'kml_colors' => array(
array(
'color' => 'FFAA77',
'country' => 'CN'
),
array(
'color' => 'FF0077',
'country' => 'IN'
),
),
)
);
Update the MaxMind files
API Path
/settings/geoip_file
Description
Update the MaxMind files: city, country, or country IPv6
224
Use ALL
CAPS
Use twoletter
country
designators
in ALL CAPS
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
Menu
> Settings > Geolocation > Upload MaxMind [x] Database
Output
array
Parameters
REQ
Format
Default
Valid Inputs
type
X
string
—
city | country | countryv6
file
X
file
—
<filepath>
Example
callAPI('POST','/settings/geoip_file',
array(
'type' => 'city',
'file' => 'c:\user\maxmind\GeoLite2-city.mmdb'
)
);
225
Description
File type
Path to the MMDB file
Security Analytics Reference Guide
Security Analytics 8.1
Indicators APIs
"Favorite" is the internal name for "indicator."
Get shared indicators for current user
API Path
/favorites/active
Description
Retrieve a list of active (shared) indicators for the logged-in user; does not retrieve non-shared indicators
GUI Location
Menu
> Analyze > Indicators
Parameters
None
Python Example
s.callAPI("GET","/favorites/active")
PHP Example
callAPI('GET','/favorites/active');
Output
'result': [{'appliances': '',
'name': 'Symantec Web Reputation Service',
'sensor_uuids': '',
'uuid': '5b7da23b-116c-496e-8762-794e1e1d64a3'},
...
{'appliances': '',
'name': 'Zeus Tracker - Bad IPs - Live Feed',
'sensor_uuids': '',
'uuid': '5b7da23d-8b70-4a7e-acbb-794e1e1d64a3'}],
'resultCode': 'API_SUCCESS_CODE',
Get a list of indicators
API Path
/favorites
Description
Retrieve a paginated, detailed list of indicators and their parameters
226
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
Menu
> Analyze > Indicators
Parameters
REQ Format Default
Valid Inputs
Description
uuids
array
—
page
integer
1
1–<n>
Page to retrieve; first page is 1
limit
integer
—
1–100
Number of items per page
sort
string
name
name
Sort-by column
direction
string
ASC
ASC | DESC
filters
JSON
—
<advanced filter for
indicators>
name
string
—
<UTF-8 characters>
Boolean
null
null | true | false
shared
chopValues
Boolean
true
<GET: /favorites/active> Array of UUIDs of indicators to retrieve. Omit
| <GET: /favorites>
this parameter to retrieve all favorites.
true | false
Sort direction
Advanced filter attributes; indicator is the only
valid key
Substring to filter on exact indicator names
n
Null — All indicators
n
True — Shared indicators only
n
False — Non-shared indicators only
True — Restrict the list to <= 2000 items
Python Example
s.callAPI("GET","/favorites", {
'page': 1,
'limit': 20,
'sort': 'name',
'direction': 'DESC',
'filters': {
'all': {
'key' => 'indicator',
'comp' => '~',
'value' => 'RFC1918'
}
},
'name': 'mime',
'uuids': [<UUID-1>,<UUID-2>,<UUID-3>,<UUID-4>,<UUID-5>],
'shared': null,
'chopValues': false
}
)
PHP Example
callAPI('GET','/favorites',
array(
'page' => 1,
'limit' => 20,
'sort' => 'name',
'direction' => 'DESC',
'filters' => array(
'all' => array(
array(
'key' => 'indicator',
'comp' => '~',
227
Security Analytics Reference Guide
Security Analytics 8.1
'value' => 'RFC1918'
)
)
),
'name' => 'mime',
'uuids' => array(<UUID-1>,<UUID-2>,<UUID-3>,<UUID-4>,<UUID-5>),
'shared' => null,
'chopValues' => false
)
);
Output
'paging': {'DeepseeFavorite': {'count': 56,
'current': 25,
'limit': 25,
'nextPage': True,
'options': [],
'order': {'DeepseeFavorite.name': 'ASC',
'DeepseeFavorite.ordinal': 'ASC'},
'page': 1,
'pageCount': 3,
'paramType': 'named',
'prevPage': False}},
'result': {'pageCount': 3,
'results': [{'active': True,
'aggregate_uuid': '984f2e1b-4366-131a-2773-0e8db7da9d94',
'appliance_id': None,
'appliances': [],
'creatable': True,
'deletable': True,
'edit_type': 'all',
'end_time_of_execution': '23:59:59',
'events': [],
'frequency': None,
'hash_uuid': 'c0e4e7a1-c2cc-7875-c441-2d9c6de5375b',
'linked_uuid': None,
'name': 'Local File Analysis - Live Exploits',
'nested': 0,
'original_params': None,
'sensor_uuids': [],
'shared': True,
'time_of_execution': None,
'user_id': None,
'uuid': '5b7da23b-386c-452b-8579-794e1e1d64a3',
'value': '["mime_type=\\"application\\/java-archive\\"","mime_
type=\\"application\\/x-java-jnlp-file\\"","mime_
type=\\"application\\/pdf\\"","mime_type=\\"application\\/xpdf\\"","mime_type=\\"application\\/acrobat\\"","mime_
type=\\"application\\/vnd.pdf\\"","mime_
type=\\"text\\/pdf\\"","mime_type=\\"text\\/x-pdf\\"","mime_
type=\\"text\\/html\\"","mime_type=\\"application\\/octetstream\\"","mime_type=\\"application\\/octet-strem\\"","mime_
type=\\"application\\/octect-strem\\"","mime_
type=\\"application\\/x-shockwave-flash\\"","mime_
type=\\"application\\/x-shockwave-flash2-preview\\"","mime_
type=\\"application\\/futuresplash\\"","mime_
type=\\"application\\/vnd.rn-realflash\\"","mime_
type=\\"application\\/x-silverlight-2\\"","url_risk_verdict=5"]',
'value_length': 18}]},
'resultCode': 'API_SUCCESS_CODE',
228
Security Analytics Reference Guide
Security Analytics 8.1
Get import-type parameters for indicators
API Path
/favorites/importers
Description
Retrieve a list of all valid indicator import types and their input parameters
GUI Location
Menu
> Analyze > Indicators > Tools > Import > Location=Remote
Parameters
None
Python Example
s.callAPI("GET","/favorites/importers")
PHP Example
callAPI('GET','/favorites/importers');
Output
'result': {'deepsee': {'name': 'JSON', 'params': []},
'dshield': {'name': 'DShield',
'params': {'name': {'label': 'Name', 'type': 'text'}}},
'simple_list': {'name': 'List',
'params': {'field': {'label': 'Field',
'type': 'list',
'values': 'field_options'},
'name': {'label': 'Name',
'type': 'text'}}},
'snort': {'name': 'Snort',
'params': {'keepDirection': {'label': 'Honor rule '
'directionality',
'type': 'boolean'},
'name': {'label': 'Name', 'type': 'text'}}}},
'resultCode': 'API_SUCCESS_CODE',
Create or edit an indicator
API Path
/favorites/save
Description
Create or edit an indicator
GUI Location
n
Menu
> Analyze > Indicators > Tools > New
n
Menu
> Analyze > Indicators > [edit indicator]
229
Security Analytics Reference Guide
Security Analytics 8.1
Output
array
Parameters
REQ
uuid
name
value
X
Format
Default
Valid Inputs
UUID
0
0 | <GET: /favorites>
|
<GET:
/favorites/active>
n
Create new — Use 0
n
Edit entry — UUID required
<UTF-8 characters>
n
Create new — Name
required
n
Edit entry — New name
string
—
Description
JSON
—
<primary filter
array>
Boolean
true
true | false
applianceIds
array
null
GET: /cmc_
settings/appliances
array (<appliance_
id1> => <appliance_
name1>,<appliance_
id2> => <appliance_
name2>)
CMC Only. Array of sensors IDs to
receive the indicator
linked_uuid
UUID
null
null | <GET:
/favorites> | <GET:
/favorites/active>
UUID to link to the main indicator
so that changes to a child indicator
will update the parent; not visible in
GUI
shared
X
Example 1
Create a new indicator (favorite)
callAPI('POST','favorites/save',
array(
'uuid' => '0',
'name' => 'MiddlewareGroup',
'value' => json_encode(
array
(
'application_group='middleware'
)
)
)
);
Example 2
Edit an existing indicator on three sensors. Run this API on a CMC.
callAPI('POST','favorites/save?appliances=1',
230
Primary-filter attributes; JSONencoded
True — Shared
Security Analytics Reference Guide
Security Analytics 8.1
array(
'uuid' => <UUID>,
'name' => 'Middleware&Management',
'value' => json_encode(
array(
'application_group=middleware',
'application_group=network management'
)
'applianceIDs' => array(
1 => 'sensorA',
4 => 'sensorD',
5 => 'sensorE'
)
)
)
);
Import indicators from a file; create a live-feed indicator
API Path
/favorites/import
Description
Import indicators from a file or create a live-feed indicator
GUI Location
Menu
> Analyze > Indicators > Tools > Import
Output
array
Parameters
type
importLocation
importFile
remoteLocation
applianceIds
REQ
Format
Default
X
string
—
string
local
Valid Inputs
Description
GET: /favorites/importers File type to import.
local | remote
string
—
<filepath>
URI
—
<URI>
array
null
n
Local — Browser upload
n
Remote — Upload from URI
Required if importLocation=local;
path of file to import
Required if
importLocation=remote; URI of
remote file
GET: /cmc_
CMC Only. Array of sensors IDs to
settings/appliances
receive the indicator
array (<appliance_id1> =>
<appliance_
name1>,<appliance_id2> =>
<appliance_name2>)
231
Security Analytics Reference Guide
REQ
shared
Security Analytics 8.1
Format
Default
Valid Inputs
Description
true | false
True — Shared
Boolean
true
array
—
name
string
—
<UTF-8 characters>
keepDirection
integer
0
0 | 1
importTypeParam
GET: /favorites/importers Parameters that are required by
each type; array +may contain all
of the parameters below
Required if type!=json; name for
the indicator
Valid if type=snort
1 — Retain the directionality of the
original rule
field
string
—
importSchedule
array
—
frequency
string
null
daily | weekly | monthly |
hour | minute | once |
custom
events
array
null
<scheduled_events>
Valid only if
importLocation=remote; depends
on the value of frequency
time_of_
execution
string
null
<hh:ii:ss>
Valid only if
importLocation=remote; first time
to re-import the file at
remoteLocation
end_time_of_
execution
string
null
<hh:ii:ss> | 23:59:59
<primary_filter_
attribute>
Required if type=simple_list and
importLocation=local; attribute to
match to the values in the imported
list, such that <primary filter
attribute>=<list value>
Valid only if
importLocation=remote; array
contains events, frequency, time_
of_execution, end_time_of_
execution
Valid only if
importLocation=remote; how often
to re-import the file at
remoteLocation
Valid only if location=remote;
n
Example 1
Import a list of values for ipv4_address onto three sensors. Run this API on the CMC.
callAPI('POST','favorites/import?appliances=1',
array(
'type' => 'simple_list',
'importLocation' => 'local',
232
<hh:ii:ss> is valid when
frequency=hour or minute,
else use 23:59:59
Security Analytics Reference Guide
Security Analytics 8.1
'importFile' => 'c:\dox\indicator_list.txt',
'importTypeParams' => array(
'name' => 'BlackListed IPs',
'field' => 'ipv4_address'
'applianceIDs' => array(
1 => 'sensorA',
4 => 'sensorD',
5 => 'sensorE'
)
)
)
);
Example 2
Import indicators exported from another appliance
callAPI('POST','favorites/import',
array(
'type' => 'deepsee',
'importLocation' => 'local',
'importFile' => 'c:\dox\indicators.json'
)
);
Example 3
Create a live-feed indicator from a remote Snort list
callAPI('POST','favorites/import',
array(
'shared' => true,
'type' => 'snort',
'importTypeParams' => array(
'name' => 'SnortRules',
'keepDirection' => true
),
'importLocation' => 'remote',
'remoteLocation' => 'http://rules.emergingthreats.net/blockrules/emergingciarmy.rules',
'importSchedule' => array(
'frequency" => 'minute',
'events' => '01',
'time_of_execution' => '0:0:00',
'end_time_of_execution' => '23:59:00'
)
)
);
Delete indicators
API Path
/favorites/delete
Description
Delete one or more indicators
233
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
Menu
> Analyze > Indicators > Tools > Delete
Output
array
Parameters
selectedIds
REQ
Format
Default
Valid Inputs
X
array
—
<GET: /favorites>
array
null
<GET: /cmc_
settings/appliances>
applianceIds
Description
UUID(s) of the indicator(s) to delete
CMC only. Sensors to delete the
indicator(s) from
Example
callAPI('POST','favorites/delete',
array(
'selectedIds' => array(
'<UUID-1>',
'<UUID-2>'
),
'applianceIds' => array(
<sensor-1>,
<sensor-2>,
<sensor-3>
)
)
);
Activate or deactivate an indicator
API Path
/favorites/toggle/<UUID>
Description
Activate or deactivate an indicator
GUI Location
Menu
> Analyze > Indicators >
Output
array
Parameters
uuid
REQ
Format
Default
Valid Inputs
X
UUID
—
<GET: /favorites> | <GET:
/favorites/active>
234
Description
UUID of indicator to
toggle
Security Analytics Reference Guide
REQ
action
Security Analytics 8.1
Format
Default
Valid Inputs
Description
Boolean
true
true | false
True — Activate
Example
callAPI('POST','favorites/toggle/<UUID>',
array(
'action' => 'false'
)
);
235
Security Analytics Reference Guide
Security Analytics 8.1
License APIs
Get the serial number of the appliance
API Path
/settings/machine_details
Description
Retrieve the serial number of the appliance
GUI Location
About
Output
{'result' : {serial_number': '<serial number>' 'resultCode': '<result>'}}
Parameters
None
PHP Example
callAPI('GET','/settings/machine_details');
Python Example
s.callAPI("GET","/settings/machine_details")
Get the DS Seed file
API Path
/settings/download_seed
Description
Download dsseed.tgz
GUI Location
About
> License Details > Download DS Seed
Output
ApiResultCode
Parameters
None
Example
callAPI('GET','/settings/download_seed');
236
Security Analytics Reference Guide
Security Analytics 8.1
Get license settings
API Path
/settings/entitlements
Description
Retrieve license information
GUI Location
About
> License Details
Output
ApiResultCode
Parameters
None
Example
callAPI('GET','/settings/entitlements');
Get current license file
API Path
/settings/license
Description
Download solera-license.dat
GUI Location
About
> License Details > Download
Output
solera-license.dat
Parameters
None
Example
callAPI('GET','/settings/license');
237
Security Analytics Reference Guide
Security Analytics 8.1
Retrieve a license from the server
API Path
/settings/license_server
Description
Retrieve a license from the license server
GUI Location
About
> License Details
Output
array
Parameters
REQ
Format
Default
Valid Inputs
Description
serial
X
string
—
<license_key>
Retrieve your license key from Symantec Support
Center, as instructed in your eFulfillment message
license
X
string
null
<GET: /config>
License identifier, if previously licensed
Example
callAPI('POST','/settings/license_server',
array(
'serial' => '<license_key>',
'license' => '<license_ID>'
)
);
Upload a license
API Path
/settings/license
Description
Upload the license file (license.tgz) to the appliance; successful upload reboots the appliance
GUI Location
About
> License Details > Browse
Output
ApiResultCode
238
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
license
REQ
Format
Default
Valid Inputs
Description
X
file
—
<path>\license.tgz
License file
Example
callAPI('POST','/settings/license',
array(
'license' => 'c:\documents\user5\downloads\license.tgz'
)
);
239
Security Analytics Reference Guide
Security Analytics 8.1
Logging and Communication APIs
Get all log entries
API Path
/statistics/logging
Description
Retrieve all Audit Log entries
GUI Location
Menu
> Settings > Audit Log
Output
array
Parameters
REQ
Format
Default
Valid Inputs
Description
page
integer
1
1–<n>
Page to retrieve; first page is 1
limit
integer
25
1–100
Number of items per page
direction
string
DESC
ASC | DESC
filters
JSON
—
<advanced filter for
audit log>
sort
string
time
Sort order
Advanced filter attributes. Only = and
!= operators are permitted.
time | priority | category Sort-by field
| event | message
Python Example
s.callAPI("GET","/statistics/logging", {
'page': 1,
'limit': 20,
'direction': 'ASC',
'filters': {
'all': {
{
'key': 'category',
'comp': '=',
'value': 'alerts'
},
{
'any': {
{
'key': 'event',
'comp': '=',
'value': 'capture stop'
},
{
'key': 'priority',
240
Security Analytics Reference Guide
Security Analytics 8.1
'comp': '!=',
'value': 'Error'
}
}
}
}
}
}
)
PHP Example
callAPI('GET','/statistics/logging',
array(
'page' => 1,
'limit' => 20,
'direction' => ASC,
'filters' => array(
'all' => array(
array(
'key' => 'category',
'comp' => '=',
'value' => 'alerts'
),
array(
'any' => array(
array(
'key' => 'event',
'comp' => '=',
'value' => 'capture stop'
),
array(
'key' => 'priority',
'comp' => '!=',
'value' => 'Error'
)
)
)
)
)
);
Output
'paging': {'SysLog': {'count': <integer>,
'current': <integer>,
'limit': <integer>,
'nextPage': [True|False],
'options': {'conditions': [],
'order': {'SysLog.time': '[asc|desc]'}},
'order': {'SysLog.time': '[asc|desc]'},
'page': <integer>,
'pageCount': <integer>,
'paramType': 'named',
'prevPage': [True|False]}},
'result': [{'category': '<category>',
'event': '<event>',
'log_id': <integer>,
'message': '<line 1>'
'<line 2>',
'priority': '<priority>',
'time': '<MM/DD/YYYY hh:ii:ss>'},
...
{'category': '<category>',
'event': '<event>',
'log_id': <integer>,
'message': '<line 1>'
'<line 2>',
'priority': '<priority>',
241
Security Analytics Reference Guide
Security Analytics 8.1
'time': '<MM/DD/YYYY hh:ii:ss>'}],
'resultCode': 'API_SUCCESS_CODE',
Get logging settings
API Path
/settings/logging_settings
Description
Retrieve all SNMP, SMTP, and syslog settings
GUI Location
Menu
> Settings > Communications > Server Settings
Parameters
None
Python Example
s.callAPI("GET","/settings/logging_settings")
PHP Example
callAPI('GET','/settings/logging_settings');
Output
'result': {'icdx_meta_enabled': '',
'icdx_valid': [True|False],
'log_email_address': '<email_address>',
'log_email_auth_optional': [0|1],
'log_email_sender': '<email_sender>',
'log_email_smtp_password': '***************************',
'log_email_smtp_port': <port>,
'log_email_smtp_server': '<hostname>',
'log_email_smtp_username': '<string>',
'log_email_use_starttls': [True|False],
'log_icdx_exchange': '<string>',
'log_icdx_password': '*************************',
'log_icdx_port': '5672',
'log_icdx_server': '<hostname>',
'log_icdx_username': '<string>',
'log_phantomcyber_key': '*****************',
'log_phantomcyber_server': '<hostname>',
'log_snmp_auth_password': '***************************',
'log_snmp_auth_password2': '',
'log_snmp_auth_protocol': 'SHA',
'log_snmp_auth_protocol2': '',
'log_snmp_authtrap': [True|False],
'log_snmp_encryption_password': '***************************',
'log_snmp_encryption_password2': '',
'log_snmp_encryption_protocol': 'AES',
'log_snmp_encryption_protocol2': '',
'log_snmp_inform_servers': [{'authkey': '<hash>',
'authproto': 'SHA',
'port': <port>,
'privkey': '<hash>',
'privproto': 'AES',
'secname': '<ro username>',
242
Security Analytics Reference Guide
Security Analytics 8.1
'server': '<hostname>',
'version': [1|3]}],
'log_snmp_ro_community': 'public',
'log_snmp_ro_user': 'public',
'log_snmp_ro_user2': '',
'log_snmp_snmpdenable': [True|False],
'log_snmp_trap_community': '***************************',
'log_snmp_trap_servers': [{'authkey': '<hash>',
'authproto': 'SHA',
'port': <port>,
'privkey': '<hash>',
'privproto': 'AES',
'secname': '<ro username>',
'server': '<hostname>',
'version': [1|3]}],
'log_snmp_version': '[1|3]',
'log_syslog_coalescing': [0|1],
'log_syslog_facility': <integer>,
'log_syslog_servers': [{'port': <port>,
'protocol': '<protocol>',
'server': '<hostname>'}],
'smtp_valid': [True|False],
'snmp_valid': [True|False],
'syslog_valid': [True|False]},
'resultCode': 'API_SUCCESS_CODE',
Get remote-notification templates for rules
API Path
/settings/all_templates
Description
Retrieve all remote-notification templates for the rules
GUI Location
Menu
> Analyze > Rules > [New | Edit Rule] > Remote Notifications > [SNMP | Syslog | SMTP]
Output
array
Parameters
None
Python Example
s.callAPI("GET","/settings/all_templates")
PHP Example
callAPI('GET','/settings/all_templates');
Output
'result': {'pageCount': 0,
'rows': [{'appliance_id': 0,
'creatable': False,
243
Security Analytics Reference Guide
Security Analytics 8.1
'deletable': False,
'last_modified_date': '<YYYY-MM-DD hh:ii:ss>.529927',
'name': 'CEF Template',
'template_format_str': '|,,ipv4_initiator,port_initiator,ipv4_responder,port_
responder,start_time,',
'type': 'Syslog',
'ui_data': '{"uuid":null,"type":"syslog","name":"CEF '
'Template","ui_data":"","template_format_str":"","email_
subject":"","delimiter":"|","keyvaluepair":["ipv4_initiator","port_initiator","ipv4_
responder","port_responder","start_time"],"templateOutput":"|,ipv4_
initiator=\\"\\",port_initiator=\\"\\",ipv4_responder=\\"\\",port_
responder=\\"\\",start_time=\\"\\",","ext":"json"}',
'uuid': '5b8f0267-7aa0-4941-9338-69307f000001'},
...
{'appliance_id': 0,
'creatable': False,
'deletable': False,
'last_modified_date': '<YYYY-MM-DD hh:ii:ss>.983576',
'name': 'Web Reputation',
'template_format_str': ',,,http_uri,mime_type,application_id,ip_protocol,ipv4_
initiator,ipv4_responder,ipv6_initiator,ipv6_responder,port_initiator,port_
responder,',
'type': 'Syslog',
'ui_data': '{"uuid":null,"type":"syslog","name":"Web '
'Reputation","ui_data":"","template_format_str":"","email_
subject":"","delimiter":",","keyvaluepair": '
'["http_uri","mime_type","application_id","ip_protocol","ipv4_initiator","ipv4_
responder","ipv6_initiator","ipv6_responder","port_initiator","port_
responder"],"ext":"json"}',
'uuid': '5b8f0293-7b68-4d9e-8253-69307f000001'}]},
'resultCode': 'API_SUCCESS_CODE',
Get global email
API Path
/settings/global_email
Description
Retrieve the global communications email
GUI Location
Menu
> Settings > Communication > Server Settings > Default Email Address
Output
array
Parameters
None
Python Example
s.callAPI("GET","/settings/global_email")
PHP Example
callAPI('GET','/settings/global_email');
244
Security Analytics Reference Guide
Security Analytics 8.1
Output
'result': {'global_communicationi_email': [True|False]},
'resultCode': 'API_SUCCESS_CODE',
Get audit log information
API Path
/statistics/filter_options
Description
Get priorities, categories, and events for the Audit Log
GUI Location
Menu
> Settings > Audit Log
Output
array
Parameters
None
Python Example
s.callAPI("GET","/statistics/filter_options")
PHP Example
callAPI('GET','/statistics/filter_options');
Output
'result': {'category': ['Miscellaneous',
'System Events',
...
'Rule Events',
'Anomaly Events'],
'event': ['Change IP Address',
'Change Gateway',
...
'YARA Rules Default Restored',
'Metadata'],
'priority': ['Emergency',
'Alert',
...
'Informational',
'Debug']},
'resultCode': 'API_SUCCESS_CODE',
Get CSV of log entries
API Path
/statistics/save_log
245
Security Analytics Reference Guide
Security Analytics 8.1
Description
Download Audit Log entries as a comma-delimited file (CSV)
GUI Location
Menu
> Settings > Audit Log > Download Log
Output
ApiResultCode
Parameters
None
Python Example
s.callAPI("GET","/statistics/save_log")
PHP Example
callAPI('GET','/statistics/save_log');
Get MIB file
API Path
/settings/download_logging_mib
Description
Download a ZIP of the MIB
GUI Location
Menu
> Settings > Communication > Advanced > Download MIB
Output
ApiResultCode
Parameters
None
Python Example
s.callAPI("GET","/settings/download_logging_mib")
PHP Example
callAPI('GET','/settings/download_logging_mib');
246
Security Analytics Reference Guide
Security Analytics 8.1
Export logging settings
API Path
/settings/download_logging_settings
Description
Download logging_config.dat
GUI Location
Menu
> Settings > Communication > Advanced > Export Settings
Output
ApiResultCode
Parameters
None
Python Example
callAPI('GET','/settings/download_logging_settings');
PHP Example
callAPI('GET','/settings/download_logging_settings');
Get remote-notification templates
API Path
/settings/get_templates
Description
Retrieve the remote-notification templates; this API retrieves the contents of the templates, including the default
templates
GUI Location
Menu
> Settings > Communication > Templates
Parameters
REQ
Format
Default
Valid Inputs
Description
page
integer
1
1–<n>
Page to retrieve; first page is 1
limit
integer
25
1–100
Number of items per page
sort
string
name
name | type
Sort-by field
direction
string
ASC
ASC | DESC
Sort direction
247
Security Analytics Reference Guide
Security Analytics 8.1
Python Example
s.callAPI("GET","/settings/get_templates", {
'page': 1,
'limit': 20,
'sort': 'type',
'direction': 'DESC'
}
)
PHP Example
callAPI('GET','/settings/get_templates',
array(
'page' => 1,
'limit' => 20,
'sort' => 'type',
'direction' => 'DESC'
)
);
Output
'paging': {'AlertTemplates': {'count': <integer>,
'current': <integer>,
'limit': <integer>,
'nextPage': [True|False],
'options': {'conditions': [],
'order': {'AlertTemplates.name': 'asc'}},
'order': {'AlertTemplates.name': 'asc'},
'page': <integer>,
'pageCount': <integer>,
'paramType': 'named',
'prevPage': [True|False]}},
'result': {'pageCount': 1,
'templates': [{'creatable': False,
'deletable': False,
'name': 'CEF Template',
'template_format_str': '|,,ipv4_initiator,port_initiator,ipv4_
responder,port_responder,start_time,',
'type': 'Syslog',
'ui_data': {'delimiter': '|',
'email_subject': '',
'ext': 'json',
'keyvaluepair': ['ipv4_initiator',
'port_initiator',
'ipv4_responder',
'port_responder',
'start_time'],
'name': 'CEF Template',
'templateOutput': '|,ipv4_initiator="",port_
initiator="",ipv4_responder="",port_responder="",start_
time="",',
'template_format_str': '',
'type': 'syslog',
'ui_data': '',
'uuid': None},
'uuid': '<UUID>'},
...
{'creatable': False,
'deletable': False,
'name': 'Web Reputation',
'template_format_str': ',,,http_uri,mime_type,application_id,ip_
protocol,ipv4_initiator,ipv4_responder,ipv6_initiator,ipv6_
responder,port_initiator,port_responder,',
'type': 'Syslog',
'ui_data': {'delimiter': ',',
'email_subject': '',
248
Security Analytics Reference Guide
Security Analytics 8.1
'ext': 'json',
'keyvaluepair': ['http_uri',
'mime_type',
'application_id',
'ip_protocol',
'ipv4_initiator',
'ipv4_responder',
'ipv6_initiator',
'ipv6_responder',
'port_initiator',
'port_responder'],
'name': 'Web Reputation',
'template_format_str': '',
'type': 'syslog',
'ui_data': '',
'uuid': None},
'uuid': '<UUID>'}]},
'resultCode': 'API_SUCCESS_CODE',
Get logging categories
API Path
/settings/logging_categories
Description
Retrieve the categories for the Audit Log
GUI Location
n
Menu
> Settings > Communications > Advanced > Remote Notifications
n
Menu
> Settings > Audit Log
Parameters
None
Python Example
s.callAPI("GET","/settings/logging_categories")
PHP Example
callAPI('GET','/settings/logging_categories');
Output
'result': {'categories': {'action': {'email': 0,
'local': 1,
'snmp': 0,
'syslog': 0},
'alerts': {'email': 0,
'local': 1,
'snmp': 0,
'syslog': 0},
'anomaly': {'email': 0,
'local': 1,
249
Security Analytics Reference Guide
Security Analytics 8.1
'snmp': 0,
'syslog': 0},
'capture': {'email': 0,
'local': 1,
'snmp': 0,
'syslog': 0},
'deepsee': {'email': 0,
'local': 1,
'snmp': 0,
'syslog': 0},
'enrichment': {'email': 0,
'local': 1,
'snmp': 0,
'syslog': 0},
'favorite': {'email': 0,
'local': 1,
'snmp': 0,
'syslog': 0},
'hardware': {'email': 0,
'local': 1,
'snmp': 0,
'syslog': 0},
'indexing': {'email': 0,
'local': 1,
'snmp': 0,
'syslog': 0},
'misc': {'email': 0,
'local': 1,
'snmp': 0,
'syslog': 0},
'playback': {'email': 0,
'local': 1,
'snmp': 0,
'syslog': 0},
'rules': {'email': 0,
'local': 1,
'snmp': 0,
'syslog': 0},
'system': {'email': 0,
'local': 1,
'snmp': 0,
'syslog': 0},
'user': {'email': 0,
'local': 1,
'snmp': 0,
'syslog': 0}}},
'resultCode': 'API_SUCCESS_CODE',
Get remote-notification options
API Path
/settings/logging_options
Description
Retrieve valid syslog facilities, logging categories, and remote-logging methods for this appliance
250
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
Menu
> Settings > Communications > Server Settings > Syslog Settings
Output
array
Parameters
None
Python Example
s.callAPI("GET","/settings/logging_options")
PHP Example
callAPI('GET','/settings/logging_options');
Options
'result': {'logging_categories': ['misc',
'system',
'user',
'playback',
'capture',
'deepsee',
'hardware',
'rules',
'alerts',
'indexing',
'enrichment',
'favorite',
'action',
'anomaly'],
'logging_methods': ['local', 'email', 'snmp', 'syslog'],
'logging_syslog_facilities': {'0': 'Kernel',
'1': 'User',
'10': 'AuthPriv',
'11': 'FTP',
'16': 'Local Use 0 (local0)',
'18': 'Local Use 2 (local2)',
'19': 'Local Use 3 (local3)',
'2': 'Mail',
'20': 'Local Use 4 (local4)',
'21': 'Local Use 5 (local5)',
'22': 'Local Use 6 (local6)',
'3': 'Daemon',
'4': 'Auth',
'5': 'SysLog',
'6': 'LPR',
'7': 'News',
'8': 'UUCP',
'9': 'Cron'}},
'resultCode': 'API_SUCCESS_CODE',
251
Security Analytics Reference Guide
Security Analytics 8.1
Configure communication settings — MODIFIED
For this API, all unspecified fields will reset to default (null, false); therefore, it is
recommended that you include a value for all fields during an edit to avoid losing
permissions or other essential characteristics.
API Path
/settings/logging_settings
Description
Configure settings for SMTP, SNMP, syslog, ICDx remote notifications, and Splunk Phantom
GUI Location
Menu
> Settings > Communication > Server Settings
Output
Boolean
Parameters
REQ
Format
X
array
—
<GET: /settings/logging_
settings>
Settings for
logging and
communication;
array must
contain all
other
parameters
log_icdx_exchange
string
—
<UTF-8 characters>
Name of ICDx
exchange (new)
log_icdx_password
string
—
<UTF-8 characters>
Password for
the ICDx server
(new)
log_icdx_port
integer
—
5671 | 5672
5672 — If icdx_
ssl = false
5671 — If icdx_
ssl=true
log_icdx_server
string
—
<hostname> | <IP_address>
Hostname of
the ICDx server
(new)
log_icdx_username
string
—
<UTF-8 characters>
Username for
the ICDx server
(new)
settings
Default
252
Valid Inputs
Description
Security Analytics Reference Guide
Security Analytics 8.1
REQ
Format
Default
Valid Inputs
log_phantomcyber_key
string
—
<hex>
API key for the
Splunk
Phantom server
(new)
log_phantomcyber_
server
string
—
<hostname> | <IP_address>
Hostname or IP
of the Splunk
Phantom server
(new)
log_snmp_version
integer
1
1 | 3
log_snmp_ro_community
string
public
<UTF-8 characters>
Read-only
community
name
log_snmp_ro_user
string
public
<UTF-8 characters>
Read-only user
name
log_snmp_ro_user2
string
—
<UTF-8 characters>
Second readonly user name
(new)
log_snmp_auth_
protocol
string
SHA
SHA
Authentication
protocol; valid
only if log_
snmp_
version=3; only
SHA is valid
log_snmp_auth_
protocol2
string
SHA
SHA
Second
authentication
protocol (new) ;
valid only if log_
snmp_
version=3; only
SHA is valid
log_snmp_auth_
password
string
—
<UTF-8 characters>
Authentication
password; valid
only if log_
snmp_
version=3
log_snmp_auth_
password2
string
—
<UTF-8 characters>
Second
authentication
password
(new) ; valid only
if log_snmp_
version=3
253
Description
SNMP version;
1=SNMPv2,
3=SNMPv3
Security Analytics Reference Guide
Security Analytics 8.1
REQ
Format
Default
log_snmp_encryption_
protocol
string
AES
AES
Privacy
encryption
protocol; valid
only if log_
snmp_
version=3; only
AES is valid
log_snmp_encryption_
protocol2
string
AES
AES
Second privacy
encryption
protocol (new) ;
valid only if log_
snmp_
version=3; only
AES is valid
log_snmp_encryption_
password
string
—
<UTF-8 characters>
Privacy
encryption
password; valid
only if log_
snmp_
version=3
log_snmp_encryption_
password2
string
—
<UTF-8 characters>
Second privacy
encryption
password
(new) ; valid only
if log_snmp_
version=3
log_snmp_trap_
community
string
—
<UTF-8 characters>
SNMP trap
community
name
log_snmp_authtrap
Boolean
false
true | false
True — Enable
Authtrap
log_snmp_snmpdenable
Boolean
false
true | false
True — Enable
SNMP polling
array
—
—
Inform server;
array must
contain
position,
server, port,
version, and
optionally
secname,
authproto,
authkey,
privproto, and
privkey
log_snmp_inform_
servers
254
Valid Inputs
Description
Security Analytics Reference Guide
Security Analytics 8.1
REQ
Format
Default
Valid Inputs
integer
—
—
Position in the
list of servers of
the same type.
First position is
0.
server
string
—
<hostname> | <IP_address>
SNMP server
hostname or IP
port
integer
162
1—65536
SNMP server
port; contained
in server arrays
version
integer
1
1 | 3
SNMP version;
1=SNMPv2;
contained in
server arrays
secname
string
—
<UTF-8 characters>
Required if
version=3;
read-only
username;
contained in
server arrays
authproto
string
SHA
SHA
Required if
version=3;
authentication
protocol; only
SHA is valid;
contained in
server arrays
authkey
string
—
<UTF-8 characters>
Required if
version=3;
authentication
password;
contained in
server arrays
privproto
string
AES
AES
Required if
version=3;
privacy
protocol; only
AES is valid;
contained in
server arrays
position
255
Description
Security Analytics Reference Guide
Security Analytics 8.1
REQ
Format
Default
Valid Inputs
Description
privkey
string
—
<UTF-8 characters>
Required if
version=3;
privacy
encryption
password;
contained in
server arrays
log_snmp_trap_servers
array
—
—
Trap server;
array must
contain
position,
server, port,
version, and
optionally
secname,
authproto,
authkey,
privproto, and
privkey
integer
0
<GET: /settings/logging_
settings>
Syslog facility
Boolean
false
true | false
protocol
string
udp
tcp | udp | tls | tls-fips
log_syslog_servers
array
—
—
Syslog server;
array must
contain
position,
server, port,
protocol
log_email_address
string
—
<user>@<domain>.<tld>
Default email
address
log_email_smtp_server
string
—
<hostname> | <ip_address>
SMTP server
log_email_smtp_port
integer
25
1–65536
SMTP server
port
log_email_smtp_
username
string
—
<UTF-8 characters>
SMTP
username
log_email_smtp_
password
string
—
<UTF-8 characters>
SMTP password
log_syslog_facility
log_syslog_coalescing
256
True — Enable
syslog
coalescing
Protocol to
send syslog
messages
Security Analytics Reference Guide
Security Analytics 8.1
REQ
Format
Default
log_email_auth_
optional
Boolean
false
true | false
True — SMTP
authentication
required
log_email_use_
starttls
Boolean
false
true | false
True — Use
STARTTLS
string
—
<user>@<domain>.<tld>
log_email_sender
Valid Inputs
Python Example
Configure the SMTP server, an SNMP inform server, an SNMP trap server, and two syslog servers.
s.callAPI("POST","/settings/logging_settings", {
'settings': {
'log_email_address': 'sysadmin@domain.com',
'log_email_sender': 'SA-24@domain.com',
'log_email_smtp_server': '203.0.113.5',
'log_email_smtp_port': 25,
'log_email_auth_optional': 0,
'log_email_smtp_username': 'admin',
'log_email_smtp_password': 'smtp_password',
'log_email_use_starttls': 1,
'log_global_communication_email': 'SA-27@domain.com',
'log_icdx_username': 'admin',
'log_icdx_password': 'h@ckm3n0t',
'log_icdx_server': '198.51.100.24',
'log_icdx_port': 5671,
'log_icdx_exchange': 'SA-24',
'log_icdx_ssl': True,
'log_icdx_ssl_verify_certificate': False,
'log_phantomcyber_server': '198.51.100.157',
'log_phantomcyber_key': '<key>',
'log_snmp_snmpdenable': 1,
'log_snmp_ro_user': 'public',
'log_snmp_ro_community': 'public',
'log_snmp_version': 1,
'log_snmp_auth_protocol': 'SHA',
'log_snmp_auth_password': 'snmp_auth_password',
'log_snmp_encryption_protocol': 'AES',
'log_snmp_encryption_password': 'snmp_encrypt_password',
'log_snmp_trap_community': 'snmp_trap_name',
'log_snmp_inform_servers': [
{
'position': 0,
'server': '203.0.113.6',
'port': 162,
'community': 'roinform',
'version': 3,
'secname': '444_inform',
'auth_protocol': 'SHA',
'auth_password': 'auth_password',
'encryption_protocol': 'AES',
'encryption_password': 'encrypt_password'
}
],
'log_snmp_trap_servers': [
{
'position': 0,
'server': '203.0.113.7',
'port': 162,
257
Description
Email address
for the FROM
field
Security Analytics Reference Guide
Security Analytics 8.1
'community': '999_inform',
'version': 3,
'secname': '999_trap',
'auth_protocol': 'SHA',
'auth_password': 'auth_password',
'encryption_protocol': 'AES',
'encryption_password': 'encrypt_password'
}
],
'log_snmp_authtrap': 1,
'log_syslog_coalescing': 1,
'log_syslog_facility': 16,
'log_syslog_servers': [
{
'position': 0,
'server': '203.0.113.8',
'port': 514,
'protocol': 'tls-fips'
},
{
'position': 1,
'server': '203.0.113.9',
'port': 55514,
'protocol': 'udp'
}
]
}
})
PHP Example
Configure the SMTP server, an SNMP inform server, an SNMP trap server, and two syslog servers.
callAPI('POST','/settings/logging_settings',
array('settings'=>
array(
'log_email_address' => 'sysadmin@domain.com',
'log_email_sender' => 'SA-24@domain.com',
'log_email_smtp_server' => '203.0.113.5',
'log_email_smtp_port' => 25,
'log_email_auth_optional' => 0,
'log_email_smtp_username' => 'admin',
'log_email_smtp_password' => 'smtp_password',
'log_email_use_starttls' => 1,
'log_global_communication_email' => 'SA-27@domain.com',
'log_snmp_snmpdenable' => 1,
'log_snmp_ro_user' => 'public',
'log_snmp_ro_community' => 'public',
'log_snmp_version' => 1,
'log_snmp_auth_protocol' => 'SHA',
'log_snmp_auth_password' => 'snmp_auth_password',
'log_snmp_encryption_protocol' => 'AES',
'log_snmp_encryption_password' => 'snmp_encrypt_password',
'log_snmp_trap_community' => 'snmp_trap_name',
'log_snmp_inform_servers' => array(
array(
'position' => 0,
'server' => '203.0.113.6',
'port' => 162,
'community' => 'roinform',
'version' => 3,
'secname' => '444_inform',
'auth_protocol' => 'SHA',
'auth_password' => 'auth_password',
'encryption_protocol' => 'AES',
'encryption_password' => 'encrypt_password'
)
),
258
Security Analytics Reference Guide
Security Analytics 8.1
'log_snmp_trap_servers' => array(
array(
'position' => 0,
'server' => '203.0.113.7',
'port' => 162,
'community' => '999_inform',
'version' => 3,
'secname' => '999_trap',
'auth_protocol' => 'SHA',
'auth_password' => 'auth_password',
'encryption_protocol' => 'AES',
'encryption_password' => 'encrypt_password'
)
),
'log_snmp_authtrap' => 1,
'log_syslog_coalescing' => 1,
'log_syslog_facility' => 16,
'log_syslog_servers' => array(
array(
'position' => 0,
'server' => '203.0.113.8',
'port' => 514,
'protocol' => 'tls-fips'
),
(
'position' => 1,
'server' => '203.0.113.9',
'port' => 55514,
'protocol' => 'udp'
)
)
)
)
))
Enable or disable remote-notification types
API Path
/settings/logging_categories
Description
Enable and disable remote notifications per category and method
GUI Location
Menu
> Settings > Communication > Advanced > Remote Notifications
Output
Boolean
259
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ Format Default
categories
X
array
—
Valid Inputs
array( 'categories' => array(
'<GET: /settings/logging_
categories>' => array( '<method>'
=> [true | false], '<method>' =>
[true | false] ),
'<GET: /settings/logging_
categories>' => array( '<method>'
=> [true | false], '<method>' =>
[true | false] ) )
Description
n
category — Audit Log
categories
n
method — local, email,
snmp, syslog
o
n
Python Example
s.callAPI("POST","/settings/logging_categories", {
'categories': {
'system': {
'email': True,
'snmp': True,
'syslog': True,
'local: False
},
'alert': {
'snmp': True,
'syslog': True,
'local': False
},
'capture': array(
'snmp': False,
'syslog': False,
'local': False
}
}
)
PHP Example
callAPI('POST','/settings/logging_categories',
array(
'categories' => array(
'system' => array(
'email' => true,
'snmp' => true,
'syslog' => true,
'local' => false
),
'alert' => array(
'snmp' => true,
'syslog' => true,
'local' => false
),
'capture' => array(
'snmp' => false,
'syslog' => false,
'local' => false
)
)
)
);
260
email method is
not valid for the
deepsee (Report
Events) category
Unspecified categories or
methods are set to false
Security Analytics Reference Guide
Security Analytics 8.1
Configure a remote-notification template
API Path
/settings/save_template
Description
Save a remote-notification template
GUI Location
Menu
> Settings > Communications > Templates > New
Output
array
Parameters
REQ
uuid
name
type
Format
UUID | null
X
string
Default
null
Valid Inputs
null | <GET: /settings/get_
templates>
<UTF-8 characters>
Description
n
Create new — Use null
n
Edit entry — UUID
required
n
Create new — Name
required
n
Edit entry — New name
X
string
smtp | snmp | syslog
X
string
<UTF-8 characters>
Valid only if type=smtp; subject
line of email
delimiter
X
string
; | <> | \ | : | , | {} | "" |
/ | () | . | | | ' | \s | () |
\t
Character to delimit key/value
pairs
keyvaluepair
X
string
<primary_filter_attribute>
Attributes from the primary filter
email_
subject
Python Example
s.callAPI("POST","/settings/save_template", {
'uuid': null,
'name': 'snmp-00',
'type': 'snmp',
'email_subject': 'SNMP message',
'delimiter': ';',
'keyvaluepair': [
'application_id',
'country',
'ipv4_responder',
'port_responder'
]
261
Type of template
Security Analytics Reference Guide
Security Analytics 8.1
}
)
PHP Example
callAPI('POST','/settings/save_template',
array(
'uuid' => null,
'name' => 'snmp-00',
'type' => 'snmp',
'email_subject' => 'SNMP message',
'delimiter' => ';',
'keyvaluepair'=> array(
'application_id',
'country',
'ipv4_responder',
'port_responder'
)
)
)
);
Clear the audit log
API Path
/settings/erase_log
Description
Clear all audit log entries
GUI Location
Menu
> Settings > Communication > Advanced > Clear Log Entries
Output
[null]
Parameters
None
Python Example
s.callAPI("POST","/settings/erase_log")
PHP Example
callAPI('POST','/settings/erase_log');
Upload a new settings file
API Path
/settings/logging_advanced
262
Security Analytics Reference Guide
Security Analytics 8.1
Description
Upload a new communication settings file, which overwrites the old settings
GUI Location
Menu
> Settings > Communication > Browse > Import Communication Settings
Output
Boolean
Parameters
REQ
Format
X
file
file
Default
Valid Inputs
—
<filename>.dat
Description
DAT-formatted settings file
Python Example
s.callAPI("POST","settings/logging_advanced", {
'file': '<filename>.dat'
}
)
PHP Example
callAPI('POST','settings/logging_advanced',
array(
'file' => '<filename>.dat'
)
);
Delete template
API Path
/settings/delete_template/<id>
Description
Delete a remote-notification template
GUI Location
Menu
> Settings > Communication > Templates
Output
Boolean
Parameters
id
REQ
Format
X
UUID
Default
—
Valid Inputs
Description
<GET: /settings/get_templates>
Template ID
263
Security Analytics Reference Guide
Security Analytics 8.1
Python Example
s.callAPI("POST","settings/delete_template/<template_id>")
PHP Example
callAPI('POST','settings/delete_template/<template_id>');
n
placeholder
n
All Files
264
Security Analytics Reference Guide
Security Analytics 8.1
Location:
Metadata APIs
To see all APIs click the Expand All
icon at the top of the page.
265
Security Analytics Reference Guide
Security Analytics 8.1
266
Security Analytics Reference Guide
Security Analytics 8.1
© 2019 Symantec Corporation | Security Analytics 8.1 | Updated: Wednesday, August 7, 2019
About | Support | Feedback | Forums
version of online help might not contain the most up-to-date information. For the current documentation, go to Security Analytics Product
Documentation.
267
Security Analytics Reference Guide
Security Analytics 8.1
Network APIs
Get network settings
API Path
/settings/network
Description
Retrieve network settings for the appliance
GUI Location
n
Initial Configuration
n
Menu
> Settings > Network
Output
array
Parameters
None
Example
callAPI('GET','/settings/network');
Configure the management interface
API Path
/settings/network/management_interfaces
Description
Configure the bond0 management interface with one or two physical interfaces.
GUI Location
Menu
> Settings > Network > Use Multiple Management Interfaces
Parameters
management_interfaces
REQ
Format
Default
Valid Inputs
X
string
—
eth<X>
268
Description
Physical
interfaces
on the
appliance
(limit:2)
Security Analytics Reference Guide
Security Analytics 8.1
Example
s.callAPI("POST","/settings/network/management_interfaces", {
'management_interfaces': [
'eth0',
'eth1'
]
})
Restart network interfaces
API Path
/settings/network/restart
Description
Restart the network interfaces, including the capture interfaces
GUI Location
n/a
Parameters
None
Example
callAPI('POST','/settings/network/restart');
Configure appliance name
API Path
/settings/network/system_name
Description
Set or edit system name
GUI Location
n
Initial Configuration
n
Menu
> Settings > Network
Output
API_REBOOT_CODE
Parameters
system_name
REQ
Format
Default
Valid Inputs
X
string
—
<UTF-8 characters>
269
Description
Host name of appliance
Security Analytics Reference Guide
Security Analytics 8.1
Example
callAPI('POST','/settings/network/system_name',
array(
'system_name' => 'SA-0143'
)
);
Configure IP settings
API Path
/settings/network/ip_address
Description
Set or edit IP addresses
GUI Location
n
Initial Configuration
n
Menu
> Settings > Network
Output
ApiResultCode
Parameters
REQ
Format
Default
Valid Inputs
Description
Boolean
false
true | false
True — Enable DHCP and ignore
the rest of the settings
ip_address
string
—
<dotted-decimal>
IPv4 address for bond0
ip_address_secondary
string
—
<dotted-decimal>
Secondary IPv4 address for bond0
netmask
string
—
<dotted-decimal>
Network mask
netmask_secondary
string
—
<dotted-decimal>
Secondary network masks
gateway
string
—
<dotted-decimal>
Gateway
gateway_secondary
string
<dotted-decimal>
Secondary gateways
ipv6_address
string
—
ipv6_secondaries
string
—
ipv6_gateway
string
—
dhcp
[<ipv6>]
Primary IPv6 address for bond0
[<ipv6>],[<ipv6>] Secondary IPv6 addresses for
bond0, comma-delimited
[<ipv6>]
Example
callAPI('POST','/settings/network/ip_address',
array(
'dhcp' => false,
'ip_address' => '203.0.113.5',
'netmask' => '255.255.255.0',
270
IPv6 gateway
Security Analytics Reference Guide
Security Analytics 8.1
'gateway' => '203.0.113.1',
'ipv6_address' => '[2026:fe33:21:a1:a5f7::0a02]'
'ipv6_secondaries' => '[2001:0db8::ff90:0a02]','[fc00::20ad:0045]'
'ipv6_gateway' => '[2026:fe33:21:a1::1]'
)
);
Configure DNS
API Path
/settings/network/dns
Description
Create or edit DNS settings
GUI Location
n
Initial Configuration
n
Menu
> Settings > Network
Output
ApiResultCode
Parameters
REQ
Format
Default
Valid Inputs
Description
X
string
—
<ip_address>
Primary
DNS server
secondary_dns
string
—
<ip_address>
Secondary
DNS server
tertiary_dns
string
—
<ip_address>
Tertiary
DNS server
override_dns
Boolean
false
true | false
True —
Override
DNS checks
and forcesave the
settings
primary_dns
Example
callAPI('POST','/settings/network/dns',
array(
'primary_dns' => '203.0.113.5',
'secondary_dns' => '203.0.113.6',
'tertiary_dns' => '2620:aa:3001:55:faff::5',
'override_dns' => true
)
);
271
Security Analytics Reference Guide
Security Analytics 8.1
Configure HTTP proxy
API Path
/settings/network/http_proxy
Description
Create or edit HTTP proxy settings
GUI Location
n
Initial Configuration
n
Menu
> Settings > Network
Output
API_REBOOT_CODE
Parameters
http_proxy
REQ
Format
Default
X
string
—
Example
callAPI('POST','/settings/network/http_proxy',
array(
'http_proxy' => 'http://203.0.113.5:8080'
)
);
Configure No Proxy settings
API Path
/settings/network/no_proxy
Description
Set the No Proxy settings
GUI Location
n
Initial Configuration
n
Menu
> Settings > Network
Output
API_REBOOT_CODE
272
Valid Inputs Description
http://
<hostname>
:<port>
Web proxy server
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
no_proxy
REQ
Format
Default
Valid Inputs
X
string
—
<domain>
.<tld> | <ip_
address>
Example
callAPI('POST','/settings/network/no_proxy',
array(
'no_proxy' => 'symantec.com,203.0.113.5'
)
);
273
Description
Comma-delimited list
of domains or IP
addresses to bypass
the proxy.
Security Analytics Reference Guide
Security Analytics 8.1
Packet Analyzer APIs
Get packet analyzer summary
API Path
/packet_analyzer/packets
Description
Retrieve packet analyzer summary data
GUI Location
n
Menu
Packets
> Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > Actions > Analyze
n
Menu
> Analyze > Summary > Extractions > [artifact entry] > Analyze PCAP
Output
array
Parameters
REQ
pcap
Format Default
Valid Inputs
Description
string
—
/timespan/<YYYY-MMDD>T<hh:ii:ss>
_<YYYY-MMDD>T<hh:ii:ss>/data.pcap[ng]
startPacket
integer
1
1–<n>
Packet number of the first packet to
retrieve within the pcap timespan
packetCount
integer
1000
1–1000
Number of packets to retrieve
filter
string
—
<Wireshark display filter>
X
PCAP path
Filter in Wireshark format
Example
callAPI('GET','/packet_analyzer/packets',
array(
'pcap' => '/timespan/2019-11-23T00:00:00_2019-11-23T00:25:59/data.pcapng',
'startPacket' => 25,
'packetCount' => 1000,
'filter' => 'ip.src==192.0.2.0/24 and ip.dst==203.0.113.0/24'
)
);
Get packet details
API Path
/packet_analyzer/detail
274
Security Analytics Reference Guide
Security Analytics 8.1
Description
Retrieve details about a specific packet.
GUI Location
n
Menu
> Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > Actions > Analyze
Packets > [click packet; second panel]
n
Menu
> Analyze > Summary > Extractions > [artifact entry] > Analyze PCAP > [click packet; second panel]
Output
array
Parameters
REQ
pcap
X
packet
Format Default
/timespan/<YYYY-MM-DD>T<hh:ii:ss>_
<YYYY-MM-DD>T<hh:ii:ss>/data.pcap
[ng]
string
integer
Valid Inputs
1
<GET: /packet_analyzer/packets>
Description
PCAP path
ID of the packet to retrieve
Example
callAPI('GET','/packet_analyzer/detail'
array(
'pcap' => '/timespan/2019-11-23T00:00:00_2019-11-23T00:25:59/data.pcapng',
'packet' => '300'
),
);
Get PCAP from packet analyzer
API Path
/packet_analyzer/download
Description
Download a PCAP from the packet analyzer
GUI Location
n
Menu
> Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > Actions > Analyze
Packets > Download PCAP
n
Menu
> Analyze > Summary > Extractions > [artifact entry] > Analyze PCAP > Download PCAP
Output
ApiResultCode
275
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
Format
Default
X
string
—
pcapType
string
pcapng
pcap | pcapng
filter
string
—
<Wireshark display filter>
pcap
Valid Inputs
Description
/timespan/<YYYY-MM-DD>T<hh:ii:ss>_
PCAP path
<YYYY-MM-DD>T<hh:ii:ss>/data.pcap[ng]
If filter is specified,
pcapType=pcap
Filter in Wireshark format
Example
callAPI('GET','/packet_analyzer/download'
array(
'pcap' => '/timespan/2019-11-23T00:00:00_2019-11-23T00:25:59/data.pcap',
'pcapType' => 'pcap'
'filter' => 'ip.src==192.0.2.0/24 and ip.dst==203.0.113.0/24'
)
);
276
Security Analytics Reference Guide
Security Analytics 8.1
PCAP APIs
Get estimated PCAP size
API Path
/deepsee_reports/pcapsize
Description
Retrieve the estimated size of the PCAP
GUI Location
Menu
> Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > [More Information | Actions >
Download PCAP]
Output
array
Parameters
REQ
Format
query
X
array
timespan
X
JSON
Default
Valid Inputs
Description
—
<primary filter array>
Primary filter
—
<timespan array>
Python Example
s.callAPI("GET","deepsee_reports/pcapsize", {
'query': [
'port>50000',
'application_id=dns,http'
],
'timespan': json.dumps({
'start': '2019-11-03T10:00:00',
'end': '2019-11-03T10:10:00'
})
}
)
PHP Example
callAPI('GET','deepsee_reports/pcapsize',
array(
'query' => array(
'port>50000',
'application_id=dns,http'
),
'timespan' => json_encode(
array(
'start' => '2019-11-03T10:00:00',
'end' => '2019-11-03T10:10:00'
)
)
)
);
277
Start and end times for the PCAP
Security Analytics Reference Guide
Security Analytics 8.1
Download a PCAP from indexing drive parameters
API Path
/pcap/download/deepsee
Description
Download a PCAP according to Indexing DB parameters
GUI Location
n/a
Output
ApiResultCode
Parameters
REQ
Format
path
X
string
—
<Indexing DB path>
PCAP path
name
X
string
—
<UTF-8 characters>
Name for the file
pcapType
string
pcapng
pcap | pcapng
download
array
—
integer
—
type
mountId
string
Default
—
Valid Inputs
Description
PCAP format
Download parameters; array includes type
and mountId
1 | 2 | 3
<GET: /pcap_
import/mount_points>
Download type
n
1 — Browser
n
2 — NFS/CIFS
n
3 — Prepare download
Mount point IDs; valid if type=2
Python Example
s.callAPI("GET","/pcap/download/deepsee",{
'path': '/timespan/2019-11-23T00:00:00_2019-11-23T00:21:59/application_
id/runescape/country/china/ip_responder/48.55.187.0/24',
'name': '2019-11-23_china-runescape',
'pcapType': 'pcap',
'download': {
'type': 2,
'mountId': '<mount_id>'
}
}, '<filename>.pcap'
)
PHP Example
callAPI('GET','/pcap/download/deepsee',
array(
278
Security Analytics Reference Guide
Security Analytics 8.1
'path' => '/timespan/2019-11-23T00:00:00_2019-11-23T00:21:59/application_
id/runescape/country/china/ip_responder/48.55.187.0/24',
'name' => '2019-11-23_china-runescape',
'pcapType' => 'pcap',
'download' => array(
'type' => 2,
'mountId' => '<mount_id>'
)
), <filename>.pcap
);
Download PCAP from merge path using path parts
API Path
/pcap/download/merge
Description
Download a PCAP from /pfs/merge using path parts
GUI Location
Menu
> Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > [More Information | Actions >
Download PCAP] > PCAP without PCAP Filters download
Output
ApiResultCode
Parameters
REQ
Format
X
array
ethX| aggX| ifbX
Capture interface(s)
start
X
string
<YYYY-MM-DD>T<hh:ii:ss>
Start date and time
stop
X
string
<bytes>|<YYYY-MMDD>T<hh:ii:ss>
interfaces
type
string
filter
string
Default
date
Valid Inputs
size | date
<BPF expression>
Python Example
s.callAPI("GET","/pcap/download/merge", {
'interfaces': [
'eth2',
'eth3',
'agg1'
],
'start': '2019-11-23T00:00:00',
'stop': '2019-11-23T00:07:59',
'type': 'date',
'filter': '(net 203.0.113.0 mask 255.255.248.0)'
279
Description
n
If type=size then stop=<bytes>
n
If type=date then stop=<YYYYMM-DD>T<hh:ii:mm>
Method to calculate stop
Capture filter
Security Analytics Reference Guide
Security Analytics 8.1
}, '<filename>.pcap'
)
PHP Example
callAPI('GET','/pcap/download/merge',
array(
'interfaces' => array(
'eth3',
'eth3',
'agg1'
),
'start' => '2019-11-23T00:00:00',
'stop' => '2019-11-23T00:07:59',
'type' => 'date',
'filter' => '(net 203.0.113.0 mask 255.255.248.0)'
), <filename>.pcap
);
Download a PCAP from merge path
API Path
/pcap/download/merge_path
Description
Download a PCAP from /pfs/merge
GUI Location
n/a
Output
ApiResultCode
Parameters
REQ Format Default
path
filter
X
merge
path
string
—
—
Valid Inputs
Description
[<ethX>:]<ethX>-<MM.DD.YYYY.hh.ii.ss>:d<MM.DD.YYYY.hh.ii.ss>:d
Time-delimited end
[<ethX>:]<ethX>-<MM.DD.YYYY.hh.ii.ss>:d<bytes>:s
Size-delimited end
<BPF expression>
Python Example
s.callAPI("GET","/pcap/download/merge_path",{
'path': 'eth3:agg1-2019.11.23.00.00.00:d-2019.11.23.00.07.59:d',
'filter': '(net 203.0.113.0 mask 255.255.248.0)'
}, '<filename>.pcap'
)
280
Capture filter
Security Analytics Reference Guide
Security Analytics 8.1
PHP Example
callAPI('GET','/pcap/download/merge_path',
array(
'path' => 'eth3:agg1-2019.11.23.00.00.00:d-2019.11.23.00.07.59:d',
'filter' => '(net 203.0.113.0 mask 255.255.248.0)'
), <filename>.pcap
);
Download PCAP using primary filter path
API Path
/pcap/download/query
Description
Download a PCAP using the primary filter path
GUI Location
Menu
> Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > [More Information >
Download | Actions > Download PCAP]
Output
ApiResultCode
Parameters
REQ
Format
X
JSON
—
<timespan array>
query
array
—
<primary filter array>
pcapType
string
pcapng
pcap | pcapng
download
array
—
integer
—
timespan
type
mountId
filter
X
Default
Valid Inputs
Description
Start and end times for the PCAP
Primary bar filters
PCAP format
Download parameters; array includes
type and mountId
1 | 2 | 3
string
—
<GET: /pcap_
import/connections>
string
—
<BPF expression>
Python Example
s.callAPI("GET","/pcap/download/query", {
'timespan': {
'start': '2019-11-23T00:00:00',
'end': '2019-11-23T00:07:59'
281
Download type
n
1 — Browser
n
2 — NFS/CIFS
n
3 — Prepare download
Mount point IDs; valid if type=2
Capture filter to apply to the PCAP
Security Analytics Reference Guide
Security Analytics 8.1
},
'query': [
'port=80',
'filename~exe'
],
'pcapType': 'pcap',
'download': {
'type': '2',
'mountId': '<mount_id>'
}
'filter': '(net 203.0.113.0 mask 255.255.248.0)'
}, '<filename>.pcap'
)
PHP Example
callAPI('GET','/pcap/download/query',
array(
'timespan' => json_encode(
array(
'start' => '2019-11-23T00:00:00',
'end' => '2019-11-23T00:07:59'
),
),
'query' => array(
'port=80',
'filename~exe'
),
'pcapType' => 'pcap',
'download' => array(
'type' => '2',
'mountId' => '<mount_id>'
)
'filter' => '(net 203.0.113.0 mask 255.255.248.0)'
), <filename>.pcap
);
Python Example
s.callAPI("GET","/pcap/download/query", {
'timespan': {
'start': '2019-11-23T00:00:00',
'end': '2019-11-23T00:07:59'
},
'query': [
'port=80',
'filename~exe'
],
'pcapType': 'pcap',
'download': {
'type': '2',
'mountId': '<mount_id>'
}
'filter': '(net 203.0.113.0 mask 255.255.248.0)'
}, '<filename>.pcap'
)
Get list of mount points
API Path
/pcap_import/connections
Description
Retrieve a paginated list of mount points
282
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
Menu
> Capture > Import PCAP > Manage Connections
Output
array
Parameters
page
REQ
Format
Default
Valid Inputs
X
integer
—
1–<n>
Page to retrieve; first page is
1
integer
25
1–100
Number of rows per page
string
asc
asc | desc
string
null
limit
direction
sort
Description
Sort order
mount_id | server_name | port_num | Sort-by field
remote_location | username |
password | protocol | alias |
active | last_modified_date |
refcount | export_refcount
Python Example
s.callAPI("GET","/pcap_import/connections", {
'page': 10,
'limit': 20,
'direction': 'desc',
'sort': 'protocol'
}
)
PHP Example
callAPI('GET','/pcap_import/connections',
array(
'page' => 10,
'limit' => 20,
'direction' => 'desc',
'sort' => 'protocol'
)
);
Get USB mount point files and folders
API Path
/pcap_import/explore_local
Description
Retrieve a list of files and directories in the attached USB directory
283
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
Menu
> Capture > Import PCAP > Imports > New > Import from Appliance USB Drive
Output
array
Parameters
REQ
path
Format
string
Default
/
Valid Inputs
/ | /<folder_on_usb_drive>/
Description
USB directory to explore
Python Example
s.callAPI("GET","/pcap_import/explore_local", {
'path': '/temp/PCAPs/'
}
)
PHP Example
callAPI('GET','/pcap_import/explore_local',
array(
'path' => '/temp/PCAPs/'
)
);
Get remote mount point files and folders
API Path
/pcap_import/explore_remote/<mountId>
Description
Get remote mount-point files and folders from a specified mount point
GUI Location
n
Menu
> Capture > Import PCAP > Manage Connections > Edit
n
Menu
> Capture > Import PCAP > Watch Folders > New
n
Menu
> Analyze > Rules > [New | Edit] > PCAP Export Server
n
Menu
> Capture > Import PCAP > Imports > New > Import from Remote Server
Output
array
284
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
Format
Default
Valid Inputs
X
integer
—
<GET: /pcap_import/connections>
string
/
/<filepath>/
mountId
path
Description
Mount point ID
Folder path
Python Example
s.callAPI("GET","/pcap_import/explore_remote/<mountId>", {
'path': '/<path>/'
}
)
PHP Example
callAPI('GET','/pcap_import/explore_remote/<mountId>',
array(
'path' => '/<path>/'
)
);
Get list of PCAP import jobs
API Path
/pcap_import/jobs/<jobStatus>
Description
Retrieve a paginated list of jobs, by job status
GUI Location
Menu
> Capture > Import PCAP > Imports
Output
array
Parameters
jobStatus
REQ
Format
X
integer
Default
—
Valid Inputs
0 | 1 | 2 | 3 | 4 | 5
285
Description
Status of jobs to retrieve
n
0 — Scheduled
n
1 — Queued
n
2 — Running
n
3 — Complete
n
4 — Failed
n
5 — Canceled
Security Analytics Reference Guide
REQ
Security Analytics 8.1
Format
Default
Valid Inputs
page
integer
—
1–<n>
Page to retrieve; first page is 1
limit
integer
—
1–100
Number of items per page
string
desc
asc | desc
string
null
direction
sort
job_id | schedule_id | mount_id
| import_type | iface_name |
pcap_file | retain_timestamp |
import_status | bytes_written |
packets_imported | packets_
dropped | file_size | created_
time | start_time | end_time |
result_summary | first_packet_
time | last_packet_time |
import_failure_reason | start_
slot_id | start_element | end_
slot_id | end_element | user_id
| shared | import_version
Python Example
s.callAPI("GET","/pcap_import/jobs/<jobStatus>", {
'jobStatus': 3,
'page': 2,
'limit': 25,
'direction': 'asc',
'sort': 'file_size'
}
)
PHP Example
callAPI('GET','/pcap_import/jobs/<jobStatus>',
array(
'jobStatus' => 3,
'page' => 2,
'limit' => 25,
'direction' => 'asc',
'sort' => 'file_size'
)
)
);
Get all mount points
API Path
/pcap_import/mount_points
Description
Retrieve a list of mount points.
286
Description
Sort order
Sort-by field
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
n
Menu
> Capture > Import PCAP > Manage Connections
n
Menu
> Capture > Import PCAP > Watch Folders > New
n
Menu
> Analyze > Rules > [New | Edit] > PCAP Export Server
Output
array
Parameters
None
Python Example
s.callAPI("GET","/pcap_import/mount_points")
PHP Example
callAPI('GET','/pcap_import/mount_points');
Get a list of watch folders
API Path
/pcap_import/schedules
Description
Retrieve a paginated list of watch folders
GUI Location
Capture > Import PCAP > Watch Folders
Output
array
Parameters
REQ
Format
Default
Valid Inputs
Description
page
integer
—
1–<n>
Page to retrieve; first page is
1
limit
integer
—
1–100
Number of items per page
string
desc
asc | desc
direction
287
Sort direction
Security Analytics Reference Guide
REQ
sort
Security Analytics 8.1
Format
Default
null
string
Valid Inputs
Description
schedule_id | mount_id | directory Sort-by field
| start_date | end_date | run_freq
| retain_timestamp | last_
modified_date | active
Python Example
s.callAPI("GET","/pcap_import/schedules", {
'page': 10,
'limit': 20,
'direction': 'asc',
'sort': 'schedule_id'
}
)
PHP Example
callAPI('GET','/pcap_import/schedules',
array(
'page' => 10,
'limit' => 20,
'direction' => 'asc',
'sort' => 'schedule_id'
)
);
Get PCAP upload status
API Path
/pcap_import/upload_progress/<jobid>
Description
Retrieve the PCAP upload status
GUI Location
Menu
> Capture > PCAP Import > Imports > Status field
Output
array
Parameters
jobid
REQ
Format
X
integer
Default
—
Valid Inputs
Description
<GET: /pcap_import/init_
Job ID
upload/<pcapFile>/<retainTimestamp>/<shared>
>
Python Example
s.callAPI("GET","/pcap_import/upload_progress/<jobid>")
288
Security Analytics Reference Guide
Security Analytics 8.1
PHP Example
callAPI('GET','/pcap_import/upload_progress/<jobid>');
Import PCAP from USB drive
API Path
/pcap_import/import_local
Description
Creates a new job and begins importing a PCAP from an attached USB drive.
GUI Location
Menu
> Capture > Import PCAP > Imports > New > Import from Appliance USB Drive
Output
array
Parameters
REQ
Format
files
X
array
—
<GET: /pcap_import/explore_
local>
retain
X
integer
—
0 | 1
shared
Boolean
Default
Valid Inputs
true
true | false
Python Example
s.callAPI("POST","/pcap_import/import_local", {
'files':[
'/pcapng/pcap-004.pcapng',
'/pcapng/pcap-005.pcapng'
],
'retain': 0,
'shared': False
}
)
PHP Example
callAPI('POST','/pcap_import/import_local',
array(
'files' => array(
'/pcapng/pcap-004.pcapng',
'/pcapng/pcap-005.pcapng'
),
'retain' => 0,
'shared' => false
289
Description
Array of PCAP files on the USB
drive
n
0 — Do not retain
timestamps
n
1 — Retain original
timestamps
True — Shared PCAP
Security Analytics Reference Guide
Security Analytics 8.1
)
);
Import PCAP from mount point
API Path
/pcap_import/import_remote
Description
Creates a new job and begins importing a PCAP from a mount point
GUI Location
Menu
> Capture > Import PCAP > Imports > New > Import from Remote Server
Output
array
Parameters
REQ
Format
files
X
array
—
<GET: /pcap_import/explore_
remote/<mountId>
retain
X
integer
—
0 | 1
startOffset
X
shared
Default
Valid Inputs
integer
—
1–<n>
Boolean
true
true | false
Python Example
s.callAPI("POST","/pcap_import/import_remote", {
'files': [
'/pcap/pcap-007.pcap',
'/pcap/pcap-008.pcap'
],
'retain': 0,
'startOffset': 3600,
'shared': False
}
)
PHP Example
callAPI('POST','/pcap_import/import_remote',
array(
'files' => array(
'/pcap/pcap-007.pcap',
'/pcap/pcap-008.pcap'
),
'retain' => 0,
290
Description
Array of remote locations
n
0 — Do not retain
timestamps
n
1 — Retain original
timestamps
Number of seconds from now
before starting the import.
True — Shared PCAP
Security Analytics Reference Guide
Security Analytics 8.1
'startOffset' => 3600,
'shared' => false
)
);
Import PCAP from workstation
API Path
/pcap_import/init_upload/<pcapFile>/<retainTimestamp>/<shared>
Description
Creates a new job and begins importing a PCAP from the local workstation
GUI Location
Menu
> Capture > Import PCAP > Imports > New > Import from My Computer
Output
integer
Parameters
pcapFile
retainTimestamp
shared
REQ
Format
X
URL
encoding
—
<URL-encoding>.pcap |
<URL-encoding>.pcapng
X
integer
—
0 | 1
X
integer
Default
Valid Inputs
—
0 | 1
Python Example
s.callAPI("POST","/pcap_import/init_upload/HTTP%20from%20China.pcapng/0/1")
PHP Example
callAPI('POST','/pcap_import/init_upload/HTTP%20from%20China.pcapng/0/1');
291
Description
URL-encoded
name of the PCAP
file
n
0 — Do not
retain
timestamps
n
1 — Retain
original
timestamps
n
0 — Nonshared
PCAP
n
1 — Shared
PCAP
Security Analytics Reference Guide
Security Analytics 8.1
Upload PCAP chunks
API Path
/pcap_import/upload/<jobid>/<index>/<chunks>
Description
After you split up a large PCAP into smaller chunks, use this API to upload the chunks in order, for reassembly. To
upload a non-chunked file, set index and chunks to 0.
GUI Location
n/a
Output
array
Parameters
REQ
Format
Default
Valid Inputs
Description
jobid
X
integer
—
index
X
integer
—
0–<n>
Position in the
sequence of
chunks. Zero-based
count.
chunks
X
integer
—
0–<n>
Total number of
chunks
file
X
string
—
<UTF-8 characters>
The name of the
PCAP file chunk.
<GET: /pcap_import/init_
Job ID
upload/<pcapFile>/<retainTimestamp>/<shared>
>
Python Example
Original PCAP is named extreme-behemoth.pcapng. You have divided the PCAP into 4 chunks.
Create the Job ID, discard the original timestamps, and mark it as shared.
s.callAPI("POST","/pcap_import/init_upload/extreme-behemoth.pcapng/0/true")
Returns job ID 42.
s.callAPI("POST","/pcap_import/upload/42/0/4",{
'file':'extreme-behemoth.pcapng.chunk1'
}
)
292
Security Analytics Reference Guide
Security Analytics 8.1
s.callAPI("POST","/pcap_import/upload/42/1/4",{
'file':'extreme-behemoth.pcapng.chunk2'
}
)
s.callAPI("POST","/pcap_import/upload/42/2/4",{
'file':'extreme-behemoth.pcapng.chunk3'
}
)
s.callAPI("POST","/pcap_import/upload/42/3/4",{
'file':'extreme-behemoth.pcapng.chunk4'
}
)
PHP Example
Original PCAP is named extreme-behemoth.pcapng. You have divided the PCAP into 4 chunks.
Create the Job ID, discard the original timestamps, and mark it as shared.
callAPI('POST','/pcap_import/init_upload/extreme-behemoth.pcapng/0/true');
Returns job ID 42.
callAPI('POST','/pcap_import/upload/42/0/4',
array(
'file' => 'extreme-behemoth.pcapng.chunk1'
)
);
callAPI('POST','/pcap_import/upload/42/1/4',
array(
'file' => 'extreme-behemoth.pcapng.chunk2'
)
);
callAPI('POST','/pcap_import/upload/42/2/4',
array(
'file' => 'extreme-behemoth.pcapng.chunk3'
)
);
callAPI('POST','/pcap_import/upload/42/3/4',
array(
'file' => 'extreme-behemoth.pcapng.chunk4'
)
);
Cancel PCAP upload
API Path
/pcap_import/upload_canceled/<jobid>
Description
Cancel PCAP upload
293
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
Menu
> Capture > Import PCAP > Imports > [close browser page | reload browser page]
Output
array
Parameters
REQ
Format
Default
X
integer
—
jobid
Valid Inputs
Description
<GET: /pcap_import/init_
Job ID
upload/<pcapFile>/<retainTimestamp>/<shared>
>
Python Example
s.callAPI("POST","/pcap_import/upload_canceled/<jobid>")
PHP Example
callAPI('POST','/pcap_import/upload_canceled/<jobid>');
Mark PCAP upload as failed
API Path
/pcap_import/upload_failed/<jobid>/<error>
Description
Mark a PCAP upload job as failed
GUI Location
Menu
> Capture > PCAP Import > Imports > Status field
Output
array
Parameters
REQ
Format
Default
jobid
X
integer
—
error
X
integer
—
Valid Inputs
Description
<GET: /pcap_import/init_
Job ID
upload/<pcapFile>/<retainTimestamp>/<shared>
>
0
Python Example
s.callAPI("POST","/pcap_import/upload_failed/<jobid>/0")
294
Only 0 (zero) is valid
Security Analytics Reference Guide
Security Analytics 8.1
PHP Example
callAPI('POST','/pcap_import/upload_failed/<jobid>/0');
Add watch folder
API Path
/pcap_import/watch
Description
Add a new watch folder
GUI Location
Menu
> Capture > Import PCAP > Watch Folders > New
Output
array
Parameters
REQ
Format
folders
X
array
—
<GET: /pcap_import/explore_
remote/<mountId>>
retain
X
integer
—
0 | 1
runFreq
X
integer
Default
—
Valid Inputs
1–<n>
Python Example
s.callAPI("POST","/pcap_import/watch", {
'folders': [
'%2Ftemp%2Fusers%2Fadmin%2Fpcaps%2F',
'%2Ftemp%2Fusers%2Fadmin%2FpcapNGS'
]
'retain': 0,
'runFreq': 10800
}
)
PHP Example
callAPI('POST','/pcap_import/watch',
array(
'folders' => array(
'%2Ftemp%2Fusers%2Fadmin%2Fpcaps%2F',
'%2Ftemp%2Fusers%2Fadmin%2FpcapNGS'
),
'retain' => 0,
'runFreq' => 10800
)
295
Description
Watch-folder paths, URL-encoded
n
0 — Do not retain timestamps
n
1 — Retain original
timestamps
Interval in minutes between folder
checks
Security Analytics Reference Guide
Security Analytics 8.1
);
Delete mount points
API Path
/pcap_import_mount_points/delete/<ids>
Description
Delete one or more mount points
GUI Location
Menu
> Capture > Import PCAP > Manage Connections
Output
array
Parameters
REQ
Format
X
integer
ids
Default
—
Valid Inputs
<GET: /pcap_import/connections>
Description
Comma-delimited list of mountpoint IDs.
Python Example
s.callAPI("POST","/pcap_import_mount_points/delete/<id1>,<id2>,<id3>")
PHP Example
callAPI('POST','/pcap_import_mount_points/delete/<id1>,<id2>,<id3>');
Create a PCAP mount point
API Path
/pcap_import_mount_points/save
Description
Create a PCAP server mount point
GUI Location
n
Menu
> Capture > Import PCAP > Manage Connections > Add New Server
n
Menu
> Analyze > Rules > New > PCAP Export Server > Add New Server
n
Menu
> Capture > Import PCAP > Imports > New > Import from Remote Server > New
296
Security Analytics Reference Guide
Security Analytics 8.1
Output
array
Parameters
alias
REQ
Format
X
string
protocol
serverName
X
portNum
Default
Valid Inputs
Description
—
<UTF-8 characters>
Display name
string
nfs
nfs | cifs
Server protocol
string
—
<hostname>|<dotted-decimal>
Server location
integer
0
0–65535
Port number
directory
X
string
—
/<filepath>/
username
X
string
—
<UTF-8 characters>
Valid if protocol=cifs
password
X
string
—
<UTF-8 characters>
Valid if protocol=cifs
Python Example
s.callAPI("POST","/pcap_import_mount_points/save", {
'alias': 'pcap_exports',
'protocol': 'cifs',
'serverName': 'fileserv.domain.com',
'portNum': 22,
'directory': '/pcaps/deepsee-exports/',
'username': 'admin',
'password': '55geT!meIn&*'
}
)
PHP Example
callAPI('POST','/pcap_import_mount_points/save',
array(
'alias' => 'pcap_exports',
'protocol' => 'cifs',
'serverName' => 'fileserv.domain.com',
'portNum' => 22,
'directory' => '/pcaps/deepsee-exports/',
'username' => 'admin',
'password' => '55geT!meIn&*'
)
);
Edit an existing mount point
API Path
/pcap_import_mount_points/edit/<id>
Description
Edit a mount point that has already been configured on the appliance.
297
Watch-folder path
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
Menu
> Capture > Import PCAP > Manage Connections
Output
array
Parameters
REQ
Format
id
X
integer
—
<GET: /pcap_import/connections>
Mount point ID
alias
X
string
—
<UTF-8 characters>
Display name
string
nfs
nfs | cifs
Server protocol
string
—
<hostname>|<dotted-decimal>
Server location
integer
0
1–66535
protocol
serverName
X
portNum
Default
Valid Inputs
Description
Port number; 0 — All ports
directory
X
string
—
/<filepath>/
username
X
string
—
<UTF-8 characters>
Valid if protocol=cifs
password
X
string
—
<UTF-8 characters>
Valid if protocol=cifs
Python Example
s.callAPI("POST","/pcap_import_mount_points/edit/<id>", {
'alias': 'pcap_exports',
'protocol': 'cifs',
'serverName': 'fileserv.domain.com',
'portNum': 22,
'directory': '/pcaps/deepsee-exports/',
'username': 'admin',
'password': '55geT!meIn&*'
}
)
PHP Example
callAPI('POST','/pcap_import_mount_points/edit/<id>',
array(
'alias' => 'pcap_exports',
'protocol' => 'cifs',
'serverName' => 'fileserv.domain.com',
'portNum' => 22,
'directory' => '/pcaps/deepsee-exports/',
'username' => 'admin',
'password' => '55geT!meIn&*'
)
);
Delete a watch folder
API Path
/pcap_import_schedules/delete/<id>
298
Watch-folder path
Security Analytics Reference Guide
Security Analytics 8.1
Description
Delete a PCAP-import schedule (watch folder)
GUI Location
Menu
> Capture > Import PCAP > Watch Folders > Delete entry
Output
array
Parameters
ids
REQ
Format
Default
Valid Inputs
X
integer
—
<GET: /pcap_import/schedules>
Python Example
s.callAPI("POST","/pcap_import_schedules/delete/<id>")
PHP Example
callAPI('POST','/pcap_import_schedules/delete/<id>');
299
Description
PCAP import ID
Security Analytics Reference Guide
Security Analytics 8.1
Playback APIs
Begin playback session
API Path
/regens/start
Description
Start a playback session
GUI Location
Menu
> Capture > Summary > Start Playback
Output
ApiResultCode
Parameters
REQ
Format
Default
Valid Inputs
Description
inputInterfaces
X
array
—
ethX | aggX
One or more input interfaces
outputInterface
X
string
—
ethX
timeSpan
X
array |
string
—
all | live | MM/DD/YYYY
hh:ii:ss [MM/DD/YYYY
hh:ii:ss]
filter
BPF
—
<BPF expression>
Example
callAPI('POST','/regens/start',
array(
'inputInterfaces' => array(
'eth1',
'eth3'
),
'outputInterface' => 'eth7',
'timeSpan' => array(
'11/03/2019 13:00:00',
'11/03/2019 15:59:59'
),
'filter' => '!(port 80 or 8080 or 443)',
300
Output interface
n
all — Replay the traffic
that was already
captured on this interface
n
live — Replay all traffic
as it is captured by the
input interface(s)
n
timespan array — Start
time for the first slot to
play back; omit the end
time to never stop (which
is "regeneration" rather
than "playback")
Capture filter
Security Analytics Reference Guide
Security Analytics 8.1
)
)
);
Delete playback session
API Path
/regens/delete/<id>
Description
Delete a playback session
GUI Location
Menu
> Capture > Summary > Stop Playback
Output
array
Parameters
id
REQ
Format
Default
Valid Inputs
X
string
—
<GET: /captures/get_all_
interfaces>
Example
callAPI('POST','/regens/delete/<id1>,<id2>,<id3>');
301
Description
Comma-delimited list of playback IDs
Security Analytics Reference Guide
Security Analytics 8.1
Report and Report Status APIs
Also see "Summary Page APIs" on page 369.
Run a report
API Path
/deepsee_reports/report
Description
Run a specified report
GUI Location
Menu
> Analyze > Summary > Reports
Parameters
REQ
Format
X
string |
integer
—
<identity path>
page
integer
0
0–<n>
Page to retrieve; first page is 0
pageSize
integer
25
1–100
Number of items per page
column
string
sessions
bytes | packets | sessions
| fragments | bad_csums |
artifacts
direction
string
desc
asc | desc
filters
array
—
<advanced report status
filter>
compType
string
none
bytes | packets | sessions
| none
compDate
array
—
<timespan array>
Timespan for the second report in the
comparison
metrics
array
sessions
bytes | packets | sessions
| fragments | bad_csums |
artifacts
Data to return. Corresponds to the
Results columns on Analyze > Reports.
type
string
ranked
ranked | geolocation
Report type; If type=geolocation, field
in the identityPath must equal ipv4_
conversation
sessionId
UUID
null
null | <GET: /deepsee_
reports/start_session>
identityPath
Default
Valid Inputs
302
Description
A value to identify the report.
Sort-by column. Value must be
included in metrics.
Sort order
Advanced filter attributes
Value on which to make the report
comparison.
Session ID. This value is obtained
after running /deepsee_
reports/start_session once
Security Analytics Reference Guide
REQ
restart
extraData
Security Analytics 8.1
Format
Default
Boolean
false
array
—
Valid Inputs
true | false
histogram | no_hearbeat |
no_data
Description
True — Run the report again
Extra data to return
n
histogram — Return
histogram data
n
no_heartbeat — Do not
update the report heartbeat
n
no_data — Do not return the
report data; only return totals,
report ID, and similar
information
Example 1: Report with Primary and Advanced Filters plus Histogram
Python Example 1
Run a UDP Initiator report with primary and advanced filters; also return histogram data
s.callAPI("GET","/deepsee_reports/report", {
'identityPath': {
'timespan': {
'start': '2019-11-03T13:45:01-07:00',
'end': '2019-11-03T13:45:04-07:00'
},
'query': [
'application_id=dns'
],
'field': 'udp_initiator'
},
'column': 'bytes',
'pageSize': 25,
'filters': {
'all': [
{
'key': 'bytes',
'comp': '>=',
'value': 1000
},
{
'any': [
{
'key': 'udp_initiator',
'comp': '>',
'value': 20000
},
{
'key': 'bad_checksums',
'comp': '!=',
'value': 0
}
]
}
]
},
'metrics': [
'sessions',
'bytes',
303
Security Analytics Reference Guide
Security Analytics 8.1
'packets'
],
'extraData': [
'histogram'
]
}
)
PHP Example1
Run a UDP Initiator report with primary and advanced filters; also return histogram data
callAPI('GET','/deepsee_reports/report',
array(
'identityPath' => array(
'timespan' => array(
'start' => '2019-11-03T13:45:01-07:00',
'end' => '2019-11-03T13:45:04-07:00'
),
'query' => array(
'application_id=dns'
),
'field' => 'udp_initiator'
),
'column' => 'bytes',
'pageSize' => 25,
'filters' => array(
'all' => array(
array(
'key' => 'bytes',
'comp' => '>=',
'value' => 1000
),
array(
'any' => array(
array(
'key' => 'udp_initiator',
'comp' => '>',
'value'=> 20000
),
array(
'key' => 'bad_checksums',
'comp' => '!=',
'value'=> 0
)
)
)
)
),
'metrics' => array(
'sessions',
'bytes',
'packets'
),
'extraData' => array(
'histogram'
)
)
);
Initial Output 1
'result': {'result': {'data': [],
'status': {'artifacts_count': <integer>,
'bad_csums_count': <integer>,
'bytes_count': <integer>,
'fidelity_percent': <integer>,
304
Security Analytics Reference Guide
Security Analytics 8.1
'fragments_count': <integer>,
'packets_count': <integer>,
'percentage': <integer>,
'report_daemon_id': <integer>,
'report_id': <integer>,
'sessions_count': <integer>,
'state': '<state>',
'timeDeleted': [True|False],
'time_place': <integer>,
'total_size': <integer>},
'total_count': <integer>}},
'resultCode': 'API_SUCCESS_CODE',
This API does not return data after the first API request. You must poll the
appliance in the meantime to incrementally retrieve the data. See "Using Polling
with the APIs" on page 415 for more information.
Completed Output 1
'result': {'result': {'beacon': None,
'data': [{'columns': ['<field>', <sessions>, <bytes>, <packets>],
'id': 'id_<hex>'},
{'columns': ['<field>', <sessions>, <bytes>, <packets>],
'id': 'id_<hex>'},
...
{'columns': ['<field>', <sessions>, <bytes>, <packets>],
'id': 'id_<hex>'},
{'columns': ['<field>', <sessions>, <bytes>, <packets>],
'id': 'id_<hex>'}],
'geolocation_totals': None,
'histogram': {'data': [{'columns': [0, <integer>, <integer>, <integer>],
'extra': {'end_time': <epoch>,
'start_time': <epoch>},
'text': '<MM/DD/YYYY hh:ii:ss>',
'time': <epoch>},
...
{'columns': [0, <integer>, <integer>, <integer>],
'extra': {'end_time': <epoch>,
'start_time': <epoch>},
'text': '<MM/DD/YYYY hh:ii:ss>',
'time': <epoch>}],
'status': {'artifacts_count': <integer>,
'bad_csums_count': <integer>,
'bytes_count': <integer>,
'fidelity_percent': <integer>,
'fragments_count': <integer>,
'packets_count': <integer>,
'percentage': <integer>,
'sessions_count': <integer>,
'state': '<state>',
'timeDeleted': [True|False],
'time_place': <integer>,
'total_size': <integer>},
'total_count': <integer>},
'max': <integer>,
'min': <integer>,
'report_totals': [0, <integer>, <integer>, <integer>],
'routes': None,
'status': {'artifacts_count': <integer>,
'bad_csums_count': <integer>>,
'bytes_count': <integer>,
'fidelity_percent': <integer>,
'fragments_count': <integer>,
305
Security Analytics Reference Guide
Security Analytics 8.1
'geolocation_max': <integer>,
'geolocation_min': <integer>,
'packets_count': <integer>,
'percentage': <integer>,
'report_daemon_id': <integer>,
'report_id': <integer>,
'sessions_count': <integer>,
'state': '<state>',
'time_place': <integer>},
'total': [0, <integer>, <integer>, <integer>],
'total_count': <integer>}},
'resultCode': 'API_SUCCESS_CODE',
Example 2: Report Comparison
Python Example 2
Run a File Name report comparison with primary filters only
s.callAPI("GET","/deepsee_reports/report", {
'identityPath': {
'timespan': {
'start': '2019-11-03T13:40:00-07:00',
'end': '2019-11-03T13:50:00-07:00'
},
'query': [
'country=china',
'mime_type~pdf'
],
'field': 'filename',
},
'pageSize': 15,
'column': 'bytes',
'direction': 'asc',
'compType': 'bytes',
'compDate': {
'start':'2019-11-02T14:40:00-07:00',
'end':'2019-11-02T14:50:00-07:00'
}
}
)
PHP Example 2
Run a File Name report comparison between two different hours with primary filters but not advanced filters
callAPI('GET','/deepsee_reports/report',
array(
'identityPath' => array(
'timespan' => array(
'start' => '2019-11-03T13:40:00-07:00',
'end' => '2019-11-03T13:50:00-07:00'
),
'query' => array(
'country=china',
'mime_type~pdf'
),
'field' => 'filename',
),
'pageSize' => 15,
'column' => 'bytes',
'direction' => 'asc',
'compType' => 'bytes',
'compDate' => array(
'start' => '2019-11-03T14:40:00-07:00',
306
Security Analytics Reference Guide
Security Analytics 8.1
'end' => '2019-11-03T14:50:00-07:00'
)
)
);
Initial Output 2
'result': {'data': [],
'result': {'compType': 'bytes',
'data': [],
'histogram': {'previous_data': []},
'status': {'artifacts_count': 0,
'bad_csums_count': 0,
'bytes_count': 0,
'fidelity_percent': 0,
'fragments_count': 0,
'packets_count': 0,
'percentage': 0,
'report_daemon_id': <integer>,
'report_id': <integer>,
'sessions_count': 0,
'state': 'new',
'timeDeleted': False,
'time_place': 0,
'total_size': 0},
'total': [1, 1, 1, 1],
'total_count': 0},
'status': {'artifacts_count': 0,
'bad_csums_count': 0,
'bytes_count': 0,
'fidelity_percent': 0,
'fragments_count': 0,
'packets_count': 0,
'percentage': 0,
'sessions_count': 0,
'state': 'new',
'timeDeleted': [True|False],
'time_place': 0,
'total_size': 0},
'total_count': 0},
'resultCode': 'API_SUCCESS_CODE',
This API does not return data after the first API request. You must poll the
appliance in the meantime to incrementally retrieve the data. See "Using Polling
with the APIs" on page 415 for more information.
Completed Output 2
'result': {'data': [],
'result': {'beacon': None,
'compType': 'bytes',
'data': [{'columns': ['<filename>',
0,
1,
1,
123412341234.12],
'id': 'id_<hex>'},
...
{'columns': ['<filename>',
0,
32,
32,
123412341234.12],
'id': 'id_<hex>'}],
307
Security Analytics Reference Guide
Security Analytics 8.1
'geolocation_totals': None,
'histogram': {'data': [{'columns': [0, 122],
'extra': {'end_time': <epoch>,
'start_time': <epoch>},
'text': 'MM/DD/YYYY hh:ii:ss',
'time': <epoch>},
...
{'columns': [0, 0],
'extra': {'end_time': <epoch>,
'start_time': <epoch>},
'text': 'MM/DD/YYYY hh:ii:ss',
'time': <epoch>}],
'previous_data': [{'columns': [0, 0],
'extra': {'end_time': <epoch>,
'start_time': <epoch>},
'text': 'MM/DD/YYYY '
'hh:ii:ss',
'time': <epoch>},
...
{'columns': [0, 0],
'extra': {'end_time': <epoch>,
'start_time': <epoch>},
'text': 'MM/DD/YYYY '
'hh:ii:ss',
'time': <epoch>}],
'status': {'artifacts_count': <integer>,
'bad_csums_count': <integer>,
'bytes_count': <integer>,
'fidelity_percent': <integer>,
'fragments_count': <integer>,
'packets_count': <integer>,
'percentage': <integer>,
'sessions_count': <integer>,
'state': '<state>',
'timeDeleted': [True|False],
'time_place': <integer>,
'total_size': <integer>},
'total_count': <integer>},
'max': <integer>,
'min': <integer>,
'report_totals': [<integer>, <integer>],
'routes': None,
'status': {'artifacts_count': <integer>,
'bad_csums_count': <integer>,
'bytes_count': <integer>,
'fidelity_percent': <integer>,
'fragments_count': <integer>,
'geolocation_max': <integer>,
'geolocation_min': <integer>,
'packets_count': <integer>,
'percentage': <integer>,
'report_daemon_id': <integer>,
'report_id': <integer>,
'sessions_count': <integer>,
'state': '<state>',
'time_place': <integer>},
'total': [<integer>, <integer>],
'total_count': <integer>},
'status': {'artifacts_count': <integer>,
'bad_csums_count': <integer>,
'bytes_count': <integer>,
'fidelity_percent': <integer>,
'fragments_count': <integer>,
'packets_count': <integer>,
'percentage': <integer>,
'sessions_count': <integer>,
308
Security Analytics Reference Guide
Security Analytics 8.1
'state': '<state>',
'timeDeleted': [True|False],
'time_place': <integer>,
'total_size': <integer>},
'total_count': <integer>},
'resultCode': 'API_SUCCESS_CODE',
Example 3: Geolocation Report
Python Example 3
Run a Geolocation report
s.callAPI("GET","/deepsee_reports/report", {
'identityPath': {
'timespan': {
'start': '2019-11-03T13:40:00-07:00',
'end': '2019-11-03T13:50:00-07:00'
},
'field': 'ipv4_conversation',
},
'type': 'geolocation'
}
)
PHP Example 3
Run a Geolocation report.
callAPI('GET','/deepsee_reports/report',
array(
'identityPath' => array(
'timespan' => array(
'start' => '2019-11-03T13:40:00-07:00',
'end' => '2019-11-03T13:50:00-07:00'
),
'field' => 'filename',
),
'type' => 'geolocation'
)
);
Initial Output 3
'result': {'result': {'beacon': None,
'data': [],
'geolocation_totals': [],
'histogram': None,
'max': <float>,
'min': <float>,
'report_totals': [],
'routes': [],
'status': {'report1': {'artifacts_count': 0,
'bad_csums_count': 0,
'bytes_count': 0,
'fidelity_percent': 0,
'fragments_count': 0,
'packets_count': 0,
'percentage': 0,
'report_daemon_id': <integer>,
'report_id': <integer>,
'sessions_count': 0,
'state': '<state>',
309
Security Analytics Reference Guide
Security Analytics 8.1
'timeDeleted': [True|False],
'time_place': 0,
'total_size': 0},
'report2': {'artifacts_count': 0,
'bad_csums_count': 0,
'bytes_count': 0,
'fidelity_percent': 0,
'fragments_count': 0,
'packets_count': 0,
'percentage': 0,
'report_daemon_id': <integer>,
'report_id': <integer>,
'sessions_count': 0,
'state': '<state>',
'timeDeleted': [True|False],
'time_place': 0,
'total_size': 0}},
'total': [],
'total_count': 0}},
'resultCode': 'API_SUCCESS_CODE',
This API does not return data after the first API request. You must poll the
appliance in the meantime to incrementally retrieve the data. See "Using Polling
with the APIs" on page 415 for more information.
Completed Output 3
'result': {'result': {'beacon': None,
'data': [{'columns': ['<location>', <number_of_addresses>, <bytes>],
'id': 'ipv4_conversation_32',
'ids': ['ipv4_conversation_32'],
'latitude': <signed_floating>},
'longitude': <signed_floating>}},
...
{'columns': ['<location>', <number_of_addresses>, <bytes>],
'id': 'ipv4_conversation_36',
'ids': ['ipv4_conversation_36'],
'latitude': <signed_floating>},
'longitude': <signed_floating>}}],
'geolocation_totals': [0, <integer>, <integer>],
'histogram': None,
'max': <integer>,
'min': <integer>,
'report_totals': [<integer>, <integer>],
'routes': [{'latitude1': <signed_floating>,
'latitude2': <signed_floating>,
'longitude1': <signed_floating>,
'longitude2': <signed_floating>},
...
{'latitude1': <signed_floating>,
'latitude2': <signed_floating>,
'longitude1': <signed_floating>,
'longitude2': <signed_floating>}],
'status': {'report1': {'artifacts_count': 0,
'bad_csums_count': 0,
'bytes_count': 0,
'fidelity_percent': 100,
'fragments_count': 0,
'geolocation_max': 0,
'geolocation_min': 0,
310
Security Analytics Reference Guide
Security Analytics 8.1
'packets_count': 0,
'percentage': 100,
'report_daemon_id': <integer>,
'report_id': <integer>,
'sessions_count': 0,
'state': 'complete',
'time_place': 0},
'report2': {'artifacts_count': 0,
'bad_csums_count': 0,
'bytes_count': <integer>,
'fidelity_percent': 100,
'fragments_count': 0,
'geolocation_max': 0,
'geolocation_min': 0,
'packets_count': <integer>,
'percentage': 100,
'report_daemon_id': <integer>,
'report_id': <integer>,
'sessions_count': <integer>,
'state': 'complete',
'time_place': 0}},
'total': [0, <integer>, <integer>],
'total_count': <integer>}},
'resultCode': 'API_SUCCESS_CODE',
Get job queue — NEW
API Path
/job_queue/job_queue
Description
Retrieve a list of jobs in the job queue.
GUI Location
Job Queue page
Parameters
REQ
Format
Default
Valid Inputs
Description
page
integer
1
1–<n>
Page to
retrieve;
first page is
1
limit
integer
25
1–100
Number of
items per
page
sort
string
create_date
create_date | start_date | finish_
date
direction
string
desc
asc | desc
Sort order
filters
array
—
<advanced job queue filter>
Advanced
filter
attributes
311
Sort-by
column
Security Analytics Reference Guide
Security Analytics 8.1
Python Example
s.callAPI('GET', '/job_queue/job_queue', {
'page': 1,
'limit': 25,
'sort': 'start_date',
'filters': {
'all': [
{
'key': 'id',
'comp': '>=',
'value': 16
}
]
}
}
)
PHP Example
callAPI('GET', '/job_queue/job_queue',
array(
'page' => 1,
'limit' => 25,
'sort' => 'start_date',
'filters' => array(
'all' => array(
'key': 'id',
'comp': '>=',
'value': 16
)
)
)
);
Output
'paging': {'JobQueue': {'count': <integer>,
'current': <integer>,
'limit': <integer>,
'nextPage': [True | False],
'options': {'order': {'JobQueue.<field>': '[asc | desc]'}},
'order': {'JobQueue.<field>': '[asc | desc]'},
'page': <integer>,
'pageCount': <integer>,
'paramType': 'named',
'prevPage': [True | False],
'queryScope': None}},
'result': {'pageCount': 1,
'rows': [{'can_download': [True | False],
'create_date': 'YYYY-MM-DD hh:ii:ss.999999-06',
'data': '{"appliances":"","options":{"ac":"Reports","sc":{"Reports":{"rI":"<report_
name>","sv":58,
"s":1000,"sc":"sessions","sd":"d"}},"pb":[],"ca":{"start":<epoch>,"end":<epoch>}},
"username":"<username>","file":"\\/tmp\\/<filename>.pdf"}',
'elapsed_time': 'hh:ii:ss',
'finish_date': 'YYYY-MM-DD hh:ii:ss.999999-06',
'id': <integer>,
'message': '',
'queued': [True | False],
'start_date': 'YYYY-MM-DD hh:ii:ss.999999-06',
312
Security Analytics Reference Guide
Security Analytics 8.1
'status': <integer>,
'type': <integer>,
'username': '<username>'},
{'can_download': [True | False],
'create_date': 'YYYY-MM-DD hh:ii:ss.999999-06',
'data': '{"appliances":"","timespan":{"start":"<epoch>","end":"<epoch>"},"options":
{"polling":false,"threatSummary":false,"field":"threat_summary","timespan":
{"start":"<epoch>","end":"<epoch>"},
"delivery":{"email":{"selected":"0"},"download":{"selected":"1"}},"reportlets":[],"
_Token":{"key":"<key>","unlockedFields":[]}},"username":"admin","user_
id":1,"outputFile":"\\/home\\/apache\\/tmp\\/
risk_and_visibility_report_<hex>.pdf"}',
'elapsed_time': 'hh:ii:ss',
'finish_date': 'YYYY-MM-DD hh:ii:ss.999999-06',
'id': <integer>,
'message': '',
'queued': [True | False],
'start_date': 'YYYY-MM-DD hh:ii:ss.999999-06',
'status': <integer>,
'type': <integer>,
'username': '<username>'},
]},
'resultCode': 'API_SUCCESS_CODE',
Download a file from the job queue — NEW
API Path
/job_queue/download
Description
Download a file in the job queue.
GUI Location
Job Queue page
Parameters
id
REQ
Format
X
integer
Default
—
Python Example
s.callAPI('GET', '/job_queue/download', {
"id": 5
})
PHP Example
s.callAPI('GET', '/job_queue/download',
array(
313
Valid Inputs
Description
<GET: /job_queue/job_queue>
ID of a job in
the queue
Security Analytics Reference Guide
Security Analytics 8.1
'id' => 5
)
);
Output
Get job queue count — NEW
API Path
/job_queue/count
Description
Get the number of non-downloaded jobs in the job queue.
GUI Location
Job Queue icon
Parameters
None
Python Example
s.callAPI('GET', '/job_queue/count')
PHP Example
s.callAPI('GET', '/job_queue/count');
Output
'result': <integer>,
'resultCode': 'API_SUCCESS_CODE'
Get filter options for the job queue — NEW
API Path
/job_queue/filter_options
Description
Get the advanced filter attributes for the Job Queue page.
GUI Location
Job Queue icon
Parameters
None
314
Security Analytics Reference Guide
Security Analytics 8.1
Python Example
s.callAPI('GET', '/job_queue/filter_options')
PHP Example
s.callAPI('GET', '/job_queue/filter_options');
Output
{'errors': [],
'messages': [],
'paging': [],
'result': {'status': ['Error',
'Queued',
'Running',
'Downloadable',
'Finished'],
'type': ['Error',
'Download PDF',
'Generate PDF',
'Generate CSV',
'Import Favorite',
'Download PCAP',
'Generate Threat Summary',
'Email Threat Summary Report',
'Save Result']},
'resultCode': 'API_SUCCESS_CODE',
'validationErrors': {'JobQueue': [], 'Meta': [], 'Util': [], 'res': []}}
Start session for combining reports
API Path
/deepsee_reports/start_session
Description
Starts a session for combining reports together to run simultaneously.
GUI Location
Menu
> Analyze > Summary
Example
n
Run GET: /deepsee_reports/start_session to get a sessionId.
n
Run GET:/deepsee_reports/report N times, using the same sessionId each time and the same identity
path except for field. These reports are queued.
n
Run GET:/ deepsee_reports/finalize_session to run all of the queued reports as if they were one report.
Output
'result': '<UUID>',
'resultCode': 'API_SUCCESS_CODE',
315
Security Analytics Reference Guide
Security Analytics 8.1
Finish session for combining reports
API Path
/deepsee_reports/finalize_session
Description
Launches all reports that are queued for the session.
GUI Location
Menu
> Analyze > Summary
Parameters
sessionId
REQ
Format
X
UUID
Default
Valid Inputs
—
<GET: /deepsee_reports/start_
session>
Description
Session to
launch
Output
'resultCode': 'API_SUCCESS_CODE',
Download CSV report
API Path
/deepsee_reports/csv
Description
Download an existing report in CSV format
GUI Location
Menu
> Analyze > Summary > Reports > Actions > Download CSV
Parameters
identityPath
direction
REQ
Format
X
string |
integer
string
Default
—
DESC
Valid Inputs
<GET: /deepsee_
reports/report>
Description
Run /deepsee_reports/report to get
the report ID; include no_data in
the extraData array for a faster
return time
<report ID>
Use the report ID for identityPath
ASC | DESC
Sort order
316
Security Analytics Reference Guide
REQ
column
Format
Security Analytics 8.1
Default
string
—
Valid Inputs
bytes | packets | sessions |
fragments | bad_csums |
artifacts | risk | item
Description
Sort-by column
PHP Example
callAPI('GET','/deepsee_reports/csv',
array(
'identityPath' => 3447,
'direction' => 'DESC',
'column' => 'bytes'
), '<filename>.csv'
);
Python Example
s.callAPI("GET","/deepsee_reports/csv", {
'identityPath': 3447,
'direction': 'DESC',
'column': 'bytes'
}, '<filename>.csv'
)
Output
<filename>.csv
Download PDF report
API Path
/deepsee_reports/pdf/<reportId>
Description
Download a report in PDF format.
GUI Location
Menu
> Analyze > Summary > Reports > Actions > Download PDF
Parameters
identityPath
REQ
Format
X
string |
integer
Default
—
Valid Inputs
Description
<GET: /deepsee_
reports/report
>|<GET: /report_daemons>
Run either API to get the report ID
<report ID>
Use the report ID for identityPath
Sort order
direction
string
—
ASC | DESC
column
string
—
bytes | sessions | packets
317
Sort-by column
Security Analytics Reference Guide
Security Analytics 8.1
PHP Example
callAPI('GET','/deepsee_reports/pdf/3447',
array(
'direction' => 'DESC',
'column' => 'bytes'
),
'<filename>.pdf'
)
Python Example
s.callAPI("GET","/deepsee_reports/pdf/3447", {
'direction': 'DESC',
'column': 'bytes'
}, '<filename>.pdf'
)
Output
<filename>.pdf
Download a raw TSV file
API Path
/pcap/download/raw
Description
Download a raw.tsv file
GUI Location
Menu
> Analyze > [Summary | Reports | Extractions | Geolocation] > Actions > Download Raw TSV
Parameters
path
REQ
Format
X
array
—
<Indexing DB path>
Indexing database path
array
—
<RAW.TSV fields>
Omit to specify all fields
fields
Default
Valid Inputs
Description
Python Example
s.callAPI("GET","/pcap/download/raw", {
'path':'/timespan/2019-11-23T00:00:00_2019-11-23T00:23:59/application_
id/runescape/country/china/ip_responder/203.0.113.0/24',
'fields': [
'aggregate_social_persona_hooks,'
'application_id1',
'application_id2',
'first_slot_id',
'packet_count',
'start_time',
'stop_time'
]
}, '<filename>.tsv'
)
PHP Example
callAPI('GET','/pcap/download/raw',
318
Security Analytics Reference Guide
Security Analytics 8.1
array(
'path' => '/timespan/2019-11-23T00:00:00-07:00_2019-11-23T00:23:5907:00/application_id/runescape/country/china/ip_responder/203.0.113.0/24',
'fields' => array(
'aggregate_social_persona_hooks,'
'application_id1',
'application_id2',
'first_slot_id',
'packet_count',
'start_time',
'stop_time'
)
), '<filename>.tsv'
);
Output
<filename>.tsv
Get report status summary
API Path
/report_daemons/summary_data
Description
Retrieve the report status summary
GUI Location
Menu
> Analyze > Report Status > Summary
Parameters
REQ
filters
Format
Default
Valid Inputs
Description
JSON
—
<advanced report status
filter>
page
integer
1
1–<n>
Number of the page to retrieve; first
page is 1
limit
integer
25
1–100
Number of items per page
sort
string
count
count
Sort-by column
string
DESC
ASC | DESC
array
—
direction
groupBy
X
Advanced filter attributes
Sort order
percentage | field | state | Tables on the Report Status Summary
username | appliance
page
Python Example
s.callAPI("GET","/report_daemons/summary_data", {
'page': 1,
'limit': 15,
'direction': 'DESC',
'filters': json.dumps({
{
319
Security Analytics Reference Guide
Security Analytics 8.1
'all': [
{
'key': 'state',
'comp': '=',
'value': 'complete'
},
{
'key': 'username',
'comp': '=',
'value': 'admin'
}
]
}
}),
'groupBy': {
['field']
}
}
)
PHP Example
callAPI('GET','/report_daemons/summary_data',
array(
'page' => 1,
'limit' => 15,
'direction' => 'DESC',
'filters' => json_encode(
array(
'all' => array(
array(
'key' => 'state',
'comp' => '=',
'value' => 'complete'
)
array(
'key' => 'username',
'comp' => '=',
'value' => 'admin'
)
)
)
),
'groupBy' => array(
'field'
)
)
);
Output
'paging': {'ReportDaemon': {'count': <integer>,
'current': <integer>,
'limit': <integer>,
'nextPage': [True|False],
'options': {'order': {'count': 'desc'}},
'order': {'count': 'desc'},
'page': <integer>,
'pageCount': <integer>,
'paramType': 'named',
'prevPage': [True|False]}},
'result': {'pageCount': <integer>,
'rows': [{'count': <integer>, 'field': '<report_attribute>'},
{'count': <integer>, 'field': '<report_attribute>'},
...
{'count': <integer>, 'field': '<report_attribute>'},
{'count': <integer>, 'field': '<report_attribute>'}]},
'resultCode': 'API_SUCCESS_CODE',
320
Security Analytics Reference Guide
Security Analytics 8.1
Get report status list
API Path
/report_daemons
Description
Retrieve the report status list
GUI Location
Menu
> Analyze > Report Status > List
Parameters
REQ
filters
Format
Default
Valid Inputs
Description
JSON
—
<advanced report status
filter>
page
integer
1
1–<n>
Page to retrieve; first page is 1
limit
integer
25
1–100
Number of items per page
string
DESC
ASC | DESC
string
id
id | field | start_time | end_
time | age | run_time | name |
disk_usage | timespan_start |
timespan_end | percentage
direction
sort
Python Example
s.callAPI("GET","/report_daemons", {
'page': 1,
'limit': 15,
'sort': 'percentage',
'direction': 'ASC',
'filters': json.dumps(
{
'all': [
{
'key': 'state',
'comp': '=',
'value': 'complete'
},
{
'key': 'username',
'comp': '=',
'value': 'admin'
}
]
}
)
}
)
321
Advanced filter attributes
Sort order
Sort-by column
Security Analytics Reference Guide
Security Analytics 8.1
PHP Example
callAPI('GET','/report_daemons',
array(
'page' => 1,
'limit' => 15,
'sort' => 'percentage',
'direction' => 'ASC',
'filters' => json_encode(
array(
'all' => array(
array(
'key' => 'state',
'comp' => '=',
'value' => 'complete'
)
array(
'key' => 'username',
'comp' => '=',
'value' => 'admin'
)
)
)
)
)
);
Output
'paging': {'ReportDaemon': {'count': <integer>,
'current': <integer>,
'limit': <integer>,
'nextPage': [True|False],
'options': [],
'order': '"ReportDaemon"."id" [ASC|DESC]',
'page': <integer>,
'pageCount': <integer>,
'paramType': 'named',
'prevPage': [True|False]}},
'result': {'pageCount': <integer>,
'rows': [{'disk_usage': '<size>',
'end_time': '<YYYY-MM-DD><hh:ii:ss>.003329-06',
'field': '<field>',
'id': <integer>,
'name': '',
'path_bar': '["<report_attribute>"]',
'run_time': '<hh:ii:ss>',
'saved_count': 0,
'start_time': '<YYYY-MM-DD><hh:ii:ss>.387784-06',
'state': 'complete',
'timespan_end': '<YYYY-MM-DD><hh:ii:ss>-06',
'timespan_start': '<YYYY-MM-DD><hh:ii:ss>-06',
'username': '<username>'},
...
'resultCode': 'API_SUCCESS_CODE',
Get scheduled reports
API Path
/deepsee_reports/schedules
Description
Retrieve all scheduled reports
322
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
Menu
> Analyze > Scheduled Reports
Parameters
REQ
Format Default
Valid Inputs
Description
page
integer
1
1–<n>
Number of the page to retrieve;
first page is 1
limit
integer
25
1–100
Number of items per page
string
asc
asc | desc
Sort order
integer
0
0 | 1 | 2
n
0 — Both Shared and Not
Shared
n
1 — Not Shared
n
2 — Shared
direction
shared
sort
string
name
id | name | created_by_userid | Sort-by column
frequency | report_types |
appliances | time_span | time_
of_execution | recipients |
output_format | is_active |
shared | created | modified |
last_execution | status | end_
time_of_execution
Python Example
s.callAPI("GET","/deepsee_reports/schedules", {
'page': 3,
'limit': 50,
'direction': 'desc',
'shared': 2,
'sort': 'last_execution'
}
)
PHP Example
callAPI('GET','/deepsee_reports/schedules',
array(
'page' => 3,
'limit' => 50,
'direction' => 'desc',
'shared' => 2,
'sort' => 'last_execution'
)
);
Output
'paging': {'ReportSchedule': {'count': <integer>,
'current': <integer>,
'limit': <integer>,
'nextPage': [True|False],
'options': {'conditions': [],
'order': {'ReportSchedule.name': '[asc|desc]'}},
'order': {'ReportSchedule.name': '[asc|desc]'},
323
Security Analytics Reference Guide
Security Analytics 8.1
'page': <integer>,
'pageCount': <integer>,
'paramType': 'named',
'prevPage': [True|False]}},
'result': {'pageCount': <integer>,
'results': [{'ReportSchedule': {'ReportScheduleEvent': [{'event': '<frequency>',
'id': <integer>,
'nice_event': '<frequency>',
'report_schedule_id': <integer>}],
'appliances': [None|<appliance_ids>],
'created': '<YYYY-MM-DD><hh:ii:ss>-06',
'created_by_userid': <integer>,
'end_time_of_execution': '<hh:ii:ss>',
'frequency': '<frequency>',
'gauge_path_json': '["<primary filter>"]',
'id': <integer>,
'is_active': [True|False],
'last_execution': None,
'massaged_time_span': '<time_span>',
'modified': '<YYYY-MM-DD>'
'<hh:ii:mm>.310877-06',
'name': '<report_name>',
'output_format': '[CSV|PDF]',
'recipients': '<email_address>',
'repeat': '<frequency>',
'repeats_every': '<frequency>',
'report_types': '<primary filter attribute>',
'shared': [True|False],
'status': None,
'time_of_execution': '<hh:ii:mm>',
'time_span': '-<time>'}}]},
'resultCode': 'API_SUCCESS_CODE',
Get path
API Path
/deepsee_reports/gauge_path
Description
Retrieve an Indexing DB path for the specified query
GUI Location
Menu
> Analyze > Summary pages > More Information dialog
Parameters
REQ
Format
Default
Valid Inputs
query
X
JSON
—
<primary filter array>
timespan
X
JSON
—
<timespan array>
Python Example
s.callAPI("GET","deepsee_reports/gauge_path", {
'query': json.dumps([
'port>10000',
324
Description
Primary filter attribute/values
Start and end times
Security Analytics Reference Guide
Security Analytics 8.1
'application_id=dns,udp'
]),
'timespan': json.dumps({
'start': '2019-11-03T10:00:00-07:00',
'end': '2019-11-03T10:15:00-07:00'
})
}
)
PHP Example
callAPI('GET','deepsee_reports/gauge_path',
array(
'query' => json_encode(
array(
'port>10000',
'application_id=dns,udp'
)
),
'timespan' => json_encode(
array(
'start' => '2019-11-03T10:00:00-07:00',
'end' => '2019-11-03T10:15:00-07:00'
)
)
)
);
Output
'result': '/timespan/2019-11-03T10:00:00-07:00_2019-11-03T10:15:00-07:00/port/_gt_
10000/application_id/udp',
'resultCode': 'API_SUCCESS_CODE',
Get estimated PCAP size
API Path
/deepsee_reports/estimate_pcapsize
Description
Retrieve the estimated size of the report PCAP within a specified timespan
GUI Location
n
Menu
dialog
> Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > More Information
n
Menu
> Analyze > Summary > [Summary | Reports | Extractions | Geolocation] > Status bar > Search
Size field
Parameters
REQ
Format
Default
Valid Inputs
startTime
X
integer
—
<unix epoch>
Start of timespan
stopTime
X
integer
—
<unix epoch>
End of timespan
325
Description
Security Analytics Reference Guide
Security Analytics 8.1
Python Example
s.callAPI("GET","deepsee_reports/estimate_pcapsize", {
'startTime': 1677980000,
'stopTime': 1678039074
}
)
PHP Example
callAPI('GET','deepsee_reports/estimate_pcapsize',
array(
'startTime' => 1677980000,
'stopTime' => 1678039074
)
)
);
Output
'result': '<bytes>',
'resultCode': 'API_SUCCESS_CODE',
Download Google Earth KMZ file
API Path
/deepsee_reports/kmz
Description
Download a Google Earth KMZ file of the current report(s)
GUI Location
Menu
> Analyze > Summary pages > Actions > Google Earth
Parameters
REQ
Format
Default
Valid Inputs
query
X
JSON
—
<primary filter array>
timespan
X
JSON
—
<timespan array>
Python Example
s.callAPI("GET","/deepsee_reports/kmz", {
'query': json.dumps([
'port>50000',
'application_id=dns,http'
]),
'timespan': json.dumps({
'start': '2019-11-03T10:00:00-07:00',
'end': '2019-11-03T10:15:00-07:00'
})
}
)
PHP Example
callAPI('GET','/deepsee_reports/kmz',
array(
'query' => json_encode(
326
Description
Primary filter attributes
Timespan
Security Analytics Reference Guide
Security Analytics 8.1
array(
'port>50000',
'application_id=dns,http'
),
),
'timespan' => json_encode(
array(
'start' => '2019-11-03T10:00:00-07:00',
'end' => '2019-11-03T10:15:00-07:00'
)
)
)
);
Output
<filename>.kmz
Get the chart settings on the Reports page
API Path
/deepsee/ranked_chart_setting
Description
Retrieve the settings for the chart on the Reports page
GUI Location
Menu
> Analyze > Summary > Reports > Report Summary > Settings
Parameters
None
Python Example
s.callAPI("GET","/deepsee/ranked_chart_setting")
PHP Example
callAPI('GET','/deepsee/ranked_chart_setting');
Output
'result': {'axisScale': '[linear|logarithmic]', 'numResults': <integer>, 'type': '
[pie|bar|column|scatter]'},
'resultCode': 'API_SUCCESS_CODE',
Delete jobs from the job queue — NEW
API Path
/job_queue/delete
Description
Delete one or more jobs from the job queue.
327
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
Job Queue page
Parameters
ids
REQ
Format
X
integer
Default
—
Valid Inputs
Description
<GET: /job_queue/job_queue>
IDs of jobs
in the queue
Python Example
s.callAPI('POST', '/job_queue/delete', {
"id": 5,6
})
PHP Example
s.callAPI('POST', '/job_queue/delete',
array(
'id' => 5,6
)
);
Generate a Risk and Visibility report
API Path
/deepsee_reports/threat_summary
Description
Generate a Risk and Visibility report. The finished report is located in /home/apache/tmp.
GUI Location
[Account Name]
> Risk and Visibility Report
Parameters
REQ
Format
Default
Valid Inputs
reportData
X
array
—
Array that contains all other fields
delivery
X
array
—
Delivery methods: download from the web UI
and/or email to specified recipients. At least
one delivery method must be specified.
download
array
—
Whether the report is to be downloaded from
the web UI.
selected
integer
1
0 | 1
328
Description
Whether the option is selected:
n
0 — Not selected
n
1 — Selected
Security Analytics Reference Guide
REQ
email
recipient_
list
reportlets
X
timespan
Format
Security Analytics 8.1
Default
Valid Inputs
array
—
array
—
<user@domain.tld>
Boolean
false
[] | false
array
—
<timespan array>
Description
Whether the report is to be emailed to
specified recipients.
List of email addresses to receive the report
Can be false or an empty array
Timespan of the data to include in the report
Python Example
s.callAPI("POST","/deepsee_reports/threat_summary", {
'reportData': {
'delivery': {
'download': {
'selected': 1
},
'email': {
'selected': 1,
'recipient_list': [
'joe@nowhere.com'
]
}
},
'reportlets': False,
'timespan': {
'start': '2019-09-01T10:00:00-07:00',
'end': '2019-09-02T10:00:00-07:00'
}
}
}
)
PHP Example
callAPI('POST','/deepsee_reports/threat_summary',
array(
'reportData' => array(
'delivery' => array(
'download' => array(
'selected' => 1
),
'email' => array(
'selected' => 1,
'recipient_list' => array(
'joe@nowhere.com'
)
)
),
'reportlets' => array(),
'timespan' => array(
'start' => '2019-09-01T10:00:00-07:00',
'end' => '2019-09-02T10:00:00-07:00'
)
)
)
);
Output
'result': 'API_SUCCESS_CODE',
'resultCode': 'API_SUCCESS_CODE',
329
Security Analytics Reference Guide
Security Analytics 8.1
Stop a report
API Path
/report_daemons/stop
Description
Stop one or more reports in the active state
GUI Location
Menu
> Analyze > Report Status > List
Output
IDs of successfully stopped reports
Parameters
REQ
identityPaths
X
Format Default
integer
—
Valid Inputs
<GET: /deepsee_reports/report> |
<GET: /report_daemons>
Python Example
s.callAPI("POST","/report_daemons/stop", {
'identityPaths': [
375,
383
]
}
)
PHP Example
callAPI('POST','/report_daemons/stop',
array(
'identityPaths' => array(
375,
383
)
)
);
Delete a report
API Path
/report_daemons/delete
Description
Delete a report in the stopped, complete, or error state
330
Description
Run either API to get
the report ID
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
Menu
> Analyze > Report Status > List > [selected reports] > Delete button
Output
IDs of successfully deleted reports
Parameters
identityPaths
REQ
Format
X
string |
integer
Default
—
Valid Inputs
<GET: /deepsee_reports/report>|
<GET: /report_daemons>
<report ID>
Python Example
s.callAPI("POST","/report_daemons/delete", {
'identityPaths': [
554,
557,
559
]
}
)
PHP Example
callAPI('POST','/report_daemons/delete',
array(
'identityPaths' => array(
554,
557,
559
)
)
);
Save a report
API Path
/deepsee_reports/save
Description
Save a report to the Report Status page
GUI Location
n
Menu
> Analyze > Summary > Actions > Save
n
Menu
> Analyze > Summary > Reports > Actions > Save
331
Description
Run either API to get the
report ID
Use the report ID for
identityPath
Security Analytics Reference Guide
n
Menu
Security Analytics 8.1
> Analyze > Summary > Geolocation > Actions > Save
Output
ApiResultCode
Parameters
identityPath
name
REQ
Format
X
string |
integer
X
string
Default
—
Valid Inputs
<GET: /deepsee_
reports/report> |
<GET: /report_daemons>
Run either API to get the report ID
<report ID>
Use the report ID for identityPath
—
<UTF-8 characters>
Python Example
s.callAPI("POST","/deepsee_reports/save", {
'identityPaths': [
384
],
'name': 'Email_Subject-20191103'
}
)
PHP Example
callAPI('POST','/deepsee_reports/save',
array(
'identityPaths' => array(
384
),
'name' => 'Email_Subject-20191103'
)
);
Stop a report
API Path
/deepsee_reports/stop
Description
Stop a report that is currently running
GUI Location
Menu
Description
> Analyze > Summary > (any) Stop button
Output
ApiResultCode
332
Name for the report
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
Format
X
string |
integer
identityPath
Default
Valid Inputs
—
Description
<GET: /deepsee_
reports/report> |
<GET: /report_daemons>
<report ID>
Run either API to get the
report ID
Use the report ID for
identityPath
Python Example
s.callAPI('POST','/deepsee_reports/stop', {
'identityPaths': [
384
]
}
)
PHP Example
callAPI('POST','/deepsee_reports/stop',
array(
'identityPaths' => array(
384
)
)
);
Edit the chart on the Reports page
API Path
/deepsee/ranked_chart_setting
Description
Edit the settings for the Selected Totals chart on the Reports page.
GUI Location
Menu
> Analyze > Summary > Reports > Report Summary > Settings
Output
array
Parameters
REQ
Format
Default
Valid Inputs
type
X
string
—
pie | bar | column |
scatter
axisScale
X
string
—
linear | logarithmic
333
Description
Chart type
Scale for the y-axis; logarithmic is not
valid for type=pie
Security Analytics Reference Guide
REQ
Format
X
integer
numResults
Security Analytics 8.1
Default
Valid Inputs
—
1–40
Description
Number of results to display
Python Example
s.callAPI("POST","/deepsee/ranked_chart_setting", {
'type': 'pie',
'axisScale': 'linear',
'numResults': 25
}
)
PHP Example
callAPI('POST','/deepsee/ranked_chart_setting',
array(
'type' => 'pie',
'axisScale' => 'linear',
'numResults' => 25
)
);
Create or edit a scheduled report
API Path
/deepsee_reports/schedule_create
Description
Create or edit a scheduled report; completing a new schedule runs the report once
GUI Location
Menu
> Analyze > Scheduled Reports
Output
array
Parameters
REQ Format Default
id
name
X
X
string
string
—
—
Valid Inputs
null | <GET: /deepsee_
reports/schedules>
<UTF-8 characters>
334
Description
n
New — Use null
n
Edit — Scheduled
report ID required
n
New — Name for the
report required
n
Edit — New name for
the report
Security Analytics Reference Guide
Security Analytics 8.1
REQ Format Default
shared
frequency
X
X
events
integer
Valid Inputs
—
0 | 1
Description
n
0 — Non-shared report
n
1 — Shared report
string
—
daily | weekly | monthly |
hour | minute | once | custom
array
—
<scheduled events syntax>
When to run the report,
according to the value of
frequency
Time to begin running the
schedule
How often to run the report
timeOfExecution
X
string
—
<hh:ii:ss>
endTimeOfExecution
X
string
—
<hh:ii:ss> | 23:59:59
Time to stop running the
schedule; if frequency = hour
or minute specify when to stop,
else this value is 23:59:59
gaugePathJson
X
JSON
—
<primary filter array>
Primary filter attribute/value
pairs; to specify an indicator,
run GET: /favorites
timeSpan
X
string
—
email
—
<user>@<domain>.<tld>
recipients
-<integer> [minutes | hours | Start time for the report's data,
days | weeks | months |
expressed as
years]
<hyphen><integer> <unit_of_
|<YYYY-MM-DD>T<hh:ii:ss>_
time>; end time is
<YYYY-MM-DD>T<hh:ii:ss>
timeOfExecution If
frequency=once, specify both
start and end times.
Email accounts to receive
reports, semicolon-delimited
outputFormat
X
string
—
PDF | CSV
reportType
X
string
—
<available reports>
createdByUserID
X
integer
—
<GET: /users/setting>
ID of user who created the
report
integer
—
<GET: /cmc_
settings/appliances>
CMC only. Sensors on which to
save this scheduled report
appliances
Output format for report
Report type; use the report's
corresponding primary filter
attribute
Python Example
Schedule a Country Responder report to run once every 3 hours beginning at midnight. The report is filtered by
the Countries - OFAC indicator and the report timespan is the 15 minutes prior to report execution. A PDF
version of the report is sent to two email addresses.
s.callAPI("POST","/deepsee_reports/schedule_create", {
'id': None,
'name': '3-Hour High-Risk Countries',
335
Security Analytics Reference Guide
Security Analytics 8.1
'shared: 1,
'frequency': 'hour',
'events': {
'03'
},
'timeOfExecution': '00:00:00',
'endTimeOfExecution': '23:59:59',
'gaugePathJson': {
{
'favorite=581cc1a3-b884-4e39-a2f2-67b31e1d64a3'
}
},
'timeSpan': '-15 minutes',
'recipients': 'admin@domain.com;security@domaincom',
'outputFormat': 'PDF',
'reportType': 'country_responder',
'createdByUserID': 1
}
)
PHP Example
Schedule a Country Responder report to run once every 3 hours beginning at midnight. The report is filtered by
the Countries - OFAC indicator and the report timespan is the 15 minutes prior to report execution. A PDF
version of the report is sent to two email addresses.
callAPI('POST','/deepsee_reports/schedule_create',
array(
'id' => null,
'name' => '3-Hour High-Risk Countries',
'shared' => 1,
'frequency' => 'hour',
'events' => array(
'03'
),
'timeOfExecution' => '00:00:00',
'endTimeOfExecution' => '23:59:59',
'gaugePathJson' => json_encode(
array(
'favorite=581cc1a3-b884-4e39-a2f2-67b31e1d64a3'
)
),
'timeSpan' => '-15 minutes',
'recipients' => 'admin@domain.com;security@domaincom',
'outputFormat' => 'PDF',
'reportType' => 'country_responder',
'createdByUserID' => 1
)
);
Delete a scheduled report
API Path
/deepsee_reports/schedule_delete/<id>
Description
Delete a specified scheduled report
336
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
Menu
> Analyze > Scheduled Reports > [schedule entry]
Output
array
Parameters
REQ
Format
X
integer
id
Default
—
Valid Inputs
<GET: /deepsee_
reports/scheduled>
Description
ID of scheduled report to be deleted
Python Example
s.callAPI("POST","/deepsee_reports/schedule_delete/<scheduled_report_id>")
PHP Example
callAPI('POST','/deepsee_reports/schedule_delete/<scheduled_report_id>');
Activate or deactivate a scheduled report
API Path
/deepsee_reports/schedule_toggle/<id>/<action>
Description
Toggle a scheduled report between activate and inactive
GUI Location
Menu
> Analyze > Scheduled Reports > [schedule entry]
Output
ApiResultCode
Parameters
REQ
Format
Default
Valid Inputs
id
X
integer
—
<GET: /deepsee_
reports/schedules>
action
X
string
—
activate | deactivate
Python Example
s.callAPI("POST","/deepsee_reports/schedule_toggle/25/deactivate")
PHP Example
callAPI('POST','/deepsee_reports/schedule_toggle/25/deactivate');
337
Description
ID of the scheduled report
Action to perform
Security Analytics Reference Guide
Security Analytics 8.1
Rules APIs
"Action" is the internal name for "rule."
Get rules
API Path
/actions
Description
Retrieve a list of rules
GUI Location
Menu
> Analyze > Rules
Output
array
Parameters
REQ
Format
Default
Valid Inputs
page
integer
1
1-<n>
Page to get. First page is 1
limit
integer
25
1–100
Number of rows per page
direction
string
ASC
ASC | DESC
sort
string
name
name
shared
integer
null
null | 0 | 1 | 2
uuid
UUID | array
null
null | UUID | <UUID_
array>
Example
callAPI('GET','/actions',
array(
'page' => 2,
'limit' => 25,
'direction' => 'DESC',
'shared' => 2,
'uuid' => array(
338
Description
Sort direction
Sort-by column
n
null — All rules
n
0 — All rules
n
1 — Non-shared rules
n
2 — Shared rules
n
null — Retrieve all rules
n
UUID | array — Valid only after
this API has been run once
Security Analytics Reference Guide
Security Analytics 8.1
<uuid1>,
<uuid2>,
<uuid3>
)
)
);
Download rule scripts
API Path
/actions/download
Description
Retrieve workflow scripts
GUI Location
Menu
> Analyze > Rules
Output
download
Parameters
REQ
uuid
applianceId
Format Default
Valid Inputs
UUID
—
<GET: /actions>
integer
null
1-<n>
Example
callAPI('GET','/actions/download',
array(
'uuid' => <uuid>,
'applianceId' => 4
)
);
Create or edit a rule — MODIFIED
API Path
/actions/save
Description
Create or edit a rule
GUI Location
Menu
> Analyze > Rules > [New | Edit]
339
Description
UUID of Lua script to download
CMC Only. Sensor where rule resides
Security Analytics Reference Guide
Security Analytics 8.1
Output
array
Parameters
uuid
name
type
REQ
Format
Default
Valid Inputs
X
uuid
null
null | <GET: /actions>
X
string
integer
—
<UTF-8 characters>
1
0 | 1 | 2 | 4 | 8 | 128 |
256
268435<three-digit
type>
Description
n
New — Use null to
create a new rule
n
Edit — Required
n
New — Required
n
Edit — Optional
Valid if open parser is not
being used.
n
0 — None
n
1 — Alert
n
2 — Data
Enrichment
n
4 — PCAP Export
n
8 — IPFIX Export
n
128 — Dynamic
Filter
256 — Discard
Packets (new)
To enable open parser, use
these values:
n
openParser
array
—
regexes
string
—
n
456 — None
n
457 — Alert
n
458 — Data
Enrichment
n
460 — PCAP Export
n
464 — IPFIX Export
n
584 — Dynamic
Filter
Open parser attributes;
array includes regexes,
delimiter, and metaAction
<regular expressions>
340
Regular expression(s)
Security Analytics Reference Guide
Security Analytics 8.1
REQ
metaAction
delimiter
Format
Default
Valid Inputs
Description
integer
1
1 | 2 | 3 | 5
Action to take on matching
traffic
n
1 — Add flag to
metadata
n
2 — Add matching
value to metadata
n
3 — Add succeeding
value to metadata
until this delimiter;
requires delimiter
n
5 — Take no action
string
None
<RE-compliant
delimiter>
A delimiter; valid only if
metaAction=3
array
—
<GET: /favorites> |
<GET:
/favorites/active>
Array of indicator UUIDs
active
Boolean
true
true | false
True — Active
shared
Boolean
true
true | false
True — Shared
offBox
array
—
snmp
UUID
—
null |
<GET: /settings/all_
templates>
SNMP template UUID
smtp
UUID
—
null |
<GET: /settings/all_
templates>
SMTP template UUID
syslog
UUID
—
null |
<GET: /settings/all_
templates>
syslog template UUID
icdx
UUID
—
null |
<GET: /settings/all_
templates>
ICDx template UUID (new)
Boolean
false
true | false
emails
array
—
<user>@<domain>.<tld>
Email address(es)
applianceId
array
null
null | <GET: /cmc_
settings/appliances>
CMC Only. IDs of sensors
where the rule is written
favorites
phantomcyber
X
Remote notifications; array
includes snmp, smtp,
syslog, emails, icdx,
phantomcyber
341
True — Splunk Phantom
output is enabled (new)
Security Analytics Reference Guide
REQ
Security Analytics 8.1
Format
Default
Valid Inputs
alertInterval
seconds
900
1-<n>
Valid if type=1 or
type=268435457
900 = 15 minutes
importance
integer
1
1 | 2 | 3
Valid if type=1 or
type=268435457
integrationProviders
Description
n
1 — Notice
n
2 — Warning
n
3 — Critical
array
—
<GET: /integration_
providers/all_
providers>
Valid if type=2 or
type=268435458; real-time
enrichment provider IDs
mountId
integer
0
<GET: /pcap_
import/connections>
Valid if type=4 or
type=268435460; PCAP
server mount points
pcapng
Boolean
true
true | false
Valid if type=4 or
type=268435460; PCAP
export format
n
True — PCAPNG
n
False — PCAP
ipfix
array
—
ip
string
—
<ipv4 address> | <ipv6
address>
port
integer
—
1–65535
autonotch
array
—
duration
integer
300
<seconds>
Valid if type=128 or
type=268435584; number
of seconds before the filter
is removed
array
ip_
responder,
ip_port_
responder,
protocol
ip_initiator | ip_port_
initiator | ip_responder
| ip_port_responder |
protocol
Valid if type=128 or
type=268435584;
attributes of the flow to use
when creating the BPF filter
values
Valid if type=8 or
type=268435464; array
contains ip and port
IPFIX server address
IPFIX port
Valid if type=128 or
type=268435584; array
contains duration and
values
342
Security Analytics Reference Guide
REQ
Security Analytics 8.1
Format
Default
Valid Inputs
array
0
0 | 1
endPointProviders
Example 1
Create a new alert on a CMC and write it to two sensors
callAPI('POST','/actions/save',
array(
'uuid' => null,
'name' => 'Alert_1',
'type' => 1,
'favorites' => array(
<indicator_uuid-1>,
<indicator_uuid-2>
),
'applianceId' => array(
<sensorID-1>,
<sensorID-2>
),
'alertInterval' => 3600,
'importance' => 2,
'shared' => true,
'offBox' => array(
'snmp' => <template_id>,
'emails' => array(
<email_address-1>,
<email_address-2>
)
)
)
);
Example 2
Create a new data-enrichment rule
callAPI('POST','/actions/save',
array(
'uuid' => null,
'name' => 'Enrichment_1',
'type' => 2,
'favorites' => array(
<indicator_uuid-1>,
<indicator_uuid-2>
),
'integrationProviders' => array(
<enrichment_provider-1>,
<enrichment_provider-2>
),
'offBox' => array(
'smtp' => <snmp_template_id>
343
Description
Valid if type!=128 or
type!=268435584
n
0 — Do not send
data to endpoint
providers
n
1 — Send data to
endpoint providers
Security Analytics Reference Guide
Security Analytics 8.1
)
)
);
Example 3
Edit an IPFIX Export rule to change the server IP address
callAPI('POST','/actions/save',
array(
'uuid' => '<IPFIX_export_rule_uuid>',
'type' => 8,
'favorites' => array(
<indicator_uuid-1>,
<indicator_uuid-2>
),
'name' => 'PDF to IPFIX',
'ipfix' => array(
'ip' => '<new_ip_address>'
)
)
);
Example 4
Create a Dynamic Filter rule
callAPI('POST','/actions/save',
array(
'uuid' => null,
'name' => 'Netflix Filter',
'type' => 128,
'favorites' => array(
'<indicator_uuid-1>'
),
'shared' => true,
'offBox' => array(
'snmp' => '<template_id>',
'emails' => array(
'<email_address-1>',
'<email_address-2>'
),
),
'autonotch' => array(
'duration' => 30,
'values' => array(
'ip_port_responder',
'protocol'
)
)
)
);
Example 5
Create an open-parser rule.
344
Security Analytics Reference Guide
Security Analytics 8.1
callAPI('POST','/actions/save',
array(
'uuid' => null,
'name' => 'Phone Numbers',
'type' => 268435456,
'favorites' => array(
'<indicator_uuid-1>'
),
'openParser' => array(
'regexes' => array(
"((?:\+?1[ .-]\s*)?(((\(\s*[2-9]\d{2}\s*\)\s*[ .-]?)|([2-9]\d{2}\s*[
.-])))\s*[2-9]((1[02-9])|([02-9]\d{1}))\s*[ .-]\s*\d{4})"
),
'metaAction' => 2
)
'shared' => true,
'offBox' => array(
'icdx' => '<template_id>'
)
)
);
Example 6
Create a Discard Packets rule.
callAPI('POST','/actions/save',
array(
'uuid' => null,
'name' => 'Discard Encrypted',
'type' => 256,
'favorites' => array(
'<indicator_uuid-1>'
)
'shared' => true,
)
);
Activate/deactivate a rule
API Path
/actions/toggle/<uuid>
Description
Toggle a rule between active and inactive
GUI Location
Menu
> Analyze > Rules > Activated/Deactivated icon
Output
array
345
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
Format
Default
Valid Inputs
X
uuid
—
<GET: /actions>
Boolean
true
true | false
uuid
action
Description
UUID of a rule
n
True — Activate
n
False — Deactivate
Example
callAPI('POST','/actions/toggle/<uuid>',
array(
'action' => false
)
);
Delete a rule
API Path
/actions/delete
Description
Delete rules and rule references
GUI Location
Menu
> Analyze > Rules > [delete]
Parameters
selectedIds
REQ
Format
Default
Valid Inputs
X
array
—
<GET: /actions>
Example
callAPI('POST','/actions/delete',
array(
'selectedIds' => 'array(
'<uuid-1>',
'<uuid-2>',
'<uuid-3>'
)
)
);
346
Description
Array of rule UUIDs to delete
Security Analytics Reference Guide
Security Analytics 8.1
Security APIs
These APIs correspond to remote-access settings that are not specific to a user account, found mostly on the
Settings > Security page.
Also see: "User Account APIs" on page 386 and "Authentication APIs" on page 100.
Generate a Certificate-Signing Request
API Path
/settings/generate_req
Description
Generate a certificate-signing request
GUI Location
Menu
> Settings > Security > PKI and SSL
Output
Boolean
Parameters
REQ
Format
Default
Valid Inputs
countryName
X
STRING
—
<2-LETTER DESIGNATOR>
Two-letter country designator
according to ISO 3166; ALL
CAPS
stateOrProvinceName
X
string
—
<UTF-8 characters>
Spelled-out name of state or
province
localityName
X
string
—
<UTF-8 characters>
City or town
organizationName
X
string
—
<UTF-8 characters>
Company name
organizationalUnitName
X
string
—
<UTF-8 characters>
Division or department
commonName
X
string
—
<UTF-8 characters>
Domain name (CN) of the
server
emailAddress
X
string
—
<UTF-8 characters>
Contact e-mail address
Example
callAPI('GET','/settings/generate_req',
array(
'countryName' => 'US',
'stateOrProvinceName' => 'Utah',
'localityName' => 'Draper',
'organizationName' => 'Symantec',
'organizationalUnitName' => 'Engineering',
'commonName' => 'forensic302.ourcompany.com',
'emailAddress' => 'username@ourcompany.com'
)
347
Description
Security Analytics Reference Guide
Security Analytics 8.1
)
);
Get the number of passwords to remember
API Path
/system_security/password_settings
Description
Configure the PAM CRACKLIB password remember attribute
GUI Location
Menu
> Settings > Security > Password Settings
Output
array
Parameters
None
Example
callAPI('GET','/system_security/password_settings');
Get IPv6 firewall rules
API Path
/firewall6
Description
Retrieve the IPv6 firewall rules
GUI Location
Menu
> Settings > Security > Firewall IPv6
Output
array
Parameters
None
348
Security Analytics Reference Guide
Security Analytics 8.1
Example
callAPI('GET','/firewall6');
Get IPv4 firewall rules
API Path
/firewall
Description
Retrieve the IPv4 firewall rules
GUI Location
Menu
> Settings > Security > Firewall
Output
array
Parameters
None
Example
callAPI('GET','/firewall');
Get password aging
API Path
/users/password_aging/<id>
Description
Retrieve how often a user must change the password, in days
GUI Location
Initial Configuration
Output
string
349
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
Format
Default
Valid Inputs
X
integer |
string
—
<
GET: /settings/users
> | admin | root
id
Example
callAPI('GET','/users/password_aging/<id>');
Get password-strength information
API Path
/system_security/password_strength
Description
Retrieve the system password-strength attributes.
GUI Location
n
Initial Configuration
n
Menu
> Settings > System > Password Strength
Output
array
Parameters
None
Example
callAPI('GET','/system_security/password_strength');
Get web-access settings
API Path
/settings/security
350
Description
User ID or username
Security Analytics Reference Guide
Security Analytics 8.1
Description
Retrieve an array of remote-access security settings such as maximum authorization attempts, authentication
lockout interval
GUI Location
Menu
> Settings > Security > Web Access
Output
array
Parameters
None
Example
callAPI('GET','/settings/security');
Get certificates and keys
API Path
/settings/pki
Description
Retrieve certificate and key information
GUI Location
Menu
> Settings > Security > PKI and SSL
Output
array
Parameters
None
Example
callAPI('GET','/settings/pki');
Configure the number of passwords to remember
API Path
/system_security/password_settings
351
Security Analytics Reference Guide
Security Analytics 8.1
Description
Configure the PAM CRACKLIB password remember attribute
GUI Location
Menu
> Settings > Security > Password Settings
Output
integer
Parameters
remember
REQ
Format
Default
Valid Inputs
X
integer
—
0–10
Description
Number of passwords to remember
Example
callAPI('POST','/system_security/password_settings'
array(
'remember' => 8
)
);
Configure an IPv6 firewall rule chain
API Path
/firewall/add_rules6
Description
Add one or more rule chains to the IPv6 firewall
GUI Location
Menu
> Settings > Security
Output
array
Parameters
REQ
Format
Default
Valid Inputs
X
array
—
—
chain
string
INPUT
INPUT
Type of chain; only INPUT is valid
position
integer
—
0–<n>
Position in the rule chain; default is
last position
rules
352
Description
Array of rule objects; array contains
all other parameters
Security Analytics Reference Guide
REQ
Security Analytics 8.1
Format
Default
Valid Inputs
match
array
—
comment | state | <service
name>
Match extension; array may contain
comment, state, or a service name;
the parameter specified here must
be included in the rules array
comment
string
—
<ASCII-printable
characters>
Up to 250 ASCII-printable characters
state
string
—
NEW
|
ESTABLISHED
| RELATED | INVALID
destination
string
—
<ipv6> | <ipv6:CIDR>
destinationport
string
—
1–65536 | <service name>
in-interface
string
—
<GET: /captures/list_
interfaces> | ANY
Interface where the packet is
received
jump
string
—
ACCEPT | DROP | QUEUE |
RETURN
Policy — The action to take when the
rule matches
mac
string
—
<ethernet address>
Hardware address
protocol
string
—
<service name> | all
Protocol for the rule
source
string
—
<ipv6> | <ipv6:CIDR>
Source IP address or CIDR-formatted
network
source-port
string
—
1–65536 | <service name>
Example
callAPI('POST','/firewall/add_rules6',
array(
'rules' => array(
array =>
chain => INPUT,
position => 0,
match => array(
'icmp6',
'in-interface'
),
source => '2620:25:0:8a8f::/64',
source-port => 'icmp6',
in-interface => 'eth3',
jump => 'ACCEPT',
protocol => 'icmp6',
state => 'NEW'
),
array =>
chain => INPUT,
position => 0,
match => array(
'icmp6',
'in-interface'
),
source => '2620:7a:3e:100::/64',
source-port => 'icmp6',
353
Description
State of the connection
Destination IP address or CIDRformatted network
Destination port or service name
Source port or service name
Security Analytics Reference Guide
Security Analytics 8.1
in-interface => 'eth3',
jump => 'ACCEPT',
protocol => 'icmp6',
state => 'NEW'
)
)
)
);
Update the IPv6 firewall rule chain
API Path
/firewall/update_chain6
Description
Update the IPv6 rule chain
GUI Location
Menu
> Settings > Security
Output
array
Parameters
REQ
rules
Format
Default Valid Inputs
Description
array
—
<GET: /firewall6>
chain
string
INPUT
INPUT
Type of chain; only INPUT is valid
position
integer
—
0–<n>
Position in the rule chain; default is
last position
match
array
—
comment | state | <service
name>
Match extension; array may contain
comment, state, or a service name;
the parameter specified here must
be included in the rules array
comment
string
—
<ASCII-printable
characters>
Up to 250 ASCII-printable characters
state
string
—
NEW
|
ESTABLISHED
| RELATED | INVALID
destination
string
—
<ipv6> | <ipv6:CIDR>
destinationport
string
—
1–65536 | <service name>
X
354
Array of rule objects; array contains
all other parameters
State of the connection
Destination IP address or CIDRformatted network
Destination port or service name
Security Analytics Reference Guide
REQ
Format
Security Analytics 8.1
Default Valid Inputs
Description
in-interface
string
—
<GET: /captures/list_
interfaces> | ANY
Interface where the packet is
received
jump
string
—
ACCEPT | DROP | QUEUE |
RETURN
Policy — The action to take when the
rule matches
mac
string
—
<ethernet address>
Hardware address
protocol
string
—
<service name> | all
Protocol for the rule
source
string
—
<ipv6> | <ipv6:CIDR>
Source IP address or CIDR-formatted
network
source-port
string
—
1–65536 | <service name>
Example
callAPI('POST','/firewall/update_chain6',
array(
'rules' => array(
array =>
chain => INPUT,
position => 5,
match => array(
'icmp6',
'in-interface'
),
source => '2620:7a:3e:100::/64',
source-port => 'icmp6',
in-interface => 'eth3',
jump => 'ACCEPT',
protocol => 'icmp6',
state => 'NEW'
)
)
)
);
Delete an IPv6 firewall rule chain
API Path
/firewall/delete_rules6
Description
Delete an IPv6 firewall rule
GUI Location
Menu
> Settings > Security > Firewall IPv6 > [delete rule]
Output
array
355
Source port or service name
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
Format
Default
rules
X
array
—
position
X
integer
—
Valid Inputs
Description
Array of rule objects; only position
is valid
<GET: /firewall6>
Position in the rule chain of the rule
to delete
Example
callAPI('POST','/firewall/delete_rules6',
array(
'rules' => array(
array => (
position => 9
),
array => (
position => 10
)
)
)
);
Configure an IPv4 firewall rule chain
API Path
/firewall/add_rules
Description
Add one or more rule chains to the IPv4 firewall
GUI Location
Menu
> Settings > Security
Output
array
Parameters
REQ
Format
Default
Valid Inputs
X
array
—
<GET: /firewall>
Array of rule objects; array
contains all other
parameters
chain
string
INPUT
INPUT
Type of chain; only INPUT is
valid
position
integer
—
0–<n>
Position in the rule chain;
default is last position
rules
356
Description
Security Analytics Reference Guide
Security Analytics 8.1
REQ
Format
Default
Valid Inputs
match
array
—
comment
| state | <service name>
comment
string
—
<ASCII-printable
characters>
state
string
—
NEW
|
ESTABLISHED
| RELATED | INVALID
destination
string
—
<dotteddecimal> | <CIDR>
destination-port
string
—
1–65536 | <service name>
Destination port or service
name
in-interface
string
—
<GET: /captures/list_
interfaces> | ANY
Interface where the packet
is received
jump
string
—
ACCEPT | DROP | QUEUE |
RETURN
Policy — The action to take
when the rule matches
mac
string
—
<ethernet address>
Hardware address
protocol
string
—
<service name> | all
Protocol for the rule
source
string
—
<dotteddecimal> | <CIDR>
source-port
string
—
1–65536 | <service name>
Example
callAPI('POST','/firewall/add_rules',
array(
'rules' => array(
array =>
chain => INPUT,
position => 0,
match => array(
'icmp',
'in-interface'
),
source => '203.0.113.0/24',
source-port => 'icmp',
in-interface => 'eth3',
jump => 'ACCEPT',
protocol => 'icmp',
state => 'NEW'
),
array =>
chain => INPUT,
position => 1
match => array(
357
Description
Match extension; array may
contain comment, state, or
a service name; the
parameter specified here
must be included in the
rules array
Up to 250 ASCII-printable
characters
State of the connection
Destination IP address or
CIDR-formatted network
Source IP address or CIDRformatted network
Source port or service
name
Security Analytics Reference Guide
Security Analytics 8.1
'icmp',
'in-interface'
),
source => '192.0.2.0/24',
source-port => 'icmp',
in-interface => 'eth3',
jump => 'ACCEPT',
protocol => 'icmp',
state => 'NEW'
)
)
)
);
Update the IPv4 firewall rule chain
API Path
/firewall/update_chain
Description
Replace the existing IPv4 rule chain with the provided chain
GUI Location
Menu
> Settings > Security
Output
array
Parameters
REQ
Format
Default
Valid Inputs
X
array
—
<GET: /firewall>
chain
string
INPUT
INPUT
Type of chain; only INPUT is valid
position
integer
—
0–<n>
Position in the rule chain; default is
last position
match
array
—
comment | state | <service
name>
Match extension; array may contain
comment, state, or a service name;
the parameter specified here must
be included in the rules array
comment
string
—
<ASCII-printable
characters>
Up to 250 ASCII-printable characters
rules
358
Description
Array of rule objects; array contains
all other parameters
Security Analytics Reference Guide
REQ
Security Analytics 8.1
Format
Default
Valid Inputs
state
string
—
NEW
|
ESTABLISHED
| RELATED | INVALID
destination
string
—
<dotted-decimal> | <CIDR>
Destination IP address or CIDRformatted network
destinationport
string
—
1–65536 | <service name>
Destination port or service name
in-interface
string
—
<GET: /captures/list_
interfaces> | ANY
Interface where the packet is
received
jump
string
—
ACCEPT | DROP | QUEUE |
RETURN
Policy — The action to take when the
rule matches
mac
string
—
<ethernet address>
Hardware address
protocol
string
—
<service name> | all
Protocol for the rule
source
string
—
<dotted-decimal> | <CIDR>
Source IP address or CIDR-formatted
network
source-port
string
—
1–65536 | <service name>
Source port or service name
Example
callAPI('POST','/firewall/update_chain',
array(
'rules' => array(
array =>
chain => INPUT,
position => 0,
match => array(
'icmp',
'in-interface'
),
source => '203.0.113.0/24',
source-port => 'icmp',
in-interface => 'eth3',
jump => 'ACCEPT',
protocol => 'icmp',
state => 'NEW'
)
)
)
);
Delete the IPv4 firewall rule chain
API Path
/firewall/delete_rules
359
Description
State of the connection
Security Analytics Reference Guide
Security Analytics 8.1
Description
Delete an IPv4 firewall rule
GUI Location
Menu
> Settings > Security > Firewall
Output
array
Parameters
REQ
Format
Default
rules
X
array
—
position
X
integer
—
Valid Inputs
Array of rule objects; only position is
valid
<GET: /firewall>
Example
callAPI('POST','/firewall/delete_rules',
array(
'rules' => array(
array => (
position => 5
),
array => (
position => 6
)
)
)
);
Set password-strength information
API Path
/system_security/password_strength
Description
Configure the system password-strength attributes
GUI Location
n
Initial Configuration
n
Menu
Description
> Settings > System > Password Strength
Output
ApiResultCode
360
Position in the rule chain of the rule to
delete
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
Format
Default
Valid Inputs
array
null
0-96
Number of characters that must be different
in the new password
dcredit
integer
null
0 | 1
1 — Numeral required
minlen
integer
null
6–96
Minimum password length
maxrepeat
integer
null
0–96
Frequency of password occurrence
ocredit
integer
null
0 | 1
1 — Require other (special) characters
lcredit
integer
null
0 | 1
1 — Require lower-case
ucredit
integer
null
0 | 1
1 — Require uppercase
difok
Description
Example
callAPI('POST','/system_security/password_strength',
array(
'difok' => 0,
'dcredit' => 1,
'minlen' => 15,
'maxrepeat' => 10,
'ocredit' => 1,
'ucredit' => 1,
'lcredit' => 1
)
);
Configure password aging
API Path
/users/password_aging/<id>
Description
How often users must change the password, in days
GUI Location
n
Initial Configuration
n
Menu
> Settings > Users and Groups > Users > [edit user] > Password Aging
Output
array
361
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
Format
Default
Valid Inputs
Description
id
X
integer | string
—
admin | <GET:
User ID or
/users/account_ username
info>
max_days_between_password_change
X
integer
—
0 | 7 | 14 | 30 | Number of
60 | 90 | 120 | days before
365
the
password
must be
changed
n
Example
callAPI('POST','/users/password_aging/root',
array(
'max_days_between_password_change' => '90'
)
);
Configure global access settings
API Path
/settings/security
Description
Configure GUI-access settings
GUI Location
Menu
> Settings > Security
Output
array
Parameters
REQ
Format
Default
Valid Inputs
params
X
array
—
<GET:
/settings/security>
Array of parameters, listed below
SystemSetting
X
array
—
<GET:
/settings/security>
UI-access setting names
362
Description
0—
Never
Security Analytics Reference Guide
REQ
Security Analytics 8.1
Format
Default
Valid Inputs
max_auth_
attempts
integer
3
1–32767
auth_lockout_
interval
integer
1200
1–99999999
max_web_
sessions
integer
10
1–32767
Boolean
true
true | false
web_port
integer
80
1–65536
HTTP port number
web_port_
secure
integer
443
1–65536
HTTPS port number
allow_ssh
Boolean
true
true | false
ssh_port
integer
22
1–65536
SSH port number
vpn_port
integer
1194
1–65536
CMC Only. CMC VPN port
fips_mode
Boolean
false
true | false
True — Enable FIPS mode
respond_to_
ping
Boolean
false
true | false
True — Respond to ICMP pings
enable_
firewall
Boolean
true
true | false
True — Enable IPv4 firewall
enable_
firewall6
Boolean
true
true | false
True — Enable IPv6 firewall
only_allow_
secure
Example
callAPI('POST','/settings/security',
'params' => array(
'SystemSetting' => array(
'max_auth_attempts' => 4,
'max_web_sessions' => 20,
'auth_lockout_interval' => 3600,
'only_allow_secure' => true,
'web_port' => 88,
'web_port_secure' => 443,
'allow_ssh' => 'false,
'ssh_port' => 22,
'vpn_port' => 5194,
'fips_mode' => true,
'respond_to_ping' => true,
'enable_firewall' => true,
'enable_firewall6' => true
)
)
);
Edit root password
API Path
/settings/edit_root_password
363
Description
Maximum login attempts
Unsuccessful login timeout in seconds
Maximum concurrent web sessions
True — Require HTTPS access
True — Allow SSH access
Security Analytics Reference Guide
Security Analytics 8.1
Description
Edit the root password
GUI Location
Initial Configuration
Output
ApiResultCode
Parameters
REQ
Format
Default
X
string
—
password
Valid Inputs
<conforms to current password
requirements>
Description
Root password
Example
callAPI('POST','/settings/edit_root_password',
array(
'password' => '3030rootMEouT#$#'
)
);
Configure PKI settings
API Path
/settings/pki
Description
Configure PKI certificate settings
GUI Location
Menu
> Settings > Security
Output
array
Parameters
REQ
Format
Default
Valid Inputs
Description
server_cert_name
X
filepath
—
<filepath>
Path to the SSL
certificate file
server_cert_key
X
filepath
—
<filepath>
Path to the key file for
server_cert_name
364
Security Analytics Reference Guide
Security Analytics 8.1
REQ
client_verification
client_verification_ad
use_server_cert
client_ca
client_crl_url
Format
Default
Boolean
false
Boolean
Boolean
false
true
Valid Inputs
true | false
true | false
true | false
Description
n
True — Verify
client certificate
n
False — No
verification; any
parameters
that follow will
be ignored
n
True — Require
client certificate
for Login
Correlation
Service
n
False —
Certificate not
required for
LCS
n
True — Use
existing SSL
certificate and
key for
CMC/sensor
communication;
client_ca and
client_crl_url
will be ignored
n
False — Use
the SSL
certificate and
key that follow
for CMC/sensor
communication
filepath
—
<filepath>
Path to the issuing
authority's certificate;
valid when client_
verification=cert or
use_server_
cert=false
string
—
<URL>.[pem | der |
crl]
Certificate revocation
list for the issuing
authority; valid when
client_
verification=true or
use_server_
cert=false
365
Security Analytics Reference Guide
Security Analytics 8.1
REQ
Format
Default
Valid Inputs
Description
client_cert_name
filepath
—
<filepath>
Path to the SSL client
certificate for
CMC/sensor
communication
client_cert_key
filepath
—
<filepath>
Path to the key for
client_cert_name
enable_revocation_check
Boolean
true
true | false
Example
callAPI('POST','/settings/pki',
array(
'server_cert_name' => '/etc/pki/tls/certs/mySSLcert.crt',
'server_cert_key' => '/etc/pki/tls/private/mySSLkey.key',
'client_verification' => true,
'client_ca' => '/etc/pki/tls/certs/CAsslCERT.crt',
'client_crl_url' => 'https://issuer.domain.com',
'user_server_cert' => false,
'client_cert_name' => '/etc/pki/tls/certs/myCLIENTcert.crt',
'client_cert_key' => '/etc/pki/tls/private/myCLIENTkey.key'
)
);
366
True — Check for
revocation of the
Intelligence Services
certificates
Security Analytics Reference Guide
Security Analytics 8.1
Statistics APIs
Get all interface statistics
API Path
/statistics/network
Description
Get statistics for all Ethernet interfaces
GUI Location
Menu
> Statistics > Network System
Output
array
Parameters
None
Example
callAPI('GET','/statistics/network');
Get statistics for an interface
API Path
/statistics/network_details/<interface>
Description
Get statistics for a specified Ethernet interface
GUI Location
Menu
> Statistics > Network System > [interface name]
Output
array
Parameters
interface
REQ
Format
Default
Valid Inputs
Description
X
string
—
ethX | aggX
Ethernet or aggregated
interface
Example
callAPI('GET','/statistics/network_details/eth3');
367
Security Analytics Reference Guide
Security Analytics 8.1
Get size of data on disk
API Path
/statistics/size
Description
Retrieve the size on disk data for all interfaces; data is cumulative since the last reboot of the appliance
GUI Location
Menu
> Statistics > Size on Disk
Output
array
Parameters
None
Example
callAPI('GET','/statistics/size');
Get storage statistics
API Path
/statistics/storage
Description
Retrieve information about the storage system
GUI Location
Menu
> Statistics > Storage System
Output
object | array
Parameters
None
Example
callAPI('GET','/statistics/storage');
368
Security Analytics Reference Guide
Security Analytics 8.1
Summary Page APIs
Also see "Report and Report Status APIs" on page 302.
Get a list of Summary and Geolocation views
API Path
/deepsee/summary_views
Description
Retrieve Summary views and their report widgets; return Geolocation views and their properties
GUI Location
n
Menu
> Analyze > Summary > [View Selector]
n
Menu
> Analyze > Summary > Geolocation > [View Selector]
Parameters
None
Python Example
s.callAPI("GET","/deepsee/summary_views")
PHP Example
callAPI('GET','/deepsee/summary_views');
Output
'result': {'geolocation_views': [{'defaultView': True,
'id': 8,
'shared': True,
'text': 'World',
'user_id': 1,
'view_data': {'lat': 0,
'lon': 0,
'zoom': 0}}],
'summary_views': [{'defaultView': True,
'format': 1,
'id': 1,
'reportlets': [{'source': 'application_group'},
{'source': 'application_group_time'},
{'requestParams': {'column': 'sessions',
'direction': 'd',
'metrics': ['sessions'],
'type': 'ranked',
'view': ['table']},
'source': 'application_id'},
{'source': 'country_initiator'},
{'source': 'country_responder'}],
'shared': True,
'text': 'Default View',
'user_id': 1},
...
{'defaultView': False,
'format': 1,
369
Security Analytics Reference Guide
Security Analytics 8.1
'id': 7,
'reportlets': [{'source': 'application_group'},
{'source': 'application_group_time'},
{'source': 'application_id'},
{'source': 'ipv4_initiator'},
{'source': 'ipv4_responder'},
{'requestParams': {'column': 'item',
'direction': 'd',
'metrics': ['sessions'],
'type': 'ranked',
'view': ['table']},
'source': 'flow_duration'},
{'requestParams': {'column': 'item',
'direction': 'd',
'metrics': ['sessions'],
'type': 'ranked',
'view': ['table']},
'source': 'bytes'},
{'source': 'dns_name'},
{'source': 'country_initiator'},
{'source': 'country_responder'},
{'source': 'port_initiator'},
{'source': 'port_responder'}],
'shared': True,
'text': 'Anomaly Investigation',
'user_id': 1}]},
'resultCode': 'API_SUCCESS_CODE',
Get report field information
API Path
/deepsee/field_info
Description
Retrieve all possible report names, all possible filter terms, all fields that can be used with len_* and num_*
queries, all fields grouped by namespace, mapping between flow namespace fields and any corresponding
packet namespace field, all fields available for remote notification, and all possible custom fields.
GUI Location
[Various menus and other screen elements throughout the GUI]
Parameters
None
Python Example
s.callAPI("GET","/deepsee/field_info")
PHP Example
callAPI('GET','/deepsee/field_info');
Output
'result': {'aggregate_fields': ['database_query',
'dns_ancount',
'dns_host_ipv4_addr',
'dns_host_ipv6_addr',
370
Security Analytics Reference Guide
Security Analytics 8.1
...
'voip_id',
'web_query',
'web_server'],
'all_report_fields': ['application_group',
'application_id',
'autogenerated_domain',
...
'voip_id',
'web_query',
'web_server'],
'custom_analytic_fields': [],
'flow_only_report_fields': ['application_group',
'application_id',
'autogenerated_domain',
'autogenerated_domain_score',
...
'voip_id',
'web_query',
'web_server'],
'namespace_fields': {'flows': {'application_group': True,
'application_group_time': True,
...
'web_query': True,
'web_server': True},
'groups': {'fuzzy_hash': True,
'md5_hash': True,
'sha1_hash': True,
'sha256_hash': True},
'packets': {'ethernet_address_packet': True,
'ethernet_address_vendors_packet': True,
'modbus_function_code': True,
'modbus_function_code_name': True,
'packet_length': True},
'verdicts': {'file_signature_verdict': True,
'local_file_analysis_verdict': True,
...
'url_categories': True,
'url_risk_verdict': True}},
'offbox_possible_fields': ['application_group',
'application_id',
...
'web_query',
'web_server'],
'raw_tsv_fields': ['protocol_family',
'application_ids',
...
'aggregate_web_query_hooks',
'aggregate_web_server_hooks'],
'report_fields': ['application_group',
'application_id',
...
'web_query',
'web_server'],
'search_fields': ['application_group',
'application_id',
...
'tcp_port',
'udp_port']},
'resultCode': 'API_SUCCESS_CODE',
Create or edit a Summary view
API Path
/deepsee/save_view
371
Security Analytics Reference Guide
Security Analytics 8.1
Description
Create or edit a Summary or Geolocation view
GUI Location
n
Menu
> Analyze > Summary > [View Selector] > Add New View
n
Menu
> Analyze > Summary > Geolocation > [View Selector] > Save Current Map as View
Output
ApiResultCode
Parameters
id
name
REQ
Format
X
integer/null
X
format
string
integer
Default
null
Valid Inputs
null | <GET: /deepsee/summary_
views>
—
<UTF-8 characters>
1
1 | 2
Description
n
Create new — Use null
n
Edit entry — ID
required
n
Create new — Name
required
n
Edit entry — New
name
n
1 — Use flow-based
columns
n
2 — Use fixed columns
shared
Boolean
false
true | false
True — Shared view
default
Boolean
false
true | false
True — Default view
Python Example
s.callAPI("POST","/deepsee/save_view", {
'id': null,
'name': 'E-Mail',
'format': 1,
'shared': True,
'default': True
}
)
PHP Example
callAPI('POST','/deepsee/save_view',
array(
'id' => null,
'name' => 'E-Mail',
'format' => 1,
'shared' => true,
'default' => true
)
);
372
Security Analytics Reference Guide
Security Analytics 8.1
Add a report widget to a Summary view
API Path
/deepsee/create_reportlet
Description
Add one or more report widgets to a view
GUI Location
n
Menu
> Analyze > Summary > Actions > Add/Edit Widgets
n
Menu
> Analyze > Summary > [View Selector] > Add New View > Save > Add Report Widget
Output
array
Parameters
REQ
Format
id
X
integer
fields
X
array
Default
Valid Inputs
Description
—
<GET: /deepsee/summary_views>
ID of the view
—
<GET: /deepsee/field_info>
Python Example
s.callAPI("POST","/deepsee/create_reportlet", {
'id': 8,
'fields': [
'dns_ancount',
'dns_name',
'dns_ttl'
]
}
)
PHP Example
callAPI('POST','/deepsee/create_reportlet',
array(
'id' => 8,
'fields' => array(
'dns_ancount',
'dns_name',
'dns_ttl'
)
)
);
373
Array of widgets to add
Security Analytics Reference Guide
Security Analytics 8.1
Edit a report widget
API Path
/deepsee/edit_reportlet
Description
Edit one or more report widgets
GUI Location
Menu
> Analyze > Summary > [selected view] > [edit widget]
Output
array
Parameters
REQ
Format
id
X
integer
—
<GET: /deepsee/summary_ ID of the view
views>
field
X
string
—
<GET: /deepsee/summary_ Name of report widget
views>
X
array
—
<GET: /deepsee/summary_ Parameters to edit; array may
views>
contain all of the parameters below
type
string
ranked
ranked
direction
string
d
a | d
requestParams
column
view
string
array
Default
item
table
Valid Inputs
Description
Only ranked is valid
Sort order
n
a — Ascending
n
d — Descending
item | sessions | bytes | Sort-by field
packets | fragments |
n item — Report attribute
bad_csums
table | pie | column |
bar
Python Example
s.callAPI("POST","/deepsee/edit_reportlet", {
'id': 3,
'field': 'tcp_initiator',
'requestParams': {
'type' => 'ranked',
'direction' => 'd',
'column' => 'sessions',
374
n
fragments — IP fragments
n
bad_csums — Bad
checksums
Display mode
Security Analytics Reference Guide
Security Analytics 8.1
'view' => [
'pie'
]
}
}
)
PHP Example
callAPI('POST','/deepsee/edit_reportlet',
array(
'id' => 3,
'field' => 'tcp_initiator',
'requestParams' => array(
'type' => 'ranked',
'direction' => 'd',
'column' => 'sessions',
'view' => array(
'pie'
)
)
)
);
Delete a report widget from a Summary view
API Path
/deepsee/delete_reportlet
Description
Delete one or more report widgets from a Summary view
GUI Location
Menu
> Analyze > Summary > [Report Widget] > [delete widget]
Output
array
Parameters
REQ
Format
id
X
integer
fields
X
array
Default
Valid Inputs
Description
—
<GET: /deepsee/summary_views>
ID of the view
—
<GET: /deepsee/summary_views>
Array of report widgets to
delete
Python Example
s.callAPI("POST","/deepsee/delete_reportlet", {
'id': 7,
'fields': [
'flow_id',
'interface',
'mime_type'
]
375
Security Analytics Reference Guide
Security Analytics 8.1
}
)
PHP Example
callAPI('POST','/deepsee/delete_reportlet',
array(
'id' => 7,
'fields' => array(
'flow_id',
'interface',
'mime_type'
)
)
);
Edit the report-widget order in a view
API Path
/deepsee/edit_reportlet_order
Description
Change the order in which the report widgets appear in a Summary view. Report widgets not in the order array
are deleted from the view. Report widgets newly included in the order array are added to the view.
GUI Location
Menu
> Analyze > Summary > [Summary View]
Output
ApiResultCode
Parameters
REQ
Format
id
X
integer
order
X
array
Default
Valid Inputs
Description
—
<GET: /deepsee/summary_views>
ID of the view
—
<GET: /deepsee/summary_views> |
<GET: /deepsee/field_info>
Python Example
s.callAPI("POST","/deepsee/edit_reportlet_order", {
'id': 8,
'order': [
'<first_widget>',
'<second_widget>',
'<third_widget>',
'<fourth_widget>',
'<nth_widget>'
]
}
}
PHP Example
callAPI('POST','/deepsee/edit_reportlet_order',
376
Names of the widgets in the
desired sequence
Security Analytics Reference Guide
Security Analytics 8.1
array(
'id' => 8,
'order' => array(
'<first_widget>',
'<second_widget>',
'<third_widget>',
'<fourth_widget>',
'<Nth_widget>'
)
)
);
Delete a Summary page view
API Path
/deepsee/delete_view/<viewId>
Description
Delete a Summary page view
GUI Location
Menu
> Analyze > Summary > [View Selector] > [Delete View]
Output
ApiResultCode
Parameters
viewId
REQ
Format
X
integer
Default
—
Valid Inputs
Description
<GET: /deepsee/summary_views>
ID of the view
Python Example
s.callAPI("POST","/deepsee/delete_view/<viewId>")
PHP Example
callAPI('POST','/deepsee/delete_view/<viewId>');
377
Security Analytics Reference Guide
Security Analytics 8.1
System APIs
Get disk health status
API Path
/disk_health/download
Description
Download a file that contains information on the health of system disks
GUI Location
Click system error banner > Download button
Output
disk_health_<YYYY-MM-DD>T<zz:zz>_<mmiiss>.log.tar.gz
Parameters
None
Example
callAPI('GET','/disk_health/download');
Download the CSR
API Path
/system/csr
Description
Download the customer-service report
GUI Location
Menu
> Settings > System
Output
ApiResultCode
Parameters
None
Example
callAPI('GET','/system/csr');
378
Security Analytics Reference Guide
Security Analytics 8.1
Reboot the system gracefully
API Path
/system/reboot
Description
Reboot the system after all processes have finished
GUI Location
Menu
> Settings > System > Reboot
Output
ApiResultCode
Parameters
None
Example
callAPI('POST','/system/reboot');
Shut down the system gracefully
API Path
/system/shutdown
Description
Shut down the system after all processes have finished
GUI Location
Menu
> Settings > System > Shut Down
Output
ApiResultCode
Parameters
None
Example
callAPI('POST','/system/shutdown');
379
Security Analytics Reference Guide
Security Analytics 8.1
Upgrades APIs
Perform upgrade precheck
API Path
/upgrades/check
Description
Retrieve the usage statistics on /var and /home and the size of extractions on disk.
GUI Location
Menu
> Settings > Upgrade > Upgrade Precheck button
Parameters
None
PHP Example
callAPI('GET','/upgrades/check');
Python Example
callAPI("GET","/upgrades/check")
Output
'result': {'extractorSize': {'data': '<integer>',
'localizedType': 'Size of Extractions on Disk',
'type': 'extractorSize'},
'fsck': {'data': [[{'mount': '/boot', 'name': 'BOOT'}]],
'localizedType': 'fsck.label',
'type': 'fsck'},
'homeSize': {'data': 'Using <b><integer>%</b> of <b>/HOME</b> drive: '
'<b><integer>G</b> used; <b><integer>G</b> available.',
'localizedType': '/home Disk Usage',
'type': 'homeSize'},
'varSize': {'data': 'Using <b><integer>%</b> of <b>/VAR</b> drive: '
'<b><integer>G</b> used; <b><integer>G</b> available.',
'localizedType': '/var Disk Usage',
'type': 'varSize'}},
'resultCode': 'API_SUCCESS_CODE',
Get upgrade servers
API Path
/upgrades/list
Description
Retrieve a list of upgrade servers
GUI Location
Menu
> Settings > Upgrades
380
Security Analytics Reference Guide
Security Analytics 8.1
Output
array
Parameters
None
Example
callAPI('GET','/upgrades/list');
Get the manifest
API Path
/upgrades/manifest
Description
Retrieve a list of possible upgrades
GUI Location
Menu
> Settings > Upgrades > Upgrade from Server
Output
string
Parameters
serverId
filter
REQ
Format
Default
Valid Inputs
X
integer
—
<GET: /upgrades/list>
Boolean
true
true | false
Example
callAPI('GET','/upgrades/manifest',
array(
'serverId' => 2,
'filter' => 'true'
)
);
Get download status
API Path
/upgrades/download_status
381
Description
Upgrade server ID
n
True — Retrieve only applicable
upgrades
n
False — Retrieve all upgrades
Security Analytics Reference Guide
Security Analytics 8.1
Description
Retrieve the status of an upgrade file's download to an appliance
GUI Location
Menu
> Settings > Upgrades > [progress bar]
Output
array
Parameters
REQ
Format
Default
Valid Inputs
Description
serverId
X
integer
—
<GET: /upgrades/list>
Upgrade server ID
fileName
X
text
—
<GET: /upgrades/manifest>
Upgrade file name
Example
callAPI('GET','/upgrades/download_status',
array(
'serverId' => 2,
'fileName' => 'atpsa-8.1.1-45000-x86_64-DVD.tar'
)
);
Configure upgrade server
API Path
/upgrades/edit_server
Description
Create or edit an upgrade-server entry
GUI Location
Menu
> Settings > Upgrade > New
Output
ApiResultCode
Parameters
REQ
Format
Default
Valid Inputs
type
X
integer
—
1
protocol
X
integer
—
0 | 1
host
X
string
—
hostname | <ip_address>
382
Description
Reserved. Always use 1
0 — HTTP
1 — HTTPS
Location of upgrade server
Security Analytics Reference Guide
Security Analytics 8.1
REQ
Format
path
X
string
—
/<filepath>/
Must begin and end with slash
file_name
X
string
—
Manifest.xml
Must be this filename
username
X
string
—
<UTF-8 characters>
User name to access the server
password
X
string
—
<UTF-8 characters>
Password for the user name
integer
—
<GET: /upgrades/list>
id
validate_
certificate
Default
Valid Inputs
true
Boolean
true | false
Description
n
Create new — Omit field
n
Edit entry — ID required
Valid only if protocol=1; validate the
update-server certificate
Example
callAPI('POST','/upgrades/edit_server',
array(
'type' => '1',
'protocol' => '0',
'host' => 'upgrades.domain.com',
'file_name' => 'Manifest.xml',
'path' => '/upgrades/'
'username' => 'admin',
'password' => '55geT!meIn&*'
)
);
Delete an upgrade server
API Path
/upgrades/delete/<id>
Description
Remove an upgrade server
GUI Location
Menu
> Settings > Upgrade > Delete
Output
ApiResultCode
Parameters
REQ
Format
Default
Valid Inputs
X
integer
—
<GET: /upgrades/list>
id
Example
callAPI('POST','/upgrades/delete/2');
383
Description
Upgrade server ID
Security Analytics Reference Guide
Security Analytics 8.1
Download an upgrade file
API Path
/upgrades/select
Description
Downloads an upgrade file for local installation.
GUI Location
Menu
> Settings > Upgrade > Upgrade from Server
Output
ApiResultCode
Parameters
REQ
Format
Default
Valid Inputs
serverId
X
integer
—
<GET: /upgrades/list>
upgradeFile
X
string
—
atpsa-<version>-x86_64DVD.tar
Example
callAPI('POST','/upgrades/select',
array(
'serverId' => 3,
'upgradeFile' => 'atpsa-8.1.1-45000-x86_64-DVD.tar'
)
);
Initiate upgrade
API Path
/upgrades/initiate
Description
Begin upgrading an appliance
GUI Location
Menu
> Settings > Upgrade > Upgrade from Server
Output
ApiResultCode
384
Description
Server ID
Name of upgrade file
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
filename
REQ
Format
Default
Valid Inputs
X
string
—
atpsa-<version>-x86_64-DVD.tar
Example
callAPI('POST','/upgrades/initiate',
array(
'filename' => 'atpsa-8.1.1-45000-x86_64-DVD.tar'
)
);
385
Description
Name of upgrade file
Security Analytics Reference Guide
Security Analytics 8.1
User Account APIs
These APIs correspond to the functions on the [Account_Name]
> Preferences dialogs and the Users and Groups Settings page.
> Account Settings and[Account_Name]
Also see "Authentication APIs" on page 100 and "Security APIs" on page 347.
Get logged-in user information
API Path
/users/account_info
Description
Retrieve the name, email, and ID of the logged-in user
GUI Location
[Account Name]
> Account Settings
Output
array
Parameters
None
Example
callAPI('GET','/users/account_info');
Get paginated list of users
API Path
/settings/users
Description
Retrieve a paginated list of users
GUI Location
Menu
> Settings > Users and Groups > Users
Output
array
386
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
Format
Default
Valid Inputs
page
integer
1
1–<n>
Page to retrieve; first page is 1
limit
integer
25
1–100
Number of items per page
sort
string
name
name | email | id
desc
string
asc
asc | desc
Boolean,
integer
false
false | <user_id>
userId
getAuth
getGroups
filter
Boolean
false
false | true
Description
Sort-by field
Sort direction
n
User ID — Return a specific user; run
this API once with userId=false to obtain
values
n
False — Return all users
n
False — Only get failed authorization
attempts
n
True — Get all authorization settings,
including lockout interval, failure limit,
last attempt
Boolean
false
true | false
Get group membership
string
—
<UTF-8
characters>
Filter for group names
Example
callAPI('GET','/settings/users',
array(
'page' => 2,
'limit' => 20,
'sort' => 'id',
'direction' => 'desc',
'userId' => 5,
'getAuth' => 'true',
'getGroups' => 'true'
)
);
Get logged-in user account preferences
API Path
/users/setting/<setting>
Description
Retrieve preference settings for the logged-in user
387
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
n
[Account Name]
> Preferences
n
[Account Name]
> Account Settings
Output
string | integer
Parameters
REQ
Format
Default
Valid Inputs
X
string
—
unit_network | pagination_
limit | language | totp |
mime_type_view | api_time_
prefix | api_time_postfix |
dark
setting
Description
Settings on the Account Preferences
dialog
n
totp — Time-based one-time
password.
Example
callAPI('GET','/users/setting/unit_network');
Get default group
API Path
/settings/group_default
Description
Retrieve the name of the default user group
GUI Location
Menu
> Settings > Users and Groups
Parameters
REQ
remote
Format
Default
Valid Inputs
Description
Boolean
false
true | false
CMC only True — Retrieve default remote
group
Example
callAPI('GET','/settings/group_default',
array(
'remote' => true
)
);
Output
388
Security Analytics Reference Guide
Security Analytics 8.1
{'errors': [],
'messages': [],
'paging': [],
'result': {'groupname': 'user', 'id': 2},
'resultCode': 'API_SUCCESS_CODE',
'validationErrors': {'Group': [], 'Meta': [], 'res': []}}
Get groups
API Path
/settings/groups
Description
Retrieve a paginated list of groups
GUI Location
Menu
> Settings > Users and Groups > Groups
Output
array
Parameters
REQ
Format
Default
Valid Inputs
Description
page
mixed
1
1–<n>
Page to retrieve; first page is 1
limit
mixed
25
1–100
Number of items per page
sort
string
groupname
desc
string
asc
asc | desc
getPermissions
Boolean
false
true | false
True — Include permissions
getUsers
Boolean
false
true | false
True — Include users
remote
Boolean
false
true | false
CMC only True — Include remote
groups
filter
string
—
<UTF-8 characters>
groupname | id |
Sort-by field
description | default
| remote
Example
callAPI('GET','/settings/groups',
array(
'page' => '2',
'limit' => '20',
'sort' => 'groupname',
'desc' => 'desc',
'getPermissions' => true,
'getUsers' => true,
'remote' => true,
'filter' => 'audit'
389
Sort direction
Filter for group names
Security Analytics Reference Guide
Security Analytics 8.1
)
);
Get user group permissions
API Path
/settings/permission_tree
Description
Retrieve a list of all possible permissions
GUI Location
Menu
> Settings > Users and Groups > Groups
Output
array
Parameters
None
Example
callAPI('GET','/settings/permission_tree');
Get LDAP groups
API Path
/settings/list_ldap_groups
Description
Retrieve a list of LDAP (external) group names; valid only when an LDAP server has been configured and
activated
GUI Location
Menu
> Settings > Users and Groups > Groups > LDAP Groups column
Output
array
Parameters
REQ
search
Format
Default
Valid Inputs
string
—
<UTF-8 characters>
390
Description
LDAP group name to search
Security Analytics Reference Guide
Security Analytics 8.1
Example
callAPI('GET','/settings/list_ldap_groups');
Configure per-user password aging
API Path
/settings/edit_user_chage/<id>
Description
Configure password aging for a user
GUI Location
Menu
> Settings > Users and Groups > [add/edit user account]
Output
integer
Parameters
REQ
Format
Default
Valid Inputs
id
X
integer
—
<GET: /users/account_
info>
passwordAging
X
integer
0
0 | 7 | 14 | 30 | 60 | 90 |
120 | 365
Example
callAPI('POST','/settings/edit_user_chage/33'
array(
'passwordAging' => 90
)
);
Generate current user's API key
API Path
/users/generate_api_key
Description
Generate a new API key for the current user and overwrite any previous key
GUI Location
[Account Name]
> Account Settings > Reset API Key
391
Description
User ID
Number of days before the user
must change the password
Security Analytics Reference Guide
Security Analytics 8.1
Output
string
Parameters
None
Example
callAPI('POST','/users/generate_api_key');
Set user information
API Path
/users/account_info
Description
Set the display name and email address for the logged-in user
GUI Location
[Account Name]
> Account Settings
Output
ApiResultCode
Parameters
REQ
Format
Default
Valid Inputs
X
string
—
<GET: /users/account_info>
The display name for the current user
string
—
<username>@<domain>.<tld>
Associated email address
name
email
Description
Example
callAPI('POST','/users/account_info
array(
'name' => 'LDAP_admin',
'email' => 'LDAPadmin@domain.com'
)
);
Edit a current-user preference — MODIFIED
API Path
/users/setting/<setting>
Description
Edit one account preference for the logged-in user
392
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
[Account Name]
> Preferences
Output
ApiResultCode
Parameters
REQ
Format
Default
Valid Inputs
setting
X
string
—
<GET:
/users/setting/<setting>>
value
X
array
—
Name of the setting
Value for setting; array contains
one value only, from the
parameters below
unit_
network
string
b | B | p
pagination_
limit
integer
5 | 10 | 15 | 20 | 25 | 50 | 75 |
100
language
string
eng | fra | jpn | kor
totp
string
<QR code> | ' '
dark
Description
Unit of measurement to display in
results tables.
b — Bits
B — Bytes
p — Packets
Number of entries per page
Language for the web UI
Time-based one-time password to
synchronize with Google
Authenticator.
n
' ' (space) — Disable 2FA
n
<QR code> — Enable 2FA
Boolean
true | false
mime_type_
view
string
magic | mime | derived
api_time_
prefix
integer
0–<n>
The number of seconds that will be
subtracted from a single timevalue in an API path to calculate the
start time
api_time_
postfix
integer
0–<n>
The number of seconds that will be
added to a single time-value in an
API path to calculate the end time
Example
callAPI('POST','/users/setting/unit_network',
array(
'value' => 'p'
393
True — Display the web UI in dark
mode (new)
Specify how the file type is
displayed in the Type column on
the Extractions page.
Security Analytics Reference Guide
Security Analytics 8.1
)
);
Change current-user password
API Path
/users/change_password
Description
Change the password of the logged-in user
GUI Location
[Account Name]
> Account Settings > Change Password
Output
ApiResultCode
Parameters
REQ
Format
Default
Valid Inputs
oldPw
X
string
—
<current password>
Old password
newPw
X
string
—
<current password requirements>
New password
confirmPw
X
string
—
<identical to newPw>
Example
callAPI('POST','/settings/change_password',
array(
'oldPw' => '55geT!meIn&*',
'newPw' => '23leT!meoUt&*',
'confirmPw' => '23leT!meoUt&*'
)
);
Create a user group
API Path
/settings/create_group
Description
Create a new user group and set the permissions
GUI Location
Menu
> Settings > Users and Groups > Groups > Tools > New
394
Description
New password again
Security Analytics Reference Guide
Security Analytics 8.1
Output
integer
Parameters
REQ
name
Format Default
Valid Inputs
Description
string
—
<UTF-8 characters>
Name for
the group
string
—
<UTF-8 characters>
Description
of the group
default
Boolean
false
true | false
deepsee
array
—
<primary_filter>
Data-access
control filter
permissions
array
—
<GET: /settings/permission_tree>
Group
permission
attributes;
the attribute
must begin
with a
forward
slash ( / )
users
array
—
<GET: /settings/users>
Users to
assign to the
group
externalGroups
array
—
<GET: /settings/list_ldap_groups>
Boolean
false
true | false
string
—
<GET: /cmc_settings/appliances>
description
remote
cmcCheck
X
Example
callAPI('POST','/settings/create_group',
array(
'name' => 'LDAP_auditors',
'description' => 'Auditors in LDAP groups',
'default' => 'false',
395
True —
Make
default
group
External
(LDAP)
group
names to
map to this
group
CMC only.
Valid only if
remote=true
; array of
remote
group name
CMC only.
Sensor key
Security Analytics Reference Guide
Security Analytics 8.1
'deepsee' => array(
'application_group=authentication'
),
'permissions' => array(
'/settings/ldap' => true,
'/logs' => true
),
'users' => array(
'ldap_user_1',
'ldap_user_2',
'admin'
),
'externalGroups' => array(
'auditors',
'admins'
),
'remote' => true
)
);
Create a new user
API Path
/settings/create_user
Description
Create a new local user
GUI Location
Menu
> Settings > Users and Groups > Users > Tools > New
Output
ApiResultCode
Parameters
REQ
Format
Default
Valid Inputs
username
X
string
—
<UTF-8 characters>
Username
password
X
string
—
<current password
requirements>
Password
name
string
—
<UTF-8 characters>
Display name
email
email
—
<username>
@<domain>.<tld>
396
Description
Email that is associated with the account
Security Analytics Reference Guide
REQ
groups
remote
remoteGroups
Security Analytics 8.1
Format
Default
Valid Inputs
array
—
<GET: /settings/groups>
Boolean
false
true | false
array
—
<GET: /settings/groups>
Example
callAPI('POST','/settings/create_user',
array(
'username' => 'ursula_user',
'password' => 'changeMEnow12#$',
'name' => 'Ursula User',
'email' => 'ursulau@domain.com',
'groups' => array(
'user',
'auditor'
),
'remote' => true,
'remoteGroups' => array(
'user',
'auditor'
)
)
);
Assign LDAP groups to current user
API Path
/settings/auto_assign_groups
Description
Retrieve LDAP groups for the logged-in user, if the user is not local
397
Description
Array of group designators
n
user
n
admin
n
auditor
n
security_admin
n
< user-defined group>
CMC only True — Groups are remote
groups
CMC only. Valid only if remote=true;
array of remote group names
n
user
n
admin
n
auditor
n
security_admin
n
<user-defined group>
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
Menu
> Settings > Authentication
Output
ApiResultCode
Parameters
None
Example
callAPI('POST','/settings/auto_assign_groups');
Delete user groups
API Path
/settings/delete_group/<ids>
Description
Delete one or more user groups
GUI Location
Menu
> Settings > Users and Groups > Groups > [delete group]
Output
ApiResultCode
Parameters
REQ
Format
Default
Valid Inputs
X
integer
—
<GET:
/settings/groups>
Boolean
false
true | false
ids
remote
Description
Comma-delimited IDs of the groups
n
True — CMC Only. Remote group
n False — Local group
This value must be the same for all
groups to be deleted; in other words, all
groups to delete must be either local or
remote
Example
callAPI('POST','/settings/delete_group/<id1>,<id2>,<id3>',
array(
'remote' => true
)
);
398
Security Analytics Reference Guide
Security Analytics 8.1
Delete users
API Path
/settings/delete_user/<ids>
Description
Delete one or more users
GUI Location
Menu
> Settings > Users and Groups > Users > [delete users]
Output
ApiResultCode
Parameters
ids
REQ
Format
Default
Valid Inputs
X
integer
—
<GET: /settings/users>
Example
callAPI('POST','/settings/delete_user/<id1>,<id2>,<id3>');
Disable a user account
API Path
/settings/disable_user/<id>
Description
Disable a user account
GUI Location
n
Menu
> Settings > Users and Groups > Users > [edit user]
n
[Unsuccessful login attempts exceeded]
Output
ApiResultCode
399
Description
Comma-delimited IDs of the user
accounts
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
Format
Default
Valid Inputs
X
integer
—
<GET: /settings/users>
Boolean
true
true | false
id
disable
Description
ID of the user account
True — Disable
Example
callAPI('POST','/settings/disable_user/<id>',
array(
'disable' => true
)
);
Edit a user group
For this API, all unspecified fields will reset to default (null, false); therefore, it is
recommended that you include a value for all fields during an edit to avoid losing
permissions or other essential characteristics.
API Path
/settings/edit_group/<id>
Description
Edit an existing user group
GUI Location
n
Menu
> Settings > Users and Groups > Groups > [edit group]
n
CMC Only. Menu
> Settings > Users and Groups > Remote Groups > [edit group]
Output
ApiResultCode
Parameters
REQ
Format
Default
Valid Inputs
id
X
integer
—
<GET: /settings/groups>
Group ID
name
X
string
—
<UTF-8 characters> |
<GET: /settings/groups>
Name for the group; required both
to create and to edit group
string
null
<UTF-8 characters>
default
Boolean
false
true | false
True — Set as default group
deepsee
array
null
<primary_filter>
New primary filter attributes
description
400
Description
Description for the group
Security Analytics Reference Guide
REQ
Security Analytics 8.1
Format
Default
Valid Inputs
Description
permissions
array
null
users
array
null
<GET: /settings/users>
remote
Boolean
false
true | false
CMC only True — Groups are
remote groups
externalGroups
array
null
<GET: /settings/groups>
CMC only. Valid only if
remote=true; array of remote
group name
cmcCheck
string
null
<GET: /cmc_
settings/appliances>
<
New permissions
GET: /settings/permission_
tree>
New user list for the group
CMC only. Sensor key
Example
callAPI('POST','/settings/edit_group/5',
array(
'name' => 'LDAP_users_2',
'description' => 'Second tier of LDAP users',
'default' => true,
'deepsee' => array(
'application_group=authentication
'),
'permissions' => array(
'ldap' => true,
'logs' => true
),
'users' => array(
'ldap_user_500',
'ldap_user_501',
'admin
'),
'remote' => true,
'externalGroups' => array(
'auditors',
'admins'
),
'cmcCheck' => 'B603guSqEJM6pOrq90gJjIjcOKcyn8Jv9BJ1zHYHi5KlOFNmjD'
)
);
Edit a user by user ID
For this API, all unspecified fields will reset to default (null, false); therefore, it is
recommended that you include a value for all fields during an edit to avoid losing
permissions or other essential characteristics.
API Path
/settings/edit_user/<id>
401
Security Analytics Reference Guide
Security Analytics 8.1
Description
Find an account by user ID and then edit its settings
GUI Location
Menu
> Settings > Users and Groups > Users > [edit user]
Output
ApiResultCode
Parameters
REQ
Format
Default
Valid Inputs
X
integer
null
<GET: /settings/users>
username
string
null
<UTF-8 characters>
New username
password
string
null
<current password
requirements>
New password
name
string
null
<UTF-8 characters>
New display name
email
email
null
<username>@<domain>.<tld>
New email address
groups
array
null
<GET: /settings/groups>
remote
Boolean
false
true | false
array
null
<GET: /settings/groups>
id
remoteGroups
Description
User ID
Array of new group names
CMC only True — Groups are remote
groups
CMC only. Valid only if remote=true;
array of remote group name
Example
callAPI('POST','/settings/edit_user/337',
array(
'username' => 'newusername337',
'password' => 'newpassword337',
'name' => 'newdisplayname337',
'email' => 'newemail337@domain.com',
'groups' => 'user',
'remoteGroups' => 'user'
)
);
Edit a user by username
For this API, all unspecified fields will reset to default (null, false); therefore, it is
recommended that you include a value for all fields during an edit to avoid losing
permissions or other essential characteristics.
402
Security Analytics Reference Guide
Security Analytics 8.1
API Path
/settings/edit_user_by_username
Description
Find an account by username and then edit its settings
GUI Location
Menu
> Settings > Users and Groups > Users > [edit user]
Output
ApiResultCode
Parameters
REQ
Format
Default
X
string
null
name
string
null
<UTF-8 characters>
New display name
email
email
null
<username>
@<domain>.<tld>
New email account
groups
array
null
remote
Boolean
false
true | false
CMC only True — Groups are
remote groups
array
null
<GET:
/settings/groups>
CMC only. Valid only if
remote=true; array of remote
group name
username
remoteGroups
Valid Inputs
Description
<GET: /settings/users> Username of the account
<
Array of new group names
GET: /settings/groups>
Example
callAPI('POST','/settings/edit_user_by_username',
array(
'username' => 'ursula_user',
'name' => 'ursula_user_00',
'email' => 'ursula@domain.com',
'groups' => 'user',
'remoteGroups' => 'user'
)
);
Change user password
API Path
/settings/edit_user_password/<id>
403
Security Analytics Reference Guide
Security Analytics 8.1
Description
Change a user's password
GUI Location
Menu
> Settings > Users and Groups > Users > [edit user]
Output
ApiResultCode
Parameters
REQ
Format
Default
Valid Inputs
id
X
integer
—
<GET: /settings/users>
password
X
string
—
<current password requirements>
Example
callAPI('POST','/settings/edit_user_password/337',
array(
'password' => '3030rootMEouT#$#'
)
);
404
Description
User ID
New password
Security Analytics Reference Guide
Security Analytics 8.1
Web Interface Settings APIs
Get allowed hosts — NEW
API Path
/web_interface/allowed_hosts
Description
Retrieve a list of the alternative hostnames for the appliance.
GUI Location
Menu
> Settings > Web Interface
Parameters
None
PHP Example
callAPI('GET','/web_interface/allowed_hosts');
Python Example
s.callAPI("GET","/web_interface/allowed_hosts")
Output
{'errors': [],
'messages': [],
'paging': [],
'result': ['<host1>', '<host2>', '<host3>'],
'resultCode': 'API_SUCCESS_CODE',
'validationErrors': {'AllowedHost': [], 'Meta': [], 'res': []}}
Get appliance configuration
API Path
/config
Description
Retrieve the information for the appliance, such as build number, license, model
GUI Location
About
Output
JSON
Parameters
None
405
Security Analytics Reference Guide
Security Analytics 8.1
Example
callAPI('GET','/config');
Get web UI idle timeout
API Path
/web_interface/web_timeout
Description
Retrieve the automatic idle timeout for the web UI
GUI Location
Menu
> Settings > Web Interface
Output
integer
Parameters
None
Example
callAPI('GET','/web_interface/web_timeout');
Get external preview state
API Path
/web_interface/external_preview
Description
Retrieve the Enable External HTML Elements Preview state
GUI Location
Menu
> Settings > Web Interface
Output
Boolean
Parameters
None
Example
callAPI('GET','/web_interface/external_preview');
406
Security Analytics Reference Guide
Security Analytics 8.1
Get usage-tracking state
API Path
/web_interface/usage_tracking
Description
Retrieve the usage-tracking state
GUI Location
Menu
> Settings > Web Interface (not valid for beta versions)
Output
Boolean
Parameters
None
Example
callAPI('GET','/web_interface/usage_tracking');
Get message of the day
API Path
/web_interface/motd
Description
Retrieve the message of the day
GUI Location
Menu
> Settings > Web Interface
Output
string
Parameters
None
Example
callAPI('GET','/web_interface/motd');
407
Security Analytics Reference Guide
Security Analytics 8.1
Get Universal Connector state
API Path
/web_interface/uc_allow
Description
Retrieve the Universal Connector state
GUI Location
Menu
> Settings > Web Interface
Output
Boolean
Parameters
None
Example
callAPI('GET','/web_interface/uc_allow');
Get referrers
API Path
/web_interface/referers
Description
Retrieve the list of referrers
GUI Location
Menu
> Settings > Web Interface
Output
array
Parameters
None
Example
callAPI('GET','/web_interface/referers');
408
Security Analytics Reference Guide
Security Analytics 8.1
Set allowed hosts — NEW
API Path
/web_interface/allowed_hosts
Description
Add allowed hostnames for the appliance.
GUI Location
Menu
> Settings > Web Interface
Parameters
None
Python Example
s.callAPI('POST', '/web_interface/allowed_hosts', {
"hosts": {
["<host1>", "<host2>"]
}
})
Output
{
"result": true,
"errors": [],
"messages": [
"Allowed Hosts settings saved successfully."
],
"validationErrors": {
"res": [],
"AllowedHost": [],
"Meta": []
},
"paging": [],
"resultCode": "API_SUCCESS_CODE"
}
Set web UI idle timeout
API Path
/web_interface/web_timeout
Description
Set the time for automatic idle timeout
GUI Location
Menu
> Settings > Web Interface
Output
Boolean
409
Security Analytics Reference Guide
Security Analytics 8.1
Parameters
REQ
Format
Default
Valid Inputs
X
integer
—
5 | 10 | 30 | 60 | 120 | 240 | 480 | 1440 |
4320 | 7200 | 10080
timeout
Description
Timeout in minutes
Example
callAPI('POST','/web_interface/web_timeout'
array(
'timeout' => 4320
)
);
Set external preview state
API Path
/web_interface/external_preview
Description
Toggle the external HTML preview setting
GUI Location
Menu
> Settings > Web Interface
Output
Boolean
Parameters
REQ
externalPreview
X
Format Default
Valid Inputs
Description
Boolean
true | false
True — External preview enabled
—
Example
callAPI('POST','/web_interface/external_preview'
atray(
'externalPreview' => false
)
);
Set usage tracking state
API Path
/web_interface/usage_tracking
Description
Toggle the usage-tracking state
410
Security Analytics Reference Guide
Security Analytics 8.1
GUI Location
Menu
> Settings > Web Interface (not valid for beta versions)
Output
Boolean
Parameters
usageTracking
REQ
Format
Default
Valid Inputs
Description
X
Boolean
—
true | false
True — Enable usage tracking
Example
callAPI('POST','/web_interface/usage_tracking'
array(
'usageTracking' => false
)
);
Edit Message of the Day
API Path
/web_interface/motd
Description
Create or edit the Message of the Day
GUI Location
Menu
> Settings > Web Interface
Output
Boolean
Parameters
REQ
Format
Default
Valid Inputs
X
string
—
<UTF-8 characters>
motd
Description
Example
callAPI('POST','/web_interface/motd'
array(
'motd' => 'Hello world'
)
);
411
Message of the day
Security Analytics Reference Guide
Security Analytics 8.1
Set Universal Connector state
API Path
/web_interface/uc_allow
Description
Sets whether to allow the Universal Connector bookmarklet referrer exception (dls.soleranetworks.com)
GUI Location
Menu
> Settings > Web Interface
Output
Boolean
Parameters
REQ
Format
Default
Valid Inputs
Description
X
Boolean
—
true | false
True — Allow Universal Connector
allow
Example
callAPI('POST','/web_interface/'
array(
'allow' => true
)
);
Edit referrers list
API Path
/web_interface/referers
Description
Edit the list of referrers
GUI Location
Menu
> Settings > Web Interface
Output
Boolean
Parameters
referers
REQ
Format
Default
Valid Inputs
X
array
—
<domain.tld> | <dotteddecimal>
412
Description
Comma-delimited list of devices that are allowed
to refer to the appliance
Security Analytics Reference Guide
Security Analytics 8.1
Example
callAPI('POST','/web_interface/referers'
array(
'upgrades.soleranetworks.com',
'203.0.113.5'
)
);
Restart the internal web server
API Path
/system/restart_apache
Description
Restart the web server after active processes have finished
GUI Location
n/a
Output
ApiResultCode
Parameters
None
Example
callAPI('POST','/system/restart_apache');
413
Security Analytics Reference Guide
Security Analytics 8.1
API Appendix
414
Security Analytics Reference Guide
Security Analytics 8.1
Using Polling with the APIs
Some APIs do not return data immediately because they launch a process that takes more than a few seconds to
run. Instead, you must poll the appliance to retrieve the data.
The APIs for which you should use polling are:
n
GET: /deepsee_reports/report
n
GET: /artifacts/artifacts
For these APIs the initial run of the API starts the report or extraction, and then you should continue to run the
same API every several seconds — with all of the same parameters (timespan, filters) — to retrieve data
incrementally as the report or extraction progresses. When state has reached one of the final states — stopped,
stopping, error, or complete — there is no more data to retrieve, and so you can stop polling.
The stopped, stopping, and error states indicate that the process has stopped running, but the process may not
have finished processing all of the data for the timespan.
n
To restart a report, first run POST: /report_daemons/stop, run POST: /report_daemons/delete, and
then run the same API as before.
n
To restart an extraction, first run POST: /artifacts/stop, run POST: /artifacts/delete, and then run
the same API as before.
Symantec recommends that you not use the percent_complete or percentage
parameters to determine when a report or extraction has finished. The state
parameter is the definitive metric for tracking the process state.
Syntax: Identity Path
Choose one of the following identity-path formats:
Source
Format Description
<
enhanced primary filter
>
array
Timespan plus the JSON equivalent of a Primary Filter;
supports operators. This identity path permits you to
select the report to run on the Reports Page.
<existing item ID>
string
Available only after the API has already been run once,
within the last couple of minutes.
These values are mutually exclusive.
Syntax: Enhanced Primary Filter Array
This array type returns the data from the Reports page on Menu
> Analyze > Summary > Reports. (For the
Geolocation page see the Geolocation Report example for /deepsee_reports/report).
415
Security Analytics Reference Guide
Security Analytics 8.1
See "Advanced API Queries" on page 77 to create complex primary filters. You can also use this array for an
extraction by omitting the type, field, and sample attributes.
Field
REQ
Default
timespan
X
—
Array consisting of 'start' and 'end' with the
dates specified as <YYYY-MM-DD>T<hh:ii:ss>
[+|-]<zz:zz>
ranked
Type of report; ranked — Reports page; geoip —
Geolocation page
type
query
field
sample
X
Valid Values / Description
—
Array of attribute/value pairs in the primary filter
bar, including operators and using the primary filter
attributes; enclose AttributeOperatorValue in the
same set of quotes: 'filename~executive_
report'
application_id
Report selector for the Reports page; values are the
primary filter attribute names for reports. Omit this
field for an extraction.
100
Session resolution, expressed as a percentage: 1 |
25 | 50 | 75 | 100
PHP
array(
'timespan' => array(
'start' => '2019-11-03T10:00:00+05:00',
'end' => '2019-11-03T10:10:00+05:00'
),
'query' => array(
'port_responder=53',
'dns_name!~internal'
),
'field' => 'tcp_initiator'
)
Python
{
'timespan': {
'start': '2019-11-03T10:00:00+05:00',
'end': '2019-11-03T10:10:00+05:00'
},
'query': [
'port_responder=53',
'dns_name!~internal'
],
'field': 'tcp_initiator'
}
Syntax: Advanced-Filter Array
Use this syntax to specify the equivalent of an Advanced Filter in the UI. (See "Advanced Filters" in the Security
Analytics 8.1.x Administration and Central Manager Guide on support.symantec.com.)
416
Security Analytics Reference Guide
Security Analytics 8.1
Field Valid Values / Description
key Appropriate advanced filter attribute:
Alerts
Click to see values
Anomalies
Click to see values
Analyze > Summary
> Reports
Click to see values
Analyze > Report
Status
Click to see values
Audit Log
Click to see values
Extractions
Geolocation
Click to see values; initiator_X and responder_X
produce the same results
Click to see values
Indicators
indicator
Job Queue
id | status | type
Retrospective Jobs
command (1 — Reindexing, 2 — Reprocessing)
source (1 — Auto, 2 — Manual)
CMC Only. Sensors
label
comp = != ~ !~ > >= < <=
value Any valid value for the corresponding attribute
all Boolean AND
any Boolean OR
The following examples reduced to Boolean logic are ((ip_address=203.0.113.5) && (url~blue ||
url~coat))
Python
[
'all':[
{
'key':'ip_address',
'comp':'=',
'value':'203.0.113.5'
}
{
'any':[
{
'key':'url',
'comp':'~',
'value':'blue'
},
{
417
Security Analytics Reference Guide
Security Analytics 8.1
'key':'url',
'comp':'~',
'value':'coat'
}
]
}
]
]
PHP
array(
'all' => array(
array(
'key' => 'ip_address',
'comp' => '=',
'value' => '203.0.113.5'
)
array(
'any' => array(
array(
'key' => 'url',
'comp' => '~',
'value' => 'blue'
),
array(
'key' => 'url',
'comp' => '~',
'value' => 'coat'
)
)
)
)
)
Syntax: Primary Filter Array
Use this syntax to specify the equivalent of a primary filter in the UI, without the timespan. Consult "Advanced
API Queries" on page 77 to use Boolean AND and OR in the filter.
Field
Description
array Array of attribute/value pairs for the primary filter, including the operators. To specify
an indicator, run GET: /favorites to get the UUID for favorite.
Python
[
'port=8080',
'application_id~http',
'favorite=581cc1a3-b884-4e39-a2f2-67b31e1d64a3'
]
PHP
json_encode(
array(
'port=8080',
'application_id~http',
'favorite=581cc1a3-b884-4e39-a2f2-67b31e1d64a3'
)
)
418
Security Analytics Reference Guide
Security Analytics 8.1
Syntax: Timespan Array
PHP
'timespan' => json_encode(
array(
'start' => '<YYYY-MM-DD>T<hh:ii:ss>[+|-]<zz:zz>',
'end' => '<YYYY-MM-DD>T<hh:ii:ss>[+|-]<zz:zz>'
)
)
Python
'timespan':json.dumps({
{
'start':'<YYYY-MM-DD>T<hh:ii:ss>[+|-]<zz:zz>',
'end':'<YYYY-MM-DD>T<hh:ii:ss>[+|-]<zz:zz>'
}
})
Syntax: Timespan Date Array
Python
{
'startDate':'<YYYY-MM-DD>T<hh:ii:ss>[+|-]<zz:zz>',
'endDate':'<YYYY-MM-DD>T<hh:ii:ss>[+|-]<zz:zz>'
}
PHP
array(
'startDate' => '<YYYY-MM-DD>T<hh:ii:ss>[+|-]<zz:zz>',
'endDate' => '<YYYY-MM-DD>T<hh:ii:ss>[+|-]<zz:zz>'
)
Syntax: Geolocation Internal Labels
PHP
array(
'ip_cidr' => '<ip>/<mask>',
'long' => <float>,
'lat' => <float>,
'label' => '<string>'
)
Python
{
'ip_cidr':'<ip>/<mask>',
'long':<float>,
'lat':<float>,
'label':'<string>'
}
Syntax: Scheduled Events
Specify only one value for the array. Valid values depend on the value of frequency.
$frequency
Valid Values
Format
Definition
daily
daily
single-value array
Every day
419
Security Analytics Reference Guide
Security Analytics 8.1
$frequency
Valid Values
Format
Definition
weekly
Mon | Tue | Wed | Thu |
Fri | Sat | Sun
single-value array
Specify the day of the week
monthly
[01–31] | [1st | 2nd |
3rd | 4th | last][weekday | weekend_day |
Mon | Tue | Wed | Thu |
Fri | Sat | Sun]
single-value array
Specify one of the following:
hour
00–23
single-value array
Numerical hour
minute
00–59
single-value array
Numerical minute
once
<YYYY-MM-DD>T<hh:ii:ss>
single-value array
Date/time
custom
array(<MMM>-<ordinal><DDD>,<MMM>-<ordinal><DDD>)
multiple-value array
n
n
numerical day of month: 06 for
the 6th
ordinal plus day: 2nd-Tue, 3rdweekday, last-Sun
Irregular dates: Feb-2nd-Thu , Jullast-Fri , Oct-3rd-Mon
LDAP Schema Values
These attributes are valid for the schema field of the POST: /settings/ldap API. To see further explanations of
the attributes, see Specify Mapped LDAP Schema in the Security Analytics 8.1.x Administration and Central
Manager Guide on support.symantec.com.
Atrribute
Schema Name
inetorgperson InetOrgPerson
mad
madrfc2307
Microsoft Active Directory
Microsoft Active Directory (RFC 2307)
msu20
Microsoft Services for Unix 2.0
msu35
Microsoft Services for Unix 3.5
rfc2307
rfc2307bis
user_defined
RFC 2307 Network Information Service
RFC 2307bis Network Information
Service
User Defined
These attributes are valid for the array in the schema field of the POST: /settings/ldap API. To see futher
explanations of the attributes, see Define a New LDAP Schema in the Security Analytics 8.1.x Administration and
Central Manager Guide on support.symantec.com.
Attribute
user_object_
class
REQ
Format
Default
string
—
Valid Inputs
UI Label
User Object
Class
420
Security Analytics Reference Guide
Attribute
REQ
Security Analytics 8.1
Format
Default
login_name
string
—
Login Name
Attribute
gecos
string
—
Full Name
(GECOS)
Attribute
user_password
string
—
User
Password
Attribute
string
—
pam_password_
change
Valid Inputs
ad
clear
clear_
remove_old
crypt
exop
exop_send_
old
UI Label
ADSI
Cleartext
Cleartext, remove old pw
first
Crypt
RFC 3062
RFC 3062 (send old and
new pw)
md5
MD5
nds
Novell NDS
racf
Password
Change
Method
®
IBM RACF
uid_number
X
integer
—
User ID
Number
Attribute
home_directory
X
string
—
Home
Directory
Attribute
login_shell
string
—
User Shell
Attribute
group_object_
class
string
—
Group
Object Class
integer
—
Group ID
Number
Attribute
string
—
Group
Membership
Attribute
gid_number
pam_member
X
421
Security Analytics Reference Guide
Attribute
REQ
Security Analytics 8.1
Format
Default
string
—
rfc_mode
Valid Inputs
UI Label
rfc2307
rfc2307bis
Menu
UID
Distinguished Name
Group
Membership
Type
> Analyze > Alerts > Summary
Specify alert groups as follows:
appliance
cached
description
destination_ip
destination_mac
destination_port
endpoint_providers
Menu
importance
integration_provider
match_criteria
name
indicator
rule
result
score
source_ip
source_mac
source_port
type
> Analyze > Anomalies > Summary
Specify anomaly groups as follows:
applications
country
initiator_ip
responder_ip
url_categories
Capture Summaries Inputs
See the View menu on Menu
> Capture for details.
cpu
CPU usage
qfto
Flow-table overflow
ram
RAM usage
impt
PCAP imports
fts
Flow table size
nt
s_spsd
All capture interfaces, aggregated
DPI threads
ethX
Ethernet interface
Slot overflow
ifbX
Accolade interface
tmf
Cumulative flow maximum
qfc
Flows in progress
qsd
Slots in use
qp
aggregate
Packets in progress
uxqueued
uxprocd
®
File analysis jobs in progress
Processed file analysis
uxmaxqueue
File analysis queue discards
uxmaxslrg
File analysis range discards
422
Security Analytics Reference Guide
qnf
Flows initiated
Security Analytics 8.1
uxnotlive
uxprobes
423
File analysis slot discards
File analysis requests
Security Analytics Reference Guide
Security Analytics 8.1
Using the APIs
Consult this page for information on how to use the APIs to perform specific tasks.
This page contains examples in Python only. To request that a task sequence be
added to this page or that a PHP example be provided, send an email to
documentation_inbox@symantec.com with "Security Analytics API Examples" in the
subject line.
Best Practices
n
Review Best Searching Practices, Flows in Security Analytics, and Detecting File Types in the Security
Analytics 8.1.x Administration and Central Manager Guide on support.symantec.com to see how to create
the narrowest possible filters so that system resources are not expended in extracting unwanted artifacts.
n
Because the APIs refer to web UI functions, you can test the sequence of events that is required to
perform the desired task in the web UI first, before creating the API sequence. The GUI Location field in
the API documentation shows where the web UI calls the API:
API Path
/report_daemons/summary_data
Description
Retrieve the report status summary
GUI Location
Menu
> Analyze > Report Status > Summary
Downloading Extracted Artifacts
This example shows how to download the artifacts that are produced by an extraction session.
Download All Suspected Executables from OFAC Countries
During a One-Minute Timespan
The equivalent tasks on the web UI for this example would be:
n
manually editing the timespan filter to the desired span
n
putting two indicators in the primary filter bar
n
running the extraction
424
Security Analytics Reference Guide
Security Analytics 8.1
n
applying advanced filters to the results
n
selecting artifacts of interest
n
downloading the artifacts as a single ZIP archive
This example will isolate the suspected executables from the other artifacts on the appliance by:
n
Applying the timespan filter — The timespan filter will be set to one minute to avoid excessively long
extraction times. Artifacts outside the timespan will not be extracted.
n
Applying the indicators as primary filters — Existing indicators will be used as primary filters, which
produces only the flows that contain values that match the indicators.
n
Applying advanced filters — Advanced filters isolate specific artifacts in the matching flows.
Step 1: Retrieve the UUIDs for the Indicators
This example assumes that these indicators exist on the appliance:
n
The preloaded indicator Countries - OFAC, containing country="X" filters for countries that are sanctioned
by the Office of Foreign Assets Control (US Treasury).
n
A custom indicator called PE File Type, containing the filter file_type="PE (exe)". This indicator detects
executables by examining the file signature/magic number.
Run GET: /favorites API
This API is the equivalent of applying two advanced filters with the OR operator on the Analyze > Indicators page.
("Favorite" is the internal name for "indicator.")
pprint.pprint(
s.callAPI(
"GET","/favorites", {
'filters':
{
'any':
[
{
'key': 'indicator',
'comp': '~',
'value': 'ofac'
},
{
'key': 'indicator',
'comp': '=',
'value': '"PE File Type"'
}
]
}
}
425
Security Analytics Reference Guide
Security Analytics 8.1
)
)
Results
The desired data is in the uuid field for each indicator.
{'errors': [],
'messages': [],
...
'result': {'pageCount': 1,
'results':
[{'active': True,
...
'uuid': '59baf513-a2a4-4ff3-9182-061c1e1d64a3',
},
{'active': True,
...
'uuid': '59baf513-356c-4605-a533-061c1e1d64a3',
Step 2: Apply Filters and Initiate the Extraction
For this iteration the timespan filter will be set to one minute, the indicators will filter out all flows that do not
match the indicator values, and the advanced filters limit the artifacts that are returned to those that have the
specified attributes.
Run GET: /artifacts/artifacts API
This API is the equivalent of narrowing the timespan to one minute on Analyze > Summary > Extractions, applying
two indicators as primary filters with the OR operator, and applying three advanced filters with the AND
operator. In this example, the advanced filters eliminate zero-byte artifacts, file chunks, and artifacts that do not
have "application" in the artifact's file_type field.
pprint.pprint(
s.callAPI(
"GET", "/artifacts/artifacts", {
'identityPath': {
'timespan': {
'start': '2019-11-03T10:00:00',
'end': '2019-11-03T10:01:00'
},
'query': [
'favorite=59baf513-a2a4-4ff3-9182-061c1e1d64a3',
'favorite=59baf513-356c-4605-a533-061c1e1d64a3'
],
},
'filters': {
'all': [
{
426
Security Analytics Reference Guide
Security Analytics 8.1
'key': 'file_size',
'comp': '!=',
'value': 0
},
{
'key': 'file_type',
'comp': '~',
'value': 'application'
},
{
'key': 'file_extension',
'comp': '!=',
'value': 'part'
}
]
}
}
)
)
Results
The desired data is in the artifact_search_id field. Notice that state shows new.
{'errors': [],
'messages': [],
'paging': [],
'result': {'applianceStatuses': [],
...
'status': {'artifact_search_id': 62,
...
'state': 'new'}
Step 3: Poll the Appliance until the Extraction Is Finished
The GET: /artifacts/artifacts API does not produce artifacts after the first request; instead, you must poll the
appliance every few seconds to retrieve the data incrementally, as the extractions are performed. To poll the
appliance, send the same API call as you sent the first time.
If you change any item in identityPath from the original API call, you will initiate a
new extraction instead of retrieving the artifacts from the initial request.
When state equals one of the final states (stopping, stopped, error, complete), the extraction process has
finished. Do not use percent_complete or percentage to determine whether the extraction has finished.
427
Security Analytics Reference Guide
Security Analytics 8.1
After an extraction has finished, it remains in cache for six hours.
Step 4: Obtain the Artifact IDs
When the extraction has finished, examine the results from the final API call. The desired information is in the id
field for each artifact.
'result': {'applianceStatuses': [],
...
'sorted_artifacts': [{'active': False,
...
'id': 1483520,
Step 5: Download the Artifacts
Now that you have the artifact IDs, you can download them from the appliance. In this example, seven artifact
IDs were returned, and all of them will be downloaded as a single archive called artifacts.zip.
Run GET: /artifacts/download
This API is the equivalent of selecting artifact check boxes on Analyze > Summary > Extractions and clicking
Download Artifacts. This example uses the search ID as the identityPath. Alternatively, you can use the
identical identityPath values (timespan, primary filters) as in the original API call.
pprint.pprint(
s.callAPI('GET', '/artifacts/download', {
'searchId': 62,
'ids': [1483520, 1483529, 1483537, 1483555, 1483564, 1483675, 1483701]
}, 'artifacts.zip'
)
)
Result
The file is downloaded to the directory where the API call resides.
{'download_file': 'artifacts.zip', 'filesize': 1911630}
Process finished with exit code 0
Downloading PCAPs
This example shows how to download the PCAPs of selected flows.
428
Security Analytics Reference Guide
Security Analytics 8.1
Download PCAPs of All Flows that Contain URLs that Score 9
or 10 from the Web Reputation Service
This example demonstrates how to use a data-enrichment alert to select which PCAPs to download. The
equivalent tasks on the web UI would be:
n
enabling the Web Reputation Service service and rule
n
setting the advanced filter on the Alerts List page to a 10-minute interval
n
clicking View Report Summary for each alert
n
selecting Actions > Download PCAP on the Summary view
This example will isolate the suspected flows from the other flows by:
n
Enabling the Web Reputation Service rule — The Web Reputation Service rule posts alerts of verdicts
of 7 or higher.
n
Applying filters to the alerts list — Advanced filters for alerts can isolate the alerts from a particular
provider with a particular verdict during a selected timespan.
Step 1: Enable the Web Reputation Service Provider and Rule
If you have not already done so, verify that the Web Reputation Service provider and rule are enabled.
1. On the web UI, select Settings > Data Enrichment.
2. Under Symantec Intelligence Services, enable the Symantec Web Reputation Service.
3. Select Analyze > Rules.
4. Enable the Symantec Web Reputation Service rule.
Step 2: Retrieve a list of alerts during a 10-minute timespan
This example uses a 10-minute timespan for alert retrieval. You should adjust the time interval according to the
volume of Web Reputation Service (WRS) alerts that you get.
Run GET: /alerts
This API is the equivalent of applying two advanced filters with the AND operator as well as setting the timespan.
pprint.pprint(
s.callAPI(
"GET", "/alerts", {
'startDate': '2019-10-02T14:00:00',
'endDate': '2019-10-02T14:10:00',
'filters': {
'all': [
429
Security Analytics Reference Guide
Security Analytics 8.1
{
'key': 'integration_provider',
'comp': '~',
'value': ''
},
{
'key': 'score',
'comp': '>=',
'value': '9'
}
]
}
}
)
)
Results
The desired data is in the flow_id field for each alert. The uuid field contains a unique identifier for each alert,
which you may want to use as the PCAP file name.
'result': {'pageCount': 5,
'rows': [{'action': 'Symantec Web Reputation Service',
...
'flow_id': 28162095,
...
'uuid': '2ac29727-462e-4ca4-a4f8-98b10bf4aba1',
...
{'action': 'Symantec Web Reputation Service',
...
'flow_id': 28162081,
...
'uuid': 'da01fdda-c4f4-4910-9cc7-df4904a6457c',
Step 3: Download the PCAP for Each Alert Flow
The next step is to download the PCAP that corresponds to the flow_id.
Run GET: /pcap/download/deepsee
For each alert hit, download the flow by flow_id, and use the date plus the UUID of the alert as the PCAP file
name. You must include the timespan from the original API call.
s.callAPI(
"GET",
"/pcap/download/deepsee", {
'path': '/timespan/2019-10-02T16:00:00_2019-10-02T16:10:00/flow_id/28162095',
430
Security Analytics Reference Guide
},
Security Analytics 8.1
'download': {
'type': 1,
},
'pcapType': 'pcap'
'2019-10-02_2ac29727-462e-4ca4-a4f8-98b10bf4aba1.pcap'
)
Results
Process finished with exit code 0, and the PCAPs downloaded to the same directory where the API call is located.
431
Security Analytics Reference Guide
Security Analytics 8.1
Resources
Consult these resources for assistance with your Security Analytics implementation:
n
Required Ports, Protocols and Services for Symantec Enterprise Security Products
(https://www.symantec.com/docs/DOC11287)
n
All Security Analytics documentation
(https://support.symantec.com/us/en/documentation.1145515.html)
n
Security Analytics support page (https://support.symantec.com/us/en/product.security-analytics.html)
n
Symantec Support (https://support.symantec.com/us/en/contact-us.html)
432