Skip to content

EventFilter integration guide

About EventFilter API

The Argus EvenFilter API provides endpoints for creating, updating, and fetching different types of event filters.

The EvenFilter API uses role based access control for read- and write access to eventfilters per customer.

In the V2 API we separate between the three main types of filter:

Analysis filters

Analysis filters use Esper to analyse an event stream. Esper is an advanced Event Processing Language(ELP) which supports high throughput and advanced logic for selecting interesting events. Events that match an EPL expression generates a new Argus event, which can then be modified using a Groovy script before it is sent to be reported and analysed.

Analysis filters always have the following properties:

  • statementCode - An ELP expression to select events in an event stream
  • triggerCode - Groovy code to manipulate the generated event
  • name - A unique name for this event. In argus the event will be named "ARGUS-"
Annotation filters
Annotation filters work the same way as analysis filters, but instead of generating new events the filter will enrich the matching event.
Match filters

Match filters compare events against a set of criteria. If the criteria match then one or more actions will be performed on the event. Possible actions are:

  • drop - If the drop action is added, the event is dropped and won't be sendt forward
  • newSeverity - If newSeverity is set, the severity of the event is set to the new value
  • newAggregationKey - If newAggregationKey is set, then the aggregation key is set to the new value
  • newSourceAggregationBits - If newSourceAggregationBits is set, the aggregation bits for the source IP is set to the selected value
  • newDestinationAggregationBits - If newDestinationAggregationBits is set, the aggregation bits for the destination IP is set to the selected value
  • transformCode - If transformCode is set, the groovy code is run is run on the event.
  • continueAfterTransform - If continueAfterTransform is set, the filter matcher will continue looking for matching filters

In the V2 API, new match filters that are created are IPAttackEventMatchFilter in the V1 api.

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

Tip

The Swagger API documentation is always up-to-date and lets you try out any query with your user session or an API-key.

Analysis filter

Fetch a single analysis filter

Analysis filters are fetched by ID. Filters are by default returned without the code parts. If you want the code add includeCode=true to the query. 

1
2
# Fetch the analysis filter with ID 1. Include the code in the response
curl https://api.mnemonic.no/eventfilters/v2/analysis/1?includeCode=true

Add an analysis filter

Adding an analysis filter requires at least a name, statementCode, triggerCode and an actionName. The statement and trigger code is validated by the back end, and the request will fail if the code is not valid.

1
2
3
4
5
6
7
# Add a minimal analysis filter
curl -X POST https://api.mnemonic.no/eventfilters/v2/analysis -d '{
      "name": "Filter name",
      "statementCode": "A valid esper statement",
      "triggerCode": "Valid groovy code",
      "actionName": "A unique name for the generated event"
    }'

Update an analysis filter

Use a PUT request on the filter to update it. The update should include at least one field to change, and must contain a comment describing why the change was made to the filter. When a filter is updated, the old version is stored as a revision of the filter. 

1
2
3
4
5
6
# Minimal request to update an analysis filter
curl -X PUT https://api.mnemonic.no/eventfilters/v2/analysis/1 -d '{
{
  "name": "Updated filter name",
  "comment": "The filter was updated to show of the API"
}'

Fetch an analysis filter's revisions

You can fetch the earlier revisions of a filter. The revisions returned by this endpoint do not include all the fields of the filter. To get all the fields the filter must be fetched explicitly 

1
2
# Fetch the revisions of the analysis filter with ID 1
curl https://api.mnemonic.no/eventfilters/v2/analysis/1/revisions

Duplicate an analysis filter

To use an existing filter as a starting point you can duplicate it. A duplicated filter is identical to the original, except that it has a new ID and that it doesn't have the revision history.

Note that while the request does not take any arguments, it does require an empty request body.

1
2
# Fetch the analysis filter with ID 1. Include the code in the response
curl -X POST https://api.mnemonic.no/eventfilters/v2/analysis/1/duplicate -d '{}'

Searching for analysis filters

Filters can be found either using the advanced POST search endpoint, or a simple GET list endpoint.

1
2
3
4
5
6
7
8
# Simple search for analysis filters with "Filter" in the field name, which is the default field 
curl https://api.mnemonic.no/eventfilters/v2/analysis?keywords=Filter

# Advances search for  analysis filters with "groovy" in the field triggerCode
curl -X POST https://api.mnemonic.no/eventfilters/v2/analysis/search -d '{
    "keywords": "groovy",
    "keywordFieldStrategy": ["triggerCode"]
}'

Deleting an analysis filter

Filters are deleted using DELETE request. Note that deleting filter does not remove it from the database, it will only be marked as deleted in the API.

1
2
# Delete the analysis filter with ID 1
curl -X DELETE 'https://api.mnemonic.no/eventfilters/v2/analysis/1'

