Overview

The series allows you to automate certain actions and integrate with existing frameworks, applications, and architectures. The API uses the Representational State Transfer (REST) architecture. The overview covers key conventions used throughout the API guide and an example workflow using the RESTful API.

Introduction

Note

Generating master and client certificates is covered in the PX Series User Guide.

Series searches begin by searching the internal connection storage. After identifying connections that match the filter criteria, the Series appliance makes references and extracts packets for each connection. This data is all available using the RESTful API.

Each connection can have one or more packets. The packet list request returns a list of packets holding high-level data. To get more detailed data per individual packet, use the packet detail request.

An overview of the search workflow is detailed on the following pages.

Overview of search workflow

The Series API search workflow is described in the following steps:

1. Launch an advanced search. See Advanced Search Request. For example, to find all TCP activity for a specific workstation with an IP address of xxx.xxx.xxx.xxx, enter the following:

curl -k --user cpx:hammerhead "stime=20131101.000100&window=3000&ip_list=xxx.xxx.xxx.xxx&depth=session" https://xxx.xxx.xxx.xxx/api/4.0/search

1. The Series API returns a search_id, for example, 7b123. To monitor the status of a search with a search_id of 7b123, use the search summary request. See Search Summary Request. For example:

curl -k --user cpx:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/search/7b123/poll

1. When the search is done ("done":true), use the status of advanced search request to see if the data was found. See Status of Advanced Search Request. For example:

curl -k --user cpx:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/search/7b123

1. If the search found connections and packets (output_xpf_foundRecords > 0 && output_packet_foundRecords > 0), use the connection summary request to retrieve connection or packet data or session analysis data. See Connection Summary Request. For example:

curl -k --user cpx:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/results/7b123

1. After the connections are retrieved, you can retrieve the packets for a connection. See Packet List Request. For example, you can use the following request for the first connection:

curl -k --user cpx:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/results/7b123/0

1. After you have a list of packets, use the pindex from one of the packets (3) to view that packetʼs details. See Single Packet Detail Request. For example:

curl -k --user cpx:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/results/7b123/0/3

1. If the search found sessions, use the session information request to retrieve session analysis data. See Session Information Request. For example:

curl -k --user cpx:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/results/7b123/sessions

1. To download your packets, use the download packets request. See Download Packets Request. For example:

curl -k --user cpx:hammerhead -o output.pcap https://xxx.xxx.xxx.xxx/api/4.0/results/7b123/packets

Authentication

To authenticate your API requests, include the user name and password for your Series appliance in the header. For example:

--user cpx:hammerhead

If the request is successful, a cookie is returned in the header that can be used to authenticate future requests.

Conventions

Note

All parameters used in the API are case sensitive.

UTC Format

Use Coordinated Universal Time (UTC) for start time (stime), end time (etime), and so on. Dates can be represented as follows:

• yyyymmdd.hhmmss

For example: etime=20131101.000100 = 1 Nov 2013 12:01:00 GMT

• second epoch

For example: 1458237457 = Thu, 17 Mar 2016 17:57:37 GMT

• nanosecond epoch

For example: 1458237498377 = Thu, 17 Mar 2016 17:58:18 GMT

• now

For example: etime=now

• 0.hhmmss, where 0 represents today

For example: stime=0.000100 = 12:01:00 GMT today

Unless otherwise stated, the Series API displays the unit of time for searches in seconds.

PX RESTful API endpoints

Search

The Series appliance uses a patent-pending tiered search architecture that enables fast searches for network connections and packets over long time periods. You can perform two types of searches:

• Filtered packet searches using a list of IP addresses or XPF fields

• Detailed searches based on numerous filters

Note

Search performance is affected based on capture rates and other searches going on at the same time.

Historical search data are available for a maximum of 48 hours unless they are stored. This time might decrease when the

/flow/tmp filesystem is more than 90% full.

Use the search endpoints to create, cancel, or list searches:

• Packet search request

GET https://<PX_IP_address>/api/4.0/search/stream

• Advanced search request

POST https://<PX_IP_address>/api/4.0/search

• Search within a search request

POST https://<PX_IP_address>/api/4.0/searchinsearch

• Upload PCAP request

POST https://<PX_IP_address>/api/4.0/search/upload

• Historical searches request

GET https://<PX_IP_address>/api/4.0/search/history

• Search summary request

GET https://<PX_IP_address>/api/4.0/search/<search_id>/poll

• Status of advanced search request

GET https://<PX_IP_address>/api/4.0/search/<search_id>

• Session analysis using existing ruleset request

POST https://<PX_IP_address>/api/4.0/search/<search_id>/session-analysis

• Cancel searches request

DELETE https://<PX_IP_address>/api/4.0/search/<search_id>

• List queued searches request

GET https://<PX_IP_address>/api/4.0/queue

• List saved search definitions request

GET https://<PX_IP_address>/api/4.0/user/searches

• Create saved search definitions request

POST https://<PX_IP_address>/api/4.0/user/searches

• Update saved search definitions request

PUT https://<PX_IP_address>/api/4.0/user/searchesa

• Delete saved search definitions request

DELETE https://<PX_IP_address>/api/4.0/user/searches

Packet search request

To search captured data and output a binary stream of packets that can be saved as a file, send the following request:

GET https://<PX_IP_address>/api/4.0/search/stream

Required header:

--user <username>:<password>

This search is performed when this API endpoint is called.

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Query parameters

• stime—Date and time from which the search should start. See Conventions for the format.

• etime—Date and time at which the search should end. See Conventions for the format.

• window—The window of time before and after the specified start time that should be searched. If stime is used as a parameter, the window parameter is divided by two and subtracted from the stime to make a new start time. The window parameter is added to the original stime to make an etime. If stime is not specified, stime defaults to the current time. If etime and window are not specified, etime defaults to stime + 1 second.

• xpf—Filter that supports BPF as defined at http://www.tcpdump.org/manpages/pcap-filter.7.html. It is also used with PX-specific connection attributes, see Connection metadata properties. Sample formatting is host xxx.xxx.xxx.xxx && packetdeltacountin>25. If the xpf parameter is not provided, packets between the start and end time range are returned. If the limit parameter is provided, the limit refers to the number of packets to return and not the number of flow records.

• limit—The maximum number of connections returned. The default connection limit for asynchronous searches is 100.

• strict—If this parameter is set to true, the search ignores extra VLANs and multiprotocol label switching (MPLS) unless you specify them in the xpf parameter. The default value is false.

• ip_list—Comma-separated list of IP addresses to be used as a filter. This parameter is useful for sporadic traffic over a long period of time.

• pgrep—A string. Each packet that matches the xpf parameter is searched by a regex engine for this string.

Example

GET https://xxx.xxx.xxx.xxx/api/4.0/search/stream

Required header:

--user cpx:hammerhead

Packet search response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type]

Content-Disposition: [Content Disposition]

""

Response fields

• Response Code—A standard HTTP response code.

• Response Message—A standard HTTP response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Content Disposition—Name of downloaded file.

Example

HTTP/1.1 200 OK

Date: Wed, 16 Mar 2016 16:07:08 GMT

Content-Type: application/octet-stream; charset=UTF-8

Content-Disposition: attachment; filename = "download_2016160707.pcap"

M>▒▒▒%

cURL code sample: Packet search

The code sample was run with cURL 7.57.0.

curl -k --user cpx:hammerhead "https://xxx.xxx.xxx.xxx/api/4.0/search/ stream?stime=20110901.015959&etime=20110901.030000&xpf=tcp"

This cURL sample includes the following options:

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• --user cpx:hammerhead—Replace cpx with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/search/ stream?stime=20110901.015959&etime=20110901.030000&xpf=tcp—The search request URL. Replace xxx.xxx.xxx.xxx with the IP address of your Series appliance. Replace 20110901.015959 with the start time of the range that you want searched. Replace 20110901.030000 with the end time of the range that you want searched. Replace tcp with the appropriate filter.

Note

Enclose the URL in double quotation marks if it includes special characters such as [, ], {, }, ?, &, and *.

Results

This example searches captured data for a specified time range. The output is a PCAP/binary file.

Advanced search request

To initiate an advanced search and generate a search ID that can be used to poll, send the following request:

POST https://<PX_IP_address>/api/4.0/search

Required header:

--user <username>:<password>

See Search summary request.

To retrieve results, see Download packets request.

For details and a visual representation of this process, see Overview of search workflow.

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Query parameters

• stime—Date and time from which the search should start. See Conventions for the format.

• etime—Date and time at which the search should end. See Conventions for the format.

• window—The window of time before and after the specified start time that should be searched. If stime is used as a parameter, the window parameter is divided by two and subtracted from the stime to make a new start time. The window parameter is added to the original stime to make an etime. If stime is not specified, stime defaults to the current time. If etime and window are not specified, etime defaults to stime + 1 second.

• xpf—Filter to reduce the results set; it supports BPF as defined at http://www.tcpdump.org/manpages/pcap-filter.7.html. It is also used with PX-specific connection attributes, see Connection Metadata Properties. Sample formatting is host

127.0.0.1 && packetdeltacountin>25.

• flowID—Filter to search for events tagged with a flowID. Provide "flowID = <id>" in the xpf field when submitting a search. Support for != is also available.

• limit—The maximum number of connections returned. The default URL encoding limit for asynchronous searches is 100.

• ruleset—The ruleset to use in the search. The ruleset can be local or uploaded (see examples below. If uploading a new ruleset, you can use the skipVerify option to skip validation of the uploaded ruleset (in the event of invalid signatures). Optional.

• strict—If this parameter is set to true, the search ignores extra VLANs and MPLS unless you specify them in the xpf

parameter. The default value is false.

• ip_list—A comma-separated list of IP addresses to be used as a pre-filter on connections. Specifically useful for sporadic traffic over a long period of time.

• depth—This search parameter controls what data is processed during a search. There are three types of a searches: connection, packet, and session. The default value is connection. Because a session-depth search includes a packet-depth search and a connection-depth search, session searches take more time than connection or packet searches. A packet-depth search includes a connection-depth search, so packet searches take longer than connection searches. To use less time, execute a connection or packet search instead of a session search and then review the data that was returned.

  • connection: To search connections only, set depth=connection. The “connection” value searches the ultrafast connection index to find information about traffic the Series appliance recorded. These connection records contain address, port, and protocol information, and TCP flags, if appropriate.

  • packet: To search packets only, set depth=packet.

  • session: To initiate session analysis, set depth=session. As the third main search phase, “session” pulls packets from the PCAP storage and analyzes them in the session analysis engine. Session searches allow you to analyze packets of interest.

Note

Session analysis is a processor-intensive and memory-intensive operation. The higher the connection limit, the longer this request will take. If there are more than 250 connections, session analysis is not recommended.

Examples

POST https://xxx.xxx.xxx.xxx/api/4.0/search?stime=20110901.015959&etime=&xpf=tcp&depth=packet

POST https://xxx.xxx.xxx.xxx/api/4.0/search -d "limit=100&strict=False&xpf=flowID = 123&depth=connection&stime=1519742735&etime=1519743035"

New search using an existing ruleset:

POST https://xxx.xxx.xxx.xxx/api/4.0/search -d "ruleset=myruleset&depth=session&stime=1537904410&etime=1537904710"

New search using a new ruleset:

https://xxx.xxx.xxx.xxx/api/4.0/search -F "depth=session" -F "stime=1537904410" -F "etime=1537904710" -F "ruleset=@myruleset.tgz"

Required header:

--user cpx:hammerhead

Advanced search response

HTTP/1.1 [Response Code] [Response Message]

{

"hash_field": "SEARCH_bdcae5adcef44e5b7f52c8bb8e6833de", "params": {

"etime": "2018-09-25T19:45:10Z",

"stime": "2018-09-25T19:40:10Z",

"ruleset": "myruleset"

},

"search_id": "bdcae5adcef44e5b7f52c8bb8e6833de", "search_type": "all",

"status": "-2"

}

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• stime—Start time of search.

• etime—End time of search.

• Hash Field—Hash key for the status of this search.

• Search Type—Type of search.

• XPF—Filter that supports BPF as defined at http://www.tcpdump.org/manpages/pcap-filter.7.html. It is also used with PX-specific connection attributes, see Connection metadata properties. Sample formatting is host 127.0.0.1 && packetdeltacountin>25.

• Search ID—The unique search identifier. search_id is the key to summary, detail, store, and so on. This return value connects to many other functions as an input parameter.

• Search Type—Type of search requested: stream or all.

• Status—Status of search. For example, –2 means that the search is queued.

Example

HTTP/1.1 200 OK

Date: Fri, 11 Mar 2016 22:33:49 GMT

Content-Type: text/html; charset=UTF-8

{

"hash_field": "SEARCH_578df457cb1049a18ae5f014e6dc5d5c", "params": {

"limit": 100, "search_type": "all", "xpf": "tcp"

},

"search_id": "578df457cb1049a18ae5f014e6dc5d5c", "search_type": "all",

"status": "-2"

}

cURL code sample: Advanced search

The code sample was run with cURL 7.57.0.

curl -k --user cpx:hammerhead

"stime=20150901.015959&etime=20150901.030000&xpf=tcp&depth=packet" https://xxx.xxx.xxx.xxx/api/4.0/search

This cURL sample includes the following options:

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• --user cpx:hammerhead—Replace cpx with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• "stime=20110901.015959&etime=&xpf=tcp&depth=packet"—This option specifies the time range that will be searched, TCP-only results, and a packet-depth search.

• https://xxx.xxx.xxx.xxx/api/4.0/search—The search request URL. Replace xxx.xxx.xxx.xxx with the IP address of your Series appliance.

Results

This example executes a packet-depth search within a specified time range and returns only TCP results. The output is in JSON.

Search within a search request

To search within the results of an existing search, send the following request:

POST https://<PX_IP_address>/api/4.0/searchinsearch

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the PX Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Query parameters

• source_id—Required. The universally unique identifier of the search that you want to search within. The source search must either be a packet-depth search or a session-depth search.

• stime—The date and time for the start of the search. This value must be the same as the stime of the source search.

• etime—Date and time for the end of the search. This value must be the etime of the source search.

• window—The window of time before and after the specified start time that should be searched. If stime is used as a parameter, the window parameter is divided by two and subtracted from the stime to make a new start time. The window parameter is added to the original stime to make an etime. If stime is not specified, stime defaults to the current time. If etime and window are not specified, etime defaults to stime + 1 second.

• xpf—Filter to reduce the results set. The filter supports BPF as defined at http://www.tcpdump.org/manpages/pcap-filter.7.html. It is also used with PX-specific connection attributes; see Connection Metadata Properties. Sample formatting is host 127.0.0.1 && packetdeltacountin>25.

• limit—The maximum number of connections returned. The default connection limit for asynchronous searches is 100.

• strict—This value is ignored.

• ip_list—This value is ignored.

• depth—This field must be set to packet.

Example

POST https://xxx.xxx.xxx.xxx/api/4.0/ searchinsearch?stime=20110901.015959&etime=&xpf=tcp&depth=packet&source_id=301571c6fbbb43167411e85f45911460

Required header:

--user cpx:hammerhead

Search within a search response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type] hash_field: [Hash Field] input_create_time: [Input Create Time] input_depth: [Input Depth]

input_etime_nanoseconds: [Input End Time in Nanoseconds] input_etime_second: [Input End Time in Seconds] input_hash_field: [Input Hash Field]

input_limit: [Input Limit] input_score: [Input Score] input_search_id: [Input Search ID] input_search_type: [Input Search Type] input_source: [Input Source]

input_stime_nanoseconds: [Input Start Time in Nanoseconds] input_stime_second: [Input Start Time in Seconds] input_strict: [Input Strictness]

input_user: [Input User] input_xpf: [Input XPF] output_bpf: [Output BPF] output_status: [Output Status] search_id: [Search ID]

status: [Status]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Hash Field—Hash key for the status of this search.

• Input Create Time—Time at which the search was submitted.

• Input Depth—Search depth. A search can be at the connection, packet, or session depth.

• Input End Time in Nanoseconds—The nanoseconds portion of the end time of the search time range.

• Input End Time in Seconds—The seconds portion of the end time of the search time range.

• Input Hash Field—Hash key for the status of this search.

• Input Limit—Requested maximum number of connection records to find.

• Input Score—Time when the search was created.

• Input Search ID—Generated search ID that uniquely identifies this search.

• Input Search Type—Type of search requested: stream or all.

• Input Source—The universally unique identifier of the search that you are searching within.

• Input Start Time in Nanoseconds—The nanoseconds portion of the start time of the search time range.

• Input Start Time in Seconds—The seconds portion of the start time of the search time range.

• Input Strictness—If this field is set to true, no variations on the input are tried.

• Input User—User who made the search request.

• Input XPF—Filter provided by the end user.

• Output BPF—Generated XPF after input_xpf is processed by the PX XPF processing engine.

• Output Status—Status of the search. For example, –2 means that the search is queued.

• Search ID—The unique search identifier of the search within a search.

• Status—Status of search. For example, –2 means that the search is queued.

Example

HTTP/1.1 200 OK

Date: Fri, 31 Mar 2017 20:50:52 GMT

Content-Type: application/json; charset=utf-8

{

"hash_field": "SEARCH_d6e6c3cc4fc543356da6fd4e0df27d18", "input_create_time": "1490993452",

"input_depth": "packet", "input_etime_nanoseconds": "0",

"input_etime_second": "1490020140",

"input_hash_field": "SEARCH_d6e6c3cc4fc543356da6fd4e0df27d18", "input_limit": "0",

"input_score": "1490993452",

"input_search_id": "d6e6c3cc4fc543356da6fd4e0df27d18",

"input_search_type": "all",

"input_source": "92e32b18ef8646ed5b7caa15f438129d", "input_stime_nanoseconds": "0",

"input_stime_second": "1490018940", "input_strict": "false", "input_user": "cpx",

"input_xpf": "layer7Classification = 7", "output_bpf": "ether[148:4] = 7", "output_status": "-2",

"search_id": "d6e6c3cc4fc543356da6fd4e0df27d18", "status": "-2"

}

cURL code sample: Search within a search

The code sample was run with cURL 7.57.0.

curl -k --user cpx:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/searchinsearch --data 'xpf=layer7Classification+%3D+7&stime=20161026.155315&etime=20161026.202822&limit=0&depth=packet&ip_list=&source_id=7b

This cURL sample includes the following options:

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• --user cpx:hammerhead—Replace cpx with the user name for your PX Series appliance. Replace hammerhead with the password for your PX Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/searchinsearch—The search request URL. Replace xxx.xxx.xxx.xxx with the IP address of your PX Series appliance.

• --data 'xpf=layer7Classification+%3D+7&stime=20161026.155315&etime=20161026.202822&limit=0&depth=packet&ip_list=&source_id option specifies what to search for within an existing search.

Results

This example returns a subset of results from an existing search. The output is in JSON.

Upload PCAP request

To upload a packet capture (PCAP) file, send the following request:

POST https://<PX_IP_address>/api/4.0/search/upload

Required and optional headers:

--user <username>:<password>

-H "Content-Type: multipart/form-data" uploadfile: <upload_file>

storename: <store_name>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

• upload_file—Name and location of the packet capture file.

• store_name—Optional. Name for the uploaded packet capture file. If this parameter is omitted, a search universally unique identifier is generated and used.

Example

POST https://xxx.xxx.xxx.xxx/api/4.0/search/upload

Required and optional headers:

--user cpx:hammerhead

-H "Content-Type: multipart/form-data"

-F "uploadfile=@/home/test.pcap"

-F "storename=storeTest3"

Upload PCAP response

input_create_time: [Input Create Time] input_depth: [Input Depth] input_hash_field: [Input Hash Field] input_score: [Input Score] input_search_id: [Input Search Identifier] input_search_type: [Input Search Type] input_user: [Input User]

output_depth: [Output Depth] output_index_end: [Packet Index End Time]

output_index_foundRecords: [Packet Index Found Records] output_index_limitPercent: [Packet Index Limit Percent Complete] output_index_message: [Packet Index Status Message] output_index_packetPercent: [Packet Index Percent Complete] output_index_start: [Packet Index Start]

output_index_status: [Packet Index Status] output_lastUpdate: [Last Update] output_message: [Output Status Message]

output_packet_elapsed: [Packet Retrieval Elapsed Time]

output_packet_end: [Packet Retrieval End Time] output_packet_foundRecords: [Packet Retrieval Found Records] output_packet_message: [Packet Retrieval Status Message] output_packet_packetPercent: [Packet Retrieval Percent Complete] output_packet_processedBytes: [Packet Retrieval Packet Size] output_packet_start: [Packet Retrieval Start] output_packet_status: [Packet Retrieval Status] output_session_message: [Session Analysis Status Message] output_session_packetPercent: [Session Analysis Percent Complete] output_session_status: [Session Analysis Status]

output_status: [Output Status] output_xpf_end: [Connection Index End Time]

output_xpf_foundRecords: [Connection Index Found Records] output_xpf_limitPercent: [Connection Index Percent Complete] output_xpf_message: [Connection Index Status Message] output_xpf_packetCount: [Connection Index Packet Count] output_xpf_start: [Connection Index Start] output_xpf_status: [Connection Index Status]

target_depth: [Target Depth]

Response fields

• Input Create Time—Time at which the search was submitted.

• Input Depth—Search depth. A search can be at the connection, packet, or session depth.

• Input Hash Field—Hash key for the status of this search.

• Input Score—Time when the search was created.

• Input Search Identifier—Generated search ID that uniquely identifies this search.

• Input Search Type—Type of search requested: stream or all.

• Input User—User who made the search request.

• Output Depth—Search depth. A search can be at the connection, packet, or session depth.

• Packet Index End Time—End time of this phase in epoch time.

• Packet Index Found Records—Number of records found.

• Packet Index Limit Percent Complete—Percentage complete of all potential packets found.

• Packet Index Status Message—Current status message for this phase.

• Packet Index Percent Complete—Percentage complete, based on captured packet times.

• Packet Index Start—Start time of this phase in epoch time.

• Packet Index Status—Status of this phase. Valid values are skipped, done, working, idle, and error.

• Last Update—Time when the search was last updated.

• Output Status Message—Status of the search.

• Packet Retrieval Elapsed—Total elapsed time of this phase.

• Packet Retrieval End Time—End time of this phase in epoch time.

• Packet Retrieval Found Records—Number of records found.

• Packet Retrieval Status Message—Current status message for this phase.

• Packet Retrieval Percent Complete—Percentage complete of all potential packets found.

• Packet Retrieval Packet Size—Size of the packets processed.

• Packet Retrieval Start—Start time of this phase in epoch time.

• Packet Retrieval Status—Status of this phase. Valid values are skipped, done, working, idle, and error.

• Session Analysis Status Message—Current status message for this phase.

• Session Analysis Percent Complete—Percentage complete of all potential packets found.

• Session Analysis Status—Status of this phase. Valid values are skipped, done, working, idle, and error.

• Output Status—Status of the search. Valid values are skipped, done, working, idle, and error.

• Connection Index End Time—End time of this phase in epoch time.

• Connection Index Found Records—Number of records found.

• Connection Index Percent Complete—Percentage complete, based on input_limit.

• Connection Index Status Message—Percentage complete, based on captured packet times.

• Connection Index Packet Count—Number of packets to be found, based on connection records.

• Connection Index Start—Start time of this phase in epoch time.

• Connection Index Status—Status of this phase. Valid values are skipped, done, working, idle, and error.

• Target Depth—Search depth. A search can be at the connection, packet, or session depth.

Example

HTTP/1.1 200 OK

Date: Fri, 11 Mar 2016 22:33:49 GMT

Content-Type: text/html; charset=UTF-8

{

"input_create_time":"1468417915",

"input_depth":"connection", "input_hash_field":"SEARCH_8767f52de62446766c29a5132d76f400", "input_score":"1468417915", "input_search_id":"8767f52de62446766c29a5132d76f400", "input_search_type":"upload",

"input_user":"cpx", "output_depth":"connection", "output_index_end":"1468417936", "output_index_foundRecords":"0", "output_index_limitPercent":"100", "output_index_message":"Search complete", "output_index_packetPercent":"100", "output_index_start":"1468417936", "output_index_status":"done", "output_lastUpdate":"1468417936", "output_message":"Search complete", "output_packet_elapsed":"0.000", "output_packet_end":"0", "output_packet_foundRecords":"0", "output_packet_message":"skipped", "output_packet_packetPercent":"0", "output_packet_processedBytes":"0", "output_packet_start":"0", "output_packet_status":"skipped", "output_session_message":"skipped", "output_session_packetPercent":"0", "output_session_status":"skipped", "output_status":"done", "output_xpf_end":"1468417936", "output_xpf_foundRecords":"0", "output_xpf_limitPercent":"100", "output_xpf_message":"Search complete", "output_xpf_packetPercent":"100", "output_xpf_start":"1468417936", "output_xpf_status":"done", "target_depth":"connection"

}

cURL code sample: Upload PCAP

The code sample was run with cURL 7.57.0.

curl -k --user cpx:hammerhead -X POST -H "Content-Type: multipart/form-data" -F "uploadfile=@/home/test.pcap"

-F "storename=storeTest3" https://xxx.xxx.xxx.xxx/api/4.0/search/upload

This cURL sample includes the following options:

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• --user cpx:hammerhead—Replace cpx with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• -X POST—This option specifies using the POST method.

• -H "Content-Type: multipart/form-data"—This option allows you to submit files using HTTP.

• -F "uploadfile=@/home/test.pcap"—This option specifies the name and location of the packet capture file to upload.

• -F "storename=storeTest3"—This option specifies the name to save the uploaded packet capture file as.

• https://xxx.xxx.xxx.xxx/api/4.0/search/upload—The search request URL. Replace xxx.xxx.xxx.xxx with the IP address of your Series appliance.

Results

This example uploads a PCAP file and saves it with the specified file name. The output is in JSON.

Historical searches request

To list all searches during the past 48 hours and their status, send the following request:

GET https://<PX_IP_address>/api/4.0/search/history

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Example

GET https://xxx.xxx.xxx.xxx/api/4.0/search/history

Required header:

--user cpx:hammerhead

Historical searches response

HTTP/1.1 [Response Code] [Response Message]

Date: [Date]

Content-Type: [Content Type] current_time: [Current Time] message: [Message]

input_create_time: [Input Create Time] input_depth: [Input Depth]

input_etime_nanoseconds: [Input End Time in Nanoseconds] input_etime_second: [Input End Time in Seconds] input_hash_field: [Input Hash Field]

input_limit: [Input Limit] input_score: [Input Score]

input_search_id: [Input Search Identifier] input_search_type: [Input Search Type] input_stime_nanoseconds: [Input Start Time in Nanoseconds] input_stime_second: [Input Start Time in Seconds] input_strict: [Input Strictness]

input_time_format: [Input Time Format] input_user: [Input User] output_elapsed: [Output Elapsed Time]

output_firstFlowEpoch: [Output First Flow Epoch] output_firstIndexEpoch: [Output First Index Epoch] output_firstPacketEpoch: [Output First Packet Epoch] output_index_elapsed: [Packet Index Elapsed Time] output_index_end: [Packet Index End Time] output_index_foundRecords: [Packet Index Found Records] output_index_message: [Packet Index Status Message] output_index_packetPercent: [Packet Index Percent Complete] output_index_rangePercent: [Packet Index Range Percent] output_index_searchedFiles: [Packet Index Searched Files] output_index_start: [Packet Index Start] output_index_status: [Packet Index Status] output_lastUpdate: [Last Update]

output_message: [Output Status Message] output_packet_elapsed: [Packet Retrieval Elapsed Time] output_packet_end: [Packet Retrieval End Time] output_packet_foundRecords: [Packet Retrieval Found Records] output_packet_message: [Packet Retrieval Status Message]

output_packet_packetPercent: [Packet Retrieval Percent Complete] output_packet_processedBytes: [Packet Retrieval Packet Size] output_packet_start: [Packet Retrieval Start] output_packet_status: [Packet Retrieval Status] output_searchEnd: [Search End]

