Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Sample Response Fields

 

Output Field

Description

behavior_details

The analysis result of Juniper ATP Appliance’s behavioral analysis engine for an event.

has_ivp

Indicates whether the infection verification package (IVP) was available for the event.

cnc_array

Command and Control (CNC) activities involved in the event.

processes_spawned

Processes that were created during the event.

registry_changes

Modification(s) to system registry during the malware event

mutexes

Mutexes used during the event.

file_opened

Files opened during the malware event.

crsf_token

Token ID for this request.

Tip

To obtain Behavior information via API, [1] query analysis_details for the event with get_components= 1 set; this returns the array of all child elements of the zip that includes the sha1sum for the child element(s). Next, query behavior_details using the sha1sum.

Example:

Then, querying bahavior_details, something like the following is returned:

Tip

Sample APIs for obtaining behavioral details from a Zip file.

  1. Get components of the Zip file:

    Example

    URL:https://host1.JATP.net/cyadmin/api.php?op=analysis_details

    Data:

    sha1sum:5ac9a76d3057cd40f33bf8698028ed9928badb04 (sha1sum of the Zip file)

    get_components:1

    Response:

  2. Get behavioral details:

    URL:https://test.juniper.net/cyadmin/api.php?op=behavior_details

    Data:

    sha1sum:1bca4f69ec98fb9b65f75d1ef8d611493a231e73 (sha1sum from the previous response)

    Response:

behavior_features

Use this API to retrieve the top five suspicious behaviors and anomalies associated with a captured file, or a file submitted for analysis.

https://host/cyadmin/api.php?op=behavior_features

HTTP Post Parameters

Description

sha1sum

SHA1Sum of the object.

Example

An example of a sha1sum request:

An example of an md5sum request:

An example of an event_id request:

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample Response

This API’s response displays the top 5 suspicious behaviors of the object identified by its SHA1SUM. The response would be a behavior_features json dictionary that will have array of top features that caused the incident. It will be in the following format.

Example output follows:

bit9_config

This API configures Bit9 server integration with the Juniper ATP Appliance system for real-time threat mitigation and blocking.

https://HOST/cyadmin/api.php?op=bit9_config

HTTP Post Parameters

Description

bit9_enabled

Enables Bit9 integration

bit9_host_name

Host name of the Bit9 server

bit9_api_key

API key obtained from Bit9

csrf_token

unique ID for the configuration

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample Response

There is no response generated for the bit9_config API.

blocked_ips

This API retrieves a a list of List of IP addresses with corresponding malware details that can be blocked

The API for blocked IPS data retrieval is as follows (there are no required parameters):

https://HOST/cyadmin/api.php?op=blocked_ips

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample output

An object is returned for each incident involving a malicious source IP which includes the following fields:

HTTP Post Parameters

Description

malware_ip

IP address associated with the malware

incident_id

Incident ID assigned to this incident

endpoint_ip

IP Address of the targeted endpoint

malware_name

Name of the malware

last_seen

Date the malware was processed by the Collector

collector_id

ID of the Collector that processed the malicious traffic

bluecoat_config

Use this API to configure bluecoat integration for threat mitigation.

https://10.1.1.1/cyadmin/api.php?op=bluecoat_config

HTTP Post Parameters

Description

availability

Availability of a bluecoat server port

blocked_term

IP address of the blocked terminal

cache_age

Cache aging limit

allowed_ips

IP addresses specified as “allowed” during configuration

csrf_token

unique ID for the configuration

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample Response

There is no response generated for this API call.

change_password

Use this API to change the admin password for the Juniper ATP Appliance Central Manager Web UI.

https://10.1.1.1/cyadmin/api.php?op=change_password

HTTP Post Parameters

Description

old_password

The password to be changed.

new_password

The new password.

csrf_token

unique ID for the configuration

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample Response

There is no response generated for this API call.

collector_details

Use this API to retrieve details for a particular Web Collector.

https://10.1.1.1/cyadmin/api.php?op=collector_details

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample Response

An example response follows.

collector_performance

Use this API to retrieve the performance trend data for a specified collector.

https://10.1.1.1/cyadmin/api.php?op=collector_performance

HTTP Post Parameters

Description

interval_sec

The number of seconds in the time frame of interest, ending in “end_time_sec”

num_intervals

The number of intervals.

tz_offset_sec

The tz offset in seconds.

collector_id

The ID of the collector for which performance information is to be retrieved.

metric_name

Name of the metric

offered_traffic

Traffic processed for every 5min in kbps.

offered_traffic_rate

Total bandwidth of traffic being analyzed.

inspected_traffic_rate

The traffic objects inspected by the analysis and detection engines.

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample Response

A sample response follows:

collectors_summary

Use this API to retrieve summary information from all Web Collectors connected to the Core.

https://10.1.1.1/cyadmin/api.php?op=collectors_summary

HTTP Post Parameters

Description

collector_id

The ID of the collector for which details information is to be retrieved.

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample Response

An example response follows.

delete_whitelist_rules

Use this API to delete configured whitelist rules by name.

https://<Host>/cyadmin/api.php?op=delete_whitelist_rules

<Host> - the IP Address of the device

HTTP Post Parameters

Description

type

[optional] Specifies the type; possible value “incident”

name

Name of the rule to be deleted

An example follows.

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample Response

There is no response available for this API.

download_matched_yara

Use this API to download matched yara rule detections.

https://<Host>/cyadmin/api.php?op=download_matched_yara

<Host> - the IP Address of the device

HTTP Post Parameters

Description

type

