# atmos aws security analyze

Analyze AWS security findings from Security Hub, Config, Inspector, and GuardDuty, then map them to the Atmos components and stacks that manage the affected resources. Generates remediation reports with optional AI-powered analysis.

> ⚠️ Experimental

## Description

The `atmos aws security analyze` command connects to AWS security services via Atmos Auth, retrieves security findings, and maps them to the Terraform/Atmos components that manage the affected resources. By default, it works without any AI provider. When the `--ai` flag is passed, it uses the configured AI provider to analyze each finding and generate remediation guidance with concrete code changes.

Use it for:

- **Security Posture Review**: Get a prioritized view of security findings mapped to your Atmos components and stacks
- **Remediation Planning**: Use `--ai` for AI-generated code changes to fix security issues in your Terraform components
- **CI/CD Integration**: Export findings as JSON or CSV for automated security gates in deployment pipelines
- **Compliance Reporting**: Filter findings by severity, source, or compliance framework for targeted reports

## Usage

```shell
atmos aws security analyze [flags]
```

## Flags

- **`--stack, -s`**
  Filter findings to a specific Atmos stack (e.g., 
  `prod-us-east-1`
  ).
- **`--component, -c`**
  Filter findings to a specific Atmos component (e.g., 
  `vpc`
  , 
  `eks`
  ).
- **`--severity`**
  Comma-separated list of severity levels (case-insensitive): 
  `CRITICAL`
  , 
  `HIGH`
  , 
  `MEDIUM`
  , 
  `LOW`
  , 
  `INFORMATIONAL`
  . Default: 
  `critical,high`
  .
- **`--source`**
  Filter findings by source service: 
  `security-hub`
  , 
  `config`
  , 
  `inspector`
  , 
  `guardduty`
  , 
  `macie`
  , 
  `access-analyzer`
  , 
  `all`
   (default: 
  `all`
  ).
- **`--format, -f`**
  Output format: 
  `markdown`
  , 
  `json`
  , 
  `yaml`
  , 
  `csv`
  , 
  `sarif`
  , 
  `ocsf`
   (default: 
  `markdown`
  ). 
  `sarif`
   emits a SARIF 2.1.0 document compatible with GitHub code scanning and other SARIF viewers. 
  `ocsf`
   emits OCSF 1.4.0 Detection Findings (cloud + vulnerability profiles) for ingestion into SIEM and security data lake platforms — Splunk, Elastic, Sumo Logic, Panther, Snowflake.
- **`--file`**
  Write output to a file instead of stdout. Creates parent directories if they don't exist.
- **`--max-findings`**
  Maximum number of findings to retrieve and analyze (default: 
  `500`
  ). Set to 
  `0`
   to fetch 
  **all**
   matching findings — recommended when exporting to 
  `--format json`
  , 
  `sarif`
  , or 
  `ocsf`
   so downstream tooling (SIEM, dashboards) sees complete data. When the limit is reached and more findings exist, a warning is logged so truncation is never silent.
- **`--ai`**
  Enable AI-powered analysis and remediation suggestions. Requires 
  `ai.enabled: true`
   in your 
  `atmos.yaml`
  .
- **`--region`**
  AWS region to query for findings (overrides 
  `aws.security.region`
   config).
- **`--identity, -i`**
  Atmos Auth identity for AWS credentials (overrides 
  `aws.security.identity`
   config).
- **`--framework`**
  Filter findings by compliance framework (e.g., 
  `cis-aws`
  , 
  `pci-dss`
  ).
- **`--no-group`**
  Disable grouping of duplicate findings. By default, findings with the same title are collapsed into a summary table. Use 
  `--no-group`
   to show each finding individually with full tags — useful for AI pipelines and detailed analysis.

## Examples

### Basic Usage

```shell
# Analyze findings for a specific stack
atmos aws security analyze --stack prod-us-east-1

# Filter by severity
atmos aws security analyze --stack prod-us-east-1 --severity critical,high

# Filter by source service
atmos aws security analyze --stack prod-us-east-1 --source security-hub
```

### AI-Powered Analysis

```shell
# Enable AI analysis for remediation guidance
atmos aws security analyze --stack prod-us-east-1 --ai

# AI analysis for critical findings only
atmos aws security analyze --stack prod-us-east-1 --severity critical --ai
```

### Output Formats

```shell
# Output as JSON for CI/CD integration
atmos aws security analyze --stack prod-us-east-1 --format json

# Output as CSV for compliance reporting
atmos aws security analyze --format csv > findings.csv

# Markdown report for documentation
atmos aws security analyze --stack prod-us-east-1 --format markdown --severity critical,high

# SARIF 2.1.0 for GitHub code scanning, Defender, and SARIF viewers
atmos aws security analyze --stack prod-us-east-1 --format sarif --file findings.sarif

# OCSF 1.4.0 Detection Findings for SIEM / security data lake ingestion
atmos aws security analyze --stack prod-us-east-1 --format ocsf --file findings.ocsf.json
```

### Filtering and Targeting

```shell
# Findings for a specific component
atmos aws security analyze --stack prod-us-east-1 --component vpc

# Limit number of findings
atmos aws security analyze --stack prod-us-east-1 --max-findings 20

# Filter by compliance framework
atmos aws security analyze --stack prod-us-east-1 --framework cis-aws
```

### Saving to a File

```shell
# Save markdown report to a file
atmos aws security analyze --stack prod-us-east-1 --file security-report.md

# Save JSON findings to a file
atmos aws security analyze --stack prod-us-east-1 --format json --file findings.json

# Save to a nested directory (created automatically)
atmos aws security analyze --stack prod-us-east-1 --format json --file reports/security/findings.json
```

### CI/CD Integration

```shell
# Security gate in pipeline
atmos aws security analyze --stack prod-us-east-1 --severity critical --format json --file security.json
if jq -e '.findings | length > 0' security.json; then
  echo "Critical security findings detected"
  exit 1
fi

# Generate security report as a deployment artifact
atmos aws security analyze --stack prod-us-east-1 \
  --severity critical,high \
  --file security-report.md
```

## Configuration

Configure the security 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
    default_severity:
      - CRITICAL
      - HIGH
    sources:
      security_hub: true
      inspector: true
      guardduty: true
    max_findings: 50
    tag_mapping:
      stack_tag: "atmos:stack"
      component_tag: "atmos:component"
    account_map:                   # For account-level findings
      "123456789012": "prod"
      "234567890123": "security"
```

To enable AI-powered analysis with the `--ai` flag, also configure your AI provider:

```yaml
ai:
  enabled: true
  default_provider: bedrock
  providers:
    bedrock:
      model: anthropic.claude-sonnet-4-6-20250514-v1:0
      base_url: us-east-1
```

## Related Commands