Skip to main content

Retrieve security rules

POST 
/v2/security/rules/search

Retrieve a list of security rules for a specific Security account. The results are paginated. Filtering, sorting and pagination are all optional. If you want to get all rules, send the payload in {} format. Please ensure to change the region in the URL to match your account's region.

Request​

Body

    filter object

    Filter by rule name, severity, and more. If you want to get all rules, just send filter as an empty object the payload.

    search string

    Searches by rule titles and descriptions that contain the string.

    severities string[]

    List of rule severities, as specified by the security rule's definition

    updatedBy string[]

    Email addresses of the last users to update the rules

    createdBy string[]

    Email addresses of the user who created the rules.

    enabledState list of booleans

    true to include enabled rules, false to include disabled rules. An empty list defaults to both enabled and disabled rules.

    emailNotifications string[]

    List of email addresses on the recipients list to receive notifications when the rules trigger.

    tags string[]

    Tags are labels used to organize security rules

    sort object

    Explicit sorting rules are not required, but recommended. Otherwise the database will determine the sorting.

    sortByField string

    Possible values: [SEVERITY, NAME, CREATED_AT, UPDATED_AT]

    Sort by a single parameter.

    descending boolean

    Default value: true

    If left blank, descending sorting will result. If false results in ascending sorting.

    pagination object

    Default pagination is a page of 25 results. Look for the total field in the response for the number of available results overall, and use the pagination function to page through the results.

    pageNumber int32

    Default value: 1

    If you overshoot the page number, it will return empty with no results, but it won't fail the request.

    pageSize int32

    Possible values: <= 1000

    Default value: 25

    Controls the number of results per page. Valid inputs are 1 to 1000.

Responses​

successful operation

