Event Service v2¶

Danger

The V2 API is under development, and requires user feedback before it is ready for production.

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 Overview to learn the general concepts and common data structures used throughout the Argus API.

In the v2 api we have unified the different event types from v1. We now only return a single Event type, and have the type as a field on the response model. We also allow filtering in search and stats apis if you are only interested in one of the types.

In v2 we also reduce the size of the default event returned. We no longer return the properties, or comments attached to a case by default. Instead, we have added options to the different endpoints to allow the user more control over which fields they need returned.

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/v2/event/1569185283911/2171/6c36deb6-d5e3-461c-bab4-fca397006cb9

This returns the default event model

If you want to get the properties, comments, or sub events these have to be requested specifically. Properties can be requested either by key, or you can request to get all the properties returned. Details on how to request these fields can be found on the swagger page

Fetch the payload of an event¶

To fetch the payload of an event, use the same url as for fetching an event, but add /payload at the end

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

This returns the payload model

Fetch the PCAP of an event¶

To fetch the PCAP of an event, use the same url as for fetching an event, but add /pcap at the end

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

This returns the actual PCAP data of the event

Fetch the lineage of an event¶

It can be difficult to know when, how, and where an event has been updated. To make it easier to reason about we have created a lineage endpoint which will return changes made to an event. The types of changes that are stored are: - created - When the event was created - updated - When the event was updated - assessed - When the event was assessed - indexedElasticSearch - When the event was indexed into elasticsearch - indexedOpenSearch - When the event was indexed into OpenSearch

To fetch the lineage of an event, use the same url as for fetching an event, but add /lineage at the end

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

This returns the lineage events stored for the event

Fetch events associated with a case¶

This returns result-set of the default event model
The endpoint internally only uses streaming. Uses the same count logic as in V1.

To fetch the events associated with a case, use the following endpoint:

# list the first 25 events associated with case 12342345, include selected properties: prop1, prop2
curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/events/v2/case/12342345?includeProperties=prop1&includeProperties=prop2

Supported request parameters: - includeAllProperties: boolean, whether to include/exclude all properties, overrides the selection of 'includeProperties' if set to true, default is false - includeComments: boolean, whether to include/exclude comments, default is false - includeSubEvents: boolean, whether to include/exclude sub-events, default is false - includeProperties: set of property keys, which properties to include, has any effect if includeAllProperties=false, default empty - offset: integer, the amount of events to skip from the beginning, default 0 - limit: integer, the max amount of events to return, 0 means no limit, default 25 - sortBy: list of field names, fields to sort events by, without a sign is ascending, with '-' sign is descending, currently supports only timestamp-field, default '-timestamp'

Search for events¶

Searching for events can be done using the simple search GET endpoint or the advanced search POST endpoint. Both searches return the default event model, with the option to return comments, sub events, and a selection of properties.

Please read the Overview to learn about general concepts for search endpoints.

Simple search¶

For simple search, we allow searching for a small subset of the fields. If a filter parameter is repeated the values are OR-ed together

# search for events with signature "ARGUS-HTTP_POST_IP", customer "mycustomer" 
curl -X GET -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/events/v2/event?signature=ARGUS-HTTP_POST_IP&customer=mycustomer

# search for events with customer either shortname mycustomer or ID 1
curl -X GET -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/events/v2/event?customer=mycustomer&customer=1

See the Swagger API documentation for details on available query parameters

Advanced search¶

# search for low severity, aggregated events from the mnemonic customer, where one of the endpoints is a customer network
# the attack category is "Access of domain or IP with bad reputation", and the property 'network.protocol' is set
curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/events/v2/event/search -d '{
  "type": ["aggregated"],
  "severity": ["low"],
  "customer": ["mnemonic"],
  "endpoint": [{"includeFlag": ["isCustomerNet"]}],
  "attack": [{"attackCategory": ["353"]}],
  "property": [{"key": "network.protocol"}]
}'

See the Swagger API documentation for details on available query parameters

Event Statistics¶

The statistics endpoint allows a user to retrieve quantitative data about a set of events that match certain search criteria.

The statistics request supports the same search criteria as the search endpoint; the statistics criteria then apply to the results of the search.

The statistics request itself is composed of 2 key components:

field aggregation - the field(s) by which we want to group the resulting events and structure the response
range metrics - return counts for events matching the defined timestamp filters

For example, we could ask for statistics for events created the last week, grouped by customer and the type of attack the event was categorized as.

curl -X 'POST' \
  'https://api.mnemonic.no/events/v2/event/statistics' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Argus-API-Key: my/api/key' \
  -d '
{
  "type": [
    "aggregated"
  ],
  "startTimestamp": "-7d",
  "timeFieldStrategy": [
    "created"
  ],
  "severity": [
    "high",
    "critical"
  ],
  "groupBy": [
    {
      "field": "customer"
    },
    {
      "field": "attackCategory"
    }
  ]
}'

The response's structure is a unidirectional tree where the branches represent unique field aggregation values i.e. in this example groups and definitions.

Each branch consists of the count of assets within the branch and metadata containing

identifier - the unique ID of the object
shortName - the unique human/machine readable identifier
name - the human readable non-unique identifier
type - the type of the metadata. This can be used to looking up the actual objects grouped by.

Each branch then potentially contains buckets, which represent the next layer in the tree.

The leaves contain the actual metrics response e.g.:

{
  "group": {
    "identifier": "123",
    "shortName": "customer",
    "displayName": "Customer",
    "type": "customer"
  },
  "count": 3562,
  "rawEventCount": 18246,
  "buckets": [
    {
      "group": {
        "identifier": "373",
        "shortName": "68430823-db2a-11eb-91d4-005056beea2d",
        "displayName": "Attempted application exploit",
        "type": "attackCategory"
      },
      "count": 988,
      "rawEventCount": 3518,
      "buckets": [],
      "timeline": []
    }
  ],
  "timeline": []
}

See the Swagger API documentation for details on available query parameters and fields to group by.

Event assessment¶

This endpoint performs event (re-)assessment and returns the default event model with the updated event data.
Details about the request payload are specified in the event assessment model.

curl -X 'PUT' \
 'https://api.mnemonic.no/events/v2/event/1569185283911/2171/6c36deb6-d5e3-461c-bab4-fca397006cb9/assess' \
 -H "Argus-API-Key: my/api/key" \
 -d '{
   "enableFlag": [
     "falsePositive"
   ],
   "disableFlag": [
     "identifiedThreat"
   ],
   "newSeverity": "low",
   "comment": "your comment",
   "handledByAnalyst": false,
   "associateCase": [
     12340
   ],
   "disassociateCase": [
     12341
   ],
   "trigger": [
     "slaViolation"
   ]
 }'

Event assessment by compatibility path¶

This endpoint performs event (re-)assessment by compatibility path, which includes the event type, that is internally ignored.
It returns the default event model with the updated event data.
Details about the request payload are specified in the event assessment model.

curl -X 'PUT' \
 'https://api.mnemonic.no/events/v2/event/AGGR/1569185283911/2171/6c36deb6-d5e3-461c-bab4-fca397006cb9/assess' \
 -H "Argus-API-Key: my/api/key" \
 -H 'Content-Type: application/json' \
 -d '{
   "enableFlag": [
     "falsePositive"
   ],
   "disableFlag": [
     "identifiedThreat"
   ],
   "newSeverity": "low",
   "comment": "your comment",
   "handledByAnalyst": false,
   "associateCase": [
     12340
   ],
   "disassociateCase": [
     12341
   ],
   "trigger": [
     "slaViolation"
   ]
 }'

Bulk assessment of events¶

This endpoint performs assessment of multiple events with one request.
The events are included into the assessment by the search criteria that is part of the payload. The second part of the payload consists of the event assessment parameters.
Details about the request payload are specified in the event bulk assessment model.
The endpoint returns the event bulk assessment response which contains the results of the assessment.

curl -X 'PUT' \
 'https://api.mnemonic.no/events/v2/event/assess' \
 -H "Argus-API-Key: my/api/key" \
 -H 'Content-Type: application/json' \
 -d '{
   "assessment": {
     "enableFlag": [
       "falsePositive"
     ],
     "disableFlag": [
       "identifiedThreat"
     ],
     "newSeverity": "low",
     "comment": "your comment",
     "handledByAnalyst": false,
     "associateCase": [
       12340
     ],
     "disassociateCase": [
       12341
     ],
     "trigger": [
       "slaViolation"
     ]
   },
   "search": {
     "eventIdentifier": [
       "AGGR/1569185283911/2171/6c36deb6-d5e3-461c-bab4-fca397006cb9",
       "AGGR/1569185283911/2171/71d2a74d-ae3b-4656-896a-75edb85f9080"
     ]
   }
 }'

