Alarm Integration Guide¶

Overview¶

The Alarm Service provides a system for gathering and organizing info about attacks, how each alarm is mapped to technical signatures, and mapping of alarms to Argus attack categories and MITRE ATT&CK categories.
Changes to Alarms are made available as updates through the Alarm Update WebSocket.
The service also keeps track of the volume and last observation of each signature from the Event Service.

Concepts¶

Attack Category is an arbitrary category for grouping attacks. These categories are defined in Argus, and not part of an external standard.
Alarm brings together the accumulated info about known attacks. This is meant to quickly help the analyst assess incoming recognized attacks. Alarms are also manually created and updated by us. An alarm can have comments, labels, references and links. Alarms can be grouped into attack categories.
Signature is technical attack signature, defined both by external sources and by us. It also provides info about the time when the signature was detected/triggered.
The actual signatures for recognizing attacks are not stored in the alarm service - just the info about the attack. Signatures are not independent entities, but are the primary key of an Alarm Mapping. Signature is also referred to as attack identifier.
Alarm Mapping is the relationship between an alarm and selected signatures. Signatures are mapped to Alarms by a user process or through automated imports via API. An unmapped alarm mapping means that the signature has not yet been mapped to an alarm. Access to view and edit specific mappings are decided by the mapping's customer scope. The scope is populated by mappings being triggered by customers in the Event Service.
MITRE Category provides a standardized structure about various known attack tactics and techniques. It is regularly imported into the alarm service from an external source (https://github.com/mitre/cti/releases) . MITRE categories can be related to other MITRE categories and they can also be associated with alarms.

Data Model¶

alarms data model

Permissions¶

Managing/changing alarm information requires the ALARM-MANAGER role.

Viewing alarm information is included in the EVENT-VIEWER role.

API Usage Examples¶

Only some operations are listed here. Please consult the Swagger API documentation for the complete list of supported operations and the statuses of the endpoints (PUBLIC, INTERNAL, DEV).

Please read the Overview to learn the general concepts and common data structures used throughout the Argus API.
The Swagger API documentationis always up-to-date and lets you try out any query with your user session or an API-key.

Fetching an alarm¶

Request:

curl -X GET -H "Argus-API-Key: $API_KEY_ENV_VAR" https://api.mnemonic.no/alarms/v1/alarm/2

Response:

Show response

{
  "responseCode": 200,
  "limit": 0,
  "offset": 0,
  "count": 0,
  "metaData": {},
  "messages": [],
  "data": {
    "id": 2,
    "shortName": "bufferOverflow",
    "attackCategory": {
      "id": 5,
      "shortName": "6842e8ef-db2a-11eb-91d4-005056beea2d",
      ...,
    },
    "mappings": [],
    "comments": [
      {
         "comment": "a comment",
         "timestamp": 1650880294784,
         ...,
      }
    ],
    "references": [
      "CVE-2001-0010",
      "https://www.cvedetails.com/cve/CVE-2001-0010/?lang=en&ts=1234"
    ],
    "labels": [
      "testLabel"
    ],
    "info": "ISC BIND is the most popular implementation of the DNS protocol for Linux and Unix DNS servers. ...",
    "description": "DNS - Detected DNS packet longer than a given length that contains a TSIG resource record.",
    "internalReference": null,
    "links": [
      "http://www.cert.org/advisories/CA-2001-02.html",
      "http://xforce.iss.net/xforce/xfdb/6015"
    ],
    ...
  },
  "size": 0
}

Listing alarms¶

Request:

curl -X GET -H "Argus-API-Key: $API_KEY_ENV_VAR" https://api.mnemonic.no/alarms/v1/alarm?offset=0&limit=2

Response:

Show response

{
  "responseCode": 200,
  "limit": 2,
  "offset": 0,
  "count": 16062,
  "metaData": {},
  "messages": [],
  "data": [
    {
      "id": 3,
      "shortName": "1d0b861a-db02-11eb-91d4-005056beea2d",
      "attackCategory": {
        "id": 5,
        "shortName": "6842e8ef-db2a-11eb-91d4-005056beea2d",
        ...
      },
      ...
    },
    {
      "id": 4,
      "shortName": "1d0b9849-db02-11eb-91d4-005056beea2d",
      "attackCategory": {
        "id": 6,
        "shortName": "6842ec7a-db2a-11eb-91d4-005056beea2d",
        ...
      },
      ...
    }
  ],
  "size": 2
}

Searching for an alarm¶

Request:

curl -X POST -H "Argus-API-Key: $API_KEY_ENV_VAR" -H "Content-Type: application/json" https://api.mnemonic.no/alarms/v1/alarm/search -d '{
  "alarm": [ "1000", "1d105abb-db02-11eb-91d4-005056beea2d" ],
  "keywordFieldStrategy": [ "id", "shortName" ],
  "keywordMatchStrategy": "any"
}'