Schema
    total int32

    The total number of rules returned by the query. The total entities found after filtering and sorting. This number is fixed and not affected by pagination.

    results object[]
  • Array [
    • id int32

    Logz.io security rule ID.

    updatedAt string

    Date and time in UTC when the rule was last updated.

    updatedBy string

    Email of the user who last updated the rule.

    createdAt string

    Date and time in UTC when the rule was first created updated.

    createdBy string

    Email of the user who first created the rule.

    enabled boolean

    If true, the rule is currently active.

    title string

    Rule title.

    description string

    A description of the event, its significance, and suggested next steps or instructions for the team.

    tags string[]

    Tags for filtering rules and triggered rules. Can be used in Kibana Discover, dashboards, and more.

    output object

    Automatically sends out notifications with sample results when the rule triggers.

    recipients object

    Add email addresses and/or endpoint channels to automatically receive notifications with sample data when the rule triggers.

    emails string[]

    Array of email addresses to be notified when the rule triggers.

    notificationEndpointIds int32[]

    Array of IDs of pre-configured endpoint channels to notify when the rule triggers.

    suppressNotificationsMinutes int32

    Possible values: >= 5 and <= 1440

    Add a waiting period in minutes to space out notifications. (The rule will still trigger but will not send out notifications during the waiting period.)

    type string

    Possible values: [JSON, TABLE]

    Selects the output format for the rule notification. If the rule has no aggregations/group by fields, JSON offers the option to send full sample logs without selecting specific fields.

    searchTimeFrameMinutes int32

    Possible values: >= 5 and <= 1440

    The time frame for evaluating the log data is a sliding window, with 1 minute granularity.

    The recommended minimum and maximum values are not validated, but needed to guarantee the rule's accuracy.

    The minimum recommended time frame is 5 minutes, as anything shorter will be less reliable and unnecessarily resource-heavy.

    The maximum recommended time frame is 1440 minutes (24 hours). The rule runs on the index from today and yesterday (in UTC) and the maximum time frame increases throughout the day, reaching 48 hours exactly before midnight UTC.

    subComponents object[]

    Determines when the rule should trigger using any combination of a search query, filters, group by aggregations, accounts to search, and trigger conditions.

  • Array [
    • queryDefinition object

    Determines when the rule should trigger using any combination of a search query, filters, group by aggregations, accounts to search, and trigger conditions.

    query string

    Default value: *

    Provide a Kibana search query written in Lucene syntax. The search query together with the filters select for the relevant logs.

    Cannot be null - send an asterisk wildcard * if not using a search query.

    filters object

    Apply must and must_not filters to the monitoring alert. Filters are more efficient compared to a query, so it's recommended to opt for a filter over a query, where possible. See Elasticsearch Bool-Query for more detail.

    bool object

    Runs Elasticsearch Bool Query filters on the data (before the search query is applied). The most efficient way to grab the logs you are looking for.

    must object[]
  • Array [
    • match_phrase object
    Field object
    query string
  • ]
    • must_not object[]
  • Array [
    • match_phrase object
    Field object
    query string
  • ]
    • groupBy string[]nullable

    Possible values: <= 3

    Specify 1-3 fields by which to group the results and count them. If you apply a group by operation, the rule returns a count of the results aggregated by unique values.

    aggregation object

    Specifies a trigger condition that acts as a threshold.

    aggregationType string

    Possible values: [SUM, MIN, MAX, AVG, COUNT, UNIQUE_COUNT, NONE, PERCENTAGE, PERCENTILE]

    Specifies the aggregation operator.

    • If COUNT, fieldToAggregateOn must be null, and groupBy fields must not be empty.

    • If NONE, fieldToAggregateOn must be null, and groupBy field must not be empty (or null).

    • If PERCENTAGE, valueToAggregateOn must be specified.

    • If any other operator type (other than NONE or COUNT), fieldToAggregateOn must not be null.

    fieldToAggregateOn string

    Selects the field on which to run the aggregation for the trigger condition.

    • Cannot be a field already in use for groupBy.
    valueToAggregateOn string

    Used by the PERCENTAGE aggregation to select the field’s value. This value is used to determine if its ratio out of the total amount of logs in the query satisfies the trigger condition.

    • Only relevant for the PERCENTAGE aggregation.
    shouldQueryOnAllAccounts boolean

    Default value: true

    Only applicable when the rule is run from the main account. If true, the rule runs on the main account and all associated searchable sub accounts. If false, specify relevant account IDs for the rule to monitor using the accountIdsToQueryOn field.

    accountIdsToQueryOn int32[]

    Specify Account IDs to select which accounts the rule should monitor. The rule will be checked only on these accounts.

    trigger object

    Sets the triggering threshold and severity tab to label the event when the rule triggers.

    operator string

    Possible values: [LESS_THAN, GREATER_THAN, LESS_THAN_OR_EQUALS, GREATER_THAN_OR_EQUALS, EQUALS, NOT_EQUALS]

    Specifies the operator for evaluating the results.

    severityThresholdTiers object

    Possible values: [INFO, LOW, MEDIUM, HIGH, SEVERE]

    Default value: [object Object]

    Sets a severity label per trigger threshold as a key:value pair.

    If using more than one sub-component, only 1 severityThresholdTiers is allowed. Otherwise, 1 per enum are allowed (for a total of 5 thresholds of increasing severities).

    Increasing severity must adhere to the logic of the operator.

    output object

    Selects the data output to be sent in the notification when the rule triggers. Not applicable, when grouping by fields or aggregating results, as the output is auto-selected.

    columns object[]
  • Array [
    • fieldName string

    Specify the fields to be included in the notification.

    regex string

    Trims the data using regex filters. Learn more

    sort string

    Possible values: [DESC, ASC]

    Specify a single field to sort by. The field cannot be an analyzed field (a field that supports free text search or searching by part of a message, such as the 'message' field).

  • ]
  • ]
    • correlations object

    Only applicable when multiple sub-components are in use. Selects a logic for correlating the rule’s sub-components.

    AND is currently the only supported operator. When AND is the correlationOperator, both sub-components must meet their triggering criteria for the rule to trigger.

    correlationOperators string[]

    Possible values: [AND]

    joins object[]

    Specifies which group by fields must have the same values to trigger the rule.

    Joins the group by fields from the first and second sub-components. The key represents the index of the sub component in the array (See the example - the index of the first sub-component is 0, the second is 1).

    The fields must be ordered pairs of the group by fields already in use in the queryDefinition.

    protected boolean

    If true, the rule is pre-defined by Logz.io. Protected parameters cannot be edited. The only parameters that can be edited are

    • shouldQueryOnAllAccounts
    • accountIdsToQueryOn
    • severityThresholdTiers
    • tags
    • description
    • enabled
    • output (in subComponents)
    • searchTimeFrameMinutes
    schedule object

    Defines the intervals in which an alert will be evaluated. This feature is still in production, but the payload already contains the data.

    cron string

    Cron job for the intervals schedule.

    timezone string

    Time zone for the cron job. If no time zone is selected, UTC will be used by default.

    mitreTags string[]

    Tags used for classifying, discussing, and interpreting security incidents. This feature is currently under development.

  • ]
    • pagination object

    Default pagination is a page of 25 results. Look for the total field in the response for the number of available results overall, and use the pagination function to page through the results.

    pageNumber int32

    Default value: 1

    If you overshoot the page number, it will return empty with no results, but it won't fail the request.

    pageSize int32

    Possible values: <= 1000

    Default value: 25

    Controls the number of results per page. Valid inputs are 1 to 1000.

Loading...