Alert Rule Schema

A rule uses the results of one or more queries to execute one or more actions. The basic alert workflows are described here: JupiterOne Alert Rule configuration documentation Users can also directly edit the JSON that defines a rule for more advanced workflow execution:

Steps to configuring a rule

1. Navigate to the JupiterOne alert rule configuration page (e.g. https://apps.us.jupiterone.io/alerts/edit)
2. Click "Create Rule"
3. Click "Show Advanced" to open the advanced rule editor

JSON Example:

{
  "id": "552b2f27-67e2-4351-97f3-083a040350c1",
  "name": "unencrypted-critical-data-stores",
  "description": "Unencrypted data store with classification label of 'critical' or 'sensitive' or 'confidential' or 'restricted'",
  "version": 1,
  "specVersion": 1,
  "pollingInterval": "ONE_DAY",
  "question": {
    "queries": [
      {
        "name": "query0",
        "query": "Find DataStore with classification=('critical' or 'sensitive' or 'confidential' or 'restricted') and encrypted!=true",
        "version": "v1"
      }
    ]
  },
  "operations": [
    {
      "when": {
        "type": "FILTER",
        "condition": "{{queries.query0.total > 0}}"
      },
      "actions": [
        {
          "type": "CREATE_ALERT"
        }
      ]
    }
  ],
  "outputs": ["queries.query0.total", "alertLevel"]
}

Rule Properties

Type: PollingInterval

Enumeration of the scheduled frequencies that rules can automatically be evaluated. Possible values:

ONE_DAY
ONE_HOUR
THIRTY_MINUTES
DISABLED

Type: RuleOperation

A RuleOperation is a single condition and series of actions that are executed when the condition is met.

Type: Question

A Question contains a collection of named queries that should be executed during the rule evaluation process and whose responses can be used in any RuleOperation.

Type: QuestionQuery

A named query that should be executed during the rule evaluation process and whose responses can be used in any RuleOperation.

Type: RuleOperationCondition

Condition used to determine whether the associated action(s) should be executed. The type of RuleOperationCondition is determined using the type property.

Type: FilterRuleOperationCondition

Type: RuleOperationAction

Action that is executed when a corresponding condition is met. The type of RuleOperationAction is determined using the type property.

Action: SET_PROPERTY

Includes a property that can be used in rule evaluation input.

Example:

{
  "type": "SET_PROPERTY",
  "targetProperty": "alertLevel",
  "targetValue": "CRITICAL"
}

Action: CREATE_ALERT

Creates a JupiterOne alert that is visible on the alerts app.

Example:

{
  "type": "CREATE_ALERT"
}

Action: SEND_EMAIL

Sends an email to a list of recipients with details related to alerts that were created during the rule evaluation.

Example:

{
  "type": "SEND_EMAIL",
  "recipients": ["no-reply@jupiterone.io"]
}

Action CREATE_JIRA_TICKET

Creates a Jira ticket using a specific JupiterOne Jira integration configuration.

Example:

{
  "type": "CREATE_JIRA_TICKET",
  "integrationInstanceId": "b59cfa95-2201-4173-bea4-be9b26661553",
  "entityClass": "Vulnerability",
  "project": "81198",
  "summary": "Ticket summary",
  "issueType": "Task",
  "additionalFields": {
    "description": {
      "type": "doc",
      "version": 1,
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "Jira description here!"
            }
          ]
        }
      ]
    }
  }
}

Action: SEND_SLACK_MESSAGE

Sends a Slack message to a given Slack webhook URL.

Example:

Once the integration has been configured, copy the integration ID from the integration instance page. It will look something like d1549f40-b9fd-447a-bec5-4360c9ca7e8c.

1. Configure a rule with the SEND_SLACK_MESSAGE action and specify the integrationInstanceId with the unique identifier of the integration and channels denoting the destinations. Example alert rule configuration with the SEND_SLACK_MESSAGE action:

NOTE: In order for the JupiterOne Slack bot to deliever messages to a private Slack channel, the JupiterOne Slack bot must be a member of that private channel.

