Event Service v1#

About the Event Service#

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.

Tip

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

Specific to the Event service is the Event model and its subtypes, raw and aggregated events.

Raw, formerly known as a NIDS (Network intrusion detection system) event, is the direct records of a security event. While aggregated is multiple events that has been merged together to form a more comprehensive model. Both types contains a set of standard fields, see below, and properties that helps describe both what happened and the environment that it happened in. These events can then be connected to ongoing cases for case handlers to deal with.

Event Model#

customerInfo

Information on the customer for whom the event happen.

properties

A list of key-value pairs that details specific information related to the environment, processes the event has been through and appended information by the different agents.
The keys should be written in the format of “key.with.dot.separated.name”, and the value can be Strings, Integers or IPs

comments

Comments added to the event either through automated systems or manually added by an analyst.

associatedCases

Argus cases that are related to the event.

location

Where the request causing the event took place, such as a datacenter, component or simply physical location.

attackInfo

Known information regarding the type of event such as the type of alarm that noticed it, what kind of attack and associated signature.

domain

The domain associated to the request, represented as by a FQDN (Fully Qualified Domain Name) string.

uri

Related URI

count

Number of times the request causing the event has been seen.

source

The originator IP of the request, contains geo location, port and network address.

destination

The destination of the request, contains geo location, port and network address

protocol

The protocol used in the request causing the event.

timestamp

When the event occurred.

startTimestamp

Used for aggregates and represents the first occurrence of the event.

endTimestamp

Used for aggregates and represents the last occurence of the event.

lastUpdatedTimeStamp

When the information on the event was last updated.

flags

A list of states that helps define the event and what has been done during analysis.

severity

How critical the event is and from that how high it should be prioritized by analysts. Ranges from low to critical

detailedEventIDs

Related events, those that builds up the aggregate or simply associated with the event.

id

A unique identifier for the event. Contains the type, timestamp. An example would be AGGR/1569185283911/2171/6c36deb6-d5e3-461c-bab4-fca397006cb9

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 the Swagger API documentation for details on available query parameters

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 eventlastUpdatedTimestamp. 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"
}'