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 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 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 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