Lastline Custom Intelligence API

The Lastline Custom Intelligence API is accessible for hosted customers at:

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

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

The purpose of this API is to allow to integrate custom intelligence into Lastline products.

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 Custom Intelligence API

  • examples/add_custom_intel_csv.py:

    a sample python script that uses this client to blacklist lists of domains or IPs from a csv file

  • 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 Custom Intelligence API.

Types of intelligence

The Lastline custom intelligence API supports the following types of intelligence

  • Blacklist IPs:

    A Lastline Sensor will generate events when it detects traffic to these IPv4 addresses.

  • Blacklist Domains:

    A Lastline Sensor will generate events when it detects DNS requests for these domains or traffic to IPs resolved from these domains.

  • IDS Rules:

    A Lastline Sensor will generate events when these IDS rules match against the monitored network traffic. In addition to the rules themselves, the custom intelligence API supports variables for the custom IDS rules as well as references for documenting the rules.

  • IDS Rule variables:

    The custom IDS rules provided by a customer may include variables. The values for these variables are then provided as a separate feed. This allows a customer to, for example, define a rule at the global scope and specialize it on each sensor with different variable values defined at the sensor scope.

  • IDS Rule references:

    The custom IDS rules provided by a customer may include shorthand references to resources such as the CVE archive. The custom intelligence API allows users to define the mapping between reference keywords (such as “cve”) and the URL prefix used to resolve the reference URL (such as “https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-”). These mappings are treated just like another entity type, although they can only be defined at the global scope.

  • Yara Rules:

    The Lastline Engine will generate alerts when an analyzed objects matches one of the given rules.

Scope of intelligence

The Lastline Intelligence API allows a user with multiple Lastline Appliances to specify different intelligence for each appliance. When adding intelligence entries through the API, users must select one of the following scopes:

  • Global Scope:

    The intelligence entries in the global scope apply to all of the user’s appliances.

  • License Scope:

    The intelligence entries in the license scope apply to all a user’s appliance configured with a specified Lastline license.

  • Sensor Scope:

    The intelligence entries in the sensor scope apply only to a specific sensor.

The intelligence feed used by a Lastline Sensor combines intelligence entries in the relevant global, license and sensor scopes.

Example
The custom IP address blacklist deployed to a Sensor is the union of all addresses in the customer’s Global IP Blacklist, those in the relevant license’s IP Blacklist, and those in the specific sensor’s IP Blacklist.

If the same intelligence entry (e.g. a blacklisted IP) is present at multiple scopes that apply to the sensor, the most specific entry is selected.

Example
If the IP 1.1.1.1 is blacklisted at the global scope with impact 50, and at sensor Sensor123‘s scope with impact 90, the blacklist for Sensor123 will include IP 1.1.1.1 with impact 90.

Not that a single request to the add, get, del and list methods documented below always operates on a single scope.

Example
If domain www.example.com is added to the Domain Blacklist at the global scope, attempting to delete the domain at the license or sensor scope will have no effect: the www.example.com Domain will still be part of the Domain Blacklist for all sensors, until it is removed at the global scope.

NOTE: Yara rules are applied by all Engine appliances and are thus always added on the global scope.

Access control

To use the custom intelligence API, users must authenticate with Account-based authentication.

Modifying the custom intelligence for a Lastline installation (add and delete methods for each intelligence type), listing and getting feeds (list and feed methods for each intelligence type) require a user account with administrator privileges.

Viewing the configured custom intelligence (get method for each intelligence type) can be done with any user account that has access to a specified sensor or license. This permission is called “Access alerts” in the Lastline Portal.

Methods

Method Index

Custom IP Blacklist:

  • add_ip():

    Add or update one or more IPs in the custom IP blacklist

  • get_ip():

    Get an IP’s entry from the custom IP blacklist

  • del_ip():

    Remove one or more IPs from the custom IP blacklist

  • list_ip():

    List the IPs in the custom IP blacklist

  • feed_ip():

    Get the IP blacklist feed as it would be served to a sensor

Custom domain Blacklist:

  • add_domain():

    Add or update one or more domains in the custom domain blacklist

  • get_domain():

    Get a domain’s entry from the custom domain blacklist

  • del_domain():

    Remove one or more domains from the custom domain blacklist

  • list_domain():

    List the domains in the custom domain blacklist

  • feed_domain():

    Get the domain blacklist feed as it would be served to a sensor

Custom IDS rules:

Variables for custom IDS rules:

Reference for custom IDS rules:

Custom Yara rules:

Custom Breach Defender rules:

Custom postprocessing rules:

Method Documentation

intel.ip.add_ip(response_format)

Add or update one or more entries to the custom IP blacklist.

URL

