Manage detections as code (DaC) in SIEM (InsightIDR)

Detections as code lets you manage SIEM (InsightIDR) detections using code instead of configuring them manually in the user interface. You define detection logic and settings declaratively, store them in version control, and deploy changes through your existing CI/CD pipelines.

Using SIEM (InsightIDR) APIs, you can programmatically create and update detections. Terraform manages SIEM (InsightIDR) resources as infrastructure as code (IaC).

By managing detections alongside your infrastructure and application code, you can:

• Promote consistent, repeatable deployments across environments
• Reduce configuration drift
• Track and audit changes through version control
• Apply updates without manual changes in the SIEM (InsightIDR) interface

This approach helps security teams integrate detection management into established development and operations workflows.

Why use Terraform for detections as code?

Terraform helps you manage detections as code by applying infrastructure-as-code (IaC) practices to detection engineering. When you define detection rules as declarative resources, you can version, validate, and promote changes in a controlled and repeatable way.

Instead of making manual updates in the user interface, you define the desired state in code and let Terraform enforce it consistently across environments and tenants.

• Declarative management – Define the desired state of detection rules in code and maintain it as your single source of truth.
• Version control and review – Store detections in Git, track changes over time, and use pull requests to support peer review.
• Safe change previews – Use terraform plan to preview changes before you apply them.
• Controlled promotion – Promote detections across development, staging, and production environments using a plan → approve → apply workflow.
• Reduced configuration drift – Ensure deployed detections match what is defined in your repository.
• Multi-tenant scale – Manage and update detections consistently across multiple environments or customer tenants.
• Auditability and compliance – Maintain a clear change history to support investigations, reporting, and compliance requirements.

If you are new to Terraform, review their documentation .

Getting started

Prerequisites

Before you start managing your detection rules as code, make sure you have the following in place:

• SIEM (InsightIDR) access with permissions to create and manage detection rules, as well as the relevant organization IDs and API keys. For more information on getting organization keys and API keys, read Manage Platform API Keys .
• Install Terraform. You can download this from this location , taking note of the version.
  • Review the Rapid7 Provider documentation  on the Terraform Registry site. Take note of the source for the Rapid7 provider.
  • (Optional) Install the Terraform extension for Visual Studio Code .
• Git installed and access to a Git repository to version, review, and manage detection rule code.

Set up Terraform workspace and configure Rapid7 provider

Complete the following steps to set up a Terraform workspace and configure Rapid7 as a provider:

1. Open your terminal (or command prompt) and create a new directory for your Terraform configuration:

mkdir directory-name 2. Create a provider configuration file called provider.tf. 3. In the file, specify that the configuration requires the Rapid7 provider:

1. Provide the source and version which you would have gotten in the prerequisite steps .
2. Set up variables for authentication: region, organization ID, API key. Note that these are stored as plaintext in the state file. Read more here .
3. Include the configuration block that references the setup of the Rapid7 provider, configured from the organization_id, region, and api_key, provided from the manager where these are stored. You received the organization ID and API key in the prerequisite steps.

terraform {
  required_providers {
    rapid7 = {
      source  = "rapid7/rapid7"
      version = "[Refer to provider documentation for latest version https://registry.terraform.io/providers/rapid7/rapid7/latest]"
    }
  }
}

variable "region" {}

variable "organization_id" {}

variable "api_key" {}

provider "rapid7" {
  organization_id = var.organization_id
  region          = var.region
  api_key         = var.api_key
}

4. Create a variables file called variables.tfvars. In the variables file, define the values for region, organization_id, and api_key. This configures the provider with the credentials to be able to access the API.
5. In the command line, run terraform init to initialize the workspace. This installs the required providers.

You can now start creating resources. We’ll start with a basic detection rule.

Create a basic custom detection rule

Define a new resource for a custom detection rule by completing the following steps:

1. Create a Terraform file and provide an appropriate name.
2. In the file, create a resource for the detection rule.
3. Provide the required attributes for the rule. The required attributes are:
   1. name: Give the custom detection rule a meaningful name.
   2. description: Provide a general description of the purpose of the custom detection rule.
   3. action: Set an action  for the detection rule. For the purposes of testing, set this as CREATES_ALERTS with a priority of INFO.
   4. priority: Set the priority .
   5. logic: Define the LEQL  conditions that determine when the rule should trigger. Note: Subqueries, groupby clauses, and calculate functions are not supported in custom detection rules.
   6. Other optional configurable attributes can be found in the schema here .

  name           = "Horrible Malware"
  description    = "Detects horrible malware"
  recommendation = "Uninstall!"
  techniques     = ["T1589"]

  action   = "CREATES_ALERTS"
  priority = "MEDIUM"

  logic = {
    leql = <<-LEQL
      from(event_type = process_start_event)
      where(
        process.cmd_line ICONTAINS "malware.exe"
      )
    LEQL
  }
}

4. Return to the command prompt, run the -out plan command, and review the attributes to be applied.
5. Run apply to create the detection rule in the configured organization.
6. (Optional) Return to the Detection Rules Library in the SIEM (InsightIDR) UI and confirm that the newly created rule is visible.

Create an exception

You can include an exception  alongside a detection rule to specify circumstances where the detection rule should not fire:

1. Open the resource in your editor.
2. Provide the required attributes for the exception:
   1. name: Give the exception a meaningful name.
   2. action: Set an action  for the exception.
   3. priority: Set the priority .
   4. logic: Define the LEQL  conditions that determine when the exception should trigger. Note: Subqueries, groupby clauses, and calculate functions are not supported in custom detection rules.
   5. Rule RRN (Rapid7 resource name): Add the RRN of the detection rule you want the exception to apply to.
   6. Other optional configurable attributes can be found in the schema here .

resource "rapid7_siem_detection_rule_exception" "example_exception" {
  rule_rrn = rapid7_siem_detection_rule.example_rule.rrn

  name = "Suppress for me"

  action   = "OFF"
  priority = "LOW"
  logic = {
    # One of either a collection of key-value pair conditions...
    conditions = [
      {
        key            = "user"
        operator       = "IS"
        value          = "trusted"
        case_sensitive = false
      },
      {
        key      = "source_ip"
        operator = "CIDR"
        value    = "127.0.0.1/32"
      }
    ]

    # ...or a LEQL exception
    # leql = <<-LEQL
    #   where(
    #     user IN [trusted, safe] AND
    #     source_ip = IP(127.0.0.1/32)
    #   )
    # LEQL
  }
}

3. Return to the command prompt, run the plan command, and review the attributes to be applied.
4. (Optional) Return to the Detection Rules Library in the SIEM (InsightIDR) UI and confirm that the newly added exception is visible.

Managing detections as code resources

Edit a resource

After creating the detection rule or exception as a resource, you may need to modify the attributes of the detection rule:

1. Open the resource in your editor and edit the attributes as necessary.
2. Return to the command prompt, run the terraform plan -out=plan command, and review the changes.
3. Run terraform apply to apply the changes to the detection rule or exception.
4. (Optional) Return to the Detection Rules Library in the SIEM (InsightIDR) UI and confirm that the changes have been applied.

Delete a resource

1. Open the resource in your editor. Remove the detection rule or exception entirely.
2. Return to the command prompt, run the plan command, and review the changes.
3. Run apply to apply the changes to the detection rule or exception.
4. (Optional) Return to the Detection Rules Library in the SIEM (InsightIDR) UI and go to Deleted Detection Rules to confirm the detection rule has been removed. If you just deleted an exception, go to the relevant detection rule and confirm the exception has been removed.

Terraform Import

You can use the terraform import command to bring existing resources and their current configuration into your Terraform state. This approach is especially helpful if you’ve made multiple changes directly in the UI and want to capture those updates without manually recreating each change in your configuration files. By importing the resource, you align your Terraform state with the current state of your environment, reducing duplication and minimizing the risk of configuration drift.

