Versions Compared

Old Version 51

changes.mady.by.user Borja Moro Moreno

Saved on

compared with

New Version 52

changes.mady.by.user Borja Moro Moreno

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents
maxLevel2
typeflat

...

Check the list of available endpoints and methods to work with alert definitions using the Alerts API:

Endpoints and methods

Description

Status
colourYellow
titleGET
 /alertDefinitions see below

Get the list of all the alerts defined in a domain.

Status
colourGreen
titlePOST
 /alertDefinitions see below

Create a new alert definition.

Status
colourGreen
titlePOST
 /alertDefinitions/batch see below

Create a set of new alert definitions.

Status
colourBlue
titlePUT
/alertDefinitions see below

Update a specific alert definition.

Status
colourBlue
titlePUT
/alertDefinitions/batch see below

Update a set of alert definitions.

Status
colourBlue
titlePUT
/alertDefinitions/status see below

Update the status of several alert definitions in bulk.

Status
colourRed
titleDELETE
 /alertDefinitions see below

Delete alert definitions in bulk.

Endpoints and methods

Anchor
path1
path1
GET /alertDefinitions

Get the list of all the alerts defined in a given domain.

Rw ui expands macro
Rw expand
titleRequest

Query string parameters

Query string parameters are optionally added after the path parameters, preceded by a question mark (?) and separated by an ampersand (&)

Parameter

Type

Definition

page

number

Use these parameters to group your list of alerts by a specific number (size) and get only one of the resulting groups (page). This comes in handy if you need to get only a specific set of alerts and have a long list.

Note that the count of both the selected page and groups defined starts at 0, so for example, if you enter page=2 and size=5 and have 22 alerts in your list, the API will divide the list into groups of 5 alerts (0-4, 5-9, 10-14, 15-19, and 20-22) and will return the group of alerts 10-14.

size

number

nameFilter

string

Use this parameter to filter alerts by their names. You will only get alerts that contain the terms specified in their names. The filter is case insensitive.

idFilter

number

Indicate an alert definition ID to get only that specific alert. 

Note

How can I get the ID of an alert definition?

Alert definition IDs are not displayed in the Devo platform, so you should get them using this request to list all the alerts in the domain. IDs are included in the response.

You will also get the ID of an alert definition after creating it using POST /alertDefinitions

Example

Find below a couple of examples in cURL language.

For example, this request will return the first group of up to 2 alerts of your list of alert definitions in your domain:

Code Block
curl -H "standAloneToken:YOUR_TOKEN" -X GET "https://api-us.devo.com/alerts/v1/alertDefinitions?page=0&size=2"

And this one will filter only alerts that include the term security in their names:

Code Block
curl -H "standAloneToken:YOUR_TOKEN" -X GET "https://api-us.devo.com/alerts/v1/alertDefinitions?page=0&size=2&nameFilter=security"

Learn how to authorize your request in this article.

Rw expand
titleResponse

Code

Description

200

Successful response. Alerts' information retrieved.

Code Block
[
  {
    "id": "214554",
    "creationDate": 1678293187000,
    "name": "AWSWAFRuleDeletion",
    "message": "WAF rule or rulegroup deletion",
    "description": "WAF rule or rulegroup deletion",
    "categoryId": "2432",
    "subcategory": "lib.my.tutorials.AWS",
    "subcategoryId": "4452",
    "isActive": false,
    "isFavorite": false,
    "isAlertChain": false,
    "alertCorrelationContext": {
      "id": "67741",
      "nameId": "my.alert.tutorials.AWSWAFRuleDeletion",
      "ownerEmail": "john.smith@devo.com",
      "querySourceCode": "from cloud.aws.cloudtrail where eq(eventName,\"DeleteRule\") or eq(eventName,\"DeleteRuleGroup\") group every 1m select count() as count",
      "priority": 3,
      "correlationTrigger": {
        "kind": "each",
        "externalPeriod": null,
        "externalOffset": null,
        "internalPeriod": null,
        "internalOffset": null
      }
    },
    "actionPolicyId": []
  },
  {
    "id": "214555",
    "creationDate": 1678293190000,
    "name": "AWSRootAccessConsoleLogin",
    "message": "Root access via console",
    "description": "Root access via console",
    "categoryId": "2432",
    "subcategory": "lib.my.tutorials.threats",
    "subcategoryId": "4453",
    "isActive": false,
    "isFavorite": false,
    "isAlertChain": false,
    "alertCorrelationContext": {
      "id": "67742",
      "nameId": "my.alert.tutorials.AWSRootAccessConsoleLogin",
      "ownerEmail": "john.smith@devo.com",
      "querySourceCode": "from cloud.aws.cloudtrail where eventSource=\"signin.amazonaws.com\" where eventName=\"ConsoleLogin\" select str(jqeval(jqcompile(\".ConsoleLogin\"), responseElements)) as loginResponse select str(jqeval(jqcompile(\".MFAUsed\"), additionalEventData)) as mfaUsed group every 1m by userName,userIdentity_principalId,userIdentity_type,mfaUsed,loginResponse where userIdentity_type=\"Root\" where loginResponse=\"Success\" select count() as count",
      "priority": 2,
      "correlationTrigger": {
        "kind": "each",
        "externalPeriod": null,
        "externalOffset": null,
        "internalPeriod": null,
        "internalOffset": null
      }
    },
    "actionPolicyId": []
  }
]

400

Error in request.

401

Unauthorized request.

403

Forbidden request.

405

Method not allowed.

500

Server error and Java exception.