Set analysis filter log level

Use this endpoint to change the log level of filter instances.

1
2
3
4
# Set the log level of the analysis filter with ID 1 to debug
curl -X PUT https://api.mnemonic.no/eventfilters/v2/analysis/1/logging -d '{
  "logLevel": "debug"
}'

Reviving an analysis filter

This can be useful if you need to undelete an analysis filter. Note that while the request does not take any arguments, it does require an empty request body.

1
2
# Revive the analysis filter with ID 1
curl -X PUT 'https://api.mnemonic.no/eventfilters/v2/analysis/1/revive' -d '{}'

Get the status of an analysis filter

Shows the current status of the different filter instances. This will return the status for all the instances

1
curl  'https://api.mnemonic.no/eventfilters/v2/analysis/1/status'

Enable/disable analysis filter instance running on a host

Enables/disables an analysis filter instance running on a host

1
2
3
4
# Disable the instance of the analysis filter with ID 1 running on the instance with ID 2
curl -X PUT 'https://api.mnemonic.no/eventfilters/v2/analysis/1/2/disable'
# Enable the instance of the analysis filter with ID 1 running on the instance with ID 2
curl -X PUT 'https://api.mnemonic.no/eventfilters/v2/analysis/1/2/enable'

Annotation filter

Fetch a single annotation filter

Annotation filters are fetched by ID. Filters are by default returned without the code parts. If you want the code add includeCode=true to the query.

1
2
# Fetch the annotation filter with ID 2. Include the code in the response
curl 'https://api.mnemonic.no/eventfilters/v2/annotation/2?includeCode=true'

Add an annotation filter

Adding an annotation filter requires at least a name, statementCode, and triggerCode. The statement and trigger code are validated by the backend, and the request will fail if the code is not valid.

1
2
3
4
5
6
7
# Add a minimal annotation filter
curl -X POST 'https://api.mnemonic.no/eventfilters/v2/annotation' -d '{
  "name": "Filter name",
  "statementCode": "A valid esper statement",
  "triggerCode": "Valid groovy code",
  "actionName": "A unique name for the generated event"
}'

Update an annotation filter

Use a PUT request on the filter to update it. The update should include at least one field to change, and must contain a comment describing why the change was made to the filter. When a filter is updated, the old version is stored as a revision of the filter.

1
2
3
4
5
# Minimal request to update an annotation filter
curl -X PUT 'https://api.mnemonic.no/eventfilters/v2/annotation/2' -d '{
  "name": "Updated filter name",
  "comment": "The filter was updated to show of the API"
}'

Fetch an annotation filter's revisions

You can fetch the earlier revisions of a filter. The revisions returned by this endpoint do not include all the fields of the filter. To get all the fields the filter must be fetched explicitly

1
2
# Fetch the revisions of the annotation filter with ID 2
curl 'https://api.mnemonic.no/eventfilters/v2/annotation/2/revisions'

Duplicate an annotation filter

To use an existing filter as a starting point you can duplicate it. A duplicated filter is identical to the original, except that it has a new ID and that it doesn't have the revision history.

Note that while the request does not take any arguments, it does require an empty request body.

1
2
# Fetch the annotation filter with ID 1. Include the code in the response
curl -X POST 'https://api.mnemonic.no/eventfilters/v2/annotation/2/duplicate' -d '{}'

Searching for annotation filters

Filters can be found either using the advanced POST search endpoint, or a simple GET list endpoint.

1
2
3
4
5
6
7
8
# Simple search for analysis filters with "Filter" in the field name, which is the default field 
curl https://api.mnemonic.no/eventfilters/v2/annotation?keywords=Filter

# Advances search for  annotation filters with "groovy" in the field triggerCode
curl -X POST https://api.mnemonic.no/eventfilters/v2/annotation/search -d '{
    "keywords": "groovy",
    "keywordFieldStrategy": ["triggerCode"]
}'

Deleting an annotation filter

Filters are deleted using DELETE request. Note that deleting filter does not remove it from the database, it will only be marked as deleted in the API.

1
2
# Delete the annotation filter with ID 2
curl -X DELETE https://api.mnemonic.no/eventfilters/v2/annotation/2

Set annotation filter log level

Use this endpoint to change the log level of filter instances.

1
2
3
4
# Set the log level of the annotation filter with ID 2 to debug
curl -X PUT https://api.mnemonic.no/eventfilters/v2/annotation/2/logging -d '{
  "logLevel": "debug"
}'

Reviving an annotation filter

This can be useful if you need to undelete an annotation filter. Note that while the request does not take any arguments, it does require an empty request body.

1
2
# Revive the annotation filter with ID 2
curl -X PUT https://api.mnemonic.no/eventfilters/v2/annotation/2/revive -d '{}'

Get the status of an annotation filter