/papi/intel/ip/add[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • key:

    access_key[:subkey] for which we are adding intelligence entries

  • key_id:

    access key for which we are adding intelligence entries (provide in alternative to key)

  • subkey_id:

    subkey for which we are adding intelligence entries (provide together with key_id in alternative to key)

  • entries:

    Entries to add. This is a JSON list.

The entries field holds a list of mappings with the following fields:

  • ip:

    The IP address. An IPv4 address in dotted-decimal notation. (required)

  • source:

    Use this field to store the source of this information, such as the name of the watchlist or blacklist that this entry comes from (up to 45 ASCII characters).

  • comment:

    Free text comment field for (up to 255 characters)

  • impact:

    Impact level of events generated by this entry. This can be 10-100 in increments of 10.

Contents of successful response

  • added:

    Number of entries added

  • updated:

    Number of entries updated

  • unchanged:

    Number of entries unchanged

  • errors:

    list of entries that could not be successfully added, with associated error message.

Note that a response may be successful (with the success field set to 1) even though all entries had an error.

intel.ip.get_ip(response_format)

Get intelligence on an IP address.

URL

/papi/intel/ip/get[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • key:

    access_key[:subkey] for which we are fetching intelligence entries

  • key_id:

    access key id for which we are fetching intelligence entries (provide in alternative to key)

  • subkey_id:

    subkey for which we are fetching intelligence entries (provide together with key_id in alternative to key)

  • ip:

    The IP addresses to get, in dotted-decimal notation. (required)

  • inherit_scope:

    Boolean. If true, inherit entry from more general scope if no entry is found at requested scope. (default False)

Contents of successful response

  • impact:

    Impact of entry

  • source:

    Source of entry

  • comment:

    Comment of entry

  • account:

    Username of account that last modified the entry (administrator users only)

  • ts:

    Timestamp when entry was last modified

Error Codes

intel.ip.del_ip(response_format)

Delete one or more entries to the custom IP blacklist.

URL

/papi/intel/ip/del[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • key:

    access_key[:subkey] for which we are fetching intelligence entries

  • key_id:

    access key for which we are fetching intelligence entries (provide in alternative to key)

  • subkey_id:

    subkey for which we are fetching intelligence entries (provide together with access_key_id in alternative to key)

  • ips:

    The IP addresses to delete. A comma-separated list of IPv4 address in dotted-decimal notation. (required)

Contents of successful response

  • deleted:

    number of entries deleted

  • missing:

    number of entries not found

  • errors:

    list of entries that could not be successfully deleted, with associated error message.

intel.ip.list_ip(response_format)

Get intelligence on IP addresses

URL

/papi/intel/ip/list[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • key:

    access_key[:subkey] for which we are fetching intelligence entries

  • key_id:

    access key id for which we are fetching intelligence entries (provide in alternative to key)

  • subkey_id:

    subkey for which we are fetching intelligence entries (provide together with key_id in alternative to key)

  • source:

    If provided, only return entries from this source

Contents of successful response

List of entries. Each entry holds:

  • ip:

    blacklisted IP

  • impact:

    Impact of entry

  • source:

    Source of entry

  • comment:

    Comment of entry

  • account:

    Username of account that last modified the entry

  • ts:

    Timestamp when entry was last modified

intel.ip.feed_ip(response_format)

Get intelligence on IP addresses

URL

/papi/intel/ip/feed[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • key:

    access_key:subkey for which we are fetching an intelligence feed

  • key_id:

    access key id for which we are fetching an intelligence feed (provide together with subkey_id in alternative to key)

  • subkey_id:

    subkey for which we are fetching intelligence entries (provide together with key_id in alternative to key)

  • current_version:

    version of feed you currently have, as returned by this method. Defaults to 0 if you have no version.

Contents of successful response

A successful API response may be a full intelligence feed or an incremental feed, at the discretion of the API backend. If there are no changes, the backend may return an empty incremental update.

  • old_version:

    This will be 0 for a full feed, or the base for diffing for an incremental feed.

  • new_version:

    The version of the feed we are returning. Use this for your next call to this method.

  • remove:

    List of IPs to remove from the old feed version. This will be empty for full feeds.

  • add:

    List of IP entries to add to the feed.

Each entry in the add list holds the following fields:

  • entry_key:

    The IP address in dotted-decimal notation

  • impact:

    The impact of the feed entry.

When receiving an incremental feed, the client must apply the diff to their current feed as follow:

  1. remove the entries in the remove list, if they exist
  2. add the entries in the add list. If an entry with that key exists already, update it instead.

As a result of this policy, the update of a feed should be idempotent.

intel.domain.add_domain(response_format)

Add or update one or more entries to the custom domain blacklist.

URL

/papi/intel/domain/add[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • key:

    access_key[:subkey] for which we are adding intelligence entries

  • key_id:

    access key for which we are adding intelligence entries (provide in alternative to key)

  • subkey_id:

    subkey for which we are adding intelligence entries (provide together with key_id in alternative to key)

  • entries:

    Entries to add. This is a JSON list.

The entries field holds a list of mappings with the following fields:

  • domain:

    The domain. This is a fully-qualified domain name in ASCII (required)

  • source:

    Use this field to store the source of this information, such as the name of the watchlist or blacklist that this entry comes from (up to 45 ASCII characters).

  • comment:

    Free text comment field for (up to 255 characters)

  • impact:

    Impact level of events generated by this entry. This can be 10-100 in increments of 10.

Contents of successful response

  • added:

    Number of entries added

  • updated:

    Number of entries updated

  • unchanged:

    Number of entries unchanged

  • errors:

    list of entries that could not be successfully added, with associated error message.

Note that a response may be successful (with the success field set to 1) even though all entries had an error.

intel.domain.get_domain(response_format)

Get intelligence on a domain.

URL

/papi/intel/domain/get[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • key:

    access_key[:subkey] for which we are fetching intelligence entries

  • key_id:

    access key id for which we are fetching intelligence entries (provide in alternative to key)

  • subkey_id:

    subkey for which we are fetching intelligence entries (provide together with key_id in alternative to key)

  • domain:

    The fully qualified domain name to get (required)

  • inherit_scope:

    Boolean. If true, inherit entry from more general scope if no entry is found at requested scope. (default False)

Contents of successful response

  • impact:

    Impact of entry

  • source:

    Source of entry

  • comment:

    Comment of entry

  • account:

    Username of account that last modified the entry (administrator users only)

  • ts:

    Timestamp when entry was last modified

Error Codes

intel.domain.del_domain(response_format)

Delete one or more entries to the custom domain blacklist.

URL

/papi/intel/domain/del[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • key:

    access_key[:subkey] for which we are fetching intelligence entries

  • key_id:

    access key for which we are fetching intelligence entries (provide in alternative to key)

  • subkey_id:

    subkey for which we are fetching intelligence entries (provide together with access_key_id in alternative to key)

  • domains:

    The domains to delete. A comma-separated list of domain names(required)

Contents of successful response

  • deleted:

    number of entries deleted

  • missing:

    number of entries not found

  • errors:

    list of entries that could not be successfully deleted, with associated error message.

intel.domain.list_domain(response_format)

Get intelligence on domain addresses

URL

/papi/intel/domain/list[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • key:

    access_key[:subkey] for which we are fetching intelligence entries

  • key_id:

    access key id for which we are fetching intelligence entries (provide in alternative to key)

  • subkey_id:

    subkey for which we are fetching intelligence entries (provide together with key_id in alternative to key)

  • source:

    If provided, only return entries from this source

Contents of successful response

List of entries. Each entry holds:

  • domain:

    blacklisted domain

  • impact:

    Impact of entry

  • source:

    Source of entry

  • comment:

    Comment of entry

  • account:

    Username of account that last modified the entry

  • ts:

    Timestamp when entry was last modified

intel.domain.feed_domain(response_format)

Get intelligence on a domain name

URL

/papi/intel/domain/feed[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • key:

    access_key:subkey for which we are fetching an intelligence feed

  • key_id:

    access key id for which we are fetching an intelligence feed (provide together with subkey_id in alternative to key)

  • subkey_id:

    subkey for which we are fetching intelligence entries (provide together with key_id in alternative to key)

  • current_version:

    version of feed you currently have, as returned by this method. Defaults to 0 if you have no version.

Contents of successful response

A successful API response may be a full intelligence feed or an incremental feed, at the discretion of the API backend. If there are no changes, the backend may return an empty incremental update.

  • old_version:

    This will be 0 for a full feed, or the base for diffing for an incremental feed.

  • new_version:

    The version of the feed we are returning. Use this for your next call to this method.

  • remove:

    List of domain names to remove from the old feed version. This will be empty for full feeds.

  • add:

    List of domain entries to add to the feed.

Each entry in the add list holds the following fields:

  • entry_key:

    The domain name as an ASCII string

  • impact:

    The impact of the feed entry.

When receiving an incremental feed, the client must apply the diff to their current feed as follow:

  1. remove the entries in the remove list, if they exist
  2. add the entries in the add list. If an entry with that key exists already, update it instead.

As a result of this policy, the update of a feed should be idempotent.

intel.ids_rule.add_ids_rule(response_format)

Add or update one or more entries to the custom IDS rules.

URL

/papi/intel/ids_rule/add[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • key:

    access_key[:subkey] for which we are adding intelligence entries

  • key_id:

    access key for which we are adding intelligence entries (provide in alternative to key)

  • subkey_id:

    subkey for which we are adding intelligence entries (provide together with key_id in alternative to key)

  • entries:

    Entries to add. This is a JSON list.

The entries field holds a list of mappings with the following fields:

  • rule:

    The rule string (required)

  • source:

    Use this field to store the source of this information, such as the name of the rule set that this entry comes from (up to 45 ASCII characters).

  • impact:

    Impact level of events generated by this entry. This can be 10-100 in increments of 10.

Contents of successful response

  • added:

    Number of entries added

  • updated:

    Number of entries updated

  • unchanged:

    Number of entries unchanged

  • errors:

    list of entries that could not be successfully added, with associated error message.

Note that a response may be successful (with the success field set to 1) even though all entries had an error.

intel.ids_rule.get_ids_rule(response_format)

Get a custom IDS rule

URL

/papi/intel/ids_rule/get[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • key:

    access_key[:subkey] for which we are fetching intelligence entries

  • key_id:

    access key id for which we are fetching intelligence entries (provide in alternative to key)

  • subkey_id:

    subkey for which we are fetching intelligence entries (provide together with key_id in alternative to key)

  • rule_id:

    The identifier of the rule (sid) Provide either this or the signature_id

  • group_id:

    The group id of the rule (gid). Defaults to 0. Provide together with rule_id

  • signature_id:

    The identifier of the signature internal to the Lastline API. Provide either this or rule_id

  • inherit_scope:

    Boolean. If true, inherit entry from more general scope if no entry is found at requested scope. (default False)

Contents of successful response

  • impact:

    Impact of entry

  • source:

    Source of entry

  • message:

    The rule’s msg field

  • classification:

    The rule’s classtype field

  • refs:

    Comma-separated list of the rules’ ref fields

  • customer_rule:

    The rule as provided to /ids_rule/add (administrator users only)

  • sensor_rule:

    The rule as deployed to the Lastline sensor (administrator users only)

  • rule_id:

    The identifier of the rule (sid)

  • group_id:

    The group id of the rule (gid)

  • revision_id:

    The revisionf of the rule (rev field)

  • signature_id:

    Lastline identifier for the rule

  • account:

    Username of account that last modified the entry (administrator users only)

  • last_modified:

    Timestamp when entry was last modified

Error Codes

intel.ids_rule.del_ids_rule(response_format)

Delete one or more entries from the custom IDS rules.

URL

/papi/intel/ids_rule/del[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • key:

    access_key[:subkey] for which we are fetching intelligence entries

  • key_id:

    access key for which we are fetching intelligence entries (provide in alternative to key)

  • subkey_id:

    subkey for which we are fetching intelligence entries (provide together with access_key_id in alternative to key)

  • rules:

    The rules. A JSON list of mappings holding rule_id and optionally group_id of the rules to delete.

Contents of successful response

  • deleted:

    number of entries deleted

  • missing:

    number of entries not found

  • errors:

    list of entries that could not be successfully deleted, with associated error message.

intel.ids_rule.list_ids_rule(response_format)

Get intelligence on custom IDS rules.

URL

/papi/intel/ids_rule/list[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • key:

    access_key[:subkey] for which we are fetching intelligence entries

  • key_id:

    access key id for which we are fetching intelligence entries (provide in alternative to key)

  • subkey_id:

    subkey for which we are fetching intelligence entries (provide together with key_id in alternative to key)

  • source:

    If provided, only return entries from this source

Contents of successful response

List of entries. Each entry holds:

  • impact:

    Impact of entry

  • source:

    Source of entry

  • message:

    The rule’s msg field

  • classification:

    The rule’s classtype field

  • refs:

    Comma-separated list of the rules’ ref fields

  • customer_rule:

    The rule as provided to /ids_rule/add

  • sensor_rule:

    The rule as deployed to the Lastline sensor

  • rule_id:

    The identifier of the rule (sid)

  • group_id:

    The group id of the rule (gid)

  • revision_id:

    The revisionf of the rule (rev field)

  • signature_id:

    Lastline identifier for the rule

  • account:

    Username of account that last modified the entry

  • last_modified:

    Timestamp when entry was last modified

intel.ids_rule.feed_ids_rule(response_format)

Get intelligence on custom IDS rules.

URL

/papi/intel/ids_rule/feed[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • key:

    access_key:subkey for which we are fetching an intelligence feed

  • key_id:

    access key id for which we are fetching an intelligence feed (provide together with subkey_id in alternative to key)

  • subkey_id:

    subkey for which we are fetching intelligence entries (provide together with key_id in alternative to key)

  • current_version:

    version of feed you currently have, as returned by this method. Defaults to 0 if you have no version.

Contents of successful response

A successful API response may be a full intelligence feed or an incremental feed, at the discretion of the API backend. If there are no changes, the backend may return an empty incremental update.

  • old_version:

    This will be 0 for a full feed, or the base for diffing for an incremental feed.

  • new_version:

    The version of the feed we are returning. Use this for your next call to this method.

  • remove:

    List of custom IDS rules to remove from the old feed version. This will be empty for full feeds.

  • add:

    List of entries to add to the feed.

Each entry in the add list holds the following fields:

  • entry_key:

    group_id:rule_id of the rule

  • rule:

    The rule as it is to be deployed to the sensor

  • impact:

    The impact of the feed entry.

When receiving an incremental feed, the client must apply the diff to their current feed as follow:

  1. remove the entries in the remove list, if they exist
  2. add the entries in the add list. If an entry with that key exists already, update it instead.

As a result of this policy, the update of a feed should be idempotent.

intel.ids_rule_variable.add_ids_rule_variable(response_format)

Add or update one or more variables for custom IDS rules.

URL

/papi/intel/ids_rule_variable/add[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • key:

    access_key[:subkey] for which we are adding intelligence entries

  • key_id:

    access key for which we are adding intelligence entries (provide in alternative to key)

  • subkey_id:

    subkey for which we are adding intelligence entries (provide together with key_id in alternative to key)

  • entries:

    Entries to add. This is a JSON list.

The entries field holds a list of mappings with the following fields:

  • variable_name:

    The variable name. Up to 32 ASCII characters (required)

  • variable_type:

    ‘ADDRESSGROUP’ or ‘PORTGROUP’ (required)

  • value:

    The value of the variable: Up to 4096 ASCII characters (required)

Contents of successful response

  • added:

    Number of entries added

  • updated:

    Number of entries updated

  • unchanged:

    Number of entries unchanged

  • errors:

    list of entries that could not be successfully added, with associated error message.

Note that a response may be successful (with the success field set to 1) even though all entries had an error.

intel.ids_rule_variable.get_ids_rule_variable(response_format)

Get the value of a variable for custom IDS rules.

URL

/papi/intel/ids_rule_variable/get[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • key:

    access_key[:subkey] for which we are fetching intelligence entries

  • key_id:

    access key id for which we are fetching intelligence entries (provide in alternative to key)

  • subkey_id:

    subkey for which we are fetching intelligence entries (provide together with key_id in alternative to key)

  • variable_name:

    The name of the variable to get (required)

  • inherit_scope:

    Boolean. If true, inherit entry from more general scope if no entry is found at requested scope. (default False)

Contents of successful response

  • variable_type:

    ‘ADDRESSGROUP’ or ‘PORTGROUP’

  • value:

    The value of the variable

  • account:

    Username of account that last modified the entry (administrator users only)

  • ts:

    Timestamp when entry was last modified

Error Codes

intel.ids_rule_variable.del_ids_rule_variable(response_format)

Delete one or more ids rule variables.

URL

/papi/intel/ids_rule_variable/del[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • key:

    access_key[:subkey] for which we are fetching intelligence entries

  • key_id:

    access key for which we are fetching intelligence entries (provide in alternative to key)

  • subkey_id:

    subkey for which we are fetching intelligence entries (provide together with access_key_id in alternative to key)

  • variable_names:

    The variables to delete. A comma-separated list of variable names(required)

Contents of successful response

  • deleted:

    number of entries deleted

  • missing:

    number of entries not found

  • errors:

    list of entries that could not be successfully deleted, with associated error message.

intel.ids_rule_variable.list_ids_rule_variable(response_format)

Get custom ids rule variables

URL

/papi/intel/ids_rule_variable/list[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • key:

    access_key[:subkey] for which we are fetching intelligence entries

  • key_id:

    access key id for which we are fetching intelligence entries (provide in alternative to key)

  • subkey_id:

    subkey for which we are fetching intelligence entries (provide together with key_id in alternative to key)

  • source:

    If provided, only return entries from this source

Contents of successful response

List of entries. Each entry holds:

  • variable_name:

    The variable name

  • variable_type:

    ‘ADDRESSGROUP’ or ‘PORTGROUP’

  • value:

    The value of the variable

  • account:

    Username of account that last modified the entry

  • ts:

    Timestamp when entry was last modified

intel.ids_rule_variable.feed_ids_rule_variable(response_format)

Get feed of ids rule variables

URL

/papi/intel/ids_rule_variable/feed[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • key:

    access_key:subkey for which we are fetching an intelligence feed

  • key_id:

    access key id for which we are fetching an intelligence feed (provide together with subkey_id in alternative to key)

  • subkey_id:

    subkey for which we are fetching intelligence entries (provide together with key_id in alternative to key)

  • current_version:

    version of feed you currently have, as returned by this method. Defaults to 0 if you have no version.

Contents of successful response

A successful API response may be a full intelligence feed or an incremental feed, at the discretion of the API backend. If there are no changes, the backend may return an empty incremental update.

  • old_version:

    This will be 0 for a full feed, or the base for diffing for an incremental feed.

  • new_version:

    The version of the feed we are returning. Use this for your next call to this method.

  • remove:

    List of variable names to remove from the old feed version. This will be empty for full feeds.

  • add:

    List of variable names entries to add to the feed.

Each entry in the add list holds the following fields:

  • entry_key:

    The name of the variable

  • value:

    The value of the variable

  • variable_type:

    ‘ADDRESSGROUP’ or ‘PORTGROUP’

When receiving an incremental feed, the client must apply the diff to their current feed as follow:

  1. remove the entries in the remove list, if they exist
  2. add the entries in the add list. If an entry with that key exists already, update it instead.

As a result of this policy, the update of a feed should be idempotent.

intel.ids_rule_reference.add_ids_rule_reference(response_format)

Add or update one or more references for custom IDS rules.

URL

/papi/intel/ids_rule_reference/add[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • entries:

    Entries to add. This is a JSON list.

The entries field holds a list of mappings with the following fields:

  • keyword:

    The keyword. Up to 32 ASCII characters (required)

  • reference_value:

    The value of the reference: Up to 1024 ASCII characters (required)

Contents of successful response

  • added:

    Number of entries added

  • updated:

    Number of entries updated

  • unchanged:

    Number of entries unchanged

  • errors:

    list of entries that could not be successfully added, with associated error message.

Note that a response may be successful (with the success field set to 1) even though all entries had an error.

intel.ids_rule_reference.get_ids_rule_reference(response_format)

Get a reference for custom IDS rules.

URL

/papi/intel/ids_rule_reference/get[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • keyword:

    The name of the keyword to get (required)

Contents of successful response

  • keyword:

    The keyword

  • reference_value:

    The value of the reference

  • account:

    Username of account that last modified the entry (administrator users only)

  • ts:

    Timestamp when entry was last modified

Error Codes

intel.ids_rule_reference.del_ids_rule_reference(response_format)

Delete one or more custom IDS rule references.

URL

/papi/intel/ids_rule_reference/del[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • keywords:

    The keywords to delete. A comma-separated list of keywords (required)

Contents of successful response

  • deleted:

    number of entries deleted

  • missing:

    number of entries not found

  • errors:

    list of entries that could not be successfully deleted, with associated error message.

intel.ids_rule_reference.list_ids_rule_reference(response_format)

Get custom IDS rule references

URL

/papi/intel/ids_rule_reference/list[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

Contents of successful response

List of entries. Each entry holds:

  • keyword:

    The keyword

  • reference_value:

    The value of the reference

  • account:

    Username of account that last modified the entry

  • ts:

    Timestamp when entry was last modified

intel.yara_rule.add_yara_rule(response_format)

Add or update one or more custom Yara rules.

NOTE: The Yara-rule sub-module of the Intelligence-API is available only on on-premise systems. It is available on Lastline Enterprise and Analyst On-Premise vesrsions >=7.8.

URL

/papi/intel/yara_rule/add[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • entries:

    Entries to add. This is a JSON list.

The entries field holds a list of mappings with the following fields:

  • rule:

    The rule string (required). This must be a single Yara rule (in version 1.7.7 compatible format). Lastline uses a set of reserved metadata entries that must not be used in the rule - if such entries are found in the body of the uploaded rule, the rule is rejected. Reserved metadata entries are “score”, “lastline_custom_signature” and “threat”.

  • score:

    Impact level of events generated by this entry. This can be 0-100 in increments of 1.

  • source:

    Use this field to store the source of this information, such as the name of the rule set that this entry comes from (up to 45 ASCII characters).

  • comment:

    For any user comments.

Contents of successful response

  • added:

    Number of entries added

  • updated:

    Number of entries updated

  • unchanged:

    Number of entries unchanged

  • errors:

    list of entries that could not be successfully added, with associated error message.

Note that a response may be successful (with the success field set to 1) even though all entries had an error.

intel.yara_rule.get_yara_rule(response_format)

Gets a custom Yara rule.

NOTE: The Yara-rule sub-module of the Intelligence-API is available only on on-premise systems. It is available on Lastline Enterprise and Analyst On-Premise vesrsions >=7.8.

URL

/papi/intel/yara_rule/get[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • rule_name:

    The name of the rule.

Contents of successful response

  • rule_name:

    identifier of rule

  • rule:

    full rule body (with name and possibly score)

  • engine_rule_name:

    internal identifier of rule. This is the name of the rule as it will show up in an analysis result. Its value is based on the name of the provided rule (returned as rule_name) with additional tokens for making it unique across different revisions.

  • score:

    score of this rule

  • source:

    name of rule source (e.g. “internal blacklist #2”

  • comment:

    comment for this Yara rule entry (not the same as ‘description’ Yara rule body field)

  • revision:

    number of modification for this entry

  • account:

    Username of account that last modified the entry (administrator users only)

  • last_modified:

    Timestamp when entry was last modified

Error Codes

intel.yara_rule.del_yara_rule(response_format)

Delete one or more custom Yara rules.

NOTE: The Yara-rule sub-module of the Intelligence-API is available only on on-premise systems. It is available on Lastline Enterprise and Analyst On-Premise vesrsions >=7.8.

URL

/papi/intel/yara_rule/del[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • rules:

    The rules to delete. A comma-separated list of rule names (required)

Contents of successful response

  • deleted:

    number of entries deleted

  • missing:

    number of entries not found

  • errors:

    list of entries that could not be successfully deleted, with associated error message.

intel.yara_rule.list_yara_rule(response_format)

List all Yara rules.

NOTE: The Yara-rule sub-module of the Intelligence-API is available only on on-premise systems. It is available on Lastline Enterprise and Analyst On-Premise vesrsions >=7.8.

URL

/papi/intel/yara_rule/list[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • source:

    If provided, only return entries from this source

Contents of successful response

List of entries. Each entry holds:

  • rule_name:

    identifier of rule

  • engine_rule_name:

    internal identifier of rule. This is the name of the rule as it will show up in an analysis result. Its value is based on the name of the provided rule (returned as rule_name) with additional tokens for making it unique across different revisions.

  • score:

    score of this rule

  • source:

    name of rule source (e.g., “internal blacklist #2”)

  • comment:

    comment for this Yara rule entry (not the same as ‘description’ Yara rule body field)

  • revision:

    number of modification for this entry

  • account:

    Username of account that last modified the entry (administrator users only)

  • last_modified:

    Timestamp when entry was last modified

intel.yara_rule.feed_yara_rule(response_format)

Gets a Yara rules feed.

NOTE: The Yara-rule sub-module of the Intelligence-API is available only on on-premise systems. It is available on Lastline Enterprise and Analyst On-Premise vesrsions >=7.8.

URL

/papi/intel/yara_rule/feed[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • current_version:

    version of feed you currently have, as returned by this method. Defaults to 0 if you have no version.

Contents of successful response

A successful API response may be a full intelligence feed or an incremental feed, at the discretion of the API backend. If there are no changes, the backend may return an empty incremental update.

  • old_version:

    This will be 0 for a full feed, or the base for diffing for an incremental feed.

  • new_version:

    The version of the feed we are returning. Use this for your next call to this method.

  • remove:

    List of Yara rules to remove from the old feed version. This will be empty for full feeds.

  • add:

    List of entries to add to the feed.

Each entry in the add list holds the following fields:

  • rule_name:

    name of the rule

  • rule:

    rule as it is to be deployed to the engine

When receiving an incremental feed, the client must apply the diff to their current feed as follow:

  1. remove the entries in the remove list, if they exist

2. add the entries in the add list. If an entry with that key exists already, update it instead.

As a result of this policy, the update of a feed should be idempotent.

intel.llanta_rule.validate_llanta_rule(response_format)

Validate a Breach Defender rule.

URL

/papi/intel/llanta_rule/validate[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • rule:

    The rule to validate.

Contents of successful response

  • OK:

    The string OK indicates that the rule was successfully validated

Error Codes

intel.llanta_rule.add_llanta_rule(response_format)

Add or update one or more entries to the custom Breach Defender ruleset.

URL

/papi/intel/llanta_rule/add[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • key:

    access_key[:subkey] for which we are adding intelligence entries

  • key_id:

    access key for which we are adding intelligence entries (provide in alternative to key)

  • subkey_id:

    subkey for which we are adding intelligence entries (provide together with key_id in alternative to key)

  • entries:

    Entries to add. This is a JSON list.

The entries field holds a list of mappings with the following fields:

  • rule_name:

    The user-provided rule name

  • rule:

    The rule string

  • comment:

    An optional comment about the rule

  • source:

    The source of this information (up to 45 ASCII characters).

  • impact:

    Impact level of events generated by this entry. This can be 10-100 in increments of 10.

  • activity:

    The name of an activity that this rule detects

Contents of successful response

  • added:

    Number of entries added

  • updated:

    Number of entries updated

  • unchanged:

    Number of entries unchanged

  • errors:

    list of entries that could not be successfully added, with associated error message.

Note that a response may be successful (with the success field set to 1) even though all entries had an error.

intel.llanta_rule.get_llanta_rule(response_format)

Get a custom Breach Defender rule.

URL

/papi/intel/llanta_rule/get[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • key:

    access_key[:subkey] for which we are fetching intelligence entries

  • key_id:

    access key id for which we are fetching intelligence entries (provide in alternative to key)

  • subkey_id:

    subkey for which we are fetching intelligence entries (provide together with key_id in alternative to key)

  • rule_name:

    The user-provided rule name

  • uuid:

    The generated UUID for the rule At least one of rule_name and uuid must be provided

  • inherit_scope:

    Boolean. If true, inherit entry from more general scope if no entry is found at requested scope. (default False)

Contents of successful response

  • rule_name:

    The user-provided rule name

  • uuid:

    The generated UUID for the rule At least one of rule_name and uuid must be provided

  • rule:

    The rule string

  • comment:

    An optional comment about the rule

  • source:

    The source of this rule (up to 45 ASCII characters).

  • impact:

    Impact level of events generated by this entry.

  • activity:

    The name of an activity related to this rule

  • account:

    Username of account that last modified the entry (administrator users only)

  • last_modified:

    Timestamp when entry was last modified

Error Codes

intel.llanta_rule.del_llanta_rule(response_format)

Delete one or more entries from the custom Breach Defender ruleset.

URL

/papi/intel/llanta_rule/del[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • key:

    access_key[:subkey] for which we are fetching intelligence entries

  • key_id:

    access key for which we are fetching intelligence entries (provide in alternative to key)

  • subkey_id:

    subkey for which we are fetching intelligence entries (provide together with access_key_id in alternative to key)

  • rules:

    The rules. A JSON list of mappings holding the rule_name of the rules to delete

Contents of successful response

  • deleted:

    number of entries deleted

  • missing:

    number of entries not found

  • errors:

    list of entries that could not be successfully deleted, with associated error message.

intel.llanta_rule.list_llanta_rule(response_format)

List custom Breach Defender rules.

URL

/papi/intel/llanta_rule/list[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • key:

    access_key[:subkey] for which we are fetching intelligence entries

  • key_id:

    access key id for which we are fetching intelligence entries (provide in alternative to key)

  • subkey_id:

    subkey for which we are fetching intelligence entries (provide together with key_id in alternative to key)

  • source:

    If provided, only return entries from this source

Contents of successful response

List of entries. Each entry holds: - rule_name:

The user-provided rule name
  • uuid:

    The generated UUID for the rule At least one of rule_name and uuid must be provided

  • rule:

    The rule string

  • comment:

    An optional comment about the rule

  • source:

    The source of this rule (up to 45 ASCII characters).

  • impact:

    Impact level of events generated by this entry.

  • activity:

    The name of an activity related to this rule

  • account:

    Username of account that last modified the entry (administrator users only)

  • last_modified:

    Timestamp when entry was last modified

intel.llanta_rule.feed_llanta_rule(response_format)

Get the custom Breach Defender ruleset.

URL

/papi/intel/llanta_rule/feed[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • key:

    access_key:subkey for which we are fetching an intelligence feed

  • key_id:

    access key id for which we are fetching an intelligence feed (provide together with subkey_id in alternative to key)

  • subkey_id:

    subkey for which we are fetching intelligence entries (provide together with key_id in alternative to key)

  • current_version:

    version of feed you currently have, as returned by this method. Defaults to 0 if you have no version.

Contents of successful response

A successful API response may be a full intelligence feed or an incremental feed, at the discretion of the API backend. If there are no changes, the backend may return an empty incremental update.

  • old_version:

    This will be 0 for a full feed, or the base for diffing for an incremental feed.

  • new_version:

    The version of the feed we are returning. Use this for your next call to this method.

  • remove:

    List of custom rules to remove from the old feed version. This will be empty for full feeds.

  • add:

    List of entries to add to the feed.

Each entry in the add list holds the following fields:

  • uuid:

    The unique UUID of a rule

  • rule:

    The rule as it is to be deployed to the sensor

  • revision

    The rule revision

  • activity:

    The name of an activity related to this rule

When receiving an incremental feed, the client must apply the diff to their current feed as follow:

  1. remove the entries in the remove list, if they exist
  2. add the entries in the add list. If an entry with that key exists already, update it instead.

As a result of this policy, the update of a feed should be idempotent.

intel.postprocessing_rule.validate_postprocessing_rule(response_format)

Validate a postprocessing rule.

On-Premise availability
This method is available on Lastline Enterprise/Analyst On-Premise version 8.2 or above.

URL

/papi/intel/postprocessing_rule/validate[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • matching_expression:

    The matching expression part of the rule (at least one between this and action must be provided) If the matching expression is simple enough, i.e.,

    • structured as the intersection of OR clauses
    • each OR clause is composed by one or more equality constraints on the same field
    • involving only 1 object type (e.g., only “network_event”)

    it is returned in a simple format in the response. Note that the term equality here is used a bit loosely, as it also includes:

    • IP range constraints: where we attempt to return the constraint value as a CIDR block, if possible, otherwise as range in the form ‘<start>-<end>’
    • wildcard matching constraints: e.g., ‘network_event.threat_class: foo*’

    Examples of simple matching expressions are the following:

    • (network_event.dst_port: 80 OR network_event.dst_port: 443) AND (network_event.threat_class: command&control) AND (network_event:src_ip: 192.168.1.0-192.168.1.255)
    • network_event.dst_port: 80
    • network_event.dst_port: 80 OR network_event.dst_port: 443
  • action:

    The action that should be applied to events matching the rule (at least one between this and matching_expression must be provided)

Contents of successful response

Mapping with fields:

  • valid:

    Set to true if the rule was successfully validated. Note that for invalid rules an error code is returned instead

For simple matching expressions, see description above, the mapping will have and additional key:

  • parsed_simple_matching_expression:

    Sequence of AND-ed terms of the matching expression as mappings with keys:

    • attribute_name:

      Name of the attribute of the constraint

    • values:

      Sequence of values for the attribute, obtained by joining all values for the same attribute in OR clauses of the matching expression

Moreover, if a valid action was provided, the response will contain an additional key:

  • parsed_action:

    Sequence of mappings with keys:

    • action:

      The action to apply, e.g., “suppress”

    • target:

      The target of the action, e.g., “network_event”

    • value:

      Optional value of the action, e.g., the value of the tag to assign to a matching event

Error Codes

**Example response **

For the following simple matching expression:

(network_event.dst_port: 80 OR network_event.dst_port: 443) AND (network_event.threat_class: command&control) AND (network_event:src_ip: 192.168.1.0-192.168.1.255)

and the following action:

tag:network_event = Important stuff

the response would be:

{

“valid”: True, “parsed_simple_matching_expression”: [

{
“attribute_name”: “dst_port”, “values”: [80, 443],

}, {

“attribute_name”: “threat_class”, “values”: [“command&control”],

}, {

“attribute_name”: “src_ip”, “values”: [“192.168.0.1/24”],

},

], “parsed_action”: [

{
“action”: “tag”, “target”: “network_event”, “value”: “Important stuff”,

}

]

}

intel.postprocessing_rule.add_postprocessing_rule(response_format)

Add or edit postprocessing rules.

Postprocessing rules can be added at customer or license level, but not at sensor level.

On-Premise availability
This method is available on Lastline Enterprise/Analyst On-Premise version 8.2 or above.

URL

/papi/intel/postprocessing_rule/add[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • key:

    access_key for which we are adding intelligence entries

  • key_id:

    access key for which we are adding intelligence entries (provide in alternative to key)

  • entries:

    Entries to add. This is a JSON list.

The entries field holds a list of mappings with the following fields:
  • rule_name:

    The user-provided rule name

  • matching_expression:

    The matching expression part of the rule

  • priority:

    Priority that should be assigned to the rule, to determine the run order (optional, valid values 0-100, defaults to 50)

  • action:

    The action that should be applied to events matching the rule

  • comment:

    An optional comment about the rule

  • source:

    The source of this information (up to 45 ASCII characters).

Contents of successful response

  • added:

    Number of entries added

  • updated:

    Number of entries updated

  • unchanged:

    Number of entries unchanged

  • errors:

    list of entries that could not be successfully added, with associated error message.

Error Codes

intel.postprocessing_rule.get_postprocessing_rule(response_format)

Get a postprocessing rule.

On-Premise availability
This method is available on Lastline Enterprise/Analyst On-Premise version 8.2 or above.

URL

/papi/intel/postprocessing_rule/get[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • key:

    access_key[:subkey] for which we are fetching intelligence entries

  • key_id:

    access key id for which we are fetching intelligence entries (provide in alternative to key)

  • subkey_id:

    subkey for which we are fetching intelligence entries (provide together with key_id in alternative to key)

  • rule_name:

    The user-provided rule name

  • uuid:

    The generated UUID for the rule At least one of rule_name and uuid must be provided

  • inherit_scope:

    Boolean. If true, inherit entry from more general scope if no entry is found at requested scope. (default False)

Contents of successful response

  • rule_name:

    User-provided name of the rule

  • matching_expression:

    The matching expression part of the rule

  • action:

    Action to be applied to events matching this rule

  • priority:

    Priority of the rule

  • uuid:

    Unique identifier of the rule

  • comment:

    Comment about the rule

  • account:

    Username of account that last modified the entry (administrator users only)

  • last_modified:

    Timestamp when entry was last modified

  • source:

    name of rule source

  • revision:

    number of modification for this entry

Error Codes

intel.postprocessing_rule.del_postprocessing_rule(response_format)

Delete a postprocessing rule.

On-Premise availability
This method is available on Lastline Enterprise/Analyst On-Premise version 8.2 or above.

URL

/papi/intel/postprocessing_rule/del[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • key:

    access_key[:subkey] for which we are fetching intelligence entries

  • key_id:

    access key for which we are fetching intelligence entries (provide in alternative to key)

  • subkey_id:

    subkey for which we are fetching intelligence entries (provide together with access_key_id in alternative to key)

  • rules:

    The rules. A JSON list of mappings holding the rule_name of the rules to delete

Contents of successful response

  • deleted:

    number of entries deleted

  • missing:

    number of entries not found

  • errors:

    list of entries that could not be successfully deleted, with associated error message.

intel.postprocessing_rule.list_postprocessing_rule(response_format)

List postprocessing rules.

On-Premise availability
This method is available on Lastline Enterprise/Analyst On-Premise version 8.2 or above.

URL

/papi/intel/postprocessing_rule/list[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • key:

    access_key[:subkey] for which we are fetching intelligence entries

  • key_id:

    access key id for which we are fetching intelligence entries (provide in alternative to key)

  • subkey_id:

    subkey for which we are fetching intelligence entries (provide together with key_id in alternative to key)

Contents of successful response

List of entries. Each entry holds: - rule_name:

User-provided name of the rule
  • matching_expression:

    The matching expression part of the rule

  • action:

    Action to be applied to events matching this rule

  • priority:

    Priority of the rule

  • uuid:

    Unique identifier of the rule

  • comment:

    Comment about the rule

  • account:

    Username of account that last modified the entry (administrator users only)

  • last_modified:

    Timestamp when entry was last modified

  • source:

    name of rule source

  • revision:

    number of modification for this entry

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

Error Codes

intel.blacklist.LLAPI_INTEL_ERROR__FEED_LIMIT_EXCEEDED

Error code 11001: Returned when trying to add too many entries to a custom intelligence feed.