Anchor
path2
path2
POST /alertDefinitions

Create a new alert definition.

Rw ui expands macro
Rw expand
titleRequest

Request body

You must specify the parameters of the new alert definition in the request body:

Parameter

Type

Definition

name required

string

This should be a descriptive title for the alert and corresponds to the Alert name field in the New alert definition window of the Devo app.

message

string

A short message used to identify the alert condition. This text corresponds to the Summary field in the New alert definition window of the Devo app.

You can include the field values associated with the alert using the case-sensitive variable $columnName. Take into account that only those fields strictly related to the alert are valid and they depend on the trigger method used. See each Alert trigger method to know the accepted fields.

description

string

The full description of the alert condition, which corresponds to the Description field in the New alert definition window of the Devo app. 

You can include in the alert description the field values associated with the alert using the case-sensitive variable $columnName. Take into account that only those fields strictly related to the alert are valid and they depend on the trigger method used. See each Alert trigger method to know the accepted fields.

subcategory required

string

This value corresponds to the Subcategory field in the New alert definition window of the Devo app. 

Alerts created by Devo users are always created under the My Alerts category. The value entered here is the subcategory you will use to group this alert.

isActive

boolean

Set this parameter to true if you want to activate the alert after creation. Set it to false if you want the new alert to be disabled.

The default value is true.

alertCorrelationContext required

object

This JSON object includes the following parameters:

  • withSelectAll - (boolean) Set this parameter to false if you want to show only specific columns of the alert source query. The default value is true, which means that all the columns will be shown if you don’t include this parameter or you set it to true.

  • querySourceCode required  - (string) Specify the LINQ query whose events will launch the type of alert defined.

  • priority required - (integer) Enter the priority level of the alert defined. Values 1 to 10 are allowed, corresponding to the default values in the application:

    • Very low - 0, 1

    • Low - 2, 3

    • Normal - 4, 5

    • High - 6, 7

    • Very high - 8, 9, 10

Note

When creating alerts in Devo, the priority levels and their equivalent numerical values are detailed here.

  • correlationTrigger required - (object) This JSON contains the type of alert you want to define and the specific parameters of that type. Use the parameter kind to enter the type of alert you want to define. Types correspond to the ones available in the Devo application, and are the following:

    • each

    • several

    • low

    • inactivity

    • rolling

    • deviation

    • gradient

Check the table below for the parameters you can include for each alert type.

  • timezone - (string) This field indicates a timezone to adapt the query used to monitor alert conditions. Default value is GMT

  • locale - (string) Choose your required locale. Required format is language code and region code separated by an underscore, following this: ([a-z]){2}_([A-Z]){2} Default value is en_US

Depending on the type of alert specified, you are allowed to include different parameters:

Alert type

Parameters

Description

each

Note

The parameters for the each type alerts are mandatory if the specified query includes subqueries.

However, not every query containing a subquery is allowed. Learn more about this in the section below.

Note

Note that if you use this method and include a subquery, the minimum grouping time is 1 minute, and the maximum is 100 days.

Note

When the External offset parameter is less than 1 day, the ratio between internal period/external offset must not exceed 120. A ratio above 120 will prevent the alert from being created and will return an error.

  • Valid ratio → external offset 1m, internal period 2h(=120m) → 120/1 → 120

  • Valid ratio → external offset 2h, internal period 5d(=120h) → 120/2 → 60

  • Invalid ratio → external offset 1m, internal period 3h(=180m) → 180/1 → 180

externalOffset

It is used to move the main query time range backward in time. It must be expressed in milliseconds.

For example: if the main query time range is [now()-1h, now()] with an externalOffset of 2 days, the time range would be [now() -1h -2d, now() - 2d]

The maximum time range allowed is 8640000000 milliseconds (up to 100 days).

internalPeriod

It is used to set the subquery time range. It must be expressed in milliseconds.

For example: for an internalPeriod of 10 days, the subquery time range would be [now() - 10d, now()]

The minimum allowed temporal 60000, and the maximum is 8640000000 (from 1 min to 100 days).

internalOffset

It is used to move the subquery time range backward in time. It must be expressed in milliseconds.

For example: if the subquery time range is [now()-10d, now()] with an internalOffset of 2 days, the time range would be [now() -12d, now() - 2d]

The maximum time range allowed is 8640000000 milliseconds (up to 100 days).

several

period

Specify how frequently you want Determines the duration of the intervals used by the system to check for events matching the conditions of your query.

It must be indicated in milliseconds. The minimal value is 1 second and the maximum value is 100 days.

threshold

Specifies how many events you want to use as a limit to trigger the alert.

It must be a positive integer number.

keys

You must specify one or more fields to keep track of their unique values and check against the designated threshold to trigger the alert. You can choose from any column in the table, except the eventdate.

low

period

Specify how frequently you want Determines the duration of the intervals used by the system to check for events matching the conditions of your query..

It must be indicated in milliseconds. The minimal value is 1 second and the maximum value is 100 days.

threshold

Specifies how many events you want to use as a limit to trigger the alert.

It must be a non-negative integer number.positive integer number.

inactivity

period

Specifies the duration used by the system to determine the occurrence of inactivity.

It must be indicated in milliseconds. The minimal value is 5 minutes and the maximum value is 30 days.

keys

You must specify one or more fields to keep track of their unique values, which will be checked against the full series of values in the previous period to trigger the alert. You can choose from any column in the table, except the eventdate.

rolling

Note