Event Model¶

This is the model that will be returned from the fetch and search endpoints and describes a single event

id: The full id of the event. This follows the same pattern as the v1 api for consistency.; e.g.: AGGR/1707750245205/204/6af7dee0-08b6-437e-a932-57a5953b26ed
eventID: The UUID of the event. This is enough to uniquely identify the event
type: The type of the event. Will be one of aggregated or raw
source: The origin IP of the event. See the endpoint model for more details
destination: The destination IP of the event. See the endpoint model for more details
customer: Information about the customer the event originated from
location: Where the sensor detecting the event was located.; See location in the sensor integration guide for more details
signature: The signature is the id of an alarm mapping, telling us why the event was triggered
alarm: The alarm that was triggered by the event. This is meant to quickly help the analyst assess incoming recognized attacks
attackCategory: The attack category of the alarm
domain: The domain associated to the request, represented as by a FQDN (Fully Qualified Domain Name) string
uri: The related URI
count: The number of underlying events. This value will be 0 for raw events
severity: The severity of the event. Will be one of low, medium, high, or critical
timestamps: The timestamps associated with the event. See the timestamp model for more details
sensor: Information about the sensor that reported the event
protocol: The protocol the event used. Will be one of tcp, udp, icmp, ip, esp, or unknown
associatedCases: The cases that the event is associated to. See the case model for more details
subEvents: The IDs of the sub events of the event. Will by default not be returned
properties: The properties of the event. See the properties model for more details.; Will by default not be returned
comments: The comments that have been left on the event. Will by default not be returned
flags: The flags that have been put on the event. See the event flags for more details

Payload Model¶

id: The id of the event
type: The type of the payload. Will be one of ethernet, binary, string or pcap
payload: The actual payload of the event. Will be base64 encoded if the payload type not string

Endpoint Model¶

address: The IP address of the endpoint
host: The host name of the endpoint
port: The UDP or TCP port of the endpoint
user: The user associated with this endpoint
geoInfo: Information about the geographical location of the endpoint
flags: The flags on the endpoint; Valid values are isCustomerNet, isPartialCustomerNet, customAggregation, and isManagedBySoc

Timestamp Model¶

created: Creation timestamp of the event. This is either the value provided to the collector api, or set to when the service received it if submitted without a timestamp
lastUpdated: Last update timestamp of the event
firstEvent: Timestamp of the first observed event (only for aggregated events)
lastEvent: Timestamp of the last observed event (only for aggregated events)
enginePersisted: Timestamp when the engine persisted the event
firstAssessed: Timestamp when the event was first assessed
firstNotified: Timestamp of the case association with the event

Case Model¶

id: ID of the associated case
subject: Subject of the case
categoryID: The ID of the category of the case
categoryName: The name of the category of the case
serviceID: The ID of the service of the case
serviceName: The name of the service of the case
status: Status of the case. This is one of closed, pendingClose, pendingCustomer, pendingSoc, pendingVendor, workingCustomer, or workingSoc
priority: Priority of the case. This is one of low, medium, high, or critical

Properties Model¶

type: The type of the property. This is one of boolean, long, string, or double
key: Key of the property
values:: The values associated with the key as a list of strings. If you require it in the properties type you have to parse it to the correct type yourself

Event Assessment Model¶

enableFlag: Set of event flags that should be enabled. Overlap with disableFlag will be an invalid request. See event flags for more details about the meaning of the flags. Available flags are: - falsePositive - notAThreat - tuningCandidate - followup - identifiedThreat - acknowledged - partiallyAcknowledged
disableFlag: Set of event flags that should be disabled. Overlap with enableFlag will be an invalid request. Available flags are the same as with enableFlag.
See event flags for more details about the meaning of the flags.
newSeverity: New severity of the event (if not set, keep current severity). Available severities are: - low - medium - high - critical
comment: Assessment comment to the event (not required).
handledByAnalyst: If true, then the event will be flagged as manually assessed by an analyst. Default is false.
associateCase: Set of case IDs that are going to be associated with this event (not required). Specified cases must be readable to the current user, and they must belong to same customer as this event.
disassociateCase: Set of case IDs that are going to be disassociated from this event, should not overlap with case IDs that are going to be associated with this event (not required).
trigger: Set of checks which will be run after assessment (not required). Available triggers are: - slaViolation - internalSlaViolation

