This article highlights how Elastic's new Terraform resources for security detection rules and exceptions expand practitioners' capabilities for detection-as-code deployment. Below you will find examples of defining and deploying your detection artifacts in Elastic Security with Terraform. We will also show how you can use Elastic's AI Agent to help quickly create the Terraform configuration for your custom rules. Finally, it also provides guidance on when to use the Elastic Stack Terraform provider versus tools from the detection-rules repository.

Managing Elastic with Terraform

Terraform is a tool created by HashiCorp (now IBM) to manage infrastructure in the cloud, or in self-managed environments, as code. With a simple stroke of HCL (HashiCorp configuration language), users can define the desired state of their cloud provider infrastructure, application, configuration, and in Elastic’s case, cluster settings, configuration, indices or streams, and now also detection rules and alerts, as fully configurable, traceable, and reviewable code in your favorite source management tool.

The Elastic Stack Terraform provider helps search, observability, and security professionals, as well as DevOps and SREs, configure their Elastic clusters with the right indices and mappings for their search use cases, SLOs or Fleet policies for their observability use case, and now, detection rules, alerts, and exceptions for their security use case. It can easily configure those, and many more objects and settings in the Elastic Stack.

Security Detection rules - now as code with Terraform

With V0.12.0 and V0.13.0 of the Elastic Stack Terraform provider, users can now manage their Detection rules and rule exceptions using Terraform. This is especially useful for users who have already been managing their Elastic deployments with Terraform and want to extend it to Detection rules.

Using the Elastic Stack Terraform Provider to deploy Rules and Exceptions

Let's look at an example of using the Elastic Stack Terraform Provider to deploy an Elastic Security Rule. In this example, we want to detect Windows Service Accounts that are performing an interactive logon on a host.

Service accounts typically have elevated privileges and rarely-rotated passwords, making them high-value targets for attackers. Since these accounts should only perform automated service logons, an interactive logon can indicate credential theft or misuse.

The first thing we need to think of is what telemetry we need to see which logons are happening on our host. Logon events are logged by the Windows Local Security Authority Subsystem Service (LSASS) whenever a logon session is successfully created on the machine. We can pick this up via an Elastic Agent with the Windows Integration installed.

The data will be written by the Elastic Agent into the system.security Data Stream, we can match it with this index pattern: logs-system.security-*. We also know that Logon events generate event code 4624 and that, in our example, the service account name starts with svc or ends with $. In addition, an interactive login will have a logon type of interactive.

So, we can match these events with an ES|QL rule like:

FROM logs-system.security-\*  
| WHERE event.code \== "4624" AND (user.name LIKE "svc\_\*" OR user.name LIKE "svc-\*"  
     OR user.name LIKE "\*\_svc" OR user.name LIKE "\*$")  
     AND winlog.logon.type IN ("Interactive", "RemoteInteractive",  
         "CachedInteractive", "CachedRemoteInteractive")  

There may be situations where we don't want this rule to run, for example, if there is a legacy application that we want to permit interactive logons from. So, we can create an Exception Item, like: user.name IS svc\_sqlbackup.

Now that we know what we want the Rule and its Exceptions to look like, we can use the Terraform provider's elasticstack_kibana_security_detection_rule, elasticstack_kibana_security_exception_list, and elasticstack_kibana_security_exception_item resources to define them in code.

Turning ES|QL rules into Terraform's configuration syntax, HCL, is a great use case for Elastic's AI Agent.
Elastic AI Agent capabilities help accelerate security operations across a wide range of tasks - from alerts triage and incident response to helping with detection lifecycle tasks.

Simply open AI Agent, and ask it to create Terraform configurations based on your query and exceptions.

You should end up with something like this:

Here's a closer look at the code.

There are a few elements to call out specifically:

• type: The type of exception list. For example: detection, endpoint, or endpoint_trusted_apps
• namespace_type: Determines whether the exception list is available in all Kibana spaces or just the single space in which it was created.