When the period parameter is less than 1 day, the ratio between backPeriod/period must not exceed 120. A ratio above 120 will prevent the alert from being created and will return an error.

  • Valid ratio → period 1m, backPeriod 2h(=120m) → 120/1 → 120

  • Valid ratio → period 2h, backPeriod 5d(=120h) → 120/2 → 60

  • Invalid ratio → period 1m, backPeriod 3h(=180m) → 180/1 → 180

period

Specifies how frequently you want the system to check for events matching the conditions of your query.

It must be indicated in milliseconds. The minimal value is 60 seconds and the maximum value is 100 days.

backPeriod

Specifies how far in the past the search extends.

deviation

threshold

Specifies the proportions of the deviation from the median, in other words, the upper and lower bound that must be exceeded for an alert to be triggered. 

It must be a non-negative integer number.

absolute

Set this value to true if you want to use absolute values to calculate the deviation from the median, or false if you want to use a percentage.

Using an absolute value means that the threshold specified will be considered as the number above and below which the alert will be triggered. On the other hand, using a percentage means that the threshold specified will be considered as the percentage of the median value above and below which an alert will be triggered.

aggregationColumn

Specify an aggregation column whose values will be set against the designated threshold to trigger the alert. You can choose from any of the aggregation columns added to the query but you cannot add more than one.

gradient

threshold

Specifies the proportions of the deviation from the previous value, in other words, the upper and lower bound that must be exceeded for an alert to be triggered. 

It must be a non-negative integer number.

absolute

Set this value to true if you want to use absolute values to calculate the deviation from the median, or false if you want to use a percentage.

Using an absolute value means that the threshold specified will be considered as the number above and below which the alert will be triggered. On the other hand, using a percentage means that the threshold specified will be considered as the percentage of the median value above and below which an alert will be triggered.

aggregationColumn

Specify an aggregation column whose values will be set against the designated threshold to trigger the alert. You can choose from any of the aggregation columns added to the query but you cannot add more than one.

Learn more about each type of alert, their parameters, and how to set them in Alert trigger methods.

Defining alerts with queries that include subqueries

As specified in the required parameters for the each-type alert above, users can generate alerts based on queries that contain subqueries by adding some required extra parameters. However, not every query is allowed.

Take the following into account when defining your source query:

  • Queries must not include nested subqueries.

  • Queries must not include a fixed time range in the subquery.

  • Queries must not include a temporal grouping in the subquery.

  • my.lookuplist tables cannot be used in subqueries. Learn more about lookups in Data enrichment.

See the following table to check examples of valid and not allowed query formats:

Query

Allowed?

Code Block
from T1

This query does not include any subquery, so it is not allowed.

Code Block
from T1  
  where x in (      
    from T2          
      where y in (              
        from T3          
      )  
  )

This query includes nested subqueries, so it is not allowed.

Code Block
from T1  
  where x in (      
    from T2      
    where 100 <= eventdate < 200  
  )

This query includes a fixed time range in its subquery, so it is not allowed.

Code Block
from T1  
  where x in (      
    from T2      
    group every 10m  
  )

This query includes a temporal grouping in its subquery, so it is not allowed.

Code Block
from T1    
  where x in (        
    from T2    
  )

This query has neither a group nor a time range in its subquery, so it is allowed.

Code Block
from T1    
  group by x every 10m    
  where x in (        
    from T2    
  )

This query has a temporal grouping, but it is not included in the subquery. Therefore, it is allowed.

Examples

Find below some examples of the request body for each type of alert in cURL language, including their specific parameters.

Learn how to authorize your request in this article.

Each alert example

Code Block
curl --location -g 'https://api-us.devo.com/alerts/v1/alertDefinitions' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
    "name": "myAlertEach",
    "message": "Alert definition message created with alerting API",
    "description": "Alert definition description created with alerting API",
    "subcategory": "alert",
    "alertCorrelationContext": {
        "querySourceCode": "from siem.logtrust.web.activity where url = \"https://us.devo.com/alerts/view.json\"",
        "priority": 5,
        "correlationTrigger": {
            "kind": "each"
        }
    }
}'

Each alert example with subquery

Code Block
curl --location -g 'https://api-us.devo.com/alerts/v1/alertDefinitions' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
    "name": "Alert definition with subquery",
    "message": "Alert definition with subquery",
    "description": "Alert definition with subquery",
    "subcategory": "Subcategory/Each",
    "alertCorrelationContext": {
        "querySourceCode": "from siem.logtrust.web.activity where eq(url, \"https://us.devo.com/home\"), eq(type, \"request\") where username in (from siem.logtrust.web.activity where eq(url, \"https://us.devo.com/m2search\"), eq(type, \"request\") select username) select username, userid, sessionid, locale, userAgent",
    eq(type, \"request\") select username) select username, userid, sessionid, locale, userAgent",
        "priority": 1,
        "correlationTrigger": {
            "kind": "each",
            "externalOffset": 0,
            "internalPeriod": 60000,
            "internalOffset": 1000
        }
    }
}'

Several alert example

Code Block
curl --location -g 'https://api-us.devo.com/alerts/v1/alertDefinitions' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
    "name": "myAlertSeveral",
    "message": "Alert definition created with alerting API / Several",
    "description": "Alert definition long description / Several",
    "subcategory": "Subcategory/Several",
    "priorityalertCorrelationContext": 1,{
        "correlationTriggerquerySourceCode": {"from siem.logtrust.web.activity",
        "priority": 3,
        "kindcorrelationTrigger": "each",{
            "externalOffsetkind": 0"several",
            "internalPeriodperiod": 60000300000,
            "internalOffsetthreshold": 100010000
        }
    }
}'

