Alerts and rules

List alert rules

  query ListAlertInstances(
    $alertStatus: AlertStatus
    $limit: Int
    $cursor: String
  ) {
    listAlertInstances(
      alertStatus: $alertStatus
      limit: $limit
      cursor: $cursor
    ) {
      instances {
        id
        accountId
        ruleId
        level
        status
        lastUpdatedOn
        lastEvaluationBeginOn
        lastEvaluationEndOn
        createdOn
        dismissedOn
        lastEvaluationResult {
          rawDataDescriptors {
            recordCount
          }
        }
        questionRuleInstance {
          id
          name
          description
          question {
            queries {
              query
              name
            }
          }
        }
      }
      pageInfo {
        endCursor
        hasNextPage
      }
    }
  }

Variables:

Filtering for ACTIVE Alerts:

{
  "alertStatus": "ACTIVE",
}

{
  "alertStatus": "INACTIVE",
}

Filtering for DISMISSED Alerts:

{
  "alertStatus": "DISMISSED",
}

To apply a limit to the number of results returned, pass a limit variable:

{
  "limit": 10
}

To paginate through the results, pass the endCursor received in the response as the cursor variable in the request. If endCursor is null then there are no more results to retrieve.

Create an inline alert rule from J1QL

This operation was formerly named createQuestionRuleInstance. That name is now deprecated, and you should update all usages.

mutation CreateInlineQuestionRuleInstance(
  $instance: CreateInlineQuestionRuleInstanceInput!
) {
  createInlineQuestionRuleInstance(instance: $instance) {
    id
    name
    description
    version
    pollingInterval
    question {
      queries {
        query
        version
      }
    }
    operations {
      when
      actions
    }
    outputs
  }
}

Variables:

{
  "instance": {
    "name": "unencrypted-prod-data",
    "description": "Data stores in production tagged critical and unencrypted",
    "version": "v1",
    "pollingInterval": "ONE_DAY",
    "outputs": ["alertLevel"],
    "operations": [
      {
        "when": {
          "type": "FILTER",
          "version": 1,
          "condition": [
            "AND",
            ["queries.unencryptedCriticalData.total", "!=", 0]
          ]
        },
        "actions": [
          {
            "type": "SET_PROPERTY",
            "targetProperty": "alertLevel",
            "targetValue": "CRITICAL"
          },
          {
            "type": "CREATE_ALERT"
          }
        ]
      }
    ],
    "question": {
      "queries": [
        {
          "query": "Find DataStore with (production=true or tag.Production=true) and classification='critical' and encrypted!=true as d return d.tag.AccountName as Account, d.displayName as UnencryptedDataStores, d._type as Type, d.encrypted as Encrypted",
          "version": "v1",
          "name": "unencryptedCriticalData"
        }
      ]
    }
  }
}

Note that the recommended interval for query based alert rules (aka a question) is ONE_DAY. \

Supported intervals for enterprise customers are: DISABLED, THIRTY_MINUTES, ONE_HOUR, FOUR_HOURS, EIGHT_HOURS, TWELVE_HOURS, ONE_DAY, and ONE_WEEK.

Free accounts only have access to the ONE_WEEK interval by default, but any upgrades to Compliance, Security, or Integrations will provide access to the ONE_DAY polling interval too.

Update an inline alert rule

This operation was formerly named updateQuestionRuleInstance. That name is now deprecated, and you should update all usages.

mutation UpdateInlineQuestionRuleInstance(
  $instance: UpdateInlineQuestionRuleInstanceInput!
) {
  updateInlineQuestionRuleInstance(instance: $instance) {
    id
    name
    description
    version
    pollingInterval
    question {
      queries {
        query
        version
      }
    }
    operations {
      when
      actions
    }
    outputs
  }
}

Variables:

{
  "instance": {
    "id": "b1c0f75d-770d-432a-95f5-6f59b4239c72",
    "name": "unencrypted-prod-data",
    "description": "Data stores in production tagged critical and unencrypted",
    "version": "v1",
    "pollingInterval": "ONE_DAY",
    "outputs": ["alertLevel"],
    "operations": [
      {
        "when": {
          "type": "FILTER",
          "version": 1,
          "condition": [
            "AND",
            ["queries.unencryptedCriticalData.total", "!=", 0]
          ]
        },
        "actions": [
          {
            "type": "SET_PROPERTY",
            "targetProperty": "alertLevel",
            "targetValue": "CRITICAL"
          },
          {
            "type": "CREATE_ALERT"
          }
        ]
      }
    ],
    "question": {
      "queries": [
        {
          "query": "Find DataStore with (production=true or tag.Production=true) and classification='critical' and encrypted!=true as d return d.tag.AccountName as Account, d.displayName as UnencryptedDataStores, d._type as Type, d.encrypted as Encrypted",
          "version": "v1",
          "name": "unencryptedCriticalData"
        }
      ]
    }
  }
}

Note that the only difference for update is the "id" property associated with the rule instance. You can modify all settings of a rule instance.

Create an alert rule by referencing a saved question

mutation CreateReferencedQuestionRuleInstance(
  $instance: CreateReferencedQuestionRuleInstanceInput!
) {
  createReferencedQuestionRuleInstance(instance: $instance) {
    id
    name
    description
    version
    pollingInterval
    questionId
    questionName
    operations {
      when
      actions
    }
    outputs
  }
}

Variables:

{
  "instance": {
    "name": "unencrypted-prod-data",
    "description": "Data stores in production tagged critical and unencrypted",
    "version": "v1",
    "pollingInterval": "ONE_DAY",
    "outputs": ["alertLevel"],
    "operations": [
      {
        "when": {
          "type": "FILTER",
          "version": 1,
          "condition": [
            "AND",
            ["queries.unencryptedCriticalData.total", "!=", 0]
          ]
        },
        "actions": [
          {
            "type": "SET_PROPERTY",
            "targetProperty": "alertLevel",
            "targetValue": "CRITICAL"
          },
          {
            "type": "CREATE_ALERT"
          }
        ]
      }
    ],
    "questionId": "uuid-of-saved-question",
    "questionName": "name-of-saved-question" // either questionId or questionName must be specified
  }
}

Note that you must specify either questionName or questionId in the instance for creation.

If you specify both, they must refer to the same question. After the rule is saved, subsequent requests will return both questionId and questionName.

Update an alert rule with a referenced question

mutation UpdateReferencedQuestionRuleInstance(
  $instance: UpdateReferencedQuestionRuleInstanceInput!
) {
  updateReferencedQuestionRuleInstance(instance: $instance) {
    id
    name
    description
    version
    pollingInterval
    questionId
    questionName
    operations {
      when
      actions
    }
    outputs
  }
}

Variables:

{
  "instance": {
    "id": "b1c0f75d-770d-432a-95f5-6f59b4239c72",
    "name": "unencrypted-prod-data",
    "description": "Data stores in production tagged critical and unencrypted",
    "version": "v1",
    "pollingInterval": "ONE_DAY",
    "outputs": ["alertLevel"],
    "operations": [
      {
        "when": {
          "type": "FILTER",
          "version": 1,
          "condition": [
            "AND",
            ["queries.unencryptedCriticalData.total", "!=", 0]
          ]
        },
        "actions": [
          {
            "type": "SET_PROPERTY",
            "targetProperty": "alertLevel",
            "targetValue": "CRITICAL"
          },
          {
            "type": "CREATE_ALERT"
          }
        ]
      }
    ],
    "questionId": "uuid-of-saved-question",
    "questionName": "name-of-saved-question"
  }
}

Note that the only difference in update is the "id" property associated with the rule instance. You can modify any of the settings of a rule instance. Updates are not required to specify questionId or questionName, but you can specify either for update, and if you specify both they must refer to the same saved question.

Delete an alert rule

You can use this operation to delete any rule instance, regardless of whether it uses an inline question or a referenced question.

mutation DeleteRuleInstance($id: ID!) {
  deleteRuleInstance(id: $id) {
    id
  }
}

Variables:

{
  "id": "b1c0f75d-770d-432a-95f5-6f59b4239c72"
}

note

Deleting an alert rule this way does not dismiss active alerts already triggered by this rule. It is recommended that you Disable a rule in the Alerts app UI instead of deleting one.

Trigger an alert rule on demand

mutation EvaluateRuleInstance($id: ID!) {
  evaluateRuleInstance(id: $id) {
    outputs {
      name
      value
    }
  }
}

Variables:

{
  "id": "b1c0f75d-770d-432a-95f5-6f59b4239c72"
}