Searching alerts

GET /api/v1/alerts

Access: administrator, analyst, and operator.

Query parameters

Name

Data type

Mandatory

Description

Value example

page

number

No

Page number. Starts with 1. The page size is 250 entries. If the parameter is not specified, the default value is 1.

1

id

string

No

Alert ID. If the parameter is specified several times, then a list is generated and the logical OR operator is applied.

00000000-0000-0000-0000-000000000000

TenantID

string

No

Alert tenant ID. If the parameter is specified several times, then a list is generated and the logical OR operator is applied. If the user does not have the required role in the specified tenant, then this tenant is ignored.

00000000-0000-0000-0000-000000000000

name

string

No

Alert name. Case-insensitive regular expression (PCRE).

alert
^My alert$

timestampField

string

No

The name of the alert field that is used to perform sorting (DESC) and search by period (from – to). lastSeen by default.

lastSeen, firstSeen

from

string

No

Lower bound of the period in RFC3339 format. <timestampField> >= <from>

2021-09-06T00:00:00Z (UTC)

2021-09-06T00:00:00.000Z (UTC, including milliseconds)

2021-09-06T00:00:00Z+00:00 (MSK)

to

string

No

Upper bound of the period in RFC3339 format. <timestampField> <= <to>

2021-09-06T00:00:00Z (UTC)

2021-09-06T00:00:00.000Z (UTC, including milliseconds)

2021-09-06T00:00:00Z+00:00 (MSK)

status

string

No

Alert status. If the parameter is specified several times, then a list is generated and the logical OR operator is applied.

new, assigned, escalated, closed

withEvents

bool

No

Include normalized KUMA events associated with found alerts in the response. If the parameter is present in the URL query, then its value is assumed to be true. The values specified by the user are ignored. Example: /api/v1/alerts?withEvents

 

withAffected

bool

No

Include information about the assets and accounts associated with the found alerts in the report.  If the parameter is present in the URL query, then its value is assumed to be true. The values specified by the user are ignored. Example: /api/v1/alerts?withAffected

 

Response

HTTP code: 200

Format: JSON

type Response []Alert

 

type Alert struct {

    ID                string            `json:"id"`

    TenantID          string            `json:"tenantID"`

    TenantName        string            `json:"tenantName"`

    Name              string            `json:"name"`

    CorrelationRuleID string            `json:"correlationRuleID"`

    Priority          string            `json:"priority"`

    Status            string            `json:"status"`

    FirstSeen         string            `json:"firstSeen"`

    LastSeen          string            `json:"lastSeen"`

    Assignee          string            `json:"assignee"`

    ClosingReason     string            `json:"closingReason"`

    Overflow          bool              `json:"overflow"`

    Events            []NormalizedEvent `json:"events"`

    AffectedAssets    []AffectedAsset   `json:"affectedAssets"`

    AffectedAccounts  []AffectedAccount `json:"affectedAccounts"`

}

 

type NormalizedEvent map[string]interface{}

 

type AffectedAsset struct {

    ID               string          `json:"id"`

    TenantID         string          `json:"tenantID"`

    TenantName       string          `json:"tenantName"`

    Name             string          `json:"name"`

    FQDN             string          `json:"fqdn"`

    IPAddresses      []string        `json:"ipAddresses"`

    MACAddresses     []string        `json:"macAddresses"`

    Owner            string          `json:"owner"`

    OS               *OS             `json:"os"`

    Software         []Software      `json:"software"`

    Vulnerabilities  []Vulnerability `json:"vulnerabilities"`

    KSC              *KSCFields      `json:"ksc"`

    Created          string          `json:"created"`

    Updated          string          `json:"updated"`

}

 

type OS struct {

    Name    string `json:"name"`

    Version uint64 `json:"version"`

}

 

type Software struct {

    Name    string `json:"name"`

    Version string `json:"version"`

    Vendor  string `json:"vendor"`

}

 

type Vulnerability struct {

    KasperskyID           string   `json:"kasperskyID"`

    ProductName           string   `json:"productName"`

    DescriptionURL        string   `json:"descriptionURL"`

    RecommendedMajorPatch string   `json:"recommendedMajorPatch"`

    RecommendedMinorPatch string   `json:"recommendedMinorPatch"`

    SeverityStr           string   `json:"severityStr"`

    Severity              uint64   `json:"severity"`

    CVE                   []string `json:"cve"`

    ExploitExists         bool     `json:"exploitExists"`

    MalwareExists         bool     `json:"malwareExists"`

}

 

type AffectedAccount struct {

    Name             string `json:"displayName"`

    CN               string `json:"cn"`

    DN               string `json:"dn"`

    UPN              string `json:"upn"`

    SAMAccountName   string `json:"sAMAccountName"`

    Company          string `json:"company"`

    Department       string `json:"department"`

    Created          string `json:"created"`

    Updated          string `json:"updated"`

}

Possible errors

HTTP code

Description

message field value

details field value

400

Invalid value of the "page" parameter

invalid query parameter value

page

400

Invalid value of the "status" parameter

invalid status

<status>

400

Invalid value of the "timestampField" parameter

invalid timestamp field

 

400

Invalid value of the "from" parameter

cannot parse from

variable

400

Invalid value of the "to" parameter

cannot parse to

variable

400

The value of the "from" parameter is greater than the value of the "to" parameter

from cannot be greater than to

 

500

Any other internal errors

variable

variable

Page top