Several Low alert example

Code Block
curl --location -g 'https://api-us.devo.com/alerts/v1/alertDefinitions' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
    "name": "myAlertSeveralmyAlertLow",
    "message": "Alert definition created with alerting API / SeveralLow",
    "description": "Alert definition long description / SeveralLow",
    "subcategory": "Subcategory/SeveralLow",
    "alertCorrelationContext": {
        "querySourceCode": "from siem.logtrust.web.activity",
        "priority": 3,
        "correlationTrigger": {
            "kind": "severallow",
            "period": 300000,
            "threshold": 100001
        }
    }
}'

Low Inactivity alert example

Code Block
curl --location -g 'https://api-us.devo.com/alerts/v1/alertDefinitions' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
    "name": "myAlertLowAlert definition / Inactivity",
    "message": "Alert definition created with alerting API / LowInactivity",
    "description": "Alert definition long description / LowInactivity",
    "subcategory": "Subcategory/LowInactivity",
    "alertCorrelationContext": {
        "querySourceCode": "from siem.logtrust.web.activity",
        "priority": 35,
        "correlationTrigger": {
            "kind": "lowinactivity",
            "period": 3000001800000,
            "thresholdkeys": 1["username"]
        }
    }
}'

Rolling alert example

Code Block
curl --location -g 'https://api-us.devo.com/alerts/v1/alertDefinitions' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
    "name": "Alert definition / Rolling",
    "message": "Alert definition created with alerting API / Rolling",
    "description": "Alert definition long description / Rolling",
    "subcategory": "Subcategory/Rolling",
    "alertCorrelationContext": {
        "querySourceCode": "from siem.logtrust.web.activity group every -",
        "priority": 4,
        "correlationTrigger": {
            "kind": "rolling",
            "period": 300000,
            "backPeriod": 3600000
        }
    }
}'

Deviation alert example

Code Block
curl --location -g 'https://api-us.devo.com/alerts/v1/alertDefinitions' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
    "name": "Alert definition / Deviation",
    "message": "Alert definition created with alerting API / Deviation",
    "description": "Alert definition long description / Deviation",
    "subcategory": "Subcategory/Deviation",
    "alertCorrelationContext": {
        "querySourceCode": "from siem.logtrust.web.activity group every 5m by domain select count() as count",
        "priority": 5,
        "correlationTrigger": {
            "kind": "deviation",
            "threshold": 40,
            "absolute": true,
            "aggregationColumn": [ "count" ]
        }
    }
}'

Gradient alert example

Code Block
curl --location -g 'https://api-us.devo.com/alerts/v1/alertDefinitions' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
    "name": "Alert definition / Gradient",
    "message": "Alert definition created with alerting API / Gradient",
    "description": "Alert definition long description / Gradient",
    "subcategory": "Subcategory/Gradient",
    "alertCorrelationContext": {
        "querySourceCode": "from siem.logtrust.web.activity group every 5m by domain select count() as count",
        "priority": 1,
        "correlationTrigger": {
            "kind": "gradient",
            "threshold": 40,
            "absolute": false,
            "aggregationColumn": [ "count" ]
        }
    }
}'
Rw expand
titleResponse

Code

Description

200

Successful response. Alert created.

Code Block
{
    "id": "70736",
    "creationDate": 1604567644173,
    "name": "Alert_API_each",
    "message": "$eventdate $username - $count - API",
    "description": "Alert created by API",
    "categoryId": "7",
    "subcategory": "lib.my.testfake.AlertAPI_v660",
    "subcategoryId": "133",
    "isActive": true,
    "isFavorite": false,
    "isAlertChain": false,
    "alertCorrelationContext": {
        "id": "622",
        "nameId": "my.alert.testfake.Alert_API_each_Staging_1604567643224",
        "ownerEmail": "john@xx.com",
        "querySourceCode": "from siem.logtrust.web.activity group every 1m by username, url every 1m select count() as count",
        "priority": 5,
        "correlationTrigger": {
            "kind": "each"
        }
    },
    "actionPolicyId": []
}

400

Error in request.

401

Unauthorized request.

403

Forbidden request.

405

Method not allowed.

500

Server error and Java exception.

Anchor
path23
path23
POST /alertDefinitions/batch

Create a set of new alert definitions.

Rw ui expands macro
Rw expand
titleRequest

Request body

You must specify the parameters of the alerts to be created in the request body.

Check the parameters defined in POST /alertDefinitions to learn how to define your set of alert definitions. Add all the alerts you want to define in an array as in the example below.

Example

Find below a example in cURL language. This is a body example where we are defining 2 different alert definitions:

Code Block
curl --location --request POST 'https://api-us.devo.com/alerts/v1/alertDefinitions/batch' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '[
    {
        "name": "myAlertEach2",
        "message": "Alert definition created with alerting API / Gradient",
        "description": "Alert definition long description / Gradient",
        "subcategory": "alert",
        "alertCorrelationContext": {
            "querySourceCode": "from siem.logtrust.web.activity",
            "priority": 1,
            "correlationTrigger": {
               "kind": "each"
            }
        }
    },
    {
        "name": "myAlertEach3",
        "message": "Alert definition created with alerting API / Gradient",
        "description": "Alert definition long description / Gradient",
        "subcategory": "alert",
        "alertCorrelationContext": {
            "querySourceCode": "from siem.logtrust.web.activity",
            "priority": 1,
            "correlationTrigger": {
               "kind": "each"
            }
        }
    }
]'

