Lastline Push Detection API

The Lastline Push Detection API is accessible at:

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

The purpose of this API is to push detection information collected by third party tools into Lastline Enterprise.

Sample API Clients

The sample python API clients can be downloaded here.

This sample client is provided by Lastline for use by customers and includes:

  • papi_client/api/push_detection:

    a push_detection module that provides access to most of the functionality of the Lastline Push Detection API

  • examples/analyse_captured_file.py:

    a sample python script that submits a captured file for analysis and - if the score of the file is greater than threshold(default=30) - uses this client to push a corresponding event “file downloaded” to the Lastline Push Detection API

  • examples/analyse_captured_mail.py:

    a sample python script that submits a captured mail for analysis and - if the score of the file is greater than threshold(default=30) - uses this client to push a corresponding event “mail_captured” to the Lastline Push Detection API

  • scripts/papi_shell.py:

    an ipython-based interactive shell, where the intel client is accessible as client.push_detection. This can be used to interactively explore the functionality of the Lastline Push Detection API.

File Capture

Method Index

Method Documentation

push_detection.file_capture.push_file_download(response_format)

Push an event “file downloaded”

URL

/papi/push_detection/file_capture/push_file_download[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

Required parameters:

  • task_uuid:

    UUID of the analysis task that analysed the downloaded file

  • src_ip:

    IP of the host in the protected network that downloaded the file

  • dst_ip:

    IP of the host the file has been downloaded from; only one of (dst_ip, dst_hostname) is required

  • dst_hostname:

    Name of the host the file has been downloaded from; only one of (dst_ip, dst_hostname) is required

  • application_protocol:

    Protocol used to download file: currently HTTP, HTTPS, FTP, SMB or “other”

  • filename:

    full path of the downloaded file

  • vendor_name:

    Vendor’s name of the reporting tool

  • tool_name:

    Name of the reporting tool

Network selection:

  • key:

    Push download event as if detected by this sensor. The key must be a full license key of a Lastline Enterprise Sensor that includes both an access key and a subkey. Format: “access_key:subkey”:

  • key_id:

    Id of the key (provide together with subkey_id an alternative to key).

  • subkey_id:

    Subkey id (provide together with key_id an alternative to key).

Optional parameters:

  • download_time:

    Time of the download

  • transport_protocol:

    Transport protocol used to download: currently TCP or UDP

  • src_port:

    Port used on the host in the protected network during transfer

  • dst_port:

    Port used on the host the file has been downloaded from during transfer

  • src_hostname:

    Name of the host in the protected network that downloaded the file

  • tool_version:

    Version of the reporting tool

Parameters for HTTP / HTTPS:

  • http_user_agent:

    user agent used for the download

  • http_referer:

    referer of the download

  • http_content_disposition_filename:

    filename suggested by the remote server

Parameters for FTP:

  • ftp_mode:

    FTP mode used during transfer: one of “active” or “passive”

  • ftp_direction:

    direction of transfer: one of “upload” or “download”

Parameters for SMB:

  • smb_direction:

    direction of transfer: one of “read” or “write”

  • smb_mount_point:

    mount point of the SMB share

Contents of successful response

“OK”

Limitations

  • The task_uuid must be obtained with a submission to the Lastline Analyst API using the same license key that is used for this call. This limitation may be removed in a future version.

IOC

Method Index

Method Documentation

push_detection.ioc.push_result(response_format)

Push an IOC result

URL

/papi/push_detection/push_result[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

Required parameters:

  • vendor_name:

    Vendor’s name of the reporting tool

  • tool_name:

    Name of the reporting tool

  • ioc_uuid:

    UUID of the IOC

  • ioc_source:

    Source of the IOC

  • main_ipv4:

    Main IP v4 address of the host on which the IOC has been checked (required if main_ipv6 is not defined)

  • main_ipv6:

    Main IP v6 address of the host on which the IOC has been checked (required if main_ipv4 is not defined)

  • ioc_matched:

    Set to True if the IOC matched

  • match_confidence:

    Confidence in the IOC match

  • hostname:

    Name of the host on which the IOC has been checked

  • key:

    String “key:subkey” used to identify the network on which the tested host is connected to

Optional parameters:

  • tool_version:

    Version of the reporting tool

  • check_time_start:

    Timestamp when the check was started (in seconds since the epoch)

  • check_time_end:

    Timestamp when the check was finished (in seconds since the epoch)

  • ad_domain:

    Name of the Active Directory domain the tested host belongs to

  • workgroup:

    Name of the Windows workgroup the tested host belongs to

  • netbios_name:

    NetBIOS name of the tested host

Contents of successful response

“OK”

Mail Capture

Method Index

Method Documentation

push_detection.mail_capture.push_mail(response_format)

Push a mail object to server

URL

/papi/push_detection/mail_capture/push_mail[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

Required parameters:

  • mail_json_str:

    JSON string representing the mail object: {

    “message”: {

    “message_id”: ASCII string - message_id header from email. Required, “date”: ASCII string - Date in format as specified by RFC2822. Optional, “sender”: ASCII string - either From: header(friendly name excluded) or

    MAIL_FROM envelope header. Required,

    “recipients”: list of ASCII strings - recipient addresses. May NOT include

    friendly name. Required,

    “subject”: unicode - subject header of email. Required, “received_timestamp”: ASCII string - UTC date time field in the fornmat

    “YYYY-MM-DD HH:MM:SS”. Defaults to current time UTC.

    }, “attachments”: [

    {

    “filename”: ASCII string - Required “size”: int - file size. Required “task_uuid”: string - UUID assigned by Lastline software when submitting

    for analysis. Optional.

    “action”: ASCII string - One for the following: ‘LOG’, ‘WARN’, ‘BLOCK’.

    Defaults to ‘LOG’

    }

    ], “urls”: [

    {

    “url”: ASCII string - url including any arguments. Required, “task_uuid”: - UUID assigned by Lastline software when submitting for

    analysis. Optional,

    “action”: ASCII string - One for the following: ‘LOG’, ‘WARN’, ‘BLOCK’.

    Defaults to ‘LOG’

    }

    ], “action”: ASCII string - One for the following: ‘LOG’, ‘BLOCK’. Defaults to ‘LOG’

    }

  • vendor_name: unicode - name of the vendor for the reporting tool

  • tool_name: unicode - name of the reporting tool

Network selection:

  • key:

    Push download event as if detected by this sensor. The key must be a full license key of a Lastline Enterprise Sensor that includes both an access key and a subkey. Format: “access_key:subkey”:

  • key_id:

    Id of the key (provide together with subkey_id an alternative to key).

  • subkey_id:

    Subkey id (provide together with key_id an alternative to key).

Optional parameters:

  • tool_version: ASCII string - version of the reporting tool

Contents of successful response

“OK”

Sample JSON message: {

“message”: {
“message_id”: “asdfasdasfdsasdrfe3434fs”, “date”: “Tue, 1 May 2018 17:24:16 -0400 (EST)”, “sender”: “support@corp.com”, “recipients”: [“jane.doe@corp.com”,”support@corp.com>”], “subject”: “Mail subject”, “received_timestamp”: “2018-06-04 10:11:12”

}, “attachments”: [

{
“filename”: “somefile.exe”, “size”: 23454234, “task_uuid”: “88450dbe3c0600000ffa2b3a90b8560d”, “action”: “WARN”

}

], “urls”: [

{
“url”: “https://evil.hacker.com”, “task_uuid”: “dcbadcbadcbadcbadcbadcbadcbadcba”, “action”: “LOG”

}

], “action”: “LOG”

}