Event Bulk Assessment Model¶

assessment: Event assessment model containing the details that are going to be used for this bulk request.
search: Event bulk assessment search criteria containing the search criteria for specifying events to be included into bulk assessment.

Event Bulk Assessment Search Criteria¶

This search criteria extends the event assessment search criteria.
Limit and offset are meant to be used when the volume of a single bulk assessment gets too high. Then it can be split up into sub-batches/pages. SortBy is included to guarantee predictable results for paging. If the volume is too high even for paging with limit and offset, then indexStartTimestamp and indexEndTimestamp can be used for alternative paging.

indexStartTimestamp: Only search in indexes after or on this day. Defaults to current day. Timestamps can be milliseconds since epoch, ISO8601 timestamp, or a string with a relative timestamp. See the general integration guide for more details.
indexEndTimestamp: Only search in indexes before or on this day. Defaults to current day. Timestamps can be milliseconds since epoch, ISO8601 timestamp, or a string with a relative timestamp. See the general integration guide for more details.
limit: Limit the results to the specified amount. If set to 0 we will include all results matching the query. Default is 25.
offset: Skip specified amount of results. DefaultValue is 0.
sortBy: Which field(s) to sort the results by (default is ascending by createdTimestamp). Available sort by fields are: - customerID - eventID - createdTimestamp - lastUpdatedTimestamp - firstEventTimestamp - lastEventTimestamp

Event Bulk Assessment Response¶

successes: Set of IDs of the events that were successfully assessed.
failures: Set with failure info of the events that failed assessment. The failure info contains: - eventID - reason

Event Flags¶

established

This flag is set for an event where the connection is confirmed to be established.

If this is not confirmed (uncertain), the flag is not set

blocked

This flag is set for an event where the connection is confirmed to have been blocked, e.g. an IPS reports an event which has been blocked

partiallyBlocked

This flag is set if this event is only partially blocked. This is used for aggregated events consisting of detailed events only partially flagged with "blocked"

snapshot

This flag is set for all snapshot events. Snapshot events are copies of real events, and should never be part of raw data collection/event query. Snapshots are used to represent snapshots of other events at certain points in time, and should never be changed. However, snapshots may point to a list of detailed events, which may not be snapshots

finalized

This flag is set for a (non-snapshot) aggregated event which is no longer under construction. Aggregated events are aggregated over time, and when no more events will be aggregated into this event, the finalized-flag is set. When this flag is set, further aggregation is not possible

falsePositive

This flag is set if this event has been assessed as a false positive.
For aggregated events, this flag may be set on only some of the detailed events.: This should therefore be seen as an opinion, not a certainty

notAThreat

This flag is set if this event has been assessed as not being a threat.
For aggregated events, this flag may be set on only some of the detailed events.: This should therefore be seen as an opinion, not a certainty

tuningCandidate

This flag is set if this event has been assessed as a tuning candidate.
For aggregated events, this flag may be set on only some of the detailed events.: This should therefore be seen as an opinion, not a certainty

notified

This flag is set if this event has been notified to the customer as part of a customer case. For aggregated events, this flag should only be set if all detailed events are flagged with this flag

followup

This flag is set if this event requires further followup. For aggregated events, this flag may be set on only some of the detailed events. This should therefore be seen as an indication

partiallyNotified

This flag is set if this event has been partially notified to the customer as part of a customer case. This is used when aggregating multiple events, where some of the detailed events are flagged with "notified"

identifiedThreat

This flag marks this event as an identified threat. For aggregated events, this flag may be set on only some of the detailed events. This should therefore be seen as an indication that some part of the aggregated event is an identified threat

This is used for components tagging this event as identified threat based on external information, e.g. an event agent may tag this event as identified threat based on the associated alarm being tagged as very certain/high quality

This should be configured to be the case for events which may be notified to the customer automatically/without further checks

