Lastline Network API¶

The Lastline network API is accessible at:

https://user.lastline.com/papi/net/<function>

On-premise customers should instead access this API on their Lastline Enterprise Manager at:

https://user.<MANAGER HOST NAME>/papi/net/<function>

The purpose of this API is to provide access to information collected by Lastline appliances on a protected network.

Network events¶

Method Index¶

get_event():

Get information about a network event
get_events():

Get information about network events
get_events_legacy():

DEPRECATED: Get information about network events
get_event_urls():

Get URLs associated with a network event
get_event_evidence():

Get evidence about a network event
get_event_attributes():

Get additional attributes of a network event
get_event_blacklist_match_info():

Get information about what exactly was matched on a blacklist hit to trigger an event
get_event_network_iocs():

Get network IoC tags associated with an event
get_similar_event_filters():

Get a set of filters to find events similar to a provided one

Method Documentation¶

net.network_event.get_event(response_format)¶

Get information about a specific network event

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >=7.2.

URL

/papi/net/event/get[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

timezone:

Name of selected time zone

event_id:

Identifier of the event

start_time:

Get event that happened after this date (provide for optimization purposes)

end_time:

Get event that happened before this date (provide for optimization purposes)

Contents of succesful response

A dictionary with the following keys:

event_id:

Identifier of the event

access_key_id:

Identifier of license of sensor related to the event

subkey_id:

Identifier of subkey of sensor related to the event

time:

Unix timestamp of the incident (seconds since ‘1970-01-01 00:00:00’)

start_time:

Start time of the event

end_time:

End time of the event

transport:

Transport protocol, “TCP” or “UDP”

occurrences:

Number of occurrences aggregated into this event

blocked:

Whether or not the corresponding operation is ‘BLOCK’

relevant_host_ip:

IP address of the relevant host

other_host_ip:

IP address of the other host

server_port:

The port of the server

relevant_host_hostname:

Hostname of the relevant host

other_host_hostname:

Hostname of the other host

src_host:

IP address of the source of the event (in dotted format) DEPRECATED: see relevant_host and other_host

dst_host:

IP address of the destination of the event (in dotted format) DEPRECATED: see relevant_host and other_host

dst_port:

Destination port DEPRECATED: see server_port

src_hostname:

Hostname of the source DEPRECATED: see relevant_host_hostname and other_host_hostname

src_id:

ID of the relevant host

host_label:

Label of the relevant host

host_whitelisted:

True if the host the event happened on is whitelisted

src_mac:

Mac address of the source of the incident

entry:

Blacklist entry hit, or destination host for non-blacklist events DEPRECATED: see relevant_host_hostanme and other_host_hostname

event_type_id:

Identifier of the event type

event_type:

Type of the event (‘IP’, ‘NETWORK’, ‘DNS’, ‘DYNAMIC_IP’, ‘IDS’, ‘BINARYDOWNLOAD’, ‘NETFLOW’)

hostname:

Contacted hostname, if available DEPRECATED: see relevant_host_hostanme and other_host_hostname

threat:

Detected threat. Called “Malware” in Lastline Portal.

threat_class:

Class of detected threat. Called “Malware Class” in Lastline Portal.

impact:

Impact of the event

client_ip:

IP address of the client

client_hostname:

Hostname of the client, if available

server_ip:

IP address of the server

server_hostname:

Hostname of the server, if available

user_defined:

Whether the threat class comes from a custom intelligence blacklist

comment:

Comment on the malware, or malware class, related to this incident

mitigation:

Description of the possible mitigation steps to be taken to deal with the type of malware, or malware class, related to this incident

incident_id:

Identifier of the related incident

anomaly_detector_info:

Info on detector (e.g., signature text, CVE reference, etc)

llanta_rule_uuid:

Unique identifier of the custom Breach Defender rule that was matched and triggered the event (optional: this field will not be present if the event wasn’t triggered by a match on a Breach Defender rule)

llanta_rule_revision:

Identifier of the Breach Defender rule revision (optional: this field will not be present if the event wasn’t triggered by a match on a Breach Defender rule)

description:

List containing a human-readable description of the event. Each element is a string which is a paragraph of the description.

verification_outcome:

The result of verification. Could be one of: “BLOCKED”, “SUCCESSFUL”, “FAILED” (Optional)

verifier_name:

The name of the verifier. (Optional)

verifier_message:

Message explaining the verification outcome. (Optional)

net.network_event.get_events(response_format)¶

Get information about network events on a protected network

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >=7.2.

URL

/papi/net/event/list[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_time:

Get events that happened after this date (required)

end_time:

Get events that happened before this date (required)

timezone:

Name of selected time zone

Network selection:

key:

access_key[:subkey]: Restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

Sorting and pagination:

orderby:

Sort results based on this parameter. Can be one of:

event_start_time [ASC|DESC] to sort by start time of the event event_end_time [ASC|DESC] to sort by end time of the event impact [ASC|DESC] to sort by impact of the event

max_results:

Limit to this many results

offset_results:

Skip the first offset_results results.

Filters:

event_id:

Return informations about the incident with this identifier

incident_id:

Restrict to events related to incidents with these ids

priority:

Restrict to events with this level of impact (‘HIGH’, ‘MEDIUM’ or ‘LOW’)

threat_class:

Restrict to this threat classes

threat:

Restrict to threats with these names

src_id:

Restrict to events on the host with this IDs

relevant_host_ip:

Restrict to these hosts in the monitored network, selected by IP address, CIDR block, IP range, or comma-separated list of IPs, CIDR blocks, and IP ranges. Example: “1.2.3.4,192.168.10.0/24,10.0.0.5-10.0.0.55”

other_host_ip:

Restrict events based on other IP address, selected by IP address, CIDR block, IP range, or comma-separated list of IPs, CIDR blocks, and IP ranges. Example: “1.2.3.4,192.168.10.0/24,10.0.0.5-10.0.0.55”

relevant_host_hostname:

Restrict to these hosts in the monitored network, selected by host name or label, comma-separated

other_host:

Restrict events based on other host, selected by host name or IP, comma-separated

host_tag:

Restrict to events on hosts labelled with these host tags, comma-separated

src_ip:

Restrict to these hosts in the monitored network, selected by IP address, CIDR block, IP range, or comma-separated list of IPs, CIDR blocks, and IP ranges. Example: “1.2.3.4,192.168.10.0/24,10.0.0.5-10.0.0.55” DEPRECATED: see relevant_host_ip

dest_ip:

Restrict events based on destiantion IP address, selected by IP address, CIDR block, IP range, or comma-separated list of IPs, CIDR blocks, and IP ranges. Example: “1.2.3.4,192.168.10.0/24,10.0.0.5-10.0.0.55” DEPRECATED: see other_host_ip

src_hostname:

Restrict to these hosts in the monitored network, selected by host name or label, comma-separated DEPRECATED: see relevant_host_hostname

entry:

Restrict to events that have a hit on these blacklist entries, or that have these destination ips for non-blacklist events DEPRECATED: see other_host

min_impact:

Restrict to events having impact greater or equal than this value

transport:

Restrict to this transport protocol, ‘TCP’ or ‘UDP’

port:

Restrict to these TCP/UDP destination port numbers

whitelisting:

Boolean parameter set to True to exclude malwares from whitelisted sources

homenet

3-value Boolean. If set to True only include events from sources inside the homenet, set to False to exclude events from sources inside the homenet, if not set return everything.

event_outcome

If set to “DETECTION”, filter on actual detections (events corresponding to “LOG” or “BLOCK” operations). If set to “INFO”, filter on network events that don’t correspond to detections but simply supply additional information. If set to “ALL” no restriction are applied. If not set, defaults to “DETECTION”. (available for Lastline Enterprise On-Premise versions >= 7.8)

Contents of succesful response

A list of dictionaries with the following keys:

event_id:

Identifier of the event

access_key_id:

Identifier of license of sensor related to the event

subkey_id:

Identifier of subkey of sensor related to the event

time:

Unix timestamp of the incident (seconds since ‘1970-01-01 00:00:00’)

start_time:

Start time of the event

end_time:

End time of the event

transport:

Transport protocol, “TCP” or “UDP”

occurrences:

Number of occurrences aggregated into this event

blocked:

Whether or not the corresponding operation is ‘BLOCK’

relevant_host_ip:

IP address of the relevant host

other_host_ip:

IP address of the other host

server_port:

The port of the server

relevant_host_hostname:

Hostname of the relevant host

other_host_hostname:

Hostname of the other host

src_host:

IP address of the source of the event (in dotted format) DEPRECATED: see relevant_host and other_host

dst_host:

IP address of the destination of the event (in dotted format) DEPRECATED: see relevant_host and other_host

dst_port:

Destination port DEPRECATED: see server_port

src_hostname:

Hostname of the source DEPRECATED: see relevant_host_hostname and other_host_hostname

src_id:

ID of the relevant host

host_label:

Label of the relevant host

host_whitelisted:

True if the host the event happened on is whitelisted

src_mac:

Mac address of the source of the incident

entry:

Blacklist entry hit, or destination host for non-blacklist events DEPRECATED: see relevant_host_hostanme and other_host_hostname

event_type_id:

Identifier of the event type

event_type:

Type of the event (‘IP’, ‘NETWORK’, ‘DNS’, ‘DYNAMIC_IP’, ‘IDS’, ‘BINARYDOWNLOAD’, ‘NETFLOW’)

hostname:

Contacted hostname, if available DEPRECATED: see relevant_host_hostanme and other_host_hostname

threat:

Detected threat. Called “Malware” in Lastline Portal.

threat_class:

Class of detected threat. Called “Malware Class” in Lastline Portal.

impact:

Impact of the event

client_ip:

IP address of the client

client_hostname:

Hostname of the client, if available

server_ip:

IP address of the server

server_hostname:

Hostname of the server, if available

user_defined:

Whether the threat class comes from a custom intelligence blacklist

event_outcome:

‘INFO’ if this is a network event that doesn’t correspond to a detection but simply supplies additional information,’DETECTION’ if it’s an actual detection (available for Lastline Enterprise On-Premise versions >= 7.8)

description:

List containing a human-readable description of the event. Each element is a string which is a paragraph of the description. Note that, for performance reasons, this description may be less detailed than that returned by get_event.

verification_outcome:

The result of verification. Could be one of: “BLOCKED”, “SUCCESSFUL”, “FAILED” (Optional)

net.network_event.get_events_legacy(response_format)¶

Get information about network events in a protected network

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >=7.2.

DEPRECATED

This method is deprecated: use get_event() to query for a single network event, and get_events() to query for multiple network events.

URL

/papi/net/event/list_legacy[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_time:

Get events that happened after this date (required)

end_time:

Get events that happened before this date (required)

timezone:

Name of selected time zone

Network selection:

key:

access_key[:subkey]: Restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

Pagination:

max_results:

Limit to this many results

offset_results:

Skip the first offset_results results.

Filters:

event_id:

Identifier of the event. If provided only informations about this event will be returned along with additional informations

incident_id:

Restrict to events related to incidents with these ids

priority:

Restrict to events with this level of impact (‘HIGH’, ‘MEDIUM’ or ‘LOW’)

threat_class:

Restrict to this threat classes

threat:

Restrict to threats with these names

src_id:

Restrict to events on the host with this IDs

src_ip:

Restrict to these hosts in the monitored network, selected by IP address, CIDR block, IP range, or comma-separated list of IPs, CIDR blocks, and IP ranges. Example: “1.2.3.4,192.168.10.0/24,10.0.0.5-10.0.0.55”

dest_ip:

Restrict events based on destiantion IP address, selected by IP address, CIDR block, IP range, or comma-separated list of IPs, CIDR blocks, and IP ranges. Example: “1.2.3.4,192.168.10.0/24,10.0.0.5-10.0.0.55”

src_hostname:

Restrict to these hosts in the monitored network, selected by host name or label, comma-separated

entry:

Restrict to events that have a hit on these blacklist entries, or that have these destination ips for non-blacklist events

min_impact:

Restrict to events having impact greater or equal than this value

transport:

Restrict to this transport protocol, ‘TCP’ or ‘UDP’

port:

Restrict to these TCP/UDP destination port numbers

whitelisting:

Boolean parameter set to True to exclude malwares from whitelisted sources

homenet

3-value Boolean. If set to True only include events from sources inside the homenet, set to False to exclude events from sources inside the homenet, if not set return everything.

Contents of succesful response

A list of dictionaries with the following keys:

event_id:

Identifier of the event

access_key_id:

Identifier of license of sensor related to the event

subkey_id:

Identifier of subkey of sensor related to the event

time:

Unix timestamp of the incident (seconds since ‘1970-01-01 00:00:00’)

start_time:

Start time of the event

end_time:

End time of the event

transport:

Transport protocol, “TCP” or “UDP”

occurrences:

Number of occurrences aggregated into this event

blocked:

Whether or not the corresponding operation is ‘BLOCK’

src_host:

IP address of the source of the event (in dotted format)

dst_host:

IP address of the destination of the event (in dotted format)

dst_port:

Destination port

src_hostname:

Hostname of the source

src_id:

ID of the host the event happened on

host_label:

Label of the host the event happened on

host_whitelisted:

True if the host the event happened on is whitelisted

src_mac:

Mac address of the source of the incident

entry:

Blacklist entry hit, or destination host for non-blacklist events

event_type_id:

Identifier of the event type

event_type:

Type of the event (‘IP’, ‘NETWORK’, ‘DNS’, ‘DYNAMIC_IP’, ‘IDS’, ‘BINARYDOWNLOAD’, ‘NETFLOW’)

hostname:

Contacted hostname, if available

threat:

Detected threat. Called “Malware” in Lastline Portal.

threat_class:

Class of detected threat. Called “Malware Class” in Lastline Portal.

impact:

Impact of the event

user_defined:

Whether the threat class comes from a custom intelligence blacklist

If event_id was specified, the following fields will also be present:

comment:

Comment on the malware, or malware class, related to this incident

mitigation:

Description of the possible mitigation steps to be taken to deal with the type of malware, or malware class, related to this incident

incident_id:

Identifier of the related incident

anomaly_detector_info:

Info on detector (e.g., signature text, CVE reference, etc)

net.network_event.get_event_urls(response_format)¶

Get the URLs associated with this event.

URL

/papi/net/event/urls[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

event_id:

Identifier of event for which we want to return URLs (required)

event_time:

Approximate time of event (within +- a day) (required)

key:

access_key[:subkey]: Restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

customer:

Username of customer (this is an email address). Defaults to the customer for which the current account is authenticated.

limit:

Get at most this many URLs (default and maximum 1000)

Contents of successful response

List of URLs. Each is a mapping with the following fields:

url:

The URL as a utf-8 encoded unicode string. This is a best-effort attempt to display the URL as a browser would. For fidelity to the URL that was seen on the wire, refer to the raw_url field.

raw_url:

The raw URL, as seen on the wire. This is an ASCII string. URL standards, require URLs to be ASCII, with URL-encoding of non_ASCII chars. This is not always the case in practice. Therefore, we backslash-encode the raw url. This means that any non-ASCII characters, as well as the backslash character itself, will be backslash-encoded.

method: Protocol method, if any. For HTTP, this is the HTTP

method (GET, POST,..)

Error Codes

llapi.LLAPI_ERROR__NO_SUCH_ENTITY:

No such event exists

net.network_event.get_event_evidence(response_format)¶

Get the evidence associated with this event.

URL

/papi/net/event/evidence[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

event_id:

Identifier of event for which we want to return evidence (required)

event_time:

Approximate time of event (within +- a day) (required)

key:

access_key[:subkey]: Restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

customer:

Username of customer (this is an email address). Defaults to the customer for which the current account is authenticated.

Contents of successful response

List of Evidence. Each is a mapping with the following fields:

threat:

Detected threat. Called “Malware” in Lastline Portal.

threat_class:

Class of detected threat. Called “Malware Class” in Lastline Portal.

confidence:

Confidence in the evidence (0-100)

severity:

Severity of what the evidence has detected (0-100)

impact:

Overall impact of this evidence (0-100) This combines confidence and severity into an overall number. (available for Lastline Enterprise On-Premise versions >= 7.5)

evidence_type:

Type of evidence detected

detector:

Name of detector that detected this evidence

activity:

Name of detected activity

subject:

Subject of evidence. Semantics of this field can vary depending on evidence_type.

signature_id

Identifier of network signature that detected this evidence. This is currently for customer-provided signatures at the moment.

Error Codes

llapi.LLAPI_ERROR__NO_SUCH_ENTITY:

No such event exists

net.network_event.get_event_attributes(response_format)¶

Get the attributes associated with this event.

URL

/papi/net/event/attributes[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

event_id:

Identifier of event for which we want to return attributes (required)

event_time:

Approximate time of event (within +- a day) (required)

key:

access_key[:subkey]: Restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

customer:

Username of customer (this is an email address). Defaults to the customer for which the current account is authenticated.

Contents of successful response

List of Attributes. Each is a mapping with the following fields:

name:

Name of attribute

value:

Value of atttribute

Error Codes

llapi.LLAPI_ERROR__NO_SUCH_ENTITY:

No such event exists

net.network_event.get_event_blacklist_match_info(response_format)¶

Get information about what exactly was matched on a blacklist hit to trigger this event

URL

/papi/net/event/blacklist_match[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

event_id:

Identifier of event (required)

event_time:

Approximate time of event (within +- a day) (required)

key:

access_key[:subkey]: Restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

customer:

Username of customer (this is an email address). Defaults to the customer for which the current account is authenticated.

Contents of successful response

A dictionary with the following keys:

domain:

Domain of the match (not included if ‘ip’ is)

ip:

IP address of the match (not included if ‘domain’ is)

url_path:

URL path of the match (not included if the match wasn’t on the URL path as well)

port:

Port of the match (not included if the match wasn’t on the port as well)

is_local_blacklist:

Whether this match is on a local blacklist entry

Error Codes

llapi.LLAPI_ERROR__NO_SUCH_ENTITY:

No such event exists

llapi.LLAPI_ERROR_NO_DATA_FOUND:

No match information found

net.network_event.get_event_network_iocs(response_format)¶

Get network IoC (Indicator of Compromise) tags associated with an event.

A network IoC tag can be the result of either a blacklist hit or a signature hit observed during the analysis of a malscape task. Network IoCs are looked up based on the URLs associated with the event.

URL

/papi/net/event/network_iocs[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

event_id:

Identifier of event (required)

event_time:

Approximate time of event (within +- a day) (required)

key:

access_key[:subkey]: Restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

customer:

Username of customer (this is an email address). Defaults to the customer for which the current account is authenticated.

limit:

Limit on the number of items to lookup when retrieving network IoCs (default and maximum 1000)

Contents of successful response

A list of dictionaries with the following keys:

task_uuid:

Unique identifier of the task the network IoC belongs to

score:

Score of the analysis task the network IoC belongs to

domain:

Network ioc domain, ASCII string (not included if ‘ip’ is)

ip:

String representation of the network ioc IP address (not included if ‘domain’ is)

url_path:

Path part of the network ioc, ASCII string (only included if present in the network IoC)

port:

Port of the network ioc (only included if present in the network IoC)

detector:

Name of detector that detected this evidence (if available as part of a signature match network IoC)

threat:

Detected threat. Called “Malware” in Lastline Portal (if available as part of a signature match network IoC)

impact:

Impact of this evidence (if available as part of a signature match network IoC)

Error Codes

llapi.LLAPI_ERROR__NO_SUCH_ENTITY:

No such event exists

net.network_event.get_similar_event_filters(response_format)¶

Get a set of filters to find events similar to the provided one.

Given a network event identifier, this method returns a set of filters that can be used to retrieve similar events.

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >= 8.5.

URL

/papi/net/event/similar_events_filters/get[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

event_id:

Identifier of event (required)

event_time:

Approximate time of event (within +- a day) (required)

key:

access_key[:subkey]: Restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

Contents of successful response

Dictionary containing a selection of the following keys, depending on the specific event:

relevant_host_ip:

IP address of the relevant host (in dotted format)

other_host_ip:

IP address of the other host (in dotted format)

server_port:

The port of the server

other_host_hostname:

Hostname of the other host

transport_protocol:

Transport protocol

relevant_host_in_homenet:

True if the relevant host is included in the configured homenet

other_host_in_homenet:

True if the other host is included in the configured homenet

relevant_host_whitelisted:

True if the relevant host is whitelisted

detector:

Name of the detector related to this event

threat:

Name of the detected threat

threat_class:

Class of the detected threat

event_outcome:

Outcome of the event, either “DETECTION” or “INFO”

event_type:

The event type

file_category:

High-level category of the file, e.g., Executable, Document, Java, etc.

file_type:

File type of downloaded file: detailed string

av_class:

Malware classes associated with the file during analysis

malware:

Malware associated with the file during analysis

llanta_rule_uuid:

Unique identifier of the custom Breach Defender rule that was matched and triggered the event

custom_ids_rule_id:

Identifier of the customer-provided ids rule signature

relevant_host_tags:

The tags of the relevant host

other_host_tags:

The tags of the other host

Error Codes

llapi.LLAPI_ERROR__NO_SUCH_ENTITY:

No such event exists

**Example response **

File download:

{

‘av_class’: [‘trojan’], ‘dst_ip’: ‘170.12.8.249’, ‘dst_port’: 53, ‘event_outcome’: ‘DETECTION’, ‘event_type’: ‘BINARYDOWNLOAD’, ‘file_category’: ‘Executable’, ‘file_type’: ‘PE32 executable (GUI) Intel 80386, for MS Windows’, ‘relevant_host_in_homenet’: False, ‘hostname’: ‘installer.filebulldog.com’, ‘malware’: [‘Emotet’], ‘other_host’: ‘170.12.8.249’, ‘other_host_hostname’: ‘installer.filebulldog.com’, ‘other_host_tags’: [‘my_tag’], ‘relevant_host’: ‘192.168.1.1’, ‘relevant_host_tags’: [‘another_tag’], ‘server_port’: 53, ‘src_ip’: ‘192.168.1.1’, ‘threat’: ‘FileBulldog’, ‘threat_class’: ‘adware’,

}

IDS event:

{

‘dst_ip’: ‘170.12.8.249’, ‘dst_port’: 53, ‘event_outcome’: ‘DETECTION’, ‘event_type’: ‘IDS’, ‘relevant_host_in_homenet’: False, ‘hostname’: ‘installer.filebulldog.com’, ‘other_host’: ‘170.12.8.249’, ‘other_host_hostname’: ‘installer.filebulldog.com’, ‘other_host_tags’: [‘my_tag’], ‘relevant_host’: ‘192.168.1.1’, ‘relevant_host_tags’: [‘another_tag’], ‘server_port’: 53, ‘src_ip’: ‘192.168.1.1’, ‘threat’: ‘FileBulldog’, ‘threat_class’: ‘adware’,

}

Captured files¶

Method Index¶

get_downloads():

Get information on file downloads on the protected network that were subjected to in-depth analysis
get_unique_downloads():

Get information on unique files downloaded in the protected network that were subjected to in-depth analysis
get_download_stats():

Get information on the number of files downloaded in the protected network that were subjected to in-depth analysis
get_download_log():

Get information on all file downloads detected on the protected network
get_download_log_stats():

Get information on the number of files downloaded in the protected network

Method Documentation¶

net.file_capture.get_downloads(response_format)¶

Get information about downloads of files in a protected network.

URL

/papi/net/file/downloads[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_time:

Get downloads after this time (required)

end_time:

Get downloads before this time (required)

start_datetime:

Alternative name for start_time (deprecated)

end_datetime:

Alternative name for end_time (deprecated)

timezone:

Name of selected time zone

Appliance selection:

key:

access_key[:subkey]: Get downloads detected by sensors with this key

key_id:

Get downloads detected by sensors with this key

subkey_id:

Get downloads detected by sensors with this subkey (provide together with key_id in alternative to key).

Sorting and pagination:

orderby:

Sort results based on this parameter. Can be one of:

start_time [ASC|DESC] to sort by time of download score [ASC|DESC] to sort by score of downloaded file

max_results:

Limit to this many results

offset_results:

Skip the first offset_results results.

Filters:

include_not_uploaded:

Also include downloads for which the downloaded file could not be uploaded for analysis (default False). Note that this will still not include file downloads of files that were determined to be benign on the sensor so no attempt was made to upload them for analysis.

application_protocol:

Select application protocol of download. Currently one of ‘HTTP’, ‘SMB’, ‘FTP’

event_id:

Only get downloads linked to this network event

md5:

Restrict to downloads of file with this md5 sum

task_uuid:

Restrict to downloads of files analyzed in this analysis task

min_score:

Restrict to downloads scoring at least this value (0-100)

filetype:

Restrict to downloads of one of these file types.

src_ip:

Restrict to downloads by these hosts in the protected network. This is a comma-separated list of IP addresses, IP ranges or CIDR blocks such as:

1.2.3.4

1.2.3.4-1.2.3.5

1.2.3.0/24

src_hostname:

Restrict to these hosts in the monitored network, selected by host name or label, comma-separated

dst_ip:

Restrict to downloads from these hosts. This is a comma-separated list of IP addresses, IP ranges or CIDR blocks.

http_host:

Restrict to http downloads from these hosts, as listed in the HTTP Host header. This is a comma-separated list of host names.

homenet

3-value Boolean. If set to True only return data where the host downloading the file is in homenet, if set to False only return data where the host downloading the file is not in the homenet, if not set return everything.

whitelisting

Boolean parameter to exclude file downloads from whitelisted sources

analysis_task_typed_tags:

Serialized JSON encoded sequence of Analysis Task Typed Tags. Each Typed Tag is a sequence of 2 strings for the typed tag’s type and value.

e.g. ‘[[“av_family”, “locky”], [“av_class”, “ransomware”]]’

(available for Lastline Enterprise On-Premise versions >= 7.18)

include_typed_tags:

Include the list of Analysis Task Typed Tags with each file download given a list of Analysis Task Typed Tag Types that should be included.

e.g. ‘av_family,av_class’ would return a list of Typed Tags that fit the criteria of only having a Typed Tag Type’s of “av_family” and “av_class”.

(available for Lastline Enterprise On-Premise versions >= 7.18)

Contents of successful response

A list of mappings, containing the following fields:

access_key_id:

Identifier of license of sensor that detected download

subkey_id:

Identifier of subkey of sensor that detected download

time:

Time of download, in requested timezone.

file_name:

Name of downloaded file

file_size:

Size of downloaded file, in bytes

md5:

MD5 hash of downloaded file

sha1:

SHA-1 hash of downloaded file

file_type:

File type of downloaded file: detailed string

llfiletype

File type of downloaded file: high-level category, such as Executable, Document, Java, Pdf. These are also the values that can be used in the filetypes filter of this method.

extracted_filename:

If file was extracted from an archive, file name of the extracted file as recorded in the archive metadata.

score:

Lastline score for downloaded file (0-100)

pending:

Is Lastline analysis of this file still pending?

task_uuid:

Lastline Engine task UUID

event_id:

Identifier of network event associated with this download

src_host:

IP of host in the protected network that downloaded the file

src_hostname:

Hostname of host in the protected network that downloaded the file

src_port:

TCP port used at src_host

dst_host:

IP of host from which the file was downloaded

dst_port:

TCP port used at dst_host

relevant_host_ip:

IP of relevant host

relevant_host_port:

Port of relevant host

relevant_host_hostname:

Host name of relevant host

other_host_ip:

IP of other host

other_host_port:

Port of other host

other_host_hostname:

Hostname of other host

server_ip:

IP of server

server_port:

Port of server

server_hostname:

Host name of server

client_ip:

IP of client

client_port:

Port of client

client_hostname:

Hostname of client

application_protocol:

Protocol used to download file: currently HTTP, FTP or SMB

action:

The action that was applied on the download, possible values are:

LOG

BLOCK

Additional fields are provided for downloads that used specific application-layer protocols.

HTTP:

hostname:

HTTP Host header value

user_agent:

HTTP User-agent header value

referer:

HTTP referer header value

content_disposition_filename:

File name, as reported in the HTTP Content-Disposition header

http_direction:

‘UPLOAD’ or ‘DOWNLOAD’

FTP:

ftp_action:

‘GET’ or ‘PUT’

ftp_mode:

‘ACTIVE’ or ‘PASSIVE’

SMB:

smb_direction:

‘READ’ or ‘WRITE’

mount_point:

Mount point of share from which file was downloaded

Tags:

typed_tags:

A sequence of tuples: each tuple consists of a type and a value

Legacy API:

This method replaces the ‘query_file_downloads’ and ‘query_binaries’ methods of the legacy Lastline API.

Changes:

start_time and end_time parameters are required for this method. The legacy method made them optional if an event_id was provided.

net.file_capture.get_unique_downloads(response_format)¶

Get information about unique downloaded files in a protected network.

URL

/papi/net/file/unique_downloads[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_time:

Get downloads after this time (required)

end_time:

Get downloads before this time (required)

start_datetime:

Alternative name for start_time (deprecated)

end_datetime:

Alternative name for end_time (deprecated)

timezone:

Name of selected time zone

Appliance selection:

key:

access_key[:subkey]: Get downloads detected by sensors with this key

key_id:

Get downloads detected by sensors with this key

subkey_id:

Get downloads detected by sensors with this subkey (provide together with key_id in alternative to key).

Sorting and pagination:

orderby:

Sort results based on this parameter. Can be one of:

start_time [ASC|DESC] to sort by time of download score [ASC|DESC] to sort by score of downloaded file

max_results:

Limit to this many results

offset_results:

Skip the first offset_results results.

Filters:

include_not_uploaded:

Also include downloads for which the downloaded file could not be uploaded for analysis (default False). Note that this will still not include file downloads of files that were determined to be benign on the sensor so no attempt was made to upload them for analysis.

application_protocol:

Select application protocol of download. Currently one of ‘HTTP’, ‘SMB’, ‘FTP’

event_id:

Only get downloads linked to this network event

md5:

Restrict to downloads of file with this md5 sum

task_uuid:

Restrict to downloads of files analyzed in this analysis task

min_score:

Restrict to downloads scoring at least this value (0-100)

filetype:

Restrict to downloads of one of these file types.

src_ip:

Restrict to downloads by these hosts in the protected network. This is a comma-separated list of IP addresses, IP ranges or CIDR blocks such as:

1.2.3.4

1.2.3.4-1.2.3.5

1.2.3.0/24

dst_ip:

Restrict to downloads from these hosts. This is a comma-separated list of IP addresses, IP ranges or CIDR blocks.

http_host:

Restrict to http downloads from these hosts, as listed in the HTTP Host header. This is a comma-separated list of host names.

homenet

3-value Boolean. If set to True only return data where the host downloading the file is in homenet, if set to False only return data where the host downloading the file is not in the homenet, if not set return everything.

whitelisting

Boolean parameter to exclude file downloads from whitelisted sources

analysis_task_typed_tags:

Serialized JSON encoded sequence of Analysis Task Typed Tags. Each Typed Tag is a sequence of 2 strings for the typed tag’s type and value.

e.g. ‘[[“av_family”, “locky”], [“av_class”, “ransomware”]]’

(available for Lastline Enterprise On-Premise versions >= 7.18)

include_typed_tags:

Include the list of Analysis Task Typed Tags with each file download given a list of Analysis Task Typed Tag Types that should be included.

e.g. ‘av_family,av_class’ would return a list of Typed Tags that fit the criteria of only having a Typed Tag Type’s of “av_family” and “av_class”.

(available for Lastline Enterprise On-Premise versions >= 7.18)

Contents of successful response

A list of mappings, containing the fields listed below. For fields that may vary across downloads of a same file, this method typically returns one value among those observed, as well as the number of distinct values seen.

num_downloads:

Number of downloads of this file

num_sensors:

Number of sensors that observed downloads of this file

first_seen:

Time of first download, in requested timezone.

last_seen:

Time of last download, in requested timezone.

file_name:

Name of downloaded file

num_file_names:

Number of different file names under which this file was downloaded

file_size:

Size of downloaded file, in bytes

md5:

MD5 hash of downloaded file

sha1:

SHA-1 hash of downloaded file

file_type:

File type of downloaded file: detailed string

llfiletype

File type of downloaded file: high-level category, such as Executable, Document, Java, Pdf. These are also the values that can be used in the filetypes filter of this method.

score:

Lastline score for downloaded file (0-100)

pending:

Is Lastline analysis of this file still pending?

task_uuid:

Lastline Engine task UUID

src_host:

Host in the protected network that downloaded the file

num_sources:

Number of distinct values of src_host

dst_host:

Host from which the file was downloaded

num_dst_ips:

Number of distinct values of dst_host

application_protocol:

Protocol used to download file: currently HTTP, FTP or SMB

num_application_protocols:

Number of different application protocols

hostname:

HTTP Host header value

num_hostnames:

Number of different hostname values

action:

The action that was applied on the download, possible values are:

LOG

BLOCK

If any of the aggregated downloads was blocked, the value of this field will be “BLOCK”

typed_tags:

A sequence of tuples: each tuple consists of a type and a value

Legacy API:

This method replaces the ‘query_downloaded_files’ method of the legacy Lastline API.

Changes:

start_time and end_time parameters are required for this method. The legacy method made them optional if an event_id was provided.

net.file_capture.get_download_stats(response_format)¶

Get information about unique downloaded files in a protected network.

URL

/papi/net/file/get_download_stats[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_time:

Get downloads after this time (required)

end_time:

Get downloads before this time (required)

start_datetime:

Alternative name for start_time (deprecated)

end_datetime:

Alternative name for end_time (deprecated)

timezone:

Name of selected time zone

time_zone:

Alternative name for timezone (deprecated)

Appliance selection:

key:

access_key[:subkey]: Get stats on downloads detected by sensors with this key

key_id:

Get stats on downloads detected by sensors with this key

subkey_id:

Get stats on downloads detected by sensors with this subkey (provide together with key_id in alternative to key).

Filters:

include_not_uploaded:

Also include downloads for which the downloaded file could not be uploaded for analysis (default False). Note that this will still not include file downloads of files that were determined to be benign on the sensor so no attempt was made to upload them for analysis.

application_protocol:

Select application protocol of download. Currently one of ‘HTTP’, ‘SMB’, ‘FTP’

md5:

Restrict to downloads of file with this md5 sum

task_uuid:

Restrict to downloads of files analyzed in this analysis task

min_score:

Restrict to downloads scoring at least this value (0-100)

src_ip:

Restrict to downloads by these hosts in the protected network. This is a comma-separated list of IP addresses, IP ranges or CIDR blocks such as:

1.2.3.4

1.2.3.4-1.2.3.5

1.2.3.0/24

dst_ip:

Restrict to downloads from these hosts. This is a comma-separated list of IP addresses, IP ranges or CIDR blocks.

http_host:

Restrict to http downloads from these hosts, as listed in the HTTP Host header. This is a comma-separated list of host names.

homenet

3-value Boolean. If set to True only return data where the host downloading the file is in homenet, if set to False only return data where the host downloading the file is not in the homenet, if not set return everything.

whitelisting

Boolean parameter to exclude file downloads from whitelisted sources

analysis_task_typed_tags:

Serialized JSON encoded sequence of Analysis Task Typed Tags. Each Typed Tag is a sequence of 2 strings for the typed tag’s type and value.

e.g. ‘[[“av_family”, “locky”], [“av_class”, “ransomware”]]’

(available for Lastline Enterprise On-Premise versions >= 7.18)

Contents of successful response

A list of mappings, containing the fields listed below. Element are grouped by matching file_category and start_date

file_category:

Category of the files for this group

start_date:

Date of the beginning of the download for this group

total_files:

Number of downloads in this group

distinct_files:

Number of downloads of distinct files in this group

max_score:

Maximum of all the file score in this group

Legacy API:

This method replaces the ‘query_download_stats’ method of the legacy Lastline API.

Changes:

start_date and end_date parameters does not accept datetime format any more (e.g. ‘2014-06-10 11:21:30’), but only date format (e.g. ‘2014-06-10’)

net.file_capture.get_download_log(response_format)¶

Get information about downloads of files in a protected network.

URL

/papi/net/file/download_logs[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_time:

Get downloads after this time (required)

end_time:

Get downloads before this time (required)

timezone:

Name of selected time zone

Appliance selection:

key:

access_key[:subkey]: Get stats on downloads detected by sensors with this key

key_id:

Get stats on downloads detected by sensors with this key

subkey_id:

Get stats on downloads detected by sensors with this subkey (provide together with key_id in alternative to key).

Sorting and pagination:

orderby:

Sort results based on this parameter. Sorting available on:

start_time [ASC|DESC] to sort by time of download

max_results:

Limit to this many results

offset_results:

Skip the first offset_results results.

Filters:

application_protocol:

Select application protocol of download. Currently available: ‘HTTP’, ‘HTTPS’ , ‘SMB’, ‘FTP’, ‘OTHER’

filetype:

Select the type of file to consider.

md5:

Restrict to downloads of file with these md5s sum

sha1:

Restrict to downloads of file with these sha1s sum

task_uuid:

Restrict to downloads of file with these task UUIDs

Available for Lastline Enterprise On-Premise versions >= 7.14.

src_ip:

Restrict to downloads by these hosts in the protected network. This is a comma-separated list of IP addresses, IP ranges or CIDR blocks such as:

1.2.3.4

1.2.3.4-1.2.3.5

1.2.3.0/24

dst_ip:

Restrict to downloads from these hosts. This is a comma-separated list of IP addresses, IP ranges or CIDR blocks.

src_host:

Restrict to downloads to these hosts in the protected network, as listed in the HTTP Host header. This is a comma-separated list of host names.

dst_host:

Restrict to downloads from these hosts, as listed in the HTTP Host header. This is a comma-separated list of host names.

direction:

Restrict direction of the download: UPLOAD or DOWNLOAD

submitted

3-value Boolean. If set to True, only returns data that has been uploaded to malscape. If False, returns data that has not been processed. If not seet, returns everything

homenet

3-value Boolean. If set to True only return data where the host downloading the file is in homenet, if set to False only return data where the host downloading the file is not in the homenet, if not set return everything.

whitelisting

Boolean parameter to exclude file downloads from whitelisted sources

Contents of successful response

A list of mappings, containing the following fields:

access_key_id:

Identifier of license of sensor that detected download

subkey_id:

Identifier of subkey of sensor that detected download

time:

Time of download, in requested timezone.

file_name:

For HTTP, this will be derived from the Content-Disposition header, if available. In all other cases, it will be the url-derived path

file_size:

Size of downloaded file, in bytes

md5:

MD5 hash of downloaded file

sha1:

SHA-1 hash of downloaded file

raw_url:

Raw version of the malicious url found in the file (if any)

url:

Human readable version of the malicious url found in the file (if any)

llfiletype

File type of downloaded file: high-level category, such as Executable, Document, Java, Pdf. These are also the values that can be used in the filetypes filter of this method.

submitted

Boolean specifying if the file has been submitted to analysis

pending

Is Lastline analysis of this file still pending? (None if not submitted)

score:

Lastline score for downloaded file (0-100 or null if not submitted)

task_uuid:

Lastline Engine task UUID or null if not submitted

direction

Direction of the file transfer: DOWNLOAD or UPLOAD

src_host:

IP of host in the protected network

src_hostname:

Hostname of host in the protected network

src_port:

TCP port used at src_host

dst_host:

IP of host from which the file was downloaded

dst_port:

TCP port used at dst_host

dst_hostname:

hostname from which the file was downloaded

application_protocol:

Protocol used to download file: currently HTTP, HTTPS, FTP, SMB or OTHER

file_upload_status:

Whether file was uploaded for analysis, and why. Possible values for this field currently include:

‘FILE_EXTRACTION_INCOMPLETE’

‘FILE_EXTRACTION_PROTO_ERROR’

‘FILE_SOURCE_WHITELISTED_BY_LL’

‘FILE_SOURCE_WHITELISTED_BY_CUST’

‘FILE_DECRYPTION_ERROR’

‘FILE_TOO_LARGE’

‘PREFILTER_BENIGN’

‘MALSCAPE_SUBMITTED_FILE_KNOWN’

‘MALSCAPE_SUBMITTED_FILE_NEW’

‘MALSCAPE_ERROR_INVALID_FILETYPE’

‘MALSCAPE_ERROR_QUOTA_EXCEEDED’

‘MALSCAPE_ERROR_SERVICE_UNAVAILABLE’

‘MALSCAPE_ERROR_UNEXPECTED_REASON’

‘UNKNOWN’

net.file_capture.get_download_log_stats(response_format)¶

Get statistics about downloads of files in a protected network.

URL

/papi/net/file/download_log_stats[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_time:

Get downloads after this time (required)

end_time:

Get downloads before this time (required)

timezone:

Name of selected time zone

Appliance selection:

key:

access_key[:subkey]: Get stats on downloads detected by sensors with this key

key_id:

Get stats on downloads detected by sensors with this key

subkey_id:

Get stats on downloads detected by sensors with this subkey (provide together with key_id in alternative to key).

Filters:

application_protocol:

Select application protocol of download. Currently available: ‘HTTP’, ‘HTTPS’ , ‘SMB’, ‘FTP’, ‘OTHER’

filetype:

Select the type of file to consider.

md5:

Restrict to downloads of file with these md5s sum

sha1:

Restrict to downloads of file with these sha1s sum

src_ip:

Restrict to downloads by these hosts in the protected network. This is a comma-separated list of IP addresses, IP ranges or CIDR blocks such as:

1.2.3.4

1.2.3.4-1.2.3.5

1.2.3.0/24

dst_ip:

Restrict to downloads from these hosts. This is a comma-separated list of IP addresses, IP ranges or CIDR blocks.

src_host:

Restrict to downloads to these hosts in the protected network, as listed in the HTTP Host header. This is a comma-separated list of host names.

dst_host:

Restrict to downloads from these hosts, as listed in the HTTP Host header. This is a comma-separated list of host names.

direction:

Restrict direction of the download: UPLOAD or DOWNLOAD

submitted

3-value Boolean. If set to True, only returns data that has been uploaded to malscape. If False, returns data that has not been processed. If not seet, returns everything

homenet

3-value Boolean. If set to True only return data where the host downloading the file is in homenet, if set to False only return data where the host downloading the file is not in the homenet, if not set return everything.

whitelisting

Boolean parameter to exclude file downloads from whitelisted sources

Contents of successful response

A list of mappings, containing the fields listed below. Element are grouped by matching file_category and start_date

file_category:

Category of the files for this group

start_date:

Date of the beginning of the download for this group

total_files:

Number of downloads in this group

distinct_files:

Number of downloads of distinct files in this group

Detected URLs¶

Method Index¶

get_url_detections():

Get information about URLs detected in the protected network
get_unique_detected_urls():

Get information on unique URLs detected in the protected network
get_detected_url_stats():

Get statistics on URLs detected on the network over time

Method Documentation¶

net.url.get_url_detections(response_format)¶

Get information about the detected URLs on the protected network.

On-Premise availability: This API method is available for Lastline Enterprise On-Premise version >= 7.6

URL

/papi/net/url/all[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_time:

Get detected urls after this time (required)

end_time:

Get detected urls before this time (required)

timezone:

Name of the selected timezone

Appliance selection:

key:

access_key[:subkey]: Get urls detected by sensors with this key

key_id:

Get urls detected by sensors with this key

subkey_id:

Get urls detected by sensors with this subkey (provide together with key_id in alternative to key)

Sorting and pagination:

orderby:

Sort results based on this parameter. Can be one of:

detection_time [ASC|DESC]: to sort by time of detection

score [ASC|DESC]: to sort by score of the url

max_results:

Limit to this many results

offset_results:

Skip the first offset_results results.

Filters:

detected_url_id:

The identifier of a detected URL. This is a comma separated list of identifiers.

event_id:

The identifier of the event_id of a detected url. This is a comma separated list of identifiers.

include_not_analyzed:

Also include detected URLs for which the URL could not be analyzed. (default: false)

task_uuid:

Restrict to URL(s) analyzed by this analysis task uuid(s). This is a comma-separated list of task uuids.

priority:

The priority of the detected URL based on the score produced by Lastline. Can be one of the following:

LOW

MEDIUM

HIGH

min_score:

Restrict to downloads scoring at least this value (0-100) (default: 0)

url:

Restrict to URL(s) that match this string. This must be the full, verbatim, URL. This is a JSON list of values, for example: [“http://lastline.com”, “user.lastline.com”].

md5:

Restrict to URL matching this md5 sum. This is a comma-separated list of MD5s.

http_host:

Restrict to URL(s) matching these hosts, as listed in the HTTP Host header. This is a comma-separated list of host names.

src_ip:

Restrict to URL(s) with this source IP. This is a comma-separated list of IP addresses, IP ranges or CIDR blocks such as:

1.2.3.4

1.2.3.4-1.2.3.5

1.2.3.0/24

dst_ip:

Restrict to URL(s) with this destination IP. This is a comma-seperated list of IP addresses, IP ranges or CIDR blocks.

homenet:

3-value Boolean. If set to True only return data where the host making the HTTP request is in the homenet, if set to False only return data where the host making the HTTP request is not in the homenet, if not set return everything.

whitelisting:

Boolean parameter to exclude HTTP requests coming from whitelisted sources.

analysis_task_typed_tags:

Serialized JSON encoded sequence of Analysis Task Typed Tags. Each Typed Tag is a sequence of 2 strings for the typed tag’s type and value.

e.g. ‘[[“av_family”, “locky”], [“av_class”, “ransomware”]]’

(available for Lastline Enterprise On-Premise versions >= 7.18)

include_typed_tags:

Include the list of Analysis Task Typed Tags with each URL given a list of Analysis Task Typed Tag Types that should be included.

e.g. ‘av_family,av_class’ would return a list of Typed Tags that fit the criteria of only having a Typed Tag Type’s of “av_family” and “av_class”.

(available for Lastline Enterprise On-Premise versions >= 7.18)

Contents of successful response

A list of dictionaries with the following fields:

url:

The URL that the sensor detected

md5:

The MD5 hash of the full URL

detected_url_id:

Identifier of a detected URL.

access_key_id:

Identifier of the license of the sensor that detected the URL.

subkey_id:

Identifier of the subkey of the sensor that detected the URL.

timestamp:

Timestamp of the registration of the URL in the DB, in the requested timezone

detection_time:

The date of when the URL was detected on the network.

event_id:

Identifier of network event (if any) associated with this download.

score:

Lastline score for the analyzed URL (0-100)

pending:

Is Lastline analysis of this file still pending?

task_uuid:

Lastline Engine task UUID

src_host:

Host in the protected network that made a request to the URL.

src_ip:

The IP of the host in the protected network that made a request to the URL.

src_port:

TCP port used at src_host

dst_host:

The URL resolved to this destination host

dst_ip:

The IP of the resolved destination host.

dst_port:

TCP port used at dst_host

http_host:

HTTP Host header value in the HTTP request

user_agent:

HTTP User-Agent header value in the HTTP request

referer:

HTTP Referrer header value in the HTTP request

typed_tags:

A sequence of tuples: each tuple consists of a type and a value

net.url.get_unique_detected_urls(response_format)¶

Get information about unique detected URLs on the protected network.

On-Premise availability

This API method is available for Lastline Enterprise On-Premise version >= 7.6

URL

/papi/net/url/unique[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_time:

Get detected urls after this time (required)

end_time:

Get dtected urls before this time (required)

timezone:

Name of the selected timezone

Appliance selection:

key:

access_key[:subkey]: Get urls detected by sensors with this key

key_id:

Get urls detected by sensors with this key

subkey_id:

Get urls detected by sensors with this subkey (provide together with key_id in alternative to key)

Sorting and pagination:

orderby:

Sort results based on this parameter. Can be one of: - detection_time [ASC|DESC] to sort by time of detection - score [ASC|DESC] to sort by score of the url

max_results:

Limit to this many results

offset_results:

Skip the first offset_results results.

Filters:

detected_url_id:

The identifier of a detected URL. This is a comma separated list of identifiers.

event_id:

The identifier of the event_id of a detected url. This is a comma separated list of identifiers.

include_not_analyzed:

Also include detected URLs for which the URL could not be analyzed. (default: false)

task_uuid:

Restrict to URL(s) analyzed by this analysis task uuid(s). This is a comma-separated list of task uuids.

priority:

The priority of the detected URL based on the score produced by Lastline. Can be one of the following:

LOW

MEDIUM

HIGH

min_score:

Restrict to downloads scoring at least this value (0-100) (default: 0)

url:

Restrict to URL(s) that match this string. This must be the full, verbatim, URL. This is a JSON list of values, for example: [“http://lastline.com”, “user.lastline.com”].

md5:

Restrict to URL matching this md5 sum. This is a comma-separated list of MD5s.

http_host:

Restrict to URL(s) matching these hosts, as listed in the HTTP Host header. This is a comma-separated list of host names.

src_ip:

Restrict to URL(s) with this source IP. This is a comma-separated list of IP addresses, IP ranges or CIDR blocks such as:

1.2.3.4

1.2.3.4-1.2.3.5

1.2.3.0/24

dst_ip:

Restrict to URL(s) with this destination IP. This is a comma-seperated list of IP addresses, IP ranges or CIDR blocks.

homenet:

3-value Boolean. If set to True only return data where the host making the HTTP request is in the homenet, if set to False only return data where the host making the HTTP request is not in the homenet, if not set return everything.

whitelisting:

Boolean parameter to exclude HTTP requests coming from whitelisted sources.

analysis_task_typed_tags:

Serialized JSON encoded sequence of Analysis Task Typed Tags. Each Typed Tag is a sequence of 2 strings for the typed tag’s type and value.

e.g. ‘[[“av_family”, “locky”], [“av_class”, “ransomware”]]’

(available for Lastline Enterprise On-Premise versions >= 7.18)

include_typed_tags:

Include the list of Analysis Task Typed Tags with each URL given a list of Analysis Task Typed Tag Types that should be included.

e.g. ‘av_family,av_class’ would return a list of Typed Tags that fit the criteria of only having a Typed Tag Type’s of “av_family” and “av_class”.

(available for Lastline Enterprise On-Premise versions >= 7.18)

Contents of successful response

A list of dictionaries with the following fields:

url:

The URL that the sensor detected.

md5:

The MD5 hash of the full URL.

num_requests:

Number of times host(s) made a request to this URL.

num_sensors:

Number of sensors that observed hosts, on the protected network, making a request to this URL.

first_seen:

Time of the first request made to this URL.

last_seen:

Time of the last request made to this URL.

score:

Lastline score for the analyzed URL.

pending:

Is Lastline analysis of this file still pending?

task_uuid:

Lastline Engine task UUID.

src_ip:

Host in the protected network that made a request to the URL.

dst_ip:

The URL resolved to this destination host.

num_source_ips:

Number of distinct values of src_host.

num_dst_ips:

Number of distinct values resolved to the destination host.

http_host:

HTTP Host header value.

num_http_host:

Number of distinct http host values.

typed_tags:

A sequence of tuples: each tuple consists of a type and a value

net.url.get_detected_url_stats(response_format)¶

Get information about unique detected URLs on the protected network.

On-Premise availability

This API method is available for Lastline Enterprise On-Premise version >= 7.6

URL

/papi/net/url/stats[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_date:

Get detected urls after this time (required)

end_date:

Get detected urls before this time (required)

timezone:

Name of the selected timezone

time_scale:

‘day’, ‘week’, ‘month’, defaults to ‘day’ This is the scale of the data represented. If set to day, then the stats will be grouped for each day. If week / month the stats will be grouped by week / month respectively.

Note: The start_date for each grouping will be the beginning of

the day / week / month, NOT the start_date specified.

For example, if we specify a start_date that lands on a Friday, and the time_scale is set to ‘week’, the grouping start date will be first day of that week (Sunday), but will not contain the data from Sunday-Thursday since the start_date is on Friday. The same applies for the end_date if it is not the last day of the week / month.

Appliance selection:

key:

access_key[:subkey]: Get urls detected by sensors with this key

key_id:

Get urls detected by sensors with this key

subkey_id:

Get urls detected by sensors with this subkey (provide together with key_id in alternative to key)

Filters:

detected_url_id:

The identifier of a detected URL. This is a comma separated list of identifiers.

event_id:

The identifier of the event_id of a detected url. This is a comma separated list of identifiers.

include_not_analyzed:

Also include detected URLs for which the URL could not be analyzed. (default: false)

task_uuid:

Restrict to URL(s) analyzed by this analysis task uuid(s). This is a comma-separated list of task uuids.

priority:

The priority of the detected URL based on the score produced by Lastline. Can be one of the following:

LOW

MEDIUM

HIGH

min_score:

Restrict to downloads scoring at least this value (0-100) (default: 0)

url:

Restrict to URL(s) that match this string. This must be the full, verbatim, URL. This is a JSON list of values, for example: [“http://lastline.com”, “user.lastline.com”].

md5:

Restrict to URL matching this md5 sum. This is a comma-separated list of MD5s.

http_host:

Restrict to URL(s) matching these hosts, as listed in the HTTP Host header. This is a comma-separated list of host names.

src_ip:

Restrict to URL(s) with this source IP. This is a comma-separated list of IP addresses, IP ranges or CIDR blocks such as:

1.2.3.4

1.2.3.4-1.2.3.5

1.2.3.0/24

dst_ip:

Restrict to URL(s) with this destination IP. This is a comma-seperated list of IP addresses, IP ranges or CIDR blocks.

homenet:

3-value Boolean. If set to True only return data where the host making the HTTP request is in the homenet, if set to False only return data where the host making the HTTP request is not in the homenet, if not set return everything.

whitelisting:

Boolean parameter to exclude HTTP requests coming from whitelisted sources.

analysis_task_typed_tags:

Serialized JSON encoded sequence of Analysis Task Typed Tags. Each Typed Tag is a sequence of 2 strings for the typed tag’s type and value.

e.g. ‘[[“av_family”, “locky”], [“av_class”, “ransomware”]]’

(available for Lastline Enterprise On-Premise versions >= 7.18)

Contents of successful response

A list of dictionaries containing the fields listed below. Each element is grouped by severity and detection_time.

priority:

The priority levels of the visited URL based on the score produced by the Lastline Analysis Engine. The severity can be one of three possible values: - HIGH - MEDIUM - LOW

start_date:

Date of the beginning of all URLs detected for this group

end_date:

Date of the end of all URLs detected for this group.

total_urls:

Number of URLs detected in this group

distinct_urls:

Number of distinct URLs detected in this group

Traffic captures¶

Method Index¶

get_pcap():

Get a traffic capture in pcap format
get_parsed_pcap():

Get a parsed traffic capture
get_event_parsed_pcaps():

Get parsed traffic captures for an event
get_pcaps_info():

Get information about traffic captures
get_event_pcaps_info():

Get information about traffic captures associated with an event
get_pcaps_info_legacy():

DEPRECATED: Get information about traffic captures

Method Documentation¶

net.pcap.get_pcap()¶

Download a pcap

URL

/papi/net/pcap/get_pcap

HTTP METHOD

GET

GET Parameters

pcap_id:

Identifier of pcap we want (required)

pcap_time:

Approximate time of pcap (within +/- a day) (optional but recommended)

key:

access_key[:subkey]: Restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

customer:

Username of customer (this is an email address). Defaults to the customer for which the current account is authenticated.

timezone:

Name of selected time zone

Contents of successful response

Raw traffic capture in pcap format.

net.pcap.get_parsed_pcap(response_format)¶

Get a parsed pcap

URL

/papi/net/pcap/parsed[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

pcap_id:

Identifier of pcap we want (required)

pcap_time:

Approximate time of pcap (within +/- a day) (required)

key:

access_key[:subkey]: Restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

customer:

Username of customer (this is an email address). Defaults to the customer for which the current account is authenticated.

timezone:

Name of selected time zone

Contents of successful response

Each parsed pcap is a dictionary with the following keys:

flows:

List of flows contained in the pcap

Each flow is a dictionary with the following keys:

ip_protocol:

String representation of the flow’s IP protocol (tcp, udp, icmp).

src_ip:

IPv4 that the flow originated from.

src_port:

Port that the flow originated from.

dst_ip:

IPv4 that the flow contacted.

dst_port:

Port that the flow contacted.

state:

State of the flow (new, connecting, established, closing, closed, reset).

src_tx:

Bytes sent.

dst_tx:

Bytes received.

tags:

Give indication on the type of application level protocol.

app_data:

Dictionary of keyed application level data associating the protocol name to the app level data. All flows have at least one protocol: raw. Each protocol has a unique structure.

Sample Response
{
  "success": 1,
  "data": {
    "flows": [{
      "ip_protocol": "tcp",
      "ts": "2015-01-20 20:39:19",
      "src_ip": "172.16.76.48",
      "src_port": 53790,
      "dst_ip": "67.228.175.196",
      "dst_port": 80,
      "state": "closed",
      "src_tx": 182,
      "dst_tx": 2134,
      "tags": [],
      "app_data": {
        "raw": [
           ['foo foo', true],
           ['bar bar', false]
        ]
      }
    }]
  }
}

Error Codes

llapi.LLAPI_ERROR__NO_SUCH_ENTITY:

No such pcap exists

net.pcap.get_event_parsed_pcaps(response_format)¶

Get parsed pcaps from an event

URL

/papi/net/pcap/event_parsed_pcaps[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

event_id:

Identifier of event we want (required)

event_time:

Approximate time of event (within +/- a day) (required)

key:

access_key[:subkey]: Restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

customer:

Username of customer (this is an email address). Defaults to the customer for which the current account is authenticated.

limit:

Number of pcaps to limit return by. Default/Max is 20.

timezone:

Name of selected time zone

Contents of successful response

Returns a dictionary with the following keys:

limit_reached:

Limit reached is only set when there were more pcaps available than the current limit allowed for.

pcaps:

List of parsed pcaps.

Each parsed pcap is a dictionary with only a flows key which has a value of a list of flows. Each flow is a dictionary with the following keys:

ip_protocol:

String representation of the flow’s IP protocol (tcp, udp, icmp).

src_ip:

IPv4 that the flow originated from.

src_port:

Port that the flow originated from.

dst_ip:

IPv4 that the flow contacted.

dst_port:

Port that the flow contacted.

state:

State of the flow (new, connecting, established, closing, closed, reset).

src_tx:

Bytes sent.

dst_tx:

Bytes received.

tags:

Give indication on the type of application level protocol.

app_data:

Dictionary of keyed application level data associating the protocol name to the app level data. All flows have at least one protocol: raw. Each protocol has a unique structure.

Sample Response
{
  "success": 1,
  "data": {
    "limit_reached": true, //This is only set if there are more pcaps than the limit allows
    "pcaps": [{
      "flows": [{
        "ip_protocol": "tcp",
        "ts": "2015-01-27 22:24:28",
        "src_ip": "172.16.76.48",
        "src_port": 40547,
        "dst_ip": "67.228.175.196",
        "dst_port": 80,
        "state": "closed",
        "src_tx": 182,
        "dst_tx": 2134,
        "tags": [],
        "app_data": {
          "raw": [
               ['foo foo', true],
               ['bar bar', false]
            ]
        }
      }]
    }, {
      "flows": [{
        "ip_protocol": "tcp",
        "ts": "2015-01-27 22:24:29",
        "src_ip": "172.16.76.48",
        "src_port": 40548,
        "dst_ip": "67.228.175.196",
        "dst_port": 80,
        "state": "closed",
        "src_tx": 182,
        "dst_tx": 2134,
        "tags": [],
        "app_data": {
          "raw": [
               ['foo foo', true],
               ['bar bar', false]
            ]
        }
      }]
    }]
  }
}

Error Codes

llapi.LLAPI_ERROR__NO_SUCH_ENTITY:

No such event exists

net.pcap.get_pcaps_info(response_format)¶

Get information about pcaps

URL

/papi/net/pcap/info[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

start_datetime

Approximate datetime of pcap start (within +/- a day) (required)

end_datetime

Approximate datetime of pcap end (within +/- a day, but > start_datetime) (required)

src_ip

Pcap source IPv4 address (required)

dst_ip

Pcap destination IPv4 address

src_port

Pcap source port

dst_port

Pcap destination port

pcap_id:

Identifier of pcap we want

pcap_ids:

List of pcaps we want

key:

access_key[:subkey]: Restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

customer:

Username of customer (this is an email address). Defaults to the customer for which the current account is authenticated.

timezone:

Name of selected time zone

Contents of successful response

Returns a list of pcaps with each pcap having the following properties:

pcap_id

Pcap ID.

start_time

Pcap start time.

src_ip

Source IPv4 address.

src_port

Source port.

dst_ip

Destination IPv4 address.

dst_port

Destination port.

urls

List of URLs accessed in this pcap.

Each URL is a dict with a “display”, “url” and “method” key

hosts

List of hosts the pcap contacted. May be empty.

in_bytes

Number of bytes received. May be null.

out_bytes

Number of bytes sent. May be null.

threats

List of threat names. May be empty.

protocols

List of protocols. May be empty.

successful_connections

Number of successful connections. May be null.

failed_connections

Number of failed connections. May be null.

pcap_access_allowed

true or false if pcap can be downloaded and further analyzed with the current authentication information. However, further analysis and download may be contingent on what pcap_available returns.

pcap_available

true or false if pcap exists in storage.

net.pcap.get_event_pcaps_info(response_format)¶

Get information about pcaps from an event

URL

/papi/net/pcap/event_info[. response_format]

DEPRECATED: /papi/net/pcap/event_pcaps_info[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

event_id

ID of event to query

event_time

Datetime of when the event started

key:

access_key[:subkey]: Restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

customer:

Username of customer (this is an email address). Defaults to the customer for which the current account is authenticated.

timezone:

Name of selected time zone

Contents of successful response

Returns a list of pcaps with each pcap having the following properties:

pcap_id

Pcap ID.

id

Pcap ID. (Deprecated: use pcap_id)

start_time

Pcap start time.

src_ip

Source IPv4 address.

src_port

Source port.

dst_ip

Destination IPv4 address.

dst_port

Destination port.

urls

List of URLs accessed in this pcap.

Each URL is a dict with a “display”, “url” and “method” key

hosts

List of hosts the pcap contacted.

in_bytes

Number of bytes received. May be null.

out_bytes

Number of bytes sent. May be null.

threats

List of threat names.

protocols

List of protocols.

successful_connections

Number of successful connections. May be null.

failed_connections

Number of failed connections. May be null.

pcap_access_allowed

Boolean. If true, pcap can be downloaded and further analyzed with the current authentication information. However, further analysis and download may be contingent on what pcap_available returns.

pcap_available

Boolean. If true, pcap exists in storage.

Error Codes

llapi.LLAPI_ERROR__NO_SUCH_ENTITY:

No such pcap exists

No such event exists

net.pcap.get_pcaps_info_legacy(response_format)¶

DEPRECATED This API route is deprecated and will be phased out. Use /papi/net/pcap/info instead

Get information about pcaps

URL

/papi/net/pcap/pcaps_info[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

start_datetime

Approximate datetime of pcap start (within +/- a day) (required)

end_datetime

Approximate datetime of pcap end (within +/- a day, but > start_datetime) (required)

src_ip

Pcap source IPv4 address (required)

dst_ip

Pcap destination IPv4 address

src_port

Pcap source port

dst_port

Pcap destination port

pcap_id:

Identifier of pcap we want

pcap_ids:

List of pcaps we want

key:

access_key[:subkey]: Restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

customer:

Username of customer (this is an email address). Defaults to the customer for which the current account is authenticated.

timezone:

Name of selected time zone

Contents of successful response

Returns a list of pcaps with each pcap having the following properties:

pcap_id

Pcap ID.

start_time

Pcap start time.

src_ip

Source IPv4 address.

src_port

Source port.

dst_ip

Destination IPv4 address.

dst_port

Destination port.

src_ip_l

Source address as an integer. (deprecated)

dst_ip_l

Destination address as an integer. (deprecated)

urls

List of URLs accessed in this pcap. May be empty.

Each URL is a list with index 0 being the url and index 1 being the method.

eg. ['test.lastline.com', 'GET']

http_hosts

Comma separated list of hosts the pcap contacted. May be null.

in_bytes

Number of bytes received. May be null.

out_bytes

Number of bytes sent. May be null.

threats

Comma separated list of threat names. May be null.

protocols

Comma separated list of protocols. May be null.

successful_connections

Number of successful connections. May be null.

failed_connections

Number of failed connections. May be null.

pcap_access_allowed

1 or 0. If 1 (true), pcap can be downloaded and further analyzed with the current authentication information. However, further analysis and download may be contingent on what pcap_available returns.

pcap_available

1 or 0. If 1 (true), pcap exists in storage.

Error Codes

llapi.LLAPI_ERROR__NO_SUCH_ENTITY:

No such pcap exists

Legacy API: This method replaces the “query_pcaps” method of the legacy Lastline API.

End host events¶

Method Index¶

get_alerts():

Get a filtered list of end host alerts
get_alert_details():

Get full details about a specific end host alert

Method Documentation¶

net.endpoint.get_alerts(response_format)¶

Retrieve a filtered list of endpoint alerts

URL

/papi/net/endpoint/get_alerts[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_time:

Get alerts that happened after this time (required)

end_time:

Get alerts that happened before this time (required)

start_datetime:

Alternative name for start_time (deprecated)

end_datetime:

Alternative name for end_time (deprecated)

timezone:

Name of selected time zone

Appliance selection:

key:

access_key[:subkey]: Get alerts detected by sensors with this key

key_id:

Get alerts detected by sensors with this key

subkey_id:

Get alerts detected by sensors with this subkey (provide together with key_id in alternative to key).

Sorting and pagination:

orderby:

Sort results based on this parameter. Can be one of:

alert_time [ASC|DESC] to sort by time of the alert impact [ASC|DESC] to sort by impact of the alert

max_results:

Limit to this many results

offset_results:

Skip the first offset_results results.

Filters:

alert_type:

Restrict to alerts whose type match the filter.

host_ip:

Restrict to alerts that happened on hosts which IP matches the filter. This is a comma-separated list of IP v4 addresses, IP v4 ranges or CIDR blocks such as:

1.2.3.4

1.2.3.4-1.2.3.5

1.2.3.0/24

file_md5:

Restrict to alerts associated with a file which MD5 that matches the filter. This is a comma-separated list of MD5s

malscape_task_uuid:

Restrict to alerts associated with a file which malscape task UUID matches the filter. This is a comma-separated list of UUIDs

ioc_task_uuid:

Restrict to alerts associated with a file which IOC task UUID matches the filter. This is a comma-separated list of UUIDs

Contents of successful response

A list of mappings, containing the following fields:

access_key_id:

Identifier of license of sensor that detected the alert

subkey_id:

Identifier of subkey of sensor that detected the alert

event_time:

Time of the alert, in requested timezone.

alert_type:

Type of alert (‘process_event’, ‘ioc_result’, ...)

alert_uuid:

UUID of the alert

ip_v4_address:

IP v4 of the host that triggered the alert

ip_v6_address:

IP v6 of the host that triggered the alert

confidence:

confidence in the alert

severity:

severity of the alert

impact:

criticalness of the alert

activity:

description of the detected activity

threat:

name of the threat

files:

a list of mappings, each describing a file linked with the alert and containing the following fields:

md5:

the MD5 hash of the file

sha1:

the SHA1 hash of the file

task_uuid:

the UUID of the malscape task that analysed the file

score:

the score issued by malscape for this file

net.endpoint.get_alert_details(response_format)¶

Retrieve a the details of a specific alert

URL

/papi/net/endpoint/get_alert_details[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

event_time:

time of when the event happened in timezone (required)

alert_uuid:

UUID of the alert (required)

timezone:

Name of selected time zone

Contents of successful response

A list of mappings, containing the following fields:

access_key_id:

Identifier of license of sensor that detected the alert

subkey_id:

Identifier of subkey of sensor that detected the alert

event_time:

Time of the alert, in requested timezone.

alert_type:

Type of alert (‘process_event’, ‘ioc_result’, ...)

alert_uuid:

UUID of the alert

ip_v4_address:

IP v4 of the host that triggered the alert

ip_v6_address:

IP v6 of the host that triggered the alert

confidence:

confidence in the alert

severity:

severity of the alert

impact:

overall impact of the alert

activity:

description of the detected activity

threat:

description of the threat

vendor_name:

Vendor’s name of the reporting tool

tool_name:

Name of the reporting tool

tool_version:

Version of the reporting tool

hostname:

Name of the host on which the event happened

hostname:

Name of the Active Directory domain the host belongs to

workgroup:

Name of the Workgroup the host belongs to

netbios_name:

Netbios name of the host on which the event happened

Mappings for an alert of type ‘IOC result’:

ioc_uuid:

UUID of the IOC

ioc_source:

source of the IOC

ioc_source:

source of the IOC

ioc_matched:

if the IOC matches

match_confidence:

confidence in the IOC match

check_time_start:

time when the IOC check has been started

ioc_task_uuid:

UUID of the task associated with the IOC

ioc_score:

score of the IOC

Mappings for an alert of type ‘process event’:

process_username:

username the process was running from

process_image_name:

name of the image that created the process

parent_process_username:

username the parent process was running from

parent_process_image_name:

name of the image that created the parent process

process_id:

pid of the process

parent_process_id:

pid of the parent process

files:

a list of mappings, each describing a file linked with the alert and containing the following fields:

md5:

the MD5 hash of the file

sha1:

the SHA1 hash of the file

task_uuid:

the UUID of the malscape task that analysed the file

score:

the score issued by malscape for this file

Mail¶

Mail Processing States:

RECEIVED: The email has been received by the sensor.

LOCAL_ANALYSIS: Local sensor analysis has been completed on the message.

MALSCAPE_ANALYSIS: All attachments and URLs have been uploaded to Lastline Analyst API.

DELIVERY: The message is being delivered to the next hop or sent to a quarantine server.

DONE: The message is done being processed.

UNKNOWN: The mail processing state is unknown.

Mail Analysis Statuses:

COMPLETE: The message went through complete processing.

FAIL_OPEN_ANALYSIS: Prefilter backlog caused message to skip being analyzed.

FAIL_OPEN_ANALYSIS_QUEUE_FULL: The mail message analysis queue is full.

FAIL_OPEN_MALSCAPE: Malscape was unreachable.

FAIL_OPEN_PROCESSING_TIME: The overall processing time for the mail message was too high.

UNKNOWN: The mail analysis status is unknown.

Mail Delivery Outcomes:

NEXT_HOP: There was an attempt to deliver the mail message to the next normal hop.

QUARANTINE: The mail message was sent to a quarantine server.

BOUNCE: The sender of the mail message was notified of the delivery.

UNKNOWN: The mail delivery outcome is unknown.

Method Index¶

get_mail_attachments():

Get informations about mail attachments
get_unique_mail_attachments():

Get informations about unique mail attachments
get_mail_attachment_stats():

Get statistics about mail attachments
get_mail_urls():

Get informations about urls in mails
get_unique_mail_urls():

Get informations about unique urls in mails
get_mail_url_stats():

Get statistics about urls in mails
get_mail_messages():

Get informations about mail messages
get_mail_message():

Get informations about a specific mail message
get_mail_messages_malware():

Get statistics on bad mail messages by malware
get_mail_messages_malware_priority():

Get statistics on bad mail messages by malware and priority level
get_mail_messages_stats():

Get statistics on bad mail message over time
get_mail_processing_log():

Get a list of the processed logs of a mail message
get_mail_delivery_log():

Get a list of delivery logs of a mail message
get_mail_message_headers():

Get the headers of a mail message
get_mail_detections():

Get detection information for a mail message

Method Documentation¶

net.mail.get_mail_attachments(response_format)¶

Get information about mail attachments

On Premise Availability

This method is available on Lastline Enterprise On-Premise version 7.1 or above.

URL

/papi/net/mail/attachments[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_time:

Get mail attachments after this time (required)

end_time:

Get mail attachments before this time (required)

timezone:

Name of selected time zone

Appliance selection:

key:

access_key[:subkey]: Get mail attachments detected by sensors with this key

key_id:

Get mail attachments detected by sensors with this key

subkey_id:

Get mail attachments detected by sensors with this subkey (provide together with key_id in alternative to key).

Sorting and pagination:

orderby:

Sort results based on this parameter. Can be one of:

score [ASC|DESC] to sort by score of mail attachment date [ASC|DESC] to sort by time of reception of the mail message containing the attachment ts [ASC|DESC] to sort by time of registration in the DB of the mail message containing the attachment

max_results:

Limit to this many results

offset_results:

Skip the first offset_results results.

Filters:

mail_message_id:

Select mail attachment from mail messages with this id

recipient:

Filter on mail attachments from mail messages whose recipient contains this string (available for Lastline Enterprise On-Premise versions >= 7.5)

subject:

Filter on mail attachments from mail messages whose subject contains this string (available for Lastline Enterprise On-Premise versions >= 7.5)

sender:

Filter on mail attachments from mail messages with this sender (available for Lastline Enterprise On-Premise versions >= 7.5)

min_score:

Select mail attachments scoring at least this value (0-100)

Note: If account does not have the CAN_VIEW_BENIGN_EMAILS permission,

then a minimum score filter of 30 (suspicious) is automatically applied to all requests (from Lastline Enterprise On-Premises release 7.18).

md5:

Select mail attachments having these md5s

task_uuid:

Select mail attachments analyzed in these analysis tasks

filetype

Select mail attachments belonging to these filetypes

action:

Select mail attachments on which this action was applied (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

WARN

LOG

TEST

message_action:

Select mail attachments on whose mail messages this action was applied (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

LOG

content_action:

Select mail attachments from mail messages where on at least one of its content this action was applied (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

WARN

LOG

TEST

blocked:

3-way boolean value. Set to True to filter on mail attachments that have either been blocked or whose mail messages were blocked. Set to False to filter on mail attachments that were not blocked and whose mail messages were not blocked. (available for Lastline Enterprise On-Premise versions >= 7.5.1)

analysis_task_typed_tags:

Serialized JSON encoded sequence of Analysis Task Typed Tags. Each Typed Tag is a sequence of 2 strings for the typed tag’s type and value.

e.g. ‘[[“av_family”, “locky”], [“av_class”, “ransomware”]]’

(available for Lastline Enterprise On-Premise versions >= 7.18)

include_typed_tags:

Include the list of Analysis Task Typed Tags with each Mail Attachment given a list of Analysis Task Typed Tag Types that should be included.

e.g. ‘av_family,av_class’ would return a list of Typed Tags that fit the criteria of only having a Typed Tag Type’s of “av_family” and “av_class”.

(available for Lastline Enterprise On-Premise versions >= 7.18)

mail_processing_state:

Restrict to mail messages that have a processing state that is in this comma separated list.

e.g. ‘LOCAL_ANALYSIS,MALSCAPE_ANALYSIS’ would return a list of mail attachments that fit the criteria of currently being analyzed.

(available for Lastline Email Defender On-Premises version 8.4 or above)

mail_analysis_status:

Restrict to mail messages that have an analysis status that is in this comma separated list.

e.g. ‘COMPLETE,UNKNOWN’ would return a list of mail attachments that fit the criteria of either being processed or there being no status information at all.

(available for Lastline Email Defender On-Premises version 8.4 or above)

mail_delivery_outcome:

Restrict to mail messages that have a delivery outcome that is in this comma separated list.

e.g. ‘BOUNCE,QUARANTINE’ would return a list of mail attachments that fit the criteria of either sent to a bounce server or quarantine server.

(available for Lastline Email Defender On-Premises version 8.4 or above)

lastline_mail_uuid:

Restrict to mail messages that have an llmail generated UUID that is in this comma separated list.

e.g. ‘902540c5a53f4c2a9a0e5f6eece3d8e2,85be90265ead401ba0c5e5c99eff8c57’ would return a list of mail messages that are associated with those specific UUIDs.

(available for Lastline Email Defender On-Premises version 8.4 or above)

Contents of successful response

A list of dictionaries with the following fields:

mail_message_id:

Identifier of the mail message containing this attachment (available for Lastline Enterprise On-Premise versions >= 7.5)

access_key_id

Identifier of license of sensor that detected the mail attachment

subkey_id:

Identifier of subkey of sensor that detected the mail attachment

time:

Date of reception of the mail message containing the mail attachment (extracted from the received mail message), in requested timezone

message_id:

Identifier of the mail message (extracted from the message itself)

timestamp:

Timestamp of the registration of the mail message in the DB, in requested timezone

file_name:

Name of the mail attachment

file_type:

File type of the mail attachment: detailed string

file_size:

Size of the mail attachment, in bytes

md5:

MD5 hash of mail attachment

sha1:

SHA-1 hash of mail attachment

task_uuid:

Lastline Engine task UUID

score:

Lastline score for mail attachment (0-100)

llfiletype:

File type mail attachment: high level category (e.g., Executable, Document, Java, Pdf)

sender:

Sender of the mail contaning the attachment

recipient:

Recipient of the mail containing the attachment

subject:

Subject of the mail containing the attachment

action:

Action taken on this attachment (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

WARN

LOG

TEST

message_action:

Action taken on the mail containing the attachment (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

LOG

typed_tags:

A sequence of Analysis Task Typed Tags: each Typed Tag is a sequence of two strings for the Typed Tag’s type and value.

e.g. [[“av_family”, “locky”], [“av_class”, “ransomware”]]

(available for Lastline Email Defender On-Premises version 8.1 or above)

appliance_uuid:

The appliance on which the attachment was seen.

Legacy API

This method replaces the ‘query_mail_attachments’ of the legacy Lastline API

net.mail.get_unique_mail_attachments(response_format)¶

Get informations about unique mail attachments

On Premise Availability

This method is available on Lastline Enterprise On-Premise version 7.1 or above.

URL

/papi/net/mail/unique_attachments[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_time:

Get mail attachments after this time (required)

end_time:

Get mail attachments before this time (required)

timezone:

Name of selected time zone

Appliance selection:

key:

access_key[:subkey]: Get mail attachments detected by sensors with this key

key_id:

Get mail attachments detected by sensors with this key

subkey_id:

Get mail attachments detected by sensors with this subkey (provide together with key_id in alternative to key).

Sorting and pagination:

orderby:

Sort results based on this parameter. Can be one of:

score [ASC|DESC] to sort by score of mail attachment date [ASC|DESC] to sort by time of reception of the mail message containing the attachment ts [ASC|DESC] to sort by time of registration in the DB of the mail message containing the attachment

max_results:

Limit to this many results

offset_results:

Skip the first offset_results results.

Filters:

mail_message_id:

Select mail attachment from mail messages with this id

recipient:

Filter on mail attachments from mail messages whose recipient contains this string (available for Lastline Enterprise On-Premise versions >= 7.5)

subject:

Filter on mail attachments from mail messages whose subject contains this string (available for Lastline Enterprise On-Premise versions >= 7.5)

sender:

Filter on mail attachments from mail messages with this sender (available for Lastline Enterprise On-Premise versions >= 7.5)

min_score:

Select mail attachments scoring at least this value (0-100)

Note: If account does not have the CAN_VIEW_BENIGN_EMAILS permission,

then a minimum score filter of 30 (suspicious) is automatically applied to all requests (from Lastline Enterprise On-Premises release 7.18).

md5:

Select mail attachments with these md5 sums

task_uuid:

Select mail attachments analyzed in these analysis tasks

filetype

Select mail attachments belonging to these filetypes

action:

Select mail attachments on which this action was applied (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

WARN

LOG

TEST

message_action:

Select mail attachments on whose mail messages this action was applied (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

LOG

content_action:

Select mail attachments from mail messages where on at least one of its content this action was applied (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

WARN

LOG

TEST

blocked:

3-way boolean value. Set to True to filter on mail attachments that have either been blocked or whose mail messages were blocked. Set to False to filter on mail attachments that were not blocked and whose mail messages were not blocked. (available for Lastline Enterprise On-Premise versions >= 7.5.1)

analysis_task_typed_tags:

Serialized JSON encoded sequence of Analysis Task Typed Tags. Each Typed Tag is a sequence of 2 strings for the typed tag’s type and value.

e.g. ‘[[“av_family”, “locky”], [“av_class”, “ransomware”]]’

(available for Lastline Enterprise On-Premise versions >= 7.18)

include_typed_tags:

Include the list of Analysis Task Typed Tags with each Unique Mail Attachment given a list of Analysis Task Typed Tag Types that should be included.

e.g. ‘av_family,av_class’ would return a list of Typed Tags that fit the criteria of only having a Typed Tag Type’s of “av_family” and “av_class”.

(available for Lastline Enterprise On-Premise versions >= 7.18)

mail_processing_state:

Restrict to mail messages that have a processing state that is in this comma separated list.

e.g. ‘LOCAL_ANALYSIS,MALSCAPE_ANALYSIS’ would return a list of mail attachments that fit the criteria of currently being analyzed.

(available for Lastline Email Defender On-Premises version 8.4 or above)

mail_analysis_status:

Restrict to mail messages that have an analysis status that is in this comma separated list.

e.g. ‘COMPLETE,UNKNOWN’ would return a list of mail attachments that fit the criteria of either being processed or there being no status information at all.

(available for Lastline Email Defender On-Premises version 8.4 or above)

mail_delivery_outcome:

Restrict to mail messages that have a delivery outcome that is in this comma separated list.

e.g. ‘BOUNCE,QUARANTINE’ would return a list of mail attachments that fit the criteria of either sent to a bounce server or quarantine server.

(available for Lastline Email Defender On-Premises version 8.4 or above)

lastline_mail_uuid:

Restrict to mail messages that have an llmail generated UUID that is in this comma separated list.

e.g. ‘902540c5a53f4c2a9a0e5f6eece3d8e2,85be90265ead401ba0c5e5c99eff8c57’ would return a list of mail messages that are associated with those specific UUIDs.

(available for Lastline Email Defender On-Premises version 8.4 or above)

Contents of successful response

A list of dictionaries with the following fields:

occurrences:

Number of occurrences of this attachment

first_seen:

Timestamp of the registration in the DB of the first mail containing this attachment in requested timezone

last_seen:

Timestamp of the registration in the DB of the last mail contaning this attachment in requested timezone,

num_subjects:

Number of different subject strings used in mail messages containing this attachment

num_recipients:

Number of distinct recipients that received mail messages contaning thsi attachement

num_senders:

Number of distinct senders that sent mail messages containing this attachment

num_sensors:

Number of sensors that detected this mail attachment

num_file_names:

Number of different file names for this attachment

file_name:

Name of the mail attachment

file_type:

File type of the mail attachment: detailed string

file_size:

Size of the mail attachment, in bytes

md5:

MD5 hash of mail attachment

sha1:

SHA-1 hash of mail attachment

task_uuid:

Lastline Engine task UUID

score:

Lastline score for mail attachment (0-100)

llfiletype:

File type mail attachment: high level category (e.g., Executable, Document, Java, Pdf)

sender:

Sender of the mail contaning the attachment

recipient:

Recipient of the mail containing the attachment

subject:

Subject of the mail containing the attachment

action:

Action taken on this attachment (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

WARN

LOG

TEST

message_action:

Action taken on the mail containing the attachment (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

LOG

typed_tags:

A sequence of Analysis Task Typed Tags: each Typed Tag is a sequence of two strings for the Typed Tag’s type and value.

e.g. [[“av_family”, “locky”], [“av_class”, “ransomware”]]

(available for Lastline Email Defender On-Premises version 8.1 or above)

Legacy API

This method replaces the ‘query_attached_files’ of the legacy Lastline API

net.mail.get_mail_attachment_stats(response_format)¶

Get statistics about mail attachments

On Premise Availability

This method is available on Lastline Enterprise On-Premise version 7.1 or above.

URL

/papi/net/mail/attachment_stats[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_date:

Get mail attachments after this date (required)

end_date:

Get mail attachments before this date (required)

timezone:

Name of selected time zone

Appliance selection:

key:

access_key[:subkey]: Get mail attachments detected by sensors with this key

key_id:

Get mail attachments detected by sensors with this key

subkey_id:

Get mail attachments detected by sensors with this subkey (provide together with key_id in alternative to key).

Filters:

mail_message_id:

Select mail attachment from mail messages with this id

recipient:

Filter on mail attachments from mail messages whose recipient contains this string (available for Lastline Enterprise On-Premise versions >= 7.5)

subject:

Filter on mail attachments from mail messages whose subject contains this string (available for Lastline Enterprise On-Premise versions >= 7.5)

sender:

Filter on mail attachments from mail messages with this sender (available for Lastline Enterprise On-Premise versions >= 7.5)

min_score:

Select mail attachments scoring at least this value (0-100)

Note: If account does not have the CAN_VIEW_BENIGN_EMAILS permission,

then a minimum score filter of 30 (suspicious) is automatically applied to all requests (from Lastline Enterprise On-Premises release 7.18).

md5:

Select mail attachments with these md5 sums

task_uuid:

Select mail attachments analyzed in these analysis tasks

action:

Select mail attachments on which this action was applied (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

WARN

LOG

TEST

message_action:

Select mail attachments on whose mail messages this action was applied (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

LOG

content_action:

Select mail attachments from mail messages where on at least one of its content this action was applied (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

WARN

LOG

TEST

blocked:

3-way boolean value. Set to True to filter on mail attachments that have either been blocked or whose mail messages were blocked. Set to False to filter on mail attachments that were not blocked and whose mail messages were not blocked. (available for Lastline Enterprise On-Premise versions >= 7.5.1)

analysis_task_typed_tags:

Serialized JSON encoded sequence of Analysis Task Typed Tags. Each Typed Tag is a sequence of 2 strings for the typed tag’s type and value.

e.g. ‘[[“av_family”, “locky”], [“av_class”, “ransomware”]]’

(available for Lastline Enterprise On-Premise versions >= 7.18)

mail_processing_state:

Restrict to mail messages that have a processing state that is in this comma separated list.

e.g. ‘LOCAL_ANALYSIS,MALSCAPE_ANALYSIS’ would return a list of mail attachments that fit the criteria of currently being analyzed.

(available for Lastline Email Defender On-Premises version 8.4 or above)

mail_analysis_status:

Restrict to mail messages that have an analysis status that is in this comma separated list.

e.g. ‘COMPLETE,UNKNOWN’ would return a list of mail attachments that fit the criteria of either being processed or there being no status information at all.

(available for Lastline Email Defender On-Premises version 8.4 or above)

mail_delivery_outcome:

Restrict to mail messages that have a delivery outcome that is in this comma separated list.

e.g. ‘BOUNCE,QUARANTINE’ would return a list of mail attachments that fit the criteria of either sent to a bounce server or quarantine server.

(available for Lastline Email Defender On-Premises version 8.4 or above)

lastline_mail_uuid:

Restrict to mail messages that have an llmail generated UUID that is in this comma separated list.

e.g. ‘902540c5a53f4c2a9a0e5f6eece3d8e2,85be90265ead401ba0c5e5c99eff8c57’ would return a list of mail messages that are associated with those specific UUIDs.

(available for Lastline Email Defender On-Premises version 8.4 or above)

Contents of successful response

A list of dictionaries containing the fields below. Element are grouped by start_date and file_type

file_type:

File type of the mail attachment

start_date:

Date of the reception of the mail attachment for this group, in requested timezone

total_files:

Number of mail attachments in this group

distinct_files:

Number of distinct mail attachments in this group

max_score:

Maximum of all the mail attachments score in this group

Legacy API

This method replaces the ‘query_mail_attachment_stats’ of the legacy Lastline API

net.mail.get_mail_urls(response_format)¶

Get informations about mail urls

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >= 7.5

URL

/papi/net/mail/urls[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET PARAMETERS

Time range selection:

start_time:

Get mail urls after this time (required)

end_time:

Get mail urls before this time (required)

timezone:

Name of selected time zone

Appliance selection:

key:

access_key[:subkey]: Get mail urls detected by sensors with this key

key_id:

Get mail urls detected by sensors with this key

subkey_id:

Get mail urls detected by sensors with this subkey (provide together with key_id in alternative to key).

Sorting and pagination:

orderby:

Sort results based on this parameter. Can be one of:

score [ASC|DESC] to sort by score of mail url date [ASC|DESC] to sort by time of reception of the mail message containing the url ts [ASC|DESC] to sort by time of registration in the DB of the mail message containing the url

max_results:

Limit to this many results

offset_results:

Skip the first offset_results results.

Filters:

mail_message_id:

Select mail urls from mail messages with this id

recipient:

Filter on mail urls from mail messages whose recipient contains this string

subject:

Filter on mail urls from mail messages whose subject contains this string

sender:

Filter on mail urls from mail messages with this sender

min_score:

Select mail urls scoring at least this value (0-100)

Note: If account does not have the CAN_VIEW_BENIGN_EMAILS permission,

then a minimum score filter of 30 (suspicious) is automatically applied to all requests (from Lastline Enterprise On-Premises release 7.18).

md5:

Select mail urls having these md5s

task_uuid:

Select mail urls analyzed in these analysis tasks

hostname:

Filter on urls with this hostname

action:

Select mail urls on which this action was applied (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

WARN

LOG

TEST

message_action:

Select mail urls on whose mail messages this action was applied (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

LOG

content_action:

Select mail urls from mail messages where on at least one of its content this action was applied (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

WARN

LOG

TEST

blocked:

3-way boolean value. Set to True to filter on mail urls that have either been blocked or whose mail messages were blocked. Set to False to filter on mail urls that were not blocked and whose mail messages were not blocked. (available for Lastline Enterprise On-Premise versions >= 7.5.1)

analysis_task_typed_tags:

Serialized JSON encoded sequence of Analysis Task Typed Tags. Each Typed Tag is a sequence of 2 strings for the typed tag’s type and value.

e.g. ‘[[“av_family”, “locky”], [“av_class”, “ransomware”]]’

(available for Lastline Enterprise On-Premise versions >= 7.18)

include_typed_tags:

Include the list of Analysis Task Typed Tags with each Mail URL given a list of Analysis Task Typed Tag Types that should be included.

e.g. ‘av_family,av_class’ would return a list of Typed Tags that fit the criteria of only having a Typed Tag Type’s of “av_family” and “av_class”.

(available for Lastline Enterprise On-Premise versions >= 7.18)

mail_processing_state:

Restrict to mail messages that have a processing state that is in this comma separated list.

e.g. ‘LOCAL_ANALYSIS,MALSCAPE_ANALYSIS’ would return a list of mail URLs that fit the criteria of currently being analyzed.

(available for Lastline Email Defender On-Premises version 8.4 or above)

mail_analysis_status:

Restrict to mail messages that have an analysis status that is in this comma separated list.

e.g. ‘COMPLETE,UNKNOWN’ would return a list of mail URLs that fit the criteria of either being processed or there being no status information at all.

(available for Lastline Email Defender On-Premises version 8.4 or above)

mail_delivery_outcome:

Restrict to mail messages that have a delivery outcome that is in this comma separated list.

e.g. ‘BOUNCE,QUARANTINE’ would return a list of mail URLs that fit the criteria of either sent to a bounce server or quarantine server.

(available for Lastline Email Defender On-Premises version 8.4 or above)

lastline_mail_uuid:

Restrict to mail messages that have an llmail generated UUID that is in this comma separated list.

e.g. ‘902540c5a53f4c2a9a0e5f6eece3d8e2,85be90265ead401ba0c5e5c99eff8c57’ would return a list of mail messages that are associated with those specific UUIDs.

(available for Lastline Email Defender On-Premises version 8.4 or above)

Contents of successful response

A list of dictionaries with the following fields:

mail_message_id:

Identifier of the mail message containing this url

access_key_id:

Identifier of license of sensor that detected the mail url

subkey_id:

Identifier of subkey of sensor that detected the mail url

time:

Date of reception of the mail message containing the mail url (extracted from the received mail message), in requested timezone

date:

Same as time above

message_id:

Identifier of the mail message (extracted from the message itself)

timestamp:

Timestamp of the registration of the mail message in the DB, in requested timezone

url:

Human readable version of the malicious url found in the mail message

raw_url:

Raw version of the malicious url found in the mail message

md5:

MD5 hash of mail url

task_uuid:

Lastline Engine task UUID

score:

Lastline score for mail url (0-100)

sender:

Sender of the mail contaning the url

recipient:

Recipient of the mail containing the url

subject:

Subject of the mail containing the url

action:

Action taken on this mail url (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

WARN

LOG

TEST

message_action:

Action taken on the mail containing the url (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

LOG

typed_tags:

A sequence of Analysis Task Typed Tags: each Typed Tag is a sequence of two strings for the Typed Tag’s type and value.

e.g. [[“av_family”, “locky”], [“av_class”, “ransomware”]]

(available for Lastline Email Defender On-Premises version 8.1 or above)

appliance_uuid:

The appliance on which the attachment was seen.

net.mail.get_unique_mail_urls(response_format)¶

Get informations about unique mail urls

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >= 7.5

URL

/papi/net/mail/unique_urls[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_time:

Get mail urls after this time (required)

end_time:

Get mail urls before this time (required)

timezone:

Name of selected time zone

Appliance selection:

key:

access_key[:subkey]: Get mail urls detected by sensors with this key

key_id:

Get mail urls detected by sensors with this key

subkey_id:

Get mail urls detected by sensors with this subkey (provide together with key_id in alternative to key).

Sorting and pagination:

orderby:

Sort results based on this parameter. Can be one of:

score [ASC|DESC] to sort by score of mail url date [ASC|DESC] to sort by time of reception of the mail message containing the url ts [ASC|DESC] to sort by time of registration in the DB of the mail message containing the url

max_results:

Limit to this many results

offset_results:

Skip the first offset_results results.

Filters:

mail_message_id:

Select mail urls from mail messages with this id

recipient:

Filter on mail urls from mail messages whose recipient contains this string

subject:

Filter on mail urls from mail messages whose subject contains this string

sender:

Filter on mail urls from mail messages with this sender

min_score:

Select mail urls scoring at least this value (0-100)

Note: If account does not have the CAN_VIEW_BENIGN_EMAILS permission,

then a minimum score filter of 30 (suspicious) is automatically applied to all requests (from Lastline Enterprise On-Premises release 7.18).

md5:

Select mail urls with these md5 sums

task_uuid:

Select mail urls analyzed in these analysis tasks

hostname:

Filter on urls with this hostname

action:

Select mail urls on which this action was applied (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

WARN

LOG

TEST

message_action:

Select mail urls on whose mail messages this action was applied (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

LOG

content_action:

Select mail urls from mail messages where on at least one of its content this action was applied (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

WARN

LOG

TEST

blocked:

3-way boolean value. Set to True to filter on mail urls that have either been blocked or whose mail messages were blocked. Set to False to filter on mail urls that were not blocked and whose mail messages were not blocked. (available for Lastline Enterprise On-Premise versions >= 7.5.1)

analysis_task_typed_tags:

Serialized JSON encoded sequence of Analysis Task Typed Tags. Each Typed Tag is a sequence of 2 strings for the typed tag’s type and value.

e.g. ‘[[“av_family”, “locky”], [“av_class”, “ransomware”]]’

(available for Lastline Enterprise On-Premise versions >= 7.18)

include_typed_tags:

Include the list of Analysis Task Typed Tags with each Unique Mail URL given a list of Analysis Task Typed Tag Types that should be included.

e.g. ‘av_family,av_class’ would return a list of Typed Tags that fit the criteria of only having a Typed Tag Type’s of “av_family” and “av_class”.

(available for Lastline Enterprise On-Premise versions >= 7.18)

mail_processing_state:

Restrict to mail messages that have a processing state that is in this comma separated list.

e.g. ‘LOCAL_ANALYSIS,MALSCAPE_ANALYSIS’ would return a list of mail URLs that fit the criteria of currently being analyzed.

(available for Lastline Email Defender On-Premises version 8.4 or above)

mail_analysis_status:

Restrict to mail messages that have an analysis status that is in this comma separated list.

e.g. ‘COMPLETE,UNKNOWN’ would return a list of mail URLs that fit the criteria of either being processed or there being no status information at all.

(available for Lastline Email Defender On-Premises version 8.4 or above)

mail_delivery_outcome:

Restrict to mail messages that have a delivery outcome that is in this comma separated list.

e.g. ‘BOUNCE,QUARANTINE’ would return a list of mail URLs that fit the criteria of either sent to a bounce server or quarantine server.

(available for Lastline Email Defender On-Premises version 8.4 or above)

lastline_mail_uuid:

Restrict to mail messages that have an llmail generated UUID that is in this comma separated list.

e.g. ‘902540c5a53f4c2a9a0e5f6eece3d8e2,85be90265ead401ba0c5e5c99eff8c57’ would return a list of mail messages that are associated with those specific UUIDs.

(available for Lastline Email Defender On-Premises version 8.4 or above)

Contents of successful response

A list of dictionaries with the following fields:

occurrences:

Number of occurrences of this url

first_seen:

Timestamp of the registration in the DB of the first mail containing this url in requested timezone

last_seen:

Timestamp of the registration in the DB of the last mail contaning this url in requested timezone

num_subjects:

Number of different subject strings used in mail messages containing this url

num_recipients:

Number of distinct recipients that received mail messages contaning thsi url

num_senders:

Number of distinct senders that sent mail messages containing this url

num_sensors:

Number of sensors that detected this mail url

num_url_names:

Number of different url names that point to the same website

url

Human readable version of one of the url names pointing to the same website

raw_url:

Raw version of one of the url names pointing to the same website

md5:

MD5 hash of mail url

task_uuid:

Lastline Engine task UUID

score:

Lastline score for mail url (0-100)

sender:

Sender of the mail contaning the url

recipient:

Recipient of the mail containing the url

subject:

Subject of the mail containing the url

action:

Action taken on this mail url (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

WARN

LOG

TEST

message_action:

Action taken on the mail containing the url (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

LOG

typed_tags:

A sequence of Analysis Task Typed Tags: each Typed Tag is a sequence of two strings for the Typed Tag’s type and value.

e.g. [[“av_family”, “locky”], [“av_class”, “ransomware”]]

(available for Lastline Email Defender On-Premises version 8.1 or above)

net.mail.get_mail_url_stats(response_format)¶

Get statistics about mail urls

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >= 7.5

URL

/papi/net/mail/url_stats[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_date:

Get mail urls after this date (required)

end_date:

Get mail urls before this date (required)

timezone:

Name of selected time zone

Appliance selection:

key:

access_key[:subkey]: Get mail urls detected by sensors with this key

key_id:

Get mail urls detected by sensors with this key

subkey_id:

Get mail urls detected by sensors with this subkey (provide together with key_id in alternative to key).

Filters:

mail_message_id:

Select mail urls from mail messages with this id

recipient:

Filter on mail urls from mail messages whose recipient contains this string

subject:

Filter on mail urls from mail messages whose subject contains this string

sender:

Filter on mail urls from mail messages with this sender

min_score:

Select mail urls scoring at least this value (0-100)

Note: If account does not have the CAN_VIEW_BENIGN_EMAILS permission,

then a minimum score filter of 30 (suspicious) is automatically applied to all requests (from Lastline Enterprise On-Premises release 7.18).

md5:

Select mail urls with these md5 sums

task_uuid:

Select mail urls analyzed in these analysis tasks

hostname:

Filter on urls with this hostname

action:

Select mail url on which this action was applied (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

WARN

LOG

TEST

message_action:

Select mail urls on whose mail messages this action was applied (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

LOG

content_action:

Select mail urls from mail messages where on at least one of its content this action was applied (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

WARN

LOG

TEST

blocked:

3-way boolean value. Set to True to filter on mail urls that have either been blocked or whose mail messages were blocked. Set to False to filter on mail urls that were not blocked and whose mail messages were not blocked. (available for Lastline Enterprise On-Premise versions >= 7.5.1)

analysis_task_typed_tags:

Serialized JSON encoded sequence of Analysis Task Typed Tags. Each Typed Tag is a sequence of 2 strings for the typed tag’s type and value.

e.g. ‘[[“av_family”, “locky”], [“av_class”, “ransomware”]]’

(available for Lastline Enterprise On-Premise versions >= 7.18)

mail_processing_state:

Restrict to mail messages that have a processing state that is in this comma separated list.

e.g. ‘LOCAL_ANALYSIS,MALSCAPE_ANALYSIS’ would return a list of mail URLs that fit the criteria of currently being analyzed.

(available for Lastline Email Defender On-Premises version 8.4 or above)

mail_analysis_status:

Restrict to mail messages that have an analysis status that is in this comma separated list.

e.g. ‘COMPLETE,UNKNOWN’ would return a list of mail URLs that fit the criteria of either being processed or there being no status information at all.

(available for Lastline Email Defender On-Premises version 8.4 or above)

mail_delivery_outcome:

Restrict to mail messages that have a delivery outcome that is in this comma separated list.

e.g. ‘BOUNCE,QUARANTINE’ would return a list of mail URLs that fit the criteria of either sent to a bounce server or quarantine server.

(available for Lastline Email Defender On-Premises version 8.4 or above)

lastline_mail_uuid:

Restrict to mail messages that have an llmail generated UUID that is in this comma separated list.

e.g. ‘902540c5a53f4c2a9a0e5f6eece3d8e2,85be90265ead401ba0c5e5c99eff8c57’ would return a list of mail messages that are associated with those specific UUIDs.

(available for Lastline Email Defender On-Premises version 8.4 or above)

Contents of successful response

A list of dictionaries containing the fields below. Element are grouped by start_date

start_date:

Date of the reception of the mail url for this group, in requested timezone

total_urls:

Number of mail urls in this group

distinct_url:

Number of distinct mail urls in this group

max_score:

Maximum of all the mail urls score in this group

net.mail.get_mail_messages(response_format)¶

Get informations about mail messages

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >= 7.5

URL

/papi/net/mail/messages[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_time:

Get mail messages after this time (required)

end_time:

Get mail messages before this time (required)

timezone:

Name of selected time zone

Appliance selection:

key:

access_key[:subkey]: Get mail messagess detected by sensors with this key

key_id:

Get mail messages detected by sensors with this key

subkey_id:

Get mail messages detected by sensors with this subkey (provide together with key_id in alternative to key).

Sorting and pagination:

orderby:

Sort results based on this parameter. Can be one of:

date [ASC|DESC] to sort by time of reception of the mail message containing ts [ASC|DESC] to sort by time of registration in the DB of the mail message size [ASC|DESC] to sort by size of the mail message impact [ASC|DESC] to sort by impact threat_name [ASC|DESC] to sort by the name of the threat related to this mail message threat_class_name [ASC|DESC] to sort by the name of the threat class related to this mail message sender [ASC|DESC] to sort by sender of the mail message recipient [ASC|DESC] to sort by recipient of the mail message subject [ASC|DESC] to sort by subject of the mail message

max_results:

Limit to this many results

offset_results:

Skip the first offset_results results.

Filters:

mail_message_id:

Filter on mail messages with this identifier

recipient:

Filter on mail messages whose recipient contains this string

subject:

Filter on mail messages whose subject contains this string

sender:

Filter on mail messages with this sender

relevant_content:

3-value boolean, set to True to filter on mail messages containing relevant urls/attachments, False to exclude them, if not set return all

min_impact:

Restrict to mail messages with level or impact greater or equal than this value

Note: If account does not have the CAN_VIEW_BENIGN_EMAILS permission,

then a minimum score filter of 30 (suspicious) is automatically applied to all requests (from Lastline Enterprise On-Premises release 7.18).

priority:

Restrict to mail messages with this level of impact (“HIGH”, “MEDIUM”, “LOW”)

threat:

Restrict to mail messages related to this threat

threat_class:

Restrict to mail messages related to this threat class

message_action:

Select mail messages on which this action was applied (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

LOG

content_action:

Select mail messages having content (i.e., attachments or urls) on which this action was applied (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

WARN

LOG

TEST

blocked:

3-way boolean value. Set to True to filter on mail messages that have either been blocked or at least one of their content (i.e., attachment or url) was blocked. Set to False to filter on mail messages that were not blocked an whose content was not blocked (available for Lastline Enterprise On-Premise versions >= 7.5.1)

breach_uuid:

Restrict to mails that are part of this breach (available for customers with a Lastline Breach Defender license)

assigned_to:

Get only mail messages assigned to any of these accounts. The value “unassigned” can be used to get only mail messages that have not been assigned to anyone. This is a comma-separated list of accounts. (optional) (Lastline Email Defender On-Premises version 8.2 or above)

e.g. if the value is: “user@lastline.com,unassigned” it means we filter on

mail messages assigned to user@lastline.com OR that are unassigned.

mail_state:

Restrict to mail messages in these states. This is a comma-separates list of mail states. (Lastline Email Defender On-Premises version 8.2 or above)

e.g. if the value is: “OPEN,IN_PROGRESS” it means we filter on mail messages in

either the state of “Open” or “In Progress”

Possible values are:

OPEN

IN_PROGRESS

DONE

analysis_task_typed_tags:

Restrict to messages that have attachments and/or urls with these Analysis Task Typed Tags. Provide a serialized JSON encoded sequence of Typed Tags. Each Typed Tag is a sequence of two strings for the Typed Tag’s type and value.

e.g. ‘[[“av_family”, “locky”], [“av_class”, “ransomware”]]’

(available for Lastline Email Defender On-Premises version 8.3 or above)

include_typed_tags:

Include the list of Analysis Task Typed Tags with the messages given a list of Analysis Task Typed Tag Types that should be included.

e.g. ‘av_family,av_class’ would return a list of Typed Tags that fit the criteria of only having a Typed Tag Type’s of “av_family” and “av_class”.

(available for Lastline Email Defender On-Premises version 8.3 or above)

mail_processing_state:

Restrict to mail messages that have a processing state that is in this comma separated list.

e.g. ‘LOCAL_ANALYSIS,MALSCAPE_ANALYSIS’ would return a list of mail messages that fit the criteria of currently being analyzed.

(available for Lastline Email Defender On-Premises version 8.4 or above)

mail_analysis_status:

Restrict to mail messages that have an analysis status that is in this comma separated list.

e.g. ‘COMPLETE,UNKNOWN’ would return a list of mail messages that fit the criteria of either being processed or there being no status information at all.

(available for Lastline Email Defender On-Premises version 8.4 or above)

mail_delivery_outcome:

Restrict to mail messages that have a delivery outcome that is in this comma separated list.

e.g. ‘BOUNCE,QUARANTINE’ would return a list of mail messages that fit the criteria of either sent to a bounce server or quarantine server.

(available for Lastline Email Defender On-Premises version 8.4 or above)

lastline_mail_uuid:

Restrict to mail messages that have an llmail generated UUID that is in this comma separated list.

e.g. ‘902540c5a53f4c2a9a0e5f6eece3d8e2,85be90265ead401ba0c5e5c99eff8c57’ would return a list of mail messages that are associated with those specific UUIDs.

(available for Lastline Email Defender On-Premises version 8.4 or above)

Contents of successful response

A list of dictionaries with the following fields:

mail_message_id:

Identifier of the mail message

access_key_id

Identifier of license of sensor that detected the mail attachment

subkey_id:

Identifier of subkey of sensor that detected the mail attachment

date:

Date of reception of the mail message (extracted from the received mail message itself), in requested timezone

message_id:

Identifier of the mail message (extracted from the message itself) (available for Lastline Enterprise On-Premise versions >= 7.15)

timestamp:

Timestamp of the registration of the mail message in the DB, in requested timezone

size:

Size of the mail message

sender:

Sender of the mail message

recipient:

Recipient of the mail message

subject:

Subject of the mail message

threat:

Detected threat inside the mail message. Called “Malware” in Lastline Portal

threat_class:

Class of detected threat. Called “Malware Class” in Lastline Portal

attachments:

Number of attachments contained in this mail message

urls:

Number of urls contained in this mail message

impact:

Impact of the mail message (how bad the mail message is)

relevant_content:

Boolean, whether or not the mail message contains relevant urls/attachments

message_action:

Action taken on this mail message (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

LOG

content_action:

Most critical action taken on the content of this mail message (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

WARN

LOG

TEST

assigned_to:

The account the mail message is assigned to

mail_state:

The state the mail message is in Possible values are:

OPEN

IN_PROGRESS

DONE

typed_tags:

A sequence of Analysis Task Typed Tags: each Typed Tag is a sequence of two strings for the Typed Tag’s type and value.

e.g. [[“av_family”, “locky”], [“av_class”, “ransomware”]]

(available for Lastline Email Defender On-Premises version 8.3 or above)

mail_processing_state:

The state of the mail message.

The list of possible processing states are:

DELIVERY

DONE

LOCAL_ANALYSIS

MALSCAPE_ANALYSIS

RECEIVED

QUARANTINED

UNKNOWN

(available for Lastline Email Defender On-Premises version 8.4 or above)

mail_analysis_status:

The status corresponding to the analysis of the mail message.

The list of possible analysis statuses are:

COMPLETE

FAIL_OPEN_ANALYSIS_QUEUE_FULL

FAIL_OPEN_MALSCAPE

FAIL_OPEN_PROCESSING_TIME

UNKNOWN

(available for Lastline Email Defender On-Premises version 8.4 or above)

mail_delivery_outcome:

The outcome of the mail delivery.

The list of possible mail delivery outcomes are:

BOUNCE

NEXT_HOP

QUARANTINE

UNKNOWN

(available for Lastline Email Defender On-Premises version 8.4 or above)

lastline_mail_uuid:

Unique identifier of the mail message generated by llmail.

(available for Lastline Email Defender On-Premises version 8.4 or above)

last_upload_ts:

Timestamp of the last update of the mail message from the sensor.

(available for Lastline Email Defender On-Premises version 8.4 or above)

appliance_uuid:

The appliance on which this mail was seen.

net.mail.get_mail_message(response_format)¶

Get informations about a specific mail message

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >= 7.5

URL

/papi/net/mail/message[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

start_time:

Get mail messages after this time (required)

end_time:

Get mail messages before this time (required)

timezone:

Name of selected time zone

mail_message_id:

Filter on mail messages with this id

Field selection:

include_typed_tags:

Include the list of Analysis Task Typed Tags with the messages given a list of Analysis Task Typed Tag Types that should be included.

e.g. ‘av_family,av_class’ would return a list of Typed Tags that fit the criteria of only having a Typed Tag Type’s of “av_family” and “av_class”.

(available for Lastline Email Defender On-Premises version 8.3 or above)

Contents of successful response

A dictionary with the following fields:

mail_message_id:

Identifier of the mail message

access_key_id

Identifier of license of sensor that detected the mail attachment

subkey_id:

Identifier of subkey of sensor that detected the mail attachment

date:

Date of reception of the mail message (extracted from the received mail message itself), in requested timezone

message_id:

Identifier of the mail message (extracted from the message itself)

timestamp:

Timestamp of the registration of the mail message in the DB, in requested timezone

size:

Size of the mail message

sender:

Sender of the mail message

recipient:

Recipient of the mail message

subject:

Subject of the mail message

threat:

Detected threat inside the mail message. Called “Malware” in Lastline Portal

threat_class:

Class of detected threat. Called “Malware Class” in Lastline Portal

attachments:

Number of attachments contained in this mail message

urls:

Number of urls contained in this mail message

impact:

Impact of the mail message (how bad the mail message is)

relevant_content:

Boolean, whether or not the mail message contains relevant urls/attachments

message_action:

Action taken on this mail message (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

LOG

content_action:

Most critical action taken on the content of this mail message (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

WARN

LOG

TEST

breach_uuid:

Breach this mail is part of, if any. (available for customers with a Lastline Breach Defender license)

assigned_to:

The account the mail message is assigned to

mail_state:

The state the mail message is in Possible values are:

OPEN

IN_PROGRESS

DONE

typed_tags:

A sequence of Analysis Task Typed Tags: each Typed Tag is a sequence of two strings for the Typed Tag’s type and value.

e.g. [[“av_family”, “locky”], [“av_class”, “ransomware”]]

(available for Lastline Email Defender On-Premises version 8.3 or above)

mail_processing_state:

The state of the mail message.

The list of possible processing states are:

DELIVERY

DONE

LOCAL_ANALYSIS

MALSCAPE_ANALYSIS

RECEIVED

UNKNOWN

(available for Lastline Email Defender On-Premises version 8.4 or above)

mail_analysis_status:

The status corresponding to the analysis of the mail message.

The list of possible analysis statuses are:

COMPLETE

FAIL_OPEN_ANALYSIS_QUEUE_FULL

FAIL_OPEN_MALSCAPE

FAIL_OPEN_PROCESSING_TIME

UNKNOWN

(available for Lastline Email Defender On-Premises version 8.4 or above)

mail_delivery_outcome:

The outcome of the mail delivery.

The list of possible mail delivery outcomes are:

BOUNCE

NEXT_HOP

QUARANTINE

UNKNOWN

(available for Lastline Email Defender On-Premises version 8.4 or above)

lastline_mail_uuid:

Unique identifier of the mail message generated by llmail.

(available for Lastline Email Defender On-Premises version 8.4 or above)

last_upload_ts:

Timestamp of the last update of the mail message from the sensor.

(available for Lastline Email Defender On-Premises version 8.4 or above)

appliance_uuid:

The appliance on which this mail was seen.

net.mail.get_mail_messages_malware(response_format)¶

Get statistics on bad mail messages by malware

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >= 7.5

URL

/papi/net/mail/messages_malware[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_date:

Get mail messages after this date (required)

end_date:

Get mail messages before this date (required)

timezone:

Name of selected time zone

Appliance selection:

key:

access_key[:subkey]: Get mail messages detected by sensors with this key

key_id:

Get mail messages detected by sensors with this key

subkey_id:

Get mail messages detected by sensors with this subkey (provide together with key_id in alternative to key).

Filters:

recipient:

Filter on mail messages whose recipient contains this string

subject:

Filter on mail messages whose subject contains this string

sender:

Filter on mail messages with this sender

relevant_content:

3-value boolean, set to True to filter on mail messages containing relevant urls/attachments, False to exclude them, if not set return all

min_impact:

Restrict to mail messages with level or impact greater or equal than this value

Note: If account does not have the CAN_VIEW_BENIGN_EMAILS permission,

then a minimum impact filter of 30 (suspicious) is automatically applied to all requests (from Lastline Enterprise On-Premises release 7.18).

priority:

Restrict to mail messages with this level of impact (“HIGH”, “MEDIUM”, “LOW”)

threat:

Restrict to mail messages related to this threat

threat_class:

Restrict to mail messages related to this threat class

message_action:

Select mail messages on which this action was applied (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

LOG

content_action:

Select mail messages having content (i.e., attachments or urls) on which this action was applied (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

WARN

LOG

TEST

blocked:

3-way boolean value. Set to True to filter on mail messages that have either been blocked or at least one of their content (i.e., attachment or url) was blocked. Set to False to filter on mail messages that were not blocked an whose content was not blocked (available for Lastline Enterprise On-Premise versions >= 7.5.1)

assigned_to:

Get only mail messages assigned to any of these accounts. The value “unassigned” can be used to get only mail messages that have not been assigned to anyone. This is a comma-separated list of accounts. (optional) (Lastline Email Defender On-Premises version 8.2 or above)

e.g. if the value is: “user@lastline.com,unassigned” it means we filter on

mail messages assigned to user@lastline.com OR that are unassigned.

mail_state:

Restrict to mail messages in these states. This is a comma-separates list of mail states. (Lastline Email Defender On-Premises version 8.2 or above)

e.g. if the value is: “OPEN,IN_PROGRESS” it means we filter on mail messages in

either the state of “Open” or “In Progress”

Possible values are:

OPEN

IN_PROGRESS

DONE

analysis_task_typed_tags:

Restrict to messages that have attachments and/or urls with these Analysis Task Typed Tags. Provide a serialized JSON encoded sequence of Typed Tags. Each Typed Tag is a sequence of two strings for the Typed Tag’s type and value.

e.g. ‘[[“av_family”, “locky”], [“av_class”, “ransomware”]]’

(available for Lastline Email Defender On-Premises version 8.3 or above)

mail_processing_state:

Restrict to mail messages that have a processing state that is in this comma separated list.

e.g. ‘LOCAL_ANALYSIS,MALSCAPE_ANALYSIS’ would return a list of mail messages that fit the criteria of currently being analyzed.

The list of possible states can be found in the Sphinx documentation

(available for Lastline Email Defender On-Premises version 8.4 or above)

mail_analysis_status:

Restrict to mail messages that have an analysis status that is in this comma separated list.

e.g. ‘COMPLETE,UNKNOWN’ would return a list of mail messages that fit the criteria of either being processed or there being no status information at all.

(available for Lastline Email Defender On-Premises version 8.4 or above)

mail_delivery_outcome:

Restrict to mail messages that have a delivery outcome that is in this comma separated list.

e.g. ‘BOUNCE,QUARANTINE’ would return a list of mail messages that fit the criteria of either sent to a bounce server or quarantine server.

(available for Lastline Email Defender On-Premises version 8.4 or above)

lastline_mail_uuid:

Restrict to mail messages that have an llmail generated UUID that is in this comma separated list.

e.g. ‘902540c5a53f4c2a9a0e5f6eece3d8e2,85be90265ead401ba0c5e5c99eff8c57’ would return a list of mail messages that are associated with those specific UUIDs.

(available for Lastline Email Defender On-Premises version 8.4 or above)

Contents of successful response

A list of dictionaries with the following fields (elements are grouped by threat)

start_time:

Time of the first mail message in this group

end_time:

Time of the last mail message in this group

max_impact:

Maximum level of impact of mail messages in this group

occurrences:

Number of mail messages in this group

threat:

Detected threat. Called “Malware” in Lastline Portal.

threat_class:

Class of detected threat. Called “Malware Class” in Lastline Portal.

priority:

Level of priority for this group of mail messages (based on max impact)

net.mail.get_mail_messages_malware_priority(response_format)¶

Get statistics on bad mail messages by malware and priority level

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >= 7.5

URL

/papi/net/mail/messages_malware_priority[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_date:

Get mail messages after this date (required)

end_date:

Get mail messages before this date (required)

timezone:

Name of selected time zone

Appliance selection:

key:

access_key[:subkey]: Get mail messages detected by sensors with this key

key_id:

Get mail messages detected by sensors with this key

subkey_id:

Get mail messages detected by sensors with this subkey (provide together with key_id in alternative to key).

Filters:

recipient:

Filter on mail messages whose recipient contains this string

subject:

Filter on mail messages whose subject contains this string

sender:

Filter on mail messages with this sender

relevant_content:

3-value boolean, set to True to filter on mail messages containing relevant urls/attachments, False to exclude them, if not set return all

min_impact:

Restrict to mail messages with level or impact greater or equal than this value

Note: If account does not have the CAN_VIEW_BENIGN_EMAILS permission,

then a minimum impact filter of 30 (suspicious) is automatically applied to all requests (from Lastline Enterprise On-Premises release 7.18).

priority:

Restrict to mail messages with this level of impact (“HIGH”, “MEDIUM”, “LOW”)

threat:

Restrict to mail messages related to this threat

threat_class:

Restrict to mail messages related to this threat class

message_action:

Select mail messages on which this action was applied (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

LOG

content_action:

Select mail messages having content (i.e., attachments or urls) on which this action was applied (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

WARN

LOG

TEST

blocked:

3-way boolean value. Set to True to filter on mail messages that have either been blocked or at least one of their content (i.e., attachment or url) was blocked. Set to False to filter on mail messages that were not blocked an whose content was not blocked (available for Lastline Enterprise On-Premise versions >= 7.5.1)

assigned_to:

Get only mail messages assigned to any of these accounts. The value “unassigned” can be used to get only mail messages that have not been assigned to anyone. This is a comma-separated list of accounts. (optional) (Lastline Email Defender On-Premises version 8.2 or above)

e.g. if the value is: “user@lastline.com,unassigned” it means we filter on

mail messages assigned to user@lastline.com OR that are unassigned.

mail_state:

Restrict to mail messages in these states. This is a comma-separates list of mail states. (Lastline Email Defender On-Premises version 8.2 or above)

e.g. if the value is: “OPEN,IN_PROGRESS” it means we filter on mail messages in

either the state of “Open” or “In Progress”

Possible values are:

OPEN

IN_PROGRESS

DONE

analysis_task_typed_tags:

Restrict to messages that have attachments and/or urls with these Analysis Task Typed Tags. Provide a serialized JSON encoded sequence of Typed Tags. Each Typed Tag is a sequence of two strings for the Typed Tag’s type and value.

e.g. ‘[[“av_family”, “locky”], [“av_class”, “ransomware”]]’

(available for Lastline Email Defender On-Premises version 8.3 or above)

mail_processing_state:

Restrict to mail messages that have a processing state that is in this comma separated list.

e.g. ‘LOCAL_ANALYSIS,MALSCAPE_ANALYSIS’ would return a list of mail messages that fit the criteria of currently being analyzed.

(available for Lastline Email Defender On-Premises version 8.4 or above)

mail_analysis_status:

Restrict to mail messages that have an analysis status that is in this comma separated list.

e.g. ‘COMPLETE,UNKNOWN’ would return a list of mail messages that fit the criteria of either being processed or there being no status information at all.

(available for Lastline Email Defender On-Premises version 8.4 or above)

mail_delivery_outcome:

Restrict to mail messages that have a delivery outcome that is in this comma separated list.

e.g. ‘BOUNCE,QUARANTINE’ would return a list of mail messages that fit the criteria of either sent to a bounce server or quarantine server.

(available for Lastline Email Defender On-Premises version 8.4 or above)

lastline_mail_uuid:

Restrict to mail messages that have an llmail generated UUID that is in this comma separated list.

e.g. ‘902540c5a53f4c2a9a0e5f6eece3d8e2,85be90265ead401ba0c5e5c99eff8c57’ would return a list of mail messages that are associated with those specific UUIDs.

(available for Lastline Email Defender On-Premises version 8.4 or above)

Contents of successful response

A dictionary with keys ‘priority’, ‘threat_class’ and ‘threat’ providing results aggregated by priority, priority + threat_class, priority + threat class + threat respectively. The value for each key is a list of dictionaries with the following fields:

start_time:

Time of the first mail message in this group

end_time:

Time of the last mail message in this group

max_impact:

Maximum level of impact of mail messages in this group

occurrences:

Number of mail messages in this group

threat:

(Only for ‘threat’ key) Detected threat. Called “Malware” in Lastline Portal.

threat_class:

(Only for ‘threat’ and ‘threat_class’ key) Class of detected threat. Called “Malware Class” in Lastline Portal.

priority:

Level of priority for this group of mail messages (based on max impact)

net.mail.get_mail_messages_stats(response_format)¶

Get statistics on bad mail message over time

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >= 7.5

URL

/papi/net/mail/messages_stats[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_date:

Get mail messages after this date (required)

end_date:

Get mail messages before this date (required)

timezone:

Name of selected time zone

time_scale:

‘month’, ‘day’, ‘week’, defaults to ‘day’

Appliance selection:

key:

access_key[:subkey]: Get mail messages detected by sensors with this key

key_id:

Get mail messages detected by sensors with this key

subkey_id:

Get mail messages detected by sensors with this subkey (provide together with key_id in alternative to key).

Grouping:

group_by_priority:

Boolean, defaults to True. Group results also by priority level (HIGH, MEDIUM, LOW)

Filters:

recipient:

Filter on mail messages whose recipient contains this string

subject:

Filter on mail messages whose subject contains this string

sender:

Filter on mail messages with this sender

relevant_content:

3-value boolean, set to True to filter on mail messages containing relevant urls/attachments, False to exclude them, if not set return all

min_impact:

Restrict to mail messages with level or impact greater or equal than this value

Note: If account does not have the CAN_VIEW_BENIGN_EMAILS permission,

then a minimum impact filter of 30 (suspicious) is automatically applied to all requests (from Lastline Enterprise On-Premises release 7.18).

priority:

Restrict to mail messages with this level of impact (“HIGH”, “MEDIUM”, “LOW”)

threat:

Restrict to threats with this name

threat_class:

Restrict to this threat classe

message_action:

Select mail messages on which this action was applied (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

LOG

content_action:

Select mail messages having content (i.e., attachments or urls) on which this action was applied (available for Lastline Enterprise On-Premise versions >= 7.5.1) Possible values are:

BLOCK

WARN

LOG

TEST

blocked:

3-way boolean value. Set to True to filter on mail messages that have either been blocked or at least one of their content (i.e., attachment or url) was blocked. Set to False to filter on mail messages that were not blocked an whose content was not blocked (available for Lastline Enterprise On-Premise versions >= 7.5.1)

assigned_to:

Get only mail messages assigned to any of these accounts. The value “unassigned” can be used to get only mail messages that have not been assigned to anyone. This is a comma-separated list of accounts. (optional) (Lastline Email Defender On-Premises version 8.2 or above)

e.g. if the value is: “user@lastline.com,unassigned” it means we filter on

mail messages assigned to user@lastline.com OR that are unassigned.

mail_state:

Restrict to mail messages in these states. This is a comma-separates list of mail states. (Lastline Email Defender On-Premises version 8.2 or above)

e.g. if the value is: “OPEN,IN_PROGRESS” it means we filter on mail messages in

either the state of “Open” or “In Progress”

Possible values are:

OPEN

IN_PROGRESS

DONE

analysis_task_typed_tags:

Restrict to messages that have attachments and/or urls with these Analysis Task Typed Tags. Provide a serialized JSON encoded sequence of Typed Tags. Each Typed Tag is a sequence of two strings for the Typed Tag’s type and value.

e.g. ‘[[“av_family”, “locky”], [“av_class”, “ransomware”]]’

(available for Lastline Email Defender On-Premises version 8.3 or above)

mail_processing_state:

Restrict to mail messages that have a processing state that is in this comma separated list.

e.g. ‘LOCAL_ANALYSIS,MALSCAPE_ANALYSIS’ would return a list of mail messages that fit the criteria of currently being analyzed.

(available for Lastline Email Defender On-Premises version 8.4 or above)

mail_analysis_status:

Restrict to mail messages that have an analysis status that is in this comma separated list.

e.g. ‘COMPLETE,UNKNOWN’ would return a list of mail messages that fit the criteria of either being processed or there being no status information at all.

(available for Lastline Email Defender On-Premises version 8.4 or above)

mail_delivery_outcome:

Restrict to mail messages that have a delivery outcome that is in this comma separated list.

e.g. ‘BOUNCE,QUARANTINE’ would return a list of mail messages that fit the criteria of either sent to a bounce server or quarantine server.

(available for Lastline Email Defender On-Premises version 8.4 or above)

lastline_mail_uuid:

Restrict to mail messages that have an llmail generated UUID that is in this comma separated list.

e.g. ‘902540c5a53f4c2a9a0e5f6eece3d8e2,85be90265ead401ba0c5e5c99eff8c57’ would return a list of mail messages that are associated with those specific UUIDs.

(available for Lastline Email Defender On-Premises version 8.4 or above)

Contents of successful response

A list of dictionaries with the following fields (elements are time period and optionally by priority):

start_date:

Start date of the observed period

end_date:

End date of the observed period of time

max_impact:

Maximum level of impact of mail messages in this group

occurrences:

Number of mail messages in this group

priority:

Level of priority for this group of mail messages (based on max impact)

net.mail.get_mail_processing_log(response_format)¶

Get a list of the processed logs of a mail message.

On-Premises availability

This API method is available as part of Lastline Email Defender On-Premises

versions 8.4 or above.

URL

/papi/net/mail/mail_processing_log[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET

GET Parameters

Time range selection:

start_time:

Get mail messages after this time (required)

end_time:

Get mail messages before this time (required)

timezone:

Name of selected time zone (optional)

Filters:

mail_message_id:

Get processing logs that belong to the mail message with this identifier.

If both mail_message_id and mail_message_log_id are supplied, then the parameter mail_message_id is ignored and mail_message_log_id is used for getting logs.

mail_message_log_id:

Get processing logs that belong to the mail message log with this identifier.

If both mail_message_id and mail_message_log_id are supplied, then the parameter mail_message_id is ignored and mail_message_log_id is used for getting logs.

Contents of successful response

A list of dictionaries with the following fields:

state:

State of the log stored about the mail message

timestamp:

Timestamp of the processed log

Example response

[

{“state”: “RECEIVED”, “timestamp”: “2012-10-15 08:27:33”}, {“state”: “LOCAL_ANALYSIS”, “timestamp”: “2012-10-15 08:27:33”},

]

net.mail.get_mail_delivery_log(response_format)¶

Get a list of delivery logs of a mail message.

On-Premises availability

This API method is available as part of Lastline Email Defender On-Premises

versions 8.4 or above.

URL

/papi/net/mail/mail_delivery_log[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET

GET Parameters

Time range selection:

start_time:

Get mail messages after this time (required)

end_time:

Get mail messages before this time (required)

timezone:

Name of selected time zone (optional)

Filters:

mail_message_id:

Get delivery logs that belong to the mail message with this identifier.

If both mail_message_id and mail_message_log_id are supplied, then the parameter mail_message_id is ignored and mail_message_log_id is used for getting logs.

mail_message_log_id:

Get delivery logs that belong to the mail message log with this identifier.

If both mail_message_id and mail_message_log_id are supplied, then the parameter mail_message_id is ignored and mail_message_log_id is used for getting logs.

Contents of successful response

A list of dictionaries with the following fields:

mail_delivery_outcome:

Delivery status information on each hop.

delivery_timestamp:

Timestamp of when the delivery was attempted.

details:

Detail on last delivery attempt (e.g. error message in case of failed delivery)

host:

Host IP address of the host delivered to.

Example response

[

{

‘delivery_timestamp’: ‘2012-10-15 08:27:33’, ‘details’: ‘step 1’, ‘host’: ‘www.something.com’, ‘mail_delivery_outcome’: ‘NEXT_HOP’,

},

]

net.mail.get_mail_message_headers(response_format)¶

Get the headers of a mail message.

On-Premises availability

This API method is available as part of Lastline Email Defender On-Premises

versions 8.4 or above.

URL

/papi/net/mail/mail_message_headers[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET

GET Parameters

Time range selection:

start_time:

Get a mail message after this time (required)

end_time:

Get a mail message before this time (required)

timezone:

Name of selected timezone (optional)

Filters:

mail_message_id:

Get the headers of the mail message associated with this identifier.

If both mail_message_id and mail_message_log_id are supplied, then the parameter mail_message_id is ignored and mail_message_log_id is used for getting headers.

mail_message_log_id:

Get the headers of the mail message associated with this log identifier.

If both mail_message_id and mail_message_log_id are supplied, then the parameter mail_message_id is ignored and mail_message_log_id is used for getting headers.

Contents of successful response

A list of dictionaries with the following fields:

header_field_name:

The name of the field within the mail header.

header_field_body:

The body of the field within the mail header.

Example response

[

{

‘header_field_name’: ‘Received’, ‘header_field_body’: ‘from gmail.com ([66.249.64.0])’,

}, {

‘header_field_name’: ‘ident’, ‘header_field_body’: ‘yalrla9sz`,

},

]

net.mail.get_mail_detections(response_format)¶

Get detections for a mail message.

On-Premises availability

This API method is available as part of Lastline Email Defender On-Premises

versions 9.1 or above.

URL

/papi/net/mail/detections[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET

GET Parameters

Time range selection:

start_time:

Get detections for mail message after this time (required)

end_time:

Get detections for mail message before this time (required)

timezone:

Name of selected timezone (optional)

mail_message_id:

Get detections of the mail message associated with this identifier (required)

Contents of successful response

A list of dictionaries with the following fields:

detector:

The name of the detector that made detection.

action:

The action that would be taken on the mail solely by this detector. Possible values are:

BLOCK

LOG

threat:

The name of the threat detected.

threat_class:

The name of the threat class associated with the threat.

Example response

[

{

‘detector’: ‘download:binary’, ‘action’: ‘LOG’, ‘threat’: ‘FileBulldog’,

}, {

‘detector’: ‘llrules:1088114’, ‘action’: ‘BLOCK, ‘threat’: ‘Malicious Url’,

},

]

Incidents¶

Method Index¶

get_incident():

Get information about an incident
get_incidents():

Get information about incident
get_incidents_legacy():

DEPRECATED: Get information about incidents
get_malware():

Get statistics on incidents and infected hosts in the protected network by malware
get_incident_sources():

Get informations on infected hosts in the protected network over time
get_incident_stats():

Get statistics on incidents and infected hosts in the protected network over time
get_incident_sources_legacy():

DEPRECATED: Get statistics on incidents and infected hosts in the protected network over time
get_incident_evidence():

Get evidence about an incident
get_source_incident_evidence():

Get evidence about incidents on a specific host in the protected network
set_incident_read_status():

Mark an incident as read/unread
set_incident_archived_status():

Mark an incident as archived/unarchived
set_source_cleaned_status():

Mark an incidents’ source as cleaned/uncleaned
set_source_threat_ignored_status():

Mark a source + threat pair as ignored/not ignored

Method Documentation¶

net.incident.get_incident(response_format)¶

Get information about a specific incident in the protected network

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >=7.2.

URL

/papi/net/incident/get[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

incident_id:

Return informations about the incident with this identifier

timezone:

Name of selected time zone

Contents of successful response:

A list of dictionaries with the following keys:

incident_id:

Identifier of the incident

access_key_id:

Identifier of license of sensor that detected the incident

subkey_id:

Identifier of subkey of sensor that detected the incident

time:

Start time of the incident (Deprecated)

start_time:

Start time of the incident

end_time:

End time of the incident

events:

Number of distinct events related to this incident

src_host:

IP address of the source of the incident (in dotted format)

num_src_ips:

Number of distinct source IP addresses

src_hostname:

Hostname of the source

blocked:

Whether in at least one event related to the incident the operation performed was blocking

src_id:

ID of the host the incident happened on

src_label:

Label of the source of the incident

host_label:

Label of the host the incident happened on

host_whitelisted:

True if the host the incident happened on is whitelisted

threat:

Detected threat. Called “Malware” in Lastline Portal.

threat_class:

Class of detected threat. Called “Malware Class” in Lastline Portal.

impact:

Impact of the incident

is_archived:

Whether the incident has been archived or not

is_read:

Whether the incident has been read or not

archived_cause:

Why the incident was archived

comment:

Comment on the malware, or malware class, related to this incident

mitigation:

Description of the possible mitigation steps to be taken to deal with the type of malware, or malware class, related to this incident

breach_uuid:

Breach this incident is part of (Optional) (available for Lastline Enterprise On-Premise versions >= 8.2)

net.incident.get_incidents(response_format)¶

Get information about incidents in the protected network

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >=7.2.

URL

/papi/net/incident/list[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_time:

Get incidents that happened after this date (required)

end_time:

Get incidents that happened before this date (required)

timezone:

Name of selected time zone

Appliance selection:

key:

access_key[:subkey]: Get incidents detected by sensors with this key

key_id:

Get incidents detected by sensors with this key

subkey_id:

Get incidents detected by sensors with this subkey (provide together with key_id in alternative to key).

Pagination:

max_results:

Limit to this many results

offset_results:

Skip the first offset_results results.

Filters:

priority:

Restrict to incidents with this level of impact (‘HIGH’, ‘MEDIUM’ or ‘LOW’)

threat_class:

Restrict to this threat classes

threat:

Restrict to threats with these names

src_id:

Restrict to incidents on the host with this IDs

src_ip:

Restrict to these hosts in the monitored network, selected by IP address, CIDR block, IP range, or comma-separated list of IPs,CIDR blocks and IP ranges. Example: “1.2.3.4,192.168.10.0/24,10.0.0.5-10.0.0.55”

src_hostname:

Restrict to these hosts in the monitored network, selected by host name or label, comma-separated

archived:

“archived”, “unarchived” or “all” to select archived, unarchived or all incidents respectively. Default all

read:

“read”, “unread” or “all” to select read, unread or all incidents respectively. Default all

whitelisting:

Boolean parameter set to True to exclude malwares from whitelisted sources

homenet

3-value Boolean. If set to True only include incidents from sources inside the homenet, set to False to exclude incidents from sources inside the homenet, if not set return everything.

breach_uuid:

Restrict to incidents that are part of these breaches, use the value ‘null’ to filter on incidents not belonging to any breach. (available for Lastline Enterprise On-Premise versions >= 8.2)

host_tag:

Restrict to incidents on hosts labelled with these host tags, comma-separated

incidents_older_than:

Filter on incidents that are older than this datetime

Sorting:

orderby: specify a custom sort value and direction

Contents of succesful response

A list of dictionaries with the following keys:

incident_id:

Identifier of the incident

access_key_id:

Identifier of license of sensor that detected the incident

subkey_id:

Identifier of subkey of sensor that detected the incident

time:

Unix timestamp of the incident (seconds since ‘1970-01-01 00:00:00’)

start_time:

Start time of the incident

end_time:

End time of the incident

events:

Number of distinct events related to this incident

src_host:

IP address of the source of the incident (in dotted format)

num_src_ips:

Number of distinct source IP addresses

src_hostname:

Hostname of the source

blocked:

Whether in at least one event related to the incident the operation performed was blocking

src_id:

ID of the host the incident happened on

src_label:

Label of the source of the incident

host_label:

Label of the host the incident happened on

host_whitelisted:

True if the host the incident happened on is whitelisted

threat:

Detected threat. Called “Malware” in Lastline Portal.

threat_class:

Class of detected threat. Called “Malware Class” in Lastline Portal.

impact:

Impact of the incident

is_archived:

Whether the incident has been archived or not

is_read:

Whether the incident has been read or not

archived_cause:

Why the incident was archived

breach_uuid:

Breach this incident is part of (Optional) (available for Lastline Enterprise On-Premise versions >= 8.2)

net.incident.get_incidents_legacy(response_format)¶

Get information about incidents in the protected network

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >=7.2.

DEPRECATED

This method is deprecated: use get_incident() to query for a single incident and get_incidents() to query for multiple incidents

URL

/papi/net/incident/list_legacy[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_time:

Get incidents that happened after this date (required)

end_time:

Get incidents that happened before this date (required)

timezone:

Name of selected time zone

Appliance selection:

key:

access_key[:subkey]: Get incidents detected by sensors with this key

key_id:

Get incidents detected by sensors with this key

subkey_id:

Get incidents detected by sensors with this subkey (provide together with key_id in alternative to key).

Pagination:

max_results:

Limit to this many results

offset_results:

Skip the first offset_results results.

Filters:

incident_id:

Identifier of a specific incident. If provided other filters will be ignored and only informations about this incident will be returned

priority:

Restrict to incidents with this level of impact (‘HIGH’, ‘MEDIUM’ or ‘LOW’)

threat_class:

Restrict to this threat classes

threat:

Restrict to threats with these names

src_id:

Restrict to incidents on the host with this IDs

src_ip:

Restrict to these hosts in the monitored network, selected by IP address, CIDR block, IP range, or comma-separated list of IPs,CIDR blocks and IP ranges. Example: “1.2.3.4,192.168.10.0/24,10.0.0.5-10.0.0.55”

src_hostname:

Restrict to these hosts in the monitored network, selected by host name or label, comma-separated

archived:

“archived”, “unarchived” or “all” to select archived, unarchived or all incidents respectively. Default all

read:

“read”, “unread” or “all” to select read, unread or all incidents respectively. Default all

whitelisting:

Boolean parameter set to True to exclude malwares from whitelisted sources

homenet

3-value Boolean. If set to True only include incidents from sources inside the homenet, set to False to exclude incidents from sources inside the homenet, if not set return everything.

Contents of succesful response

A list of dictionaries with the following keys:

incident_id:

Identifier of the incident

access_key_id:

Identifier of license of sensor that detected the incident

subkey_id:

Identifier of subkey of sensor that detected the incident

time:

Unix timestamp of the incident (seconds since ‘1970-01-01 00:00:00’)

start_time:

Start time of the incident

end_time:

End time of the incident

events:

Number of distinct events related to this incident

src_host:

IP address of the source of the incident (in dotted format)

num_src_ips:

Number of distinct source IP addresses

src_hostname:

Hostname of the source

blocked:

Whether in at least one event related to the incident the operation performed was blocking

src_id:

ID of the host the incident happened on

src_label:

Label of the source of the incident

host_label:

Label of the host the incident happened on

host_whitelisted:

True if the host the incident happened on is whitelisted

threat:

Detected threat. Called “Malware” in Lastline Portal.

threat_class:

Class of detected threat. Called “Malware Class” in Lastline Portal.

impact:

Impact of the incident

is_archived:

Whether the incident has been archived or not

is_read:

Whether the incident has been read or not

archived_cause:

Why the incident was archived

If incident_id was specified the following fields will also be present:

comment:

Comment on the malware, or malware class, related to this incident

mitigation:

Description of the possible mitigation steps to be taken to deal with the type of malware, or malware class, related to this incident

net.incident.get_malware(response_format)¶

Get statistics on incidents and infected sources in the protected network by malware

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >=7.2.

URL

/papi/net/incident/malware[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_date:

Get malware related to events that happened after this date (required)

end_date:

Get malware related to events that happened before this date (required)

timezone:

Name of selected time zone

Appliance selection:

key:

access_key[:subkey]: Get malware detected by sensors with this key

key_id:

Get malware detected by sensors with this key

subkey_id:

Get malware detected by sensors with this subkey (provide together with key_id in alternative to key).

Grouping:

split_by_priority:

Boolean parameter, defaults to False. Split results by priority (high/medium/low impact). This means that a malware associated with infections of different impact levels can be listed multiple times (at most once for each priority level)

Filters:

whitelisting:

Boolean parameter set to True to exclude malwares from whitelisted sources

homenet

3-value Boolean. If set to True only include malware from sources inside the homenet, set to False to exclude malware from sources inside the homenet, if not set return everything.

archived:

“archived”, “unarchived” or “all” to select malware related to archived, unarchived or all incidents respectively. Default all

read:

“read”, “unread” or “all” to select malware related to read, unread or all incidents respectively. Default all

src_ip:

Restrict to malware on these hosts in the protected network. This is a comma-separated list of IP addresses, IP ranges or CIDR blocks such as:

1.2.3.4

1.2.3.4-1.2.3.5

1.2.3.0/24

src_hostname:

Restrict to malware on hosts with these hostnames in the protected network.

breach_uuid:

Restrict to incidents that are part of these breaches, use the value ‘null’ to filter on incidents not belonging to any breach. (available for Lastline Enterprise On-Premise versions >= 8.2)

host_tag:

Restrict to incidents on hosts labelled with these host tags, comma-separated

incidents_older_than:

Filter on incidents that are older than this datetime

Contents of successful response

If split_by_priority is set to False return a list of dictionaries containing the fields below. Element are grouped by threat

start_time:

Time of the first event of this group
end_time:

Time of the last event of this group
max_impact:

Maximum of all the malware impact in this group
incidents:

Number of distinct incidents related to malware of this group
events:

Number of distinct events related to malware in this group
sources:

Number of diffent sources realated to this malware group
threat:

Detected threat. Called “Malware” in Lastline Portal.
threat_class:

Class of detected threat. Called “Malware Class” in Lastline Portal.
priority:

Level of priority for this malware group, based on the maximum impact level

If set to True return a dictionary with keys ‘priority’, ‘threat_class’ and ‘threat’ providing results aggregated by priority, priority + threat_class, priority + threat class + threat respectively.

net.incident.get_incident_sources(response_format)¶

Get informations on infected hosts in the protected network over time

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >=7.2.

URL

/papi/net/incident/incident_sources[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_date:

Get incidents related to events that happened after this date (required)

end_date:

Get incidents related to events that happened before this date (required)

timezone:

Name of selected time zone

Appliance selection:

key:

access_key[:subkey]: Get incidents detected by sensors with this key

key_id:

Get incidents detected by sensors with this key

subkey_id:

Get incidents detected by sensors with this subkey (provide together with key_id in alternative to key).

Pagination:

max_results:

Limit to this many results

Filters:

priority:

Restrict to incidents with this level of impact (‘HIGH’, ‘MEDIUM’ or ‘LOW’)

threat_class:

Restrict to this threat classes

threat:

Restrict to threats with these names

src_id:

Restrict to incidents on the host with this IDs

src_ip:

Restrict to these hosts in the monitored network, selected by IP address, CIDR block, IP range, or comma-separated list of IPs,CIDR blocks and IP ranges. Example: “1.2.3.4,192.168.10.0/24,10.0.0.5-10.0.0.55”

src_hostname:

Restrict to these hosts in the monitored network, selected by host name or label, comma-separated

archived:

“archived”, “unarchived” or “all” to select archived, unarchived or all incidents respectively. Default all

read:

“read”, “unread” or “all” to select read, unread or all incidents respectively. Default all

whitelisting:

Boolean parameter set to True to exclude malwares from whitelisted sources

homenet

3-value Boolean. If set to True only include incidents from sources inside the homenet, set to False to exclude incidents from sources inside the homenet, if not set return everything.

breach_uuid:

Restrict to incidents that are part of these breaches, use the value ‘null’ to filter on incidents not belonging to any breach. (available for Lastline Enterprise On-Premise versions >= 8.2)

host_tag:

Restrict to incidents on hosts labelled with these host tags, comma-separated

incidents_older_than:

Filter on incidents that are older than this datetime

Contents of successful response

A list of dictionaries containing the fields below.

max_impact:

Maximum impact of all the grouped incidents

incidents:

Number of incidents of this group

events:

Number of events related to the grouped incidents

start_time:

Time of the first event of this group

end_time:

Time of the last event of this group

src_host:

IP address of the source of the event (in dotted format)

num_src_ips:

Number of distinct source IP addresses

src_hostname:

Hostname of the source

access_key_id:

Identifier of license of sensor that detected the incident (available for Lastline Enterprise On-Premise versions >= 7.5)

subkey_id:

Identifier of the sensor that detected the incident

src_id:

ID of the host the incidents happened on

src_label:

Label of the source of the event

host_label:

Label of the host the incidents happened on

host_whitelisted:

True if the host the incidents happened on is whitelisted

is_archived:

Whether all incidents on this source have been archived or not

is_read:

Whether all incidents on this source have been read or not

threats:

Sequence of threats detected on this source

threat_classes:

Sequence of threat classes detected on this source

net.incident.get_incident_stats(response_format)¶

Get statistics on incidents and infected hosts in the protected network over time

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >=7.2.

URL

/papi/net/incident/incident_stats[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_date:

Get incidents related to events that happened after this date (required)

end_date:

Get incidents related to events that happened before this date (required)

time_scale:

‘month’, ‘day’, ‘week’, ‘unlimited’ (required)

timezone:

Name of selected time zone

Appliance selection:

key:

access_key[:subkey]: Get incidents detected by sensors with this key

key_id:

Get incidents detected by sensors with this key

subkey_id:

Get incidents detected by sensors with this subkey (provide together with key_id in alternative to key).

Grouping:

group_by_impact:

Boolean, defaults to false. Group results also by impact level (HIGH, MEDIUM, LOW)

Filters:

priority:

Restrict to incidents with this level of impact (‘HIGH’, ‘MEDIUM’ or ‘LOW’)

threat_class:

Restrict to this threat classes

threat:

Restrict to threats with these names

src_id:

Restrict to incidents on the host with this IDs

src_ip:

Restrict to these hosts in the monitored network, selected by IP address, CIDR block, IP range, or comma-separated list of IPs,CIDR blocks and IP ranges. Example: “1.2.3.4,192.168.10.0/24,10.0.0.5-10.0.0.55”

src_hostname:

Restrict to these hosts in the monitored network, selected by host name or label, comma-separated

archived:

“archived”, “unarchived” or “all” to select archived, unarchived or all incidents respectively. Default all

read:

“read”, “unread” or “all” to select read, unread or all incidents respectively. Default all

whitelisting:

Boolean parameter set to True to exclude malwares from whitelisted sources

homenet

3-value Boolean. If set to True only include incidents from sources inside the homenet, set to False to exclude incidents from sources inside the homenet, if not set return everything.

breach_uuid:

Restrict to incidents that are part of these breaches, use the value ‘null’ to filter on incidents not belonging to any breach. (available for Lastline Enterprise On-Premise versions >= 8.2)

host_tag:

Restrict to incidents on hosts labelled with these host tags, comma-separated

incidents_older_than:

Filter on incidents that are older than this datetime

Contents of successful response

A list of dictionaries containing the fields below.

max_impact:

Maximum impact of all the grouped incidents

incidents:

Number of incidents of this group

events:

Number of events related to the groupped incidents

sources:

Number of different sources related to incidents in this group

priority:

Level of priority of incidents in this group based on maximum impact level

start_date:

Start date of the observed period

end_date:

End date of the observed period of time

net.incident.get_incident_sources_legacy(response_format)¶

Get statistics on incidents and infected hosts in the protected network over time or just a list of infected hosts (if the time_scale parameter is not passed)

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >=7.2.

DEPRECATED

This method is deprecated: use get_incident_sources() to query for a list of sources, and get_incident_stats() to get stats of number of infections over time.

URL

/papi/net/incident/incident_sources_legacy[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_date:

Get incidents related to events that happened after this date (required)

end_date:

Get incidents related to events that happened before this date (required)

time_scale:

‘month’, ‘day’, ‘week’, ‘unlimited’ (required)

timezone:

Name of selected time zone

Appliance selection:

key:

access_key[:subkey]: Get incidents detected by sensors with this key

key_id:

Get incidents detected by sensors with this key

subkey_id:

Get incidents detected by sensors with this subkey (provide together with key_id in alternative to key).

Grouping:

group_by_impact:

Boolean, defaults to false. Group results also by impact level (HIGH, MEDIUM, LOW)

Filters:

priority:

Restrict to incidents with this level of impact (‘HIGH’, ‘MEDIUM’ or ‘LOW’)

threat_class:

Restrict to this threat classes

threat:

Restrict to threats with these names

src_id:

Restrict to incidents on the host with this IDs

src_ip:

Restrict to these hosts in the monitored network, selected by IP address, CIDR block, IP range, or comma-separated list of IPs,CIDR blocks and IP ranges. Example: “1.2.3.4,192.168.10.0/24,10.0.0.5-10.0.0.55”

src_hostname:

Restrict to these hosts in the monitored network, selected by host name or label, comma-separated

archived:

“archived”, “unarchived” or “all” to select archived, unarchived or all incidents respectively. Default all

read:

“read”, “unread” or “all” to select read, unread or all incidents respectively. Default all

whitelisting:

Boolean parameter set to True to exclude malwares from whitelisted sources

homenet

3-value Boolean. If set to True only include incidents from sources inside the homenet, set to False to exclude incidents from sources inside the homenet, if not set return everything.

Contents of successful response

A list of dictionaries containing the fields below.

If time_scale was specified:

max_impact:

Maximum impact of all the grouped incidents

incidents:

Number of incidents of this group

events:

Number of events related to the groupped incidents

sources:

Number of different sources related to incidents in this group

priority:

Level of priority of incidents in this group based on maximum impact level

start_date:

Start date of the observed period

end_date:

End date of the observed period of time

If time_scale was not specified:

max_impact:

Maximum impact of all the grouped incidents

incidents:

Number of incidents of this group

events:

Number of events related to the grouped incidents

start_time:

Time of the first event of this group

end_time:

Time of the last event of this group

src_host:

IP address of the source of the event (in dotted format)

num_src_ips:

Number of distinct source IP addresses

src_hostname:

Hostname of the source

subkey_id:

Identifier of the sensor that detected the event

src_id:

ID of the host the incidents happened on

src_label:

Label of the source of the event

host_label:

Label of the host the incidents happened on

host_whitelisted:

True if the host the incidents happened on is whitelisted

is_archived:

Whether all incidents on this source have been archived or not

is_read:

Whether all incidents on this source have been read or not

net.incident.get_incident_evidence(response_format)¶

Get the evidence associated with this incident.

URL

/papi/net/incident/evidence[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

incident_id:

Identifier of event for which we want to return URLs (required)

key:

access_key[:subkey]: Restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

customer:

Username of customer (this is an email address). Defaults to the customer for which the current account is authenticated.

timezone:

Name of selected time zone

extended:

Retrieve extra information for each evidence piece

Contents of successful response

List of Evidence. Each is a mapping with the following fields:

threat:

Detected threat. Called “Malware” in Lastline Portal.

threat_class:

Class of detected threat. Called “Malware Class” in Lastline Portal.

confidence:

Confidence in the evidence (0-100)

severity:

Severity of what the evidence has detected (0-100)

impact:

Overall impact of this evidence (0-100) This combines confidence and severity into an overall number. (available for Lastline Enterprise On-Premise versions >= 7.5)

evidence_type:

Type of evidence detected

detector:

Name of detector that detected this evidence

activity:

Name of detected activity

subject:

Subject of evidence. Semantics of this field can vary depending on evidence_type.

signature_id

Identifier of network signature that detected this evidence. This is currently for customer-provided signatures at the moment.

first_seen:

First time this evidence was detected

last_seen:

Last time this evidence was detected

reference_type:

Type of reference alert for this evidence. This is one of “NETWORK_EVENT” and “ENDPOINT_ALERT”

reference_id:

Identifier of reference alert

reference_time:

Timestamp of reference alert

The reference_type, reference_id and reference_time fields together identify an alert in which this evidence was found.

If the extended parameter is set, some or all of the following fields depending on the evidence details:

reference_event:

Information about the reference event. See network_event.get_event for info.

urls:

List of URLs associated with reference event

blacklist_match_info:

BlacklistMatchInfo for this reference event

dga_domains:

DGA domains for reference event

dga_domain_count:

Number of DGA domains for reference event

download_file_type:

File type of the downloaded file

download_file_name:

File name of the downloaded file

llanta_rule_name:

Name of the llanta rule

detector_goal:

The goal of the detector

Error Codes

llapi.LLAPI_ERROR__NO_SUCH_ENTITY:

No such event exists

net.incident.get_source_incident_evidence(response_format)¶

Get the incident evidence for incidents on a host in the network

URL

/papi/net/incident/host_evidence[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

src_ip:

IP address of host for which we want evidence

key:

access_key[:subkey]: Restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

customer:

Username of customer (this is an email address). Defaults to the customer for which the current account is authenticated.

start_time

Start of interval to consider (required)

end_time

End of interval to consider (required)

timezone:

Name of selected time zone (default UTC)

extended:

Retrieve extra information for each evidence piece

Contents of successful response

List of Evidence. This is the same as returned by get_incident_evidence, but with the additional fields:

incident_id:

Identifier of incident that included this evidence

If the extended parameter is set, some or all of the following fields depending on the evidence details:

reference_event:

Information about the reference event. See network_event.get_event for info.

urls:

List of URLs associated with reference event

blacklist_match_info:

BlacklistMatchInfo object for this reference event

dga_domains:

DGA domains for reference event

dga_domain_count:

Number of DGA domains for reference event

download_file_type:

File type of the downloaded file

download_file_name:

File name of the downloaded file

llanta_rule_name:

Name of the llanta rule

detector_goal:

The goal of the detector

net.incident.set_incident_read_status(response_format)¶

Mark an incident as read/unread.

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >= 7.15.

URL

/papi/net/incident/read_status/set[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

incident_id:

Identifier of incident

read_status:

If True mark the incident as read, if False mark it as unread

Contents of succesful response

“OK”

net.incident.set_incident_archived_status(response_format)¶

Mark an incident as archived/unarchived.

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >= 7.15.

URL

/papi/net/incident/archived_status/set[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

incident_id:

Identifier of incident

archived_status:

If True mark the incident as archived, if False mark it as unarchived

Contents of succesful response

“OK”

net.incident.set_source_cleaned_status(response_format)¶

Mark an incidents’ source as cleaned/uncleaned.

To unclean a source it must have already been cleaned beforehand, trying to unclean a source that had not been cleaned will result in an error. Also trying to clean a source that is already marked as clean will result in an error.

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >= 7.15.

URL

/papi/net/incident/source_cleaned_status/set[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

source_id:

Identifier of source

cleaned_status:

If True mark the source as cleaned, if False mark it as uncleaned

notes:

Free-text notes on the cleaning (optional)

Contents of succesful response

“OK”

net.incident.set_source_threat_ignored_status(response_format)¶

Mark a source + threat pair as ignored/not ignored.

To un-ignore a source + threat pair, it must have already been marked as ignored beforehand, trying to un-ignore a pair that had not been marked as ignored will result in an error. Also trying to mark as ignored a threat on a source that is already ignored will result in an error.

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >= 7.15.

URL

/papi/net/incident/source_threat_ignored_status/set[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

source_id:

Identifier of source

threat:

Name of the threat

ignored_status:

If True mark the source + threat as ignored, if False mark it as not ignored

notes:

Free-text notes on the cleaning (optional)

max_ignoreable_impact:

Ignore incidents of this threat on this source if the impact is less than this, int 0-100 (optional, defaults to 100)

Contents of succesful response

“OK”

Passive DNS¶

IMPORTANT NOTE: for a variety of reasons, some DNS requests performed by clients in a monitored network may end up not being stored in our pDNS storage. These reasons include, and are not limited to, rate limiting and thresholding on the sensor’s side, and particular network configurations employed on certain customer premises. Thus, results of these APIs must not be considered as representing the totality of DNS requests seen in a given customer network. Also, Lastline currently stores pDNS data for one month only. Any query will be automatically “capped” at start_time = 1 month ago if any data older than one month is requested.

On-Premise availability

Not available. pDNS features are currently available only for hosted installations.

Method Index¶

get_top_domains():

Get the top most requested dns names by a given source IP in the specified time window
view_domain():

Get the timeline of DNS requests for the given domain name from the specified source IP
view_ip():

Get the timeline of DNS requests from the given source IP, which resolved to the requested IP

Method Documentation¶

net.pdns.get_top_domains(response_format)¶

Get the top most requested domains by a given source IP in the specified time window. This returns the list of most requested DNS names that have been collected by Lastline’s pDNS storage.

URL

/papi/net/pdns/top_domains[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

src_ip:

Restrict data to DNS requests from this source IP (required)

start_time:

Start of the time window to select (required)

end_time:

End of the time window to select (required)

timezone:

Name of selected time zone

key:

access_key:subkey: Restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

limit:

Limit to this number of top queried domains

Contents of successful response

A dictionary containing the fields below:

top_domains:

List of queried domains, ordered in descending order by number of hits collected. Each element of the list is a dictionary with the following keys:

fqdn:

Fully qualified domain name observed in the DNS requests

total_hits:

Total hits collected for the given fqdn in the requested time window

other_hits:

Number of hits performed by the selected source IP that fall outside the limit of top queried domains, if any.

Sample Response
{
  "success": 1,
  "data": {
    "top_domains": [
      {"fqdn": "example1.com", "total_hits": 123},
      {"fqdn": "example2.com", "total_hits": 80},
      {"fqdn": "example3.com", "total_hits": 40},
      {"fqdn": "example4.com", "total_hits": 12},
    ],
    "other_hits": 22
  }
}

net.pdns.view_domain(response_format)¶

Get the timeline of DNS requests for the given domain name (as rrname) from the specified source IP in the provided time window.

URL

/papi/net/pdns/view_domain[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

src_ip:

Restrict data to DNS requests from this source IP (required)

start_time:

Start of the time window to select (required)

end_time:

End of the time window to select (required)

timezone:

Name of selected time zone

domain:

Filter for DNS events that queried for this domain (required)

key:

access_key:subkey: Restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

limit:

Limit to this number of top queried domains

Contents of successful response

A list of DNS Resouce Records ordered by timestamp (timeline). Each resource record contains the following fields:

rrname:

Resource Record Name requested by the client

rrtype:

Resource Record type, as string

rdata:

Resource data: list of results returned by the server

ttl:

list of TTL values for each of the entries appearing in rdata

n:

Number of requests grouped in this resource record

error:

Error, if any, returned by the server (as string)

dst_ip:

Destination IP of the DNS request

dst_port:

Destination port of the DNS request

start_ts:

Start timestamp of the DNS request

end_ts:

End timestamp of the DNS request

Sample Response
{
  "success": 1,
  "data": [
      {
        "rrname": "example.com",
        "rrtype": "A",
        "rdata": ["1.2.3.4"],
        "ttl": [86400],
        "n": 1,
        "error": None,
        "dst_ip": "192.1.68.1.250",
        "dst_port": 53,
        "start_ts": "2015-11-05 05:06:07",
        "end_ts": "2015-11-05 05:06:07",
      },
      {
        "rrname": "example.com",
        "rrtype": "MX",
        "rdata": None,
        "ttl": None,
        "n": 2,
        "error": "FORMERR",
        "dst_ip": "192.1.68.1.250",
        "dst_port": 53,
        "start_ts": "2015-11-05 10:00:07",
        "end_ts": "2015-11-05 10:00:08",
      },
  ],
}

net.pdns.view_ip(response_format)¶

Get the timeline of DNS requests from the specified source IP that, in the provided time window, obtained the given IP address as result.

URL

/papi/net/pdns/view_ip[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

src_ip:

Restrict data to DNS requests from this source IP (required)

start_time:

Start of the time window to select (required)

end_time:

End of the time window to select (required)

timezone:

Name of selected time zone

ip:

Filter for DNS replies that contanied this IP address in the rdata section (required)

key:

access_key:subkey: Restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

limit:

Limit to this number of top queried ips

Contents of successful response

A list of DNS Resouce Records ordered by timestamp (timeline). Each resource record contains the following fields:

rrname:

Resource Record Name requested by the client

rrtype:

Resource Record type, as string

rdata:

Resource data: list of results returned by the server

ttl:

list of TTL values for each of the entries appearing in rdata

n:

Number of requests grouped in this resource record

error:

Error, if any, returned by the server (as string)

dst_ip:

Destination IP of the DNS request

dst_port:

Destination port of the DNS request

start_ts:

Start timestamp of the DNS request

end_ts:

End timestamp of the DNS request

Sample Response
{
  "success": 1,
  "data": [
      {
        "rrname": "example1.com",
        "rrtype": "A",
        "rdata": ["1.2.3.4"],
        "ttl": [86400],
        "n": 1,
        "error": None,
        "dst_ip": "192.1.68.1.250",
        "dst_port": 53,
        "start_ts": "2015-11-05 05:06:07",
        "end_ts": "2015-11-05 05:06:07",
      },
      {
        "rrname": "example2.com",
        "rrtype": "A",
        "rdata": ["1.2.3.4", "5.6.7.8"],
        "ttl": [60, 3600],
        "n": 1,
        "error": None,
        "dst_ip": "192.1.68.1.250",
        "dst_port": 53,
        "start_ts": "2015-11-05 10:00:07",
        "end_ts": "2015-11-05 10:00:08",
      },
  ],
}

Geolocation¶

Method Index¶

geoip():

Get geographical information for a list of IPs

Method Documentation¶

net.location.geoip(response_format)¶

Get geografical informations for a list of IPs Returns latitude/longitude, city and country information for each IP from a given list

URL

/papi/net/location/geoip[. response_format] response_format can be xml or json (defaults to json)

Alternative URL

/papi/net/location/ip_location[. response_format] response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

ip_list

list of IPs (max 1000 allowed)

Contents of a successful response

A dictionary mapping an IP address to a dictionary with the following keys:

latitude

longitude

city

If no city information is found in the db this field will be None

country

country_code

Settings¶

Source IP Range Whitelisting¶

This API allows to whitelist source ip ranges.

Method Index¶

get_ip_range_whitelists():

Get configured source IP ranges.
add_src_ip_range_whitelist()

Add a new source IP range whitelist.
update_src_ip_range_whitelist()

Update an existing source IP range whitelist.
set_src_ip_range_whitelist_legacy()

DEPRECATED: Add/update an IP range whitelist.

Method Documentation¶

net.settings.ip_range_whitelist.get_ip_range_whitelists(response_format)¶

Get information about source ip ranges that have been whitelisted.

On-Premise availability: This API method is available for Lastline Enterprise On-Premise version >= 7.14

URL

/papi/net/settings/ip_range_whitelist/list[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

License selection:

key:

access_key[:subkey]: Get whitelists for sensors with this key

key_id:

Get whitelists with this key

subkey_id:

Get whitelists for sensors with this subkey (provide together with key_id in alternative to key)

Whitelist filters:

uuid:

Specifies a specific whitelist range to lookup by UUID. Can be a comma-separated list of UUIDs.

active:

Boolean that specifies whether the ip range is active or not. By default, this filter is not included. If set to “True” only active whitelists are returned. If set to “False” only inactive whitelists are returned.

Time information:

timezone:

Specify the timezone in which the “create_time” attribute will be converted to.

Contents of a successful response

A list of dictionaries with the following fields:

access_key_id:

Identifier of the license that the whitelist exists

subkey_id:

Identifier of the subkey that the whitelist exists

range_start:

The beginning of the whitelist IP range. This IP is inclusive to the IP range.

range_end:

The end of the whitelist ip range. This IP is inclusive to the IP range.

label:

The label of the whitelist

active:

Boolean that specifies if the whitelist is active or not

create_time:

The time in which the whitelist was created

uuid:

A unique identifier of the whitelist

net.settings.ip_range_whitelist.add_src_ip_range_whitelist(response_format)¶

Add a source whitelist range to an existing subkey

On-Premise availability: This API method is available for Lastline Enterprise On-Premise version >= 7.14

URL

/papi/net/settings/ip_range_whitelist/add[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

key:

access_key[:subkey]: Add a whitelist range for this sensor

key_id:

Add a whitelist range for a sensor with this key_id

subkey_id:

Add a whitelist range for a sensor with this subkey_id (provide together with key_id in alternative to key)

ip_range:

Specify the IPv4 range to whitelist. This can either be in the form of a single ip, dash separated ip range or a CIDR block, such as the following examples:

1.2.3.4

1.2.3.4-1.2.3.5

1.2.3.0/24

active:

Boolean that specifies whether or not this whitelist is active. Defaults to “True”

Contents of a successful response

A dictionary with the new uuid of the whitelist:

uuid:

A unique identifier of the whitelist

net.settings.ip_range_whitelist.update_src_ip_range_whitelist(response_format)¶

Update an existing source whitelist ip range.

On-Premise availability: This API method is available for Lastline Enterprise On-Premise version >= 7.14

URL

/papi/net/settings/ip_range_whitelist/update[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

uuid:

The UUID of the whitelist range to update.

ip_range:

If provided, update the whitelist range to the specified IPv4 range. This can either be in the form of a single ip, dash separated ip range or a CIDR block, such as the following examples:

1.2.3.4

1.2.3.4-1.2.3.5

1.2.3.0/24

active:

Boolean, if provided, update whether or not the whitelist is active/

Contents of a successful response

“OK”

net.settings.ip_range_whitelist.set_src_ip_range_whitelist_legacy(response_format)¶

Update or add a source whitelist ip range.

The logic to distinguish between update/add functionality is solely determined by the presence of a “uuid” parameter. If the “uuid” parameter is provided, a whitelist with the matching uuid will be updated, otherwise a whitelist range will be created.

On-Premise availability: This API method is available for Lastline Enterprise On-Premise version >= 7.14

DEPRECATED

This method is provided to ease the transition between legacy ll_api set_src_ip_range_whitelist method and the new methods in this module. It will eventually be removed.

Use get_src_ip_range_whitelists to retrieve source IP whitelist ranges. Use add_src_ip_range_whitelist to add a new source IP whitelist range. Use update_src_ip_range_whitelist to update an existing source IP whitelist range.

URL

/papi/net/settings/ip_range_whitelist/set_legacy[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters with UUID (update)

uuid:

The UUID of the whitelist range to update.
range_start:

Updates the range_start IP of the whitelist IP range. Note that this IP is inclusive to the entire range. This parameter MUST be provided in conjunction with “range_end”.
range_end:

Updates the range_end IP of the whitelist IP range. Note that this IP is inclusive to the entire range. This parameter MUST be provided in conjunction with “range_start”.
active:

Boolean, if provided, update whether or not the whitelist is active/

POST Parameters without UUID (add)

key:

access_key[:subkey]: Add a whitelist range for this sensor

key_id:

Add a whitelist range for a sensor with this key_id

subkey_id:

Add a whitelist range for a sensor with this subkey_id (provide together with key_id in alternative to key)

range_start:

As an alternative to the “ip_range” parameter, specify the start of the whitelist ip range. If specified, this parameter must be used in conjunction with the “range_end” parameter and MUST be lower and/or equal to the “range_end” ip. This IP is inclusive to the IP range.

range_end:

As an alternative to the “ip_range” parameter, specify the end of the whitelist ip range. If specified, this parameter must be used in conjunction with the “range_start” parameter and MUST be greater and/or equal to “range_end” ip. This IP is inclusive to the IP range.

active:

Boolean that specifies whether or not this whitelist is active. Defaults to “True”

Contents of a successful response

A dictionary with the following fields:

“uuid”: The UUID of the whitelist ip range that was updated/added.

Host labels¶

This API allows to label and optionally whitelist hosts in the protected network.

Method Index¶

get_host_labels():

Get configured host labels.
add_host_label():

Configure a new host label.
update_host_label():

Update an existing host label configuration.
delete_host_label():

Delete a host label configuration.
add_host_label_legacy():

DEPRECATED: add or update a host label configuration.

Method Documentation¶

net.settings.host_label.get_host_labels(response_format)¶

Retrieves the list of host labels on sensor/group of sensors

URL

/papi/net/settings/host_labels/get[. ‘response_format’]

‘response_format’ can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

key_id:

(Optional) ID of the license key whose host labels need to be retrieved

subkey_id:

(Optional) ID of the sensor whose host labels need to be retrieved

key:

(Optional) access_key[:subkey] of the sensor[s] whose host labels need to be retrieved

At least one between key_id or key must be specified.

Contents of successful response

list of dictionaries containing:

label:

Label of the host

ip:

(Optional) ip of this host (X.X.X.X form)

hostname:

(Optional) FQDN of this host

whitelisted:

Whether this label is whitelisted or not

subkey_id:

ID of the sensor under which the current label has been defined

key_id:

ID of the license under which the current label has been defined

net.settings.host_label.add_host_label(response_format)¶

Add or update an host label

URL

/papi/net/settings/host_labels/add[. ‘response_format’]

‘response_format’ can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

key:

(Optional) access_key:subkey of the sensor whose host labels need to be created/updated

key_id:

(Optional) The ID of the license key whose host labels needs to be created/updated

subkey_id

(Optional) ID of the sensor facing the device being labeled

label:

Name of the label

hostname:

(Optional) FQDN of the device being labeled

ip:

(Optional) IP of the device being labeled

whitelisted:

Whether events coming from the selected device should be hidden by default or not

Note: either key or (access_key_id, subkey_id) must be specified

Contents of successful response

“OK”

net.settings.host_label.update_host_label(response_format)¶

Add or update an host label

URL

/papi/net/settings/host_labels/update[. ‘response_format’]

‘response_format’ can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

key:

(Optional) access_key:subkey of the sensor whose host labels need to be updated

key_id:

(Optional) The ID of the license key whose host labels needs to be updated

subkey_id

(Optional) ID of the sensor facing the device being labeled

label:

Name of the label

hostname:

(Optional) FQDN of the device being labeled

ip:

(Optional) IP of the device being labeled

whitelisted:

Whether events coming from the selected device should be hidden by default or not

Note: either key or (access_key_id, subkey_id) must be specified

Contents of successful response

“OK”

net.settings.host_label.delete_host_label(response_format)¶

Delete an already existing host label

URL

/papi/net/settings/host_labels/delete[. ‘response_format’]

‘response_format’ can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

key_id:

(Optional) ID of the license key whose host labels need to be deleted

subkey_id:

(Optional) ID of the sensor whose host labels need to be deleted

key:

(Optional) access_key[:subkey] of the sensor whose host labels need to be deleted

label:

name of the label to delete

At least one between key_id or key must be specified.

Contents of successful response

“OK”

net.settings.host_label.add_host_label_legacy(response_format)¶

Add or update an host label

URL

/papi/net/settings/host_labels/add_legacy[. ‘response_format’]

‘response_format’ can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

key:

(Optional) access_key:subkey of the sensor whose host labels need to be updated

key_id:

(Optional) The ID of the license key whose host labels needs to be updated

subkey_id

(Optional) ID of the sensor facing the device being labeled

label:

Name of the label

hostname:

(Optional) FQDN of the device being labeled

ip:

(Optional) IP of the device being labeled

whitelisted:

Whether events coming from the selected device should be hidden by default or not

update:

(Optional, default False) Whether this change represents an update or a new object is created

Note: either key or (access_key_id, subkey_id) must be specified

Contents of successful response

“OK”

Breaches¶

These API methods relate to breach objects and are only available to customers with a Lastline Breach Defender license. Within the Lastline Portal breach objects are labled “intrusions”.

Method Index¶

get_breach():

Get information about a breach by the breach UUID
get_breaches():

Get information about many breaches by a list of breach UUIDs
get_breaches_phases_summary():

Get summary of breach phases involved in a number of breach objects
get_breaches_malware_summary():

Get summary of breach malware and affected hosts involved in a number of breach objects
get_breaches_hosts_summary():

Get summary of hosts involved in a number of breach objects
get_breach_malware():

Get information of which threats were detected in a breach
get_breach_phases():

Get information on which breach phases were detected on which hosts
get_breach_evidence():

Get detailed information about a breach
get_breach_incidents():

Get incident IDs that relate to a specific breach
set_breach_name():

Set the name of a breach given the breach UUID
get_breach_logs():

Get logs about a breach
get_breaches_hosts_summary():

Get the IP addresses of the hosts detected in breaches
set_breach_state():

Set the state of a breach
list_assignable_accounts():

List the allowed accounts that can be assigned intrusions within a network
assign_breach():

Assign a breach to an account
get_top_activity():

Get highest scored activities within a breach
get_top_malware():

Get highest scored malware within a breach

Method Documentation¶

net.breach.get_breach(response_format)¶

Get a breach by uuid.

Returns a single breach, in same format as the get_breaches() method. If the requested breach does not exist anymore because it has since been merged into another breach, then this will return the merged breach. In that case, the breach_uuid of the returned breach will be different from the one requested.

On-Premise availability

This API method is available as part of Lastline Breach Defender

URL

/papi/net/breach/get[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET

GET Parameters

breach_uuid:

Get a breach from this UUID (required)

timezone:

Name of the selected timezone (optional, defaults to UTC)

Contents of successful response

A dictionary containing the fields below:

access_key_id:

Identifier of the license of the sensor that detected the breach

subkey_id:

Identifier of the subkey of the sensor group that detected the breach

start_time:

The time the breach was first detected

end_time:

The time the breach was last detected

last_modified:

The last time the breach was updated

hosts_affected:

The total number of hosts affected by the breach

breach_uuid:

Identifier of the breach (if the breach was merged, then this is the destination breach’s uuid)

breach_name:

User set name of the breach

breach_phase:

The most advanced phase of the breach

breach_state:

The state the breach is in Possible values are:

OPEN

IN_PROGRESS

DONE

UPDATED

assigned_to:

A list of accounts that the breach is assigned to

impact:

Overall impact of the breach

creation_timestamp:

The time the breach was created

net.breach.get_breaches(response_format)¶

Get an overall list of breaches

On-Premise availability

This API method is available as part of Lastline Breach Defender

URL

/papi/net/breach/list[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET

GET Parameters

Time range selection:

start_time:

Get breaches after this time (required)

end_time:

Get breaches before this time (required)

timezone:

Name of the selected timezone (optional, defaults to UTC)

Appliance selection:

key:

access_key[:subkey]: Get breaches detected by sensors with this key (optional)

key_id:

Get breaches detected by sensors with this key (optional)

subkey_id:

Get breaches detected by sensors with this subkey (optional) (provide together with key_id in alternative to key)

Filters:

breach_uuids:

Get only breaches with these breach UUIDs (optional)

assigned_to:

Get only breaches assigned to any of these accounts. The value “unassigned” can be used to get only breaches that have not been assigned to anyone. This is a comma-separated list of accounts. (optional)

e.g. if the value is: “user@lastline.com,unassigned” it means we filter on

breaches assigned to user@lastline.com OR that are unassigned.

Contents of successful response

A list of dictionaries containing the fields below:

access_key_id:

Identifier of the license of the sensor that detected the breach

subkey_id:

Identifier of the subkey of the sensor group that detected the breach

start_time:

The time the breach was first detected

end_time:

The time the breach was last detected

last_modified:

The last time the breach was updated

hosts_affected:

The total number of hosts affected by the breach

breach_uuid:

Identifier of the breach

breach_name:

User set name of the breach

breach_phase:

The most advanced phase of the breach

breach_state:

The state the breach is in Possible values are:

OPEN

IN_PROGRESS

DONE

UPDATED

assigned_to:

A list of accounts that the breach is assigned to

impact:

Overall impact of the breach

creation_timestamp:

The time the breach was created

net.breach.get_breaches_phases_summary(response_format)¶

Get a full list of breach phases and the number of affected hosts for each phase

On-Premise availability

This API method is available as part of Lastline Breach Defender

URL

/papi/net/breach/phases_summary[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET

GET Parameters

Time range selection:

start_time:

Get breaches after this time (required)

end_time:

Get breaches before this time (required)

timezone:

Name of the selected timezone (optional, defaults to UTC)

Appliance selection:

key:

access_key[:subkey]: Get breaches detected by sensors with this key (optional)

key_id:

Get breaches detected by sensors with this key (optional)

subkey_id:

Get breaches detected by sensors with this subkey (optional) (provide together with key_id in alternative to key)

Filters:

breach_uuids:

Get only breaches with these breach UUIDs (optional)

assigned_to:

Get only breaches assigned to any of these accounts. The value “unassigned” can be used to get only breaches that have not been assigned to anyone. This is a comma-separated list of accounts. (optional)

e.g. if the value is: “user@lastline.com,unassigned” it means we filter on

breaches assigned to user@lastline.com OR that are unassigned.

Contents of successful response

A list of dictionaries containing the fields below:

breach_uuid:

Identifier of the breach

breach_phase:

The name of the breach phase that was detected.

hosts_affected:

The total number of hosts affected by the breach.

net.breach.get_breaches_malware_summary(response_format)¶

Get a full list of breach malware and the number of affected hosts for each malware

On-Premise availability

This API method is available as part of Lastline Breach Defender

URL

/papi/net/breach/malware_summary[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET

GET Parameters

Time range selection:

start_time:

Get breaches after this time (required)

end_time:

Get breaches before this time (required)

timezone:

Name of the selected timezone (optional, defaults to UTC)

Appliance selection:

key:

access_key[:subkey]: Get breaches detected by sensors with this key (optional)

key_id:

Get breaches detected by sensors with this key (optional)

subkey_id:

Get breaches detected by sensors with this subkey (optional) (provide together with key_id in alternative to key)

Filters:

breach_uuids:

Get only breaches with these breach UUIDs (optional)

Contents of successful response

A list of dictionaries containing the fields below:

breach_uuid:

Identifier of the breach

threat:

The name of the threat that was detected.

threat_class:

The class of the threat that was detected.

confidence:

The confidence in the evidence (0-100).

severity:

Severity of what the evidence has detected (0-100).

impact:

Overall impact of this evidence (0-100) This combines confidence and severity into an overall number.

first_seen:

Timestamp of first time this happened

last_seen:

Timestamp of last time this happened

hosts_affected:

The total number of hosts affected by the breach.

net.breach.get_breach_malware(response_format)¶

Get information of which threats were detected in a breach

On-Premise availability

This API method is available as part of Lastline Breach Defender

URL

/papi/net/breach/malware[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET

GET Parameters

breach_uuid:

Get information about the threat detected from this breach uuid (required)

timezone:

Name of the selected timezone (optional, defaults to UTC)

Contents of successful response

A list of dictionaries containing the fields below:

ip_address:

The host the threat was detected on.

threat:

The name of the threat that was detected.

threat_class:

The class of the threat that was detected.

confidence:

The confidence in the evidence (0-100).

severity:

Severity of what the evidence has detected (0-100).

impact:

Overall impact of this evidence (0-100) This combines confidence and severity into an overall number.

first_seen:

Timestamp of first time this happened

last_seen:

Timestamp of last time this happened

latest_breach_phase:

The name of the latest phase that was detected for this host and malware combination

net.breach.get_breach_phases(response_format)¶

Get information on which breach phases were detected on which hosts.

On-Premise availability

This API method is available as part of Lastline Breach Defender

URL

/papi/net/breach/phases[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET

GET Parameters

breach_uuid:

Get breach phases about this breach uuid (required)

Contents of successful response

A list of dictionaries containing the fields below:

ip_address:

The host the phase of the breach was detected on.

breach_phase:

The name of the breach phase that was detected.

net.breach.get_breach_evidence(response_format)¶

Get detailed information about a breach

On-Premise availability

This API method is available as part of Lastline Breach Defender

URL

/papi/net/breach/evidence[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET

GET Parameters

breach_uuid:

Get breach phases about this breach uuid (required)

timezone:

Name of the selected timezone (optional, defaults to UTC)

extended:

Fetch extra information for each piece of evidence (available for Lastline Enterprise On-Premise versions >= 9.2)

Contents of successful response

A list of dictionaries containing the fields below. If a field is missing in the response, then the field does not contain a value.

threat:

Name of detected threat. Called “malware” in Lastline Portal.

threat_class:

Class name of detected threat. Called “malware” in Lastline Portal.

confidence:

Confidence in the evidence (0-100).

severity:

Severity of what the evidence has detected (0-100).

impact:

Overall impact of this evidence (0-100) This combines confidence and severity into an overall number.

evidence_type:

Type of evidence detected.

detector:

Name of detector that detected this evidence.

activity:

Name of detected activity.

subject:

Subject of evidence. Semantics of this field can vary depending on evidence_type.

signature_id:

Identifier of network signature that detected this evidence. This is currently for customer-provided signatures at the moment.

reference_type:

Type of reference alert for this evidence. This is one of “NETWORK_EVENT”, “ENDPOINT_ALERT”, or “EMAIL”.

reference_id:

Identifier of reference alert.

reference_time:

Timestamp of reference alert.

incident_id:

Identifier of the incident.

breach_phase:

Name of the phase of the breach this evidence is related to.

ip_address:

The host the evidence was detected on.

first_seen:

The time the evidence was first detected.

last_seen:

The time the evidence was last detected.

If the extended parameter is set, some or all of the following fields depending on the evidence details:

May be present when reference_type is “NETWORK_EVENT”:

blacklist_match_info:

BlacklistMatchInfo object for this reference event

detector_goal:

The goal of the detector

dga_domains:

DGA domains for reference event

dga_domain_count:

Number of DGA domains for reference event

download_file_type:

File type of the downloaded file

download_file_name:

File name of the downloaded file

llanta_rule_name:

Name of the llanta rule

reference_event:

Information about the reference event. See network_event.get_event for info.

urls:

List of URLs associated with reference event

May be present when the reference_type is “EMAIL”:

reference_mail:

A dictionary with that may include the following fields:

Taken from the mail message:

access_key_id

Identifier of license of sensor that detected the mail

mail_message_id:

Identifier of the mail message

**mail_message_log_id:

Identifier of the mail message in the log storage

message_action:

Action taken on this mail message Possible values are:

BLOCK

LOG

message_id:

Identifier of the mail message (extracted from the message itself)

recipient:

Recipient of the mail message

sender:

Sender of the mail message

subject:

Subject of the mail message

subkey_id:

Identifier of subkey of sensor that detected the mail

date:

Date of reception of the mail message (extracted from the received mail message itself), in requested timezone

time:

Same as “date” above

timestamp:

Timestamp of when the mail was received by the sensor

Taken from the mail detection (url or attachment):

action:

Action taken on this detection Possible values are:

BLOCK

WARN

LOG

TEST

file_name:

Name of the mail attachment

file_type:

File type of the mail attachment: detailed string

file_size:

Size of the mail attachment, in bytes

llfiletype:

File type of the mail attachment: high level category (e.g., Executable, Document, Java, Pdf)

md5:

MD5 hash of the mail attachment or url

raw_url:

Raw version of the malicious url

score:

Lastline score for the mail attachment or url (0-100)

sha1:

SHA-1 hash of the mail attachment

task_uuid:

Lastline Engine task UUID of the url or attachment

url:

Human readable version of the malicious url

net.breach.get_breach_incidents(response_format)¶

Get incidents ids relating to a specific breach

On-Premise availability

This API method is available as part of Lastline Breach Defender

URL

/papi/net/breach/incidents[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET

GET Parameters

breach_uuid:

Get breach phases about this breach uuid (required)

Contents of successful response

A list of identifiers for breach incidents, for example:

[1, 2, 3]

net.breach.set_breach_name(response_format)¶

Set the name of a breach given the breach UUID

On-Premise availability

This API method is available as part of Lastline Breach Defender

URL

/papi/net/breach/set_breach_name[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

POST

POST Parameters

breach_uuid:

The unique identifier for the breach

breach_name:

The name to set for the breach

Contents of successful response

“OK”

net.breach.get_breach_logs(response_format)¶

Get logs about a breach

On-Premise availability

This API method is available as part of Lastline Breach Defender

URL

/papi/net/breach/logs[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET

GET Parameters

breach_uuid:

The unique identifier for the breach (required)

start_time:

Get breach logs after this time (optional)

end_time:

Get breach logs before this time (optional)

timezone:

Name of the selected timezone (optional, defaults to UTC)

Contents of successful response

A list of dictionaries containing the fields below:

event_type:

Type of the breach event, possible types include:

ADD_EVIDENCE

ADD_INCIDENT

CREATE

MERGE

REMOVE_EVIDENCE

UPDATE

message:

Message describing creation or modification of the breach object

reason:

Reason why the breach object was created or modified

rule:

Correlation rule that caused the breach log entry

ts:

The timestamp the breach log was logged

entities:

Sequence of dictionaries containing information about entities involved in this breach log entry containing the following keys:

entity_id:

The identifier of the object involved in the event, e.g., an incident_id.

entity_type:

The type of the entity involved in the event, one of:

BREACH

INCIDENT

MAIL

ts:

The time the entry was logged

net.breach.get_breaches_hosts_summary(response_format)¶

Get the IP addresses of the hosts detected in breaches

On-Premise availability

This API method is available as part of Lastline Breach Defender

URL

/papi/net/breach/hosts_summary[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET

GET Parameters

Time range selection:

start_time:

Get breaches after this time (required)

end_time:

Get breaches before this time (required)

timezone:

Name of the selected timezone (optional, defaults to UTC)

Appliance selection:

key:

access_key[:subkey]: Get breaches detected by sensors with this key (optional)

key_id:

Get breaches detected by sensors with this key (optional)

subkey_id:

Get breaches detected by sensors with this subkey (optional) (provide together with key_id in alternative to key)

Filters:

breach_uuids:

Get only breaches with these breach UUIDs (optional)

Contents of successful response

A list of dictionaries containing the fields below:

breach_uuid:

Identifier of the breach

ip_address:

The host the breach was detected in.

net.breach.set_breach_state(response_format)¶

Set the state of a breach given the breach UUID

On-Premise availability

This API method is available as part of Lastline Breach Defender

URL

/papi/net/breach/set_breach_state[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

POST

POST Parameters

breach_uuid:

The unique identifier for the breach

breach_state:

The state to set for the breach (one of “OPEN”, “DONE”, “UPDATED”, or “IN_PROGRESS”)

Contents of successful response

“OK”

net.breach.list_assignable_accounts(response_format)¶

List the allowed accounts that can be assigned intrusions within a network

On-Premise availability

This API method is available as part of Lastline Breach Defender

URL

/papi/net/breach/list_assignable_accounts[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET

GET Parameters

key:

access_key[:subkey]: Get accounts that can be assigned intrusions within the network

key_id:

Get accounts that can be assigned intrusions of any network with the key

subkey_id:

Get accounts that can be assigned to the network (provide together with key_id in alternative to key)

Contents of successful response

A list of strings for the accounts that can be assigned intrusions within the network

[“user@lastline”, “user2@lastline.com“]

net.breach.assign_breach(response_format)¶

Assign a breach to an account

On-Premise availability

This API method is available as part of Lastline Breach Defender

URL

/papi/net/breach/assign[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

POST

POST Parameters

breach_uuid:

The unique identifier for the breach

account:

An account to assign the breach to. The value “unassigned” can be used to unassign the breach from an account.

Contents of successful response

“OK”

net.breach.get_top_activity(response_format)¶

Get highest scored activities for given breach uuid.

On-Premise availability

This API method is available for Lastline Defender On-Premises versions >= 8.3

URL

/papi/net/breach/top/activity[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET

GET Parameters

max_results:

Limit to this many results (optional) Defaults to 10

breach_uuid:

Get top activity for breach with this uuid (required)

Contents of successful response

A list of dictionaries containing the fields below:

activity:

The activity

score:

The score assigned to the activity

net.breach.get_top_malware(response_format)¶

Get highest scored malware for given breach uuid.

On-Premise availability

This API method is available for Lastline Defender On-Premises versions >= 8.3

URL

/papi/net/breach/top/malware[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET

GET Parameters

max_results:

Limit to this many results (optional) Defaults to 10

breach_uuid:

Get top malware for breach with this uuid (required)

Contents of successful response

A list of dictionaries containing the fields below:

source:

The malware source

malware:

The malware

score:

The score assigned to the malware

Analysis Task¶

These API methods relate to analysis tasks.

Method Index¶

get_analysis_task_typed_tags():

Get additional information about an analysis task in the form of typed tags
list_analysis_task_typed_tag_types():

Get the possible types of tags for analysis tasks
list_analysis_task_typed_tag_values():

Get all possible values for an analysis task typed tag
get_top_activity():

Get highest scored activities within a network for given capture types
get_top_malware():

Get highest scored malware within a network for given capture types

Method Documentation¶

net.analysis_task.get_analysis_task_typed_tags(response_format)¶

Get additional information about an analysis task in the form of typed tags.

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >=7.17.

URL

/papi/net/analysis_task/typed_tags[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET

GET Parameters

task_uuid:

The unique identifier of the analysis task (required)

start_time:

Get Analysis Task Typed Tags after this time (required)

end_time:

Get Analysis Task Typed Tags before this time (required)

timezone:

Name of the selected timezone

tag_type:

Filter on task’s typed tags with this type (optional)

Contents of successful response

A list of dictionaries containing the fields below.

tag_type:

The type of the task’s typed tag type, e.g., “activity”

tag_value:

The value of the task’s typed tag value, e.g., “Evasion:Hide network activity through code injection”

net.analysis_task.list_analysis_task_typed_tag_types(response_format)¶

Get the possible types of tags for analysis tasks.

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >=7.17

URL

/papi/net/analysis_task/typed_tag/types[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET

GET Parameters

task_uuid:

The unique identifier of the analysis task (optional)

Contents of successful response

A list of strings for all possible types of analysis task tags.

net.analysis_task.list_analysis_task_typed_tag_values(response_format)¶

Get all possible values for an analysis task typed tag.

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >=7.17

URL

/papi/net/analysis_task/typed_tag/values[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET

GET Parameters

Sorting and pagination:

max_results:

Limit to this many results

offset_results:

Skip the first offset_results results.

Filters:

tag_type:

Filter on tag values with this type (optional)

tag_value:

Filter on tag values whose value contains this string, case-insensitive comparison (optional)

Contents of successful response

A list of dictionaries containing the fields below.

tag_type:

The type of the task’s typed tag type, e.g., “activity”

tag_value:

The value of the task’s typed tag value, e.g., “Evasion:Hide network activity through code injection”

net.analysis_task.get_top_activity(response_format)¶

Get highest scored activities in the given network.

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >= 8.3

URL

/papi/net/analysis_task/top/activity[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET

GET Parameters

Network selection:

key:

access_key[:subkey]: Restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

max_results:

Limit to this many results (optional) Defaults to 10

Time range selection:

start_time:

Get top activities after this time (required)

end_time:

Get activities before this time (required)

timezone:

Name of the selected timezone (optional, defaults to UTC)

Filters:

capture_types:

Get top activity for the given capture_types (optional) FILE_DOWNLOAD, MAIL_MESSAGE, WEB_URL Includes all by default

Contents of successful response

A list of dictionaries containing the fields below:

activity:

The activity

score:

The score assigned to the activity

net.analysis_task.get_top_malware(response_format)¶

Get highest scored malware in the given network.

On-Premise availability

This API method is available for Lastline Defender On-Premises versions >= 8.3

URL

/papi/net/host_info/top/malware[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET

GET Parameters

max_results:

Limit to this many results (optional) Defaults to 10

Network selection:

key:

access_key[:subkey]: Restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

Time range selection:

start_time:

Get top malware after this time (required)

end_time:

Get malware before this time (required)

timezone:

Name of the selected timezone (optional, defaults to UTC)

Filters:

capture_types:

Get top malware for the given capture_types (optional) FILE_DOWNLOAD, MAIL_MESSAGE, WEB_URL Includes all by default

Contents of successful response

A list of dictionaries containing the fields below:

source:

The malware source

malware:

The malware

score:

The score assigned to the malware

Host Info¶

These API methods relate to information about a specific host.

Method Index¶

get_ip_hostname():

Get hostnames associated with a specific host
get_top_activity():

Get highest scored activities on a host
get_top_malware():

Get highest scored malware on a host

Method Documentation¶

net.host_info.get_ip_hostname(response_format)¶

Get hostnames associated with an IP address

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >= 8.2

URL

/papi/net/host_info/ip_hostname[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Time range selection:

start_time:

Get associations after this time (required)

end_time:

Get associations before this time (required)

timezone:

Name of selected time zone

Appliance selection:

key:

access_key[:subkey]: Get information detected by sensors with this key

key_id:

Get information detected by sensors with this key

subkey_id:

Get information detected by sensors with this subkey (provide together with key_id in alternative to key).

Pagination:

max_results:

Limit to this many results

offset_results:

Skip the first offset_results results.

Sorting:

orderby: specify a custom sort value and direction, available sort values include:

“first_seen”

Filters:

ip_addresses:

Get only information relating to these IP addresses

hostnames:

Get only information relating to these hostnames

source_name:

Get only information relating to associations from this source This includes the values:

“DNSPTR”

“PROXY_AUTHORIZATION”

“DHCP_LOG”

Contents of succesful response

A list of dictionaries with the following keys:

first_seen:

Start time when first observed

last_seen:

End time when last observed

ip_address:

The IP address observed by the sensor

hostname:

The hostname associated with the IP address

source:

The source of the information about the association

net.host_info.get_top_activity(response_format)¶

Get highest scored activities for given host ip.

On-Premise availability

This API method is available for Lastline Defender On-Premises versions >= 8.3

URL

/papi/net/host_info/top/activity[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET

GET Parameters

max_results:

Limit to this many results (optional) Defaults to 10

Host selection:

ip_address:

Get top activity for host with this ip (required)

Time range selection:

start_time:

Get top activities after this time (required)

end_time:

Get activities before this time (required)

timezone:

Name of the selected timezone (optional, defaults to UTC)

Contents of successful response

A list of dictionaries containing the fields below:

activity:

The activity

score:

The score assigned to the activity

net.host_info.get_top_malware(response_format)¶

Get highest scored malware for host with given ip.

On-Premise availability

This API method is available for Lastline Defender On-Premises versions >= 8.3

URL

/papi/net/host_info/top/malware[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET

GET Parameters

max_results:

Limit to this many results (optional) Defaults to 10

Host selection:

ip_address:

Get top malware for host with this ip (required)

Time range selection:

start_time:

Get top malware after this time (required)

end_time:

Get malware before this time (required)

timezone:

Name of the selected timezone (optional, defaults to UTC)

Contents of successful response

A list of dictionaries containing the fields below:

source:

The malware source

malware:

The malware

score:

The score assigned to the malware

Tagging¶

Method Index¶

add_host_tag():

Add tag to a host
remove_host_tag():

Remove tag from a host
add_hosts_tag():

Add a tag to a sequence of hosts
remove_hosts_tag():

Remove a tag from a sequence of hosts
list_host_tags():

List all host tags within given selection
list_distinct_host_tags():

List all distinct host tags within given selection

Method Documentation¶

net.tag.add_host_tag(response_format)¶

Add tag to a host.

URL

/papi/net/tag/host/add[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

key:

access_key[:subkey]: Select host with this key.

key_id:

Select host with this access key id.

subkey_id:

Select host with this subkey (provide together with key_id in alternative to key). The subkey should be the representative of the sensor group that the sensor belongs to.

ip_address:

IP Address to select host that the tag will be applied to.

tag:

The tag to be added to the host.

Contents of successful response

“OK”

net.tag.remove_host_tag(response_format)¶

Remove tag from a host.

URL

/papi/net/tag/host/remove[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

key:

access_key[:subkey]: Select host with this key.

key_id:

Select host with this access key id.

subkey_id:

Select host with this subkey (provide together with key_id in alternative to key). The subkey should be the representative of the sensor group that the sensor belongs to.

ip_address:

IP Address of the host that the tag will be removed from.

tag:

The tag to be removed from the sensor group with given ip address.

Contents of successful response

“OK”

net.tag.add_hosts_tag(response_format)¶

Add tag to a hosts.

URL

/papi/net/tag/host/add[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

key:

access_key[:subkey]: Select appliances with this key.

key_id:

Select appliances with this access key id.

subkey_id:

Select appliances with this subkey(provide together with key_id in alternative to key). The subkey should be the representative of the sensor group that the sensor belongs to.

ip_addresses:

List of IP Addresses of the hosts that the tag will be applied to

tag:

The tag to be added to the sensor group with given ip address.

Contents of successful response

“OK”

net.tag.remove_hosts_tag(response_format)¶

Remove tags from hosts.

URL

/papi/net/tag/host/remove[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

key:

access_key[:subkey]: Select appliances with this key.

key_id:

Select appliances with this access key id.

subkey_id:

Select appliances with this subkey(provide together with key_id in alternative to key). The subkey should be the representative of the sensor group that the sensor belongs to.

ip_address:

List of IP Addresses of the hosts that the tag will be removed from.

tag:

The tag to be removed from the sensor group with given ip address.

Contents of successful response

“OK”

net.tag.list_host_tags(response_format)¶

Get a list of tags in given network.

URL

/papi/net/tag/host/list[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

key:

access_key[:subkey]: Select appliances with this key.

key_id:

Select appliances with this access key id.

subkey_id:

Select appliances with this subkey(provide together with key_id in alternative to key). The subkey should be the representative of the sensor group that the sensor belongs to.

ip_addresses:

List of IP Address to filter on. This is a comma-separated list of IP range specifiers, each of which can be one of:

A single IP address (e.g. “192.168.1.2”)

A range of IP addresses (e.g. “192.168.1.0-192.168.1.255”)

A CIDR range (e.g. “192.168.1.0/24”)

tags:

List of tags to filter on.

tag_substr:

Filter on tags with this substring.

Sorting and pagination:

max_results:

Limit to this many results

Contents of successful response

A list of dictionaries containing the fields below.

access_key_id:

The access_key_id representing the network.

network_id:

The network_id representing the sensor group.

ip_address:

The IP address in the sensor group.

tag:

The tag added to the sensor group with given IP.

net.tag.list_distinct_host_tags(response_format)¶

Get a list of distinct tags in given network.

URL

/papi/net/tag/host/list[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

key:

access_key[:subkey]: Select appliances with this key.

key_id:

Select appliances with this access key id.

subkey_id:

Select appliances with this subkey(provide together with key_id in alternative to key). The subkey should be the representative of the sensor group that the sensor belongs to.

ip_addresses:

List of IP Address to filter on. This is a comma-separated list of IP range specifiers, each of which can be one of:

A single IP address (e.g. “192.168.1.2”)

A range of IP addresses (e.g. “192.168.1.0-192.168.1.255”)

A CIDR range (e.g. “192.168.1.0/24”)

tags:

List of tags to filter on.

tag_substr:

Filter on tags with this substring.

Sorting and pagination:

max_results:

Limit to this many results

Contents of successful response

A list of all tags.

Unique Detections¶

These API methods retrieve information about what has been detected.

Method Index¶

get_detections():

Get information about unique detections
list_next_interesting():

Get the list of next interesting detections to look at

Method Documentation¶

net.detection.get_detections(response_format)¶

Get the unique detections which match the specified filters

On-Premise availability

This API method is available as part of Lastline Breach Defender

URL

/papi/net/detection/list[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET

GET Parameters

Time range selection:

min_first_seen:

Get detections first seen at or after this time

max_first_seen:

Get detections first seen at or before this time

min_last_seen:

Get detections last seen at or after this time

max_last_seen:

Get detections last seen at or before this time

timezone:

Name of selected time zone

Network selection:

key:

access_key[:subkey]: Restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

Filters:

min_score:

Get detections with at least this score

max_score:

Get detections with at most this score

detection_type:

Get detections of these types. This is a comma-separated list of types. Supported types are: “blacklist”, “network anomaly”, “lastline network signature”, “custom network signature”, and “custom nta signature”

Sorting and pagination:

orderby:

Sort results based on this parameter. Can be one of:

first_seen [ASC|DESC] to sort by first seen time last_seen [ASC|DESC] to sort by last seen time score [ASC|DESC] to sort by score

max_results:

Limit to this many results

Contents of successful response

A list of dictionaries containing the fields below:

access_key_id:

Identifier of license of sensor related to this item

subkey_id:

Identifier of subkey of sensor group related to this item

first_seen:

The time this item was first detected

last_seen:

The time this item was last detected

score:

The score attributed by the last analysis

detection_type:

The type of this detection. Supported types are: “blacklist”, “network anomaly”, “lastline network signature”, “custom network signature”, and “custom nta signature”

detection_reference_type:

The type of the reference event for this detection. Supported type is: “NETWORK_EVENT”

reference_id:

Identifier of the reference event

reference_time:

The time of the reference event

detection_parameters:

A dictionary containing the parameters of this unique detection. The keys and their meaning depends on detection_type

display:

A human-readable rendition of the detection parameters (e.g. the domain or IP for a blacklist hit)

threat:

Threat associated with this detection

threat_class:

Threat class associated with this detection

**Example response **

[

{

“access_key_id”: 1, “subkey_id”: 1, “first_seen”: “2018-01-23 11:23:58”, “last_seen”: “2018-08-08 08:08:08”, “score”: 50, “detection_type”: “blacklist”, “detection_reference_type”: “NETWORK_EVENT”, “reference_id”: “123”, “reference_time”: “2018-01-23 11:23:58”, “detection_parameters”: {“entry”: “blacklisted.host.com”}, “display”: “blacklisted.host.com”, ‘threat’: ‘FileBulldog’, ‘threat_class’: ‘adware’,

}, {

“access_key_id”: 1, “subkey_id”: 2, “first_seen”: “2018-03-05 01:02:03”, “last_seen”: “2018-09-04 02:01:00” “score”: 60, “detection_type”: “signature”, “detection_reference_type”: “NETWORK_EVENT”, “reference_id”: “456”, “reference_time”: “2018-03-05 01:02:03”, “detection_parameters”: {“custom_signature_id”: 2}, “display”: “My custom rule”, ‘threat’: ‘FileBulldog’, ‘threat_class’: ‘adware’,

}

]

net.detection.list_next_interesting(response_format)¶

Get the list of next interesting detections to look at.

Starting from a specified context, this method returns a list of possible target views to look at to find the next interesting detections.

On-Premise availability

This API method is available for On-Premise versions >= 8.4

URL

/papi/net/detection/next_interesting/list[. response_format]

response_format can be xml or json (defaults to json).

HTTP METHOD

GET

GET Parameters

Time range selection:

start_time:

Start of the time range selection

end_time:

End of the time range selection

timezone:

Name of selected time zone

Network selection:

key:

access_key[:subkey]: Restrict to appliances with this key.

key_id:

Restrict to appliances with this access key id.

subkey_id:

Restrict to appliances with this subkey (provide together with key_id in alternative to key).

Filters:

context:

The current context under analysis. Depending on the context, different suggested next detections are returned by this method. E.g., if the context is “intrusions” they won’t include intrusion information. Currently supported contexts are:

INTRUSIONS

if an unknown context is provided, all possible next detections are returned.

homenet

3-value Boolean. If set to True only return data where the host involved in the detection is in the homenet, if set to False only return data where the host is not in the homenet, if not set return everything.

whitelisting

Boolean parameter to exclude detections on whitelisted sources

Contents of successful response

A list of dictionaries containing the fields below:

destination_name:

Name of the target destination view. Currently supported:

intrusions

hosts

suspicious file downloads

suspicious emails

network anomalies

target_view:

Symbolic name for the destination view. Currently supported:

intrusions

hosts

file downloads

email detections

network events

filters:

Sequence of dictionaries, representing the filters to use on the target endpoint, with fields:

filter:

Name of the filter

value:

Value of the filter

description:

Human-readable description of this interesting detection

stats:

Dictionary containing stats about the detection, with different keys depending on the destination

count:

Counter representing the number of interesting detections found for the target view

**Example response **

[

{

“destination_name”: “suspicious file downloads”, “target_view”: “file downloads”, “filters”: [

{

“filter”: “min_score”, “value”: 30,

},

], “description”: “detected 25 suspicious file downloads on 7 hosts”, “stats”: {

“downloads”: 25, “hosts”: 7,

},

},

]