output_searchStart: [Search Start] output_session_elapsed: [Session Analysis Elapsed Time] output_session_end: [Session Analysis End Time] output_session_message: [Session Analysis Status Message]

output_session_packetPercent: [Session Analysis Percent Complete] output_session_processedBytes: [Session Analysis Packet Size] output_session_processedRecords: [Session Analysis Processed Records] output_session_start: [Session Analysis Start]

output_session_status: [Session Analysis Status] output_status: [Output Status] output_streamCount: [Stream Count]

output_xpf_elapsed: [Connection Index Elapsed Time] output_xpf_end: [Connection Index End Time] output_xpf_extentSecond: [Connection Index Second] output_xpf_firstSecond: [Connection Index First Connection] output_xpf_foundRecords: [Connection Index Found Records] output_xpf_lastSecond: [Connection Index Last Connection] output_xpf_limitPercent: [Connection Index Percent Complete] output_xpf_message: [Connection Index Status Message] output_xpf_packetCount: [Connection Index Packet Count] output_xpf_rangePercent: [Connection Index Range Percent] output_xpf_searchedBytes: [Connection Index Searched Bytes]

output_xpf_start: [Connection Index Start] output_xpf_status: [Connection Index Status] target_depth: [Target Depth]

status: [Status]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Current Time—Time when response is returned.

• Message—Summary of results.

• Input Create Time—Time at which the search was submitted.

• Input Depth—Search depth. A search can be at the connection, packet, or session depth.

• Input End Time in Nanoseconds—The nanoseconds portion of the end time of the search time range.

• Input End Time in Seconds—The seconds portion of the end time of the search time range.

• Input Hash Field—Hash key for the status of this search.

• Input Limit—Requested maximum number of connection records to find.

• Input Score—Time when the search was created.

• Input Search Identifier—Generated search ID that uniquely identifies this search.

• Input Search Type—Type of search requested: stream or all.

• Input Start Time in Nanoseconds—The nanoseconds portion of the start time of the search time range.

• Input Start Time in Seconds—The seconds portion of the start time of the search range.

• Input Strictness—If this field is set to true, no variations on the input are tried.

• Input Time Format—Time format for input. A value of 1 indicates that the pcap time stamp is in microseconds; a value of 0 indicates that the pcap time stamp is in nanoseconds.

• Input User—User who made the search request.

• Output Elapsed Time—Total elapsed time for all phases.

• Output First Flow Epoch—Time of the first flow recorded on the appliance.

• Output First Index Epoch—Time of the oldest connection packet index recorded on the appliance.

• Output First Packet Epoch—Time of the oldest packet stored on the appliance.

• Packet Index Elapsed Time—Total elapsed time of this phase.

• Packet Index End Time—End time of this phase in epoch time.

• Packet Index Found Records—Number of records found.

• Packet Index Status Message—Current status message for this phase.

• Packet Index Percent Complete—Percentage complete of all potential packets found.

• Packet Index Range Percent—Percentage complete, based on captured packet times.

• Packet Index Searched Files—Number of files touched.

• Packet Index Start—Start time of this phase in epoch time.

• Packet Index Status—Status of this phase. Valid values are skipped, done, working, idle, and error.

• Last Update—Time when the search was last updated.

• Output Status Message—Status of the search.

• Packet Retrieval Elapsed—Total elapsed time of this phase.

• Packet Retrieval End Time—End time of this phase in epoch time.

• Packet Retrieval Found Records—Number of records found.

• Packet Retrieval Status Message—Current status message for this phase.

• Packet Retrieval Percent Complete—Percentage complete of all potential packets found.

• Packet Retrieval Packet Size—Size of the packets processed.

• Packet Retrieval Start—Start time of this phase in epoch time.

• Packet Retrieval Status—Status of this phase. Valid values are skipped, done, working, idle, and error.

• Search End—Last record searched.

• Search Start—First record searched.

• Session Analysis Elapsed Time—Total elapsed time of this phase.

• Session Analysis End Time—End time of this phase in epoch time.

• Session Analysis Status Message—Current status message for this phase.

• Session Analysis Percent Complete—Percentage complete of all potential packets found.

• Session Analysis Packet Size—Size of the packets processed.

• Session Analysis Processed Records—Number of packets processed.

• Session Analysis Start—Start time of this phase in epoch time.

• Session Analysis Status—Status of this phase. Valid values are skipped, done, working, idle, and error.

• Output Status—Status of the search. Valid values are skipped, done, working, idle, and error.

• Stream Count—Number of nPulse streams.

• Connection Index Elapsed Time—Total elapsed time of this phase.

• Connection Index End Time—End time of this phase in epoch time.

• Connection Index Second—The last second of the last flow that the search examined.

• Connection Index First Connection—Epoch of the first connection found.

• Connection Index Found Records—Number of records found.

• Connection Index Last Connection—Current status message for this phase.

• Connection Index Percent Complete—Percentage complete, based on input_limit.

• Connection Index Status Message—Percentage complete, based on captured packet times.

• Connection Index Packet Count—Number of packets to be found, based on connection records.

• Connection Index Range Percent—Percentage complete, based on captured packet times.

• Connection Index Searched Bytes—Size of searched packets.

• Connection Index Start—Start time of this phase in epoch time.

• Connection Index Status—Status of this phase. Valid values are skipped, done, working, idle, and error.

• Target Depth—Search depth. A search can be at the connection, packet, or session depth.

• Status—A standard HTTP response message.

Example

HTTP/1.1 200 OK

Date: Fri, 19 Feb 2016 23:52:23 GMT

Content-Type: text/html; charset=UTF-8

{

"current_time": 1455925943, "message": "Found 1 searches.", "searches": [

{

"input_create_time": "1455054118", "input_depth": "connection", "input_etime_nanoseconds": "0",

"input_etime_second": "1455053885",

"input_hash_field": "SEARCH_6e693e264d5045f184c710a650435f76", "input_limit": "100",

"input_score": "1455054118.29",

"input_search_id": "6e693e264d5045f184c710a650435f76", "input_search_type": "all",

"input_stime_nanoseconds": "0",

"input_stime_second": "1455050285", "input_strict": "False", "input_time_format": "0", "input_user": "cpx", "output_elapsed": "0.447",

"output_firstFlowEpoch": "1455051483",

"output_firstIndexEpoch": "1455051483",

"output_firstPacketEpoch": "1455051609",

"output_index_elapsed": "0.138",

"output_index_end": "1455054118",

"output_index_foundRecords": "61345", "output_index_message": "Search complete", "output_index_packetPercent": "100",

"output_index_rangePercent": "100",

"output_index_searchedFiles": "345",

"output_index_start": "1455054118", "output_index_status": "done", "output_lastUpdate": "1455054117", "output_message": "Search complete", "output_packet_elapsed": "0.000",

"output_packet_end": "0",

"output_packet_foundRecords": "0", "output_packet_message": "skipped", "output_packet_packetPercent": "0",

"output_packet_processedBytes": "0",

"output_packet_start": "0", "output_packet_status": "skipped", "output_searchEnd": "1455054118",

"output_searchStart": "1455054118",

"output_session_elapsed": "0",

"output_session_end": "0", "output_session_message": "skipped", "output_session_packetPercent": "0", "output_session_processedBytes": "NA", "output_session_processedRecords": "NA", "output_session_start": "0", "output_session_status": "skipped", "output_status": "done", "output_streamCount": "1",

"output_xpf_elapsed": "0.016",

"output_xpf_end": "1455054118",

"output_xpf_extentSecond": "140257907072051",

"output_xpf_firstSecond": "140256452018176",

"output_xpf_foundRecords": "100",

"output_xpf_lastSecond": "140257907071710",

"output_xpf_limitPercent": "100",

"output_xpf_message": "Search complete", "output_xpf_packetCount": "61345",

"output_xpf_rangePercent": "100",

"output_xpf_searchedBytes": "0",

"output_xpf_start": "1455054118", "output_xpf_status": "done", "target_depth": "connection"

}

],

"status": "ok"

}

cURL code sample: Historical searches

The code sample was run with cURL 7.57.0.

curl -k --user cpx:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/search/history

This cURL sample includes the following options:

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• --user cpx:hammerhead—Replace cpx with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/events/search/history—The search request URL. Replace xxx.xxx.xxx.xxx with the IP address of your Series appliance.

Results

This example lists all searches during the past 48 hours and their status. The output is in JSON.

Search summary request

To provide a concise summary of an advanced search, send the following request:

GET https://<PX_IP_address>/api/4.0/search/<search_id>/poll

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

• search_id—The unique search identifier.

Example

GET https://xxx.xxx.xxx.xxx/api/4.0/search/7b123/poll

Required header:

--user cpx:hammerhead

Search summary response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type] done: [Done]

queued: [Queued]

connection: [Connection Status] packet: [Packet Status] session: [Session Status]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Done—Whether the search is complete. Valid values are True and False.

• Queued—Whether the search is queued. Valid values are True and False.

• Connection Status—Status of the connection search. Valid values are skipped, done, working, idle, and error.

• Packet Status—Status of the packet search. Valid values are skipped, done, working, idle, and error.

• Session Status—Status of the session search. Valid values are skipped, done, working, idle, and error.

Example

HTTP/1.1 200 OK

Date: Sat, 20 Feb 2016 00:51:37 GMT

Content-Type: text/html; charset=UTF-8

{

"done": true, "queued": true, "status": {

"connection": "done", "packet": "skipped", "session": "skipped"

}

}

cURL code sample: Search summary

The code sample was run with cURL 7.57.0.

curl -k --user cpx:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/search/7b123/poll

This cURL sample includes the following options:

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• --user cpx:hammerhead—Replace cpx with the user name for your PX Series appliance. Replace hammerhead with the password for your PX Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/search/7b123/poll—The search request URL. Replace xxx.xxx.xxx.xxx with the IP address of your PX Series appliance. Replace 7b123 with the search ID of interest.

Results

This example provides a concise summary of the specified search. The output is in JSON.

Status of advanced search request

To provide the status of an advanced search, send the following request:

GET https://<PX_IP_address>/api/4.0/search/<search_id>

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

• search_id—The unique search identifier.

Example

GET https://xxx.xxx.xxx.xxx/api/4.0/search/7b123

Required header:

--user cpx:hammerhead

Status of advanced search response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type] input_create_time: [Input Create Time] input_depth: [Input Depth]

input_etime_nanoseconds: [Input End Time in Nanoseconds] input_etime_second: [Input End Time in Seconds] input_hash_field: [Input Hash Field]

input_score: [Input Score] input_limit: [Input Limit] input_ruleset: [Ruleset] input_search_id: [Input Search ID] input_search_type: [Input Search Type]

input_stime_nanoseconds: [Input Start Time in Nanoseconds] input_stime_second: [Input Start Time in Seconds] input_strict: [Input Strictness]

input_time_format: [Input Time Format] input_user: [Input User] output_elapsed: [Output Elapsed Time]

output_firstFlowEpoch: [Output First Flow Epoch] output_firstIndexEpoch: [Output First Index Epoch] output_firstPacketEpoch: [Output First Packet Epoch]

output_index_elapsed: [Packet Index Elapsed Time] output_index_end: [Packet Index End Time] output_index_foundRecords: [Packet Index Found Records] output_index_message: [Packet Index Status Message] output_index_packetPercent: [Packet Index Percent Complete] output_index_rangePercent: [Packet Index Range Percent] output_index_searchedFiles: [Packet Index Searched Files] output_index_start: [Packet Index Start] output_index_status: [Packet Index Status] output_lastUpdate: [Last Update]

output_message: [Output Status Message] output_packet_elapsed”: [Packet Retrieval Elapsed Time] output_packet_end: [Packet Retrieval End Time] output_packet_foundRecords: [Packet Retrieval Found Records] output_packet_message: [Packet Retrieval Status Message]

output_packet_packetPercent: [Packet Retrieval Percent Complete] output_packet_processedBytes: [Packet Retrieval Packet Size] output_packet_start: [Packet Retrieval Start] output_packet_status: [Packet Retrieval Status] output_searchEnd: [Search End]

output_searchStart: [Search Start] output_session_elapsed: [Session Analysis Elapsed Time] output_session_end: [Session Analysis End Time] output_session_message: [Session Analysis Status Message]

output_session_packetPercent: [Session Analysis Percent Complete] output_session_processedBytes: [Session Analysis Packet Size] output_session_processedRecords: [Session Analysis Processed Record] output_session_start: [Session Analysis Start] output_session_status: [Session Analysis Status]

output_status: [Output Status] output_streamCount: [Stream Count]

output_xpf_elapsed: [Connection Index Elapsed Time] output_xpf_end: [Connection Index End Time] output_xpf_extentSecond: [Connection Index Second] output_xpf_firstSecond: [Connection Index First Connection] output_xpf_foundRecords: [Connection Index Found Records] output_xpf_lastSecond: [Connection Index Last Connection] output_xpf_limitPercent: [Connection Index Percent Complete] output_xpf_message: [Connection Index Status Message] output_xpf_packetCount: [Connection Index Packet Count] output_xpf_rangePercent: [Connection Index Range Percent] output_xpf_searchedBytes: [Connection Index Searched Bytes] output_xpf_start: [Connection Index Start] output_xpf_status: [Connection Index Status]

target_depth: [Target Depth]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Input Create Time—Time at which the search was submitted.

• Input Depth—Search depth. A search can be at the connection, packet, or session depth.

• Input End Time in Nanoseconds—The nanoseconds portion of the end time of the search time range.

• Input End Time in Seconds—The seconds portion of the end time of the search time range.

• Input Hash Field—Hash key for the status of this search.

• Input Score—Time when the search was created.

• Input Limit—Requested maximum number of connection records to find.

• Input Ruleset—Indicates (by ruleset name) which rulesets were used in the search.

• Input Search ID—Generated search ID that uniquely identifies this search.

• Input Search Type—Type of search requested: stream or all.

• Input Start Time in Nanoseconds—The nanoseconds portion of the start time of the search time range.

• Input Start Time in Seconds—The seconds portion of the start time of the search range.

• Input Strictness—If this field is set to true, no variations on the input are tried.

• Input Time Format—Time format for input. A value of 1 indicates that the pcap time stamp is in microseconds; a value of 0 indicates that the pcap time stamp is in nanoseconds.

• Input User—User who made the search request.

• Output Elapsed Time—Total elapsed time for all phases.

• Output First Flow Epoch—Time of the first flow recorded on the appliance.

• Output First Index Epoch—Time of the oldest connection packet index recorded on the appliance.

• Output First Packet Epoch—Time of the oldest packet stored on the appliance.

• Packet Index Elapsed Time—Total elapsed time of this phase.

• Packet Index End Time—End time of this phase in epoch time.

• Packet Index Found Records—Number of records found.

• Packet Index Status Message—Current status message for this phase.

• Packet Index Percent Complete—Percentage complete of all potential packets found.

• Packet Index Range Percent—Percentage complete, based on captured packet times.

• Packet Index Searched Files—Number of files touched.

• Packet Index Start—Start time of this phase in epoch time.

• Packet Index Status—Status of this phase. Valid values are skipped, done, working, idle, and error.

• Last Update—Time when the search was last updated.

• Output Status Message—Status of the search.

• Packet Retrieval Elapsed—Total elapsed time of this phase.

• Packet Retrieval End Time—End time of this phase in epoch time.

• Packet Retrieval Found Records—Number of records found.

• Packet Retrieval Status Message—Current status message for this phase.

• Packet Retrieval Percent Complete—Percentage complete of all potential packets found.

• Packet Retrieval Packet Size—Size of the packets processed.

• Packet Retrieval Start—Start time of this phase in epoch time.

• Packet Retrieval Status—Status of this phase. Valid values are skipped, done, working, idle, and error.

• Search End—Last record searched.

• Search Start—First record searched.

• Session Analysis Elapsed Time—Total elapsed time of this phase.

• Session Analysis End Time—End time of this phase in epoch time.

• Session Analysis Status Message—Current status message for this phase.

• Session Analysis Percent Complete—Percentage complete, of all potential packets found.

• Session Analysis Packet Size—Size of the packets processed.

• Session Analysis Processed Records—Number of packets processed.

• Session Analysis Start—Start time of this phase in epoch time.

• Session Analysis Status—Status of this phase. Valid values are skipped, done, working, idle, and error.

• Output Status—Status of the search. Valid values are skipped, done, working, idle, and error.

• Stream Count—Number of nPulse streams.

• Connection Index Elapsed Time—Total elapsed time of this phase.

• Connection Index End Time—End time of this phase in epoch time.

• Connection Index Second—The last second of the last flow that the search examined.

• Connection Index First Connection—Epoch time of the first connection found.

• Connection Index Found Records—Number of records found.

• Connection Index Last Connection—Current status message for this phase.

• Connection Index Percent Complete—Percentage complete, based on input_limit.

• Connection Index Status Message—Percentage complete, based on captured packet times.

• Connection Index Packet Count—Number of packets to be found, based on connection records.

• Connection Index Range Percent—Percentage complete, based on captured packet times.

• Connection Index Searched Bytes—Size of searched packets.

• Connection Index Start—Start time of this phase in epoch time.

• Connection Index Status—Status of this phase. Valid values are skipped, done, working, idle, and error.

• Target Depth—Search depth. A search can be at the connection, packet, or session depth.

Example

HTTP/1.1 200 OK

Date: Thu, 10 Mar 2016 00:06:51 GMT

Content-Type: text/html; charset=UTF-8

{

"input_create_time": "1455054118", "input_depth": "connection", "input_etime_nanoseconds": "0",

"input_etime_second": "1455053885",

"input_hash_field": "SEARCH_6e693e264d5045f184c710a650435f76", "input_limit": "100",

"input_score": "1455054118.29",

"input_search_id": "6e693e264d5045f184c710a650435f76", "input_search_type": "all",

"input_stime_nanoseconds": "0",

"input_stime_second": "1455050285", "input_strict": "False", "input_time_format": "0", "input_user": "cpx", "output_elapsed": "0.447",

"output_firstFlowEpoch": "1455051483",

"output_firstIndexEpoch": "1455051483",

"output_firstPacketEpoch": "1455051609",

"output_index_elapsed": "0.138",

"output_index_end": "1455054118",

"output_index_foundRecords": "61345", "output_index_message": "Search complete", "output_index_packetPercent": "100",

"output_index_rangePercent": "100",

"output_index_searchedFiles": "345",

"output_index_start": "1455054118", "output_index_status": "done", "output_lastUpdate": "1455054117", "output_message": "Search complete", "output_packet_elapsed": "0.000",

"output_packet_end": "0",

"output_packet_foundRecords": "0", "output_packet_message": "skipped", "output_packet_packetPercent": "0",

"output_packet_processedBytes": "0",

"output_packet_start": "0", "output_packet_status": "skipped", "output_searchEnd": "1455054118",

"output_searchStart": "1455054118",

"output_session_elapsed": "0",

"output_session_end": "0", "output_session_message": "skipped", "output_session_packetPercent": "0", "output_session_processedBytes": "NA", "output_session_processedRecords": "NA", "output_session_start": "0", "output_session_status": "skipped", "output_status": "done", "output_streamCount": "1",

"output_xpf_elapsed": "0.016",

"output_xpf_end": "1455054118",

"output_xpf_extentSecond": "140257907072051",

"output_xpf_firstSecond": "140256452018176",

"output_xpf_foundRecords": "100",

"output_xpf_lastSecond": "140257907071710",

"output_xpf_limitPercent": "100", "output_xpf_message": "Search complete", "output_xpf_packetCount": "61345",

"output_xpf_rangePercent": "100",

"output_xpf_searchedBytes": "0",

"output_xpf_start": "1455054118", "output_xpf_status": "done", "target_depth": "connection"

}

cURL code sample: Status of advanced search

The code sample was run with cURL 7.57.0.

curl -k --user cpx:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/search/7b123

This cURL sample includes the following options:

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• --user cpx:hammerhead—Replace cpx with the user name for your PX Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/search/7b123—The search request URL. Replace xxx.xxx.xxx.xxx with the IP address

of your Series appliance. Replace 7b123 with the search ID of interest.

Results

This example returns the status of the specified search. The output is in JSON.

Session analysis using existing ruleset request

To invoke session analysis on the specified search, send the following request:

POST https://<PX_IP_address>/api/4.0/search/<search_id>/session-analysis

Required header:

--user <username>:<password>

See Search summary request.

To retrieve results, see Download packets request.

For details and a visual representation of this process, see Overview of search workflow.

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

• search_id—The UUID of the search to analyze.

Query parameters

• ruleset—The ruleset to use in the search. The ruleset can be local or uploaded (see examples below. If uploading a new ruleset, you can use the skipVerify option to skip validation of the uploaded ruleset (in the event of invalid signatures). Optional.

Examples

Session analysis using an existing ruleset:

POST https://xxx.xxx.xxx.xxx/api/4.0/search/00e5156128e74fc54b3bd07a5eac214f/session-analysis -d "ruleset=myruleset&depth=session&stime=1537904410&etime=1537904710"

Session analysis using a new ruleset:

https://xxx.xxx.xxx.xxx/api/4.0/search/00e5156128e74fc54b3bd07a5eac214f/session-analysis -F "ruleset=@myruleset.tgz"

Required header:

--user cpx:hammerhead

Session analysis using existing ruleset response

HTTP/1.1 [Response Code] [Response Message]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• stime—Start time of search.

• etime—End time of search.

• Hash Field—Hash key for the status of this search.

• Search Type—Type of search.

• XPF—Filter that supports BPF as defined at http://www.tcpdump.org/manpages/pcap-filter.7.html. It is also used with

-specific connection attributes, see Connection metadata properties. Sample formatting is host 127.0.0.1 && packetdeltacountin>25.

• Search ID—The unique search identifier. search_id is the key to summary, detail, store, and so on. This return value connects to many other functions as an input parameter.

• Search Type—Type of search requested: stream or all.

• Status—Status of search. For example, –2 means that the search is queued.

Example

HTTP/1.1 200 OK

cURL code sample: Session analysis using existing ruleset

The code sample was run with cURL 7.57.0.

curl -k --user cpx:hammerhead

"stime=20150901.015959&etime=20150901.030000&xpf=tcp&depth=packet" https://xxx.xxx.xxx.xxx/api/4.0/search/ 00e5156128e74fc54b3bd07a5eac214f/session-analysis

This cURL sample includes the following options:

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• --user cpx:hammerhead—Replace cpx with the user name for your PX Series appliance. Replace hammerhead with the password for your Series appliance.

• "stime=20110901.015959&etime=&xpf=tcp&depth=packet"—This option specifies the time range that will be searched, TCP-only results, and a packet-depth search.

• https://xxx.xxx.xxx.xxx/api/4.0/search/00e5156128e74fc54b3bd07a5eac214f/session-analysis—The search request URL. Replace xxx.xxx.xxx.xxx with the IP address of your PX Series appliance., and 00e5156128e74fc54b3bd07a5eac214f with the search UUID.

Results

This example executes session analysis on the specified search.

Cancel searches request

To cancel an active and queued search, send the following request:

DELETE https://<PX_IP_address>/api/4.0/search/<search_id>

Required header:

--user <username>:<password>

Note

You can only cancel searches you initiated. An admin-level user can cancel any search.

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

• search_id—The unique search identifier.

Example

DELETE https://xxx.xxx.xxx.xxx/api/4.0/search/7b123

Required header:

--user cpx:hammerhead

Cancel searches response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type] message: [Message]

status: [Status]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Message—Error message.

• Status—A standard HTTP response message.

Example

HTTP/1.1 200 OK

Date: Wed, 16 Mar 2016 17:14:42 GMT

Content-Type: text/html; charset=UTF-8

{

"message": "Abort request is set for search id: b948090d35c54ca19d3570c9194e7863", "status": "ok"

}

cURL code sample: Cancel searches

The code sample was run with cURL 7.57.0.

curl -k --user cpx:hammerhead -X DELETE https://xxx.xxx.xxx.xxx/api/4.0/search/7b123

This cURL sample includes the following options:

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• --user cpx:hammerhead—Replace cpx with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• -X DELETE—This option changes the HTTP method to DELETE.

• https://xxx.xxx.xxx.xxx/api/4.0/events/searchid/7b123—The search request URL. Replace xxx.xxx.xxx.xxx with the IP address of your Series appliance. Replace 7b123 with the search ID of interest.

Results

This example cancels the specified search. The output is in JSON.

List queued searches request

To display the contents of the advanced search queue, send the following request:

GET https://<PX_IP_address>/api/4.0/queue

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Example

GET https://xxx.xxx.xxx.xxx/api/4.0/queue

Required header:

--user cpx:hammerhead

List queued searches response

input_user: [Input User] input_limit: [Input Limit]

input_etime_second: [Input End Time in Seconds] input_hash_field: [Input Hash Field] input_create_time: [Input Create Time] input_packet_analyze: [Input Packet Analysis]

input_etime_nanoseconds: [Input End Time in Nanoseconds] input_stime_nanoseconds: [Input Start Time in Nanoseconds] input_search_type: [Input Search Type]

input_search_id: [Input Search ID] output_bpf: [Output BPF]

input_stime_second: [Input Start Time in Seconds] input_xpf: [Input XPF]

output_status": [Output Status]

Response fields

• Input User—User who made the search request.

• Input Limit—Requested maximum number of connection records to find.

• Input End Time in Seconds—The seconds portion of the end time of the search time range.

• Input Hash Field—Hash key for the status of this search.

• Input Create Time—Time at which the search was submitted.

• Input Packet Analysis—Time to analyze input packets.

• Input End Time in Nanoseconds—The nanoseconds portion of the end time of the search time range.

• Input Start Time in Nanoseconds—The nanoseconds portion of the start time of the search time range.

• Input Search Type—Type of search requested: stream or all.

• Input Search ID—Generated search ID that uniquely identifies this search.

• Output BPF—Generated XPF after input_xpf is processed by the PX XPF processing engine.

• Input Start Time in Seconds—The seconds portion of the start time of the search range.

• Input XPF—Filter provided by the end user.

• Output Status—Status of the search. For example, –2 means that the search is queued.

Example

{

"queue": [

{

"input_user": "cpx", "input_limit": "100",

"input_etime_second": "1384442788",

"input_hash_field": "SEARCH_47ba048f10274cbc956fbf937c457b62", "input_create_time": "1384442788",

"input_packet_analyze": "0",

"input_etime_nanoseconds": "0",

"input_stime_nanoseconds": "0", "input_search_type": "all",

"input_search_id": "47ba048f10274cbc956fbf937c457", "output_bpf": "port 80",

"input_stime_second": "1293840000",

"input_xpf": "port 80",

"output_status": "-2"

}

]

}

cURL code sample: List queued searches

The code sample was run with cURL 7.57.0.

curl -k --user cpx:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/queue

This cURL sample includes the following options:

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL

connection without installing a CA certificate.

• --user cpx:hammerhead—Replace cpx with the user name for your PX Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/queue—The search request URL. Replace xxx.xxx.xxx.xxx with the IP address of your Series appliance.

Results

This example displays the contents of the advanced search queue. The output is in JSON.

List saved search definitions request

To list all search definitions that a user has created, send the following request:

GET https://<PX_IP_address>/api/4.0/user/searches

Required header:

--user <username>:<password>

The output is Base64 encoded to avoid recursive escaping of JSON strings. The output contains search-related fields, such as

limit, xpf, etime, and stime.

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Example

GET https://xxx.xxx.xxx.xxx/api/4.0/user/searches

Required header:

--user cpx:hammerhead

List saved search definitions response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type] searches: [Search Definitions] status: [Status]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Search Definitions—List of search definitions.

• Status—A standard HTTP response message.

Example

HTTP/1.1 200 OK

Date: Wed, 09 Mar 2016 23:46:02 GMT

Content-Type: text/html; charset=UTF-8