Learn how to authorize your request in this article.

Rw expand
titleResponse

Code

Description

200

Successful response. Set of alert definitions created.

Code Block
[
  {
    "context": {
      "headers": {},
      "configuration": null,
      "entity": {
        "id": "226687",
        "creationDate": 1685441802355,
        "name": "myAlertEach2",
        "message": "Alert definition created with alerting API / Gradient",
        "description": "Alert definition long description / Gradient",
        "categoryId": "2432",
        "subcategory": "lib.my.tutorials.alert",
        "subcategoryId": "4521",
        "isActive": true,
        "isFavorite": false,
        "isAlertChain": false,
        "alertCorrelationContext": {
          "id": "78228",
          "nameId": "my.alert.tutorials.myAlertEach2",
          "ownerEmail": "user@devo.com",
          "querySourceCode": "from siem.logtrust.web.activity",
          "priority": 1,
          "correlationTrigger": {
            "kind": "each",
            "externalPeriod": null,
            "externalOffset": null,
            "internalPeriod": null,
            "internalOffset": null
          }
        },
        "actionPolicyId": []
      },
      "entityType": "com.devo.config.api.model.AlertDefinition",
      "entityAnnotations": [],
      "entityStream": {
        "committed": false,
        "closed": false
      },
      "lengthLong": -1,
      "mediaType": null,
      "responseCookies": {},
      "committed": false,
      "requestCookies": {},
      "stringHeaders": {},
      "allowedMethods": [],
      "entityTag": null,
      "acceptableMediaTypes": [
        {
          "type": "*",
          "subtype": "*",
          "parameters": {},
          "quality": 1000,
          "wildcardType": true,
          "wildcardSubtype": true
        }
      ],
      "acceptableLanguages": [
        "*"
      ],
      "entityClass": "com.devo.config.api.model.AlertDefinition",
      "links": [],
      "date": null,
      "lastModified": null,
      "length": -1,
      "location": null,
      "language": null
    },
    "status": 200,
    "entity": {
      "id": "226687",
      "creationDate": 1685441802355,
      "name": "myAlertEach2",
      "message": "Alert definition created with alerting API / Gradient",
      "description": "Alert definition long description / Gradient",
      "categoryId": "2432",
      "subcategory": "lib.my.tutorials.alert",
      "subcategoryId": "4521",
      "isActive": true,
      "isFavorite": false,
      "isAlertChain": false,
      "alertCorrelationContext": {
        "id": "78228",
        "nameId": "my.alert.tutorials.myAlertEach2",
        "ownerEmail": "user@devo.com",
        "querySourceCode": "from siem.logtrust.web.activity",
        "priority": 1,
        "correlationTrigger": {
          "kind": "each",
          "externalPeriod": null,
          "externalOffset": null,
          "internalPeriod": null,
          "internalOffset": null
        }
      },
      "actionPolicyId": []
    },
    "cookies": {},
    "statusInfo": "OK",
    "metadata": {},
    "mediaType": null,
    "stringHeaders": {},
    "allowedMethods": [],
    "entityTag": null,
    "links": [],
    "date": null,
    "lastModified": null,
    "length": -1,
    "location": null,
    "language": null,
    "headers": {}
  },
  {
    "context": {
      "headers": {},
      "configuration": null,
      "entity": {
        "id": "226688",
        "creationDate": 1685441806527,
        "name": "myAlertEach3",
        "message": "Alert definition created with alerting API / Gradient",
        "description": "Alert definition long description / Gradient",
        "categoryId": "2432",
        "subcategory": "lib.my.tutorials.alert",
        "subcategoryId": "4521",
        "isActive": true,
        "isFavorite": false,
        "isAlertChain": false,
        "alertCorrelationContext": {
          "id": "78229",
          "nameId": "my.alert.tutorials.myAlertEach3",
          "ownerEmail": "user@devo.com",
          "querySourceCode": "from siem.logtrust.web.activity",
          "priority": 1,
          "correlationTrigger": {
            "kind": "each",
            "externalPeriod": null,
            "externalOffset": null,
            "internalPeriod": null,
            "internalOffset": null
          }
        },
        "actionPolicyId": []
      },
      "entityType": "com.devo.config.api.model.AlertDefinition",
      "entityAnnotations": [],
      "entityStream": {
        "committed": false,
        "closed": false
      },
      "lengthLong": -1,
      "mediaType": null,
      "responseCookies": {},
      "committed": false,
      "requestCookies": {},
      "stringHeaders": {},
      "allowedMethods": [],
      "entityTag": null,
      "acceptableMediaTypes": [
        {
          "type": "*",
          "subtype": "*",
          "parameters": {},
          "quality": 1000,
          "wildcardType": true,
          "wildcardSubtype": true
        }
      ],
      "acceptableLanguages": [
        "*"
      ],
      "entityClass": "com.devo.config.api.model.AlertDefinition",
      "links": [],
      "date": null,
      "lastModified": null,
      "length": -1,
      "location": null,
      "language": null
    },
    "status": 200,
    "entity": {
      "id": "226688",
      "creationDate": 1685441806527,
      "name": "myAlertEach3",
      "message": "Alert definition created with alerting API / Gradient",
      "description": "Alert definition long description / Gradient",
      "categoryId": "2432",
      "subcategory": "lib.my.tutorials.alert",
      "subcategoryId": "4521",
      "isActive": true,
      "isFavorite": false,
      "isAlertChain": false,
      "alertCorrelationContext": {
        "id": "78229",
        "nameId": "my.alert.tutorials.myAlertEach3",
        "ownerEmail": "user@devo.com",
        "querySourceCode": "from siem.logtrust.web.activity",
        "priority": 1,
        "correlationTrigger": {
          "kind": "each",
          "externalPeriod": null,
          "externalOffset": null,
          "internalPeriod": null,
          "internalOffset": null
        }
      },
      "actionPolicyId": []
    },
    "cookies": {},
    "statusInfo": "OK",
    "metadata": {},
    "mediaType": null,
    "stringHeaders": {},
    "allowedMethods": [],
    "entityTag": null,
    "links": [],
    "date": null,
    "lastModified": null,
    "length": -1,
    "location": null,
    "language": null,
    "headers": {}
  }
]

