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.
Fetch a single event
To fetch an event, append the event ID to the base URL
This returns the entire event:
Searching for events
To search for events, query the "aggregated" endpoint to search among all security events.
See Swagger API documentation for details on available query parameters
To do more advanced filtering, use the advanced search endpoint.
The advanced search endpoint requires a startTimestamp.
See Swagger API documentation for details on available search 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
destinationIPMinBits. Setting these parameters will limit how wide CIDR ranges will be considered.
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
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.
This will fetch the first 1000 events sorted by event lastUpdatedTimestamp. The response
Subsequent requests should use the lastUpdatedTimestamp value of the last event in the previous result, to fetch the next 1000 events.
Submitting events via API
The event collector API is designed to allow integration of 3rd party agents to deliver events into Argus.
The API allows submitting single events or a bulk of events, and will handle events asynchronously.
Notes about collector APIs:@tor
- Collector APIs are created for high-capacity, asychronous operation.
- The receiving endpoint will validate the data and the users permissions to add them, and will reject invalid data and data which the user does not have the permission to add.
- However, the API will return successful result once the data is enqueued for storage, so the results may not be immediately available. If the backend engine is under pressure, the actual storage and indexing of the data may be delayed.
- The API does not distinguish between add or update. When storing the events, if the same event ID already exists, the event will be updated with changes from the incoming event.
Note: It is not possible to update a FINALIZED event.
If submitting updates to an existing event which has previously been marked as FINALIZED, the update will be silently ignored.
The submit-API will still return status "accepted".
The ID of an event is a separate object in the submission request, with properties
The id of an event can also be written using an Argus event ID string, e.g. AGGR/1570715141521/1/1679fbfc-1792-4992-8428-3cb4df642fa8
Submitting an event
Submit a new event by calling the single event submission API:
By default, this event will be submitted with the following fields:
- Time: timestamp, startTimestamp and endTimestamp "now"
- Customer: Will be set to the current users customer
- Type: Default event type is "aggregated". Use type "raw" to submit raw events.
- Severity: low
- Count: 1
- Properties: agent.id, agent.timestamp and engine.timestamp
Remaining fields have default value null (not set).
To submit an event for a specific customer, you need to populate the "id" object of the event:
The endpoint will reject the event if the user does not have access to submit events for the specified customer.
The endpoint will respond with code 201, with a status object containing the generated ID of the accepted event.
If the event contained invalid fields, the endpoint will return 412.
Each of the identifying fields (timestamp, customerID, type and UUID) will be given a default value if not specified in the request.
Submitting an update
Submitting an update on a previous event requires the type, timestamp, customer and UUID to be the same as the existing event.
For simplicity, you can use the "id" field to submit the exact ID string returned in the submission status, which is a general Argus event ID:
Submitting with properties
Events can contain an arbitrary number of properties, and each property can have a list of values.
The V1 event search/get API does currently not support multiple values on properties, so an event with multiple property values will be returned as a comma-separated property string
Properties are accumulated on update, so updating an event with new properties will cause the event to contain the accumulated set of properties from all updates/submissions.
Updating an existing property will overwrite the existing value.
The properties are submitted as a map of property keys, each key mapping to a list of values.
For simplicity, sending a single value instead of a list is also supported.
Submitting with flags
Events can contain a set of flags, as defined in the Swagger API documentation.
Flags are accumulated on update, so updating an event with new flags will cause the event to contain the accumulated set of flags from all updates/submissions.
It is not possible to DELETE a flag through an event submission.
Some flags have special handling, called "partial flags".
E.g. for the flag "SOURCE_IS_CUSTOMERNET":
If an event is submitted without this flag, and then updated with this flag, the resulting event will be marked with the partial flag SOURCE_IS_PARTIAL_CUSTOMERNET
Submitting another update with SOURCE_IS_CUSTOMERNET will reset the flag of the event to SOURCE_IS_CUSTOMERNET.
Submitting a bulk of events
When submitting many events, the bulk API is a more efficient solution.
The bulk API accepts a list of events, and an error mode.
The default error mode is "rejectAll", which will reject the entire request with a 412 status if any event is invalid.
Alternatively, error mode "dropInvalid" will drop invalid events, and submit the valid events, before returning status 201.
In mode "dropInvalid", the endpoint will drop events which fail to validate customer or location, or other referenced fields.
However, invalid JSON or invalid fields in the JSON request will still cause a 412 on the entire request.
The status result from the bulk endpoint will list the number of accepted and rejected events, as well as a list of submission status objects, one for each event.
Response from bulk submit with dropped invalid events:
The third event was invalid, and is therefore not assigned an ID. The order of the event status objects in the bulk status object will correspond to the events in the request.
Finalizing an event
To finalize an event, submit the event with the "finalized" property.
Setting the finalized property has the same effect as adding the event flag FINALIZED.
Finalizing events prevents further updates on this event through later event submissions.
If an agent does not expect events to be updated, they should be finalized in the initial submission.
- No labels