{

[

“eyJsYWJlbCI6InNhZGRyIiwiY3VzdG9tIjoic3R pbWUlM0EyMDE yMDIwOS4xNjA4NTUlMjBldGlt ZSUzQTIwMTIwMjA5LjE2MTIwNiUyMHNhZGRy J TNBOTYuMjI3LjE1NC4yMCUyMGxpbWl0JT NBNTAwJTIwbGFiZ WwlM0FzYWRkciJ9”,

“eyJsYWJlbCI6IlZhbGlkc2VhcmNoZGF5IiwiY3Vzd G9tIjoic3RpbWUlM0EyMDEyMDIxMC4yMDQ3MTY lMjBsaW1pdCUzQTUwMCUyMGxhYmVsJTNBVmFsaWRz ZWFyY2hkYXkifQ==”,“eyJsYWJlbCI6InRlc3Q iLCJjdXN0b20iOiJzdGltZSUzQTIw MTIwMjE0LjIzNTAz NCUyMGV0aW1lJTNBMjAxMjAyMTQuMjM1NDAwJTIwb

GltaXQlM0E1MDAlMjBsYWJlbCUzQXRlc3QifQ==”

],

“status” : “ok”

}

cURL code sample: List saved search definitions

The code sample was run with cURL 7.57.0.

curl -k --user cpx:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/user/searches

This cURL sample includes the following options:

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• --user cpx:hammerhead—Replace cpx with the user name for your PX Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/user/searches—The search request URL. Replace xxx.xxx.xxx.xxx with the IP address of your Series appliance.

Results

This example lists all search definitions for a user. The output is in Base64-encoded JSON.

Create saved search definitions request

To create a search definition, send the following request:

POST https://<PX_IP_address>/api/4.0/user/searches

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Query Parameters

• stime—Date and time from which the search should start. See Conventions for the format.

• etime—Date and time at which the search should end. See Conventions for the format.

• label—The name of the component.

• window—The window of time before and after the specified start time that should be searched. If stime is used as a parameter, the window parameter is divided by two and subtracted from the stime to make a new start time. The window parameter is added to the original stime to make an etime. If stime is not specified, stime defaults to the current time. If etime and window are not specified, etime defaults to stime + 1 second.

• xpf—Filter to reduce the results set; it supports BPF as defined at http://www.tcpdump.org/manpages/pcap-filter.7.html. It is also used with PX-specific connection attributes, see Connection metadata properties. Sample formatting is host

127.0.0.1 && packetdeltacountin>25.

• limit—The maximum number of connections returned. The default connection limit for asynchronous searches is 100.

• strict—If this parameter is set to true, the search ignores extra VLANs and MPLS unless you specify them in the xpf

parameter. The default value is false.

• ip_list—A comma-separated list of IP addresses to be used as a pre-filter on connections. This parameter is useful for sporadic traffic over a long period of time.

• depth—This search parameter controls what data is processed during a search. There are three types of a searches: connection, packet, and session. The default value is connection. Because a session-depth search includes a packet-depth search and a connection-depth search, session searches take more time than connection or packet searches. A packet-depth search includes a connection-depth search, so packet searches take longer than connection searches. To use less time, execute a connection or packet search instead of a session search and then review the data that was returned.

  • connection: To search connections only, set depth=connection. The "connection" value searches the ultrafast connection index to find information about traffic the Series appliance recorded. These connection records contain address, port, and protocol information, and TCP flags, if appropriate.

  • packet: To search packets and connections only, set depth=packet.

  • session: To initiate session analysis, set depth=session. A session search pulls packets from the PCAP storage and analyzes them in the session analysis engine. Session searches allow you to analyze packets of interest.

Note

Session analysis is a processor-intensive and memory-intensive operation. The higher the connection limit, the longer this request will take. If there are more than 250 connections, session analysis is not recommended.

Example

POST https://xxx.xxx.xxx.xxx/api/4.0/user/ searches?which=mine&searchstring=%7B%22xpf%22%3A%22%22%2C%22stime%22%3A%2220170330.155009%22%2C%22etime%22%3A%2220170330

Required header:

--user cpx:hammerhead

Create saved search definitions response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type] searches: [Searches]

status: [Status]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Searches—A list of saved search definitions in Base64.

• Status—A standard HTTP response message.

Example

HTTP/1.1 200 OK

Date: Fri, 31 Mar 2017 21:49:36 GMT

Content-Type: application/json; charset=utf-8

{

"searches": [ "eyJ4cGYiOiIiLCJzdGltZSI6IjIwMTcwMzMwLjE1NTAwOSIsImV0aW

1lIjoiMjAxNzAzMzAuMTU1NTA5IiwibGltaXQiOiIxMDAiLCJkZXB0aCI6ImNvbm5lY3Rpb24iLCJpcF9saXN0IjoiIiwic291cmNlX2lkIjoiIiwid2lu

],

"status": "ok"

}

cURL code sample: Create saved search definitions

The code sample was run with cURL 7.57.0.

curl -k --user cpx:hammerhead "https://xxx.xxx.xxx.xxx/api/4.0/user/ searches?which=mine&searchstring=%7B%22xpf%22%3A%22%22%2C%22stime%22%3A%2220170330.155009%22%2C%22etime%22%3A%22201703

-X POST

This cURL sample includes the following options:

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL

connection without installing a CA certificate.

• --user cpx:hammerhead—Replace cpx with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• "https://xxx.xxx.xxx.xxx/api/4.0/user/ searches?which=mine&searchstring=%7B%22xpf%22%3A%22%22%2C%22stime%22%3A%2220170330.155009%22%2C%22etime%22%3A%22201 search request URL. Replace xxx.xxx.xxx.xxx with the IP address of your PX Series appliance.

• -X POST—This option specifies using the POST method.

Results

This example creates the specified search definition. The output is in JSON.

Update saved search definitions request

To update a search definition, send the following request:

PUT https://<PX_IP_address>/api/4.0/user/searches

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Query parameters

• stime—Date and time from which the search should start. See Conventions for the format.

• etime—Date and time at which the search should end. See Conventions for the format.

• label—The name of the component.

• window—The window of time before and after the specified start time that should be searched. If stime is used as a parameter, the window parameter is divided by two and subtracted from the stime to make a new start time. The window

parameter is added to the original stime to make an etime. If stime is not specified, stime defaults to the current time. If

etime and window are not specified, etime defaults to stime + 1 second.

• xpf—Filter to reduce the results set; it supports BPF as defined at http://www.tcpdump.org/manpages/pcap-filter.7.html. It is also used with PX-specific connection attributes, see Connection metadata properties. Sample formatting is host

127.0.0.1 && packetdeltacountin>25.

• limit—The maximum number of connections returned. The default connection limit for asynchronous searches is 100.

• strict—If this parameter is set to true, the search ignores extra VLANs and MPLS unless you specify them in the xpf

parameter. The default value is false.

• ip_list—A comma-separated list of IP addresses to be used as a pre-filter on connections. Specifically useful for sporadic traffic over a long period of time.

• depth—This search parameter controls what data is processed during a search. There are three types of a searches: connection, packet, and session. The default value is connection. Because a session-depth search includes a packet-depth search and a connection-depth search, session searches take more time than connection or packet searches. A packet-depth search includes a connection-depth search, so packet searches take longer than connection searches. To use less time, execute a connection or packet search instead of a session search and then review the data that was returned.

  • connection: To search connections only, set depth=connection. The "connection" value searches the ultrafast connection index to find information about traffic the Series appliance recorded. These connection records contain address, port, and protocol information, and TCP flags, if appropriate.

  • packet: To search packets only, set depth=packet.

  • session: To initiate session analysis, set depth=session. As the third main search phase, “session” pulls packets from the PCAP storage and analyzes them in the session analysis engine. Session searches allow you to analyze packets of interest.

Note

Session analysis is a processor-intensive and memory-intensive operation. The higher the connection limit, the longer this request will take. If there are more than 250 connections, session analysis is not recommended.

Example

PUT https://xxx.xxx.xxx.xxx/api/4.0/user/ searches?which=mine&searchstring=%7B%22xpf%22%3A%22%22%2C%22stime%22%3A%2220160330.155009%22%2C%22etime%22%3A%2220160330

Required header:

--user cpx:hammerhead

Update saved search definitions response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type] searches: [Searches]

status: [Status]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Searches—A list of saved search definitions in Base64.

• Status—A standard HTTP response message.

Example

HTTP/1.1 200 OK

Date: Fri, 31 Mar 2017 21:51:03 GMT

Content-Type: application/json; charset=utf-8

{

"searches": [ "eyJ4cGYiOiIiLCJzdGltZSI6IjIwMTcwMzMwLjE1NTAwOSIsI

mV0aW1lIjoiMjAxNzAzMzAuMTU1NTA5IiwibGltaXQiOiIxMDAiLCJkZXB0aCI6ImNvbm5lY3Rpb24iLCJpcF9saXN0IjoiIiwic291cmNlX2lkIjoiIiw "eyJ4cGYiOiIiLCJzdGltZSI6IjIwMTYwMzMwLjE1NTAwOSIsI

mV0aW1lIjoiMjAxNjAzMzAuMTU1NTA5IiwibGltaXQiOiIxMDAiLCJkZXB0aCI6ImNvbm5lY3Rpb24iLCJpcF9saXN0IjoiIiwic291cmNlX2lkIjoiIiw

],

"status": "ok"

}

cURL code sample: Update saved search definitions

The code sample was run with cURL 7.57.0.

curl -k --user cpx:hammerhead "https://xxx.xxx.xxx.xxx/api/4.0/user/ searches?which=mine&searchstring=%7B%22xpf%22%3A%22%22%2C%22stime%22%3A%2220160330.155009%22%2C%22etime%22%3A%2220160330

-X PUT

This cURL sample includes the following options:

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• --user cpx:hammerhead—Replace cpx with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• "https://xxx.xxx.xxx.xxx/api/4.0/user/ searches?which=mine&searchstring=%7B%22xpf%22%3A%22%22%2C%22stime%22%3A%2220160330.155009%22%2C%22etime%22%3A%22201 search request URL. Replace xxx.xxx.xxx.xxx with the IP address of your Series appliance.

• -X PUT—This option specifies using the PUT method.

Results

This example updates the specified search definition. The output is in JSON.

Delete saved search definitions request

To delete a search definition, send the following request:

DELETE https://<PX_IP_address>/api/4.0/user/searches

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Query parameters

• stime—Date and time from which the search should start. See Conventions for the format.

• etime—Date and time at which the search should end. See Conventions for the format.

• label—The name of the component.

• window—The window of time before and after the specified start time that should be searched. If stime is used as a

parameter, the window parameter is divided by two and subtracted from the stime to make a new start time. The window parameter is added to the original stime to make an etime. If stime is not specified, stime defaults to the current time. If etime and window are not specified, etime defaults to stime + 1 second.

• xpf—Filter to reduce the results set; it supports BPF as defined at http://www.tcpdump.org/manpages/pcap-filter.7.html. It is also used with -specific connection attributes, see Connection metadata properties. Sample formatting is host 127.0.0.1 && packetdeltacountin>25.

• limit—The maximum number of connections returned. The default connection limit for asynchronous searches is 100.

• strict—If this parameter is set to true, the search ignores extra VLANs and MPLS unless you specify them in the xpf

parameter. The default value is false.

• ip_list—A comma-separated list of IP addresses to be used as a pre-filter on connections. Specifically useful for sporadic traffic over a long period of time.

• depth—This search parameter controls what data is processed during a search. There are three types of a searches: connection, packet, and session. The default value is connection. Because a session-depth search includes a packet-depth search and a connection-depth search, session searches take more time than connection or packet searches. A packet-depth search includes a connection-depth search, so packet searches take longer than connection searches. To use less time, execute a connection or packet search instead of a session search and then review the data that was returned.

  • connection: To search connections only, set depth=connection. The "connection" value searches the ultrafast connection index to find information about traffic the Series appliance recorded. These connection records contain address, port, and protocol information, and TCP flags, if appropriate.

  • packet: To search packets only, set depth=packet.

  • session: To initiate session analysis, set depth=session. As the third main search phase, “session” pulls packets from the PCAP storage and analyzes them in the session analysis engine. Session searches allow you to analyze packets of interest.

Note

Session analysis is a processor-intensive and memory-intensive operation. The higher the connection limit, the longer this request will take. If there are more than 250 connections, session analysis is not recommended.

Example

DELETE https://xxx.xxx.xxx.xxx/api/4.0/user/ searches?which=mine&searchstring=%7B%22xpf%22%3A%22%22%2C%22stime%22%3A%2220160330.155009%22%2C%22etime%22%3A%22201603

Required header:

--user cpx:hammerhead

Delete saved search definitions response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

Example

HTTP/1.1 200 OK

Date: Fri, 31 Mar 2017 21:52:04 GMT

Content-Type: text/plain; charset=utf-8

cURL code sample: Delete saved search definitions

The code sample was run with cURL 7.57.0.

curl -k --user cpx:hammerhead "https://xxx.xxx.xxx.xxx/api/4.0/user/ searches?which=mine&searchstring=%7B%22xpf%22%3A%22%22%2C%22stime%22%3A%2220160330.155009%22%2C%22etime%22%3A%22201603

-X DELETE

This cURL sample includes the following options:

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• --user cpx:hammerhead—Replace cpx with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• "https://xxx.xxx.xxx.xxx/api/4.0/user/ searches?which=mine&searchstring=%7B%22xpf%22%3A%22%22%2C%22stime%22%3A%2220160330.155009%22%2C%22etime%22%3A%22201 search request URL. Replace xxx.xxx.xxx.xxx with the IP address of your PX Series appliance.

• -X DELETE—This option specifies using the DELETE method.

Results

This example deletes the specified search definition. The output is in JSON.

Component configuration

Use the component configuration endpoints to find which components can be configured and then change their values or restore the default values:

• List components request

GET https://<PX_IP_address>/api/4.0/config

• List component details request

GET https://<PX_IP_address>/api/4.0/config/<component>

• Configure ACM request

POST https://<PX_IP_address>/api/4.0/config/acm

• Configure authentication request

POST https://<PX_IP_address>/api/4.0/config/auth

• Configure capture request

POST https://<PX_IP_address>/api/4.0/config/px-capture

• Configure data exfiltration detection request

POST https://<PX_IP_address>/api/4.0/config/exfil

• Configure IA export request

POST https://<PX_IP_address>/api/4.0/config/ia

• Configure IPMI request

POST https://<PX_IP_address>/api/4.0/config/ipmi

• Configure IPTables request

POST https://<PX_IP_address>/api/4.0/config/iptables

• Configure iSight rule loader request

POST https://<PX_IP_address>/api/4.0/config/isight-rule-loader

• Configure network request

POST https://<PX_IP_address>/api/4.0/config/net

• Configure NTP request

POST https://<PX_IP_address>/api/4.0/config/ntp

• Configure PX-eve-route request

POST https://<PX_IP_address>/api/4.0/config/px-eve-route

• Configure SNMP request

POST https://<PX_IP_address>/api/4.0/config/snmp

• Configure system logging request

POST https://<PX_IP_address>/api/4.0/config/syslog

• Restore default component configuration request

DELETE https://<PX_IP_address>/api/4.0/config/<component>

• Synchronization state request

GET https://<PX_IP_address>/api/4.0/config/<component>/status

List components request

To list the components that can be configured, send the following request:

GET https://<PX_IP_address>/api/4.0/config

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Example

GET https://xxx.xxx.xxx.xxx/api/4.0/config

Required header:

--user cpx:hammerhead

List components response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type] [component1, component2, component3,...]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• component—Any component that can be configured.

Example

HTTP/1.1 200 OK

Date: Tue, 7 May 2019 21:26:15 GMT

Content-Type: application/json; charset=utf-8 [

"2fa",

"acm",

"auth", "backups", "disk",

"dti",

"exfil",

"export",

"ipmi", "iptables",

"isight-rule-loader", "net",

"ntp", "packetfilters", "px-aggregator", "px-capture",

"px-eve-route",

"px-purge",

"snmp", "suricata", "sysdump", "syslog",

"tap-filter",

"traps", "users"

]

cURL code sample: List components

The code sample was run with cURL 7.57.0.

curl -k --user npadmin:hammerhead

-g "https://<host>/api/4.0/config"

This cURL sample includes the following options:

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• --user npadmin:hammerhead—Replace npadmin with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• -g—This option allows URLs that contain {}[].

• "https://<host>/api/4.0/config"—The component configuration request URL. Replace <host> with the IP address of your Series appliance.

Results

This example returns a list of components that can be configured. The output is in JSON.

List component details request

To get details about a specific component, send the following request:

GET https://<PX_IP_address>/api/4.0/config/<component>

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

• component—Part of the Series appliance. See List components request for supported components.

Example

GET https://xxx.xxx.xxx.xxx/api/4.0/config/ntp

Required header:

--user cpx:hammerhead

List component details response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type] description: [Description] fields: [Fields]

label: [Label] values: [Values]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Description—A description of the component.

• Fields—Fields list different options for each component.

• Label—The name of the component.

• Values—Values for various fields.

Example

HTTP/1.1 200 OK

Date: Thu, 26 Jan 2017 23:20:07 GMT

Content-Type: application/json; charset=utf-8

{

"description": "NTP config to list NTP servers on the network", "fields": {

"servers": {

"description": "Address of NTP Servers", "label": "Servers",

"type": "address"

}

},

"label": "NTP", "values": {

"servers": [

"iad-ntp1.eng.fireeye.com"

]

}

}

cURL code sample: List component details

The code sample was run with cURL 7.57.0.

curl -k --user cpx:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/ntp

This cURL sample includes the following options:

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• --user cpx:hammerhead—Replace cpx with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/ntp—The component configuration request URL. Replace xxx.xxx.xxx.xxx

with the IP address of your Series appliance. Replace ntp with the component of interest.

Results

This example returns the details for the specified component. The output is in JSON.

Configure ACM request

To configure the Access Control Manager (ACM), send one of the following requests:

POST https://<PX_IP_address>/api/4.0/config/acm

PUT https://<PX_IP_address>/api/4.0/config/acm

Note

To use this request, you must belong to the sudo group.

You cannot update the ACM while it is being synchronized or if a system upgrade, backup, or restore is in progress.

Required header:

--user <username>:<password>

Request body:

{

inactiveTimeout: INT, maxSessionAge: INT

}

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Parameters

• inactiveTimeout—The number of seconds before the session becomes inactive. The value is an integer, and the range is 60 to 3600.

• maxSessionAge—The maximum number of seconds before a session terminates. The value is an integer, and the range is 600 to 2592000.

Example

POST https://xxx.xxx.xxx.xxx/api/4.0/config/acm

Required header:

--user npadmin:hammerhead

Request body:

{

"values": { "inactiveTimeout": [

700

],

"maxSessionAge": [ 80000

]

}

}

Configure ACM response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type] description: [Description} fields: [Fields]

label: [Label]

inactiveTimeout: [Inactive Timeout] maxSessionAge: [Maximum Session Age]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Description—A description of ACM.

• Fields—ACM options.

• Label—The name of the component.

• Inactive Timeout—The number of seconds before the session becomes inactive.

• Maximum Session Age—The maximum number of seconds before a session terminates.

Example

HTTP/1.1 200 OK

Date: Fri, 27 Jan 2017 21:50:28 GMT

Content-Type: application/json; charset=utf-8

{

"description": "ACM manages http access to back-end services", "fields": {

"inactiveTimeout": { "default": [

600

],

"description": "Time before session becomes inactive", "label": "Inactive Timeout",

"maxCount": 1,

"maxValue": 3600,

"minCount": 1,

"minValue": 60, "type": "int"

},

"maxSessionAge": { "default": [

86400

],

"description": "Maximum age of a session before it terminates", "label": "Maximum Session Age",

"maxCount": 1,

"maxValue": 2592000,

"minCount": 1,

"minValue": 600, "type": "int"

}

},

"label": "ACM", "values": {

"inactiveTimeout": [ 700

],

"maxSessionAge": [ 80000

]

}

}

cURL code sample: Configure ACM

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/acm -k -X PUT --data-binary '{"values":

{"inactiveTimeout": [700],"maxSessionAge": [80000]}}'

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with the user name for your Series appliance. Replace hammerhead with the password for your PX Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/acm—The component configuration request URL. Replace xxx.xxx.xxx.xxx

with the IP address of your Series appliance.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X PUT—This option specifies using the PUT method.

• --data-binary '{"values": {"inactiveTimeout": [700],"maxSessionAge": [80000]}}'—This option specifies the changes to make to ACM.

Results

This example updates the ACM configuration. The output is in JSON.

Configure authentication request

To configure user authentication, send one of the following requests:

POST https://<PX_IP_address>/api/4.0/config/auth

PUT https://<PX_IP_address>/api/4.0/config/auth

Note

To use this request, you must belong to the sudo group.

You cannot update authentication while it is being synchronized or if a system upgrade, backup, or restore is in progress.

Required header:

--user <username>:<password>

Request body:

{

ldapbase: 'TEXT', ldapbinddn: 'TEXT', ldapbindpw: 'TEXT', ldaphost: 'TEXT', ldapsudo: 'TEXT', ldapuiapi: 'TEXT',

radiussecret: 'TEXT', radiusserver: 'TEXT', tacacssecret: 'TEXT', tacacsserver: 'TEXT', type: 'TEXT'

}

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Parameters

• ldapbase—The default base distinguished name (DN) to use when performing lightweight directory access protocol (LDAP) operations. The base must be specified as a DN in LDAP format. If type is ldap or active-directory, this field can be empty or have one value.

• ldapbinddn—The default bind DN to use when performing LDAP operations. The bind DN must be specified as a DN in LDAP format. This field can be empty or have one value. If type is ldap or active-directory and this field is set, ldapbindpw must also be set.

• ldapbindpw—The password used when binding to the LDAP server. This field can be empty or have one value. If type is

ldap or active-directory and this field is set, ldapbinddn must also be set.

• ldaphost—The names of LDAP servers to which the LDAP library connects. Each server consists of an address and optional port number. If type is ldap or active-directory, this field must have at least one name.

• ldapsudo—The name of an LDAP or AD group. Membership in this group is required for sudo access on the Series appliance.

• ldapuiapi—The name of an LDAP or AD group. Membership in this group is required for uiapi access on the Series appliance.

• radiussecret—The RADIUS shared secret that accompanies each RADIUS server. If type is radius, this field is required.

• radiusserver—The names of RADIUS servers to which the RADIUS library connects. Each server consists of an address and optional port number. If type is radius, this field must have at least one name.

tacacssecret—The TACACS+ shared secret that accompanies each TACACS+ server. If type is tacacs, this field is required.

tacacsserver—The names of TACACS+ servers to which the TACACS+ library connects. Each server consists of an address and optional port number. If type is tacacs, this field must have at least one name.

type—The authentication type. Valid values are pam, ldap, tacacs, radius, or active-directory.

Example

POST https://xxx.xxx.xxx.xxx/api/4.0/config/auth

Required header:

--user npadmin:hammerhead

Request body:

{

"values": {

"ldapbase": [

"ou=IT staff,o=\"Example, Inc\",c=US"

],

"ldapbinddn": [

"ldapsearch -h 1.2.3.4 -D dc=example,dc=com [query]"

],

"ldapbindpw": [ "9H47nWdE5U"

],

"ldaphost": [

{

"address": [ "ldap1.server.com"

],

"port": [ 389

]

},

{

"address": [ "ldap2.server.com"

]

}

],

"radiussecret": [],

"radiusserver": [],

"tacacssecret": [],

"tacacsserver": [], "type": [

"ldap"

]

}

}

Configure authentication response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type] description: [Description]

fields: [Fields] label: [Label] ldapbase: [LDAP Base]

ldapbindn: [LDAP Bind DN] ldapbindpw: [LDAP Bind Password] ldaphost: [LDAP Host] radiussecret: [RADIUS Secret] radiusserver: [RADIUS Server] tacacssecret: [TACACS Secret] tacacsserver: [TACACS Server] type: [Type]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Description—A description of authentication.

• Fields—Fields list authentication options.

• Label—The name of the component.

• LDAP Base—The default base DN to use when performing LDAP operations.

• LDAP Bind DN—The default bind DN to use when performing LDAP operations.

• LDAP Bind Password—The password used when binding to the LDAP server.

• LDAP Host—The names of LDAP servers to which the LDAP library connects.

• RADIUS Secret—The RADIUS shared secret that accompanies each RADIUS server.

• RADIUS Server—The names of RADIUS servers to which the RADIUS library connects.

• TACACS Secret—The TACACS+ shared secret that accompanies each TACACS+ server.

• TACACS Server—The names of TACACS+ servers to which the TACACS+ library connects.

• Type—The authentication type.

Example

HTTP/1.1 200 OK

Date: Mon, 06 Feb 2017 19:14:13 GMT

Content-Type: application/json; charset=utf-8

{

"description": "Auth config to select and configure authentication", "fields": {

"ldapbase": {

"description": "LDAP base DN", "label": "LDAP base DN", "maxCount": 1,

"maxValue": 255,

"minCount": 0,

"minValue": 1,

"type": "string"

},

"ldapbinddn": {

"description": "LDAP Bind DN", "label": "LDAP Bind DN", "maxCount": 1,

"maxValue": 255,

"minCount": 0,

"minValue": 1,

"type": "string"

},

"ldapbindpw": {

"description": "LDAP Bind PW", "label": "LDAP Bind PW", "maxCount": 1,

"maxValue": 255,

"minCount": 0,

"minValue": 1,

"type": "string"

},

"ldaphost": {

"description": "LDAP Servers", "fields": {

"address": {

"description": "LDAP server Address", "label": "Address",

"maxCount": 1,

"minCount": 1,

"type": "address"

},

"port": {

"description": "LDAP server port (optional)", "label": "Port",

"maxCount": 1,

"maxValue": 65535,

"minCount": 0,

"minValue": 0,

"type": "int"

}

},

"label": "LDAP host",

"type": "object"

},

"radiussecret": {

"description": "Radius Secret", "label": "Radius Secret", "maxCount": 1,

"maxValue": 255,

"minCount": 0,

"minValue": 1,

"type": "string"

},

"radiusserver": {

"description": "Radius Servers", "fields": {

"address": {

"description": "Radius server address", "label": "Address",

"maxCount": 1,

"minCount": 1,

"type": "address"

},

"port": {

"description": "Radius server port (optional)", "label": "Port",

"maxCount": 1,

"maxValue": 65535,

"minCount": 0,

"minValue": 0,

"type": "int"

}

},

"label": "Radius Server", "maxCount": 20,

"minCount": 0,

"type": "object"

},

"tacacssecret": {

"description": "TACACS+ Secret", "label": "TACACS+ Secret", "maxCount": 1,

"maxValue": 255,

"minCount": 0,

"minValue": 1,

"type": "string"

},

"tacacsserver": {

"description": "TACACS+ Servers", "fields": {

"address": {

"description": "TACACS+ server address", "label": "Address",

"maxCount": 1,

"minCount": 1,

"type": "address"

},

"port": {

"description": "TACACS+ server port (optional)", "label": "Port",

"maxCount": 1,

"maxValue": 65535,

"minCount": 0,

"minValue": 0,

"type": "int"

}

},

"label": "TACACS+ Server", "maxCount": 20,

"minCount": 0,

"type": "object"

},

"type": {

"default": [ "pam"

],

"description": "Type of authentication to use", "enums": [

"pam",

"ldap",

"tacacs",

"radius",

"active-directory"

],

"label": "Authentication Type", "maxCount": 1,

"minCount": 1,

"type": "enum"

}

},

"label": "Authentication", "values": {

"ldapbase": [

"ou=IT staff,o=\"Example, Inc\",c=US"

],

"ldapbinddn": [

"ldapsearch -h 1.2.3.4 -D dc=example,dc=com [query]"

],

"ldapbindpw": [ "9H47nWdE5U"

],

"ldaphost": [

{

"address": [ "ldap1.server.com"

],

"port": [ 389

]

},

{

"address": [ "ldap2.server.com"

]

}

],

"radiussecret": [],

"radiusserver": [],

"tacacssecret": [],

"tacacsserver": [], "type": [

"ldap"

]

}

}

cURL code sample: Configure authentication

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/auth