resource "elasticstack_kibana_security_exception_list" "svc_account_interactive_login" {
  list_id        = "svc-account-interactive-login-exceptions"
  name           = "Service Account Interactive Login Exceptions"
  description    = "Documented exceptions for service accounts that legitimately require interactive logon"
  type           = "detection"
  namespace_type = "single"
  tags           = ["service-accounts","windows","authentication"]
}  

This creates a new exception list.

Of note, the entries array contains the conditions under which the exception applies.

resource "elasticstack_kibana_security_exception_item" "svc_sqlbackup" {
  list_id        = elasticstack_kibana_security_exception_list.svc_account_interactive_login.list_id
  item_id        = "svc-sqlbackup-exception"
  name           = "svc_sqlbackup - Legacy SQL Backup Agent"
  description    = "Approved exception: Legacy SQL backup agent requires interactive logon per vendor documentation."
  type           = "simple"
  namespace_type = "single"
  tags           = ["sql","backup","approved"]
entries = [
    {
      field    = "user.name"
      type     = "match"
      operator = "included"
      value    = "svc_sqlbackup"
    }
  ]
} 

This adds our exception: that we don't want the rule to run if the username is svc\_sqlbackup.

Of note, the elements from enabled to the technique array are examples of the other properties that can be set on a rule.

resource "elasticstack_kibana_security_detection_rule" "svc_account_interactive_login" {
  name        = "Service Account Interactive Login"
  description = <<-EOT
    Detects interactive logins by service accounts. Service accounts should authenticate
    via service (Type 5) or batch (Type 4) logon types, not interactively. Interactive
    logins by service accounts may indicate credential theft or misuse.

    This rule identifies service accounts by common naming conventions (svc_*, svc-*,
    *_svc) and managed service accounts (*$).
  EOT

  type     = "esql"
  language = "esql"
  query    = <<-EOT
    FROM logs-system.security-* metadata _id, _version, _index
    | WHERE event.code == "4624"
      AND (user.name LIKE "svc_*" OR user.name LIKE "svc-*" OR user.name LIKE "*_svc" OR user.name LIKE "*$")
      AND winlog.logon.type IN ("Interactive", "RemoteInteractive", "CachedInteractive", "CachedRemoteInteractive")
    | KEEP @timestamp, host.name, user.name, user.domain, winlog.logon.type, source.ip, _id, _version, _index
  EOT

  enabled    = true 
  severity   = "high"
  risk_score = 73

  from     = "now-6m"
  to       = "now"
  interval = "5m"

  author  = ["Security Team"]
  license = "Elastic License v2"
  tags    = [
    "Domain: Endpoint",
    "OS: Windows",
    "Use Case: Identity and Access Audit",
    "Tactic: Initial Access",
    "Data Source: Windows Security Event Log"
  ]

  false_positives = [
    "Service accounts with documented exceptions that require interactive logon",
    "Break-glass procedures during incident response",
    "Initial service account configuration or troubleshooting"
  ]

  references = [
    "https://learn.microsoft.com/en-us/entra/architecture/service-accounts-on-premises",
    "https://blog.quest.com/10-microsoft-service-account-best-practices/",
    "https://attack.mitre.org/techniques/T1078/002/"
  ]

  threat = [
    {
      framework = "MITRE ATT&CK"
      tactic = {
        id        = "TA0001"
        name      = "Initial Access"
        reference = "https://attack.mitre.org/tactics/TA0001/"
      }
      technique = [
        {
          id        = "T1078"
          name      = "Valid Accounts"
          reference = "https://attack.mitre.org/techniques/T1078/"
          subtechnique = [
            {
              id        = "T1078.002"
              name      = "Domain Accounts"
              reference = "https://attack.mitre.org/techniques/T1078/002/"
            }
          ]
        }
      ]
    }
  ]

  exceptions_list = [
    {
      id             = elasticstack_kibana_security_exception_list.svc_account_interactive_login.id
      list_id        = elasticstack_kibana_security_exception_list.svc_account_interactive_login.list_id
      namespace_type = elasticstack_kibana_security_exception_list.svc_account_interactive_login.namespace_type
      type           = elasticstack_kibana_security_exception_list.svc_account_interactive_login.type
    }
  ]
}

