Aws Security Hub

---
name: aws-security-hub
description: "Expert agent for AWS Security Hub. Covers finding aggregation from GuardDuty, Inspector, Macie, Config, IAM Access Analyzer, security standards (CIS, PCI DSS, NIST), ASFF format, cross-account/cross-region aggregation, and EventBridge automated response. WHEN: \"AWS Security Hub\", \"Security Hub\", \"ASFF\", \"Security Hub findings\", \"Security Hub standards\", \"Security Hub aggregation\", \"Security Hub EventBridge\", \"AWS security findings\", \"CIS AWS Foundations Security Hub\"."
license: MIT
---

# AWS Security Hub

This skill covers AWS Security Hub — AWS's native security findings aggregation and compliance management service. It has deep knowledge of Security Hub's architecture, finding format (ASFF), security standards, integration with AWS security services, cross-account aggregation, and automated response patterns.

## How to Approach Tasks

When you receive a request:

1. **Classify** the request type:
   - **Setup/Onboarding** -- Cover enabling Security Hub, delegated admin, organizations integration
   - **Finding Management** -- Cover ASFF format, finding filters, suppression, workflow states
   - **Security Standards** -- Cover which standards to enable, compliance scoring, remediation
   - **Integrations** -- Cover enabling GuardDuty, Inspector, Macie, Config, third-party products
   - **Cross-Account/Region** -- Cover aggregation, finding aggregation regions, linked accounts
   - **Automation** -- Cover EventBridge rules, Lambda responses, SOAR integration
   - **Custom Findings** -- Cover BatchImportFindings API for custom integrations

2. **Identify environment** -- Single account or AWS Organizations? Which AWS services are enabled (GuardDuty, Inspector, Macie)? Multi-region? Compliance requirements?

3. **Analyze** -- Apply Security Hub-specific reasoning. Security Hub is a findings aggregator and compliance assessor — not a deep detection or response platform. It aggregates and normalizes findings but the depth comes from the underlying services.

4. **Recommend** -- Provide actionable guidance on maximizing Security Hub value through proper integration setup, standards selection, and automation.

## Core Concepts

### What Security Hub Is (and Isn't)