-k -X PUT --data-binary '{"values": {"ldapbase": ["ou=IT staff,o=\"Example, Inc\",c=US"],"ldapbinddn": ["ldapsearch -h 1.2.3.4 -D dc=example,dc=com [query]"],"ldapbindpw": ["9H47nWdE5U"],"ldaphost": [{"address": ["ldap1.server.com"],"port": [389]},{"address": ["ldap2.server.com"]}],"radiussecret": [],"radiusserver": [],"tacacssecret": [],"tacacsserver": [],"type": ["ldap"]}}'

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with the user name for your Series appliance. Replace hammerhead with the password for your PX Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/auth—The component configuration request URL. Replace xxx.xxx.xxx.xxx

with the IP address of your Series appliance.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X PUT—This option specifies using the PUT method.

• --data-binary '{"values": {"ldapbase": ["ou=IT staff,o=\"Example, Inc\",c=US"],"ldapbinddn": ["ldapsearch

-h 1.2.3.4 -D dc=example,dc=com [query]"],"ldapbindpw": ["9H47nWdE5U"],"ldaphost": [{"address":

["ldap1.server.com"],"port": [389]},{"address": ["ldap2.server.com"]}],"radiussecret": [],"radiusserver": [],"tacacssecret": [],"tacacsserver": [],"type": ["ldap"]}}'—This option specifies the changes to make to authentication.

Results

This example updates the values for user authentication. The output is in JSON.

Configure capture request

To configure px-capture, send one of the following requests:

POST https://<PX_IP_address>/api/4.0/config/px-capture

PUT https://<PX_IP_address>/api/4.0/config/px-capture

Note

To use this request, you must belong to the sudo group.

You cannot update capture while it is being synchronized or if a system upgrade, backup, or restore is in progress.

Required header:

--user <username>:<password>

Request body:

{

captureFormat: 'TEXT', captureStream0: BOOLEAN,

captureStream1: BOOLEAN, captureStream2: BOOLEAN, captureStream3: BOOLEAN, classification: BOOLEAN, enableToggleStreams: BOOLEAN, tunnelDecoding: BOOLEAN

}

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Parameters

• captureFormat—The time format for packet capture data. Valid values are "nanosecond (nsec)" and "microsecond (usec)".

• captureStream0—If enableToggleStreams is set to true, this parameter determines whether stream 0 is enabled. Valid values are true and false.

• captureStream1—If enableToggleStreams is set to true, this parameter determines whether stream 1 is enabled. Valid values are true and false.

• captureStream2—If enableToggleStreams is set to true, this parameter determines whether stream 2 is enabled. Valid values are true and false.

• captureStream3—If enableToggleStreams is set to true, this parameter determines whether stream 3 is enabled. Valid values are true and false.

• classification—This parameter determines whether the classifier is enabled. Valid values are true and false.

• enableToggleStreams—This parameter determines whether individual streams can be enabled and disabled. Valid values are true and false.

• tunnelDecoding—This parameter determines whether flow records are generated for the innermost or outermost layer of data for generic routing encapsulation (GRE) tunnel data. Valid values are true and false.

Example

POST https://xxx.xxx.xxx.xxx/api/4.0/config/px-capture

Required header:

--user npadmin:hammerhead

Request body:

{

"values": { "captureFormat": [

"microsecond (usec)"

],

"captureStream0": [ true

],

"captureStream1": [ true

],

"captureStream2": [ false

],

"captureStream3": [ false

],

"classification": [ true

],

"enableToggleStreams": [ true

],

"tunnelDecoding": [ true

]

}

}

Configure capture response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type] description: [Description} fields: [Fields]

label: [Label]

captureFormat: [Capture Format] captureStream0: [Capture Stream 0] captureStream1: [Capture Stream 1] captureStream2: [Capture Stream 2] captureStream3: [Capture Stream 3] classification: [Classification] enableToggleStreams: [Toggle Streams] tunnelDecoding: [Tunnel Decoding]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Description—A description of px-capture.

• Fields—Fields list px-capture options.

• Label—The name of the component.

• Capture Format—The time format for packet capture data.

• Capture Stream 0—If Toggle Streams is set to true, this parameter determines whether stream 0 is enabled.

• Capture Stream 1—If Toggle Streams is set to true, this parameter determines whether stream 1 is enabled.

• Capture Stream 2—If Toggle Streams is set to true, this parameter determines stream 2 is enabled.

• Capture Stream 3—If Toggle Streams is set to true, this parameter determines whether stream 3 is enabled.

• Classification—This parameter determines whether the classifier is enabled.

• Toggle Streams—This parameter determines whether individual streams can be enabled and disabled.

• Tunnel Decoding—This parameter determines whether flow records are generated for the innermost or outermost layer of data for GRE tunnel data.

Example

HTTP/1.1 200 OK

Date: Mon, 06 Feb 2017 22:42:46 GMT

Content-Type: application/json; charset=utf-8

{

"description": "Configure PX-Capture", "fields": {

"captureFormat": { "default": [

"nanosecond (nsec)"

],

"description": "Time format for captured data", "enums": [

"nanosecond (nsec)", "microsecond (usec)"

],

"label": "Capture Format", "maxCount": 1,

"minCount": 1,

"type": "enum"

},

"captureStream0": { "default": [

true

],

"description": "Toggle capture stream 0", "falseLabel": "Disabled",

"label": "Capture Stream 0", "maxCount": 1,

"minCount": 1, "trueLabel": "Enabled", "type": "bool"

},

"captureStream1": { "default": [

true

],

"description": "Toggle capture stream 1", "falseLabel": "Disabled",

"label": "Capture Stream 1", "maxCount": 1,

"minCount": 1, "trueLabel": "Enabled", "type": "bool"

},

"captureStream2": { "default": [

true

],

"description": "Toggle capture stream 2", "falseLabel": "Disabled",

"label": "Capture Stream 2", "maxCount": 1,

"minCount": 1, "trueLabel": "Enabled", "type": "bool"

},

"captureStream3": { "default": [

true

],

"description": "Toggle capture stream 3", "falseLabel": "Disabled",

"label": "Capture Stream 3", "maxCount": 1,

"minCount": 1, "trueLabel": "Enabled", "type": "bool"

},

"classification": { "default": [

true

],

"description": "Toggle classification", "falseLabel": "Disabled",

"label": "Classification", "maxCount": 1,

"minCount": 1, "trueLabel": "Enabled",

"type": "bool"

},

"tunnelDecoding": { "default": [

false

],

"description": "Toggle tunnel decoding", "falseLabel": "Disabled",

"label": "Tunnel Decoding", "maxCount": 1,

"minCount": 1, "trueLabel": "Enabled", "type": "bool"

}

},

"label": "Capture", "values": {

"captureFormat": [ "microsecond (usec)"

],

"captureStream0": [ true

],

"captureStream1": [ true

],

"captureStream2": [ false

],

"captureStream3": [ false

],

"classification": [ true

],

"enableToggleStreams": [ true

],

"tunnelDecoding": [ true

]

}

}

cURL code sample: Configure capture

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/px-capture -k -X POST

--data-binary '{"values": {"captureFormat": ["microsecond (usec)"],"captureStream0": [true], "captureStream1": [true], "captureStream2": [false], "captureStream3": [false], "classification": [true], "enableToggleStreams": [true],"tunnelDecoding": [true]}}'

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/px-capture—The component configuration request URL. Replace

xxx.xxx.xxx.xxx with the IP address of your Series appliance.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X POST—This option specifies using the POST method.

• --data-binary '{"values": {"captureFormat": ["microsecond (usec)"],"captureStream0": [true], "captureStream1": [true], "captureStream2": [false], "captureStream3": [false], "classification": [true], "enableToggleStreams": [true],"tunnelDecoding": [true]}}'—This option specifies the changes to make to PX capture.

Results

This example updates the values for px-capture. The output is in JSON.

Configure data exfiltration detection request

You can write Suricata rules using the HOME_NET variable to detect data exfiltration if you define your internal network. To define IP addresses as internal addresses, send one of the following requests:

POST https://<PX_IP_address>/api/4.0/config/exfil

PUT https://<PX_IP_address>/api/4.0/config/exfil

Note

To use this request, you must belong to the sudo group.

You cannot update data exfiltration detection while it is being synchronized or if a system upgrade, backup, or restore is in progress.

Required header:

--user <username>:<password>

Request body:

{

enabled: Boolean, homeNet: 'IP_address'

}

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Parameters

• enabled—Whether the date exfiltration detection is active. When enabled is set to true, you can configure the HOME_NET variable for Suricata rule sets. Valid values are true and false.

• homeNet—Optional. A list of IP address for the home network in classless inter-domain routing (CIDR) notation.

Example

POST https://xxx.xxx.xxx.xxx/api/4.0/config/exfil

Required header:

--user npadmin:hammerhead

Request body:

{

"values": {

"enabled": [ true

],

"homeNet": [ "192.168.0.0/16",

"10.0.0.0/8",

"172.16.0.0/12"

]

}

}

Configure data exfiltration detection response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type] description: [Description} fields: [Fields]

label: [Label]

enabled: [Enabled] homeNet: [Home Net]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Description—A description of data exfiltration detection.

• Fields—Fields list data exfiltration detection options.

• Label—The name of the component.

• Enabled—Whether the data exfiltration detection service is active.

• Home Net—A list of IP address for the home network in CIDR notation.

Example

HTTP/1.1 200 OK

Date: Wed, 22 Mar 2017 17:58:38 GMT

Content-Type: application/json; charset=utf-8

{

"description": "Configure Exfil Detection", "fields": {

"enabled": {

"default": [ false

],

"description": "Enable/Disable Exfil Detection Service", "falseLabel": "Disabled",

"label": "Exfil Detection", "maxCount": 1,

"minCount": 1, "trueLabel": "Enabled", "type": "bool"

},

"homeNet": {

"default": [ "192.168.0.0/16",

"10.0.0.0/8",

"172.16.0.0/12"

],

"description": "Home network addresses in CIDR notation", "label": "Home network addresses",

"minCount": 0,

"type": "cidr"

}

},

"label": "Exfil", "values": {

"enabled": [ true

],

"homeNet": [ "192.168.0.0/16",

"10.0.0.0/8",

"172.16.0.0/12"

]

}

}

cURL code sample: Configure data exfiltration detection

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/exfil

-k -X POST

--data-binary '{"values": {"enabled": [true],"homeNet": ["192.168.0.0/16","10.0.0.0/8","172.16.0.0/12"]}}'

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/exfil—The component configuration request URL. Replace xxx.xxx.xxx.xxx

with the IP address of your Series appliance.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X POST—This option specifies using the POST method.

• --data-binary '{"values": {"enabled": [true],"homeNet": ["192.168.0.0/16","10.0.0.0/8","172.16.0.0/ 12"]}}'—This option specifies the changes to make to data exfiltration detection.

Results

This example enables data exfiltration detection and defines which IP addresses are internal addresses. The output is in JSON.

Configure IPMI request

To configure the Intelligent Platform Management Interface (IPMI), send one of the following requests:

POST https://<PX_IP_address>/api/4.0/config/ipmi

PUT https://<PX_IP_address>/api/4.0/config/ipmi

Note

To use this request, you must belong to the sudo group.

You cannot update IPMI while it is being synchronized or if a system upgrade, backup, or restore is in progress.

Required header:

--user <username>:<password>

Request body:

{

dhcp: Boolean ip: 'ipv4' gateway: 'ipv4' netmask: 'ipv4'

}

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Parameters

• description—A description of the component.

• fields—Fields list different options for each component. Fields cannot be changed.

• label—The name of the component.

• dhcp—If dhcp is set to true, the ip, gateway, and netmask fields are set automatically. Valid values are true and false.

• ip—IPMI IPv4 address. When dhcp is set to false, this parameter is required. When dhcp is set to true, this parameter is optional.

• gateway—IPMI IPv4 gateway address. When dhcp is set to false, this parameter is required. When dhcp is set to true, this parameter is optional.

• netmask—IPMI IPv4 netmask. When dhcp is set to false, this parameter is required. When dhcp is set to true, this parameter is optional.

Example

POST https://xxx.xxx.xxx.xxx/api/4.0/config/ipmi

Required header:

--user npadmin:hammerhead

Request body:

{

"values": {

"dhcp": [ false

],

"ip": [ "xxx.xxx.xxx.xxx"

],

"gateway": [ "xxx.xxx.xxx.xxx"

],

"netmask": [ "xxx.xxx.xxx.xxx"

]

}

}

Configure IPMI response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type] description: [Description] fields: [Fields]

label: [Label] dhcp: [DHCP] ip: [IP]

gateway: [Gateway] netmask: [Netmask]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Description—A description of the component.

• Fields—Fields list different options for each component.

• Label—The name of the component.

• DHCP—If dhcp is set to true, the ip, gateway, and netmask fields are set automatically.

• IP—IPMI IP address.

• Gateway—IPMI gateway address.

• Netmask—IPMI netmask.

Example

HTTP/1.1 200 OK

Date: Tue, 07 Feb 2017 16:53:20 GMT

Content-Type: application/json; charset=utf-8

{

"description": "IPMI configuration", "fields": {

"dhcp": {

"default": [ false

],

"description": "Enable DHCP - Selecting true will ignore the other fields.", "label": "Enable DHCP",

"maxCount": 1,

"minCount": 1,

"type": "bool"

},

"gateway": {

"default": [

"0.0.0.0"

],

"description": "Must be an IPv4 address.", "label": "Gateway Address",

"maxCount": 1,

"minCount": 0,

"type": "ipv4"

},

"ip": {

"default": [

"0.0.0.0"

],

"description": "Must be an IPv4 address.", "label": "IP Address",

"maxCount": 1,

"minCount": 0,

"type": "ipv4"

},

"netmask": {

"default": [

"0.0.0.0"

],

"description": "Must be an IPv4 netmask.", "label": "Netmask",

"maxCount": 1,

"minCount": 0,

"type": "ipv4"

}

},

"label": "IPMI", "values": {

"dhcp": [s true

],

"gateway": [ "xxx.xxx.xxx.xxx"

],

"ip": [ "xxx.xxx.xxx.xxx"

],

"netmask": [ "xxx.xxx.xxx.xxx"

]

}

}

cURL code sample: Configure IPMI

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/ipmi

-k -X POST --data-binary '{"values": {"dhcp": [true],"gateway": ["xxx.xxx.xxx.xxx"],"ip": ["xxx.xxx.xxx.xxx"],"netmask": ["xxx.xxx.xxx.xxx"]}}'

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/ipmi—The component configuration request URL. Replace xxx.xxx.xxx.xxx

with the IP address of your Series appliance.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X POST—This option specifies using the POST method.

• --data-binary '{"values": {"dhcp": [true],"gateway": ["xxx.xxx.xxx.xxx"],"ip": ["xxx.xxx.xxx.xxx"],"netmask": ["xxx.xxx.xxx.xxx"]}}'—This option specifies the changes to make to IPMI.

Results

This example updates the values for IPMI. The output is in JSON.

Configure IPTables request

To configure IPTables and IP6Tables to manage the Series appliance's firewall, send one of the following requests:

POST https://<PX_IP_address>/api/4.0/config/iptables

PUT https://<PX_IP_address>/api/4.0/config/iptables

Note

To use this request, you must belong to the sudo group.

You cannot update IPTables or IP6Tables while they are being synchronized or if a system upgrade, backup, or restore is in progress.

Required header:

--user <username>:<password>

Request body:

{

nagios: Boolean, nagiosport: int, openvpn: Boolean, openvpnport: int, puppet: Boolean, puppetport: int, snmp: Boolean, snmpport: int}

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Parameters

• nagios—Determines whether Nagios is enabled. Valid values are true and false.

• nagiosport—Nagios port.

• openvpn—Determines whether OpenVPN is enabled. Valid values are true and false.

• openvpnport—OpenVPN port.

• puppet—Determines whether Puppet is enabled. Valid values are true and false.

• puppetport—Puppet port.

• snmp—Determines whether SNMP is enabled.. Valid values are true and false.

• snmpport—SNMP port.

Example

POST https://xxx.xxx.xxx.xxx/api/4.0/config/iptables

Required header:

--user npadmin:hammerhead

Request body:

{

"values": {

"nagios": [ true

],

"nagiosport": [ 5666

],

"openvpn": [ true

],

"openvpnport": [ 1194

],

"puppet": [ false

],

"puppetport": [ 8139

],

"snmp": [ true

],

"snmpport": [ 161

]

}

}

Configure IPTables response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type] description: [Description] fields: [Fields]

label: [Label] nagios: [Nagios]

nagiosport: [Nagios Port] openvpn: [OpenVPN] openvpnport: [OpenVPN] puppet: [Puppet] puppetport: [PuppetPort] snmp: [SNMP]

snmpport: [SNMP Port]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Description—A description of the component.

• Fields—Fields list different options for each component.

• Label—The name of the component.

• Nagios—Whether Nagios is enabled.

• Nagios Port—The port that Nagios is using.

• OpenVPN—Whether OpenVPN is enabled.

• OpenVPN Port—The port that OpenVPN is using.

• Puppet—Whether Puppet is enabled.

• Puppet Port—The port that Puppet is using.

• SNMP—Whether SNMP is enabled.

• SNMP Port—The port that SNMP is using.

Example

HTTP/1.1 200 OK

Date: Tue, 07 Feb 2017 17:54:27 GMT

Content-Type: application/json; charset=utf-8

{

"description": "IP Tables configuration", "fields": {

"nagios": {

"default": [ false

],

"description": "Enable/disable Nagios", "falseLabel": "Disabled",

"label": "Nagios", "maxCount": 1,

"minCount": 1, "trueLabel": "Enabled", "type": "bool"

},

"nagiosport": { "default": [

5666

],

"description": "Nagios port", "label": "Nagios Port", "maxCount": 1,

"maxValue": 65535,

"minCount": 0,

"minValue": 1,

"type": "int"

},

"openvpn": {

"default": [ false

],

"description": "Enable/disable OpenVPN", "falseLabel": "Disabled",

"label": "OpenVPN", "maxCount": 1,

"minCount": 1, "trueLabel": "Enabled", "type": "bool"

},

"openvpnport": { "default": [

1194

],

"description": "OpenVPN Port", "label": "OpenVPN Port", "maxCount": 1,

"maxValue": 65535,

"minCount": 0,

"minValue": 1,

"type": "int"

},

"puppet": {

"default": [ false

],

"description": "Enable/disable Puppet", "falseLabel": "Disabled",

"label": "Puppet", "maxCount": 1,

"minCount": 1, "trueLabel": "Enabled", "type": "bool"

},

"puppetport": { "default": [

8139

],

"description": "Puppet Port", "label": "Puppet Port", "maxCount": 1,

"maxValue": 65535,

"minCount": 0,

"minValue": 1,

"type": "int"

},

"snmp": {

"default": [ false

],

"description": "Enable/disable SNMP", "falseLabel": "Disabled",

"label": "SNMP", "maxCount": 1,

"minCount": 1, "trueLabel": "Enabled", "type": "bool"

},

"snmpport": {

"default": [ 161

],

"description": "SNMP Port", "label": "SNMP Port", "maxCount": 1,

"maxValue": 65535,

"minCount": 0,

"minValue": 1,

"type": "int"

}

},

"label": "IP Tables", "values": {

"nagios": [ true

],

"nagiosport": [ 5666

],

"openvpn": [ true

],

"openvpnport": [ 1194

],

"puppet": [ false

],

"puppetport": [ 8139

],

"snmp": [ true

],

"snmpport": [ 161

]

}

}

cURL code sample: Configure IPTables

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/iptables -k -X POST --data-binary '{"values": {"nagios": [true],"nagiosport": [5666],"openvpn": [true],"openvpnport": [1194],"puppet": [false],"puppetport": [8139],"snmp": [true],"snmpport": [161]}}'

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with the user name for your Series appliance. Replace hammerhead with the password for your PX Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/iptables—The component configuration request URL. Replace

xxx.xxx.xxx.xxx with the IP address of your Series appliance.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X POST—This option specifies using the POST method.

• --data-binary '{"values": {"nagios": [true],"nagiosport": [5666],"openvpn": [true],"openvpnport": [1194],"puppet": [false],"puppetport": [8139],"snmp": [true],"snmpport": [161]}}'—This option specifies the changes to make to IPTables and IP6Tables.

Results

This example updates the values for IPTables and IP6Tables. The output is in JSON.

Configure iSight rule loader request

To configure the iSIGHT rule loader, send one of the following requests:

POST https://<PX_IP_address>/api/4.0/config/isight-rule-loader

PUT https://<PX_IP_address>/api/4.0/config/isight-rule-loader

Note

To use this request, you must belong to the sudo group.

You cannot update iSight rule loader while it is being synchronized or if a system upgrade, backup, or restore is in progress.

Required header:

--user <username>:<password>

Request body:

{

enabled: BOOLEAN, retentionSpan: INT, secretKey: 'TEXT', userKey: 'TEXT'

}

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Parameters

• enabled—Determines whether the iSight rule loader is enabled. Valid values are true and false.

• retentionSpan—The number of days to retain rule sets.

• secretKey—iSIGHT subscriber secret key.

• userKey—iSIGHT subscriber API key.

Example

POST https://xxx.xxx.xxx.xxx/api/4.0/config/isight-rule-loader

Required header:

--user npadmin:hammerhead

Request body:

{

"values": {

"enabled": [ false

],

"retentionSpan": [ 30

],

"secretKey": [ "abcdefghijk"

],

"userKey": [ "lmnopqrstuvw"

]

}

}

Configure iSight rule loader response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type] description: [Description] fields: [Fields]

label: [Label] enabled: [Enabled]

retentionSpan: [Retention Span] secretKey: [Secret Key] userKey: [User Key]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Description—A description of the component.

• Fields—Fields list different options for each component.

• Label—The name of the component.

• Enabled—Whether the iSight rule loader is enabled.

• Retention Span—The number of days to retain rule sets.

• Secret Key—iSIGHT subscriber secret key.

• User Key—iSIGHT subscriber API key.

Example

HTTP/1.1 200 OK

Date: Tue, 07 Feb 2017 18:59:06 GMT

Content-Type: application/json; charset=utf-8

{

"description": "Configuration for loading and retention of iSIGHT rules", "fields": {

"enabled": {

"default": [

false

],

"description": "Enable/disable rule loader", "falseLabel": "Disabled",

"label": "Rule loader", "maxCount": 1,

"minCount": 1, "trueLabel": "Enabled", "type": "bool"

},

"retentionSpan": { "default": [

15

],

"description": "Number of days to retain rulesets", "label": "Retention (Days)",

"maxCount": 1,

"maxValue": 90,

"minCount": 1,

"minValue": 1,

"type": "int"

},

"secretKey": {

"default": [ ""

],

"description": "iSIGHT Subscriber Secret Key", "label": "Secret Key",

"maxCount": 1,

"minCount": 1,

"type": "string"

},

"userKey": {

"default": [ ""

],

"description": "iSIGHT Subscriber API Key", "label": "API Key",

"maxCount": 1,

"minCount": 1,

"type": "string"

}

},

"label": "PX iSIGHT Rule Loader", "values": {

"enabled": [

false

],

"retentionSpan": [ 30

],

"secretKey": [

"abcdefghijk"

],

"userKey": [

"lmnopqrstuvw"

]

}

}

cURL code sample: Configure iSight rule loader

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/isight-rule-loader -k -X POST --data-binary '{"values": {"enabled": [false],"retentionSpan": [30],"secretKey": ["abcdefghijk"],"userKey": ["lmnopqrstuvw"]}}'

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/isight-rule-loader—The component configuration request URL. Replace

xxx.xxx.xxx.xxx with the IP address of your Series appliance.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X POST—This option specifies using the POST method.

• --data-binary '{"values": {"enabled": [false],"retentionSpan": [30],"secretKey": ["abcdefghijk"],"userKey": ["lmnopqrstuvw"]}}'—This option specifies the changes to the iSight rule loader.

Results

This example updates the values for the iSight rule loader. The output is in JSON.

Configure network request

To update the network configuration, send one of the following requests:

POST https://<PX_IP_address>/api/4.0/config/net

PUT https://<PX_IP_address>/api/4.0/config/net

Note

To use this request, you must belong to the sudo group.

You cannot update the network configuration while it is being synchronized or if a system upgrade, backup, or restore is in progress.

Required header:

--user <username>:<password>

Request body:

{

enabled: BOOLEAN, ipv4: 'IP address', ipv6: 'IP address', label: 'TEXT', netmaskv4: 'netmask', netmaskv6: 'netmask', dns: 'IP address', domains: 'TEXT', fqdn: 'TEXT',

gateway4: 'IP address', gateway6: 'IP address', hostname: 'TEXT'

}

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Parameters

Note

The devices field describes two network devices. There are always two devices listed.

• enabled—Whether the device is enabled. Valid values are true and false.

• ipv4—IPv4 address of the device.

• ipv6—IPv6 address of the device.

• label—The label for the device. Do not change this value.

• netmaskv4—IPv4 netmask of the device.

• netmaskv6—IPv6 netmask of the device.

• dns—List of IPv4 or IPv6 addresses of DNS servers. Maximum: 3 addresses.

• domains—List of search domains.

• fqdn—Fully qualified domain name of the Series appliance.

• gateway4—IPv4 network gateway address of the Series appliance.

• gateway6—IPv6 network gateway address of the Series appliance.

• hostname—Hostname of the Series appliance.

Example

POST https://xxx.xxx.xxx.xxx/api/4.0/config/net

Required header:

--user npadmin:hammerhead

Request body:

{

"values": {

"devices": [

{

"enabled": [

false

],

"ipv4": [

"xxx.xxx.xxx.xxx"

],

"ipv6": [], "label": [ "eth0"

],

"netmaskv4": [

"xxx.xxx.xxx.xxx"

],

"netmaskv6": []

},

{

"enabled": [

false

],

"ipv4": [],

"ipv6": [], "label": [

"eth1"

],

"netmaskv4": [],

"netmaskv6": []

}

],

"dns": [

"xxx.xxx.xxx.xxx"

],

"domains": [ "eng.fireeye.com"

],

"fqdn": [

"belmont.eng.fireeye.com"

],

"gateway4": [

"xxx.xxx.xxx.xxx"

],

"gateway6": [], "hostname": [

"belmont"

]

}

}

Configure network response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type] description: [Description] fields: [Fields]

label: [Label] enabled: [Enabled] ipv4: [IPv4]

ipv6: [IPv6] label: [Label]

netmaskv4: [IPv4 Netmask] netmaskv6: [IPv6 Netmask] dns: [DNS]

domains: [Domains]

fqdn: [FQDN]

gateway4: [IPv4 Gateway] gateway6: [IPv6 Gateway] hostname: [Hostname]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Description—A description of the component.

• Fields—Fields list different options for each component.

• Label—The name of the component.

• Enabled—Whether the device is enabled.

• IPv4—IPv4 address of the device.

• IPv6—IPv6 address of the device.

• Label—The label for the device.

• IPv4 Netmask—IPv4 netmask of the device.

• IPv6 Netmask—IPv6 netmask of the device.

• DNS—List of IPv4 or IPv6 addresses of DNS servers.

• Domains—List of search domains.

• FQDN—Fully qualified domain name of the Series appliance.

• IPv4 Gateway—IPv4 network gateway address of the Series appliance.

• IPv6 Gateway—IPv6 network gateway address of the Series appliance.

• Hostname—Hostname of the Series appliance.

Example

HTTP/1.1 200 OK

Date: Tue, 07 Feb 2017 22:41:52 GMT

Content-Type: application/json; charset=utf-8