Shows the current status of the different filter instances. This will return the status for all the instances

1
curl  https://api.mnemonic.no/eventfilters/v2/annotation/2/status

Enable/disable annotation filter instance running on a host

Enables/disables an annotation filter instance running on a host

1
2
3
4
# Disable the instance of the annotation filter with ID 1 running on the instance with ID 2
curl -X PUT 'https://api.mnemonic.no/eventfilters/v2/annotation/1/2/disable' 
# Enable the instance of the annotation filter with ID 1 running on the instance with ID 2
curl -X PUT 'https://api.mnemonic.no/eventfilters/v2/annotation/1/2/enable'

Match filter

Fetch a single match filter

Match filters are fetched by ID. Filters are by default returned without the code parts. If you want the code add includeCode=true to the query.

1
2
# Fetch the match filter with ID 3. Include the code in the response
curl https://api.mnemonic.no/eventfilters/v2/match/3?includeCode=true

Add a match filter

Adding a match filter requires at least a name, though it doesn't really do anything unless it has both some field to match events, and some action to perform when an event matches.

1
2
3
4
5
6
7
# Add a minimal match filter which changes the severity of an event 
curl -X POST https://api.mnemonic.no/eventfilters/v2/match -d '{
{
  "name": "Filter name",
  "matchCode": "Valid groovy code",
  "newSeverity": "high" 
}'

Update a match filter

Use a PUT request on the filter to update it. The update should include at least one field to change, and must contain a comment describing why the change was made to the filter. When a filter is updated, the old version is stored as a revision of the filter.

1
2
3
4
5
6
# Minimal request to update a match filter
curl -X PUT https://api.mnemonic.no/eventfilters/v2/match/3 -d '{
{
  "name": "Updated filter name",
  "comment": "The filter was updated to show of the API"
}'

Fetch a match filters revisions

You can fetch the earlier revisions of a filter. The revisions returned by this endpoint do not include all the fields of the filter. To get all the fields the filter must be fetched explicitly

1
2
# Fetch the revisions of the match filter with ID 3
curl https://api.mnemonic.no/eventfilters/v2/match/3/revisions

Duplicate a match filter

To use an existing filter as a starting point you can duplicate it. A duplicated filter is identical to the original, except that it has a new ID and that it doesn't have the revision history.

Note that while the request does not take any arguments, it does require an empty request body.

1
2
# Fetch the match filter with ID 3
curl -X POST https://api.mnemonic.no/eventfilters/v2/match/3/duplicate -d '{}'

Searching for match filters

Filters can be found either using the advanced POST search endpoint, or a simple GET list endpoint.

1
2
3
4
5
6
7
8
# Simple search for match filters with "Filter" in the field name, which is the default field 
curl https://api.mnemonic.no/eventfilters/v2/match?keywords=Filter

# Advances search for  annotation filters with "groovy" in the field matchCode
curl -X POST https://api.mnemonic.no/eventfilters/v2/match/search -d '{
    "keywords": "groovy",
    "keywordFieldStrategy": ["triggerCode"]
}'

Deleting a match filter

Filters are deleted using DELETE request. Note that deleting filter does not remove it from the database, it will only be marked as deleted in the API.

1
2
# Delete the match filter with ID 3
curl -X DELETE https://api.mnemonic.no/eventfilters/v2/match/3

Set annotation filter log level

Use this endpoint to change the log level of filter instances.

1
2
3
4
# Set the log level of the match filter with ID 3 to debug
curl -X PUT https://api.mnemonic.no/eventfilters/v2/match/3/logging -d '{
  "logLevel": "debug"
}'

Reviving a match filter

This can be useful if you need to undelete a match filter. Note that while the request does not take any arguments, it does require an empty request body.

1
2
# Revive the match filter with ID 3
curl -X PUT https://api.mnemonic.no/eventfilters/v2/match/3/revive -d '{}'

Get the status of a match filter

Shows the current status of the different filter instances. This will return the status for all the instances

1
curl https://api.mnemonic.no/eventfilters/v2/match/3/status

Debug a match filter

Runs the match filter against a set of events. If the filter does not match, it returns which field doesn't match

1
2
3
4
# Debugs the match filter with ID 3 against an event
curl -X POST https://api.mnemonic.no/eventfilters/v2/match/3/debug -d '{
  "eventIDs": ["eventID"]
}'

Enable/disable match filter instance running on a host

Enables/disables a match filter instance running on a host

1
2
3
4
# Disable the instance of the match filter with ID 1 running on the instance with ID 2
curl -X PUT 'https://api.mnemonic.no/eventfilters/v2/match/1/2/disable' 
# Enable the instance of the match filter with ID 1 running on the instance with ID 2
curl -X PUT 'https://api.mnemonic.no/eventfilters/v2/match/1/2/enable'