Facts

The NTA Fact API allows users to obtain information on hosts in a monitored network. This information is generated by the Lastline NTA engine by analyzing records extracted from network traffic (e.g., flow information, webrequests, passive DNS data).

Facts provide information about a host; for example, the type of operating system it runs, the services it offers, etc. Facts are generated by facters, which are algorithms that analyze network traffic records and identify specific facts.

This API contains methods to:

  • list facts by facter name
  • obtain the bandwidth time-series of a host
  • obtain the cluster of behaviour for a host, if present
  • obtain the list of clusters of behaviour observed in a network

It is accessible at:

https://user.lastline.com/papi/llanta/fact/<function>

Method Index

Method Documentation

llanta.facts.ping(response_format)

Ping this API.

Utility API method to check if the module is properly installed and enabled.

URL

/llanta/fact/ping[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

Contents of successful response

PONG
llanta.facts.get_base_facts(response_format)

Get base facts learned about a protected network

Base facts specify that a property is valid for given hosts during some specified interval of time. For example, a base property may say that a host had a “nameserver” role between a start time and a end time.

URL

/papi/llanta/fact/base[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Fact selection:
  • ip:

    A comma-separated list of hosts in the monitored network (required)

  • facter_type

    (required) A facter type

Time range selection:

  • start_time:

    Get base facts that were valid after this date (required)

  • end_time:

    Get base facts that were valid 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
  • max_results:

    Limit to this many results

  • offset_results:

    Skip the first offset_results results.

Contents of successful response

A list of dictionaries with the following keys:

  • access_key_id:

    Identifier of license of sensor related to the returned facts

  • subkey_id:

    Identifier of subkey of sensor related to the returned facts

  • ip:

    IP address of the host

  • start_time:

    Start time of the event

  • end_time:

    End time of the event

  • facter_type:

    The property type

  • facter_value:

    The property value

llanta.facts.get_hourly_facts(response_format)

Get hourly facts learned about a protected network

Hourly facts specify timeseries properties with hourly data points. For example, a hourly property may provide upload bandwidth data for a host in hourly buckets.

URL

/papi/llanta/fact/hourly[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Fact selection:
  • ip:

    A comma-separated list of hosts in the monitored network (required)

  • facter_type

    (required) A facter type

Time range selection:

  • start_time:

    Get base facts that were valid after this date (required)

  • end_time:

    Get base facts that were valid 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).

Either key or (key_id, subkey_id) are required.

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
  • max_results:

    Limit to this many results

  • offset_results:

    Skip the first offset_results results.

  • max_data_points:

    Maximum number of data points to return. If necessary, hourly values in the facts will be downsampled to daily values. This value defaults to 150 and is limited to at most 300.

Contents of successful response

A list of dictionaries with the following keys:

  • access_key_id:

    Identifier of license of sensor related to the returned facts

  • subkey_id:

    Identifier of subkey of sensor related to the returned facts

  • ip:

    IP address of the host

  • start_time:

    Start time of the event

  • end_time:

    End time of the event

  • facter_type:

    The property type

  • facter_value:

    The property value

  • hours:

    Array storing hourly values

llanta.facts.get_cluster_members(response_format)

Get hosts that are similar to the one specified in the request.

Similar hosts are hosts that behave similarly to a host during the selected time range, i.e. they present the same network traffic characteristics.

URL

/papi/llanta/fact/similar_hosts[. response_format]

response_format can be xml or json (defaults to json)

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

HTTP METHOD

GET

GET Parameters

Fact selection:
  • ip:

    A host in the monitored network (required)

Time range selection:

  • start_time:

    Get base facts that were valid after this date (required)

  • end_time:

    Get base facts that were valid 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:

  • max_data_points:

    Maximum number of data points to return. This represents the maximum number of facts that we can be obtained on a single call. These facts will be further aggregated when getting the similar hosts.

Contents of successful response

A list of dictionaries with the following keys:

  • clusters:

    A list of dictionaries with the following keys:

    • start_time:

      Start time of the clustering window

    • end_time:

      End time of the clustering window

    • label:

      The string representation of the behaviour of the cluster

    • hosts:

      The list of similar hosts for that clustering window

llanta.facts.get_cluster_list(response_format)

Get the list of clusters observed in a time interval.

Members of a cluster are hosts that behave similarly during the selected time range, i.e. they present the same network traffic characteristics.

URL

/papi/llanta/fact/clusters_list[. response_format]

response_format can be xml or json (defaults to json)

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

HTTP METHOD

GET

GET Parameters

Time range selection:

  • start_time:

    Get base facts that were valid after this date. (required)

  • end_time:

    Get base facts that were valid 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).

Contents of successful response

A list of dictionaries with the following keys:

  • clusters_list:

    A list of dictionaries containing the following keys:

    • label:

      The string representation of the behaviour of the cluster.

    • hosts:

      A list of dictionaries with the following keys:

      • host:

        The IP address of the host.

      • start_time:

        When the host was first observed in the cluster.

      • end_time:

        When the host was last observed in the cluster.