**Security Hub IS:**
- A central aggregation point for security findings from AWS services and partner products
- A normalized view of findings in ASFF format (no need to parse each service's unique format)
- A compliance assessment engine for security standards (CIS, PCI DSS, NIST)
- A cross-account/cross-region finding consolidation hub
- An integration point for EventBridge-based automated response

**Security Hub IS NOT:**
- A deep threat detection engine (GuardDuty does that)
- A vulnerability scanner (Amazon Inspector does that)
- A CNAPP platform (Wiz, Prisma Cloud do that)
- A SIEM (use Amazon Security Lake + Athena, or a third-party SIEM)
- A log management tool

**Core value:** One place to see all security findings across all AWS services and accounts, normalized into one format, with compliance posture visibility.

### AWS Security Finding Format (ASFF)

ASFF is the standard finding format for Security Hub. All findings — from AWS services and third-party partners — are normalized into ASFF:

**Key ASFF fields:**

```json
{
  "SchemaVersion": "2018-10-08",
  "Id": "arn:aws:securityhub:us-east-1:123456789012:finding/abc123",
  "ProductArn": "arn:aws:securityhub:us-east-1::product/aws/guardduty",
  "GeneratorId": "arn:aws:guardduty:us-east-1:123456789012:detector/def456",
  "AwsAccountId": "123456789012",
  "Types": ["TTPs/Initial Access/UnauthorizedAccess:EC2-SSHBruteForce"],
  "CreatedAt": "2024-01-15T10:30:00Z",
  "UpdatedAt": "2024-01-15T10:30:00Z",
  "Severity": {
    "Label": "HIGH",
    "Normalized": 70,
    "Original": "HIGH"
  },
  "Title": "EC2 instance is being probed on port 22",
  "Description": "...",
  "Resources": [{
    "Type": "AwsEc2Instance",
    "Id": "arn:aws:ec2:us-east-1:123456789012:instance/i-abc123",
    "Region": "us-east-1",
    "Tags": {"Environment": "production"}
  }],
  "Compliance": {
    "Status": "FAILED",
    "RelatedRequirements": ["PCI DSS 1.3.1"]
  },
  "Workflow": {
    "Status": "NEW"
  },
  "RecordState": "ACTIVE"
}
```

**Key ASFF fields explained:**
- `Types`: MITRE ATT&CK taxonomy for the finding (namespace/category/classifier)
- `Severity.Label`: CRITICAL, HIGH, MEDIUM, LOW, INFORMATIONAL
- `Severity.Normalized`: 0-100 numeric score (0=Info, 1-39=Low, 40-69=Medium, 70-89=High, 90-100=Critical)
- `Workflow.Status`: NEW, NOTIFIED, RESOLVED, SUPPRESSED (customer-controlled workflow state)
- `RecordState`: ACTIVE, ARCHIVED (provider-controlled; archived = no longer detected)
- `Compliance.Status`: PASSED, FAILED, WARNING, NOT_AVAILABLE (for standards checks)

### Finding Workflow States

| State | Who Sets It | Meaning |
|---|---|---|
| NEW | Security Hub (automatic) | New finding, not yet reviewed |
| NOTIFIED | Customer | Remediation ticket created / owner notified |
| RESOLVED | Customer | Customer verified remediation complete |
| SUPPRESSED | Customer | Intentionally ignoring (false positive, accepted risk) |

**Note:** `RecordState` is different from `Workflow.Status`. RecordState is set by the finding provider — ARCHIVED means the underlying condition is no longer detected. A finding can be ACTIVE + RESOLVED (customer marked resolved but condition still exists — misconfiguration!).

## Security Standards

### Available Standards

**CIS AWS Foundations Benchmark:**
- CIS AWS Foundations Benchmark v1.2.0
- CIS AWS Foundations Benchmark v1.4.0
- CIS AWS Foundations Benchmark v3.0.0 (latest)
- Most widely used baseline for AWS security hygiene
- Covers: IAM, logging, monitoring, networking, storage

**AWS Foundational Security Best Practices (FSBP):**
- AWS's own security standard
- 300+ controls across all major AWS services
- More comprehensive than CIS (covers more services)
- Continuously updated as AWS adds services
- Good choice for AWS-specific coverage

**PCI DSS:**
- PCI DSS v3.2.1 (older, commonly used)
- Checks AWS resource configurations for payment card data security requirements

**NIST SP 800-53:**
- NIST 800-53 R5 controls mapped to AWS service configurations
- Required for FedRAMP compliance

**AWS Resource Tagging Standard:**
- Checks that required tags are applied to all resources
- Configurable required tag keys and values

### Enabling Standards

**Via Console:**
Security Hub → Security Standards → Enable

**Via AWS CLI:**
```bash
# Enable CIS AWS Foundations Benchmark v3.0.0
aws securityhub batch-enable-standards \
  --standards-subscription-requests '[
    {"StandardsArn": "arn:aws:securityhub:us-east-1::standards/cis-aws-foundations-benchmark/v/3.0.0"}
  ]'

# List all available standards
aws securityhub describe-standards

# List controls for a standard
aws securityhub describe-standards-controls \
  --standards-subscription-arn <subscription-arn>
```

**Disabling individual controls:**
Some controls may not apply to your environment (e.g., specific EC2 requirements if you don't use EC2):
```bash
aws securityhub update-standards-control \
  --standards-control-arn <control-arn> \
  --control-status DISABLED \
  --disabled-reason "Not applicable - organization does not use this service"
```

### Security Score

Security Hub calculates a security score per enabled standard:
- Score = percentage of controls passing across all resources
- Drill down by control, by resource, by account
- Trend over time visible in Security Hub console

## Finding Sources

### AWS Native Integrations

| Service | Finding Types |
|---|---|
| Amazon GuardDuty | Threat detections: unauthorized access, data exfiltration, compromised credentials, crypto mining, recon |
| Amazon Inspector | Vulnerability findings: CVEs in EC2 and Lambda, container image CVEs in ECR, network reachability |
| Amazon Macie | Data security: S3 buckets with PII, unencrypted S3 with sensitive data, public S3 access |
| AWS Config | Config rule evaluation results (non-compliant resources) |
| AWS Firewall Manager | Firewall policy compliance findings |
| IAM Access Analyzer | Cross-account access analyzer findings: public/cross-account resource policies |
| AWS Health | Service Health events affecting security (e.g., exposed IAM credentials) |
| AWS Systems Manager Patch Manager | Patching compliance findings |

**Enabling integrations:**
Each AWS service must be separately enabled and configured. For example, GuardDuty must be enabled before its findings flow to Security Hub.

```bash
# Enable GuardDuty integration with Security Hub (after enabling GuardDuty)
# GuardDuty findings automatically flow to Security Hub when both are enabled in the same region

# Enable Amazon Inspector integration
aws inspector2 enable --resource-types EC2 LAMBDA LAMBDA_CODE
# Inspector findings automatically flow to Security Hub
```

### Third-Party Integrations

Security Hub accepts findings from 70+ partner products in ASFF format. Categories:
- SIEM/SOAR: Splunk, IBM QRadar, Palo Alto Cortex XSOAR
- CNAPP: Wiz, Prisma Cloud, Orca, Lacework, CrowdStrike
- Vulnerability management: Tenable, Qualys, Rapid7
- Container security: Aqua, Sysdig, Trend Micro
- EDR: CrowdStrike Falcon, SentinelOne
- Network: Check Point, Palo Alto Networks

**Accepting findings from a third party:**
```bash
# Enable a partner product integration
aws securityhub enable-import-findings-for-product \
  --product-arn arn:aws:securityhub:us-east-1::product/crowdstrike/crowdstrike-falcon

# The partner product then pushes findings via BatchImportFindings API
```

### Custom Finding Sources

Any system can push findings to Security Hub in ASFF format:

```bash
# Custom finding via BatchImportFindings
aws securityhub batch-import-findings --findings '[
  {
    "SchemaVersion": "2018-10-08",
    "Id": "my-custom-finding-001",
    "ProductArn": "arn:aws:securityhub:us-east-1:123456789012:product/123456789012/default",
    "GeneratorId": "my-custom-scanner",
    "AwsAccountId": "123456789012",
    "Types": ["Software and Configuration Checks/Vulnerabilities/CVE"],
    "CreatedAt": "2024-01-15T10:30:00Z",
    "UpdatedAt": "2024-01-15T10:30:00Z",
    "Severity": {"Label": "HIGH"},
    "Title": "Custom security finding",
    "Description": "Description of the finding",
    "Resources": [{"Type": "AwsEc2Instance", "Id": "arn:aws:ec2:us-east-1:123456789012:instance/i-abc"}]
  }
]'
```

## Cross-Account and Cross-Region Architecture

### AWS Organizations Integration

**Delegated administrator:**
- Designate one account as Security Hub delegated admin (typically the security account)
- All member accounts auto-enrolled in Security Hub
- Admin account sees all findings from all member accounts

```bash
# From Organizations management account
aws securityhub enable-organization-admin-account \
  --admin-account-id 123456789012

# Configure auto-enrollment of new accounts
aws securityhub update-organization-configuration \
  --auto-enable \
  --auto-enable-standards DEFAULT
```

**Finding aggregation:**
- Each region has its own Security Hub instance
- Enable finding aggregation to consolidate findings from multiple regions into one
- Designate one region as the "aggregation region"

```bash
# Enable cross-region aggregation (run from the aggregation region)
aws securityhub create-finding-aggregator \
  --region-linking-mode ALL_REGIONS
  # or: SPECIFIED_REGIONS (specify which regions to link)
```

### Multi-Account Finding Flow

```
Member Account A (us-east-1)
  └── GuardDuty, Inspector, Config findings
        ↓ [Security Hub in us-east-1]
            ↓ [cross-region aggregation]
Admin Account Security Hub (us-east-1, aggregation region)
  └── All findings from all accounts + all regions
        ├── Unified compliance dashboard
        ├── Cross-account finding search and filtering
        └── Centralized EventBridge event bus
```

## Finding Filters and Insights

### Filtering Findings

Security Hub supports complex finding filters:

```bash
# Find all critical findings from GuardDuty in production accounts
aws securityhub get-findings \
  --filters '{
    "SeverityLabel": [{"Value": "CRITICAL", "Comparison": "EQUALS"}],
    "ProductName": [{"Value": "GuardDuty", "Comparison": "EQUALS"}],
    "ResourceTags": [{"Key": "Environment", "Value": "production", "Comparison": "EQUALS"}],
    "WorkflowStatus": [{"Value": "NEW", "Comparison": "EQUALS"}],
    "RecordState": [{"Value": "ACTIVE", "Comparison": "EQUALS"}]
  }' \
  --sort-criteria '[{"Field": "CreatedAt", "SortOrder": "desc"}]'
```

**Filter fields:** `AwsAccountId`, `Region`, `SeverityLabel`, `Type`, `ResourceType`, `ResourceId`, `ProductName`, `WorkflowStatus`, `RecordState`, `ComplianceStatus`, `FirstObservedAt`, `LastObservedAt`, `ResourceTags`

### Insights

Insights are saved filters with aggregations — pre-built or custom views:

**Built-in insights:**
- "Top accounts by count of failed CIS controls"
- "Top resource types with most findings"
- "Findings with most open issues by severity"
- "AMIs that generate the most findings"

**Custom insight:**
```bash
aws securityhub create-insight \
  --name "Critical unresolved findings last 7 days" \
  --filters '{
    "SeverityLabel": [{"Value": "CRITICAL", "Comparison": "EQUALS"}],
    "WorkflowStatus": [{"Value": "NEW", "Comparison": "EQUALS"}],
    "CreatedAt": [{"Start": "2024-01-08T00:00:00Z", "End": "2024-01-15T23:59:59Z", "DateRange": null}]
  }' \
  --group-by-attribute "ResourceId"
```

## Automated Response via EventBridge

### Architecture

```
Security Hub Finding Created/Updated
  ↓
Amazon EventBridge (Security Hub event bus)
  └── Rule: match finding criteria
        └── Target: Lambda function / SNS topic / SQS queue / Step Functions / Systems Manager Automation
```

**Security Hub EventBridge event format:**
```json
{
  "source": "aws.securityhub",
  "detail-type": "Security Hub Findings - Imported",
  "detail": {
    "findings": [{
      "AwsAccountId": "123456789012",
      "Severity": {"Label": "CRITICAL"},
      "Types": ["TTPs/Initial Access/UnauthorizedAccess"],
      "Title": "Finding title",
      "Resources": [{"Type": "AwsEc2Instance", "Id": "..."}]
    }]
  }
}
```

**EventBridge event types from Security Hub:**
- `Security Hub Findings - Imported` — new finding arrived from any source
- `Security Hub Findings - Custom Action` — user-triggered action from console/API
- `Security Hub Insight Results` — insight threshold triggered

### Common Automation Patterns

**Pattern 1: Slack notification on critical findings**
```
EventBridge Rule → SNS Topic → Lambda → Slack Webhook
```

**Pattern 2: Auto-remediate S3 public access**
```
EventBridge Rule (filter: ProductFields.Check = S3.2, Compliance.Status = FAILED)
  → Lambda function
      → boto3: s3.put_public_access_block(Bucket=..., PublicAccessBlockConfiguration={BlockPublicAcls: True, ...})
      → security_hub.batch_update_findings(WorkflowStatus='RESOLVED')
```

**Pattern 3: Create JIRA ticket for new high/critical**
```
EventBridge Rule (Severity.Label in [HIGH, CRITICAL], WorkflowStatus = NEW)
  → Lambda
      → JIRA API: create issue
      → security_hub.batch_update_findings(WorkflowStatus='NOTIFIED', Note='JIRA-1234')
```

**Pattern 4: Systems Manager Automation for EC2 findings**
```
EventBridge Rule (ResourceType = AwsEc2Instance, specific finding type)
  → SSM Automation document
      → Quarantine EC2 (change security group to deny-all)
      → Create snapshot for forensics
      → Notify SOC via SNS
```

### Custom Actions

Custom actions allow manual triggering of automation from the Security Hub console:

```bash
# Create a custom action
aws securityhub create-action-target \
  --name "Send to SOAR" \
  --description "Send selected findings to SOAR platform for investigation" \
  --id "SendToSOAR"

# The custom action generates a CloudWatch Event when triggered
# EventBridge rule matches on detail-type: "Security Hub Findings - Custom Action"
# and detail.actionName = "Send to SOAR"
```

## Finding Suppression

### Suppression Rules

Suppress findings that are false positives, accepted risks, or test findings:

**Suppress by finding filter:**
```bash
aws securityhub create-automation-rule \
  --rule-name "Suppress dev account CIS findings" \
  --rule-order 1 \
  --criteria '{
    "AwsAccountId": [{"Value": "999999999999", "Comparison": "EQUALS"}],
    "ProductName": [{"Value": "Security Hub", "Comparison": "EQUALS"}]
  }' \
  --actions '[{
    "Type": "FINDING_FIELDS_UPDATE",
    "FindingFieldsUpdate": {
      "Workflow": {"Status": "SUPPRESSED"},
      "Note": {"Text": "Dev account - different risk tolerance", "UpdatedBy": "automation"}
    }
  }]'
```

**Automation rules (newer, preferred over older suppression mechanism):**
- More flexible than finding suppression
- Can update any ASFF field, not just workflow status
- Support complex filter logic (AND/OR conditions)
- Can assign severity, add notes, set workflow status

## Key Limitations

**Security Hub is NOT:**
- A real-time detection engine — it aggregates findings from other services
- A log retention tool — findings are retained for 90 days (configurable to 30-90 days)
- A query engine for raw logs — use CloudTrail Lake, Athena, or a SIEM for log queries
- A remediation platform — use EventBridge + Lambda/SSM for automated remediation

**Multi-region complexity:**
- Security Hub must be enabled in every region you want to monitor
- Without finding aggregation, you must check each region's console separately
- Aggregation region consolidates findings but cross-region queries can be slow

**Third-party coverage:**
- Security Hub is best used as the consolidation layer alongside a full CNAPP platform
- A CNAPP (Wiz, Prisma Cloud, Orca) provides deeper analysis; Security Hub provides the AWS-native aggregation layer

## Reference Files

Load this when you need deep architectural knowledge:

- `references/vulnerability-management.md` -- Vulnerability-management-specific angle: CLI quick reference and a vuln-prioritization framing of findings management. Read when the user's intent is vuln scanning/prioritization rather than CSPM posture.