{
  "name": "slack-alert-test",
  "description": "Testing Slack Messages",
  "specVersion": 1,
  "pollingInterval": "ONE_DAY",
  "templates": {
    "slackBody": "JupiterOne Account: {{item.displayName}}\n\n"
  },
  "question": {
    "queries": [
      {
        "name": "query0",
        "query": "Find DataStore with classification=('critical' or 'sensitive' or 'confidential' or 'restricted') and encrypted!=true",
        "version": "v1"
      }
    ]
  },
  "operations": [
    {
      "when": {
        "type": "FILTER",
        "specVersion": 1,
        "condition": "{{queries.query0.total > 0}}"
      },
      "actions": [
        {
          "targetValue": "HIGH",
          "type": "SET_PROPERTY",
          "targetProperty": "alertLevel"
        },
        {
          "type": "CREATE_ALERT"
        },
        {
          "integrationInstanceId": "d1549f40-b9fd-447a-bec5-4360c9ca7e8c",
          "channels": ["#random"],
          "type": "SEND_SLACK_MESSAGE",
          "body": "{{queries.query0.data|mapTemplate('slackBody')|join(' ')}}"
        }
      ]
    }
  ],
  "outputs": ["queries.query0.total", "alertLevel"]
}

Action: WEBHOOK

Sends an HTTP request to a given endpoint.

Example:

{
  "type": "WEBHOOK",
  "method": "POST",
  "body": {
    "name": "Jon"
  },
  "headers": {
    "Authorization": "Bearer abc123"
  }
}

Action: PUBLISH_SNS_MESSAGE

Publishes a message to the specified SNS topic.

Example:

{
  "type": "PUBLISH_SNS_MESSAGE",
  "integrationInstanceId": "...",
  "topicArn": "arn:aws:sns:<REGION>:arn:aws:sns:<ACCOUNT_ID>:<SNS_TOPIC_NAME>",
  "data": {
    "query0Data": "{{queries.query0.data}}",
    "anotherCustomProperty": true
  }
}

Note:

data is stringified in payload. For example:

{
  Sns: {
    Message: '{"data":{"query0Data": ..., "anotherCustomProperty": true}}'
  }
}

Action: SEND_SQS_MESSAGE

Publishes a message to the specified SQS queue.

Example:

{
  "type": "SEND_SQS_MESSAGE",
  "integrationInstanceId": "...",
  "queueUrl": "https://sqs.<REGION>.amazonaws.com/<ACCOUNT_ID>/<SQS_QUEUE_NAME>",
  "data": {
    "query0Data": "{{queries.query0.data}}",
    "anotherCustomProperty": true
  }
}

Note:

data is stringified in payload. For example:

{
  body: '{"data":{"query0Data": ..., "anotherCustomProperty": true}}'
}

Operation Templating

Templates can be used inside of any property under the operations property on a rule. The templates can contain a JavaScript-like syntax that automatically have input variables injected for usage.

For example, FilterRuleOperationCondition's are often used with rules as the condition for whether rule actions should be executed. You can use query response data inside of the rule conditions:

{
  "operations": [
    {
      "when": {
        "type": "FILTER",
        // Use the `.total` property from query named `query0`.
        "condition": "{{queries.query0.total > 0}}"
      },
      "actions": [
        {
          "type": "CREATE_ALERT"
        }
      ]
    }
  ]
}

Data from query results can be used inside of rule operations by referencing the query.query0.data property and custom templating transforms. For example:

{
  "name": "lambda-function-settings-check-runtime-nodejs610",
  "description": "Node.js 6.10 is end of life (EOL) and should no longer be used.",
  "specVersion": 1,
  "pollingInterval": "ONE_DAY",
  "templates": {
    // The email template that we will use later
    "emailBody": "({{itemIndex+1}} of {{itemCount}}) [{{item.account}}] Function Name: {{item.functionName}}<br>"
  },
  "question": {
    "queries": [
      {
        "name": "query0",
        "query": "Find aws_lambda_function with runtime='nodejs6.10' as f return f.name as functionName, f.version as version, f.tag.AccountName as account, f.tag.Project as project order by account",
        "version": "v1"
      }
    ]
  },
  "operations": [
    {
      "when": {
        "type": "FILTER",
        "specVersion": 1,
        "condition": "{{queries.query0.total > 0}}"
      },
      "actions": [
        {
          "targetValue": "HIGH",
          "type": "SET_PROPERTY",
          "targetProperty": "alertLevel"
        },
        {
          "type": "CREATE_ALERT"
        },
        {
          "type": "SEND_EMAIL",
          // Reference the `query0` data and include it in a template
          "body": "Affected Functions: <br><br>{{queries.query0.data|mapTemplate('emailBody')|join(' ')}}",
          "recipients": ["no-reply@jupiterone.io"]
        }
      ]
    }
  ],
  "outputs": ["queries.query0.total", "alertLevel"]
}