Finally, we define the rule, including the ES|QL query we provided earlier and MITRE ATT&CK classification.

You can add these resource definitions into one configuration file (perhaps security-rules.tf), add it to your configured Elastic Stack terraform directory, and then run the `terraform apply` command and parameter to deploy the Rule.

terraform apply --auto-approve

Since terraform apply runs a plan before making changes, it will automatically detect if anyone has edited a rule directly in Kibana and show you exactly what drifted: no manual exports or diffs needed.

After Terraform has made the changes, we can see the Rule in Kibana:

We can also see the Exception List:

This way, you can define your detections in Terraform and benefit from automatic deployment along with other objects you manage with Terraform.

Terraform workspaces for multi-space Elastic deployments

Terraform uses a concept called “workspaces” allowing you to reuse the same infrastructure code for multiple deployments, for example, a dev, testing, and production environment. This concept is useful for managing rules across multiple deployments and/or Kibana spaces.

Managing detections with Terraform and Detections as code

Elastic also has Detections as Code functionality available via our open detection-rules repository.

The two tools have complementary strengths and are aligned with different user profiles and workflow stages for implementing Detections as Code.

Detection as Code features in detection-rules

• Best fit user profile: Detection engineers
• Intended workflow phase: Rule authoring and validation

With dual-sync between your GitHub repo and Kibana, linting, schema validation, and unit-testing, detection-rules functionality is well-suited to experienced Detection Engineers comfortable with Git-based version control.

Elastic Stack Terraform Provider

• Best fit user profile: DevOps engineers / Platform teams
• Intended workflow phase: Deployment and operations

For users already using Terraform to manage their Elastic clusters, the Terraform Provider is a great fit, bringing consistency to all "x-as-code" operations and familiar state management and parameterization.

The key differences and optimal use cases for each tool are detailed in the comparison table below:

In short, Detection Engineers are better served by the specialized creation and testing tools provided in the detection-rules repository, while DevOps/Platform Teams should use the Terraform provider to manage detection rules as part of their broader infrastructure-as-code strategy for deployment and operations.

Try it out

To experience the full benefits of what Elastic has to offer for detection engineers, upgrade to 9.3 or start your Elastic Security free trial. Visit elastic.co/security to learn more and get started.

The release and timing of any features or functionality described in this post remain at Elastic's sole discretion. Any features or functionality not currently available may not be delivered on time or at all.

This brings your detection logic and ML jobs into the same versioned, peer-reviewed workflow as your core clusters. It ensures your security posture and AI connectors are no longer manual outliers in an otherwise automated environment.

The challenge: Security and observability configuration at scale

As Elastic deployments grow, so does the complexity of managing them. Security teams maintain hundreds of detection rules. SREs configure monitoring across dozens of clusters. ML engineers tune anomaly detection jobs across multiple environments. All of these configurations must be consistent, auditable, and reproducible.

Without infrastructure as code, teams face two problems:

1. Configuration drift. Rules, policies, and monitors are created manually through the Kibana UI. Over time, production and staging diverge. No one is sure which version of a detection rule is running where.

2. Buried audit trail. When a detection rule changes or an exception is added, there's no pull request to review, no commit history to trace, and no rollback path if something breaks. Users need to put in extra effort to access such history.

Elastic Stack Terraform provider solves this by bringing these configurations into the same version-controlled, peer-reviewed workflow that teams already use for infrastructure.

Security artifacts as code: Detection rules, exceptions, and prebuilt rules

You can now manage the full lifecycle of Elastic Security detection rules through Terraform.

Detection rules

The elasticstack_kibana_security_detection_rule resource lets you define, version, and deploy detection rules in the HashiCorp Configuration Language (HCL) format:

resource "elasticstack_kibana_security_detection_rule" "suspicious_admin_logon" {
  name        = "Suspicious Admin Logon Activity"
  type        = "query"
  query       = "event.action:logon AND user.name:admin"
  language    = "kuery"
  enabled     = true
  description = "Detects suspicious admin logon activities"
  severity    = "high"
  risk_score  = 75
  from        = "now-6m"
  to          = "now"
  interval    = "5m"
  tags        = ["security", "authentication", "admin"]
}

This means your detection rules live in Git, undergo code review, and are deployed consistently across environments. No more clicking through the Kibana UI to replicate rules from staging to production.

Detection rule resource docs

Exception lists and items

The security-as-code story extends to a full suite of exception management resources:

• elasticstack_kibana_security_exception_list - Create and manage exception lists
• elasticstack_kibana_security_exception_item - Define individual exception items within a list
• elasticstack_kibana_security_list and elasticstack_kibana_security_list_item - Manage value lists for IP allowlists, file hashes, and other indicators
• elasticstack_kibana_security_list_data_streams - Associate lists with specific data streams

Here's an example that ties them together - an exception list with items that suppress known false positives for a detection rule:

resource "elasticstack_kibana_security_exception_list" "vuln_scanner_exceptions" {
  list_id        = "vuln-scanner-exceptions"
  name           = "Vulnerability Scanner Exceptions"
  description    = "Suppress alerts from authorized vulnerability scanners"
  type           = "detection"
  namespace_type = "single"
  tags           = ["security", "vulnerability-scanning"]
}

resource "elasticstack_kibana_security_exception_item" "nessus_scanner" {
  list_id        = elasticstack_kibana_security_exception_list.vuln_scanner_exceptions.list_id
  item_id        = "nessus-scanner"
  name           = "Nessus Scanner - Authorized"
  description    = "Suppress alerts from authorized Nessus scanner hosts"
  type           = "simple"
  namespace_type = "single"

  entries = [
    {
      type     = "match"
      field    = "source.ip"
      operator = "included"
      value    = "10.0.50.10"
    },
    {
      type     = "match_any"
      field    = "process.name"
      operator = "included"
      values   = ["nessus", "nessusd"]
    }
  ]

  tags = ["nessus", "authorized-scanner"]
}

resource "elasticstack_kibana_security_exception_item" "qualys_scanner" {
  list_id        = elasticstack_kibana_security_exception_list.vuln_scanner_exceptions.list_id
  item_id        = "qualys-scanner"
  name           = "Qualys Scanner - Authorized"
  description    = "Suppress alerts from authorized Qualys scanner subnet"
  type           = "simple"
  namespace_type = "single"

  entries = [
    {
      type     = "match"
      field    = "source.ip"
      operator = "included"
      value    = "10.0.51.0/24"
    }
  ]

  tags = ["qualys", "authorized-scanner"]
}

The exception list and its items are linked by list_id, so Terraform manages the dependency graph automatically. Adding a new authorized scanner is a one-line PR - no clicking through the Kibana UI, no risk of forgetting which environment got the update.

Prebuilt security rules

The elasticstack_kibana_prebuilt_rule resource lets you manage Elastic's prebuilt detection rules via Terraform. This is particularly valuable for organizations that need to track which prebuilt rules are enabled, customize their parameters, and ensure consistent deployment across environments.

ML anomaly detection as code

Machine learning anomaly detection is one of Elasticsearch's most powerful capabilities - but managing ML jobs across environments has traditionally been a manual process. You create a job in the Kibana UI, tune the detectors, configure the datafeed, and hope someone documents the settings so they can be replicated in the next environment.

The elasticstack_elasticsearch_ml_anomaly_detection_job resource changes that. You can now define the full configuration of an anomaly detection job in HCL - detectors, bucket spans, influencers, data feeds, and analysis limits - and deploy it consistently across dev, staging, and production.

resource "elasticstack_elasticsearch_ml_anomaly_detection_job" "cpu_anomalies" {
  job_id      = "high-cpu-by-host"
  description = "Detect unusual CPU usage patterns"

  analysis_config = {
    bucket_span = "15m"
    detectors   = [{
      function   = "high_mean"
      field_name = "system.cpu.user_pct"
    }]
    influencers = ["host.name"]
  }

  data_description = {
    time_field = "@timestamp"
  }
}