threatCandidate

This flag marks this event as a threat candidate. For aggregated events, this flag may be set on only some of the detailed events. This should therefore be seen as an indication that some part of the aggregated event is a threat candidate

This is used for components tagging this event as a threat candidate based on external information, e.g. an event agent may tag this event as a threat candidate based on the associated alarm being tagged as high quality

This should be configured to be the case for events which have a very high probability of being real threats, but need some further checking before notifying to customer

acknowledged

This flag should be set for all events that have been assessed. This acknowledges the event as being assessed, and not needing further assessment. For an aggregated event, this flag indicates that all detailed events are acknowledged. Use "partiallyAcknowledged" to indicate that some of the detailed events are/may not be acknowledged

partiallyAcknowledged

This flag should be set for events which are partially acknowledged. This is used for aggregated events where some of the detailed events have been acknowledged, and more specifically for events which have been updated after being acknowledged (non-finalized aggregated events)

This should serve as an indication that the event has previously been acknowledged (and probably needs no further work), but that the event has been updated, so there may be additional information contained in this event

severityAdjusted

Indicates that this event has been severity adjusted at some point, e.g. an EventFilter has modified the severity of this event. For aggregated events, this may be an indication that some of the detailed events have this flag set, or that the aggregated event itself has been adjusted (for example due to a high aggregation count)

Property PROPERTY_L_SEVERITY_ADJUSTED_BY_FILTER or PROPERTY_L_SEVERITY_ADJUSTED_BY_USER should be set with a list of userIDs/filterIDs that have adjusted the event

commented

Indicates that there is at least one comment on the event

filtered

Indicates this event has been filtered. E.g. by a EventMatchFilter

checked

Indicates this event has been checked by an external event checker

incompleteDetails

Indicates this event does not have references to all the detailed events which have been aggregated into it

aggregatedBaseEvent

Indicates this aggregated event nevertheless is a base event, i.e. will be aggregated further

remoteStorage

Indicates that this event is stored remotely, i.e. slow/non-local lookup

hasDetails

Indicates that this event has details

hasPayload

Indicates that this event has a saved associated payload

hasPcap

Indicates that this event has a saved associated payload which is PCAP-compatible

associatedToCaseByFilter

Indicates that a filter has associated this event to a case

severityIncreasedByFilter

Indicates that a filter has increased the severity of this event.
When set, "severityAdjusted" will also be set.: Property PROPERTY_L_SEVERITY_INCREASED_BY_FILTER should be set with a list of filterID's that have adjusted the event

severityReducedByFilter

Indicates that a filter has decreased the severity of this event. When set, severityAdjusted will also be set.

Property PROPERTY_L_SEVERITY_REDUCED_BY_FILTER should be set with a list of filterID's that have adjusted the event

createdByAnalysisFilter

Indicates that this event was created by an analysis filter

extendEventTtl

extend ttl flag is needed by EventCassandraManager

initialTuning

Indicates that this event is coming from sensor in initial tuning state

postAnalysis

Indicates that this event is marked for post analysis

partialSslTerminated

Indicates that some of the connection this event represents was SSL-terminated

sslTerminated

Indicates that the connections this event represents was SSL-terminated

autoReport

Indicates that this event should be auto-reported

missingTimestamp

Raw source does not provide time for the event, instead it's the agent set the timestamp

clockOutOfSync

A future timestamp was assigned on the event, and it has been truncated to the current timestamp when encountered e.g. by agent, collector API

dropAnalysis

Raw event marked with this flag will not be processed by analysis filters

escalatedByReputation

Indicate this event has been escalated by reputation

hasSample

Event is related to a sample

storeEvent

Mark on event to make sure send to central to be stored by distributed pipeline

storeAggregated

Mark on event to make sure send to aggregation in distributed pipeline

handledByAnalyst

Mark on event to indicate that it has been assessed by an analyst

slaViolation

Mark on event to indicate that it has been associated with an SLA violation and case

payloadTruncated

Mark on event to indicate that the event's payload had been truncated due to payload size limit

hasStringPayload

Mark on event to indicate that the event's payload is of a string type

reassessed

Mark on event to indicate that the event has been reassessed.

An event is considered reassessed if it has been assessed while having the HANDLED_BY_ANALYST flag set