[optional] Specifies the type; possible value “incident”

name

Name of the yara rule.

An example follows.

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

events

Use this API to retrieve the raw data accrued during the detection and analysis process.

The “events” API provides two API calls: one that provides an array of events, and another that presents the details of the event.

  • Get Events API: events

  • Get Events Details: event_details [For information about this API, go to event_details]

To recap: Juniper ATP Appliance defines “incidents” as a group of events that share the same enterprise endpoint. In other words, a Juniper ATP Appliance incident contains events that are likely part of the same attack. Currently, the grouping of events into an incident is primarily a measure of co-occurrence in time; the events occurred at or from the same endpoint within a 5-minute timespan. In recent releases, Juniper ATP Appliance separated correlation results into incident groups and now provides an "events" API that retrieves the raw data accrued during the detection and analysis process.

Events include:

  • a download

  • a CnC detection via signature

  • a phishing detection

  • a malicious email URL or attachment

  • exploits from chain heuristics

  • a user upload

Get Events

Use the following “events” API to get events. This API returns an event_array which contains the fields listed below.

https://<Host>/cyadmin/api.php?op=events

where <Host> is The IP address of the device

The inputs to the “events” API are as follows and except for the parameter “export_csv” are used to select which events to return:

HTTP Post Parameters for “events” API

Description

api_key

[Optional] The API authorization key.

custom_snort_event

[Optional] Provides data for custom SNORT events that have been recognized in this application.

end_time_sec

[Optional] The UTC timestamp of the end of the time frame of interest.

export_csv

[Optional] Displays the incident report in comma separated values (CSV) format: 0 indicates no CSV export; 1 indicates export CSV.

filetype_value

[Optional] The file type of interest: exe, pdf, dll

geo_value

[Optional] A two-letter country code representing the threat source.

interval_sec

[Required] The number of seconds in the time frame of interest, ending in “end_time_sec”

local_ip_value

[Optional] IP address of the threat target.

malwarename_value

[Optional] The name of the detected malware.

max_results

[Optional] The maximum number of results to return.

max_severity_value

[Required] Maximum risk of the events of interest, range 0-1; maximum severity; see explanation of min_severity_value for more details.

min_severity_value

[Optional] The minimum severity of the events of interest, which ranges from 0 to 1.0, where 0 indicates a benign event and 1.0 indicates the highest severity.

The query will return all events greater or equal to the given min_severity_value and strictly less than the max_severity_value except when the min_severity_value is 0 and/or the max_severity_value is 1, in which case all events with severity greater than zero and/or less than or equal to one will be returned.

To return all benign events set both the min_severity_value and max_severity_value to zero.

remote_ip_value

[Optional] The IP address of the threat source.

total_events

[Optional] The total number of events returned.

collector_id

[Optional] ID of the Collector that processed the malicious traffic.

third_party_info

[Optional] For every event in an event_array, a third_party_info attribute can be added. It has a unique structure shown below in this section when the event_type is set as third_party. If the event_type is not set as third_party, the value of this attribute will be null.

zone_uuid

The tenant zone_uuid in the incident_array elements

The “events” API will return zone_uuid in the event_array json response elements.

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample Response

Sample output for this API is provided further below. Output field definitions are provided here:

Output Field

Definition

analysis_done_time

Timestamp for the completion of event analysis.

app_protocol_array

HTTP or Email protocol instance, as in: "app_protocol_array": ["EMAIL"],

collector_id_array

Collector(s) that observed this event. A string enclosed in curly braces { }; as in: "collector_id_array": ["00000000-0000-0000-0000- 000000000001"],

collector_name

Name of the collector that observed the event.

destination_email_id

The destination email ID.

endpoint_hostname

The hostname of the endpoint.

endpoint_id

The ID associated with the endpoint.

endpoint_ip

The IP address of the endpoint.

endpoint_name

The DNS-resolved name of the endpoint.

endpoint_os_type

The target OS determined by observing the traffic on the appliance.

endpoint_username

The username for the endpoint device.

event_category

Malware category associated with this event, for example: Adware, Trojan_DDOS, Trojan_Backdoor, etc.

event_id

The ID of this event.

event_name

Name of the threat or malware.

event_severity

Ranges from 0 (clean) to 1.0 (critical).

event_type

Type of event: “exploit”, “http”, “email”, “cnc”, “submission” (for file submission), “fsp” (for lateral detection).

has_phishing

Indication of a phishing event: “1” = true, as in "has_phishing": "1",

incident_id

The ID of the incident for which this event is correlated.

incident_risk

Risk level of the incident containing this event.

initial_done_time

Timestamp for completion of the heuristics-level analysis of the event; for example: 2016-06-31 09:45:28.670764+00

last_activity_time

The timestamp at which this event was last observed.

last_activity_epoch

Duration values in seconds; for example: 1441014034.66748

normalized_name

Normalized malware name

search_data

Search criteria applied to analysis.

source_country_code

The country code using a geoIP lookup of the threat source IP.

source_country_name

The country name using a geoIP lookup of the threat source IP.

source_email_id

The threat source email ID.

source_hostname

The threat source device hostname.

source_id

The ID for the threat source device.

source_ip

Threat source IP address.

source_name

The DNS-resolved name of the threat source IP address.

source_username

The threat source device username.

threat_source

The threat source qualifier: "threat_source":"newcard.dyndns.biz"

threat_target

A string enclosed in curly braces { }, as in: "threat_target":"{switch-54.corp.biz.com.}",

Response to the “events” example call:

Example: Third Party Ingestion Vendor

