About Events API

The Argus events API provides endpoints for searching and fetching events, as well as event statistics.

The Event API uses role based access control, so any search will be limited to the customers for which the user has permission to view events.
In addition, fetching events by case provides access to the events associated with that case, provided that the user has read access to the case.

Please read the General Integration Guide to learn the general concepts and common data structures used throughout the Argus API.

Detailed API documentation

The Swagger API documentation is always up-to-date and lets you try out any query with your user session or an API-key.

Integration guide

Fetch a single event

To fetch an event, append the event ID to the base URL

curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/events/v1/AGGR/1569185283911/2171/6c36deb6-d5e3-461c-bab4-fca397006cb9

This returns the entire event:

{
  "responseCode": 200,
  "limit": 0,
  "offset": 0,
  "count": 0,
  "metaData": {},
  "messages": [],
  "data": {
    "customerInfo": {
      "id": 2171,
      "shortName": "demo",
      "name": "Demo"
    },
    "properties": {
      "http_protocol": "HTTP/1.1",
      "event.original.signature": "SNORT-1:41336",
      "agent.parseTimestamp": "1569185281851",
      ...
    },
    "associatedCase": null,
    "location": {
      "shortName": null,
      "name": null,
      "timeZone": "Europe/Oslo",
      "id": 0
    },
    "attackInfo": {
      "alarmID": 58129,
      "alarmDescription": "MALWARE - Andr.Trojan.Sysch variant activity",
      "attackCategoryID": 363,
      "attackCategoryName": "Callback traffic (Check-in) (infected client/server)",
      "signature": "SNORT-1:41336"
    },
    "domain": null,
    "uri": null,
    "count": 1,
    "source": {
      "port": 12342,
      "geoLocation": null,
      "networkAddress": {
        "host": true,
        "ipv6": false,
        "maskBits": 32,
        "multicast": false,
        "public": false,
        "address": "10.5.97.201"
      }
    },
    "destination": {
      "port": 80,
      "geoLocation": {
        "countryCode": "NO",
        "countryName": null,
        "locationName": "",
        "latitude": 52.3824,
        "longitude": 4.8995
      },
      "networkAddress": {
        "host": true,
        "ipv6": false,
        "maskBits": 32,
        "multicast": false,
        "public": true,
        "address": "94.127.56.1"
      }
    },
    "protocol": "0",
    "timestamp": 1569185283911,
    "startTimestamp": 1569185283910,
    "endTimestamp": 1569185283910,
    "lastUpdatedTimestamp": 1569186046339,
    "flags": [
      "BLOCKED",
      "CREATED_BY_ANALYSIS_FILTER",
      "FINALIZED",
      "CUSTOM_SOURCE_AGGREGATION",
      "CUSTOM_DESTINATION_AGGREGATION",
      "SOURCE_IS_CUSTOMERNET"
    ],
    "severity": "high",
    "detailedEventIDS": [],
    "id": "AGGR/1569185283911/2171/6c36deb6-d5e3-461c-bab4-fca397006cb9"
  },
  "size": 0
}

Searching for events

To search for events, query the "aggregated" endpoint to search among all security events.

curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/events/v1/aggregated

See Swagger API documentation for details on available query parameters

Advanced search

To do more advanced filtering, use the advanced search endpoint.

The advanced search endpoint requires a startTimestamp.

curl -H "Argus-API-Key: my/api/key" -XPOST https://api.mnemonic.no/events/v1/aggregated/search -d '{
  "signature": ["SNORT-1:41336"],"startTimestamp":1567288800000
}'
# or using a relative timestamp
curl -H "Argus-API-Key: my/api/key" -XPOST https://api.mnemonic.no/events/v1/aggregated/search -d '{
"signature": ["SNORT-1:41336"],"startTimestamp":"-2days"
}'

See Swagger API documentation under events/events/v1/aggregated/search for example of usage, or go to Models/AggregatedEventSearchCriteria for details on available query parameters.

Searching by IP - CIDR ranges

Argus will by default resolve any CIDR IP range to match any IP contained within that range.

Moreover, Argus will also widen the search to include any covering ranges, i.e. any CIDR range with lower maskbits than specified which will contain the specified range/IP.

Example: Searching for 192.168.1.32/28

  • Will match CIDR range 192.168.1.32/28
  • Will match IP 192.168.1.33 (part of 192.168.1.32/28)
  • Will match CIDR range 192.168.1.40/29 (part of 192.168.1.32/28)
  • Will match CIDR range 192.168.1.0/24 (covers 192.168.1.32/28)
  • Will match CIDR range 0.0.0.0/0 (covers 192.168.1.32/28)

To control this behaviour, use parameters sourceIPMinBits and destinationIPMinBits. Setting these parameters will limit how wide CIDR ranges will be considered.

# Search for any event with source or destination IP within 192.168.1.0/24. 
# Do not match any CIDR networks wider than 192.168.0.0/20 (neither for source nor destination)
curl -H "Argus-API-Key: my/api/key" -XPOST https://api.mnemonic.no/events/v1/aggregated/search -d '{
  "ip": ["192.168.1.0/24"],
  "startTimestamp":"-2days",
  "sourceIPMinBits":20,  
  "destinationIPMinBits":20
}'

Any CIDR range specified in the search criteria will be searched for, even if the CIDR range has a lower maskbits than specified in these criteria.

Fetching events associated to a case

To fetch events associated with a case, use the eventsByCase endpoint

#list the first 10 events associated with case 12342345
curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/events/v1/case/12342345?limit=10

Fetching large amounts of events

To pull out large amounts of events, it is important to select a strategy which is resource-efficient for both the server and client, as well as a robust strategy which will leave you with a complete dataset. There are several ways for doing this, all depending on your use case. 

Common for all strategies

  • Use a medium-size limit to avoid fetching too big resultsets, but big enough to make transfer efficient
  • Use a clear sorting and limiting strategy to ensure that you will end up with a complete dataset

Pulling events continuously 

This strategy fetches events in the order they are written in the event store. If an event is updated and written again, it will be returned again.
This strategy is well suited for fetching events continously and near real-time.

curl -H "Argus-API-Key: my/api/key" -X POST -H"Content-Type: application/json" https://api.mnemonic.no/events/v1/aggregated/search -d '{
  "startTimestamp": "2020-01-01T00:00:00Z", //need to set a lower bound for the search
  "limit":1000,
  "sortBy":"lastUpdatedTimestamp"
}'

This will fetch the first 1000 events sorted by event lastUpdatedTimestamp. The response 

{
  "responseCode": 200,
  ...
  "data": [
    ...
    {..., "lastUpdatedTimestamp": 1581721863924, ... }
  ]
}

Subsequent requests should use the lastUpdatedTimestamp value of the last event in the previous result, to fetch the next 1000 events.

curl -H "Argus-API-Key: my/api/key" -X POST -H"Content-Type: application/json" https://api.mnemonic.no/events/v1/aggregated/search -d '{
  "startTimestamp": "2020-01-01T00:00:00Z", //need to set a lower bound for the search
  "lastUpdatedTimestamp": 1581721863924
  "limit":1000,
  "sortBy":"lastUpdatedTimestamp"
}'

  • No labels