400

Error in request.

401

Unauthorized request.

403

Forbidden request.

405

Method not allowed.

500

Server error and Java exception.

Anchor
path3
path3
PUT /alertDefinitions

Update a specific alert definition in your domain.

Rw ui expands macro
Rw expand
titleRequest

Request body

You must specify the parameters to be updated in the request body.

Parameter

Type

Definition

id required

string

Specify the ID of the alert definition that you want to update.

Note

How can I get the ID of an alert definition?

Alert definition IDs are not displayed in the Devo platform, so you should get them using GET /alertDefinitions to list all the alerts in the domain. IDs are included in the response.

You will also get the ID of an alert definition after creating it using POST /alertDefinitions

name required

string

Descriptive title for the alert and corresponds to the Alert name field in the New alert definition window of the Devo app.

Note

Non-editable parameter

Note that the name parameter cannot be edited when you update an alert definition. However, you must include it and indicate its original value.

message

string

A short message used to identify the alert condition. This text corresponds to the Summary field in the New alert definition window of the Devo app.

You can include the field values associated with the alert using the case-sensitive variable $columnName. Take into account that only those fields strictly related to the alert are valid and they depend on the trigger method used. See each Alert trigger methods to know the accepted fields.

description

string

The full description of the alert condition, which corresponds to the Description field in the New alert definition window of the Devo app. 

You can include in the alert description the field values associated with the alert using the case-sensitive variable $columnName. Take into account that only those fields strictly related to the alert are valid and they depend on the trigger method used. See each Alert trigger methods to know the accepted fields.

subcategory required

string

This value corresponds to the Subcategory field in the New alert definition window of the Devo app. 

Alerts created by Devo users are always created under the My Alerts category.

Note

Non-editable parameter

Note that the subcategory parameter cannot be edited when you update an alert definition. However, you must include it and indicate its original value.

isActive

boolean

Set this parameter to true if you want to activate the alert after creation. Set it to false if you want the new alert to be disabled.

The default value is true.

alertCorrelationContext

object

This JSON object includes the following parameters:

  • withSelectAll - (boolean) Set this parameter to false if you want to show only specific columns of the alert source query. The default value is true, which means that all the columns will be shown if you don't include this parameter or you set it to true.

  • querySourceCode - (string) Specify the LINQ query whose events will launch the type of alert defined.

  • priority- (integer) Enter the priority level of the alert defined. Values 1 to 10 are allowed, corresponding to the default values in the application:

    • Very low - 0, 1

    • Low - 2, 3

    • Normal - 4, 5

    • High - 6, 7

    • Very high - 8, 9, 10

Note

When creating alerts in Devo, the priority levels and their equivalent numerical values are detailed here.

  • correlationTrigger- (object) This JSON contains the type of alert you want to define and the specific parameters of that type. Use the parameter kind to enter the type of alert you want to define. Types correspond to the ones available in the Devo application, and are the following:

    • each

    • several

    • low

    • rolling

    • deviation

    • gradient

Check the table below for the parameters you can include for each alert type.

  • timezone - (string) This field indicates a timezone to adapt the query used to monitor alert conditions. Default value is GMT

  • locale - (string) Choose your required locale. Required format is language code and region code separated by an underscore, following this: ([a-z]){2}_([A-Z]){2} Default value is en_US

Example

Find below a couple of examples in cURL language.

This is a body example where we are modifying the message and description of an alert previously created:

Code Block
curl --location --request PUT 'https://api-us.devo.com/alerts/v1/alertDefinitions' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
    "id": "70736",
    "name": "Alert_API_each",
    "message": "New message",
    "description": "New description",
    "subcategory": "alert",
    "alertCorrelationContext": {
        "querySourceCode": "from siem.logtrust.web.activity where url = \"https://us.devo.com/alerts/view.json\"",
        "priority": 5,
        "correlationTrigger": {
            "kind": "each"
        }
    }
}'

And in this case, we are updating the same alert and transforming it into a Several type alert:

Code Block
curl --location --request PUT 'https://api-us.devo.com/alerts/v1/alertDefinitions' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
    "id": "70736"
    "name": "Alert_API_each",
    "message": "New message",
    "description": "New description",
    "subcategory": "alert",
    "alertCorrelationContext": {
        "querySourceCode": "from siem.logtrust.web.activity where username = "user@devo.com"",
        "priority": 3,
        "correlationTrigger": {
            "kind": "several",
            "period": 300000,
            "threshold": 10000
        }
    }
}'

Learn how to authorize your request in this article.

Rw expand
titleResponse

Code

Description

200

Successful response. Alert updated.