Example: Direct Ingestion from a Third Party Vendor

When the device_host is the source of the event, raw event data is ingested into Juniper ATP Appliance.

Example

It is possible to get events for a given hostname or IP address by passing these values in the request paramenter, for example:

min_severity_value can be 0, 0.25, 0.5, 0.75 or 1.

get_all_events, when true, will get all the events from the time Juniper ATP Appliance is installed. It can be very slow depending on the size of data.

get_lateral_and_phishing_as_events can be true or false. If true, this will get the lateral events from the endpoint_hostname_value as events. If false, the lateral events are excluded in the response.

endpoint_hostname_value is the name of the host for which events are being fetched. It is case sensitive and should exactly match with the host_name of the real system.

Note

You can also pass the IP address of the endpoint local_ip_value or username_value instead of endpoint_hostname_value.

event_details

Use the following “event_details” API to retrieve event details.

A new event_details API key is provided in the response: custom_snort_event_details.

The event_details API takes only an event_id as a parameter.

Note

The "events" API returns a set of events matching the query parameters, whereas, currently, the "event_details" API returns the details of a specific event.

https://<HOST>/cyadmin/api.php?op=event_details

An event can be one of several different types:

Types of events

Description

cnc

The event is a signature match on network traffic

email

The event is an email attachment.

exploit

The event is an HTTP exploit sequence.

fsp

The event is a lateral spread.

http

The event is an http download

upload

The event is a manual file upload, i.e. an appliance user uploaded a file for analysis.

HTTP Post Parameters

Description

event_id

[Required] The ID set for the incident during malware analysis. Get this id from the output of the API:

https://<Host>/cyadmin/api.php?op=events

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample Response

Sample output for this API is provided further below. Output field definitions are provided here. The general details are shared by each event type per these fields:

Output Field

Definition

app_protocol_array

HTTP or Email protocol instance, as in: "app_protocol_array": ["EMAIL"],

analysis_done_time

Timestamp for analysis engine detonation completion.

cnc_details

Details of a detected CnC event.

collector_id_array

The collector ID(s) associated with observing this event. A string enclosed in curly braces { }; as in:

"collector_id_array": ["00000000-0000-0000-0000-000000000001"]

collector_name

Name of the collector that observed the event.

custom_snort_event_details

Details of the custom SNORT rule match.

destination_email_id

The destination email ID.

download_details

Details about a detected download.

endpoint_hostname

The hostname of the endpoint.

endpoint_id

The ID associated with the endpoint

endpoint_ip

The IP address of the endpoint.

endpoint_name

The host name of the endpoint, if available.

endpoint_os_type

The endpoint OS type, if available.

endpoint_username

The username for the endpoint device.

event_category

The event category, for example Adware, Exploit, Trojan_Generic, etc.

event_id

The ID of this event

event_name

The event name, such as: “WORM.GAMARUE.CY”

event_severity

The severity of the event: 0 is benign, 1 is critical, 0.75 is high, 0.5 is medium

event_type

Type of event: “exploit”, “http”, “email”, “cnc”, “submission” (for file submission).

exploit_details

Details of a detected exploit event.

file_md5_string

The MD5 checksum for the event, such as:

“340c860492c5ee5f708dfee57f650cd3"

file_sha1_string

The SHA1 for the event, such as:

"a0bd2ee698848dc40f41ce593c9668ccf7dd1993"c

file_sha256_string

The SHA256 associated with the event, such as:

"e482ea7bdbfd42dbf1c33cb0b4a57920f40e8ccba52a8ba57cf6191700fb 6751"

file_size

The file size in bytes, such as:

"55808"

file_type_string

The file type associated with the event, such as:

"PE32 executable (GUI) Intel 80386, for MS Windows, UPX compressed"

file_submission_details

The data associated with the file submission event, for example:

event_id: "604"

submission_time_string: "2016-06-01 08:12:17.618365+00"

local_path: "/var/spool/c-icap/download/CI_TMPosYyjt"

file_md5_string: "340c860492c5ee5f708dfee57f650cd3"

file_sha1_string: "a0bd2ee698848dc40f41ce593c9668ccf7dd1993"

file_sha256_string:

"e482ea7bdbfd42dbf1c33cb0b4a57920f40e8ccba52a8ba57cf6191700fb 6751"

file_size: "55808"

file_type_string: "PE32 executable (GUI) Intel 80386, for MS Windows, UPX compressed"

file_suffix: "exe"

mime_type_string: "FILE_UPLOAD"

has_components: null

packer_name: "UPX"

malware_name: "WORM_GAMARUE."

malware_severity: "0.75"

malware_category: "Trojan_Generic"

malware_classname: "malware"

has_static_detection: "1"

has_behavioral_detection: "0"

user_whitelisted: null

JATP_whitelisted: null

has_cnc: null

dig_cert_name: null

analysis_start_time: "2016-06-01 08:12:17.607846+00"

analysis_done_time: "2016-06-01 08:12:46.504487+00"

source_url_rank: "-1"

reputation_score: "44"

microsoft_name: "Worm:Win32/Gamarue.I"

has_behavior_log: "1"

file_meta:

file_suffix

The file suffix, such as: "exe"

has_download

Indication of a download event.

has_phishing

Indication of a phishing event: “1” = true, as in "has_phishing": "1"

http_details

Details of the HTTP detection

incident_id

The incident id of the related incident if the event was not benign

incident_risk

The risk of the related incident on the same scale as event_severity.

initial_done_time

Timestamp for completion of the heuristics-level analysis of the event; for example: 2016-06-31 09:45:28.670764+00

