Graph

The NTA Graph API allows users to work with NTA-generated data using a graph-based representation. In this graph, nodes represent entities such as hosts, file downloads, name resolutions, etc. By means of expansions, the user can explore the graph and obtain more information about the entities represented by its nodes and edges.

This API contains methods to:

  • list and search NTA records
  • expand nodes in a NTA graph
  • create and access permalinks of a NTA graph
  • obtain more information about events generated by the NTA detectors

It is accessible at:

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

Method Index

Method Documentation

llanta.graph.ping(response_format)

Ping this API.

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

URL

/llanta/graph/ping[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

Contents of successful response

PONG
llanta.graph.list_expansions(response_format)

List the expansions available for a given node.

URL

/llanta/graph/list_expansions[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Node information

  • node_type:

    The node type (required)

Contents of successful response

A list of strings containing the expansion types that are supported for the given node.

llanta.graph.search(response_format)

Search nodes that match the given query term.

URL

/llanta/graph/search[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Query

  • q:

    The query term (required)

  • qtype

    The query type

  • existing_nodes:

    List of existing nodes, specified by their node ID

Network selection

  • key:

    The sensor key (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

Sorting and pagination:

  • max_results:

    Limit to this many results

Contents of successful response

A graph with the nodes that match the query.

llanta.graph.expand(response_format)

Expand the graph by applying an expansion type to a given node.

URL

/llanta/graph/expand[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET, POST

GET Parameters Node information

  • node_type:

    The node type (required)

  • node_value:

    The node value (required)

  • expansion_type:

    The type of expansion (required)

  • existing_nodes:

    List of existing nodes, specified by their node ID

Network selection

  • key:

    The sensor key (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

Sorting and pagination:

  • max_results:

    Limit to this many results

Contents of successful response

A graph with the nodes that match the query.

llanta.graph.get_node_info(response_format)

Get short information about a node.

URL

/llanta/graph/node_info[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters Node information

  • node_type:

    The node type (required)

  • node_value:

    The node value (required)

Network selection

  • key:

    The sensor key (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

Sorting and pagination:

  • max_results:

    Limit to this many results

Contents of successful response

A dictionary of (key, value) pairs.

llanta.graph.list_rrs(response_format)

List resource records.

URL

/llanta/graph/list_rrs[. response_format]

response_format can be xml, json, or csv (defaults to json)

HTTP METHOD

GET

GET Parameters Network selection

  • key:

    The sensor key (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

Filters:

  • fqdn:

    Restrict to resource records with the given hostname in the response

  • src_ip:

    Restrict to resource records with the given src_ip

  • dst_ip:

    Restrict to resource records with the given dst_ip

Sorting and pagination:

  • max_results:

    Limit to this many results

  • sort_by:

    Sort resource records using the given sort_by field

  • descending:

    If True, serve resource records in descending order based on the sort_by field, ascending otherwise

Contents of successful response

A list of resource records, with the following fields:
  • ts_start: The timestamp of the beginning of the DNS activity recorded in this record (as a string in the yyyy-mm-dd H:M:S format)
  • ts_end: The timestamp of the end of the DNS activity recorded in this record (as a string in the yyyy-mm-dd H:M:S format)
  • src_ip: The IP address of the device that issued the DNS request
  • src_port: The port number from which the DNS request was issued
  • dst_ip: The IP address of the nameserver that was sent the request
  • dst_port: The port number where the request was sent
  • rrname: The name of the queries resource
  • rrtype: The resource record type, as an integer as described by IANA in the DNS parameters document in the section ‘Resource Record (RR) TYPEs’ (http://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml)
  • rrclass: The resource record class, as an integer as described by IANA in the DNS parameters document in the section ‘DNS CLASSes’ (http://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml)
  • ttl: The time-to-live of the response
  • rdata: The response contents
  • error: The error code, if any
  • n: The number of time this record was observed
  • source: The sensor that produced the record
  • geoip: The geoip coordinates, as a list of objects with fields lat, lon, position, and country_code2
  • tags: A list of tags associated to this record
  • severity: An integer indicating the severity of the activity represented by this record
llanta.graph.list_webrequests(response_format)

List web requests.

URL

/llanta/graph/list_webrequests[. response_format]

response_format can be xml, json, or csv (defaults to json)

HTTP METHOD

GET

GET Parameters Network selection

  • key:

    The sensor key (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

Filters:

  • src_ip:

    Restrict to webrequests with the given src_ip

  • dst_ip:

    Restrict to webrequests with the given dst_ip

  • normalized_url:

    Restrict to webrequests with the given normalized URL

Sorting and pagination:

  • max_results:

    Limit to this many results

  • sort_by:

    Sort webrequests using the given sort_by field

  • descending:

    If True, serve webrequests in descending order based on the sort_by field, ascending otherwise

Contents of successful response

A list of webrequests, with the following fields:
  • ts_start: The timestamp of the beginning of the HTTP activity recorded in this record (as a string in the yyyy-mm-dd H:M:S format)
  • ts_end: The timestamp of the end of the HTTP activity recorded in this record (as a string in the yyyy-mm-dd H:M:S format)
  • src_ip: The IP address of the device that issued the HTTP request
  • src_port: The port number from which the HTTP request was issued
  • dst_ip: The IP address of the web server that was sent the request
  • dst_port: The port number where the request was sent
  • method: The HTTP method used in the request
  • http_version: The HTTP protocol version used in the request
  • hostname: The value of the Host request header
  • path: The path of the requested resource
  • referer: The value of the Referer request header
  • user_agent: The value of the User-Agent request header
  • response_code: The response code provided by the web server
  • response_redirect: The value of the Location response header
  • response_content_type: The value of the Content-Type response header
  • response_body_type: The file type of the response body
  • proto: The protocol used in the request (typically, TCP)
  • n: The number of time this record was observed
  • source: The sensor that produced the record
  • tags: A list of tags associated to this record
  • severity: An integer indicating the severity of the activity represented by this record
llanta.graph.list_netflows(response_format)

List netflow records.

URL

/llanta/graph/list_netflows[. response_format]

response_format can be xml, json, or csv (defaults to json)

HTTP METHOD

GET

GET Parameters

Network selection

  • key:

    The sensor key (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

Filters:

  • src_ip:

    Restrict to netflow records with the given src_ip

  • dst_ip:

    Restrict to netflow records with the given dst_ip

Sorting and pagination:

  • max_results:

    Limit to this many results

  • sort_by:

    Sort netflow records using the given sort_by field

  • descending:

    If True, serve records in descending order based on the sort_by field, ascending otherwise

Contents of successful response

A list of netflow records, with the following fields:
  • ts_start: The timestamp of the beginning of the flow activity recorded in this record (as a string in the yyyy-mm-dd H:M:S format)
  • ts_end: The timestamp of the end of the flow activity recorded in this record (as a string in the yyyy-mm-dd H:M:S format)
  • src_ip: The IP address of the device that started the flow
  • src_port: The source port of the flow
  • dst_ip: The IP address of the destination device of the flow
  • dst_port: The destination port number
  • proto: The protocol used in the flow
  • packets_in: The number of incoming packets (received by src_ip)
  • packets_out: The number of outgoing packets (sent by src_ip)
  • bytes_in: The number of bytes in incoming packets (received by src_ip)
  • bytes_out: The number of bytes in outgoing packets (sent by src_ip)
  • syns_in: The number of incoming packets with the SYN flag set (received by src_ip)
  • syns_out: The number of outgoing packets with the SYN flag set (sent by src_ip)
  • fins_in: The number of incoming packets with the FIN flag set (received by src_ip)
  • fins_out: The number of outgoing packets with the FIN flag set (sent by src_ip)
  • rst_in: The number of incoming packets with the RST flag set (received by src_ip)
  • rst_out: The number of outgoing packets with the RST flag set (sent by src_ip)
  • payload_bytes_signature: The byte size of the first several packets in the flow
  • app_layer_protocol: The application layer protocol (None if undetected)
  • source: The sensor that produced the record
  • tags: A list of tags associated to this record
  • severity: An integer indicating the severity of the activity represented by this record

Create a new permalink.

Store the current graph and create a permalink for it.

URL

/papi/llanta/add_permalink[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

Network selection

  • key:

    The sensor key (required)

  • key_id:

    The access key ID

  • subkey_id:

    The subkey (provide together with key_id in alternative to key)

Permalink

  • nodes:

    The list of nodes in the graph

  • edges:

    The list of nodes in the graph

  • name:

    A user-provided, non-unique name for the permalink (optional)

Contents of succesful response

Graph

Return the graph identified by a permalink.

URL

/papi/llanta/get_permalink[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • identifier:

    The permalink identifer, as returned by create

Contents of succesful response

None

llanta.graph.get_event_evidence(response_format)

Return the evidence associated with an event.

The evidence can contain:

  • a list or records (netflows, webrequests, passive DNS) that are

    responsible for the event

URL

/papi/llanta/get_event_evidence[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Network selection:

  • key:

    The sensor key (required)

Time range selection:

  • timezone:

    Name of selected time zone

Event selection:

  • event_id:

    The event identifier.

Sorting and pagination:

  • max_results:

    Limit to this many results

Contents of succesful response A dictionary, with the following keys:

  • netflows:

    A list of netflow records, with the same response format as list_netflows

  • webrequests:

    A list of webrequests, with the same response format as list_webrequests

  • rrs:

    A list of resource records, with the same response format as list_rrs

llanta.graph.get_event_detector_info(response_format)

Return the detector metadata of an event.

The detector metadata is a set of attributes representing the internal state of a detector in the moment it generated the event.

URL

/papi/llanta/event_detector_info/get[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Network selection

  • key:

    The sensor key (required)

  • key_id:

    The access key ID

  • subkey_id:

    The subkey (provide together with key_id in alternative to key)

Event selection:

  • event_id:

    The event identifier.

Contents of succesful response A dictionary, with the following keys:

  • state_type:

    A string representing the type of detector; allowed state types are:

    • CLASSIFICATION:

      This event was produced by a classifier.

    • CLUSTERING:

      This event is representative of a cluster of anomalous events.

    • OUTLIER:

      This event is considered anomalous with respect to an observed baseline.

  • detector_state:

    A JSON string containing the list of key-value pairs for the detector.

  • description:

    A description of the type of detector and its state.