{

"description": "Network config to hosts, hostname and network interfaces", "fields": {

"devices": {

"description": "Configuration for Network Devices", "fields": {

"enabled": {

"default": [

false

],

"description": "Is device enabled?", "label": "Enabled",

"maxCount": 1,

"minCount": 1,

"type": "bool"

},

"ipv4": {

"description": "IPv4 Address", "label": "IPv4 Address", "maxCount": 1,

"minCount": 0,

"type": "ipv4"

},

"ipv6": {

"description": "IPv6 Address", "label": "IPv6 Address", "maxCount": 1,

"minCount": 0,

"type": "ipv6"

},

"label": {

"description": "Device label - do not change", "label": "Label",

"maxCount": 1,

"maxValue": 256,

"minCount": 1,

"minValue": 1,

"type": "string"

},

"netmaskv4": {

"description": "IPv4 Netmask", "label": "IPv4 Netmask", "maxCount": 1,

"minCount": 0,

"type": "ipv4"

},

"netmaskv6": {

"description": "IPv6 Netmask", "label": "IPv6 Netmask", "maxCount": 1,

"maxValue": 128,

"minCount": 0,

"minValue": 0,

"type": "int"

}

},

"label": "Network Devices", "maxCount": 2,

"minCount": 2,

"type": "object"

},

"dns": {

"description": "Addresses of DNS Servers", "label": "DNS Addresses",

"minCount": 0,

"type": "ip"

},

"domains": {

"description": "Network domains", "label": "Domains",

"maxCount": 6,

"minCount": 0, "type": "hostname"

},

"fqdn": {

"description": "Fully Qualified Domain Name", "label": "FQDN",

"maxCount": 1,

"minCount": 0, "type": "hostname"

},

"gateway4": {

"description": "IPv4 network gateway address", "label": "IPv4 Gateway",

"maxCount": 1,

"minCount": 0,

"type": "ipv4"

},

"gateway6": {

"description": "IPv6 network gateway address", "label": "IPv6 Gateway",

"maxCount": 1,

"minCount": 0,

"type": "ipv6"

},

"hostname": {

"description": "Network hostname", "label": "Hostname",

"maxCount": 1,

"minCount": 1, "type": "hostname"

}

},

"label": "Network config", "values": {

"devices": [

{

"enabled": [

false

],

"ipv4": [

"xxx.xxx.xxx.xxx"

],

"ipv6": [], "label": [

"eth0"

],

"netmaskv4": [

"xxx.xxx.xxx.xxx"

],

"netmaskv6": []

},

{

"enabled": [

false

],

"ipv4": [],

"ipv6": [], "label": [ "eth1"

],

"netmaskv4": [],

"netmaskv6": []

}

],

"dns": [

"xxx.xxx.xxx.xxx"

],

"domains": [

"eng.fireeye.com"

],

"fqdn": [

"belmont.eng.fireeye.com"

],

"gateway4": [

"xxx.xxx.xxx.xxx"

],

"gateway6": [], "hostname": [

"belmont"

]

}

}

cURL code sample: Configure network

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/net -k -X POST --data-binary '{"values":

{"devices": [{"enabled": [false],"ipv4": ["xxx.xxx.xxx.xxx"],"ipv6": [],"label": ["eth0"],"netmaskv4":

["xxx.xxx.xxx.xxx"],"netmaskv6": []},{"enabled": [false],"ipv4": [],"ipv6": [],"label": [ "eth1"], "netmaskv4":

[],"netmaskv6": []}],"dns": ["xxx.xxx.xxx.xxx"],"domains": ["eng.fireeye.com"],"fqdn":

["belmont.eng.fireeye.com"],"gateway4": ["xxx.xxx.xxx.xxx"], "gateway6": [],"hostname": ["belmont"]}}'

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/net—The component configuration request URL. Replace xxx.xxx.xxx.xxx

with the IP address of your Series appliance.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL

connection without installing a CA certificate.

• -X POST—This option specifies using the POST method.

• --data-binary '{"values": {"devices": [{"enabled": [false],"ipv4": ["xxx.xxx.xxx.xxx"],"ipv6": [],"label":

["eth0"],"netmaskv4": ["xxx.xxx.xxx.xxx"],"netmaskv6": []},{"enabled": [false],"ipv4": [],"ipv6":

[],"label": [ "eth1"], "netmaskv4": [],"netmaskv6": []}],"dns": ["xxx.xxx.xxx.xxx"],"domains":

["eng.fireeye.com"],"fqdn": ["belmont.eng.fireeye.com"],"gateway4": ["xxx.xxx.xxx.xxx"], "gateway6": [],"hostname": ["belmont"]}}'—This option specifies the changes to make to the network configuration.

Results

This example updates the values for the network configuration. The output is in JSON.

Configure NTP request

To update the list of Network Time Protocol (NTP) servers, send one of the following requests:

POST https://<PX_IP_address>/api/4.0/config/ntp

PUT https://<PX_IP_address>/api/4.0/config/ntp

Note

To use this request, you must belong to the sudo group.

You cannot update the NTP server list while it is being synchronized or if a system upgrade, backup, or restore is in progress.

Required header:

--user <username>:<password>

Request body:

{

servers: 'TEXT'

}

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Parameters

• servers—A list of addresses for NTP servers. The value can be omitted. Any number of servers can be listed.

Example

POST https://xxx.xxx.xxx.xxx/api/4.0/config/ntp

Required header:

--user npadmin:hammerhead

Request body:

{

"values": {

"servers": [

"ntp.1.server", "ntp.2.server"

]

}

}

Configure NTP response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type] description: [Description] fields: [Fields]

label: [Label] servers: [Servers]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Description—A description of the component.

• Fields—Fields list different options for each component.

• Label—The name of the component.

• Servers—A list of addresses for NTP servers.

Example

HTTP/1.1 200 OK

Date: Tue, 07 Feb 2017 23:55:49 GMT

Content-Type: application/json; charset=utf-8

{

"description": "NTP config to list NTP servers on the network", "fields": {

"servers": {

"description": "Address of NTP Servers", "label": "Servers",

"type": "address"

}

},

"label": "NTP", "values": {

"servers": [

"ntp.1.server", "ntp.2.server"

]

}

}

cURL code sample: Configure NTP

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/ntp -k

-X POST

--data-binary '{"values": {"servers": ["ntp.1.server","ntp.2.server"]}}'

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/ntp—The component configuration request URL. Replace xxx.xxx.xxx.xxx

with the IP address of your Series appliance.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X POST—This option specifies using the POST method.

• --data-binary '{"values": {"servers": ["ntp.1.server","ntp.2.server"]}}'—This option specifies the changes to make to the NTP server list.

Results

This example updates the values for the NTP server list. The output is in JSON.

Configure PX-Eve-Route request

To configure -Eve-Route for sharing data from the Series appliance to the IA Series appliance, send one of the following requests:

POST https://<PX_IP_address>/api/4.0/config/px-eve-route

PUT https://<PX_IP_address>/api/4.0/config/px-eve-route

Note

To use this request, you must belong to the sudo group.

You cannot update -Eve-Route while it is being synchronized or if a system upgrade, backup, or restore is in progress.

Required header:

--user <username>:<password>

Request body:

{

address: 'TEXT', eventTypes: BOOLEAN, dstIP: '<ip address>', dstPort: INT, filterType: ENUM, protocol: INT,

srcIP: '<ip address>', srcPort: INT,

type: 'TEXT', pivotPort: 'TEXT'

}

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Parameters

• address—ZMQ socket address.

• eventTypes—Whether data for each listed protocol is enabled. Valid values are true and false.

• dstIP—Destination IP address.

• dstPort—Destination port number.

• filterType—Inclusive/exclusive filter. The value can be 0-255.

• protocol—Protocol. The value can be 0-255.

• srcIP—Source IP address.

• srcPort—Source port number.

• type—Valid values are inclusive and exclusive.

• pivotPort—Pivot port.

Example

POST https://xxx.xxx.xxx.xxx/api/4.0/config/px-eve-route

Required header:

--user npadmin:hammerhead

Request body:

{

"values": {

"output": [

{

"address": [ "ipc:///var/run/flow/test.zmq"

],

"eventTypes": [

{

"alert": [ true

],

"dhcp": [ false

],

"dns": [

false

],

"file": [ false

],

"fileinfo": [ false

],

"ftp": [ true

],

"http": [ true

],

"imap": [ false

],

"irc": [ false

],

"pop3": [ false

],

"pxflow": [ false

],

"rdp": [ false

],

"smb": [ false

],

"smb2": [ false

],

"smtp": [ false

],

"ssh": [ false

],

"tls": [ false

]

}

],

"filters": [

{

"filterType": [ "inclusive"

],

"type": [ "inclusive"

],

"srcIP": [ "xxx.xxx.xxx.xxx"

],

"dstIP": [ "xxx.xxx.xxx.xxx"

],

"srcPort": [ 80

],

"dstPort": [

22

],

"protocol": [ 6

]

}

]

}

],

"pivotPort": [ "eth0"

]

}

}

Configure PX-Eve-Route response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type] description: [Description} fields: [Fields]

label: [Label] address: [Address]

eventTypes: [Event Types] dstIP: [Destination IP] dstPort: [Destination Port] filterType: [Filter Type] protocol: [Protocol] srcIP:[Source IP]

srcPort: [Source Port] type: [Type]

pivotPort: [Pivot Port]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Description—A description of the component.

• Fields—Fields list different options for each component.

• Label—The name of the component.

• Address—ZMQ socket address.

• Event Types—Whether data for each listed protocol is enabled. Valid values are true and false.

• Destination IP—Destination IP address.

• Destination Port—Destination port number.

• Filter Type—Valid values are inclusive and exclusive.

• Protocol—Protocol. The value can be 0-255.

• Source IP—Source IP address.

• Source Port—Source port number.

• Type—Valid values are inclusive and exclusive.

• Pivot Port—Pivot port.

Example

HTTP/1.1 200 OK

Date: Wed, 08 Feb 2017 22:01:14 GMT

Content-Type: application/json; charset=utf-8

{

"description": "PX Eve Route is responsible for sharing data from PX to IA", "fields": {

"output": {

"description": "Data output from PX Eve Route", "fields": {

"address": {

"description": "ZMQ Socket Address", "label": "Address",

"maxCount": 1,

"maxValue": 320,

"minCount": 1,

"minValue": 0,

"type": "string"

},

"eventTypes": {

"description": "Enable/Disable Protocol Metadata", "fields": {

"alert": {

"default": [

false

],

"label": "Alert", "maxCount": 1,

"minCount": 1,

"type": "bool"

},

"dhcp": {

"default": [

false

],

"label": "DHCP",

"maxCount": 1,

"minCount": 1,

"type": "bool"

},

"dns": {

"default": [

false

],

"label": "DNS", "maxCount": 1,

"minCount": 1,

"type": "bool"

},

"file": {

"default": [

false

],

"label": "File", "maxCount": 1,

"minCount": 1,

"type": "bool"

},

"fileinfo": {

"default": [

false

],

"label": "File Info", "maxCount": 1,

"minCount": 1,

"type": "bool"

},

"ftp": {

"default": [

false

],

"label": "FTP", "maxCount": 1,

"minCount": 1,

"type": "bool"

},

"http": {

"default": [

false

],

"label": "HTTP", "maxCount": 1,

"minCount": 1,

"type": "bool"

},

"imap": {

"default": [

false

],

"label": "IMAP", "maxCount": 1,

"minCount": 1,

"type": "bool"

},

"irc": {

"default": [

false

],

"label": "IRC", "maxCount": 1,

"minCount": 1,

"type": "bool"

},

"pop3": {

"default": [

false

],

"label": "POP3", "maxCount": 1,

"minCount": 1,

"type": "bool"

},

"pxflow": {

"default": [

false

],

"label": "PX Flow", "maxCount": 1,

"minCount": 1,

"type": "bool"

},

"rdp": {

"default": [

false

],

"label": "RDP", "maxCount": 1,

"minCount": 1,

"type": "bool"

},

"smb": {

"default": [

false

],

"label": "SMB", "maxCount": 1,

"minCount": 1,

"type": "bool"

},

"smb2": {

"default": [

false

],

"label": "SMB2", "maxCount": 1,

"minCount": 1,

"type": "bool"

},

"smtp": {

"default": [

false

],

"label": "SMTP", "maxCount": 1,

"minCount": 1,

"type": "bool"

},

"ssh": {

"default": [

false

],

"label": "SSH", "maxCount": 1,

"minCount": 1,

"type": "bool"

},

"tls": {

"default": [

false

],

"label": "TLS", "maxCount": 1,

"minCount": 1,

"type": "bool"

}

},

"label": "Protocol Metadata Selection", "maxCount": 1,

"minCount": 1,

"type": "object"

},

"filters": {

"description": "Five Tuple filters applied to records to determine inclusion/exclusion.", "fields": {

"dstIP": {

"description": "Destination IP Address", "label": "Destination IP Address", "maxCount": 1,

"maxValue": 45,

"minCount": 0,

"minValue": 0,

"type": "ip"

},

"dstPort": {

"description": "Destination Port", "label": "Destination Port", "maxCount": 1,

"maxValue": 65535,

"minCount": 0,

"minValue": 0,

"type": "int"

},

"filterType": {

"description": "Inclusive/Exclusive Filter", "enums": [

"inclusive", "exclusive"

],

"label": "Inclusive/Exclusive", "maxCount": 1,

"maxValue": 255,

"minCount": 1,

"minValue": 0,

"type": "enum"

},

"protocol": {

"description": "Protocol", "label": "Protocol", "maxCount": 1,

"maxValue": 255,

"minCount": 0,

"minValue": 0,

"type": "int"

},

"srcIP": {

"description": "Source IP Address", "label": "SourceIP Address", "maxCount": 1,

"maxValue": 45,

"minCount": 0,

"minValue": 0,

"type": "ip"

},

"srcPort": {

"description": "Source Port", "label": "Source Port", "maxCount": 1,

"maxValue": 65535,

"minCount": 0,

"minValue": 0,

"type": "int"

},

"vlan": {

"description": "VLAN ID", "label": "VLAN ID",

"maxCount": 1,

"maxValue": 4095,

"minCount": 0,

"minValue": 1,

"type": "int"

}

},

"label": "Filters", "maxCount": 32,

"minCount": 0,

"type": "object"

}

},

"label": "Output Sinks", "maxCount": 30,

"minCount": 0,

"type": "object"

},

"pivotPort": {

"default": [ "eth0"

],

"description": "Device used to trace the origin of the data", "label": "PivotPort",

"maxCount": 1,

"maxValue": 9999,

"minCount": 1,

"minValue": 1,

"type": "string"

}

},

"label": "px-eve-route", "values": {

"output": [

{

"address": [ "ipc:///var/run/flow/test.zmq"

],

"eventTypes": [

{

"alert": [

true

],

"dhcp": [

false

],

"dns": [

false

],

"file": [

false

],

"fileinfo": [ false

],

"ftp": [

true

],

"http": [

true

],

"imap": [

false

],

"irc": [

false

],

"pop3": [

false

],

"pxflow": [

false

],

"rdp": [

false

],

"smb": [

false

],

"smb2": [

false

],

"smtp": [

false

],

"ssh": [

false

],

"tls": [

false

]

}

],

"filters": [

{

"dstIP": [

"xxx.xxx.xxx.xxx"

],

"dstPort": [ 22

],

"filterType": [

"inclusive"

],

"protocol": [ 6

],

"srcIP": [

"xxx.xxx.xxx.xxx"

],

"srcPort": [

80

],

"type": [

"inclusive"

]

}

]

}

],

"pivotPort": [ "eth0"

]

}

}

cURL code sample: Configure PX-Eve-Route

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/px-eve-route -k -X POST --data-binary '{"values": {"output": [{"address": ["ipc:///var/run/flow/test.zmq"],"eventTypes": [{"alert": [true],"dhcp":

[false],"dns": [false],"file": [false],"fileinfo": [false],"ftp": [true],"http": [true],"imap": [false],"irc":

[false],"pop3": [false],"pxflow": [false],"rdp": [false],"smb": [false],"smb2": [false],"smtp": [false ],"ssh":

[false],"tls": [false]}],"filters": [{"filterType": ["inclusive"],"type": ["inclusive"],"srcIP":

["xxx.xxx.xxx.xxx"],"dstIP": ["xxx.xxx.xxx.xxx"],"srcPort": [80],"dstPort": [22],"protocol": [6]}]}],"pivotPort": ["eth0"]}}'

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/px-eve-route—The component configuration request URL. Replace

xxx.xxx.xxx.xxx with the IP address of your Series appliance.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X POST—This option specifies using the POST method.

• --data-binary '{"values": {"output": [{"address": ["ipc:///var/run/flow/test.zmq"],"eventTypes": [{"alert":

[true],"dhcp": [false],"dns": [false],"file": [false],"fileinfo": [false],"ftp": [true],"http":

[true],"imap": [false],"irc": [false],"pop3": [false],"pxflow": [false],"rdp": [false],"smb":

[false],"smb2": [false],"smtp": [false ],"ssh": [false],"tls": [false]}],"filters": [{"filterType":

["inclusive"],"type": ["inclusive"],"srcIP": ["xxx.xxx.xxx.xxx"],"dstIP": ["xxx.xxx.xxx.xxx"],"srcPort": [80],"dstPort": [22],"protocol": [6]}]}],"pivotPort": ["eth0"]}}'—This option specifies the changes to make to

-Eve-Route.

Results

This example updates the values for -Eve-Route. The output is in JSON.

Configure SNMP request

To update the SNMP configuration, send one of the following requests:

POST https://<PX_IP_address>/api/4.0/config/snmp

PUT https://<PX_IP_address>/api/4.0/config/snmp

Note

To use this request, you must belong to the sudo group.

You cannot update the SNMP configuration while it is being synchronized or if a system upgrade, backup, or restore is in progress.

Required header:

--user <username>:<password>

Request body:

{

port: INT, rocommunity: 'TEXT', syscontact: 'TEXT', sysloc: 'TEXT', sysname: 'TEXT', trapcommunity: 'TEXT', trapsenabled: BOOLEAN, address: 'IP address', port: INT

}

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Parameters

• port—Required. Port number for SNMP.

• rocommunity—Optional. Read-only community group. The default value is "public".

• syscontact—Optional. The name of the person to contact for this managed node and how to get in contact. The default value is "None".

• sysloc—Optional. The physical location of this managed node. The default value is "None".

• sysname—Optional. A name assigned to this managed node, usually the nodeʼs fully qualified domain name. The default value is "None".

• trapcommunity—Community value for trap reporting.

• trapsenabled—Whether the traps are enabled. Valid values are true and false.

• address—An address for reporting traps. There can be multiple addresses.

• port—Optional. The port number for the corresponding address.

Example

POST https://xxx.xxx.xxx.xxx/api/4.0/config/snmp

Required header:

--user npadmin:hammerhead

Request body:

{

"values": {

"port": [ 161

],

"rocommunity": [ "public"

],

"syscontact": [ "None"

],

"sysloc": [ "None"

],

"sysname": [ "None"

],

"trapcommunity": [

"public"

],

"trapsenabled": [ false

],

"traptargets": [

{

"address": [ "xxx.xxx.xxx.xxx"

],

"port": [ 1220

]

},

{

"address": [ "xxx.xxx.xxx.xxx"

],

"port": [ 1644

]

}

]

}

}

Configure SNMP response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type] description: [Description} fields: [Fields]

label: [Label] port: [Port]

rocommunity: [Community] syscontact: [Contact] sysloc: [Location] sysname: [Name]

trapcommunity: [Trap Community] trapsenabled: [Traps Enabled] address: [Trap Address]

port: [Trap Port]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Description—A description of the component.

• Fields—Fields list different options for each component.

• Label—The name of the component.

• Values—Values for various fields.

• Port—Port number for SNMP.

• Community—Read-only community group.

• Contact—The name of the person to contact for this managed node and how to get in contact.

• Location—The physical location of this managed node.

• Name—A name assigned to this managed node, usually the nodeʼs fully qualified domain name.

• Trap Community—Community value for trap reporting.

• Traps Enabled—Whether the traps are enabled.

• Trap Address—An address for reporting traps.

• Trap Port—The port number for the corresponding address.

Example

HTTP/1.1 200 OK

Date: Fri, 10 Feb 2017 00:11:53 GMT

Content-Type: application/json; charset=utf-8

{

"description": "SNMP configuration", "fields": {

"port": {

"default": [ 161

],

"description": "IPtables SNMP port", "label": "Port",

"maxCount": 1,

"maxValue": 65535,

"minCount": 1,

"minValue": 1,

"type": "int"

},

"rocommunity": { "default": [

"public"

],

"description": "Read-only community", "label": "Read-Only Community", "maxCount": 1,

"maxValue": 256,

"minCount": 0,

"minValue": 1,

"type": "string"

},

"syscontact": { "default": [

"None"

],

"description": "System contact", "label": "System Contact", "maxCount": 1,

"maxValue": 256,

"minCount": 0,

"minValue": 1,

"type": "string"

},

"sysloc": {

"default": [

"None"

],

"description": "System location", "label": "System Location", "maxCount": 1,

"maxValue": 256,

"minCount": 0,

"minValue": 1,

"type": "string"

},

"sysname": {

"default": [

"None"

],

"description": "System name", "label": "System Name", "maxCount": 1,

"maxValue": 256,

"minCount": 0,

"minValue": 1,

"type": "string"

},

"trapcommunity": {

"description": "Community for Trap reporting", "label": "Trap Community",

"maxCount": 1,

"maxValue": 256,

"minCount": 0,

"minValue": 0,

"type": "string"

},

"trapsenabled": { "default": [

false

],

"description": "Enable/disable traps", "falseLabel": "Disabled",

"label": "Traps", "maxCount": 1,

"minCount": 1, "trueLabel": "Enabled", "type": "bool"

},

"traptargets": {

"description": "Targets for reporting traps",

"fields": {

"address": {

"description": "Address of target", "label": "Address",

"maxCount": 1,

"minCount": 1,

"type": "address"

},

"port": {

"description": "Port of target (optional)", "label": "Port",

"maxCount": 1,

"maxValue": 65535,

"minCount": 0,

"minValue": 0,

"type": "int"

}

},

"label": "Trap Targets", "minCount": 0,

"type": "object"

}

},

"label": "SNMP", "values": {

"port": [ 161

],

"rocommunity": [ "public"

],

"syscontact": [ "None"

],

"sysloc": [ "None"

],

"sysname": [ "None"

],

"trapcommunity": [ "public"

],

"trapsenabled": [ false

],

"traptargets": [

{

"address": [

"xxx.xxx.xxx.xxx"

],

"port": [

1220

]

},

{

"address": [

"xxx.xxx.xxx.xxx"

],

"port": [

1644

]

}

]

}

}

cURL code sample: Configure SNMP

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https:///xxx.xxx.xxx.xxx/api/4.0/config/snmp -k -X POST --data-binary '{"values": {"port": [161],"rocommunity": ["public"],"syscontact": ["None"],"sysloc": ["None"],"sysname": ["None"],"trapcommunity": ["public"],"trapsenabled": [false],"traptargets": [{"address":

["xxx.xxx.xxx.xxx"],"port": [1220]},{"address": ["xxx.xxx.xxx.xxx"],"port": [1644]}]}}'

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with the user name for your Series appliance. Replace hammerhead with the password for your PX Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/snmp—The component configuration request URL. Replace xxx.xxx.xxx.xxx

with the IP address of your Series appliance.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X POST—This option specifies using the POST method.

• --data-binary '{"values": {"port": [161],"rocommunity": ["public"],"syscontact": ["None"],"sysloc":

["None"],"sysname": ["None"],"trapcommunity": ["public"],"trapsenabled": [false],"traptargets": [{"address": ["xxx.xxx.xxx.xxx"],"port": [1220]},{"address": ["xxx.xxx.xxx.xxx"],"port": [1644]}]}}'—This option specifies the changes to make to the SNMP configuration.

Results

This example updates the values for the SNMP configuration. The output is in JSON.

Restore default component configuration request

To restores the default values for a specific component, send the following request:

DELETE https://<PX_IP_address>/api/4.0/config/<component>

Note

To use this request, you must belong to the sudo group.

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

• component—Part of the Series appliance.

Example

DELETE https://xxx.xxx.xxx.xxx/api/4.0/config/ntp

Required header:

--user npadmin:hammerhead

Restore default component configuration response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type] description: [Description] fields: [Fields]

label: [Label] values: [Values]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Description—A description of the component.

• Fields—Fields list different options for each component.

• Label—The name of the component.

• Values—Values for various fields.

Example

HTTP/1.1 200 OK

Date: Fri, 27 Jan 2017 22:00:43 GMT

Content-Type: application/json; charset=utf-8

{

"description": "NTP config to list NTP servers on the network", "fields": {

"servers": {

"description": "Address of NTP Servers", "label": "Servers",

"type": "address"

}

},

"label": "NTP", "values": {

"servers": []

}

}

cURL code sample: Restore default component configuration

The code sample was run with cURL 7.57.0.

curl -k --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/ntp -X DELETE

This cURL sample includes the following options:

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• --user npadmin:hammerhead—Replace npadmin with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/ntp—The component configuration request URL. Replace xxx.xxx.xxx.xxx

with the IP address of your Series appliance. Replace ntp with the component of interest.

Results

This example restores the default values for the specified component. The output is in JSON.

Synchronization state request

To check if the configuration of Series components has been synchronized, send the following request:

GET https://<PX_IP_address>/api/4.0/config/<component>/status

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

• component—Part of the Series appliance.

Example

GET https://xxx.xxx.xxx.xxx/api/4.0/config/acm/status

Required header:

--user cpx:hammerhead

Synchronization state response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type] status: [Status]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Status—Status of synchronization.

Example

HTTP/1.1 200 OK

Date: Wed, 16 Mar 2016 18:27:09 GMT

Content-Type: text/html; charset=UTF-8

{

"status": "synced",

}

cURL code sample: Synchronization state

The code sample was run with cURL 7.57.0.

curl -k --user cpx:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/acm/status

This cURL sample includes the following options:

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• --user cpx:hammerhead—Replace cpx with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/acm/status—The component configuration request URL. Replace

xxx.xxx.xxx.xxx with the IP address of your Series appliance. Replace acm with the component of interest.

Results

This example returns whether the configuration of Series components has been synchronized The output is in JSON.

Event-based capture

Event-based capture (EBC) uses defined rules to capture data around a specific event in network traffic. For example, you can use EBC to capture all packets for a blacklisted host address. When a rule matches an event in the network traffic, the Series appliance automatically creates a search on the data surrounding the event. Packets retrieved from event-based search are managed and stored differently than the other packets.

Use the EBC endpoints to retrieve EBC events:

• View stored EBC events request

GET https://<PX_IP_address>/api/4.0/events/stored

• View EBC search history request

GET https://<PX_IP_address>/api/4.0/events/searchhistory

• View search details for a stored EBC event request

GET https://<PX_IP_address>/api/4.0/events/stored/<Search UUID>

• Retrieve search ID for EBC event UUID request

GET https://<PX_IP_address>/api/4.0/events/searchid/<EVENT UUID>

View stored EBC events request

To retrieve stored EBC event information, send the following request:

GET https://<PX_IP_address>/api/4.0/events/stored

Required header:

--user <username>:<password>

You can retrieve events from a specified time period, events that occurred before or after a specified time, or the newest or oldest events.

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

• component—Part of the Series appliance.

Query parameters

• stime—The start of the search period, expressed as a floating-point epoch time stamp. See Conventions for the format. Use this parameter with etime to specify a complete time range.

• etime—The end of the search period, expressed as a floating-point epoch time stamp. See Conventions for the format. Use

this parameter with stime to specify a complete time range.

• direction—Possible values are start, end, older, or newer. Use start or end to retrieve the oldest or newest events based on the specified start or end time. Use older or newer with the time parameter to retrieve events that occurred before or after a specified time stamp.

• time—The reference time used when direction is set to older or newer. The time is expressed as a floating-point epoch time stamp.

• count—Number of events to return in the result set. The maximum is 100.

Parameters are required in one of the following combinations:

• Time range—Use stime and etime. direction and time carry no meaning in this usage.

For example: stime=20150304.000000&etime=20150304.000001

• Older events—Use a direction of older and the time parameter. stime and etime carry no meaning in this usage.

For example: time=20150304.000000&direction=older

• Newer events—Use a direction of newer and the time parameter. stime and etime carry no meaning in this usage.

For example: time=20150304.000000&direction=newer

