openapi: 3.2.0 info: description: '# Introduction This API is documented using the **OpenAPI 2.0** specification.' title: Logz.io Security rules API termsOfService: https://logz.io/about-us/terms-of-use/ contact: email: help@logz.io url: https://docs.logz.io/ license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://api.logz.io/ security: - X-API-TOKEN: [] tags: - name: Security Rules description: Security rules help you connect the dots between your data sources and events that could indicate a security threat or breach. paths: /v2/security/rules: post: tags: - Security Rules summary: Create a security rule description: 'Creates a new security rule and activates it. Please ensure to change the region in the URL to match your account''s region.' operationId: createSecurityRule responses: '201': description: successful operation content: application/json: schema: $ref: '#/components/schemas/SecurityRuleResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/SecurityRuleRequest' /v2/security/rules/{ruleId}: get: tags: - Security Rules operationId: getSecurityRule summary: Retrieve a security rule description: 'Retrieves a security rule by its ID. Please ensure to change the region in the URL to match your account''s region.' parameters: - name: ruleId in: path required: true description: null schema: type: integer format: int32 responses: '200': description: successful operation headers: {} content: application/json: schema: $ref: '#/components/schemas/SecurityRuleResponse' put: summary: Update a security rule description: 'Applies changes to a rule, identified by its ID. Can also be used to enable or disable a rule. Please ensure to change the region in the URL to match your account''s region.' tags: - Security Rules operationId: updateSecurityRule parameters: - name: ruleId in: path required: true schema: type: integer format: int32 responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/SecurityRuleResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/SecurityRuleRequest' delete: summary: Delete a security rule description: 'Deletes a security rule by its ID. Please ensure to change the region in the URL to match your account''s region.' tags: - Security Rules operationId: deleteSecurityRule parameters: - name: ruleId in: path required: true schema: type: integer format: int32 responses: '200': description: successful operation headers: {} content: application/json: schema: $ref: '#/components/schemas/SecurityRuleResponse' /v2/security/rules/search: post: tags: - Security Rules operationId: searchAccountSecurityRules summary: Retrieve security rules description: '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.' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/PagedSearchResponseSecurityRuleResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/AlertsSearchRequest' /v2/security/rules/{id}/enable: post: tags: - Security Rules operationId: enableSecurityRule summary: Enable a rule description: 'Enables a security rule by its ID. Please ensure to change the region in the URL to match your account''s region.' parameters: - name: id description: Rule ID in: path required: true example: 305572 schema: type: integer format: int32 responses: default: description: successful operation /v2/security/rules/{id}/disable: post: tags: - Security Rules operationId: disableSecurityRule summary: Disable a rule description: 'Disables a security rule by its ID. Please ensure to change the region in the URL to match your account''s region.' parameters: - name: id description: Rule ID in: path required: true example: 305976 schema: type: integer format: int32 responses: default: description: successful operation /v2/security/rules/bulk/update: post: tags: - Security Rules operationId: bulkUpdateSecurityRule summary: Bulk update security rules description: 'Update security rules in bulk. Please ensure to change the region in the URL to match your account''s region.' responses: default: description: successful operation requestBody: content: application/json: schema: type: object properties: filters: type: object properties: search: type: string description: Search string example: string severities: type: array description: Filter by the severities of the security rules. You can manually test your results in the [UI](https://app.logz.io/#/dashboard/security/rules/rule-definitions?from=0&sortBy=updatedAt&sortOrder=DESC). items: type: string example: SEVERE enum: - INFO - LOW - MEDIUM - HIGH - SEVERE updatedBy: type: array description: Email addresses of the last users to update the rules items: type: string example: user@company.com createdBy: type: array description: Email addresses of the users to create the rules items: type: string example: user@company.com enabledState: type: list of booleans description: true to include enabled rules, false to include disabled rules. An empty list defaults to both enabled and disabled rules. emailNotifications: type: array description: List of email addresses on the recipients list to receive notifications when the rules trigger. items: type: string example: string notificationsEndpointIds: type: array description: Notification endpoints items: type: integer format: int32 example: 0 tags: type: array description: Tags are labels used to organize security rules. example: threat items: type: object example: network_threat: null recon: null ruleIds: type: array items: type: integer format: int32 example: 0 fields: type: object properties: enabled: description: Whether felds are enabled. type: boolean recipients: type: object description: Recepients. properties: recipientsOperation: description: Recepients operation. type: string example: ADD recipients: type: object description: Recepients. properties: emails: type: array description: Email addresses of the recepients. items: type: string example: string notificationEndpointIds: type: array description: Notification endpoints. items: type: integer format: int32 example: 0 all: type: boolean required: true /v2/security/rules/bulk/delete: post: tags: - Security Rules operationId: bulkDeleteSecurityRule summary: Bulk delete security rules description: 'Delete security rules in bulk. Please ensure to change the region in the URL to match your account''s region.' responses: default: description: successful operation requestBody: content: application/json: schema: type: object properties: filters: type: object properties: search: type: string description: Search string example: string severities: type: array description: Filter by the severities of the security rules. You can manually test your results in the [UI](https://app.logz.io/#/dashboard/security/rules/rule-definitions?from=0&sortBy=updatedAt&sortOrder=DESC). items: type: string example: SEVERE enum: - INFO - LOW - MEDIUM - HIGH - SEVERE updatedBy: type: array description: Email addresses of the last users to update the rules items: type: string example: user@company.com createdBy: type: array description: Email addresses of the users to create the rules items: type: string example: user@company.com enabledState: type: list of booleans description: true to include enabled rules, false to include disabled rules. An empty list defaults to both enabled and disabled rules. emailNotifications: type: array description: List of email addresses on the recipients list to receive notifications when the rules trigger. items: type: string example: string notificationsEndpointIds: type: array description: Notification endpoints items: type: integer format: int32 example: 0 tags: type: array description: Tags are labels used to organize security rules. example: threat items: type: object example: network_threat: null recon: null ruleIds: type: array items: type: integer format: int32 example: 0 fields: type: object properties: enabled: description: Whether felds are enabled. type: boolean recipients: type: object description: Recepients. properties: recipientsOperation: description: Recepients operation. type: string example: ADD recipients: type: object description: Recepients. properties: emails: type: array description: Email addresses of the recepients. items: type: string example: string notificationEndpointIds: type: array description: Notification endpoints. items: type: integer format: int32 example: 0 all: type: boolean required: true components: schemas: AlertsSearchRequest: title: Search request Results type: object properties: filter: description: Filter by rule name, severity, and more. If you want to get all rules, just send `filter` as an empty object the payload. $ref: '#/components/schemas/AlertsFilter' sort: description: Explicit sorting rules are not required, but recommended. Otherwise the database will determine the sorting. $ref: '#/components/schemas/AlertsSortRequest' pagination: $ref: '#/components/schemas/Pagination' SecurityRuleRequest: type: object required: - subComponents properties: title: type: string description: Rule title example: Excessive WARN levels in PROD description: type: string description: A description of the event, its significance, and suggested next steps or instructions for the team. example: Steps to remediate... tags: type: array items: type: string maxItems: 25 minItems: 0 description: Tags for filtering rules and triggered rules. Can be used in Kibana Discover, dashboards, and more. example: network output: $ref: '#/components/schemas/RuleOutput' searchTimeFrameMinutes: type: integer minimum: 5 maximum: 1440 format: int32 description: '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.' example: 20 subComponents: type: array description: Sets the search criteria using a search query, filters, group by aggregations, accounts to search, and trigger conditions. items: $ref: '#/components/schemas/SubRule' correlations: $ref: '#/components/schemas/SubRuleCorrelation' enabled: type: boolean description: If `true`, the alert is enabled and active. schedule: $ref: '#/components/schemas/RuleSchedule' sendToAll: type: boolean default: false description: If `true`, a single email will be sent to all email addresses. rca: type: boolean description: Activate AI Agent analysis (OrionIQ) for the rule. rcaNotificationEndpointIds: type: array items: type: integer description: Notification endpoint IDs for AI Agent analysis (OrionIQ). useAlertNotificationEndpointsForRca: type: boolean description: Whether to use rule notification endpoints for AI Agent analysis (OrionIQ). runbook: type: string description: Runbook instructions to help the AI Agent analysis (OrionIQ) understand how to handle the rule better. mitreTags: type: array items: type: string description: "Maps this rule to MITRE ATT&CK tactics and techniques. \nHelps correlate events with known adversary behavior. \nTags are saved as MITRE ATT&CK ID, for example: \"T0895\" , \"T1695.001\"" PagedSearchResponseSecurityRuleResponse: type: object properties: total: type: integer format: int32 description: 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. example: 500 results: type: array items: $ref: '#/components/schemas/SecurityRuleResponse' pagination: $ref: '#/components/schemas/Pagination' AlertsFilter: type: object properties: search: type: string description: Searches by rule titles and descriptions that contain the string. severities: type: array items: type: string enum: - INFO - LOW - MEDIUM - HIGH - SEVERE description: List of rule severities, as specified by the security rule's definition example: - SEVERE - HIGH updatedBy: type: array items: type: string description: Email addresses of the last users to update the rules createdBy: type: array items: type: string description: Email addresses of the user who created the rules. enabledState: type: list of booleans description: true to include enabled rules, false to include disabled rules. An empty list defaults to both enabled and disabled rules. example: - true emailNotifications: type: array items: type: string description: List of email addresses on the recipients list to receive notifications when the rules trigger. tags: type: array items: type: string description: Tags are labels used to organize security rules AlertsSortRequest: type: object required: - field properties: sortByField: type: string description: Sort by a single parameter. enum: - SEVERITY - name - createdAt - updatedAt descending: type: boolean default: true description: If left blank, descending sorting will result. If `false` results in ascending sorting. RuleSchedule: type: object description: Defines the frequency and the time frame in which an rule will be evaluated. properties: cronExpression: type: string description: Cron job for the intervals schedule. example: 0 0/60 9-17 ? * * * timezone: type: string description: Time zone for the cron job. If no time zone is selected, UTC will be used by default. example: America/Sao_Paulo BoolFilter: type: object description: 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](https://www.elastic.co/guide/en/elasticsearch/reference/6.8/query-dsl-bool-query.html) for more detail. properties: bool: $ref: '#/components/schemas/FilterLists' Aggregation: type: object description: Specifies a trigger condition that acts as a threshold. properties: aggregationType: type: string description: '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.' enum: - SUM - MIN - MAX - AVG - COUNT - UNIQUE_COUNT - NONE - PERCENTAGE - PERCENTILE fieldToAggregateOn: type: string description: 'Selects the field on which to run the aggregation for the trigger condition. * Cannot be a field already in use for `groupBy`.' valueToAggregateOn: type: string description: '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.' SubRuleOutput: type: object description: 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. properties: columns: type: array items: $ref: '#/components/schemas/ColumnConfig' shouldUseAllFields: type: boolean description: If `true`, the notification output will include entire logs with all of their fields in the sample data. default: true RuleOutput: type: object description: Automatically sends out notifications with sample results when the rule triggers. properties: recipients: $ref: '#/components/schemas/RuleRecipients' suppressNotificationsMinutes: type: integer format: int32 minimum: 5 maximum: 1440 description: 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.) example: 60 type: type: string description: 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. enum: - JSON - TABLE RuleTrigger: type: object description: Sets the triggering threshold and severity tab to label the event when the rule triggers. properties: operator: type: string enum: - LESS_THAN - GREATER_THAN - LESS_THAN_OR_EQUALS - GREATER_THAN_OR_EQUALS - EQUALS - NOT_EQUALS example: GREATER_THAN_OR_EQUALS description: Specifies the operator for evaluating the results. severityThresholdTiers: type: object description: '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.' enum: - INFO - LOW - MEDIUM - HIGH - SEVERE additionalProperties: null default: MEDIUM: 10.0 example: MEDIUM: 10.0 HIGH: 100.0 SEVERE: 300.0 SubRule: type: object properties: queryDefinition: $ref: '#/components/schemas/RuleQuery' trigger: $ref: '#/components/schemas/RuleTrigger' output: $ref: '#/components/schemas/SubRuleOutput' SubRuleCorrelation: type: object description: '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.' properties: correlationOperators: type: array items: type: string enum: - AND joins: type: array description: '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`.' items: type: object additionalProperties: null example: 0: region 1: region ColumnConfig: type: object description: Customize the alert output to be sent out in notifications when the alert triggers. properties: fieldName: type: string description: Specify the fields to be included in the notification. regex: type: string description: Trims the data using regex filters. [Learn more](https://docs.logz.io/user-guide/alerts/regex-filters.html) sort: type: string description: 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). enum: - DESC - ASC FilterLists: type: object description: Runs Elasticsearch [Bool Query](https://www.elastic.co/guide/en/elasticsearch/reference/6.8/query-dsl-bool-query.html) filters on the data (before the search query is applied). The most efficient way to grab the logs you are looking for. properties: must: type: array items: type: object properties: match_phrase: type: object properties: Field: type: object properties: query: type: string example: value must_not: type: array items: type: object properties: match_phrase: type: object properties: Field: type: object properties: query: type: string example: value Pagination: type: object description: 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. properties: pageNumber: type: integer format: int32 description: If you overshoot the page number, it will return empty with no results, but it won't fail the request. default: 1 example: 1 pageSize: type: integer format: int32 description: Controls the number of results per page. Valid inputs are 1 to 1000. maximum: 1000 default: 25 example: 100 RuleRecipients: type: object description: Add email addresses and/or endpoint channels to automatically receive notifications with sample data when the rule triggers. properties: emails: type: array description: Array of email addresses to be notified when the rule triggers. items: type: string example: tom.a@logz.io notificationEndpointIds: type: array description: Array of IDs of pre-configured endpoint channels to notify when the rule triggers. items: type: integer format: int32 SecurityRuleResponse: type: object properties: id: type: integer format: int32 description: Logz.io security rule ID. example: 627816 updatedAt: type: string description: Date and time in UTC when the rule was last updated. example: 2020-04-02 18:58:16+00:00 updatedBy: type: string description: Email of the user who last updated the rule. example: tomer@logz.io createdAt: type: string description: Date and time in UTC when the rule was first created updated. example: 2020-02-02 18:58:16+00:00 createdBy: type: string description: Email of the user who first created the rule. example: tomer@logz.io enabled: type: boolean description: If `true`, the rule is currently active. exampe: true title: type: string description: Rule title. example: Excessive WARN levels in PROD description: type: string description: A description of the event, its significance, and suggested next steps or instructions for the team. example: Steps to remediate... tags: type: array items: type: string description: Tags for filtering rules and triggered rules. Can be used in Kibana Discover, dashboards, and more. example: - network - aws output: $ref: '#/components/schemas/RuleOutput' searchTimeFrameMinutes: type: integer minimum: 5 maximum: 1440 format: int32 description: '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: type: array description: Determines when the rule should trigger using any combination of a search query, filters, group by aggregations, accounts to search, and trigger conditions. items: $ref: '#/components/schemas/SubRule' correlations: $ref: '#/components/schemas/SubRuleCorrelation' protected: type: boolean description: "If `true`, the rule is pre-defined by Logz.io. Protected parameters cannot be edited. \nThe only parameters that can be edited are:\n\n* `shouldQueryOnAllAccounts`\n* `accountIdsToQueryOn`\n* `severityThresholdTiers`\n* `tags`\n* `description`\n* `enabled`\n* `output` (in `subComponents`)\n* `searchTimeFrameMinutes`\n* `schedule`\n* `sendToAll`\n* `rca`\n* `rcaNotificationEndpointIds`\n* `useAlertNotificationEndpointsForRca`\n* `runbook`" schedule: $ref: '#/components/schemas/RuleSchedule' sendToAll: type: boolean description: If `true`, one email will be sent with all email address. default: false rca: type: boolean description: Activate AI Agent analysis (OrionIQ) for the rule. rcaNotificationEndpointIds: type: array items: type: integer description: Notification endpoint IDs for AI Agent analysis (OrionIQ). useAlertNotificationEndpointsForRca: type: boolean description: Whether to use rule notification endpoints for AI Agent analysis (OrionIQ). runbook: type: string description: Runbook instructions to help the AI Agent analysis (OrionIQ) understand how to handle the rule better. mitreTags: type: array items: type: string description: "Maps this rule to MITRE ATT&CK tactics and techniques. \nHelps correlate events with known adversary behavior. \nTags are saved as MITRE ATT&CK ID, for example: \"T1110\" , \"T1090.003\"" RuleQuery: type: object description: Determines when the rule should trigger using any combination of a search query, filters, group by aggregations, accounts to search, and trigger conditions. properties: query: type: string description: '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.' default: '*' example: type:apache_access filters: $ref: '#/components/schemas/BoolFilter' groupBy: type: - array - 'null' description: 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. items: type: string maxItems: 3 minItems: 0 aggregation: $ref: '#/components/schemas/Aggregation' shouldQueryOnAllAccounts: type: boolean default: true example: false description: 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: type: array description: Specify Account IDs to select which accounts the rule should monitor. The rule will be checked only on these accounts. items: type: integer format: int32 example: 2321 securitySchemes: X-API-TOKEN: description: 'You can manage your API tokens from the [Logz.io API tokens](https://app.logz.io/#/dashboard/settings/manage-tokens/api) page. API tokens are account-specific. You will need to be logged into the relevant Log Management or SIEM account to view the API tokens associated with it. To manage your API tokens, log into the relevant account in your Logz.io platform, click the gear in the top-right menu, and select [**Tools > Manage tokens > API tokens**](https://app.logz.io/#/dashboard/settings/manage-tokens/api). It''s important to keep your tokens secure. API tokens carry privileges to make changes to users and accounts, so if you believe an API token has been compromised, delete it, and replace it with a new token in your integrations.' type: apiKey in: header name: X-API-TOKEN x-servers: - url: https://api.logz.io description: US East (Northern Virginia) - url: https://api-au.logz.io description: Asia Pacific (Sydney) - url: https://api-ca.logz.io description: Canada (Central) - url: https://api-eu.logz.io description: Europe (Frankfurt) - url: https://api-uk.logz.io description: Europe (London) x-tagGroups: - name: Log Monitoring tags: - Search logs - Alerts - Deployments - Insights - Logz.io snapshots - name: Cloud SIEM tags: - Security account - Security rules - Security events - Lookup lists - name: Account administration tags: - Manage users - Manage metrics account - Associated accounts - Authentication groups - Who am I - Manage time-based log accounts - Manage shared tokens - Manage API tokens - Manage notification endpoints - Import or export Kibana objects - name: Manage data shipping tags: - Manage log shipping tokens - Drop filters - Archive logs - Restore logs - Parsing - Delete object API - name: Data security tags: - Retrieve audit trail - name: Connect to AWS resources tags: - Connect to CloudTrail - Connect to S3 Buckets - name: Metrics API Gateway tags: - Grafana contact points - Grafana data source - Grafana alerting provisioning - Grafana silence management - Grafana annotations - Grafana dashboards - Grafana dashboard search - Grafana snapshots - Grafana get all folders description: Metrics API Gateway to supported endpoints.