Skip to main content

Security Configuration

The aws.security section configures security scanning and compliance reporting for AWS resources. It controls which AWS security services to query, severity filters, resource-to-component tag mapping, and compliance frameworks.

Experimental

Quick Start​

atmos.yaml

aws:
  security:
    enabled: true
    identity: "security-readonly"  # Atmos Auth identity → Security Hub delegated admin
    region: "us-east-2"            # Security Hub aggregation region

This enables security scanning with Atmos Auth credentials targeting the Security Hub delegated admin account. Default sources: Security Hub, Config, Inspector, GuardDuty. Default severity: CRITICAL and HIGH.

Full Configuration​

atmos.yaml

aws:
  security:
    enabled: true

    # Atmos Auth identity for AWS credentials (targets delegated admin account).
    identity: "security-readonly"

    # Default AWS region (Security Hub aggregation region).
    region: "us-east-2"

    # AWS security services to query
    sources:
      security_hub: true       # AWS Security Hub (aggregates all services)
      config: true             # AWS Config compliance rules
      inspector: true          # Amazon Inspector vulnerability scans
      guardduty: true          # Amazon GuardDuty threat detection
      macie: false             # Amazon Macie sensitive data findings
      access_analyzer: false   # IAM Access Analyzer

    # Default severity filter (when --severity flag is not specified)
    default_severity:
      - CRITICAL
      - HIGH

    # Maximum findings per analysis run
    max_findings: 500

    # Tag keys for mapping AWS resources to Atmos components
    tag_mapping:
      stack_tag: "atmos:stack"
      component_tag: "atmos:component"
    # Account names are resolved automatically via AWS Organizations DescribeAccount API.
    # If account_map is configured, it takes priority (no API call for matched IDs).
    # Use account_map only if Organizations access is unavailable.
    # account_map:
    #   "123456789012": "prod"
    #   "234567890123": "security"

    # Compliance frameworks to track
    frameworks:
      - cis-aws
      - pci-dss

Settings Reference​

enabled
Enable AWS security and compliance features. Default: false.
identity
Atmos Auth identity for AWS credentials. Targets the account where Security Hub is the delegated administrator. Overridable with --identity / -i flag. See Auth Configuration for identity setup.
region
Default AWS region for Security Hub queries (typically the finding aggregation region). Overridable with --region flag. Default: us-east-1.
sources
Configure which AWS security services to query for findings. See Sources below.
default_severity
Default severity filter when --severity flag is not specified. Valid values: CRITICAL, HIGH, MEDIUM, LOW, INFORMATIONAL. Default: ["CRITICAL", "HIGH"].
max_findings
Maximum findings per analysis run. Controls the number of findings fetched from AWS. Default: 500.
tag_mapping
Tag keys used for mapping AWS resources back to Atmos components and stacks. See Tag Mapping below.
account_map
Optional static mapping of AWS account IDs to names. When configured, matched account IDs are resolved from this map without AWS API calls. For unmatched IDs, the system falls back to the AWS Organizations DescribeAccount API. Use this when Organizations access is unavailable or to override specific account names. Example: "123456789012": "prod".
frameworks
Compliance frameworks to track with atmos aws compliance report. Supported: cis-aws, pci-dss, soc2, hipaa, nist.

Sources​

AWS Security Hub acts as a central aggregator for findings from multiple AWS security services. Each source can be enabled or disabled independently.

security_hub
Query AWS Security Hub for aggregated findings from all integrated services. This is the primary source and should usually be enabled. Default: true.
config
Query AWS Config for configuration compliance rule evaluations. Detects resources that don't comply with your Config rules. Default: true.
inspector
Query Amazon Inspector for automated vulnerability assessments of EC2 instances, Lambda functions, and container images. Default: true.
guardduty
Query Amazon GuardDuty for intelligent threat detection findings. Identifies malicious activity and unauthorized behavior. Default: true.
macie
Query Amazon Macie for sensitive data discovery findings in S3 buckets. Useful for data classification and privacy compliance. Default: false.
access_analyzer
Query IAM Access Analyzer for findings about resources shared with external entities. Helps identify unintended public or cross-account access. Default: false.

Tag Mapping​

Atmos maps AWS resources to components and stacks using resource tags. These tags should be applied to your AWS resources via Terraform. The default tags follow Atmos conventions.

stack_tag
Tag key identifying the Atmos stack. Default: "atmos:stack".
component_tag
Tag key identifying the Atmos component. Default: "atmos:component".

How Tag Mapping Works​

When a security finding is detected on an AWS resource, Atmos looks up the resource's tags to determine which component and stack manage it. This enables targeted remediation guidance.

If tags are not found, Atmos falls back to heuristic mapping using resource naming conventions and resource type patterns.

example

# Ensure your Terraform components apply Atmos tags
# In your component's main.tf:
# tags = {
#   "atmos:stack"     = var.atmos_stack
#   "atmos:component" = var.atmos_component
# }

Compliance Frameworks​

The frameworks list determines which compliance standards are reported by atmos aws compliance report.

cis-aws
CIS AWS Foundations Benchmark. Industry-standard security configuration guidelines.
pci-dss
Payment Card Industry Data Security Standard. Required for organizations handling credit card data.
soc2
SOC 2 Trust Service Criteria. Security, availability, processing integrity, confidentiality, and privacy.
hipaa
Health Insurance Portability and Accountability Act. Required for protected health information (PHI).
nist
NIST Cybersecurity Framework. Voluntary framework for managing cybersecurity risk.

AI-Powered Analysis​

By default, atmos aws security analyze works without any AI provider. To enable AI-powered root cause analysis and remediation guidance, use the --ai flag:

shell

atmos aws security analyze --stack prod-us-east-1 --ai

This requires an AI provider to be configured in the ai section of atmos.yaml. See AI Configuration for setup.