last_activity_time

The most recent time this event had any activity.

last_activity_epoch

The epoch ID for the event, such as: “1417421537.61837”

local_path

The path to the malware download.

mime_type_string

MIME type for the event, such as: "FILE_UPLOAD"

normalized_name

Normalized name that qualifies the event (for example: “Phishing”).

phishing_details

Details of a detected phishing event.

search_data

A display of the search data for the event, such as:

"a0bd2ee698848dc40f41ce593c9668ccf7dd1993 340c860492c5ee5f708dfee57f650cd3 Trojan_Generic e482ea7bdbfd42dbf1c33cb0b4a57920f40e8ccba52a8ba57cf6191700fb6 751 WORM_GAMARUE.CY" source_country_code The country code using a geoIP

source_country_code

The country code using a geoIP lookup of the threat source IP.

source_country_name

The country name using a geoIP lookup of the threat source IP.

source_email_id

The threat source email ID.

source_hostname

The threat source device hostname.

source_id

The ID for the threat source device.

source_ip

Threat source IP address.

source_name

The host name of the threat source IP address, if available.

source_username

The threat source device username.

submission_time_string

The date and time of the file upload for malware analysis.

threat_source

The threat source qualifier: "threat_source":"newcard.dyndns.biz"

threat_target

A string enclosed in square braces [ ], as in:

"threat_target":"[10.1.1.26"]

user_ack_status

Status of the current user (for example: “new”).

A Sample response for an HTTP download:

Note

The specific details for each event change for each event type and are contained in the sub-object download_details, cnc_details, exploit_details, etc. of the event_details object.

A Sample Response for Phishing:

A sample response for custom snort event details:

file_submit

Use this API function to submit a file to the Juniper ATP Appliance threat detection system for analysis.

The API format for file submission is as follows:

https://<HOST>/cyadmin/cgi-bin/file_submit

The file_submit API returns the event_id; use to event_details API to get the malware analysis results for the submitted file. “File Upload” (from the Central Manager Incidents page) is the Web UI equivalent of the file_submit API.

This API requires a form data “file” designation that specifies the file to be submitted. In addition, the user may submit an optional form data segment named “file_meta_json” as the meta to the submitted file. The JSON string “file_meta_json” as shown below:

HTTP Post Parameters

Description

file_meta_json

Name of the file to be submitted for analysis. The simple key value pair data when sent will show on the File Uploads tab in the Central Manager.

file

[Required] Path of the file to be submitted for analysis.

Following a successful file submission, an HTTP 200 response is returned. The content of the response is a JSON string containing the status code 0, the event id of the file submission, and the SHA1 sum of the submitted file. Various HTTP codes are returned for different error cases. The content of the response is a JSON string that includes the status code -1 and the reason for the failure with details.

Note

Be aware that in the example below that the “file” and “file_meta_json” fields are required form names (the file_meta_json field is required when you want to specify a name for the file when it appears in the analysis results), and the red highlighted text below in the Example ("file_name": "customer_file1")calls out the required key:value pair in the meta.

The designator "fada509542437360aeaa73a6256a9f1c88764e823f0f0a6a78fb66e419b5f389" is the name of the malware file used for testing.

The file_meta_json is recently enhanced; when all required endpoint metadata is available to process, the incident is shown in the Central Manager Incident tab.

Metadata JSON Structure

Note

File submissions that include an endpoint IP address or endpoint hostname can be correlated with other file submissions or malicious events that originated from the same endpoint IP address or endpoint hostname. These file submissions are displayed on the Central Manager Web UI Incidents tab. File submissions that do not include an endpoint IP address or endpoint hostname are displayed on the File Uploads tab.

Additionally, the file upload username is persistent and derived from the session data.

Example

  • Example 1: Uploading a file using CURL without end point and source metadata

  • Example 2: Uploading a file with source and destination endpoint data

Example 1 Uploading a file using CURL without end point and source metadata

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

The analysis result will is returned to the Central Manager Web UI File Upload tab because there is no source and end point data.

Sample Output

Example 2: Uploading a file with source and destination endpoint data

Note

Refer to Metadata JSON Structuresection for more information.

The formatted JSON for this example is shown below:

The file_capture_time is is epoch time. (Optional): Convert human readable time to epoch and vice versa at http://www.epochconverter.com/ If specified, this will be treated as the file capture time. The endpoint_os_type might be “windows” for windows hosts and “macos” for OSX; these are optional as well, as are endpoint_hostname and source_hostname are optional. Because endpoint data is present, the analysis result is provided in the Incident tab, not the File Upload tab. Depending on whether the file is benign or malware, the analysis will appear as Threat, Suspicious or Benign in the Incident table.

Example 3: Uploading a file with source and destination email IDs

There is no change in the response format for this file upload API example from previous releases. A successful fileupload returns the following JSON:

The non zero status indicates failure.

Retrieving the submitted file analysis results

Now use the event_details API to get the result of the submitted file.

Note that the returned JSON matches the existing events API except that only data specific to file upload is returned. The user who uploaded the file is also returned. Files are displayed that are still being analyzed because the API returns all the events without the status finalized.

Note

All file uploads performed by integrations such as Carbon Black/Bit9 are returned with available metadata in the Incident tab’s Incident table.

get_auto_mitigation_settings

This API retrieves configured auto-mitigation settings.

https://HOST/cyadmin/api.php?op=get_auto_mitigation_settings

Example

See Also:set_auto_mitigation_settings

get_blocked_emails_ex

Use this API to retrieve all blocked emails.

The API for retrieving all blocked emails is shown as follows:

