The FlowTraq Web API provides a RESTful interface for for retrieving NetFlow data from a FlowTraq Server in JSON format for use by third-party applications. This API defines two methods of retrieving data:
NetFlow data processed into specific FlowTraq views
Raw NetFlow session records as stored by FlowTraq
An API authentication token is required for all requests. Authentication tokens must be generated for each client through the FlowTraq command line tools. To request the token, send an HTTP request such as:
POST https://example.com/flowtraq/api/v1/auth
Parameter Name | Value | Default Value | Notes |
---|---|---|---|
server | string | "localhost" | The FlowTraq server address. |
port | number | 9640 | The FlowTraq server port. |
username | string | required | Username of a user on the Flowtraq server. |
password | string | required | Password of the Flowtraq server user. |
The response will contain either the resulting auth token or an error message:
Parameter Name | Value | Notes |
---|---|---|
auth_token | string | Only returned if authentication successful. |
error | string | Only returned if authentication failed. |
Various FlowTraq view combinations may be retrieved via the API by sending requests to:
GET https://example.com/flowtraq/api/v1/stat
Parameter Name | Value | Default Value | Notes |
---|---|---|---|
server | string | "localhost" | The FlowTraq server address. |
port | number | 9640 | The FlowTraq server port. |
auth_token | string | required | A recently acquired authentication token from an authentication request. |
group_by | string | "IP" | A rank entity as described in Retrieving Statistical Queries from the Command Line. |
count_by | string | "BYTES" | A rank field as described in Retrieving Statistical Queries from the Command Line. Use a space to separate the token "unique". |
direction | string | none | Possible values: "snd", "rcv". |
before_time | timestamp | none | A timestamp in the format "MM/DD/YY hh:mm:ss.microsec". |
after_time | timestamp | none | A timestamp in the format "MM/DD/YY hh:mm:ss.microsec". |
time_range | string | -15m | A time specifier as described in Time Navigation. |
query | string | none | A filter string as described in Filter String Syntax. |
rows | number | 10 | The maximum number or rows to return. |
The response will contain either the resulting data table or an error message:
Parameter Name | Value | Notes |
---|---|---|
columns | [string] | An array of column names. |
data | [[string]] | An array of rows, one rank entity per row. Values in each row correspond to the column names in the columns field. |
error | string | Only returned if the request failed. |
For example, using curl in a shell command:
$ curl "https://example.com/flowtraq/api/v1/stat?auth_token=18265a85ca45db35d0a8c263e6dd2c37&group_by=COUNTRY&count_by=BYTES&time_range=-1h"
{"columns":["COUNTRY","SENT BYTES","COLORS","SENT BYTES","RECV BYTES","SENT PCKTS","RECV PCKTS","SESS. INIT","SESS. ACPT","TIME SERIES"],"data":[["192.0.0.7","291953601","9f5afbff","291953601","288067046","597183","592799","1999","2092",["2473710","2478259", ... ]] ... ]}
Raw NetFlow session records may be retrieved from FlowTraq storage API via:
GET https://example.com/flowtraq/api/v1/sessions
Request parameters are the same as when retrieving processed FlowTraq views. See Retrieving Processed FlowTraq Views: Request Parameters.
The response will contain either the resulting data table or an error message:
Parameter Name | Value | Notes |
---|---|---|
columns | [string] | An array of column names. |
data | [[string]] | An array of rows, one session per row. Values in each row correspond to the column names in the columns field. |
summary | [string] | A total byte and session count of the query. |
error | string | Only returned if the request failed. |
For example, using curl in a shell command:
$ curl "https://example.com/flowtraq/api/v1/sessions?auth_token=18265a85ca45db35d0a8c263e6dd2c37&group_by=COUNTRY&count_by=BYTES&time_range=-1h"
{"columns":["CLIENT ADDRESS","CLIENT COUNTRY","CLIENT AS", ... ],"data":[["192.168.68.13","??","0", ... ], ...], "summary":["Total sessions: 802","Total Packets: 1832127","Total Bytes: 1160933394"]}