• Newest events—Use a direction of start. stime, etime, and time carry no meaning in this usage.

For example: direction=start

• Oldest events—Use a direction of end. stime, etime, and time carry no meaning in this usage.

For example: direction=end

Example

GET https://xxx.xxx.xxx.xxx/api/4.0/events/stored?stime=20150304.000000&etime=20150304.000001

Required header:

--user cpx:hammerhead

View stored EBC events response

message: [Message] newer: [Newer] older: [Older]

parameters: [Parameters] status: [Status]

ebc: [EBC User] faas: [FaaS User]

input_create_time: [Input Create Time] input_depth: [Input Depth]

@timestamp: [Input Time Stamp] appType: [Application Type]

destinationIPv4Address: [Destination IPv4 Address] destinationTransportPort: [Destination Port] npulseStreamId: [nPulse Stream ID] observationTimeMicroseconds: [Observation Time] protocolIdentifier: [Protocol]

ruleClass: [Rule Class]

ruleGID: [Rule Group Identifier] ruleMessage: [Rule Message] rulePayload: [Rule Payload] rulePriority: [Rule Priority] ruleRev: [Rule Revision]

ruleSID: [Rule Signature Identifier] sourceIPv4Address: [Source IPv4 Address] sourceTransportPort: [Source Port]

input_etime_nanoseconds: [Input End Time in Nanoseconds] input_etime_second: [Input End Time in Seconds] input_hash_field: [Input Hash Field]

input_limit: [Input Limit] input_score: [Input Score] input_search_id: [Input Search ID] input_search_type: [Input Search Type]

input_stime_nanoseconds: [Input Start Time in Nanoseconds] input_stime_second: [Input Start Time in Seconds] input_user: [Input User]

input_window: [Input Window] input_xpf: [Input XPF] output_bpf: [Output BPF]

output_elapsed: [Output Elapsed Time] output_elastic_elapsed": [Text Maintenance Elapsed Time] output_elastic_end: [Text Maintenance End Time] output_elastic_message: [Text Maintenance Status Message] output_elastic_start: [Text Maintenance Start Time] output_elastic_status: [Text Maintenance Status] output_firstFlowEpoch: [Output First Flow Epoch] output_firstIndexEpoch: [Output First Index Epoch] output_firstPacketEpoch: [Output First Packet Epoch] output_index_elapsed: [Packet Index Elapsed Time] output_index_end: [Packet Index End Time] output_index_foundRecords: [Packet Index Found Records] output_index_message: [Packet Index Status Message] output_index_packetPercent:[Packet Index Percent Complete] output_index_rangePercent: [Packet Index Range Percent] output_index_searchedFiles: [Packet Index Searched Files] output_index_start: [Packet Index Start] output_index_status: [Packet Index Status] output_lastUpdate: [Last Update]

output_message: [Output Status Message] output_packet_elapsed: [Packet Retrieval Elapsed Time] output_packet_end: [Packet Retrieval End Time] output_packet_foundRecords: [Packet Retrieval Found Records] output_packet_message: [Packet Retrieval Status Message]

output_packet_packetPercent: [Packet Retrieval Percent Complete] output_packet_processedBytes: [Packet Retrieval Packet Size] output_packet_start: [Packet Retrieval Start] output_packet_status: [Packet Retrieval Status] output_searchEnd: [Search End]

output_searchStart: [Search Start] output_status: [Output Status] output_streamCount: [Stream Count]

output_xpf_elapsed: [Connection Index Elapsed Time] output_xpf_end: [Connection Index End Time] output_xpf_extentSecond: [Connection Index Second] output_xpf_firstSecond: [Connection Index First Connection] output_xpf_foundRecords: [Connection Index Found Records] output_xpf_lastSecond: [Connection Index Last Connection] output_xpf_limitPercent: [Connection Index Percent Complete] output_xpf_message: [Connection Index Status Message] output_xpf_packetCount: [Connection Index Packet Count] output_xpf_rangePercent: [Connection Index Range Percent] output_xpf_searchedBytes: [Connection Index Searched Bytes] output_xpf_start: [Connection Index Start] output_xpf_status: [Connection Index Status]

store_name: [Store Name]

Response fields

• Message—Summary of results

• Newer—Newest event in search.

• Older—Oldest event in search.

• Parameters—Query parameters and their settings. See Query parameters.

• Status—A standard HTTP response message.

• EBC User—Uses event-based capture.

• FaaS User—Has a FaaS account.

• Input Create Time—Time at which the search was submitted.

• Input Depth—Search depth. A search can be at the connection, packet, or session depth.

• Input Time Stamp—Time when command was entered.

• Application Type—Well-known port number of the protocol found for this event. For example, http=80, tls=443, and smtp=25.

• Destination IPv4 Address—Destination IPv4 address.

• Destination Port—Destination port.

• nPulse Stream ID—nPulse stream identifier.

• Observation Time—Time in microseconds.

• Protocol—Protocol identifier.

• Rule Class—Rule class.

• Rule Group Identifier—User-defined group identifier that can be used to group rules.

• Rule Message—Rule message.

• Rule Payload—Encoded rule.

• Rule Priority—User-defined rule priority.

• Rule Revision—Rule revision.

• Rule Signature Identifier—User-defined signature identifier that can be used to uniquely identify a rule within a set of rules.

• Source IPv4 Address—Source IPv4 address.

• Source Port—Source port.

• Input End Time in Nanoseconds—The nanoseconds portion of the end time of the search time range.

• Input End Time in Seconds—The seconds portion of the end time of the search time range.

• Input Hash Field—Hash key for the status of this search.

• Input Limit—Requested maximum number of connection records to find.

• Input Score—Time when the search was created.

• Input Search ID—Generated search identifier that uniquely identifies this search.

• Input Search Type—Type of search requested: stream or all.

• Input Start Time in Nanoseconds—The nanoseconds portion of the start time of the search time range.

• Input Start Time in Seconds—The seconds portion of the start time of the search range.

• Input User—User who made the search request.

• Input Window—The window of time before and after the specified start time that should be searched. If stime is used as a parameter, the window parameter is divided by two and subtracted from the stime to make a new start time. The window parameter is added to the original stime to make an etime. If stime is not specified, stime defaults to the current time. If etime and window are not specified, etime defaults to stime + 1 second.

• Input XPF—Filter provided by the end user.

• Output BPF—Generated XPF after input_xpf is processed by the XPF processing engine.

• Output Elapsed Time—Total elapsed time for all phases.

• Text Maintenance Elapsed Time—Total elapsed time of this phase.

• Text Maintenance End Time—End time of this phase in epoch time.

• Text Maintenance Status Message—Current status message for this phase.

• Text Maintenance Start Time—Start time of this phase in epoch time.

• Text Maintenance Status—Status of this phase. Valid values are skipped, done, working, idle, and error.

• Output First Flow Epoch—Time of the first flow recorded on the appliance.

• Output First Index Epoch—Time of the oldest connection packet index recorded on the appliance.

• Output First Packet Epoch—Time of the oldest packet stored on the appliance.

• Packet Index Elapsed Time—Total elapsed time of this phase.

• Packet Index End Time—End time of this phase in epoch time.

• Packet Index Found Records—Number of records found.

• Packet Index Status Message—Current status message for this phase.

• Packet Index Percent Complete—Percentage complete, of all potential packets found.

• Packet Index Range Percent—Percentage complete, based on captured packet times.

• Packet Index Searched Files—Number of files touched.

• Packet Index Start—Start time of this phase in epoch time.

• Packet Index Status—Status of this phase. Valid values are skipped, done, working, idle, and error.

• Last Update—Time when the search was last updated.

• Output Status Message—Status of the search.

• Packet Retrieval Elapsed Time—Total elapsed time of this phase.

• Packet Retrieval End Time—End time of this phase in epoch time.

• Packet Retrieval Found Records—Number of records found.

• Packet Retrieval Status Message—Current status message for this phase.

• Packet Retrieval Percent Complete—Percentage complete, of all potential packets found.

• Packet Retrieval Packet Size—Size of the packets processed.

• Packet Retrieval Start—Start time of this phase in epoch time.

• Packet Retrieval Status—Valid values are skipped, done, working, idle, and error.

• Search End—Last record searched.

• Search Start—First record searched.

• Output Status—Status of the search. Valid values are skipped, done, working, idle, and error.

• Stream Count—Number of nPulse streams.

• Connection Index Elapsed Time—Total elapsed time of this phase.

• Connection Index End Time—End time of this phase in epoch time.

• Connection Index Second—The last second of the last flow that the search examined.

• Connection Index First Connection—Epoch of the first connection found.

• Connection Index Found Records—Number of records found.

• Connection Index Last Connection—Current status message for this phase.

• Connection Index Percent Complete—Percentage complete, based on input_limit.

• Connection Index Status Message—Percentage complete, based on captured packet times.

• Connection Index Packet Count—Number of packets to be found, based on connection records.

• Connection Index Range Percent—Percentage complete, based on captured packet times.

• Connection Index Searched Bytes—Size of searched packets.

• Connection Index Start—Start time of this phase in epoch time.

• Connection Index Status—Status of this phase. Valid values are skipped, done, working, idle, and error.

• Store Name—Name that search is stored as.

Example

{

"message": "Found 1 EBC stored searches.", "newer": 1425481651.99,

"older": 1425481332.21,

"parameters": { "count": 25

},

"status": "ok", "storedEvents" : [

{

"ebc": "true",

"faas": "true", "input_create_time": "1425481647", "input_depth": "packet",

"input_ebc": [

{

"@timestamp": "2015-03-04T14:58:00.000001Z",

"appType": 4,

"destinationIPv4Address": "xxx.xxx.xxx.xxx", "destinationTransportPort": 44840,

"npulseStreamId": 3750560618,

"observationTimeMicroseconds": "2015-03-04T14:58:00.000001Z", "protocolIdentifier": 17,

"ruleClass": "Potentially Bad Traffic", "ruleGID": 1,

"ruleMessage": "ET POLICY Unusual number of DNS No Such Name Responses", "rulePayload": "Li4uLi4uLi4uLi4uLmZpbmRlcjEtcmVhZG5ld3MuYXN0cmF3ZWIuY29tLnJ "rulePriority": 2,

"ruleRev": 5,

"ruleSID": 2003195,

"sourceIPv4Address": "xxx.xxx.xxx.xxx", "sourceTransportPort": 53

}

]

"input_etime_nanoseconds": "36",

"input_etime_second": "1425481347",

"input_hash_field": "SEARCH_02cc1f1adc4c41ee8beacdb8c9eb2bdb", "input_limit": "1",

"input_score": "1425481647.39",

"input_search_id": "02cc1f1adc4c41ee8beacdb8c9eb2bdb", "input_search_type": "all",

"input_stime_nanoseconds": "23",

"input_stime_second": "1425480738", "input_user": "eventbasedcapture", "input_window": "0",

"input_xpf": "host xxx.xxx.xxx.xxx and host xxx.xxx.xxx.xxx", "output_bpf": "host xxx.xxx.xxx.xxx and host xxx.xxx.xxx.xxx", "output_elapsed": "0.359",

"output_elastic_elapsed": "0.000",

"output_elastic_end": "0", "output_elastic_message": "skipped", "output_elastic_start": "0", "output_elastic_status": "skipped", "output_firstFlowEpoch": "1424895839",

"output_firstIndexEpoch": "1424895839",

"output_firstPacketEpoch": "1425275100",

"output_index_elapsed": "0.235",

"output_index_end": "1425481647",

"output_index_foundRecords": "60", "output_index_message": "Index search complete", "output_index_packetPercent": "100",

"output_index_rangePercent": "100",

"output_index_searchedFiles": "310",

"output_index_start": "1425481647", "output_index_status": "done", "output_lastUpdate": "1425481647", "output_message": "Search complete", "output_packet_elapsed": "1.026",

"output_packet_end": "1425481647",

"output_packet_foundRecords": "60", "output_packet_message": "Packet search complete", "output_packet_packetPercent": "100",

"output_packet_processedBytes": "7860",

"output_packet_start": "1425481647", "output_packet_status": "done", "output_searchEnd": "1425481647",

"output_searchStart": "1425481647", "output_status": "done",

"output_streamCount": "4",

"output_xpf_elapsed": "0.031",

"output_xpf_end": "1425481647",

"output_xpf_extentSecond": "1425481347",

"output_xpf_firstSecond": "139884215344462",

"output_xpf_foundRecords": "1",

"output_xpf_lastSecond": "1425481038",

"output_xpf_limitPercent": "100", "output_xpf_message": "XPF search complete", "output_xpf_packetCount": "60",

"output_xpf_rangePercent": "100",

"output_xpf_searchedBytes": "0",

"output_xpf_start": "1425481647", "output_xpf_status": "done",

"store_name": "EBC_9c42499d-6b5b-45f9-9b09-a2068ed6c2aa"

}

]

}

cURL code sample: View stored EBC events

The code sample was run with cURL 7.57.0.

curl -k –-user cpx:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/events/stored "count=25&direction=older&time=1425481332.21"

This cURL sample includes the following options:

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• --user cpx:hammerhead—Replace cpx with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/events/stored—The EBC request URL. Replace xxx.xxx.xxx.xxx with the IP address of your Series appliance.

• "count=25&direction=older&time=1425481332.21"—This option specifies that 25 events that are older than the specified time will be returned.

Results

This example returns the stored EBC event information for 25 events that are older than the specified time. The output is in JSON.

View EBC search history request

To retrieve a list of the 200 most recent EBC searches and the status, send the following request:

GET https://<PX_IP_address>/api/4.0/events/searchhistory

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Example

GET https://xxx.xxx.xxx.xxx/api/4.0/events/searchhistory

Required header:

--user cpx:hammerhead

View EBC search history response

ebc: [EBC User] faas: [FaaS User]

input_create_time: [Input Create Time] input_depth: [Input Depth]

@timestamp: [Input Time Stamp] action: [Action]

duplicateCount: [Duplicate Count] ruleClass: [Rule Class]

ruleGID: [Rule Group Identifier] ruleMessage: [Rule Message] rulePriority: [Rule Priority] ruleRev: [Rule Revision]

ruleSID: [Rule Signature Identifier] destinationIPv4Address: [Destination IPv4 Address] destinationTransportPort: [Destination Port]

ebc: [EBC Type] ebcDepth: [EBC Depth] ebcTiming: [EBC Timing]

protocolIdentifier: [Protocol Identifier] protocolIdentifierName: [Protocol Name] pxuuid: [PX UUID]

sourceIPv4Address: [Source IPv4 Address sourceTransportPort: [Source Port] input_etime_nanoseconds: [Input End Time in Nanoseconds] input_etime_second: [Input End Time in Seconds]

input_hash_field: [Input Hash Field] input_limit: [Input Limit] input_score: [Input Score]

input_search_id: [Input Search Identifier] input_search_type: [Input Search Type] input_stime_nanoseconds: [Input Start Time in Nanoseconds] input_stime_second: [Input Start Time in Seconds] input_time_format: [Input Time Format]

input_user: [Input User] input_window: [Input Window] input_xpf: [Input XPF] output_bpf: [Output BPF] output_depth: [Output Depth]

output_elapsed: [Output Elapsed Time] output_firstFlowEpoch: [Output First Flow Epoch] output_firstIndexEpoch: [Output First Index Epoch] output_firstPacketEpoch: [Output First Packet Epoch] output_index_elapsed: [Packet Index Elapsed Time] output_index_end: [Packet Index End Time] output_index_foundRecords: [Packet Index Found Records] output_index_message: [Packet Index Status Message] output_index_packetPercent: [Packet Index Percent Complete] output_index_rangePercent: [Packet Index Range Percent] output_index_searchedFiles: [Packet Index Searched Files] output_index_start: [Packet Index Start] output_index_status: [Packet Index Status] output_lastUpdate: [Last Update]

output_message: [Output Status Message] output_packet_elapsed: [Packet Retrieval Elapsed Time] output_packet_end: [Packet Retrieval End Time] output_packet_foundRecords: [Packet Retrieval Found Records] output_packet_message: [Packet Retrieval Status Message]

output_packet_packetPercent: [Packet Retrieval Percent Complete] output_packet_processedBytes: [Packet Retrieval Packet Size] output_packet_start: [Packet Retrieval Start] output_packet_status: [Packet Retrieval Status] output_searchEnd: [Search End]

output_searchStart: [Search Start] output_session_message: [Session Analysis Status Message]

output_session_packetPercent: [Session Analysis Percent Complete] output_session_status: [Session Analysis Status]

output_status: [Output Status] output_streamCount: [Stream Count]

output_xpf_elapsed: [Connection Index Elapsed Time] output_xpf_end: [Connection Index End Time] output_xpf_extentSecond: [Connection Index Second] output_xpf_firstSecond: [Connection Index First Connection] output_xpf_foundRecords: [Connection Index Found Records] output_xpf_lastSecond: [Connection Index Last Connection] output_xpf_limitPercent: [Connection Index Percent Complete] output_xpf_message: [Connection Index Status Message] output_xpf_packetCount: [Connection Index Packet Count] output_xpf_rangePercent: [Connection Index Range Percent] output_xpf_searchedBytes: [Connection Index Searched Bytes] output_xpf_start: [Connection Index Start] output_xpf_status: [Connection Index Status]

store_name: [Store Name] status: [Status]

Response fields

• EBC User—Uses event-based capture.

• FaaS User—Has a FaaS account.

• Input Create Time—Time at which the search was submitted.

• Input Depth—Search depth. A search can be at the connection, packet, or session depth.

• Input Time Stamp—Time when command was entered.

• Action—The action performed by the engine when a signature matches the alert. A value of allowed means that the engine will send an alert for the packet and continued scanning the flow.

• Duplicate Count—Number of duplicates of this alert in the flow associated with this alert.

• Rule Class—Defined by the user in the rule configuration.

• Rule Group Identifier—User-defined group identifier that can be used to group rules.

• Rule Message—Defined by the user in the rule configuration.

• Rule Priority—User-defined rule priority.

• Rule Revision—Rule revision.

• Rule Signature Identifier—User-defined signature identifier that can be used to uniquely identify a rule within a set of rules.

• Destination IPv4 Address—Destination IPv4 address.

• Destination Port—Destination port.

• EBC Type—The EBC action to take. A value of pcap indicates that a pcap should be stored for the flow associated with this alert.

• EBC Depth—Capture depth. The depth can be connection, packet, or session. An empty string indicates that the default packet depth is used.

• EBC Timing—The delay in seconds before the EBC search and store for this alert occur. A value of -1 is the default and indicates that the EBC search and store for this alert occur when the end of the flow is detected or in 10 minutes, whichever is sooner.

• Protocol Identifier—Number that identifies which protocol is being used.

• Protocol Name—Name of the protocol being used.

• PX UUID—Universally unique identifier for this specific alert.

• Source IPv4 Address—Source IPv4 address.

• Source Port—Source port.

• Input End Time in Nanoseconds—The nanoseconds portion of the end time of the search time range.

• Input End Time in Seconds—The seconds portion of the end time of the search time range.

• Input Hash Field—Hash key for the status of this search.

• Input Limit—Requested maximum number of connection records to find.

• Input Score—Time when the search was created.

• Input Search Identifier—Generated search identifier that uniquely identifies this search.

• Input Search Type—Type of search requested: stream or all.

• Input Start Time in Nanoseconds—The nanoseconds portion of the start time of the search time range.

• Input Start Time in Seconds—The seconds portion of the start time of the search range.

• Input Time Format—Time format for input. A value of 1 indicates that the pcap time stamp is in microseconds; a value of 0 indicates that the pcap time stamp is in nanoseconds.

• Input User—User who made the search request.

• Input Window—The window of time before and after the specified start time that should be searched. If stime is used as a parameter, the window parameter is divided by two and subtracted from the stime to make a new start time. The window parameter is added to the original stime to make an etime. If stime is not specified, stime defaults to the current time. If etime and window are not specified, etime defaults to stime + 1 second.

• Input XPF—Filter provided by the end user.

• Output BPF—Generated XPF after input_xpf is processed by the XPF processing engine.

• Output Depth—Search depth. A search can be at the connection, packet, or session depth.

• Output Elapsed Time—Total elapsed time for all phases.

• Output First Flow Epoch—Time of the first flow recorded on the appliance.

• Output First Index Epoch—Time of the oldest connection packet index recorded on the appliance.

• Output First Packet Epoch—Time of the oldest packet stored on the appliance.

• Packet Index Elapsed Time—Total elapsed time of this phase.

• Packet Index End Time—End time of this phase in epoch time.

• Packet Index Found Records—Number of records found.

• Packet Index Status Message—Current status message for this phase.

• Packet Index Percent Complete—Percentage complete, of all potential packets found.

• Packet Index Range Percent—Percentage complete, based on captured packet times.

• Packet Index Searched Files—Number of files touched.

• Packet Index Start—Start time of this phase in epoch time.

• Packet Index Status—Status of this phase. Valid values are skipped, done, working, idle, and error.

• Last Update—Time when the search was last updated.

• Output Status Message—Status of the search.

• Packet Retrieval Elapsed Time—Total elapsed time of this phase.

• Packet Retrieval End Time—End time of this phase in epoch time.

• Packet Retrieval Found Records—Number of records found.

• Packet Retrieval Status Message—Current status message for this phase.

• Packet Retrieval Percent Complete—Percentage complete, of all potential packets found.

• Packet Retrieval Packet Size—Size of the packets processed.

• Packet Retrieval Start—Start time of this phase in epoch time.

• Packet Retrieval Status—Status of this phase. Valid values are skipped, done, working, idle, and error.

• Search End—Last record searched.

• Search Start—First record searched.

• Session Analysis Status Message—Current status message for this phase.

• Session Analysis Percent Complete—Percentage complete, of all potential packets found.

• Session Analysis Status—Status of this phase. Valid values are skipped, done, working, idle, and error.

• Output Status—Status of the search. Valid values are skipped, done, working, idle, and error.

• Stream Count—Number of nPulse streams.

• Connection Index Elapsed Time—Total elapsed time of this phase.

• Connection Index End Time—End time of this phase in epoch time.

• Connection Index Second—The last second of the last flow that the search examined.

• Connection Index First Connection—Epoch of the first connection found.

• Connection Index Found Records—Number of records found.

• Connection Index Last Connection—Current status message for this phase.

• Connection Index Percent Complete—Percentage complete, based on input_limit.

• Connection Index Status Message—Percentage complete, based on captured packet times.

• Connection Index Packet Count—Number of packets to be found, based on connection records.

• Connection Index Range Percent—Percentage complete, based on captured packet times.

• Connection Index Searched Bytes—Size of searched packets.

• Connection Index Start—Start time of this phase in epoch time.

• Connection Index Status—Status of this phase. Valid values are skipped, done, working, idle, and error.

• Store Name—Name that search is stored as.

• Status—A standard HTTP response message.

Example

{

"ebc": "true",

"faas": "true", "input_create_time": "1459173598", "input_depth": "packet", "input_ebc": [

{

"@timestamp": "2016-03-28T13:44:57.000001Z",

"alert": {

"action": "allowed", "duplicateCount": 0, "ruleClass": "", "ruleGID": 1,

"ruleMessage": "GET Method Found in HTTP Traffic From Client to Server", "rulePriority": 1,

"ruleRev": "0",

"ruleSID": 10000003

},

"destinationIPv4Address": "xxx.xxx.xxx.xxx", "destinationTransportPort": 80,

"ebc": "pcap",

"ebcDepth": "",

"ebcTiming": -1,

"protocolIdentifier": 6, "protocolIdentifierName": "TCP",

"pxuuid": "41270c8f-2074-4f3d-b58e-d6ae21c3fffa",

"sourceIPv4Address": "xxx.xxx.xxx.xxx", "sourceTransportPort": 42438

}

],

"input_etime_nanoseconds": "5",

"input_etime_second": "1459173298",

"input_hash_field": "SEARCH_8c9ffe11ea3f4e9eb306568b98fef545", "input_limit": "1",

"input_score": "1459173598.73",

"input_search_id": "8c9ffe11ea3f4e9eb306568b98fef545", "input_search_type": "all",

"input_stime_nanoseconds": "5",

"input_stime_second": "1459172396",

"input_time_format": "0", "input_user": "eventbasedcapture", "input_window": "1",

"input_xpf": "proto 6 and host xxx.xxx.xxx.xxx and port 42438 and host xxx.xxx.xxx.xxx and port 80", "output_bpf": "proto 6 and host xxx.xxx.xxx.xxx and port 42438 and host xxx.xxx.xxx.xxx and port 80", "output_depth": "packet",

"output_elapsed": "52.815",

"output_firstFlowEpoch": "1458614340",

"output_firstIndexEpoch": "0",

"output_firstPacketEpoch": "0",

"output_index_elapsed": "51.338",

"output_index_end": "1459173650",

"output_index_foundRecords": "0", "output_index_message": "Search complete", "output_index_packetPercent": "100",

"output_index_rangePercent": "100",

"output_index_searchedFiles": "0",

"output_index_start": "1459173598", "output_index_status": "done", "output_lastUpdate": "1459173651", "output_message": "Search complete", "output_packet_elapsed": "52.726",

"output_packet_end": "1459173650",

"output_packet_foundRecords": "0", "output_packet_message": "Search complete", "output_packet_packetPercent": "100",

"output_packet_processedBytes": "0",

"output_packet_start": "1459173598", "output_packet_status": "done", "output_searchEnd": "1459173651",

"output_searchStart": "1459173598", "output_session_message": "skipped", "output_session_packetPercent": "0", "output_session_status": "skipped", "output_status": "done", "output_streamCount": "4",

"output_xpf_elapsed": "51.337",

"output_xpf_end": "1459173650",

"output_xpf_extentSecond": "140024523784192",

"output_xpf_firstSecond": "140024523784192",

"output_xpf_foundRecords": "0",

"output_xpf_lastSecond": "140024523784192",

"output_xpf_limitPercent": "0", "output_xpf_message": "Search complete", "output_xpf_packetCount": "0",

"output_xpf_rangePercent": "0",

"output_xpf_searchedBytes": "0",

"output_xpf_start": "1459173598", "output_xpf_status": "done",

"store_name": "EBC_8c9ffe11ea3f4e9eb306568b98fef545", "target_depth": "packet"

}

cURL code sample: View EBC search history

The code sample was run with cURL 7.57.0.

curl -k –-user cpx:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/events/searchhistory

This cURL sample includes the following options:

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• --user cpx:hammerhead—Replace cpx with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/events/searchhistory—The EBC request URL. Replace xxx.xxx.xxx.xxx with the IP address of your Series appliance.

Results

This example returns a list of the 200 most recent EBC searches and the status. The output is in JSON.

View search details for a stored EBC event request

To view search details for a specific EBC event, send the following request:

GET https://<PX_IP_address>/api/4.0/events/stored/<search_id>

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

• search_id—The unique search identifier.

Example

GET https://xxx.xxx.xxx.xxx/api/4.0/events/stored/7b123

Required header:

--user cpx:hammerhead

View search details for a stored EBC event response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type] input_abort: [Input Abort] input_aborted_by: [Input Aborted By] input_create_time: [Input Create Time] input_depth: [Input Depth]

input_etime_nanoseconds: [Input End Time in Nanoseconds] input_etime_second: [Input End Time in Seconds] input_hash_field: [Input Hash Field]

input_limit: [Input Limit] input_score: [Input Score] input_search_id: [Input Search ID] input_search_type: [Input Search Type]

input_stime_nanoseconds: [Input Start Time in Nanoseconds] input_stime_second: [Input Start Time in Seconds] input_time_format: [Input Time Format]

input_user: [Input User] output_depth: [Output Depth] output_elapsed: [Output Elapsed Time]

output_firstFlowEpoch: [Output First Flow Epoch] output_firstIndexEpoch: [Output First Index Epoch] output_firstPacketEpoch: [Output First Packet Epoch] output_index_elapsed: [Packet Index Elapsed Time] output_index_end: [Packet Index End Time] output_index_foundRecords: [Packet Index Found Records] output_index_message: [Packet Index Status Message] output_index_packetPercent: [Packet Index Percent Complete] output_index_rangePercent: [Packet Index Range Percent] output_index_searchedFiles: [Packet Index Searched Files] output_index_start: [Packet Index Start] output_index_status: [Packet Index Status] output_lastUpdate: [Last Update]