https://HOST/cyadmin/api.php?op=get_blocked_emails_ex

Example

get_blocked_ips_ex

Use this API to retrieve all the mitigation rules and their status for firewalls. This API replaces “get_blocked_ips” in the previous release.

The API for retrieving blocked IPS rules and status is shown as follows:

https://HOST/cyadmin/api.php?op=get_blocked_ips_ex

Example

The returned JSON is an array in the following format:

HTTP Post Parameters

Description

threat_actor

An attacker’s IP address.

confidence

The mitigation rule confidence determination. The values range from 0 to 1. Automatic mitigation is based on the confidence score, and can be set from the Central Manager Config > System Settings page under “Auto Mitigation Settings.”

threat_source

Source information created as a result of an incident, or created by Juniper ATP Appliance ATA.

event_array

A set of individual events derived from incidents, including their details as a JSON dictionary.

The following attributes report the action taken by Juniper ATP Appliance for mitigation. These actions are used by the Juniper ATP Appliance Central Manager to provide status:

Mitigation Attributes

Description

push_to_device

Shows whether the rule is required to be pushed to the configured firewall device.

who

Shows who created the rule; USER is displayed if the incident created the attribute; Juniper ATP is displayed if the incident is created by the Juniper ATP Appliance as part of ATA.

limit

A 'limit' is shown as 't' if and only if the threat has been "limited", for example, the threat should be pushed based on the threat's confidence, but the number of threats to be pushed exceeds the configured threat capacity of the device, and so this threat has been held back ("limited"). A “limit” is shown as 'f' if it has not been limited. The limits for the number of auto mitigation rules configured is defined in Config > System Settings under Auto Mitigation Settings.

Sample Output

get_blocked_signatures

Use this API to obtain a list of blocked signatures.

The API for getting blocked signatures is as follows (there are no required parameters):

https://HOST/cyadmin/api.php?op=get_blocked_signatures

Example

Sample Output

get_blocked_urls_ex

Use this API to obtain a list of the mitigation rules applicable to web gateways; this replaces the “get_blocked_url” available from a previous release.

The API for getting blocked gateway rules data is as follows:

https://HOST/cyadmin/api.php?op=get_blocked_urls_ex

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

HTTP Post Parameters

Description

threat_actor

The returned value “threat_actor” is a regular expression of URL, URI or the URL itself.

limit

A "limit" is returned as “t" for true or f" for false; “f” indicates also that the limit it is less than “Max URL Threats” configured at the Central Manager Config>System Settings page.

Sample Output

get_iocs

Use this API to retrieve Indicators of Compromise (IoCs) in STIX format.

Structured Threat Information Expression (STIX™) is a language used to qualify cyber threat data and intel so it can be exchanged, stored, and analyzed. The “get_iocs” API allows users to query Juniper ATP Appliance to obtain Indicators of Compromise (IoC) in a standard STIX format.

The API for returning IoCs is as follows:

https://HOST/cyadmin/api.php?op=get_iocs

Example

HTTP Post Parameters

Description

max_results

The maximum number of indicators that the API will return. A default number of 500 maximum is applied if “max_results” is unspecified.

end_time_sec

The end of the time range for which the indicators are selected. The current time is used if “end_time_sec” is unspecified.

interval_sec

The length of the time range for which the indicators are selected. A default of 24 hours is applied if “interval_sec” is unspecified.

begin_time_sec

The beginning of the time range for which the indicators are selected. The argument “end_time_sec” and “interval_sec” are used if ”begin_time_sec” is unspecified. Note that “begin_time_sec” overrides “interval_sec” if both arguments are present in the request.

event_id

The event ID relative to all returned indicators of compromise. All other arguments are ignored if “event_id” is provided in the API request.

Note: Querying large datasets can require a long response time; see the Tip provided on the following page for optional query management strategies.

IoC Filtering

Filtering IoCs with the “get_iocs” API can be implemented in either of two ways:

  1. Time based Filtering

    As indicated in the HTTP POST Parameters table above, time-based filtering can be implemented by pairing the arguments “beginning_time_sec” and “end_time_sec,” or by pairing “end_time_sec” and “interval_sec,” in order to specify the time range of IoCs you would like to receive.

  2. Event ID based Filtering

    Another filtering option is event_id filtering; specify the “event_id” argument in the request and the response will only contain IoCs that are related to that particular event, regardless of the time that the event took place.

Note

The get_iocs API generates a response based on events with a severity of > 0 and are not whitelisted.

Query the API by specifying the time range and the maximum number of indicators to be fetched. The time range can be of arbitrary size. You can choose to fetch on any intervals as long as the joint of all intervals covers the entire timeline. Any overlap in the results of different queries can be identified by the event ID embedded in the indicators.

Tip

The STIX API query might take a long time to generate the response result against very large database. The default “max_results” parameter is 500 indicators and the default time range is 24 hours. But you can increase and decrease those arguments as necessary. It is a good practice to specify your time range at a relatively small interval so that the total number of returned indicators is small. Then repeat the request with a sliding window to eventually retrieve all indicators.

It is possible to request a maximum number of indicators that is smaller than the actual number of indicators within a specified time range. An error message will be returned displaying the actual number of indicators so that the set can be adjusted accordingly. The API will not select the requested number of indicators.

Note

Indicators may get updated when an event is updated due to rescan. Within the results of multiple queries, indicators with recent timestamp are preferred unless a complete history is required. The event ID in the indicator can be used to replace an outdated result on the client side.

Sample Responses

Sample responses for the “get_iocs” API are provided below for the following categories:

