Documentation
API Methods
API Methods
Introduction
NETALERT can easily integrate with external tools and provides two API calls for extracting information from NETALERT. The information that can be extracted includes:
- Traffic informations
- Alert informations
API methods
Each request must authentificate against NETALERT by using an API key AND IP Address. These keys are generated in the administration section of NETALERT and are beeing used by adding to each request an authorisation header:
All the NETALERT APIs methods are the POST request type.
For remote management capabilities, NETALERT uses the same mechanisms.
Authorization: Bearer {API_KEY}
An API key is accepted only from the address recorded as its remote host when the key was created
under API Keys; the same key sent from any other address is
refused with 401 Invalid Token. Keys generated by the current release are 64 hexadecimal
characters long. Keys created by earlier releases, which are 32 characters long, remain valid.
Method - postAPIGetTraffic
To extract traffic information, use the postAPIGetTraffic method with the following parameters:
- StartDate: the start time of the search
- EndDate: the end time of the search
- Filter: the OpenSearch filter, a query string query for data filtering
- maxNumberOfResults: The upper limit of data entries provided by an API call to a single request
The method is:
https://{NETALERT_IP}/api/postAPIGetTraffic
Ex: Request
{
"StartDate": "2024-02-05 11:59:45",
"EndDate": "2024-02-05 12:00:00",
"Filter": "*",
"maxNumberOfResults": 100
}
Ex: Response
{
"data": {
"totalResults": 29126861,
"data": [
{
"SrcMAC": "1c:98:ec:1b:67:dd",
"DestMAC": "80:30:e0:3c:7e:74",
"SrcIP": "192.168.200.71",
"DestIP": "192.168.200.6",
"Protocol": "ICMP",
"UpperLayerChecksum": "11427",
"TCPSequence": "0",
"TCPack": "0",
"TCPFlags": "0",
"EthernetType": "Internet Protocol version 4 (IPv4)",
"HeaderLength": "138",
"RXdirection": "0",
"Flow_GUID": "C470E583-55C1-AA72-5AAF-7AF2196FDE1A",
"Packet_GUID": "BB433881-B4C1-7D2F-13BE-133E92D5CB58",
"UTC_ISO8601": "2024-02-13T11:42:55.239608+00:00",
"insertTimestamp": 1707824575,
"DetectedTrafficTag": "TrafficICMP",
"ttl": "64",
"status": "Normal",
"connectionStatus": "CLOSED",
"total_bytes": 138,
"datasourceType": "TAP/SPAN",
"_OS7": {
"isExternalTraffic": false,
"isInternalTraffic": true,
"isInternalTransfer": false,
"isExternalTransfer": false,
"s_IPClass": "Class C",
"d_IPClass": "Class C",
"isDNSRequest": false,
"isICMP": true,
"icmp_code": 2,
"icmp_type": 3,
"icmp_id": 0,
"icmp_seq": 0,
"isProxyTraffic": false,
"isFile": false,
"isUnknownFile": false,
"isCryptoMining": false,
"isTOR": false,
"isDynamicDNSRequest": false,
"isScan": false,
"isAuthentication": false,
"isBruteForce": false,
"isDHCP": false,
"isKerberos": false,
"isSMTP": false,
"isSSL": false,
"isKnownProtocol": true,
"isDetectedFwProtocol": false,
"isDetectedRvProtocol": false
},
"_ssl": [],
"Log": {
"index": "day_traffic_2024-02-13",
"type": "traffic",
"id": "NDxGoo0BCsC4LDmy82VY",
"score": null
}
}
]
},
"isSuccess": true,
"message": "",
"errorMessage": null
Method - GetSingleTraffic
- In order to retreive a single specific traffic event, use a flow_guid guid filter as in the following example:
Flow_GUID: C470E583-55C1-AA72-5AAF-7AF2196FDE1A
You can extract Flow_GUID from the results set of the bigger traffic request.
GetSingleTraffic: /api/postAPIGetTraffic
{
"Filter": C470E583-55C1-AA72-5AAF-7AF2196FDE1A
}
Method - postAPIGetAlerts
To extract traffic information, use the postAPIGetAlerts method with the following parameters:
- StartDate: the start time of the search
- EndDate: the end time of the search
- Filter: the Opensearch filter, a query string query for data filtering
- maxNumberOfResults: The upper limit of data entries provided by an API call to a single request
The method is:
http://{NETALERT_IP}/api/postAPIGetAlerts
Ex: Request
{
"StartDate": "2024-02-05 11:59:45",
"EndDate": "2024-02-13 12:00:00",
"Filter": "*",
"maxNumberOfResults": 100
}
Ex: Response
{
"data": {
"totalResults": 1650293,
"data": [
{
"Flow_ID": "E2A80A95-A2D3-9D72-8A2B-A14989C0E9DD",
"ML_score": 99.68,
"Alert_IDS": "962a05b2-5045-4211-92a4-a5de6262aab6",
"Packet_IDS": "F513AB01-F980-0CEC-F54F-80005E5D47F4",
"AlertID": "1707824765_BYDGB4DI9NFQXMZ2TOLB",
"AlertName": "Connections",
"UTC_ISO8601": "2024-02-13T11:46:05.402429+00:00",
"Content": "",
"ML_score_sources": [
{
"Name": "PyodIForest",
"ML_score": 98.8,
"Parameters": [
{
"paramName": "behaviour",
"paramValue": "new"
},
{
"paramName": "bootstrap",
"paramValue": "False"
}
]
},
{
"Name": "PyodKNN",
"ML_score": 100,
"Parameters": [
{
"paramName": "algorithm",
"paramValue": "auto"
}
]
},
{
"Name": "PyodLODA",
"ML_score": 99.3,
"Parameters": [
{
"paramName": "contamination",
"paramValue": "0.0015"
}
]
},
{
"Name": "PyodLOF",
"ML_score": 100,
"Parameters": [
{
"paramName": "algorithm",
"paramValue": "auto"
},
{
"paramName": "contamination",
"paramValue": "0.0015"
}
]
},
{
"Name": "PyodOCSVM",
"ML_score": 100,
"Parameters": [
{
"paramName": "cache_size",
"paramValue": "200"
},
{
"paramName": "coef0",
"paramValue": "0.0"
}
]
},
{
"Name": "AmlAE",
"ML_score": 100,
"Parameters": [
{
"paramName": "encoder_neurons",
"paramValue": "[10, 6, 4]"
},
{
"paramName": "decoder_neurons",
"paramValue": "[6, 10, 11]"
}
]
}
],
"Alert_IP": "192.168.200.241",
"Alert_MAC": "",
"Alert": {
"index": "day_alerts_2024-02-13",
"type": "alerts",
"id": "KT1Joo0BCsC4LDmy2Xbi",
"score": null
}
},
{
"Flow_ID": "6949C738-F02C-5799-11CC-73E54C47DEA3",
"ML_score": 99.68,
"Alert_IDS": "962a05b2-5045-4211-92a4-a5de6262aab6",
"Packet_IDS": "310935D0-499D-47ED-BE65-DA4CF4BE5308",
"AlertID": "1707824764_WTXI5U8XIP53LBGIINRL",
"AlertName": "Connections",
"UTC_ISO8601": "2024-02-13T11:46:04.073214+00:00",
"Content": "",
"ML_score_sources": [
{
"Name": "PyodIForest",
"ML_score": 98.8,
"Parameters": [
{
"paramName": "behaviour",
"paramValue": "new"
},
{
"paramName": "bootstrap",
"paramValue": "False"
}
]
},
{
"Name": "PyodKNN",
"ML_score": 100,
"Parameters": [
{
"paramName": "algorithm",
"paramValue": "auto"
},
{
"paramName": "contamination",
"paramValue": "0.0015"
}
]
},
{
"Name": "PyodLODA",
"ML_score": 99.3,
"Parameters": [
{
"paramName": "contamination",
"paramValue": "0.0015"
},
{
"paramName": "n_bins",
"paramValue": "auto"
}
]
},
{
"Name": "PyodLOF",
"ML_score": 100,
"Parameters": [
{
"paramName": "algorithm",
"paramValue": "auto"
}
]
},
{
"Name": "PyodOCSVM",
"ML_score": 100,
"Parameters": [
{
"paramName": "cache_size",
"paramValue": "200"
},
{
"paramName": "coef0",
"paramValue": "0.0"
}
]
},
{
"Name": "AmlAE",
"ML_score": 100,
"Parameters": [
{
"paramName": "encoder_neurons",
"paramValue": "[10, 6, 4]"
},
{
"paramName": "decoder_neurons",
"paramValue": "[6, 10, 11]"
}
]
}
],
"Alert_IP": "192.168.200.182",
"Alert_MAC": "",
"Alert": {
"index": "day_alerts_2024-02-13",
"type": "alerts",
"id": "8j1Joo0BCsC4LDmy1HSy",
"score": null
}
},
{
"Flow_ID": "A7637DE0-DBD2-C48F-A149-1D07DB4C9D44",
"ML_score": 99.68,
"Alert_IDS": "962a05b2-5045-4211-92a4-a5de6262aab6",
"Packet_IDS": "F24BEC7E-F2DA-4327-C75A-88B9DE3AB69B",
"AlertID": "1707824763_ZCKF4YMHQ7DG36UUX8V5",
"AlertName": "Connections",
"UTC_ISO8601": "2024-02-13T11:46:02.771659+00:00",
"Content": "",
"ML_score_sources": [
{
"Name": "PyodIForest",
"ML_score": 98.8,
"Parameters": [
{
"paramName": "behaviour",
"paramValue": "new"
},
{
"paramName": "bootstrap",
"paramValue": "False"
}
]
},
{
"Name": "PyodKNN",
"ML_score": 100,
"Parameters": [
{
"paramName": "algorithm",
"paramValue": "auto"
},
{
"paramName": "contamination",
"paramValue": "0.0015"
}
]
},
{
"Name": "PyodLODA",
"ML_score": 99.3,
"Parameters": [
{
"paramName": "contamination",
"paramValue": "0.0015"
},
{
"paramName": "n_bins",
"paramValue": "auto"
}
]
},
{
"Name": "PyodLOF",
"ML_score": 100,
"Parameters": [
{
"paramName": "algorithm",
"paramValue": "auto"
},
{
"paramName": "contamination",
"paramValue": "0.0015"
}
]
},
{
"Name": "PyodOCSVM",
"ML_score": 100,
"Parameters": [
{
"paramName": "cache_size",
"paramValue": "200"
},
{
"paramName": "coef0",
"paramValue": "0.0"
}
]
},
{
"Name": "AmlAE",
"ML_score": 100,
"Parameters": [
{
"paramName": "encoder_neurons",
"paramValue": "[10, 6, 4]"
},
{
"paramName": "decoder_neurons",
"paramValue": "[6, 10, 11]"
}
]
}
],
"Alert_IP": "192.168.200.90",
"Alert_MAC": "",
"Alert": {
"index": "day_alerts_2024-02-13",
"type": "alerts",
"id": "kz1Joo0BCsC4LDmyz3Oc",
"score": null
}
}
]
},
"isSuccess": true,
"message": "",
"errorMessage": null
}
Method - GetSingleAlerts
- In order to retreive a single specific alert, use a AlertID filter as in the follosing example:
AlertID: 1707824765_BYDGB4DI9NFQXMZ2TOLB
GetSingleAlerts: /api/postAPIGetAlerts
{
"Filter": "1707824765_BYDGB4DI9NFQXMZ2TOLB"
}
Method - postGetTrafficCountByField
To extract traffic information, use the postGetTrafficCountByField method with the following parameters:
- StartDate: the start time of the search
- EndDate: the end time of the search
- Filter: the OpenSearch filter, a query string query for data filtering
- Field: the field you want to search by
- maxNumberOfResults: The upper limit of data entries provided by an API call to a single request
The method is:
https://{NETALERT_IP}/api/postGetTrafficCountByField
Ex: Request
{
"StartDate": "2024-02-05 11:59:45",
"EndDate": "2024-02-05 12:00:00",
"Filter": "",
"Field": "SrcIP",
"maxNumberOfResults": 100
}
Ex: Response
{
"data": {
"totalResults": 1420,
"data": [
{
"key": "192.168.200.181",
"value": 899
},
{
"key": "192.168.200.190",
"value": 78
},
{
"key": "192.168.200.99",
"value": 75
}
]
},
"isSuccess": true,
"message": "",
"errorMessage": null
}
Method - postGetSrcIPConnections
To extract traffic information, use the postGetSrcIPConnections method with the following parameters:
- StartDate: the start time of the search
- EndDate: the end time of the search
- Filter: the OpenSearch filter, a query string query for data filtering
- Field: the field you want to search by
- maxNumberOfResults: The upper limit of data entries provided by an API call to a single request
The method is:
https://{NETALERT_IP}/api/postGetSrcIPConnections
Ex: Request
{
"StartDate": "2024-02-05 11:59:45",
"EndDate": "2024-02-05 12:00:00",
"Filter": "",
"Field": "SrcIP",
"maxNumberOfResults": 100
}
Ex: Response
{
"data": {
"totalResults": 1420,
"data": [
{
"key": "192.168.200.181",
"value": 899
},
{
"key": "192.168.200.190",
"value": 78
},
{
"key": "192.168.200.99",
"value": 75
},
{
"key": "192.168.200.96",
"value": 65
}
]
},
"isSuccess": true,
"message": "",
"errorMessage": null
}
Method - postGetDestIPConnections
To extract traffic information, use the postGetDestIPConnections method with the following parameters:
- StartDate: the start time of the search
- EndDate: the end time of the search
- Filter: the OpenSearch filter, a query string query for data filtering
- Field: the field you want to search by
- maxNumberOfResults: The upper limit of data entries provided by an API call to a single request
The method is:
https://{NETALERT_IP}/api/postGetDestIPConnections
Ex: Request
{
"StartDate": "2024-02-05 11:59:45",
"EndDate": "2024-02-05 12:00:00",
"Filter": "",
"Field": "SrcIP",
"maxNumberOfResults": 100
}
Ex: Response
{
"data": {
"totalResults": 1420,
"data": [
{
"key": "79.119.244.94",
"value": 893
},
{
"key": "192.168.200.240",
"value": 127
},
{
"key": "192.168.200.10",
"value": 57
},
{
"key": "192.168.200.100",
"value": 34
},
{
"key": "192.168.200.6",
"value": 33
},
{
"key": "192.168.200.250",
"value": 26
},
{
"key": "8.8.8.8",
"value": 24
},
{
"key": "239.255.255.250",
"value": 19
},
{
"key": "142.251.133.67",
"value": 14
},
{
"key": "172.217.17.142",
"value": 13
},
{
"key": "31.13.84.4",
"value": 13
},
{
"key": "142.251.140.42",
"value": 12
},
{
"key": "172.217.169.163",
"value": 12
},
{
"key": "31.13.84.36",
"value": 12
}
]
},
"isSuccess": true,
"message": "",
"errorMessage": null
}
Method - postGetAlertCountByField
To extract traffic information, use the postGetAlertCountByField method with the following parameters:
- StartDate: the start time of the search
- EndDate: the end time of the search
- Filter: the OpenSearch filter, a query string query for data filtering
- Field: the field you want to search by
- maxNumberOfResults: The upper limit of data entries provided by an API call to a single request
The method is:
https://{NETALERT_IP}/api/postGetAlertCountByField
Ex: Request
{
"StartDate": "2024-02-05 11:59:45",
"EndDate": "2024-02-05 12:00:00",
"Filter": "",
"Field": "AlertName",
"maxNumberOfResults": 100
}
Ex: Response
{
"data": {
"totalResults": 45,
"data": [
{
"key": "DNSRequests",
"value": 40
},
{
"key": "Connections",
"value": 3
},
{
"key": "BruteForce",
"value": 1
},
{
"key": "IOCIP",
"value": 1
}
]
},
"isSuccess": true,
"message": "",
"errorMessage": null
}
Method - GetPcap
Retrieves the captured packets for a specific flow, so a recorded conversation can be downloaded and examined in an external tool.
The flow is identified by its Flow_ID, which is present in the results of a traffic request.
The method is:
https://{NETALERT_IP}/api/GetPcap
{
"Flow_ID": "C470E583-55C1-AA72-5AAF-7AF2196FDE1A"
}
The response carries the capture together with a filename for it. Note that packet recording is limited in size, so a capture represents the beginning of a conversation rather than necessarily the whole of it.
Method - GetAlerts
Returns alerts matching a filter, in the same request style as postAPIGetAlerts above.
The method is:
https://{NETALERT_IP}/api/GetAlerts
The response contains the matching alerts along with the total number of results, so a client can tell whether more data exists beyond the entries returned.
Method - GetTraffic
The traffic equivalent of GetAlerts, returning traffic records matching a filter.
The method is:
https://{NETALERT_IP}/api/GetTraffic
Method - postGetDataSenseSettings
Returns the current DataSense capture settings for the instance. This is useful for confirming externally how an appliance is configured to capture — for example when auditing several instances — without opening each web interface.
The method is:
https://{NETALERT_IP}/api/postGetDataSenseSettings
Method - postValidateProxyConnection
Checks whether a connection to a remote NETALERT instance can be established with the supplied details. Use it when configuring Remote Instances to confirm the target is reachable before saving the configuration.
The method is:
https://{NETALERT_IP}/api/postValidateProxyConnection
Agent enrollment and flow gateway endpoints
The following endpoints exist for the lightcollector installer and the flow gateway. They are called automatically by those components and are not intended for general integration; they are listed here so that they can be accounted for in firewall rules and security reviews.
Agent enrollment
These endpoints are used by the installer that Generate deploy command produces. They do not
use an API key. Each request carries the enrollment token from the deploy command, which is
single-use and expires one hour after it is generated; a missing, used or expired token is refused
with 403.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/lc/enroll?token={TOKEN}&os=linux | Returns the installer script. Only os=linux is supported. |
| GET | /api/lc/binary?token={TOKEN} | Returns the agent binary, fetched from the flow gateway. |
| POST | /api/lc/complete | Completes enrollment and consumes the token. The body carries the token and the host name; the response carries the agent’s configuration and credentials. |
Flow gateway
The flow gateway uses these endpoints to learn which agents may publish and to report when each agent last sent flows, which is what the Last flow column of Agent Management shows.
| Method | Path | Purpose |
|---|---|---|
| GET | /apiv2/lc/agents | Returns the agents that are currently enrolled. Revoked agents are not included. |
| POST | /apiv2/lc/seen | Reports the time flows were last received from each agent. |
Both are authenticated with Authorization: Bearer {API_KEY}, using an active API key whose remote
host is the host name of the flow gateway as configured in LightcollectorGatewayURL. Unlike the
other methods, the request is not checked against its source address, because the gateway’s
address can change when it is restarted; only keys registered for the gateway host are accepted on
these two paths. Any other request is refused with 401 Unauthorized.