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 General integration guide 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 General integration guide 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