Configuration

Customize StackSage audit behavior with a stacksage.yml file in your repository root.

Quick Start

Create a stacksage.yml file in your repository root:

# Create a stacksage.yml in your working directory
cat > stacksage.yml << 'EOF'
# StackSage configuration — all settings are optional

exclusions:
  tags:
    - key: stacksage:ignore
      value: "true"

thresholds:
  ebs:
    unattached_days: 7
  nat_gateway:
    idle_threshold_gb_per_day: 1.0

reporting:
  min_savings_usd: 0
EOF

All configuration settings are optional. StackSage uses sensible defaults if no config file is present.

Configuration Sections

Exclusions

Skip specific resources, regions, or entire detector types:

exclusions:
  # Skip specific resource IDs
  resources:
    - vol-abc123  # Intentional idle volume for disaster recovery
    - nat-xyz789  # NAT gateway for staging environment
  
  # Skip resources with specific tags
  tags:
    - key: stacksage:ignore
      value: "true"
    - key: environment
      value: development
  
  # Skip entire regions
  regions:
    - us-west-1  # Disaster recovery region
  
  # Disable specific detectors
  detectors:
    - ec2_generation_upgrade  # Hardware roadmap planned
    - gp2_to_gp3_migration    # Migration in Q3

Tip: Use exclusions to suppress known findings that you've consciously decided not to address, reducing noise in your reports.

Thresholds

Adjust detection sensitivity for your environment:

thresholds:
  ebs:
    unattached_days: 14           # Default: 7
    performance_utilization: 0.15  # Default: 0.20 (20%)
  
  nat_gateway:
    idle_threshold_gb_per_day: 0.5  # Default: 1.0
  
  lambda:
    low_invocation_threshold: 5  # Default: 10 per day
  
  rds:
    low_connection_count: 5  # Default: 10 connections
  
  elb:
    idle_request_threshold_per_day: 5.0  # Default: 10.0
    min_days_old: 14  # Only check resources >14 days old
  
  lb:
    min_days_old: 14  # Default: 7
  
  severity:
    high_cost_threshold: 100  # Findings ≥$100/mo = high severity
    medium_cost_threshold: 25  # Findings ≥$25/mo = medium

Reporting Filters

Control what appears in final reports:

reporting:
  # Only show findings with savings ≥ this amount
  min_savings_usd: 10  # Default: 0
  
  # Only show these severity levels (empty = show all)
  severity_filter:
    - critical
    - high
  
  # Finding types to include (empty = show all)
  finding_types:
    - cost_optimization
    - security
    - performance

Tag Governance

Define required tags and cost allocation rules:

tag_governance:
  required_tags:
    - Name
    - Environment
    - Owner
    - CostCenter
  
  cost_allocation_tags:
    - CostCenter
    - Project
    - Team
  
  audit_tag_filters:
    - key: Compliance
      values:
        - SOC2
        - HIPAA

Common Patterns

Progressive Rollout

Start with high thresholds and gradually tighten as you address findings:

# Week 1: Focus on high-impact items only
reporting:
  min_savings_usd: 50
  severity_filter: [critical, high]

# Week 4: Lower threshold as you address findings
reporting:
  min_savings_usd: 20
  severity_filter: [critical, high, medium]

Team-Specific Audits

Use tag-based exclusions for different teams:

# Only audit infrastructure team resources
exclusions:
  tags:
    - key: Team
      value: application
    - key: Team
      value: data-science

Environment-Based Rules

Skip development resources, focus on production:

exclusions:
  tags:
    - key: Environment
      value: development
    - key: Environment
      value: staging

thresholds:
  # More aggressive for production
  ebs:
    unattached_days: 3
  nat_gateway:
    idle_threshold_gb_per_day: 0.1