Code Block
{
    "id": "70736",
    "creationDate": 1604567644173,
    "name": "Alert_API_each",
    "message": "New message",
    "description": "New description",
    "categoryId": "7",
    "subcategory": "lib.my.testfake.AlertAPI_v660",
    "subcategoryId": "133",
    "isActive": true,
    "isFavorite": false,
    "isAlertChain": false,
    "alertCorrelationContext": {
        "id": "622",
        "nameId": "my.alert.testfake.Alert_API_each_Staging_1604567643224",
        "ownerEmail": "john@xx.com",
        "querySourceCode": "from siem.logtrust.web.activity group every 1m by username, url every 1m select count() as count",
        "priority": 5,
        "correlationTrigger": {
            "kind": "each"
        }
    },
    "actionPolicyId": []
}

400

Error in request.

401

Unauthorized request.

403

Forbidden request.

405

Method not allowed.

500

Server error and Java exception.

Anchor
path35
path35
PUT /alertDefinitions/batch

Update a set of alert definitions in your domain.

Rw ui expands macro
Rw expand
titleRequest

Request body

You must specify the parameters to be updated in the request body.

Check the parameters defined in PUT /alertDefinitions to learn how to update your set of alert definitions. Add all the alerts you want to update in an array as in the example below.

Example

Find below a example in cURL language. This is a body example where we are updating 2 different alert definitions:

Code Block
curl --location --request PUT 'https://api-us.devo.com/alerts/v1/alertDefinitions/batch' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '[
    {
        "id": "123456"
        "name": "myAlertEach2",
        "message": "Alert definition created with alerting API / Gradient",
        "description": "Alert definition long description / Gradient",
        "subcategory": "alert",
        "alertCorrelationContext": {
            "querySourceCode": "from siem.logtrust.web.activity",
            "priority": 1,
            "correlationTrigger": {
               "kind": "each"
            }
        }
    },
    {
        "id": "567890"
        "name": "myAlertEach3",
        "message": "Alert definition created with alerting API / Gradient",
        "description": "Alert definition long description / Gradient",
        "subcategory": "alert",
        "alertCorrelationContext": {
            "querySourceCode": "from siem.logtrust.web.activity",
            "priority": 1,
            "correlationTrigger": {
               "kind": "each"
            }
        }
    }
]'

Learn how to authorize your request in this article.

Rw expand
titleResponse

Code

Description

200

Successful response. Set of alert definitions updated.

Code Block
[
  {
    "context": {
      "headers": {},
      "configuration": null,
      "entity": {
        "id": "123456",
        "creationDate": 1678293190000,
        "name": "myAlertEach2",
        "message": "Alert definition created with alerting API / Gradient",
        "description": "Alert definition long description / Gradient",
        "categoryId": "2432",
        "subcategory": "lib.my.tutorials.threats",
        "subcategoryId": "4453",
        "isActive": false,
        "isFavorite": false,
        "isAlertChain": false,
        "alertCorrelationContext": {
          "id": "67742",
          "nameId": "my.alert.tutorials.AWSRootAccessConsoleLogin",
          "ownerEmail": "user@devo.com",
          "querySourceCode": "from siem.logtrust.web.activity",
          "priority": 1,
          "correlationTrigger": {
            "kind": "each",
            "externalPeriod": null,
            "externalOffset": null,
            "internalPeriod": null,
            "internalOffset": null
          }
        },
        "actionPolicyId": []
      },
      "entityType": "com.devo.config.api.model.AlertDefinition",
      "entityAnnotations": [],
      "entityStream": {
        "committed": false,
        "closed": false
      },
      "lengthLong": -1,
      "mediaType": null,
      "responseCookies": {},
      "committed": false,
      "requestCookies": {},
      "acceptableMediaTypes": [
        {
          "type": "*",
          "subtype": "*",
          "parameters": {},
          "quality": 1000,
          "wildcardType": true,
          "wildcardSubtype": true
        }
      ],
      "allowedMethods": [],
      "entityTag": null,
      "acceptableLanguages": [
        "*"
      ],
      "entityClass": "com.devo.config.api.model.AlertDefinition",
      "stringHeaders": {},
      "links": [],
      "date": null,
      "lastModified": null,
      "length": -1,
      "location": null,
      "language": null
    },
    "status": 200,
    "cookies": {},
    "allowedMethods": [],
    "entityTag": null,
    "statusInfo": "OK",
    "stringHeaders": {},
    "mediaType": null,
    "metadata": {},
    "links": [],
    "date": null,
    "lastModified": null,
    "entity": {
      "id": "123456",
      "creationDate": 1678293190000,
      "name": "myAlertEach2",
      "message": "Alert definition created with alerting API / Gradient",
      "description": "Alert definition long description / Gradient",
      "categoryId": "2432",
      "subcategory": "lib.my.tutorials.threats",
      "subcategoryId": "4453",
      "isActive": false,
      "isFavorite": false,
      "isAlertChain": false,
      "alertCorrelationContext": {
        "id": "67742",
        "nameId": "my.alert.tutorials.AWSRootAccessConsoleLogin",
        "ownerEmail": "user@devo.com",
        "querySourceCode": "from siem.logtrust.web.activity",
        "priority": 1,
        "correlationTrigger": {
          "kind": "each",
          "externalPeriod": null,
          "externalOffset": null,
          "internalPeriod": null,
          "internalOffset": null
        }
      },
      "actionPolicyId": []
    },
    "length": -1,
    "location": null,
    "language": null,
    "headers": {}
  },
  {
    "context": {
      "headers": {},
      "configuration": null,
      "entity": {
        "id": "567890",
        "creationDate": 1678293187000,
        "name": "myAlertEach3",
        "message": "Alert definition created with alerting API / Gradient",
        "description": "Alert definition long description / Gradient",
        "categoryId": "2432",
        "subcategory": "lib.my.tutorials.AWS",
        "subcategoryId": "4452",
        "isActive": false,
        "isFavorite": false,
        "isAlertChain": false,
        "alertCorrelationContext": {
          "id": "567890",
          "nameId": "my.alert.tutorials.AWSWAFRuleDeletion",
          "ownerEmail": "user@devo.com",
          "querySourceCode": "from siem.logtrust.web.activity",
          "priority": 1,
          "correlationTrigger": {
            "kind": "each",
            "externalPeriod": null,
            "externalOffset": null,
            "internalPeriod": null,
            "internalOffset": null
          }
        },
        "actionPolicyId": []
      },
      "entityType": "com.devo.config.api.model.AlertDefinition",
      "entityAnnotations": [],
      "entityStream": {
        "committed": false,
        "closed": false
      },
      "lengthLong": -1,
      "mediaType": null,
      "responseCookies": {},
      "committed": false,
      "requestCookies": {},
      "acceptableMediaTypes": [
        {
          "type": "*",
          "subtype": "*",
          "parameters": {},
          "quality": 1000,
          "wildcardType": true,
          "wildcardSubtype": true
        }
      ],
      "allowedMethods": [],
      "entityTag": null,
      "acceptableLanguages": [
        "*"
      ],
      "entityClass": "com.devo.config.api.model.AlertDefinition",
      "stringHeaders": {},
      "links": [],
      "date": null,
      "lastModified": null,
      "length": -1,
      "location": null,
      "language": null
    },
    "status": 200,
    "cookies": {},
    "allowedMethods": [],
    "entityTag": null,
    "statusInfo": "OK",
    "stringHeaders": {},
    "mediaType": null,
    "metadata": {},
    "links": [],
    "date": null,
    "lastModified": null,
    "entity": {
      "id": "567890",
      "creationDate": 1678293187000,
      "name": "myAlertEach3",
      "message": "Alert definition created with alerting API / Gradient",
      "description": "Alert definition long description / Gradient",
      "categoryId": "2432",
      "subcategory": "lib.my.tutorials.AWS",
      "subcategoryId": "4452",
      "isActive": false,
      "isFavorite": false,
      "isAlertChain": false,
      "alertCorrelationContext": {
        "id": "67741",
        "nameId": "my.alert.tutorials.AWSWAFRuleDeletion",
        "ownerEmail": "user@devo.com",
        "querySourceCode": "from siem.logtrust.web.activity",
        "priority": 1,
        "correlationTrigger": {
          "kind": "each",
          "externalPeriod": null,
          "externalOffset": null,
          "internalPeriod": null,
          "internalOffset": null
        }
      },
      "actionPolicyId": []
    },
    "length": -1,
    "location": null,
    "language": null,
    "headers": {}
  }
]