To import changes made in the UI to your Terraform configuration, complete the following steps:

1. Locate the detection rule you wish to import in the Detection Rule Library.
2. Copy the RRN for the changed detection rule you want to import. If you cannot find the RRN, complete the steps here .
3. In the file where your detection rule resources are located, create an import block:

import {
  id = "rrn:cba:ux2:a123456b-ab12-3456-c78d-12a3456b7c8"
  to = "abc_custom_detection_rule.abc_malware"

1. id: Paste the RRN you copied from the UI here.
2. to: Include the resource identifier of your resource append and the name of the rule. For example, detection_rule_resource.detection_rule_name.
3. Run plan -generate-config-out=[path], where [path] is the name of the file where you’d like the import to go.
4. Review the config, confirming all the fields being imported from the UI are present.
5. Run plan. The rule can now be managed through detections as code.

Bulk Import

If you want to bulk import detection rules from the UI to get them under detections as code management, you can import rules in batch. To learn more, review our documentation in the Terraform provider page .

Reports and analytics

A data source is available for alert reports , which utilizes alert triage APIs to provide statistical breakdowns, such as alerts by rule or status, helping you to understand the performance of custom detection rules. This data can be exported as JSON for use in external dashboards.

To configure report generation using this data source, complete the following steps:

1. Create a new Terraform file in your workspace and give it an appropriate name that matches your reporting purpose.
2. In that file, define the siem_alert_report data source. Refer to the schema documented in the dropdown below for guidance. Multiple levels of aggregation can be included, as needed.

data "rapid7_siem_alert_report" "report" {
  from = timeadd(plantimestamp(), "-${30 * 24}h") # 30 days ago
  to   = plantimestamp()                          # Now

  # Filter by status
  query = "alert.status IN [OPEN, INVESTIGATING, CLOSED]"

  aggregation = [
    ["alert.organization.id", "alert.organization.name"],
    # Aggregate by rule
    ["alert.rule.rrn", "alert.rule.name"],
    # Then by status
    ["alert.status"]
  ]
}

3. In the command prompt, run terraform init.
4. Run terraform plan -out alert_reports.tfplan to create a plan file (recommended for repeatability).
5. Run terraform apply alert_reports.tfplan to apply the plan.
6. To generate a JSON report, run terraform output -json alerts_by_rule_then_status_json > alert_report.json

The output format of the reports can now be used in third-party tools for reporting.

Managing detections as code in GitHub

Detections as code lets you manage custom detections using a Git-based, pull request (PR) workflow. Detection logic is stored in your repository and promoted through controlled validation and approval steps before deployment.

The exact implementation depends on your environment, CI/CD tooling, and governance requirements. The workflow below reflects a common and recommended approach using GitHub, Jenkins, Terraform, and Atlantis.

Suggested workflow

1. Clone the repository Clone your detections repository locally to begin making changes.
2. Make and test changes locally Update the Terraform configuration. Before submitting changes, run local validation checks (such as schema validation, linting, and optional unit tests) to catch syntax or logic issues early and to avoid promoting noisy detection rules to production.
3. Open a Pull Request (PR) Push your branch and open a PR. All detection changes follow a PR-driven workflow to ensure visibility and review.
4. Automated validation (Jenkins + CI) When the PR is opened or updated, Jenkins runs automated checks, which may include:
   • Detection validation and formatting checks
   • Preflight validation
   • Test execution This ensures issues are identified before changes are approved.
5. Terraform plan via Atlantis As Terraform is used to manage detections, Atlantis automatically runs terraform plan and posts the results as a comment in the PR. This allows reviewers to clearly see what will change before deployment.
6. Review and approval required Changes must be reviewed and approved before they can be applied. This helps maintain detection quality, performance expectations, and operational guardrails.
7. Apply and promote After approval, Atlantis applies the changes (plan → approve → apply). Detections are promoted through environments in a controlled, auditable manner.