Note

For more information about STIX indicators, refer to Sample STIX Data

Sample Response for get_iocs

HTTP without IVP

Sample Response for get_iocs

Sample Response for get_iocs

HTTP with IVP

Sample Response for get_iocs

Submission with IVP

Sample Response for get_iocs

Submission Zip

Sample Response for get_iocs

Email without IVP

Sample Response for get_iocs

Email with IVP

Sample Response for get_iocs

CnC

Sample Response for get_iocs

Exploit

Sample STIX Data

STIX validator is used as the minimal validation

Sample STIX Data are provided in this section for:

  • HTTP Event

  • Submission Event

  • Email Event

  • CnC Event

  • Exploit Event

  • IVP

Sample STIX Data for an HTTP Event

Sample STIX Data for an Email Event

get_ivp

Use this API to generate and download an IVP for a given event_id, MD5sum or SHA1SUM.

The API for getting blocked URLs is as follows (there are no required parameters):

https://HOST/cyadmin/api.php?op=get_ivp

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

HTTP Post Parameters

Description

event_id | md5sum | sha1sum

[Required] Provide one of these event identifiers.

Sample Output

A file containing the IVP.

get_reports

Use this API to retrieve configuration information

Reports include: siem, email-coll, network-value, auto-mitigation, dlp-configuration, av-configuration, golden image results, configured zones and all configured mitigation devices.

The API for report retrieval is as follows (there are no required parameters):

https://HOST/cyadmin/api.php?op=get_reports

An example of the API for retrieving configured tenant zones is as follows:

The API for retrieving information about a specific tenant zone is as follows:

The API for retrieving all mitigation devices, “op=get_reports&report_group=auto-mitigation”, is shown as follows:

https://HOST/cyadmin/api.php?op=get_reports&report_group=automitigation

The returned value is same as that displayed in Config > Environmental Settings > Firewall Mitigation Settings at the Central Manager.

The API response contains a “report_table” field which is a JSON object/map keyed on report id. Each value is a report object that constrains the following common fields as well as fields specific to each report group:

Report Field

Description

report_group

Retrieve configuration for “report”, “siem”, “avconfiguration”, “email-coll”, “network-value”, “automitigation”, “dlp-configuration”, “custom-image”,

report_id

The ID of the report to display.

time_created

Time of report file creation.

time_modified

Time report was last modified

user_id

User who created the report

zones-configuration

currently configured zones

Example

[Displays HTML for the corresponding report.]

[Displays all mitigation devices in the corresponding report. The returned json report_table dictionary contains elements for each configured device. The ID is provided in UUID format, such as 4F12B367-5983-4D6E-8719-B9C84A01F043 in the report_id. This can be used in other APIs such as “test connection.” You can ignore other attributes returned as they are used mainly by the JATPJATP Web UI. Note that the attribute host_name is the name or IP address of the mitigation device, and mitigate_type is the device type.]

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample Output

To get custom Golden Image results information:

To get mitigation device data:

get_unchecked_exposures

This API retrieves a list of infections that have not yet been verified.

The API for unverified infection retrieval is as follows:

https://HOST/cyadmin/api.php?op=get_unchecked_exposures

No parameters are required.

Ecxample

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample Output

get_users

This API retrieves current user profiles.

The API for user profile retrieval is as follows (there are no required parameters):

https://HOST/cyadmin/api.php?op=get_users

The response includes:

user_id

user_name

user_fullname

api_key

api_key_is_disabled [status]

role_array

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample Output

get_whitelist_rules

Use this API to retrieve all configured whitelist rules.

https://<Host>/cyadmin/api.php?op=get_whitelist_rules

<Host> - the IP Address of the device

HTTP Post Parameters

Description

type

[optional] Specifies the type; possible value “incident”

An example follows.

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample Response

get_zones

Use this API to retrieve all MSSP tenant-specific “zones” information.

https://<Host>/cyadmin/api.php?op=get_zones

<Host> - the IP Address of the device

HTTP Post Parameters

Description

type

[optional] Specifies the type; possible value “incident”

An example follows.

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample Response

history_details

Retrieve detection history for a given SHA1 SUM hash.

See also; incident_details; incidents; add _incident_comments

https://<Host>/cyadmin/api.php?op=history_details

<Host> - the IP Address of the device

HTTP Post Parameters

Description

sha1sum

SHA1 SUM hash

An example follows.

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample Response

incident_comments

Retrieve incident comments associated with an incident.

See also; incident_details; incidents; add _incident_comments

https://<Host>/cyadmin/api.php?op=incident_comments

<Host> - the IP Address of the device

HTTP Post Parameters

Description

incident_id

ID of the incident for which comments are to be retrieved.

An example follows.

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample Response

incidents

Retrieving incidents from a Juniper ATP Appliance.Use this API to retrieve incidents from the Central Manager.

incident_comments; add _incident_comments

<Host> - the IP Address of the device

The current release includes the following changes:

– App_protocol_array uses “LOG” as the protocol in addition to other protocols in the incident. And collector_id_array will have UUID of the third party ingestion collector, as in:

“collector_id_array”: ["LOG","HTTP"]

HTTP Post Parameters

Description

collector_id

[optional] ID of the Collector that processed the malicious traffic; can include LOG or Protocol

endpoint_id

Identification of the endpoint(s) in an array contained in square brackets [ ].

end_time_sec

[optional] The UTC timestamp of the end of the time frame of interest.

export_csv

[optional] Displays the incident report in comma separated values (CSV) format: 0 indicates no CSV export; 1 indicates export CSV.

