Lastline Threat Intelligence API

The Lastline Threat Intelligence API is accessible at:

The purpose of this API is to give users access to threat intelligence produced by Lastline.

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/intel:

    an intel module that provides access to most of the functionality of the Lastline Threat Intelligence API

  • papi_client/api/intel_artifact_feed:

    an intel_artifact_feed module that provides access to the Lastline Malicious Artifact Threat Intelligence and its Malicious Artifact Feed presented below

  • scripts/papi_shell.py:

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

Intelligence feeds

The Lastline Intelligence API offers functionality to download the following feeds from Lastline’s hosted backend:

  • Malicious Artifact Feed:

    The Malicious Artifact Feed contains information about artifacts seen and detected as malicious by Lastline. The feed is updated hourly and every new version is released as a full bootstrap file or a delta file from past versions. Users can download this feed and maintain their own local cache of the feed (e.g. local database). Access to this feed requires a valid license for the Malicious Artifact Threat Intelligence.

  • Threat Intelligence Feed:

    The Threat Intelligence Feed contains a list of blacklisted domain names and IP addresses with some metadata about them.

Methods

Method Index

Malicious Artifact Feed:

Threat Intelligence Feed:

Lastline threat metadata access:

Lastline offline mode:

Method Documentation

intel.artifact_feed.get_malicious_artifact_feed()

Get the Lastline’s feed of malicious artifacts. Access to this API requires a valid license for the Malicious Artifact Threat Intelligence. It is only available on Lastline’s hosted backend.

URL

/papi/intel/lastline/artifact_feed/download

HTTP METHOD

GET

GET Parameters

  • username:

    account name to use to authenticate the request

  • password:

    account password to use to authenticate the request

  • origin_version:

    current version of the artifact feed held by the client (optional, if not set, the server will send back a full bootstrap of the artifact feed).

  • feed_format:

    format of the artifact feed requested (optional, if not set, default to 1). This API supports version 1 only for now. Any other value will raise an error.

Contents of successful response

CSV file containing the malicious artifact feed. Metadata about the feed is provided in the form of a header using a commented line format. The CSV fields are described in the header depending on the feed format.

Depending on the client version of origin and the latest released version, this might be a simple delta or a full bootstrap containing all the samples. Note that even if the client sends a version, the server might decide to send the full copy (for example if the client’s version is too old). The client can determine from the file header whether the returned file is a delta or a full bootstrap using the OriginVersion presented below.

Delta and bootstrap files all share the same format.

Header Format: Header lines are commented lines using # at the start of the line. The header contains important information about the feed:

  • # :BaseVersion: <Released version returned by the API>
  • # :OriginVersion: <Origin version held by the client for delta, 0 for full bootstrap>
  • # :Generation: <Generation timestamp>
  • # :FormatVersion: <Format version number>
  • # :Format: <Ordered list of names for the CSV fields>
  • # :Field: <type> <name>

Feed Format: Every line of the CSV file correspond to an operation applied to the feed:

  • add: Adding new artifact to the feed
  • del: Deleting artifact from the feed (mandatory)
  • fad: Fading artifact out of the feed (optional, depend on the client retention policy)

The fading operations are provided by Lastline as recommendations for the implementation of a retention policy by the client. Alternatively, the client can use the operation timestamps to define their own retention policy.

Error codes
  • 304

    Returned when the client already hold the latest revision

  • 403

    Returned when authentication was not successful

  • 422

    Returned when invalid or missing parameters are sent in the request

  • 503

    Returned when the service is temporarily unavailable

intel.blacklist.get_threat_intel_feed(response_format)

Export the Threat Intelligence Feed

This API is a drop-in replacement for a legacy API that was served from previct-api-blacklist:

/papi/blacklist/export

It is only available on Lastline’s hosted backend and requires a Lastline Threat Intelligence license and the customer permission “Can manage custom threat intelligence entries”.

To test out this functionality, log in to the user Portal and visit:

The response should be similar to the example shown below:

{
“data”: {
“blacklist”: {

“removed”: [], “added”: [

{
“impact”: 50, “threat_class”: “command&control”, “confidence”: 50, “severity”: 100, “ip”: “185.45.24.254”, “threat”: “Feodo”,

}, {

“impact”: 80, “threat_class”: “command&control”, “domain”: “veiseyjnutgk.com”, “severity”: 100, “confidence”: 80, “threat”: “Zusy”,

},

],

}, “base_version”: 0, “version”: 122875, “type”: “full”,

}, “success”: 1,

}

URL

/papi/intel/lastline/blacklist/export_threat_intel_feed

HTTP METHOD

GET

GET Parameters

  • base_version:

    An optional parameter to provide the version of the Threat Intelligence Feed that has been fetched previously.

    If provided and the latest version is identical, then an empty response is returned that will look like:

    {

    “type”: “empty”, “version”: 122875,

    }

    If provided and there is a newer version available, the entire Threat Intellience Feed is returned. Incremental support is not currently in use.

Contents of successful response

JSON file containing the threat intelligence feed. Depending on the version sent by the client, this might be a full copy containing the entire blacklist, or only an update. Note that even if the client sends a version, the server might decide to send the full copy (for example if the client’s version is too old)

