GuardDuty now lets you write custom detection rules and roll them out organization-wide
On September 1, 2026, AWS opened GuardDuty to custom detection rules, associable per account and controllable at the organization level with a dry-run mode and an expiry date. Security teams can now code their own detection scenarios instead of waiting for vendor findings.
September 1, 2026. Twelve new API methods. Amazon GuardDuty opens its detection engine to custom rules, associable per account and deployable organization-wide by the delegated administrator account. DRY_RUN. That is the mode in which a rule can be tested before going LIVE. Why it matters: for years GuardDuty has been a black box producing findings from a closed catalog. It is becoming a programmable detection platform — and the SOC shifts from consuming findings to writing detections.
A black box that opens up
GuardDuty continuously monitors activity across AWS accounts, workloads, and data for malicious or anomalous behavior. Its historical strength has always been zero-tuning: enable the service, let it ingest VPC Flow Logs, CloudTrail events, and DNS logs, and you receive typed findings — credential exfiltration, crypto mining, anomalous behavior. Its limit is the same coin: the detection catalog is defined by AWS, and a scenario that is not in it simply does not exist.
The September 1, 2026 announcement moves that boundary. Custom detection rules let you encode the knowledge of a specific environment — a legacy account that should never touch a given API, an exfiltration pattern unique to one business, an indicator drawn from a past investigation. The rule becomes a code artifact, versionable, testable, and auditable, rather than a hunch dropped into a ticket.
The model: association, organization, expiry
The twelve methods sketch a three-layer model that has to be read as one design.
The account layer manages associating a rule with an account. CreateCustomDetectionRuleAssociation enables a rule with a mode — LIVE or DRY_RUN — and returns an association ID. UpdateCustomDetectionRuleAssociation flips that mode without recreating the association, DeleteCustomDetectionRuleAssociation disables it idempotently, and ListCustomDetectionRuleAssociations enumerates it, filterable by rule or by mode. Every association carries an expiry date (ExpiresAt), which makes time-boxed hunting trivial to bound.
The organization layer replicates the mechanism across the estate. CreateCustomDetectionRuleOrgConfiguration is available only to the delegated administrator account and enables a rule across the whole organization, with two mutually exclusive lists: IncludeAccountIds to target specific accounts, or ExcludeAccountIds to cover everything but a list of exceptions. UpdateCustomDetectionRuleOrgConfiguration, DeleteCustomDetectionRuleOrgConfiguration, GetCustomDetectionRuleOrgConfiguration, and ListCustomDetectionRuleOrgConfigurations complete the lifecycle.
The state layer is the most instructive: a configuration returns a Status of ACTIVE, PROCESSING, or FAILED, with a StatusReason. Propagating a rule across hundreds of accounts is not instantaneous, and the API admits it instead of pretending otherwise.
Why DRY_RUN changes the practice
DRY_RUN is the most important design decision in this release. Writing a detection means accepting the risk of the false positive: a rule too broad floods the SOC, a rule too narrow misses the incident. Historically, you only discovered the tuning in production, after the first massive false-positive.
With DRY_RUN, the rule runs and observes without emitting blocking findings: you measure its trigger rate against real traffic before flipping it to LIVE. The validation loop becomes software-like — a staging environment before production — applied to detection. Combined with automatic expiry, it makes one-off hunts viable: deploy a rule in DRY_RUN, let it mature for a few days, promote it if the signal is clean, and let it expire if it is not.
import boto3
gd = boto3.client("guardduty")
# 1. Test a rule without emitting blocking findings
association = gd.create_custom_detection_rule_association(
RuleId="arn:aws:guardduty:eu-west-1:123456789012:custom-rule/exfil-legacy-iam",
Mode="DRY_RUN",
)
print(association["RuleAssociation"]["AssociationId"])
# 2. Promote it to production once the signal is validated
gd.update_custom_detection_rule_association(
RuleId="arn:aws:guardduty:eu-west-1:123456789012:custom-rule/exfil-legacy-iam",
AssociationId=association["RuleAssociation"]["AssociationId"],
Mode="LIVE",
)Promoting a rule then becomes an act of governance rather than a reflex: it is decided on metrics, with an explicit rollback path back to DRY_RUN if the rule drifts.
What it does not replace
Be clear about the limit. GuardDuty remains a detection engine, not a response engine. Writing a rule that spots an exfiltration pattern only produces a finding; the automation that follows — isolating an instance, revoking keys, opening a ticket — still lives in EventBridge, Lambda, or a SOAR. The value of the announcement is to move the boundary of what is detectable, not of what is handled.
The second limit is operational: a custom rule inherits the same dependency on sources as native findings. If CloudTrail or VPC Flow Logs do not cover the observed zone, the finest rule in the world sees nothing. Programmability of detection does not waive log coverage — it only makes that coverage pay off faster.
None of this makes GuardDuty a substitute for a dedicated detection-engineering practice. The custom rule is only as good as the hypothesis it encodes, and the hypothesis still has to come from somewhere — an investigation, a threat model, a post-mortem. What the API adds is not the intelligence, but the ability to turn it into a persistent, versioned, and measurable control instead of a one-off script that runs once and is forgotten.
Detection as code, at last
The announcement is part of a broader trend: detection as code. Just as infrastructure stopped being clicked in a console to be written in Terraform or Pulumi, detection stops being a console setting to become an artifact versioned in a repository, reviewed in a pull request, and deployed by a pipeline. The benefit is not cosmetic: a rule in Git is auditable, replayable, and reversible, where a setting in the GuardDuty console exists only as a screenshot.
Concretely, the workflow becomes: a rule written in a file, a review by the security team, a DRY_RUN deployment on a subset of accounts, a measurement of the trigger rate, then a LIVE promotion — all triggered by the same CI as the rest of the platform. For a team managing dozens of accounts, that is the only way to keep detection coherent without multiplying manual settings.
Verdict
If you are already on GuardDuty, adopt it in stages: encode your two or three most painful home-grown scenarios first (legacy accounts, known exfiltration patterns, indicators from past investigations), deploy them in DRY_RUN, measure the trigger rate, then promote them to LIVE with an expiry date for one-off hunts. The organization layer is the right scale for a homogeneous rollout — use ExcludeAccountIds for test accounts rather than multiplying manual associations.
If you are not on GuardDuty, the combination of custom rules plus organization-level configuration lowers the adoption bar substantially: you are no longer inheriting only generic findings, you can aim at your specific risks from day one.
If you run a multi-cloud SOC, read this as a market signal: managed detection is converging on openness. The differentiator will soon stop being the ability to detect, and become the quality of the rules a team knows how to write and maintain.