This matters for teams that rely on ML to catch infrastructure anomalies, unusual user behavior, or security threats. Instead of manually recreating jobs when spinning up new clusters or recovering from failures, the entire ML configuration lives in version control - reviewable, repeatable, and recoverable.

Cross-cluster automation with API keys

For organizations running multiple Elasticsearch clusters, the provider now supports cluster API keys for cross-cluster search (CCS) and cross-cluster replication (CCR). You can create API keys specifically designed for secure cross-cluster communication, enabling end-to-end automation of multi-cluster architectures.

This means you can provision two clusters, configure CCS/CCR between them, and set up the necessary security credentials - all in a single Terraform configuration.

resource "elasticstack_elasticsearch_security_api_key" "ccs_key" {
  name = "cross-cluster-search-key"
  type = "cross_cluster"

  access = {
    search = [{
      names = ["logs-*", "metrics-*"]
    }]
    replication = [{
      names = ["archive-*"]
    }]
  }

  expiration = "90d"

  metadata = jsonencode({
    environment = "production"
    purpose     = "ccs-ccr-between-prod-clusters"
    team        = "platform"
  })
}

When the type is set to cross_cluster, the API key is scoped to CCS/CCR operations. You define which index patterns are accessible for search and replication, set an expiration policy, and tag the key with metadata - all reviewable in a pull request.

Learn more about API key resources in the documentation.

AI connectors as code

The provider now supports .bedrock and .gen-ai connectors, bringing AI infrastructure into your Terraform workflows. As teams increasingly integrate large language models into their Elastic workflows - for AI assistants, attack discovery, and automated investigations - managing these connector configurations as code becomes essential.

resource "elasticstack_kibana_action_connector" "bedrock" {
  name              = "aws-bedrock"
  connector_type_id = ".bedrock"
  config = jsonencode({
    apiUrl       = "https://bedrock-runtime.us-east-1.amazonaws.com"
    defaultModel = "anthropic.claude-v2"
  })
  secrets = jsonencode({
    accessKey = var.aws_access_key
    secret    = var.aws_secret_key
  })
}

resource "elasticstack_kibana_action_connector" "openai" {
  name              = "openai"
  connector_type_id = ".gen-ai"
  config = jsonencode({
    apiProvider  = "OpenAI"
    apiUrl       = "https://api.openai.com/v1/chat/completions"
    defaultModel = "gpt-4"
  })
  secrets = jsonencode({
    apiKey = var.openai_api_key
  })
}

With these connectors defined in Terraform, you can version your AI integration configuration alongside the rest of your Elastic infrastructure - and swap models or providers through a simple PR.

Observability enhancements

Synthetics monitors

The elasticstack_kibana_synthetics_monitor resource now includes a labels field, enabling better organization and filtering of synthetic checks. Labels let you tag monitors by team, environment, or service, making it easier to manage synthetic monitoring at scale.

Additional platform improvements

Recent releases also included several resources and attributes that round out the provider's coverage:

• elasticstack_elasticsearch_alias - Manage Elasticsearch aliases as a dedicated resource
• elasticstack_kibana_default_data_view - Set the default data view for a Kibana space
• solution attribute on elasticstack_kibana_space - Configure the solution type for Kibana spaces (available from 8.16)
• Fleet agent policy enhancements - host_name_format for configuring hostname vs. FQDN, and required_versions for version pinning

Getting started

If you're already using the Elastic Stack Terraform provider, upgrade to the latest provider version to get all of these capabilities:

terraform {
  required_providers {
    elasticstack = {
      source  = "elastic/elasticstack"
      version = "~> 0.14"
    }
  }
}

If you're new to managing your Elastic Stack with Terraform, start with the provider documentation on the Terraform registry.

To start using Elastic Cloud today, log in to the Elastic Cloud console or sign up for a free trial.
For the full set of changes, check out the release notes on GitHub.