# atmos aws compliance report

Generate compliance posture reports against industry frameworks. Retrieves compliance status from AWS Security Hub enabled standards, maps failing controls to Atmos components, and generates reports with remediation guidance.

> ⚠️ Experimental

## Description

The `atmos aws compliance report` command retrieves compliance status from AWS Security Hub enabled standards, maps failing controls to Atmos components that manage the affected resources, and generates reports. It supports multiple compliance frameworks and produces actionable reports that identify exactly which Terraform components need changes to achieve compliance.

Use it for:

- **Compliance Audits**: Generate reports showing your posture against specific compliance frameworks
- **Remediation Planning**: Identify which Atmos components need changes to fix failing controls
- **Multi-Framework Assessment**: Evaluate your infrastructure against multiple standards simultaneously
- **Continuous Compliance**: Integrate into CI/CD pipelines to track compliance drift over time

## Usage

```shell
atmos aws compliance report [flags]
```

## Flags

- **`--stack, -s`**
  Filter compliance results to a specific Atmos stack (e.g., 
  `prod-us-east-1`
  ).
- **`--framework`**
  Compliance framework to evaluate against: 
  `cis-aws`
  , 
  `pci-dss`
  , 
  `soc2`
  , 
  `hipaa`
  , 
  `nist`
  . When omitted, reports on all enabled frameworks.
- **`--format, -f`**
  Output format: 
  `markdown`
  , 
  `json`
  , 
  `yaml`
  , 
  `csv`
   (default: 
  `markdown`
  ).
- **`--file`**
  Write output to a file instead of stdout. Creates parent directories if they don't exist.
- **`--controls`**
  Comma-separated list of specific control IDs to evaluate (e.g., 
  `CIS.1.1,CIS.1.2`
  ).
- **`--identity, -i`**
  Atmos Auth identity for AWS credentials (overrides 
  `aws.security.identity`
   config).
- **`--ai`**
  Enable AI-powered analysis of the compliance report. The global 
  `--ai`
   flag captures the report output and sends it to the configured AI provider for a summary with remediation guidance for each failing control.

## Examples

### Basic Usage

```shell
# CIS AWS Foundations Benchmark report
atmos aws compliance report --framework cis-aws --stack prod-us-east-1

# PCI DSS compliance status
atmos aws compliance report --framework pci-dss

# All frameworks for a stack
atmos aws compliance report --stack prod-us-east-1
```

### Output Formats

```shell
# Output as JSON for automation
atmos aws compliance report --framework cis-aws --format json

# Markdown report for documentation
atmos aws compliance report --framework soc2 --stack prod-us-east-1 --format markdown
```

### AI-Powered Analysis

```shell
# Get AI remediation guidance for failing controls
atmos aws compliance report --ai

# AI analysis for a specific framework
atmos aws compliance report --framework cis-aws --ai
```

### Saving to a File

```shell
# Save markdown report to a file
atmos aws compliance report --framework hipaa --file hipaa-report.md

# Save JSON report to a file
atmos aws compliance report --framework pci-dss --format json --file pci-report.json

# Save to a nested directory (created automatically)
atmos aws compliance report --framework cis-aws --format json --file reports/compliance/cis.json
```

### Targeted Evaluation

```shell
# Check specific controls
atmos aws compliance report --framework cis-aws --controls CIS.1.1,CIS.1.2,CIS.2.1

# NIST framework for production
atmos aws compliance report --framework nist --stack prod-us-east-1

# Multiple stacks comparison
for stack in dev-us-east-1 staging-us-east-1 prod-us-east-1; do
  echo "=== $stack ==="
  atmos aws compliance report --framework cis-aws --stack "$stack" --format json --file "compliance-${stack}.json"
done
```

### CI/CD Integration

```shell
# Compliance gate in pipeline
atmos aws compliance report --framework pci-dss --stack prod-us-east-1 --format json --file compliance.json
if jq -e '.failing_controls | length > 0' compliance.json; then
  echo "PCI DSS compliance failures detected"
  exit 1
fi

# Generate compliance report as a deployment artifact
atmos aws compliance report --stack prod-us-east-1 --file compliance-report.md
```

## Supported Frameworks

- **`cis-aws`**
  CIS AWS Foundations Benchmark. Industry-standard security configuration guidelines for AWS accounts.
- **`pci-dss`**
  Payment Card Industry Data Security Standard. Required for organizations that handle credit card data.
- **`soc2`**
  SOC 2 (Service Organization Control 2). Trust service criteria for security, availability, processing integrity, confidentiality, and privacy.
- **`hipaa`**
  Health Insurance Portability and Accountability Act. Required for organizations handling protected health information (PHI).
- **`nist`**
  NIST 800-53. Security and privacy controls for federal information systems and organizations.

## Configuration

Configure the compliance command in your `atmos.yaml` under the `aws.security` section:

```yaml
aws:
  security:
    enabled: true
    identity: "security-readonly"  # Atmos Auth identity
    region: "us-east-2"            # Security Hub aggregation region
    frameworks:
      - cis-aws
      - pci-dss
```

## Related Commands