Skip to content

Exceptions and policy for IaC

Platform and AppSec teams need two things from an IaC gate: block risky changes, and let a specific, explained, by-design case through without switching the rule off for everyone. agent-bom has one exception model for IaC findings, whichever way the exception is declared, and a policy file that can allow, warn or block by rule, resource and environment.

Every accepted exception:

  • needs a reason;
  • records where it was declared (source and origin), and optionally an owner and an expiry;
  • leaves the active findings and every gate (--fail-on-severity, policy block), but stays in the output: the JSON iac_findings.suppressed list, SARIF suppressions (shown as dismissed in code-scanning UIs), the HTML report and the console summary (N accepted exception(s));
  • stops applying the day after it expires: the finding is active again and the scan prints a warning. Within 14 days of expiry the scan prints a notice.

A malformed exception never suppresses anything. A bad ignore-file entry or policy rule stops the scan before anything is scanned, with an error naming the entry, whether or not the run includes IaC paths; an inline marker with a malformed expires= is reported and not applied.

Where exceptions come from

Source Declared in Who controls it Recorded as
Inline marker the IaC file, on or above the line anyone who can commit the file source: inline, origin: path:line
Ignore file .agent-bom-ignore.yaml or --ignore-file repository owners source: ignore_file, origin: file#entry
Policy allow rule --policy file whoever owns the policy source: policy, origin: policy:name#rule
Tenant exception POST /v1/exceptions, approved by a second admin the platform's admins source: tenant, approved_by

Inline marker

Put the marker on the offending line or the line directly above it. expires= and owner= are optional and come before the reason:

securityContext:
  # agent-bom: ignore[K8S-001] expires=2026-12-31 owner=platform-team node debugger needs host access
  privileged: true

Several rule ids can share a marker: ignore[K8S-001,K8S-006]. A marker with no reason suppresses nothing.

Ignore file

agent-bom iac and agent-bom scan --iac read .agent-bom-ignore.yaml from the working directory, or the file given with --ignore-file. An entry is an IaC entry when it has rule, resource or type: iac, or when its id is an IaC rule id (K8S-001, TF-SEC-012, DOCKER-003, ...). Vulnerability entries in the same file keep working as before.

ignores:
  # One rule, one directory, until a date
  - rule: K8S-001
    path: "deploy/dev/**"
    reason: "Debug pods in dev need privileged mode"
    owner: platform-team
    expires: 2026-12-31

  # One rule on one declared resource
  - rule: K8S-006
    resource:
      kind: Deployment
      name: legacy-batch
      namespace: jobs
      labels: {team: data}
    reason: "Writes scratch files to the root filesystem; tracked in DATA-142"
    expires: 2027-03-31

  # The vulnerability form still works
  - id: CVE-2024-1234
    reason: "Not exploitable: no user input reaches the parser"
Field Required Meaning
rule (or id) yes IaC rule id, or a glob such as K8S-*. A bare * needs a path or resource.
reason yes Why this is accepted. Carried into every export.
path no Glob on the finding's path, relative to the scanned directory or to the working directory.
resource no kind, name, namespace (globs) and labels (all must be present). Matches only findings whose resource the parser knows (Kubernetes manifests and rendered Helm charts); it never matches a finding without one.
expires no YYYY-MM-DD; the exception applies through that day.
owner no Team or person accountable for the exception.

Unknown keys are rejected so a typo cannot quietly widen or disable an entry.

Tenant exceptions (API)

On a self-hosted control plane, IaC exceptions use the same request and four-eyes approval workflow as vulnerability exceptions, scoped to the caller's tenant:

curl -X POST "$AGENT_BOM_URL/v1/exceptions" -H "X-API-Key: $REQUESTER_KEY" \
  -H 'Content-Type: application/json' -d '{
    "iac_rule_id": "K8S-001",
    "iac_path": "deploy/ops/*",
    "iac_resource": {"kind": "Pod", "name": "node-debugger"},
    "reason": "Node debugger needs host access (CAB-1182)",
    "expires_at": "2026-12-31T00:00:00Z"
  }'

curl -X PUT "$AGENT_BOM_URL/v1/exceptions/$ID/approve" -H "X-API-Key: $SECOND_ADMIN_KEY"