Rule Evaluation Templating Language

A template can be created in any RuleOperation using the {{...}} syntax. Inside of the {{...}} is a JavaScript-like language that allows for powerful rule evaluation functionality. Additionally, if the template contains exactly one expression and nothing else, the original type of the computed value is preserved. If multiple expressions are used, the entire value is casted to a string.

The following is an example where the type boolean would be preserved because there is only a single expression:

{{true}}

The following is an example where the entire value would be cast to a string because it contains multiple expressions:

{{age + 10}} is my age and my name is {{firstName + " " + lastName}}

Unary Operators

Binary Operators

Comparisons

Ternary operator

Native Types

Groups

Grouping operations with parentheses:

Custom Transforms

Some custom transforms are exposed in the rule templating language.

mapTemplate(templateName: string) Custom Transform

mapTemplate is used to separate and reuse templates inside of a rule. The transform expects a single array and the first argument should be a string whose value matches a template in rule templates object.

The mapTemplate transform exposes additional input variable to the template:

NOTE: The properties that are accessible on the item property are pulled from the properties object and the entity object if the item matches the schema for an entity.

Example operation:

{
  "type": "SEND_EMAIL",
  // Reference the `query0` data and include it in a template
  "body": "{{queries.query0.data|mapTemplate('emailBody')|join(' ')}}",
  "recipients": ["no-reply@jupiterone.io"]
}

Example templates:

{
  "emailBody": "({{itemIndex+1}} of {{itemCount}}) [{{item.account}}] Function Name: {{item.somePropertyOnItem}}<br>"
}

mapProperty(...properties: string) Custom Transform

Allows for mapping individual properties from an array. A single property may be supplied or multiple properties may be supplied. The properties that are accessible are pulled from the properties object and the entity object if the item matches the schema for an entity. If the array that is being evaluated with mapProperty matches the schema of an entity, the the rule evaluator will attempt to pull properties passed to mapProperty from the entity properties.

Example query data:

{
  "query": "FIND Person",
  "data": [
    {
      "id": "",
      "entity": {
        "_createdOn": 1234
        // ...
      },
      "properties": {
        "firstName": "Jon"
        // ...
      }
    },
    {
      "id": "",
      "entity": {
        "_createdOn": 12345
        // ...
      },
      "properties": {
        "firstName": "Jane"
        // ...
      }
    }
  ]
}

Example accessing properties data using mapProperty and the above data:

{
  "type": "SEND_EMAIL",
  // This would return: `Jon,Jane`
  "body": "{{queries.query0.data|mapProperty('firstName')|join}}",
  "recipients": ["no-reply@jupiterone.io"]
}

Example accessing entity data using mapProperty and the above data:

{
  "type": "SEND_EMAIL",
  // This would return: `1234,12345`
  "body": "{{queries.query0.data|mapProperty('_createdOn')|join}}",
  "recipients": ["no-reply@jupiterone.io"]
}

join(separator?: string) Custom Transform

Similar to the Array.prototype.join function in JavaScript. Returns a new string by concatenating all of the elements in an array. If the separator argument is not passed to join, the array elements are separated by a comma by default.

This transform will often be used with mapTemplate or mapProperty.

Example:

{
  "type": "SEND_EMAIL",
  "body": "{{queries.query0.data|mapTemplate('emailBody')|join(' ')}}",
  "recipients": ["no-reply@jupiterone.io"]
}

Example of default if no separator is passed to join:

{
  "type": "SEND_EMAIL",
  "body": "{{queries.query0.data|mapTemplate('emailBody')|join}}",
  "recipients": ["no-reply@jupiterone.io"]
}