filetype_value

[optional] The file type of interest: exe, pdf, dll

geo_value

[optional] A two-letter country code representing the threat source.

interval_sec

[required] The number of seconds in the time frame of interest, ending in “end_time_sec”

local_ip_value

[optional] IP address of the threat target.

malwarename_value

[optional] The name of the detected malware

max_results

[optional] The maximum number of results to return.

max_risk_value

[required] maximum risk of the events of interest, range 0-1; see explanation of min_risk_value for details.

min_risk_value

[optional] The minimum risk of the events of interest, which ranges from 0 to 1, where 0 indicates a benign event and 1 indicates the highest risk.

The query will return all events greater or equal to the given min_risk_value and strictly less than the max_risk_value except when the min_risk_value is 0 and/or the max_risk_value is 1, in which case all events with risk greater than zero and/or less than or equal to one will be returned.

To return all benign events set both the min_risk_value and max_risk_value to zero.

remote_ip_value

[optional] The IP address of the threat source.

threat_target

Identification of the targeted endpoint(s) in an array displayed in square brackets [ ].

zone_uuid

The tenant zone_uuid in the incident_array elements

Note

If an exploit is present, the incident_details>exploit_array object displays a new attribute called dst_ip.

Examples follow.

Example 1

The response of op=incidents will have the tenant zone_uuid in the incident_array elements.

Zone_uuid can be passed to op=incidents API to fetch incidents from a particular zone. If zone_uuid is not passed, incidents from all zones are retrieved. If a zone is not configured, the default zone UUID of ‘00000000-0000- 0000-0000-000000000000’ is returned.

Example 2

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample Response

A Sample Response Showing Endpoint Identity

A Sample Response for an HTTP Download

A Sample Response for a Phishing Email:

A Sample Response for a Lateral Detection

incident_details

Retrieving details of an Incident in Juniper ATP Appliance.

Use this API function to retrieve incident details from the Juniper ATP Appliance threat detection system, including OS changes such as mutexes, process starts or registry changes associated with a file object.

The API for incident detail retrieval is as follows:

https://<HOST>/cyadmin/api.php?op=incident_details

<HOST> - The IP address of the Juniper ATP Appliance.

HTTP Post Parameters

Description

incident_id

[required] The ID set for the incident during malware analysis; get this ID in the output of API https:// <Host>/cyadmin/api.php?op=incidents</Host>

zone_uuid

The tenant zone_uuid in the incident_array elements

The response of op=incident_details will have the tenant zone_uuid in the incident_array elements.

Zone_uuid can be passed to the op=incident_details API to fetch incident details from a particular zone. If zone_uuid is not passed, incidents from all zones are retrieved. If a zone is not configured, the default zone UUID of ‘00000000-0000-0000-0000-000000000000’ is returned.

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

A new field third_party_event_array lists all third party events correlated as part of the incident

Example

Optional Curl Command Options

Or

Or

In the above examples, the first curl command sends the incident_uuid as post param and in the next two examples it is sent as a get parameter. You can pass incident_id or incident_uuid. Incident_uuid is suggested.

Sample Outputs

Several samples are provided below:

Sample Response for a Phishing Event

Sample output for an incident with Phishing detection:

Apart from the above new keys, phishing_array has been introduced in this API

Sample Response for an SMB Lateral Detection

Sample output for an incident with SMB lateral detection:

Sample Incident Details for an Exploit

Sample output for an incident with exploit:

Sample Incident Details with YARA Rule Matching

Sample response for an incident with YARA rule matching (“yara_rule_array” has been added to the download_array). In this example, "has_yara_match": "1" and "yara_rule_array" are the sample values:

ingestion_vendor_details

Use this API function to obtain log ingestion and event details per integrated vendor. This API returns all the ingestion vendors and various fields of ingested data supported by Juniper ATP Appliance. A typical response is provided below. Some of the fields are used by Juniper ATP Appliance for acquiring events information.

https://<HOST>/cyadmin/api.php?op=ingestion_vendor_details

<HOST> - The IP address of the Juniper ATP Appliance.

See Also: op=get_incident | op=incident_details | op=behavior_details

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample Output

Creating or Updating an External Event Collector Source

Use the following settings:

report_group=third-party-source

This setting holds the configured third party event sources listed under External Event Collectors in the Juniper ATP Appliance. Central Manager Web UI Config > Environmental Settings page.

Get vendor_category, vendor_name values from the op=ingestion_vendor_details API for the source you are configuring.

Parameters differ slightly based on the whether ingestion will be coming from Splunk or via Direct Log collection. Be sure to supply the following sample parameters in POST or GET:

Example for Splunk Ingestion

Example for Direct Log Ingestion

Response will be {"status":0} for success.

Where:

report_id (which is a UUID). A random UUID can be generated and used with this API.

vendor_category, vendor_name are the values from op=ingestion_vendor_details for the source being configured.

Other values map to the equivalent values shown in the Juniper ATP Appliance Web UI.

Getting All Configured External Event Collector Event Sources

The third party external event sources are stored in the reports framework. Pass op=get_reports&report_group;=third-party-sources to obtain all configured third party sources.

Example

Output will display in the following format:

license_details

Use this API function to obtain current license status and details for Juniper ATP Appliance support, content and product licenses.

The API for a license details request is as follows:

https://<HOST>/cyadmin/api.php?op=license_details

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample JSON Request

login

Use the login API function to set the SESSID cookie when login is successful. This API also returns basic user and configuration information

HTTP Post Parameters

Description

init