An IaC exception needs an exact rule id, a path or resource scope, a reason and a bounded, timezone-aware expiry; the requester cannot approve it. Only approved, unexpired exceptions of the scan's tenant are applied when the API scans a repository, and when the MCP scan tool scans a project directory (the tenant the MCP server is bound to with AGENT_BOM_MCP_TENANT_ID). A revoked or expired one stops applying at the next scan. These repository scans honour inline markers and tenant exceptions; they do not read an ignore file from the scanned repository. If the exception store is unavailable, no tenant exception applies and the scan records a warning.

Policy-as-code for IaC

A policy rule is an IaC rule when it sets "scope": "iac" or any iac_* condition. IaC rules are never evaluated against vulnerabilities, and the existing vulnerability rules are never evaluated against IaC findings.

Condition Matches
iac_rule rule id or glob (K8S-001, K8S-*)
severity_gte CRITICAL, HIGH, MEDIUM, LOW
iac_path glob on the finding's path
iac_resource_kind, iac_resource_name, iac_namespace globs on the declared resource
iac_labels labels the resource must carry
iac_environment the finding's environment (below)

A finding's environment comes from the policy's environments map (path globs per environment) first, then from an environment or env label on the resource. A finding with no environment matches no iac_environment rule, so map every deploy directory you want a rule to cover.

Action Effect
block (or fail) fails the scan (exit 1)
warn reported, does not fail
allow accepts the finding as an exception: needs reason, takes optional owner and expires, and is recorded with source: policy

A block rule with "waivable": false cannot be bypassed from the repository: inline markers, ignore-file entries and policy allow rules that cover a finding it matches are rejected (the scan prints rejected exception), and the finding blocks. Only an approved tenant exception can waive it.

Example: block privileged pods in prod, warn in dev, and accept the dev debug pod explicitly.

{
  "name": "iac-guardrails",
  "environments": {
    "prod": ["deploy/prod/**", "k8s/overlays/prod/**"],
    "dev": ["deploy/dev/**", "k8s/overlays/dev/**"]
  },
  "rules": [
    {
      "id": "no-privileged-prod",
      "description": "Privileged pods are blocked in prod",
      "iac_rule": "K8S-001",
      "iac_environment": "prod",
      "action": "block",
      "waivable": false
    },
    {
      "id": "dev-debugger-ok",
      "iac_rule": "K8S-001",
      "iac_environment": "dev",
      "iac_resource_name": "node-debugger",
      "action": "allow",
      "reason": "Dev node debugger runs privileged by design",
      "owner": "platform-team",
      "expires": "2027-01-31"
    },
    {
      "id": "privileged-dev-warn",
      "description": "Other privileged pods in dev are reviewed",
      "iac_rule": "K8S-001",
      "iac_environment": "dev",
      "action": "warn"
    }
  ]
}
agent-bom iac deploy/ --policy iac-guardrails.json --fail-on-severity high -f sarif -o iac.sarif

Reading the result

"iac_findings": {
  "total": 5,
  "findings": [ ... active findings, the only ones gates see ... ],
  "suppressed": [
    {
      "rule_id": "K8S-001",
      "file_path": "dev/pod.yaml",
      "resource": {"kind": "Pod", "name": "node-debugger", "namespace": "dev", "labels": {}},
      "suppressed": true,
      "suppression": {
        "state": "accepted_risk",
        "reason": "Debug pods in dev need privileged mode",
        "source": "ignore_file",
        "origin": ".agent-bom-ignore.yaml#1",
        "owner": "platform-team",
        "expires": "2026-12-31",
        "expiring_soon": false,
        "approved_by": null,
        "exception_id": "iacx-..."
      }
    }
  ],
  "exceptions": {"accepted": 1, "expired": 0, "expiring_soon": 0, "invalid": 0, "rejected": 0,
                 "by_source": {"ignore_file": 1}, "notices": []},
  "policy": {"policy_name": "iac-guardrails", "failures": [], "warnings": [], "allowed": [], "passed": true}
}

Use --verbose on the console to list each accepted exception with its reason, owner and expiry.

Security notes

Exceptions are a place to hide risk, so the design keeps them auditable:

  • no exception without a reason, and nothing malformed is ever applied;
  • every accepted finding stays in JSON, SARIF and HTML with who/where/why/until;
  • expiry is enforced on every scan, not only when someone remembers;
  • waivable: false keeps a repository author from waiving an org rule in code;
  • tenant exceptions need a second admin, an exact rule and scope, and a bounded expiry, and every read and write is scoped to the caller's tenant.

See also: Cloud Posture and IaC Gates, Policy Engine.