Exclusions & Filters

Suppress known findings you've consciously decided not to address — keeping your reports focused on actionable waste.

Overview

Exclusions are defined in stacksage.yml and applied before findings are surfaced in the report. Four types of exclusion are supported: by resource ID, by tag, by region, and by detector type.

Exclude by Resource ID

Skip specific AWS resources by their ID:

exclusions:
  resources:
    - vol-abc123        # Intentional idle volume for disaster recovery
    - nat-xyz789        # NAT gateway for staging environment
    - i-0123456789abcd  # Bastion host — always on by design

Exclude by Tag

Skip any resource that has a matching tag key/value pair. Useful for excluding entire environments or teams:

exclusions:
  tags:
    - key: stacksage:ignore
      value: "true"           # Opt-out tag on individual resources
    - key: Environment
      value: development      # Ignore all dev resources
    - key: Environment
      value: staging

Tip: Add a stacksage:ignore: "true" tag directly on any AWS resource to permanently exclude it without touching stacksage.yml.

Exclude by Region

Skip entire AWS regions — useful for DR regions or regions with no active workloads:

exclusions:
  regions:
    - us-west-1       # Disaster recovery region
    - ap-northeast-2  # Unused region

Disable Specific Detectors

Turn off an entire detection category when it doesn't apply to your environment:

exclusions:
  detectors:
    - ec2_generation_upgrade   # Hardware roadmap already planned
    - gp2_to_gp3_migration     # Migration scheduled for Q3
    - nat_gateway              # NAT gateways are required by policy

Reporting Filters

In addition to exclusions, you can filter what appears in the final report without suppressing the underlying finding:

reporting:
  min_savings_usd: 10       # Only show findings with ≥$10/mo savings
  severity_filter:
    - critical
    - high                  # Omit medium/low from report
  finding_types:
    - cost_optimization     # Only show cost findings (omit security)

Full example

exclusions:
  resources:
    - vol-abc123
  tags:
    - key: stacksage:ignore
      value: "true"
    - key: Environment
      value: development
  regions:
    - us-west-1
  detectors:
    - gp2_to_gp3_migration

reporting:
  min_savings_usd: 10
  severity_filter: [critical, high, medium]