output_message: [Output Status Message] output_packet_elapsed: [Packet Retrieval Elapsed Time] output_packet_end: [Packet Retrieval End Time] output_packet_foundRecords: [Packet Retrieval Found Records] output_packet_message: [Packet Retrieval Status Message]

output_packet_packetPercent: [Packet Retrieval Percent Complete] output_packet_processedBytes: [Packet Retrieval Packet Size] output_packet_start: [Packet Retrieval Start] output_packet_status: [Packet Retrieval Status] output_searchEnd: [Search End]

output_searchStart: [Search Start] output_session_elapsed: [Session Analysis Elapsed Time] output_session_end: [Session Analysis End Time]

output_session_message: [Session Analysis Status Message] output_session_packetPercent: [Session Analysis Percent Complete] output_session_start: [Session Analysis Start] output_session_status: [Session Analysis Status]

output_status: [Output Status] output_streamCount: [Stream Count]

output_xpf_elapsed: [Connection Index Elapsed Time] output_xpf_end: [Connection Index End Time] output_xpf_extentSecond: [Connection Index Second] output_xpf_firstSecond: [Connection Index First Connection] output_xpf_foundRecords: [Connection Index Found Records] output_xpf_lastSecond: [Connection Index Last Connection] output_xpf_limitPercent: [Connection Index Percent Complete] output_xpf_message: [Connection Index Status Message] output_xpf_packetCount: [Connection Index Packet Count] output_xpf_rangePercent: [Connection Index Range Percent] output_xpf_searchedBytes: [Connection Index Searched Bytes] output_xpf_start: [Connection Index Start] output_xpf_status: [Connection Index Status]

target_depth: [Target Depth]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Input Abort—How many searches were canceled.

• Input Aborted By—User who canceled the search.

• Input Create Time—Time at which the search was submitted.

• Input Depth—Search depth. A search can be at the connection, packet, or session depth.

• Input End Time in Nanoseconds—The nanoseconds portion of the end time of the search time range.

• Input End Time in Seconds—The seconds portion of the end time of the search time range.

• Input Hash Field—Hash key for the status of this search.

• Input Limit—Requested maximum number of connection records to find.

• Input Score—Time when the search was created.

• Input Search ID—Generated search identifier that uniquely identifies this search.

• Input Search Type—Type of search requested: stream or all.

• Input Start Time in Nanoseconds—The nanoseconds portion of the start time of the search time range.

• Input Start Time in Seconds—The seconds portion of the start time of the search range.

• Input Time Format—Time format for input. A value of 1 indicates that the pcap time stamp is in microseconds; a value of 0 indicates that the pcap time stamp is in nanoseconds.

• Input User—User who made the search request.

• Output Depth—Search depth. A search can be at the connection, packet, or session depth.

• Output Elapsed Time—Total elapsed time for all phases.

• Output First Flow Epoch—Time of the first flow recorded on the appliance.

• Output First Index Epoch—Time of the oldest connection packet index recorded on the appliance.

• Output First Packet Epoch—Time of the oldest packet stored on the appliance.

• Packet Index Elapsed Time—Total elapsed time of this phase.

• Packet Index End Time—End time of this phase in epoch time.

• Packet Index Found Records—Number of records found.

• Packet Index Status Message—Current status message for this phase.

• Packet Index Percent Complete—Percentage complete, of all potential packets found.

• Packet Index Range Percent—Percentage complete, based on captured packet times.

• Packet Index Searched Files—Number of files touched.

• Packet Index Start—Start time of this phase in epoch time.

• Packet Index Status—Status of this phase. Valid values are skipped, done, working, idle, and error.

• Last Update—Time when the search was last updated.

• Output Status Message—Status of the search.

• Packet Retrieval Elapsed Time—Total elapsed time of this phase.

• Packet Retrieval End Time—End time of this phase in epoch time.

• Packet Retrieval Found Records—Number of records found.

• Packet Retrieval Status Message—Current status message for this phase.

• Packet Retrieval Percent Complete—Percentage complete, of all potential packets found.

• Packet Retrieval Packet Size—Size of the packets processed.

• Packet Retrieval Start—Start time of this phase in epoch time.

• Packet Retrieval Status—Valid values are skipped, done, working, idle, and error.

• Search End—Last record searched.

• Search Start—First record searched.

• Session Analysis Elapsed Time—Total elapsed time of this phase.

• Session Analysis End Time—End time of this phase in epoch time.

• Session Analysis Status Message—Current status message for this phase.

• Session Analysis Percent Complete—Percentage complete, of all potential packets found.

• Session Analysis Start—Start time of this phase in epoch time.

• Session Analysis Status—Status of this phase. Valid values are skipped, done, working, idle, and error.

• Output Status—Status of the search. Valid values are skipped, done, working, idle, and error.

• Stream Count—Number of nPulse streams.

• Connection Index Elapsed Time—Total elapsed time of this phase.

• Connection Index End Time—End time of this phase in epoch time.

• Connection Index Second—The last second of the last flow that the search examined.

• Connection Index First Connection—Epoch of the first connection found.

• Connection Index Found Records—Number of records found.

• Connection Index Last Connection—Current status message for this phase.

• Connection Index Percent Complete—Percentage complete, based on input_limit.

• Connection Index Status Message—Percentage complete, based on captured packet times.

• Connection Index Packet Count—Number of packets to be found, based on connection records.

• Connection Index Range Percent—Percentage complete, based on captured packet times.

• Connection Index Searched Bytes—Size of searched packets.

• Connection Index Start—Start time of this phase in epoch time.

• Connection Index Status—Status of this phase. Valid values are skipped, done, working, idle, and error.

• Target Depth—Search depth. A search can be at the connection, packet, or session depth.

Example

HTTP/1.1 200 OK

Date: Wed, 16 Mar 2016 18:27:09 GMT

Content-Type: text/html; charset=UTF-8

{

"input_abort": "1", "input_aborted_by": "cpx", "input_create_time": "1458147967", "input_depth": "session", "input_etime_nanoseconds": "0",

"input_etime_second": "1441076400",

"input_hash_field": "SEARCH_b948090d35c54ca19d3570c9194e7863", "input_limit": "100",

"input_score": "1458147967.97",

"input_search_id": "b948090d35c54ca19d3570c9194e7863", "input_search_type": "all",

"input_stime_nanoseconds": "0",

"input_stime_second": "1251770399",

"input_time_format": "0", "input_user": "cpx", "output_depth": "session", "output_elapsed": "45.737",

"output_firstFlowEpoch": "1455051483",

"output_firstIndexEpoch": "1455051483",

"output_firstPacketEpoch": "1455051609",

"output_index_elapsed": "0.001",

"output_index_end": "1458147967",

"output_index_foundRecords": "0", "output_index_message": "Search complete", "output_index_packetPercent": "100",

"output_index_rangePercent": "100",

"output_index_searchedFiles": "0",

"output_index_start": "1458147967", "output_index_status": "done", "output_lastUpdate": "1458148013", "output_message": "Search complete", "output_packet_elapsed": "0.489",

"output_packet_end": "1458147967",

"output_packet_foundRecords": "0", "output_packet_message": "Search complete", "output_packet_packetPercent": "100",

"output_packet_processedBytes": "0",

"output_packet_start": "1458147967", "output_packet_status": "done", "output_searchEnd": "1458148013",

"output_searchStart": "1458147967",

"output_session_elapsed": "46.000",

"output_session_end": "1458148013", "output_session_message": "Search complete", "output_session_packetPercent": "100",

"output_session_start": "1458147967", "output_session_status": "done", "output_status": "done", "output_streamCount": "1",

"output_xpf_elapsed": "0.001",

"output_xpf_end": "1458147967",

"output_xpf_extentSecond": "140389596004352",

"output_xpf_firstSecond": "0",

"output_xpf_foundRecords": "0",

"output_xpf_lastSecond": "140389596004352",

"output_xpf_limitPercent": "0", "output_xpf_message": "Search complete", "output_xpf_packetCount": "0",

"output_xpf_rangePercent": "0",

"output_xpf_searchedBytes": "0",

"output_xpf_start": "1458147967", "output_xpf_status": "done", "target_depth": "session"

}

cURL code sample: View search details for a stored EBC event

The code sample was run with cURL 7.57.0.

curl -k --user cpx:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/events/stored/7b123

This cURL sample includes the following options:

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• --user cpx:hammerhead—Replace cpx with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/events/stored/7b123—The EBC request URL. Replace xxx.xxx.xxx.xxx with the IP address of your Series appliance. Replace 7b123 with the search ID of interest.

Results

This example returns the search details for the specified EBC event. The output is in JSON.

Retrieve search ID for EBC event UUID request

To retrieve the search ID that was created that contains the given event UUID, send the following request:

GET https://<PX_IP_address>/api/4.0/events/searchid/<event_UUID>

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

• event_UUID—The event UUID.

Example

GET https://xxx.xxx.xxx.xxx/api/4.0/events/searchid/7b123

Required header:

--user cpx:hammerhead

Retrieve search ID for EBC event UUID response

Note

This mapping is only available after the search is complete, and the packets are stored.

eventUUID: [Event UUID] searchID: [Search ID] status: [Status] message: [Message]

Response fields

• Event UUID—The event UUID.

• Search ID—The unique identifier of the search.

• Status—A standard HTTP response message.

• Message—Error message.

Example

{

"params" : { "eventUUID" : "70687a74-48ab-4cf3-be58-983be3b85080" }, "searchID" : "22b6af77db4f4756a0b7177f72325d1f",

"status" : "ok",

"message" : <message if failed>,

}

cURL code sample: Retrieve search ID for EBC event

The code sample was run with cURL 7.57.0.

curl -k--user cpx:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/events/searchid/7b123

This cURL sample includes the following options:

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• --user cpx:hammerhead—Replace cpx with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/events/searchid/7b123—The EBC request URL. Replace xxx.xxx.xxx.xxx with the IP address of your Series appliance. Replace 7b123 with the event UUID of interest.

Results

This example returns the search ID for a specified EBC event. The output is in JSON.

IA export

The following IA export endpoints are available:

• List IA export configuration request

GET https://<PX_IP_address>/api/4.0/config/export/ia

• List IA export directories request

GET https://<PX_IP_address>/api/4.0/config/export/ia/outputs

• List IA Flow directory configuration request

GET https://<PX_IP_address>/api/4.0/config/export/ia/outputs/flow

• List all flow filters request

GET https://<PX_IP_address>/api/4.0/config/export/ia/outputs/flow/filters

• List a flow filter by name request

GET https://<PX_IP_address>/api/4.0/config/export/ia/outputs/flow/filters/<filter_name>

• Add a flow filter request

POST https://<PX_IP_address>/api/4.0/config/export/ia/outputs/flow/filters

• Update a flow filter request

PUT https://<PX_IP_address>/api/4.0/config/export/ia/outputs/flow/filters/<filter-name>

• Delete a flow filter request

DELETE https://<PX_IP_address>/api/4.0/config/export/ia/outputs/flow/filters/<filter-name>

• Delete all flow filters request

DELETE https://<PX_IP_address>/api/4.0/config/export/ia/outputs/flow/filters

• List IA event directory configuration request

GET https://<PX_IP_address>/api/4.0/config/export/ia/outputs/event

• List all event filters request

GET https://<PX_IP_address>/api/4.0/config/export/ia/outputs/event/filters

• List an event filter by name request

GET https://<PX_IP_address>/api/4.0/config/export/ia/outputs/event/filters/<filter_name>

• Add an event filter request

POST https://<PX_IP_address>/api/4.0/config/export/ia/outputs/event/filters

• Update an event filter request

PUT https://<PX_IP_address>/api/4.0/config/export/ia/outputs/event/filters/<filter_name>

• Delete an event filter request

DELETE https://<PX_IP_address>/api/4.0/config/export/ia/outputs/event/filters/<filter-name>

• Delete all event filters request

DELETE https://<PX_IP_address>/api/4.0/config/export/ia/outputs/event/filters

List IA export configuration request

To list the full configuration for IA export, send the following request:

GET https://<PX_IP_address>/api/4.0/config/export/ia

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—Administrator username.

• password—Administrator password.

Example

GET https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia

Required header:

--user npadmin:hammerhead

List IA export configuration response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Description—A description of the IA export.

Example

HTTP/1.1 200 OK

Date: Tue, 07 Feb 2017 00:17:49 GMT

Content-Type: application/json; charset=utf-8

{

"flow": { "eventTypes": [

"X",

"x"

],

"filters": [

{

"eventTypes": [ "x"

],

"filter": "destinationTransportPort = 53"

}

]

},

"event": { "eventTypes": [

"A",

"B", "C"

],

"filters": [

{

"eventTypes": [ "C"

],

"filter": "sourceIPv4Address = 192.168.0.1"

}

]

},

"connectedIAs": [

{

"name": "ia33-249", "eventTypes": [

"filters": []

{

"A",

"B", "C"

],

},

"name": "ia-u19", "eventTypes": [

"E",

"a", "B"

],

"filters": []

},

{

"name": "ia-33-243", "eventTypes": [

"A",

"P", "D"

],

"filters": []

}

]

}

cURL code sample: List IA export configuration

The code sample was run with cURL 7.57.0.

curl -k --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia -X GET

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with your user name. Replace hammerhead with your password.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia—The IA export configuration request URL. Replace

xxx.xxx.xxx.xxx with the IP address of your Series appliance.

• -X GET—This option specifies using the GET method.

Results

This example lists the configuration for IA export. The output is in JSON.

List IA export event types—Request

To list all the event types that can be exported to the IA appliance, send the following request:

GET https://<PX_IP_address>/api/4.0/config/export/eventtypes

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—Administrator username.

• password—Administrator password.

Example

GET https://xxx.xxx.xxx.xxx/api/4.0/config/export/eventtypes

Required header:

--user npadmin:hammerhead

List IA export event types—response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Name—Event type.

• Description—Description of an event type.

Example

HTTP/1.1 200 OK

Date: Tue, 07 Feb 2017 00:17:49 GMT

Content-Type: application/json; charset=utf-8 [

{

"name": "Alert",

"description": "Suricata generated alerts from rules"

},

{

"name": "DHCP",

"description": "Dynamic Host Configuration Protocol"

},

{

"name": "DNS",

"description": "Domain Name System"

},

{

"name": "DNP3",

"description": "Distributed Network Protocol 3"

},

{

"name": "File",

"description": "File information"

},

{

"name": "FileInfo",

"description": "Embedded File metadata"

},

{

"name": "FTP",

"description": "File Transfer Protocol"

},

{

"name": "FTP_DATA",

"description": "File Transfer Protocol Data"

},

{

"name": "HTTP",

"description": "Hypertext Transfer Protocol"

},

{

"name": "IKEv2",

"description": "Internet Key Exchange v2"

},

{

"name": "IMAP",

"description": "Interet Message Access Protocol"

},

{

"name": "IRC",

"description": "Internet Relay Chat"

},

{

"name": "KRB5",

"description": "Kerberos V5"

},

{

"name": "NFS",

"description": "Network File System"

},

{

"name": "POP3",

"description": "Post Office Protocol version 3"

},

{

"name": "pxflow",

"description": "PX generated flow records"

},

{

"name": "pxflowdnsaggr",

"description": "DNS PX generated flow records, aggregated by source IP"

},

{

"name": "RADIUS",

"description": "Remote Authentication Dial-In User Service"

},

{

"name": "RDP",

"description": "Remote Desktop Protocol"

},

{

"name": "RTSP",

"description": "Real Time Sharing Protocol"

},

{

"name": "SIP",

"description": "Session Initiation Protocol"

},

{

"name": "SMB",

"description": "Server Message Block"

},

{

"name": "SMTP",

"description": "Simple Mail Transfer Protocol"

},

{

"name": "SNMP",

"description": "Simple Network Management Protocol"

},

{

"name": "SSH",

"description": "Secure Shell"

},

{

"name": "TACPLUS",

"description": "Cisco Terminal Access Controller Access-Control System Plus"

},

{

"name": "TFTP",

"description": "Trivial File Transfer Protocol"

},

{

"name": "TLS",

"description": "Transport Layer Security"

}

]

cURL code sample: List IA export event types

The code sample was run with cURL 7.57.0.

curl -k --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/export/eventtypes -X GET

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/export/eventtypes—The IA export event types request URL. Replace

xxx.xxx.xxx.xxx with the IP address of your Series appliance.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X GET—This option specifies using the GET method.

Results

This example lists all the event types for IA export. The output is in JSON.

Create IA export output—Request

To create an export directory on your appliance for exporting events to a particular appliance and to configure metadata of supported protocols to be written to the export directory along with filters, send the following request:

POST https://<PX_IP_address>/api/4.0/config/export/ia/outputs

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the appliance running the API.

• username—Administrator username.

• password—Administrator password.

Required body:

{

"name": "iahostname1",

"eventTypes": ["HTTP", "DNS", "SMTP"],

"filters": [

{

"name": "port 80", "eventTypes": [ "HTTP"

],

"filter": "destinationTransportPort = 80 OR sourceTransportPort = 80"

}

]

}

Parameters

• name—Hostname of an IA appliance that you wish to pair with your appliance and export metadata.

• eventTypes (optional)—The event types that you wish to export to the specified IA appliance.

• filters (optional)—The filters applied to the exported metadata.

Example

POST https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs

Required header:

--user npadmin:hammerhead

Create IA export output response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Description—A description of the IA export.

Example

HTTP/1.1 200 OK

Date: Tue, 07 Feb 2017 00:17:49 GMT

Content-Type: application/json; charset=utf-8

{

"eventTypes": ["HTTP", "DNS", "SMTP"],

"filters": [

{

"name": "port 80", "eventTypes": [ "HTTP"

],

"filter": "destinationTransportPort = 80 OR sourceTransportPort = 80"

}

]

}

cURL code sample: Create IA export output

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs -k -X POST -d '{"name": "hostname1","eventTypes": ["HTTP"], "filter": "destinationTransportPort = 80 OR sourceTransportPort = 80"}'

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with your user name. Replace hammerhead with your password.

• https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs—Request URL. Replace xxx.xxx.xxx.xxx with the IP address of your Series appliance.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X POST —This option specifies using the POST method.

• -d '{"name": "hostname1","eventTypes": ["HTTP"], "filter": "destinationTransportPort = 80 OR sourceTransportPort = 80"}'—Replace hostname1 with the hostname of an IA appliance that you wish to pair with your appliance and export the metadata to the specified IA appliance. Replace HTTP with the event types that you wish to export. Replace destinationTransportPort = 80 OR sourceTransportPort = 80 with the filter that you wish to apply to the metadata export.

Results

This example pairs an appliance with your appliance and exports metadata for the specified event types (with filters) to the export directory hostname1.

To create an export directory on your appliance for exporting events to a particular appliance and to configure metadata of

supported protocols to be written to the export directory along with filters, send the following request:

Update IA export output—Request

To update the event types or filters for an IA export, send the following request:

Put https://<PX_IP_address>/api/4.0/config/export/ia/outputs/<output_name>

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—Administrator username.

• password—Administrator password.

Required body:

{

"eventTypes": ["HTTP"] "filters": [

{

"name": "port 80", "eventTypes": [

"HTTP"],

"filter": "destinationTransportPort = 80 OR sourceTransportPort = 80"

}

]

}

Parameters

• output_name—IA-export directory of an IA export that you wish to update.

• eventTypes (optional)—The event types that you wish to export to the specified IA appliance.

• filters (optional)—The filters applied to the exported metadata.

Example

Put https://<PX_IP_address>/api/4.0/config/export/ia/outputs/<OUTPUT_NAME>

Required header:

--user npadmin:hammerhead

Update IA export—Response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Description—A description of the IA export.

Example

HTTP/1.1 200 OK

Date: Tue, 07 Feb 2017 00:17:49 GMT

Content-Type: application/json; charset=utf-8

{

"eventTypes": ["HTTP"], "filters": [

{

"name": "port 80", "eventTypes": [ "HTTP"

],

"filter": "destinationTransportPort = 80 OR sourceTransportPort = 80"

}

]

}

cURL code sample: Update IA export output

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/iahostname1 -k -X PUT -d '{"eventTypes": ["HTTP"]}'

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with your user name. Replace hammerhead with your password.

• https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/iahostname1—Request URL. Replace xxx.xxx.xxx.xxx with the IP address of your Series appliance. Replace iahostname1 with the IA directory name of an IA export that you wish to update.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X PUT—This option specifies using the PUT method.

• -d '{"eventTypes": ["HTTP"]}'—Replace HTTP with the event types that you wish to export.

Results

This example updates the event types or filters for the specified IA export.

List IA export directories request

To list all the IA export directories of your appliance, send the following request:

GET https://<PX_IP_address>/api/4.0/config/export/ia/outputs

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the appliance running the API.

• username—Administrator username.

• password—Administrator password.

Example

GET https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs

Required header:

--user npadmin:hammerhead

List IA export directories response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• Description—A description of the IA export.

Example

HTTP/1.1 200 OK

Date: Tue, 07 Feb 2017 00:17:49 GMT

Content-Type: application/json; charset=utf-8

[

"flow",

"event", "iahostname1", "iahostname2"

]

cURL code sample: List IA export directories

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs -k -X GET

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with your user name. Replace hammerhead with your password.

• https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs—Request URL. Replace xxx.xxx.xxx.xxx with the IP address of your appliance.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X GET—This option specifies using the GET method.

Results

This example lists the IA directories for metadata export. The output is in JSON.

List IA flow directory configuration request

To list the flow directory configuration for IA, send the following request: GET https://<PX_IP_address>/api/4.0/config/export/ia/outputs/flow Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the appliance running the Series API.

• username—The user name for your appliance.

• password—The password for your appliance.

Example

GET https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/flow

Required header:

--user npadmin:hammerhead

List IA flow directory configuration response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content-ype—The response format.

• eventTypes—Only "X" and "x" are valid event types. These are the only event types that correspond to flow-related data.

• filters—Filter query.

Example

The top level eventTypes represents all of the metadata event types that will be written to this directory assuming no filters. Filters allow the user to "trim" the metadata that is written. They are associated with a set of event types. If the event type of the metadata record does not match, the filter will not be applied and the record will be written. A filter may have multiple event types (shown below). An event type may have multiple filters (also shown below). For example, the configuration below will filter all flow records that have a destination port of 53. It will also filter out all flow records and aggregated DNS flow records that have a source IPv4 address of 192.168.10.155.

HTTP/1.1 200 OK

Date: Tue, 06 Feb 2018 00:17:39 GMT

Content-Type: application/json; charset=utf-8

{

"eventTypes" : [ "X",

"x"

],

"filters": [

{

"name": "dns-traffic" "eventTypes" : [

"x"

],

"filter": "destinationTransportPort = 53"

},

{

"name" : "bobs-annoying-app" "eventTypes": [

"x", "X"

],

"filters": "sourceIPv4Address = 192.168.10.155"

}

]

}

cURL code sample: List IA flow directory configuration

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/flow -k -X GET

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with the user name for your Series appliance. Replace hammerhead with the password for your appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/flow—The component configuration request URL. Replace xxx.xxx.xxx.xxx with the IP address of your appliance.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X GET—This option specifies using the GET method.

Results

This example lists the flow directory configuration for IA export. The output is in JSON.

List all flow filters request

To list all flow filters for IA, send the following request:

GET https://<PX_IP_address>/api/4.0/config/export/ia/outputs/flow/filters

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Example

GET https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/flow/filters

Required header:

--user npadmin:hammerhead

Lsit all flow filters response

The response is a list of filter names.

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type]

[

"filter1", "filter2"

]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content-ype—The response format.

Example

HTTP/1.1 200 OK

Date: Tue, 06 Feb 2018 05:12:09 GMT

Content-Type: application/json; charset=utf-8 [

"dis-traffic", "bobs-annoying-app"

]

cURL code sample: List all flow filters

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/flow/filters -k -X GET

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/flow/filters—The filter request URL. Replace

xxx.xxx.xxx.xxx with the IP address of your Series appliance.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X GET—This option specifies using the GET method.

Results

This example lists all flow filters. The output is in JSON.

List a flow filter by name request

To create a new flow filter for IA, send the following request:

GET https://<PX_IP_address>/api/4.0/config/export/ia/outputs/flow/filters/<filter_name>

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

• filter_name—(string) The name of the filter to return.

Example

GET https://xxx.xxx.xx.xxx/api/4.0/config/export/ia/outputs/flow/filters/myfilter

Required header:

--user npadmin:hammerhead

List a flow filter by name response

The response is a list of filter names.

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type]

{

"name" : "string" "eventTypes": [

"x", "X"

],

"filters": "string"

}

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content-ype—The response format.

Example

HTTP/1.1 200 OK

Date: Tue, 06 Feb 2018 05:12:09 GMT

Content-Type: application/json; charset=utf-8

{

"name" : "bobs-annoying-app" "eventTypes": [

"x", "X"

],

"filters": "sourceIPv4Address = 192.168.10.155"

}

cURL code sample: List a flow filter by name

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/flow/filters/myfilter -k

-X GET

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with the user name for your PX Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/flow/filters/myfilter—The filter request URL. Replace

xxx.xxx.xxx.xxx with the IP address of your Series appliance, and myfilter with the name of the filter to list.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X GET—This option specifies using the GET method.

Results

This example lists the flow filter named myfilter. The output is in JSON.

Add a flow filter request

To create a new flow filter for IA, send the following request:

POST https://<PX_IP_address>/api/4.0/config/export/ia/outputs/flow/filters

Note

To use this request, you must belong to the sudo group.

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Request body:

{

"name": "string", "eventTypes": [

"x"

],

"filter": "string"

}

Example

POST https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/flow/filters

Required header:

--user npadmin:hammerhead

Request body:

{

"name": "mynewfilter", "eventTypes": [

"x"

],

"filter": "sourceIPv4Address = 10.10.10.1 AND destinationTransportPort = 80"

}

Add a flow filter response

The response is a JSON object detailing the filter. In a successful request the object you sent will be returned back to you.

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type]

{

"name": "string", "eventTypes": [

"x"

],

"filter": "string"

}

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content-ype—The response format.

• eventTypes—Only "X" and "x" are valid event types. These are the only event types that correspond to flow-related data.

• filter—String detailing the filter.

Example

Filters allow the user to "trim" the metadata that is written. They are associated with a set of event types. If the event type of the metadata record does not match, the filter will not be applied and the record will be written. A filter may have multiple event types, and an event type may have multiple filters. For example, the configuration below will filter all flow records that have a destination port of 80. It will also filter out all flow records and aggregated DNS flow records that have a source IPv4 address of 10.10.10.1.

HTTP/1.1 200 OK

Date: Tue, 06 Feb 2018 05:12:09 GMT

Content-Type: application/json; charset=utf-8

{

"name": "mynewfilter", "eventTypes": [

"x"

],

"filter": "sourceIPv4Address = 10.10.10.1 AND destinationTransportPort = 80"

}

cURL code sample: Add a flow filter

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/flow/filters -k -X POST

-d ' { "name": "mynewfilter", "eventTypes": [ "x" ], "filter": "sourceIPv4Address = 10.10.10.1 AND destinationTransportPort = 80" }'

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/flow/filters—The filter request URL. Replace

xxx.xxx.xxx.xxx with the IP address of your Series appliance.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X POST—This option specifies using the POST method.

• -d '{ "name": "mynewfilter", "eventTypes": [ "x" ], "filter": "sourceIPv4Address = 10.10.10.1 AND destinationTransportPort = 80" }'—Specifies the name, event type, and filter parameters of the new flow filter.

Results

This example creates a flow filter. The output is in JSON.

Update a flow filter request

To update an existing flow filter for IA, send the following request:

PUT https://<PX_IP_address>/api/4.0/config/export/ia/outputs/flow/filters/<filter-name>

