1. RESTful API Specification

1.1. Authentication

Please note that cookies should be used for authentication, for example with curl it is possible to specify username and password with --cookie "user=<user>; password=<password>"

For example, to download data for a host you can use the below curl command line:

curl -s --cookie "user=admin; password=admin" "http://192.168.1.1:3000/lua/rest/get/host/data.lua?ifid=1&host=192.168.1.2"

Please check the Examples section for more examples.

1.2. API

1.2.1. PCAP

GET /lua/rest/get/pcap/live_extraction.lua

Live PCAP traffic extraction

  • Produces: [u’application/vnd.tcpdump.pcap’]
  • Description: Raw PCAP data is returned

Parameters

Name Position Description Type
ifid query Interface identifier integer
epoch_begin query Start time (epoch) integer
epoch_end query Start time (epoch) integer
bpf_filter query BPF filter string

Responses

200 - successful operation

400 - Invalid status value

1.2.2. Interfaces

GET /lua/rest/get/interface/data.lua

Get interface data

  • Produces: [u’application/json’]
  • Description: Interface data is returned

Parameters

Name Position Description Type
ifid query Interface identifier integer

Responses

200 - successful operation

400 - Invalid status value

1.2.3. Alerts

GET /lua/rest/get/alert/data.lua

Get alerts data

  • Produces: [u’application/json’]
  • Description: Alerts are returned

Parameters

Name Position Description Type
ifid query Interface identifier integer
status query Status filter (historical, historical-flows, engaged) string

Responses

200 - successful operation

400 - Invalid status value

1.2.4. Hosts

GET /lua/rest/get/host/data.lua

Get host data

  • Produces: [u’application/json’]
  • Description: Host data is returned

Parameters

Name Position Description Type
ifid query Interface identifier integer
host query Host address string

Responses

200 - successful operation

400 - Invalid status value

1.2.5. Flows

GET /lua/pro/rest/get/db/topk_flows.lua

Get flows data. Columns include (but are not limited to) IP_PROTOCOL_VERSION, FLOW_TIME, FIRST_SEEN, LAST_SEEN, VLAN_ID, PACKETS, BYTES, SRC_TO_DST_BYTES, DST_TO_SRC_BYTES, IPV4_SRC_ADDR, IPV4_DST_ADDR, IPV6_SRC_ADDR, IPV6_DST_ADDR, PROTOCOL, L7_PROTO

  • Produces: [u’application/json’]
  • Description: Executes a top-k query to the flows database

Parameters

Name Position Description Type
ifid query Interface identifier integer
begin_time_clause query Start time (epoch) integer
end_time_clause query Start time (epoch) integer
select_keys_clause query Select keys (default: IPV4_SRC_ADDR,IPV4_DST_ADDR,L7_PROTO) string
select_values_clause query Select values (default: BYTES) string
where_clause query Where clause (default: none) string
topk_clause query Top-K clause (default: SUM) string
approx_search query Approximate search (default: true) string
maxhits_clause query Max hits (default: 10) integer

Responses

200 - successful operation

400 - Invalid status value

GET /lua/pro/rest/get/db/flows.lua

Get flows data. Columns include (but are not limited to) IP_PROTOCOL_VERSION, FLOW_TIME, FIRST_SEEN, LAST_SEEN, VLAN_ID, PACKETS, BYTES, SRC_TO_DST_BYTES, DST_TO_SRC_BYTES, IPV4_SRC_ADDR, IPV4_DST_ADDR, IPV6_SRC_ADDR, IPV6_DST_ADDR, PROTOCOL, L7_PROTO.

  • Produces: [u’application/json’]
  • Description: Executes a query to the flows database

Parameters

Name Position Description Type
ifid query Interface identifier integer
begin_time_clause query Start time (epoch) integer
end_time_clause query Start time (epoch) integer
select_clause query Select clause (default: *) string
where_clause query Where clause (default: none) string
maxhits_clause query Max hits (default: 10) integer

Responses

200 - successful operation

400 - Invalid status value