Error Codes

intel.intel_metadata.list_threats(response_format)

List threats for a threats class

URL

/papi/intel/metadata/threats[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • threat_class:

    filter on threats belonging to this threat class

Contents of successful response

A list of threats (strings)
intel.intel_metadata.list_threat_classes(response_format)

List threat classes

URL

/papi/intel/metadata/threat_classes[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET
Contents of successful response
A list of threat classes (strings)
intel.intel_metadata.get_entry_info(response_format)

Get blacklist information about an entry

URL

/papi/intel/metadata/entry_info[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • entry:

    IP or domain of the entry on which to get information (Required)

  • time:

    Select blacklist information before this time (Optional, defaults to most recent blacklist information)

Contents of successful response

A dictionary with the following keys:

  • threats:

    List of dictionaries with the following keys:

    • threat:

      Name of the threat related to the entry. Called “Malware” in Lastline Portal.

    • threat_class:

      Name of the threat class related to the entry. Called “Malware Class” in Lastline Portal.

    • severity:

      Severity level of the threat class

    • confidence:

      Confidence about the entry

    • impact:

      Overall impact of this entry

  • ips:

    If the entry is a domain, this is a list of IP addresses the domain was on

  • domains:

    If the entry is an IP addresses, this is a list of domains hosted by the IP address

intel.intel_metadata.get_url_info(response_format)

Get blacklist information about a URL.

URL

/papi/intel/metadata/url_info[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • entry:

    IP or domain of the entry on which to get information (Required)

  • url_path

    Path of the URL to get information for, starting with / (Required)

  • time:

    Select blacklist information before this time (Optional, defaults to most recent blacklist information)

Contents of successful response

A dictionary with the following keys:

  • threats:

    List of dictionaries with the following keys:

    • threat:

      Name of the threat related to the URL. Called “Malware” in Lastline Portal.

    • threat_class:

      Name of the threat class related to the URL. Called “Malware Class” in Lastline Portal.

    • severity:

      Severity level of the threat class

    • confidence:

      Confidence about the URL

    • impact:

      Overall impact of this URL

intel.offline.get_offline_bundle(response_format)

Get a bundle containing all the intel updates required to update an offline manager

It is only available on Lastline’s hosted backend.

URL

/papi/intel/offline/get_offline_bundle

HTTP METHOD

GET

HTTP HEADER

  • the “Range” header can be used to resume a incomplete download
  • the “If-Modified-Since” header can be used to download the file only if the current file is newer than the provided date

Contents of successful response

The archive, directly in the body of the answer
intel.offline.get_offline_bundle_metadata(response_format)

Get the metadata associated with the bundle

It is only available on Lastline’s hosted backend.

URL

/papi/intel/offline/get_offline_bundle_metadata

HTTP METHOD

GET

Contents of successful response

A mapping with the following entries:

  • ** md5 **: md5 hash of the bundle

  • ** sha1 **: sha1 hash of the bundle

  • ** metadata **: mapping for the metadata database dump with the following entries:

    • ** md5 **: md5 hash of the metadata dump
    • ** sha1 **: sha1 hash of the metadata dump
    • ** size **: size of the metadata dump

  • ** blacklist **: mapping for the blacklists with the following entries:

    • ** md5 **: md5 hash of the full copy to the blacklist
    • ** sha1 **: sha1 hash of the full copy to the blacklist
    • ** size **: size of the full copy to the blacklist
    • ** version **: version of the full copy to the blacklist

  • ** suricata **: mapping for the suricata rules with the following entries:

    • ** md5 **: md5 hash of the suricata rules
    • ** sha1 **: sha1 hash of the suricata rules
    • ** size **: size of the suricata rules

  • ** openintel **: mapping for the openintel 3rd party rules with the following entries:

    • ** md5 **: md5 hash of the openintel rules
    • ** sha1 **: sha1 hash of the openintel rules
    • ** size **: size of the openintel rules

For example:

{ ‘md5’: ‘7db89d3d32f12efc276858cd393e2bcf’,

‘sha1’: ‘dbf4e0ca21bcfbd9984b20015720f11c21ba5c9c’,

‘size’: 53403731,

‘blacklist’:{
‘md5’: ‘601506c9c20594e9e96db0148a9bb0db’, ‘sha1’: ‘35ad67aebcd3bc35eedb7e512483add170eaad6f’, ‘size’: 6259320, ‘version’: 84660},
‘metadata’: {
‘md5’: ‘6b79f19b277a804bb443e5d9a4098428’, ‘sha1’: ‘f4bc0a0f281b0a9772e635055bb08bd22b5cf7ac’, ‘size’: 131109172},
‘suricata’: {
‘md5’: ‘2a936932957d71c8dbf0f35236ad53f1’, ‘sha1’: ‘7fd367da7d4360d6b395ec99e69dabea7bd843bc’, ‘size’: 2742227}},
‘openintel’: {
‘md5’: ‘2a936932957d71c8dbf0f35236ad53f1’, ‘sha1’: ‘7fd367da7d4360d6b395ec99e69dabea7bd843bc’, ‘size’: 2742227}}

}