Note

To use this request, you must belong to the sudo group.

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

• filter-name—The name of the filter to update.

Request body:

{

"name": "string",

"eventTypes": [ "x"

],

"filter": "string"

}

Example

PUT https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/flow/filters/my-old-filter

Required header:

--user npadmin:hammerhead

Request body:

{

"name": "mynewfilter", "eventTypes": [

"x"

],

"filter": "sourceIPv4Address = 10.10.10.1 AND destinationTransportPort = 80"

}

Update a flow filter response

The response is a JSON object detailing the filter. In a successful request the object you sent will be returned back to you.

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type]

{

"name": "string", "eventTypes": [

"x"

],

"filter": "string"

}

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content-type—The response format.

• eventTypes—Only "X" and "x" are valid event types. These are the only event types that correspond to flow-related data.

• filter—String detailing the filter.

Example

HTTP/1.1 200 OK

Date: Tue, 06 Feb 2018 05:12:09 GMT

Content-Type: application/json; charset=utf-8

{

"eventTypes": [ "X"

]

"filter": "flow.sortedHashValue = 2048"

}

cURL code sample: Update a flow filter

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/flow/filters -k -X PUT

-d '{ "eventTypes": [ "X" ] "filter": "flow.sortedHashValue = 2048" }'

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with the user name for your PX Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/flow/filters—The filter request URL. Replace

xxx.xxx.xxx.xxx with the IP address of your Series appliance.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X PUT—This option specifies using the PUT method.

• -d '{ "eventTypes": [ "X" ] "filter": "flow.sortedHashValue = 2048" }'

Results

This example updates a flow filter. The output is in JSON.

Delete a flow filter request

To delete a flow filter for IA, send the following request:

DELETE https://<PX_IP_address>/api/4.0/config/export/ia/outputs/flow/filters/<filter-name>

Note

To use this request, you must belong to the sudo group.

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

• filter-name—The name of the filter to delete.

Example

DELETE https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/flow/filters/my-filter

Required header:

--user npadmin:hammerhead

Delete a flow filter response

The response is a JSON object detailing the filter. In a successful request the object you sent will be returned back to you.

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type]

Response fields

• Response Code—A standard HTML response code indicating success or failure

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content-type—The response format.

Example

HTTP/1.1 200 OK

Date: Tue, 06 Feb 2018 05:12:09 GMT

Content-Type: application/json; charset=utf-8

cURL code sample: Delete a flow filter

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/flow/filters/my-filter

-k -X DELETE

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/flow/filters/my-filter—The filter request URL. Replace

xxx.xxx.xxx.xxx with the IP address of your Series appliance.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X DELETE—This option specifies using the DELETE method.

Results

This example deletes the specified flow filter.

Delete all flow filters request

To delete a flow filter for IA, send the following request:

DELETE https://<PX_IP_address>/api/4.0/config/export/ia/outputs/flow/filters

Note

To use this request, you must belong to the sudo group.

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Example

DELETE https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/flow/filters

Required header:

--user npadmin:hammerhead

Delete all flow filters response

The response is a JSON object detailing the filter. In a successful request the object you sent will be returned back to you.

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type]

Response fields

• Response Code—A standard HTML response code indicating success or failure

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content-type—The response format.

Example

HTTP/1.1 200 OK

Date: Tue, 06 Feb 2018 05:12:09 GMT

Content-Type: application/json; charset=utf-8

cURL code sample: Delete all flow filters

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/flow/filters -k -X DELETE

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/flow/filters—The filter request URL. Replace

xxx.xxx.xxx.xxx with the IP address of your Series appliance.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X DELETE—This option specifies using the DELETE method.

Results

This example deletes all flow filters.

List IA event directory configuration request

To list the current event directory configuration for IA export, send the following request:

GET https://<PX_IP_address>/api/4.0/config/export/ia/outputs/event

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Example

GET https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/event

Required header:

--user npadmin:hammerhead

List IA event directory configuration response

The top level eventTypes represents all of the metadata event types that will be written to this directory assuming no filters. Filters allow the user to "trim" the metadata that is written. They are associated with a set of event types. If the event type of the metadata record does not match, the filter will not be applied and the record will be written. As with flow, a filter may have multiple event types that it should be applied to, and an event type may have multiple filters.

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type]

{

"eventTypes" : [ "B",

"2", "A"

],

"filters": [

{

"name": "string", "eventTypes" : [

"A"

],

"filter": "string"

}

]

}

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• eventTypes—The event types the filter applies to.

• filters—The filters to apply.

Example

The example below shows how to access nested JSON keys using "." notation.

HTTP/1.1 200 OK

Date: Tue, 06 Feb 2018 00:13:11 GMT

Content-Type: application/json; charset=utf-8

{

"eventTypes" : [ "B",

"2", "A"

],

"filters": [

{

"name": "test-alert", "eventTypes" : [

"A"

],

"filter": "alert.message = \"Hello, world\""

}

]

}

The filter will apply if a JSON object looks as follows: Match:

{

"alert": {

"message": "Hello, world"

}

}

No match:

{

"message": "Hello, world"

}

cURL code sample: List IA event directory configuration

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/event -k -X GET'

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/event—The component configuration request URL. Replace xxx.xxx.xxx.xxx with the IP address of your Series appliance.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X GET—This option specifies using the GET method.

Results

This example lists the event directory configuration. The output is in JSON.

List all event filters request

To list all event filters for IA, send the following request:

GET https://<PX_IP_address>/api/4.0/config/export/ia/outputs/event/filters

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Example

GET https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/event/filters

Required header:

--user npadmin:hammerhead

List all event filters response

The response is a list of filter names.

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type]

[

"string"

]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content-type—The response format.

Example

HTTP/1.1 200 OK

Date: Tue, 06 Feb 2018 05:12:09 GMT

Content-Type: application/json; charset=utf-8

[

"test-alert"

]

cURL code sample: List all event filters

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/event/filters -k -X GET

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/event/filters—The filter request URL. Replace

xxx.xxx.xxx.xxx with the IP address of your Series appliance.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X GET—This option specifies using the GET method.

Results

This example lists all event filters. The output is in JSON.

List an event filter by name request

To list a specific event filter for IA, send the following request:

GET https://<PX_IP_address>/api/4.0/config/export/ia/outputs/event/filters/<filter_name>

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

• filter_name—The name of the event filter.

Example

GET https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/event/filters/test-alert

Required header:

--user npadmin:hammerhead

List an event filter by name response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type]

{

"name" : "<string>" "eventTypes": [

"A"

],

"filters": "<string>"

}

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content-ype—The response format.

Example

HTTP/1.1 200 OK

Date: Tue, 06 Feb 2018 05:12:13 GMT

Content-Type: application/json; charset=utf-8

{

"name" : "test-alert" "eventTypes": [

"A"

],

"filters": "alert.message = \"Hello, world\""

}

cURL code sample: List an event filter by name

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/event/filters/test-alert

-k -X GET

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/event/filters/test-alert—The filter request URL. Replace xxx.xxx.xxx.xxx with the IP address of your Series appliance, and test-alert with the name of your filter.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X GET—This option specifies using the GET method.

Results

This example lists the event filter named test-alert. The output is in JSON.

Add an event filter request

To create a new event filter for IA, send the following request:

POST https://<PX_IP_address>/api/4.0/config/export/ia/outputs/event/filters

Note

To use this request, you must belong to the sudo group.

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Request body:

{

"name": "string", "eventTypes": [

"x"

],

"filter": "string"

}

Example

POST https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/event/filters

Required header:

--user npadmin:hammerhead

Request body:

{

"name": "<string>", "eventTypes": [

"<string>"

],

"filter": "<string>"

}

Add an event filter response

The response is a JSON object detailing the filter. In a successful request the object you sent will be returned back to you.

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type]

{

"name": "mynewfilter", "eventTypes": [

"B",

"A",

"2"

],

"filter": "sourceIPv4Address = 10.10.10.1 AND destinationTransportPort = 80"

}

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content-type—The response format.

• eventTypes—The event types that correspond to event-related data.

• filter—String detailing the filter.

Example

HTTP/1.1 200 OK

Date: Tue, 06 Feb 2018 05:12:09 GMT

Content-Type: application/json; charset=utf-8

{

"name": "mynewfilter", "eventTypes": [

"B",

"A", "2"

],

"filter": "sourceIPv4Address = 10.10.10.1 AND destinationTransportPort = 80"

}

cURL code sample: Add an event filter

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/event/filters -k -X POST

-d '{"name": "mynewfilter","eventTypes": ["B","A","2"], "filter": "sourceIPv4Address = 10.10.10.1 AND destinationTransportPort = 80"}'

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/event/filters—The filter request URL. Replace

xxx.xxx.xxx.xxx with the IP address of your Series appliance.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X POST—This option specifies using the POST method.

• -d '{"name": "mynewfilter","eventTypes": ["B","A","2"], "filter": "sourceIPv4Address = 10.10.10.1 AND destinationTransportPort = 80"}'—Specifies the name, event type, and filter parameters of the new event filter.

Results

This example creates an event filter. The output is in JSON.

Update an event filter request

To update an event filter for IA, send the following request:

PUT https://<PX_IP_address>/api/4.0/config/export/ia/outputs/event/filters/<filter_name>

Note

To use this request, you must belong to the sudo group.

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

• filter_name—The name of the event filter.

Request body:

{

"eventTypes": [

"<string>"

]

"filter": "<string>"

}

Example

PUT https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/event/filters/test-alert

Required header:

--user npadmin:hammerhead

Request body to update filter:

{

"filter": "alert.class = \"malware\""

}

Request body to update eventTypes:

{

"eventTypes" : [ "2"

]

}

Request body to update eventTypes and filter:

{

"eventTypes": [ "2"

]

"filter": "alert.class = \"malware\""

}

Update an event filter response

The response is a JSON object detailing the filter. In a successful request the object you sent will be returned back to you.

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type]

{

"name" : "<string>" "eventTypes": [

"A"

],

"filters": "<string>"

}

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content-type—The response format.

• eventTypes—The event types that correspond to event-related data.

• filter—String detailing the filter.

Example

HTTP/1.1 200 OK

Date: Tue, 06 Feb 2018 05:12:09 GMT

Content-Type: application/json; charset=utf-8

{

"name" : "test-alert" "eventTypes": [

"A"

],

"filters": "alert.class = \"malware\""

}

cURL code sample: Update an event filter

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/event/filters/test-alert

-k -X PUT -d '{"eventTypes": [ "2" ] "filter": "alert.class = \"malware\""}'

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/event/filters/test-alert—The filter request URL. Replace xxx.xxx.xxx.xxx with the IP address of your Series appliance.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X PUT—This option specifies using the PUT method.

• -d '{"eventTypes": [ "2" ] "filter": "alert.class = \"malware\""}'—Specifies the new event type and filter parameters of the event filter.

Results

This example updates an event filter. The output is in JSON.

Delete an event filter request

To delete an event filter for IA, send the following request:

DELETE https://<PX_IP_address>/api/4.0/config/export/ia/outputs/event/filters/<filter-name>

Note

To use this request, you must belong to the sudo group.

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

• filter-name—The name of the filter to delete.

Example

DELETE https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/event/filters/my-filter

Required header:

--user npadmin:hammerhead

Delete an event filter response

The response is a JSON object detailing the filter. In a successful request the object you sent will be returned back to you.

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type]

Response fields

• Response Code—A standard HTML response code indicating success or failure

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content-type—The response format.

Example

HTTP/1.1 200 OK

Date: Tue, 06 Feb 2018 05:12:09 GMT

Content-Type: application/json; charset=utf-8

cURL code sample: Delete an event filter

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/event/filters/my-filter

-k -X DELETE

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/event/filters/my-filter—The filter request URL. Replace xxx.xxx.xxx.xxx with the IP address of your Series appliance.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X DELETE—This option specifies using the DELETE method.

Results

This example deletes the specified event filter.

Delete all event filters request

To delete an event filter for IA, send the following request:

DELETE https://<PX_IP_address>/api/4.0/config/export/ia/outputs/event/filters

Note

To use this request, you must belong to the sudo group.

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

Example

DELETE https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/event/filters

Required header:

--user npadmin:hammerhead

Delete all event filters response

The response is a JSON object detailing the filter. In a successful request the object you sent will be returned back to you.

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type]

Response fields

• Response Code—A standard HTML response code indicating success or failure

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content-type—The response format.

Example

HTTP/1.1 200 OK

Date: Tue, 06 Feb 2018 05:12:09 GMT

Content-Type: application/json; charset=utf-8

cURL code sample: Delete all event filters

The code sample was run with cURL 7.57.0.

curl --user npadmin:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/event/filters -k -X DELETE

This cURL sample includes the following options:

• --user npadmin:hammerhead—Replace npadmin with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/config/export/ia/outputs/event/filters—The filter request URL. Replace

xxx.xxx.xxx.xxx with the IP address of your Series appliance.

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• -X DELETE—This option specifies using the DELETE method.

Results

This example deletes all event filters.

Results

Use the results endpoints to examine, store, and unstore search results:

• Connection list request

GET https://<PX_IP_address>/api/4.0/results/<search_id>

• Connection summary request

GET https://<PX_IP_address>/api/4.0/results/<search_id>/sessionsdl/connectionSummary.json

• Download file request

GET https://<PX_IP_address>/api/4.0/results/<search_id>/sessionsdl/files/file.<file_id>

• Packet list request

GET https://<PX_IP_address>/api/4.0/results/<search_id>/<connection_index>

• Single packet detail request

GET https://<PX_IP_address>/api/4.0/results/<search_id>/<connection_index>/<packet_index>

• Session information request

GET https://<PX_IP_address>/api/4.0/results/<search_id>/sessions

• Store search results request

POST https://<PX_IP_address>/api/4.0/search/<search_id>/<newname>

• Remove stored search results request

POST https://<PX_IP_address>/api/4.0/search/<search_id>/<search_id>

• List stored search results request

GET https://<PX_IP_address>/api/4.0/search/stored

• Analyze connections request

GET https://<PX_IP_address>/api/4.0/results/<search_id>/packets

• Download packets request

GET https://<PX_IP_address>/api/4.0/results/<search_id>/packets

Connection list request

To get a connection list after the search is complete, send the following request:

GET https://<PX_IP_address>/api/4.0/results/<search_id>

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

• search_id—The unique search identifier.

Query parameters

• r_index—Specifies which connection to start with in the response. The first index is zero. For example, r_index=5 specifies that the results are shown from the fifth index (4).

• r_count—Number of connection records to be returned, used in pagination.

• xpf—Filter to reduce the results set; it supports BPF as defined at http://www.tcpdump.org/manpages/pcap-filter.7.html. It is also used with PX-specific connection attributes, see Connection metadata properties. Sample formatting is host

127.0.0.1 && packetdeltacountin>25.

Example

GET https://xxx.xxx.xxx.xxx/api/4.0/results/7b123?r_index=0&r_count=250

Required header:

--user cpx:hammerhead

Connection list response

stime: [Start Time] etime: [End Time]

ethsaddr: [Ethernet Start Address] ethdaddr: [Ethernet Destination Address] saddr4: [Source IPv4 Address]

daddr4: [Destination IPv4 Address] saddr6: [Source IPv6 Address] daddr6: [Destination IPv6 Address] version: [Version]

saddr: [Source Address] daddr: [Destination Address] proto: [Protocol]

sport: [Source Port] dport: [Destination Port]

sportdisplay: [Source Port Display] dportdisplay: [Destination Port Display] vlan: [VLAN]

stream: [Stream]

classification: [Classification] spackets: [Source Packets] dpackets: [Destination Packets] sflags: [Source Flags]

dflags: [Destination Flags] flags: [Flags]

index: [Index]

Response fields

• Start Time—Date and time from which the search started. The format is a floating-point epoch time stamp.

• End Time—Date and time at which the search ended. The format is a floating-point epoch time stamp.

• Ethernet Start Address—Ethernet start address.

• Ethernet Destination Address—Ethernet destination address.

• Source IPv4 Address—Source IPv4 address.

• Destination IPv4 Address—Destination IPv4 address.

• Source IPv6 Address—Source IPv6 address.

• Destination IPv6 Address—Destination IPv6 address.

• Version—Version.

• Source Address—Source IPv4 or IPv6 address, depending on which one was used.

• Destination Address—Destination IPv4 or IPv6 address, depending on which one was used.

• Protocol—The transport layer protocol of the connection.

• Source Port—Source port.

• Destination Port—Destination port.

• Source Port Display—Source port display.

• Destination Port Display—Destination port display.

• VLAN—Number of virtual LANs.

• Stream—Number of nPulse streams.

• Classification—Application data classification.

• Source Packets—Number of source packets.

• Destination Packets—Number of destination packets.

• Source Flags—Number of source warnings.

• Destination Flags—Number of destination warnings.

• Flags—Total number of warnings.

• Index—Zero-based index of first connection from search result.

Example

[

{

"stime": "1455051483.829782000",

"etime": "1455051483.829782000",

"ethsaddr": "7e:ae:46:66:ed:0f",

"ethdaddr": "01:00:5e:00:00:01",

"saddr4": xxx.xxx.xxx.xxx",

"daddr4": xxx.xxx.xxx.xxx",

"saddr6": "",

"daddr6": "", "version": 4,

"saddr": "xxx.xxx.xxx.xxx",

"daddr": "xxx.xxx.xxx.xxx", "proto": 2,

"sport": "",

"dport": "",

"sportdisplay": "",

"dportdisplay": "",

"vlan": "", "stream": 0,

"classification": "IGMP", "spackets": 1,

"dpackets": 0,

"sflags": 0,

"dflags": 0,

"flags": 0,

"index": 0

},

{

"stime": "1455051483.829789000",

"etime": "1455051483.829789000",

"ethsaddr": "7e:ae:46:66:ed:0f",

"ethdaddr": "33:33:00:00:00:01",

"saddr4": "",

"daddr4": "",

"saddr6": "fe80::7cae:46ff:fe66:ed0f", "daddr6": "ff02::1",

"version": 6,

"saddr": "fe80::7cae:46ff:fe66:ed0f",

"daddr": "ff02::1", "proto": 0, "sport": "",

"dport": "",

"sportdisplay": "",

"dportdisplay": "",

"vlan": "", "stream": 0,

"classification": "ICMPV6", "spackets": 1,

"dpackets": 0,

"sflags": 0,

"dflags": 0,

"flags": 0,

"index": 1

}

]

cURL code sample: Connection list

The code sample was run with cURL 7.57.0.

curl -k --user cpx:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/results/7b123?r_index=0&r_count=250&xpf=port+80

This cURL sample includes the following options:

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• --user cpx:hammerhead—Replace cpx with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/results/7b123?r_index=0&r_ count=250&xpf=port+80—The results request URL. Replace xxx.xxx.xxx.xxx with the IP address of your Series appliance. Replace 7b123 with the search ID of interest.

Note

Enclose the URL in double quotation marks if it includes special characters such as [, ], {, }, ?, &, and *.

Results

This example returns the first 250 connection records for the specified search after it is complete. The output is in JSON.

Connection summary request

To get a connection summary for a completed search, send the following request:

GET https://<PX_IP_address>/api/4.0/results/<search_id>/sessionsdl/connectionSummary.json

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

• search_id—The unique search identifier.

Example

GET https://xxx.xxx.xxx.xxx/api/4.0/results/7b123/sessionsdl/connectionSummary.json

Required header:

--user cpx:hammerhead

Connection summary response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type] xpf: [XPF]

index: [Index]

packet: [Packet Status] session: [Session Status] count: [Count]

addr: [Address] srcCount: [Source Count]

dstCount: [Destination Count] srcPackets: [Source Packets] dstPackets: [Destination Packets] srcOctets: [Source Octets] dstOctets: [Destination Octets] port: [Port]

proto: [Protocol] packets: [Packets] octets: [Octets]

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

• XPF—Filter that supports BPF as defined at http://www.tcpdump.org/manpages/pcap-filter.7.html. It is also used with PX-specific connection attributes; see Connection metadata properties. Sample formatting is host 127.0.0.1 && packetdeltacountin>25.

• Index—Zero-based index of first connection from search result.

• Packet Status—Status of the packet search. Valid values are skipped, done, working, idle, and error.

• Session Status—Status of the session search. Valid values are skipped, done, working, idle, and error.

• Count—Number of records.

• Address—IP address.

• Source Count—Number of source records.

• Destination Count—Number of destination records.

• Source Packets—Number of source packets.

• Destination Packets—Number of destination packets.

• Source Octets—Size of source records.

• Destination Octets—Size of destination records.

• Protocol—The transport layer protocol of the connection.

• Packets—The number of packets.

• Octets—The size of packets.

Example

HTTP/1.1 200 OK

Date: Thu, 30 Mar 2017 20:48:31 GMT

Content-Type: application/json; charset=utf-8

{

"Processes": { "xpf":"done",

"index":"done",

"packet":"skipped", "session":"skipped"

},

"IPaddr": {

"count": 2,

"records": [

{

"addr": "24.203.30.73",

"srcCount": 1,

"dstCount": 0,

"srcPackets": 28,

"dstPackets": 39,

"srcOctets": 5636,

"dstOctets": 49473

},

{

"addr": "64.18.84.36",

"srcCount": 0,

"dstCount": 1,

"srcPackets": 0,

"dstPackets": 28,

"srcOctets": 0,

"dstOctets": 5636

}

]

},

"Port": {

"count": 2,

"records": [

{

"port": 51959,

"srcCount": 1,

"dstCount": 0,

"srcPackets": 28,

"dstPackets": 39,

"srcOctets": 5636,

"dstOctets": 49473

},

{

"port": 80,

"srcCount": 0,

"dstCount": 1,

"srcPackets": 0,

"dstPackets": 28,

"srcOctets": 0,

"dstOctets": 5636

}

]

},

"Proto":

{

"count": 1,

"records": [

{

"proto": 6,

"count": 1,

"packets": 67,

"octets": 55109

}

]

},

"Class": {

"count": 1,

"records": [

{

"class": "0x0800", "count": 1,

"packets": 67,

"octets": 55109

}

]

},

"AppId": {

"count": 1,

"records": [

{

"appid": 7, "appname": "HTTP", "count": 1,

"packets": 67,

"octets": 55109

}

]

}

}

cURL code sample: Connection summary

The code sample was run with cURL 7.57.0.

curl -k --user cpx:hammerhead https://xxx.xxx.xxx.xxx/api/4.0/results/7b123/sessionsdl/connectionSummary.json

This cURL sample includes the following options:

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• --user cpx:hammerhead—Replace cpx with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/results/7b123/sessionsdl/connectionSummary.json—The results request URL. Replace xxx.xxx.xxx.xxx with the IP address of your Series appliance. Replace 7b123 with the search ID of interest.

Note

Enclose the URL in double quotation marks if it includes special characters such as [, ], {, }, ?, &, and *.

Results

This example returns connection summary for the specified completed search. The output is in JSON.

Download file request

To download a file found during session analysis, send the following request:

GET https://<PX_IP_address>/api/4.0/results/<search_id>/sessionsdl/files/file.<file_id>

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

• search_id—The unique search identifier.

• file_id—The number identifying a file found during session analysis.

Example

GET https://xxx.xxx.xxx.xxx/api/4.0/results/7b123/sessionsdl/file.1

Required header:

--user cpx:hammerhead

Download file response

HTTP/1.1 [Response Code] [Response Message] Date: [Date]

Content-Type: [Content Type] ""

Response fields

• Response Code—A standard HTML response code.

• Response Message—A standard HTML response message.

• Date—Standard HTML date format.

• Content Type—The response format.

Example

HTTP/1.1 200 OK

Date: Fri, 31 Mar 2017 16:02:41 GMT

Content-Type: application/zip; charset=utf-8

<<zip file contents>>

cURL code sample: Download file

The code sample was run with cURL 7.57.0.

curl -k --user cpx:hammerhead https:///xxx.xxx.xxx.xxx/api/4.0/results/7b123/sessionsdl/files/file.1

This cURL sample includes the following options:

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• --user cpx:hammerhead—Replace cpx with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• https://xxx.xxx.xxx.xxx/api/4.0/results/7b123/sessionsdl/files/file.1—The results request URL. Replace xxx.xxx.xxx.xxx with the IP address of your Series appliance. Replace 7b123 with the search ID of interest. Replace 1 with the file identifier of interest.

Note

Enclose the URL in double quotation marks if it includes special characters such as [, ], {, }, ?, &, and *.

Results

This example downloads the specified file in .zip format.

Packet list request

To get a packet list for a connection, send the following request:

GET https://<PX_IP_address>/api/4.0/results/<search_id>/<connection_index>

Required header:

--user <username>:<password>

Options

• PX_IP_address—IP address of the Series appliance running the Series API.

• username—The user name for your Series appliance.

• password—The password for your Series appliance.

• search_id—The unique search identifier.

• connection_index—The index number of the connection.

Query Parameters

• r_index—Zero-based index of first packet from search result.

• r_count—The number of packets to be returned; used in pagination.

Example

GET https://xxx.xxx.xxx.xxx/api/4.0/results/7b123/3?r_index=5&r_count=30

Required header:

--user cpx:hammerhead

Packet list response

index: [Index] stime: [Start Time] etime: [End Time]

saddr: [Source Address] sport: [Source Port]

daddr: [Destination Address] dport: [Destination Port] version: [Version]

proto: [Protocol] vlan: [VLAN] stream: [Stream] flags: [Flags]

pindex: [Packet Index]

Response fields

• Index—Zero-based index of first connection from search result.

• Start Time—Date and time from which the search started. The format is a floating-point epoch time stamp.

• End Time—Date and time at which the search ended. The format is a floating-point epoch time stamp.

• Source Address—Source IP address.

• Source Port—Source port.

• Destination Address—Destination IP address.

• Destination Port—Destination port.

• Version—Version.

• Protocol—The transport layer protocol of the connection.

• VLAN—Number of virtual LANs.

• Stream—nPulse stream number.

• Flags—Number of warnings.

• Packet Index—Zero-based index of first packet from search result.

Example

[

{

“index”: 0,

“stime”: “1374591610.000578540”,

“etime”: “1374591610.580978060”,

“saddr”: “xxx.xxx.xxx.xxx”, “sport”: 42342,

“daddr”: “xxx.xxx.xxx.xxx”, “dport”: 80,

“version”: 4,

“proto”: 6,

“vlan”: 0,

“stream”: 3,

“flags”: 17,

“pindex”: “104”,

}

{

“index”: 1,

“stime”: “1374591610.000580978”,

“etime”: “1374591610.580978060”,

“saddr”: “xxx.xxx.xxx.xxx”, “sport”: 80,

“daddr”: “xxx.xxx.xxx.xxx”, “dport”: 42342,

“version”: 4,

“proto”: 6,

“vlan”: 0,

“stream”: 3,

“flags”: 17,

“pindex”: “105”,

}

]

cURL code sample: Packet list

The code sample was run with cURL 7.57.0.

curl -k --user cpx:hammerhead "r_index=0&r_count=100" https://xxx.xxx.xxx.xxx/api/4.0/results/7b123/3

This cURL sample includes the following options:

• -k—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate.

• --user cpx:hammerhead—Replace cpx with the user name for your Series appliance. Replace hammerhead with the password for your Series appliance.

• "r_index=0&r_count=100"—This option specifies which packet to start with and how many packets are returned.

• https://xxx.xxx.xxx.xxx/api/4.0/results/7b123/3—The results request URL. Replace xxx.xxx.xxx.xxx with the IP address of your Series appliance. Replace 7b123 with the search ID of interest. Replace 3 with the connection record index

of interest.

Results

This example returns a packet list for a specified connection. The output is in JSON.

Single packet detail request

To get the XML/PDML/Wireshark information for an individual packet, send the following request:

GET https://<PX_IP_address>/api/4.0/results/<search_id>/<connection_index>/<packet_index>

Required header:

--user <username>:<password>

For more details on Wireshark XML, visit https://anonsvn.wireshark.org/wireshark/trunk/doc/README.xml-output

Options