The response returns the same format as listing alarms.

Adding an alarm¶

Request:

curl -X POST -H "Argus-API-Key: $API_KEY_ENV_VAR" -H "Content-Type: application/json" https://api.mnemonic.no/alarms/v1/alarm -d '{
  "attackCategoryID": 5,
  "shortName" : "alarmShortName",
  "description" : "alarm description",
  "info" : "alarm info"
}'

The response returns the created alarm.

Updating an alarm¶

Request:

curl -X PUT -H "Argus-API-Key: $API_KEY_ENV_VAR" -H "Content-Type: application/json" https://api.mnemonic.no/alarms/v1/alarm/56960 -d '{
  "info": "updated alarm info",
  "description": "updated alarm description",
   "addLabels": [ "some label" ]
}'

The response returns the updated alarm.

Deleting an alarm¶

The response returns the deleted alarm.

curl -X DELETE -H "Argus-API-Key: $API_KEY_ENV_VAR" https://devapi.mnemonic.no/alarms/v1/alarm/56960

Mapping an alarm to signatures¶

Will create record(s) in the alarm mapping table.

Request:

curl -X POST -H "Argus-API-Key: $API_KEY_ENV_VAR" https://devapi.mnemonic.no/alarms/v1/alarm/56960/map -d '{
  "signatures": [ "signature-1", "signature-2" ]
}'

Response:

Show response

{
  "responseCode": 200,
  "limit": 0,
  "offset": 0,
  "count": 0,
  "metaData": {},
  "messages": [],
  "data": {
    "id": 56960,
    "shortName": "dc075e07-149e-4f20-bdf3-8dac343e1f2c",
    "attackCategory": {
      "id": 5,
      "shortName": "6842e8ef-db2a-11eb-91d4-005056beea2d",
      ...
    },
    "mappings": [
      {
        "attackIdentifier": "signature-1",
        "comments": [],
        "mappedTimestamp": 1655295375168,
        "firstTriggeredTimestamp": 0,
        "lastTriggeredTimestamp": 0,
        "triggerAmount": 0,
        "signature": "signature-1",
        ...
      },
      {
        "attackIdentifier": "signature-2",
        "comments": [],
        "mappedTimestamp": 1655295375168,
        "firstTriggeredTimestamp": 0,
        "lastTriggeredTimestamp": 0,
        "triggerAmount": 0,
        "signature": "signature-2",
        ...
      }
    ],
    ...
  },
  "size": 0
} 

Unmapping an alarm from signatures¶

Will set the alarm ID to null in the alarm mapping table for the matching records (by signature). It will not delete the alarm mapping records.

Request:

curl -X DELETE -H "Argus-API-Key: $API_KEY_ENV_VAR" https://api.mnemonic.no/alarms/v1/alarm/56960/unmap?signature=signature-1&signature=signature-2

Response:

Show response

{
  "responseCode": 200,
  "limit": 0,
  "offset": 0,
  "count": 0,
  "metaData": {},
  "messages": [],
  "data": {
    "id": 56960,
    "shortName": "dc075e07-149e-4f20-bdf3-8dac343e1f2c",
    "attackCategory": {
      "id": 5,
      "shortName": "6842e8ef-db2a-11eb-91d4-005056beea2d",
      ...
    },
    "mappings": []
    ...
  },
  "size": 0
} 

Deleting a signature¶

Only an unmapped signature can be deleted.

Request:

curl -X DELETE -H "Argus-API-Key: $API_KEY_ENV_VAR" https://api.mnemonic.no/alarms/v1/signature?signature=signature-1

Response:

Show response

{
  "responseCode": 200,
  "limit": 0,
  "offset": 0,
  "count": 0,
  "metaData": {},
  "messages": [],
  "data": [
    {
      "attackIdentifier": "signature-1",
      "comments": [],
      "mappedTimestamp": 0,
      "firstTriggeredTimestamp": 0,
      "lastTriggeredTimestamp": 0,
      "triggerAmount": 0,
      "signature": "signature-1",
      "flags": [
        "DELETED"
      ],
      ...
    }
  ],
  "size": 1
}