When non-zero, this augments the result with constants and configuration tables that are useful in displaying values returned by other API requests

password

cleartext password of login request

user_name

User name of login request

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample Response

logout

Use the login API function to log out and invalidate the session

Example

Sample Response

There is no response available for this API.

network_traffic

Use this API to display a per-object summary of network traffic object statistics and usage stats of the data displayed in the Central Manager Dashboard, including Core detection utilization information. This API provides various runtime metrics typically seen on the Central manager Dashboard for the last n units of time. The returned data contains information about inspected traffic, cluster utilization, analysis times and details about malwares detected recorded at various points in time. The duration is time is specified using the interval_sec and the num_intervals param.

The API for obtaining network traffic summaries from the Central Manager Web UI Dashboard is as follows:

https://<HOST>/cyadmin/api.php?op=network_traffic

HTTP Post Parameters

Description

interval_sec

Time interval in seconds. Network traffic during this time will be returned.

num_intervals

The number of intervals.

tz_offset_sec

The tz offset in seconds.

collector_id

(Optional) UUID of the Collector

Note

If an incorrect collector_id is given, the offered_traffic and inspected_traffic values are displayed as zero (0). If no collector_id parameter is passed, then the values shown for offered_traffic and inspected_traffic is representative of aggregate traffic.

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample output

The response includes a count_array attribute which is an array of various metrics (not all of which we display on the dashbord). Each element in the array indicates the value of various metrics for the specified timestamp.

Consequently, to graph them, attributes are aggregated ( certain attributes are averaged while others are summed up) for display.The response output fields include:

Response Field

Description

timestamp

Timestamp for the traffic collection

num_clean

Number of clean objects.

num_low

Number of low risk objects

num_med

Number of medium risk objects

num_high

Number of high risk traffic objects

total_objects

Total number of objects in network traffic

offered_traffic

Traffic processed for every 5min in kbps

offered_traffic_rate

Total bandwidth of traffic being analyzed.

inspected_traffic

Bandwidth used for scanning and inspecting traffic in Bytes per Second (Bps)

num_malware

Number of malicious objects detected

winxp_util_factor_short

Utilization data for Windows Cores

osx_util_factor_short

Utilization data for OSX Secondary Cores

winxp_duration

Analysis delay for winxp OS

osx_duration

Analysis delay for OSX

The following is an example response:

set_auto_mitigation_settings

This API configures auto-mitigation.

https://HOST/cyadmin/api.php?op=set_auto_mitigation_settings

Example

HTTP Post Parameters

Description

web_auto_mitigation_enabled

true | false

email_auto_mitigation_enabled

true | false

aggressiveness

moderate | always

max_url_threats

Number of threats to return

Note

The parameters web_auto_mitigation_enabled and email_auto_mitigation_enabled can be false if they are not required to be enabled.

Aggressiveness can be moderate or always. If it is always, all the threats are auto mitigated. For moderate only, only Max and High Threat confidence level threats are automatically mitigated.

See Also:get_auto_mitigation_settings

set_whitelist_rules

This API adds a new whitelist rule or updates an existing rule. Rename a rule by specifying the old_name parameter. A rule can have one or more attributes.

https://HOST/cyadmin/api.php?op=set_whitelist_rule

HTTP Post Parameters

Description

type

Specifies type; possible value “incident”

name

New name for the rule; used while changing the name of a rule.

old_name

Old name of the rule; set when re-naming a whitelist rule.

src_ip

Source IP

dst_ip

Destination IP

domain

Domain name

host:

Host name

uri

URI

sha1sum

SHA1 Sum

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample Response

No response is available for this API.

test_configuration

Use this API to test the Juniper ATP Appliance configuration.

https://HOST/cyadmin/api.php?op=test_configuration

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Parameters

HTTP Post Parameters

Description

interval_sec

[Required] The number of seconds in the time frame of interest, ending in “end_time_sec”

min_severity_value

[Required] The minimum severity value of the incident.

max_severity_value

[Required] The maximum severity value of the incident.

Sample Response

{

top_incidents

Use this API to retrieve the latest incidents.

Identification of the endpoint is provided in this API response, when available.

https://HOST/cyadmin/api.php?op=top_incidents

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Parameters

HTTP Post Parameters

Description

interval_sec

[Required] The number of seconds in the time frame of interest, ending in “end_time_sec”

min_severity_value

[Required] The minimum severity value of the incident.

max_severity_value

[Required] The maximum severity value of the incident.

Sample Response

trace_log

Use this API to retrieve the trace log for an event.

https://HOST/cyadmin/api.php?op=trace_log

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample Response

Response includes the trace log for the specified event.

trace_pcap

Use this API to retrieve the trace log for an event.

https://HOST/cyadmin/api.php?op=trace_pcap

Example

“https://HOST/cyadmin/api.php?op=trace_pcap” -d “event_id=624”

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample Response

Response includes display of the pcap for the specified event.

update_report

Use this API to update report settings and include zone configuration.

https://HOST/cyadmin/api.php?op=update_report

Parameters

HTTP Post Parameters

Description

report_group

zones-configuration

report_id

A UUID;a random UUID can be generated and used with this API.

zone_description

Description of the zone.

zone_name

Name of the zone.

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

verify

Use this API to verify and update the session cookie.

https://HOST/cyadmin/api.php?op=verify

This is a verification and update function that is successful if the session cookie is valid. On success, it returns the same result as a successful login with the parameter “init” set to non-zero.

Example

Authorization - The device user API key.

Obtain from Config > System Profiles > Users > Click on any User to obtain an API Key.

Sample Response