400

Error in request.

401

Unauthorized request.

403

Forbidden request.

405

Method not allowed.

500

Server error and Java exception.

Anchor
path4
path4
PUT /alertDefinitions/status

Use this operation to enable or deactivate several alerts at the same time.

Rw ui expands macro
Rw expand
titleRequest

Query string parameters

Query string parameters are optionally added after the path parameters, preceded by a question mark (?) and separated by an ampersand (&)

Parameter

Type

Definition

alertIds required

string

Specify the ID of the alert definition(s) that you want to update. Add as many alerIds parameters as required:

alertIds=205870&alertIds=215374

enable required

boolean

Set this parameter to true if you want to enable the alerts or false if you need to deactivate them.

Example

Find below a request example in cURL language. This request will enable the alerts with IDs 123456 and 678900 in the domain that corresponds to the given token. Learn how to authorize your request in this article.

Code Block
curl -H "standAloneToken:YOUR_TOKEN" -X PUT "https://api-us.devo.com/alerts/v1/alertDefinitions/status?alertIds=123456&alertIds=678900&enable=true"
Rw expand
titleResponse

Code

Description

200

Successful response. Alert statuses updated.

Code Block
{"updated":{"123456":true,"678900":true}}

400

Error in request.

401

Unauthorized request.

403

Forbidden request.

405

Method not allowed.

500

Server error and Java exception.

Anchor
path5
path5
DELETE /alertDefinitions

Delete alert definitions in bulk.

Rw ui expands macro
Rw expand
titleRequest

Query string parameters

Query string parameters are optionally added after the path parameters, preceded by a question mark (?) and separated by an ampersand (&)

Parameter

Type

Definition

alertIds required

string

Specify the ID of the alert definition(s) that you want to delete. Add as many alerIds parameters as required following this format:

alertIds=205870&alertIds=215374

Note

How can I get the ID of an alert definition?

Alert definition IDs are not displayed in the Devo platform, so you should get them using GET /alertDefinitions to list all the alerts in the domain. IDs are included in the response.

You will also get the ID of an alert definition after creating it using POST /alertDefinitions

Example

Find below a request example in cURL language. This request will delete the alerts with IDs 123456 and 678900 in the domain that corresponds to the given token. Learn how to authorize your request in this article.

Code Block
curl -H "standAloneToken:YOUR_TOKEN" -X DELETE "https://api-us.devo.com/alerts/v1/alertDefinitions?alertIds=215870&alertIds=215873"
Rw expand
titleResponse

Code

Description

200

Successful response. Alert(s) deleted.

400

Error in request.

401

Unauthorized request.

403

Forbidden request.

405

Method not allowed.

500

Server error and Java exception.

...