---
agentTools:
  projectIndex: https://regscale.readme.io/llms.txt
---

# Security Hub

# AWS Security Hub

## Overview

AWS Security Hub integration - `regscale aws sync_findings` - imports security findings and compliance checks from AWS Security Hub into RegScale. This integration provides vulnerability management, compliance posture tracking, and OCSF (Open Cybersecurity Schema Framework) format support for standardized security data.

## Command Syntax

```bash
regscale aws sync_findings [OPTIONS]
regscale aws sync_findings_and_assets [OPTIONS]
```

## Basic Usage

### Sync All Security Hub Findings

```bash
regscale aws sync_findings --regscale-id 123
```

### Sync Findings in OCSF Format

```bash
regscale aws sync_findings \
  --regscale-id 123 \
  --format ocsf
```

### Sync Both Native and OCSF Formats

```bash
regscale aws sync_findings \
  --regscale-id 123 \
  --format both
```

### Sync Findings with Asset Discovery

```bash
regscale aws sync_findings_and_assets --regscale-id 123
```

## Format Options

### Native AWS Format (Default)

Standard AWS Security Hub finding format with all AWS-specific fields:

```bash
regscale aws sync_findings --regscale-id 123
```

**Benefits:**

* Preserves all AWS-specific metadata
* Familiar format for AWS users
* Direct mapping to AWS documentation

### OCSF Format

Open Cybersecurity Schema Framework normalized format:

```bash
regscale aws sync_findings \
  --regscale-id 123 \
  --format ocsf
```

**Benefits:**

* Standardized schema across vendors
* Easier integration with SIEM tools
* Consistent field names and structure
* Better for multi-cloud environments

### Both Formats

Store findings in both formats for maximum flexibility:

```bash
regscale aws sync_findings \
  --regscale-id 123 \
  --format both
```

## Filtering Options

### By AWS Account ID

Filter findings by specific AWS account:

```bash
regscale aws sync_findings \
  --regscale-id 123 \
  --account-id 123456789012
```

### By Tags

Filter by AWS resource tags (AND logic):

```bash
regscale aws sync_findings \
  --regscale-id 123 \
  --tags Environment=production

# Multiple tags
regscale aws sync_findings \
  --regscale-id 123 \
  --tags Environment=production,Team=security,Compliance=required
```

### By Region

Target specific AWS region:

```bash
regscale aws sync_findings \
  --regscale-id 123 \
  --region us-west-2
```

**Multi-Region Monitoring:**

```bash
# Sync multiple regions
regscale aws sync_findings --regscale-id 123 --region us-east-1
regscale aws sync_findings --regscale-id 123 --region us-west-2
regscale aws sync_findings --regscale-id 123 --region eu-west-1
```

## Evidence Generation

Link Security Hub findings to compliance controls as evidence:

```bash
# Generate evidence for specific controls
regscale aws sync_findings \
  --regscale-id 123 \
  --generate-evidence \
  --control-ids 456,789,101
```

**With Evidence Frequency:**

```bash
regscale aws sync_findings \
  --regscale-id 123 \
  --generate-evidence \
  --control-ids 456,789 \
  --evidence-frequency 30
```

## Sync Findings with Assets

### Understanding the Difference

**`sync_findings`** - Imports findings only, assumes assets already exist in RegScale\
**`sync_findings_and_assets`** - Discovers and creates assets from findings, then imports findings

### When to Use `sync_findings_and_assets`

```bash
regscale aws sync_findings_and_assets --regscale-id 123
```

**Use this when:**

* Starting fresh with an empty Security Plan
* You want assets automatically created from findings
* Focusing on compliance-scoped assets only
* Syncing posture management findings (\~1,100 findings)

**With Filtering:**

```bash
regscale aws sync_findings_and_assets \
  --regscale-id 123 \
  --account-id 123456789012 \
  --tags Environment=production
```

### When to Use Separate Commands

```bash
# Step 1: Sync all assets
regscale aws sync_assets --regscale-id 123

# Step 2: Sync all findings
regscale aws sync_findings --regscale-id 123
```

**Use this when:**

* You need comprehensive AWS inventory
* You want all finding types (\~5,500+ findings)
* Assets already exist from previous syncs
* Full security monitoring is required

## What Gets Created in RegScale

### 1. Vulnerabilities

From Security Hub vulnerability findings:

* **CVE Details**: Common Vulnerabilities and Exposures identifiers
* **CVSS Scores**: V2 and V3 scoring information
* **Severity Levels**: CRITICAL, HIGH, MEDIUM, LOW, INFORMATIONAL
* **Affected Resources**: Linked to assets
* **Remediation Guidance**: Fix recommendations and references

### 2. Issues

From Security Hub compliance checks and security issues:

* **Compliance Status**: Pass/Fail from security standards
* **Related Standards**: PCI DSS, CIS, NIST 800-53, etc.
* **Resource Identification**: ARN and resource details
* **Remediation Steps**: Specific fix instructions
* **Severity Rating**: Based on finding severity

### 3. Assets (if using `sync_findings_and_assets`)

* **AWS Resources**: EC2, S3, RDS, Lambda, etc.
* **Asset Metadata**: ARN, type, region, account ID
* **Tags**: Resource tags from AWS
* **Configuration**: Resource-specific details
* **Finding Relationships**: Linked vulnerabilities and issues

### 4. Evidence (if `--generate-evidence` enabled)

* **Findings as Evidence**: Linked to specific controls
* **OCSF Format**: Normalized format (if specified)
* **Attachment**: Finding details and metadata
* **Control Mapping**: Automatic linking to SSP controls

## Common Use Cases

### Use Case 1: Production Security Monitoring

```bash
# Daily security posture monitoring
regscale aws sync_findings \
  --regscale-id 123 \
  --format ocsf \
  --account-id 123456789012 \
  --tags Environment=production,Monitoring=SOC \
  --region us-east-1 \
  --generate-evidence \
  --control-ids 456,789,890 \
  --profile prod-security
```

### Use Case 2: Compliance-Focused Assessment

```bash
# FedRAMP ATO compliance findings
regscale aws sync_findings_and_assets \
  --regscale-id 123 \
  --tags ATO=FedRAMP,Boundary=Moderate \
  --format both \
  --generate-evidence \
  --control-ids 100,101,102
```

### Use Case 3: Multi-Account Organization

```bash
# Account A - Production
regscale aws sync_findings \
  --regscale-id 123 \
  --account-id 111111111111 \
  --tags Environment=production \
  --profile account-a

# Account B - Staging
regscale aws sync_findings \
  --regscale-id 456 \
  --account-id 222222222222 \
  --tags Environment=staging \
  --profile account-b
```

### Use Case 4: Incident Response Investigation

```bash
# Collect all findings for incident investigation
regscale aws sync_findings \
  --regscale-id 123 \
  --account-id 123456789012 \
  --format both \
  --generate-evidence \
  --control-ids 456,789 \
  --force-refresh
```

### Use Case 5: Initial Compliance Assessment

```bash
# First-time assessment with asset discovery
regscale aws sync_findings_and_assets \
  --regscale-id 123 \
  --tags Compliance=Required \
  --format ocsf
```

## Command Options Reference

| Option                 | Description                                | Example                     |
| ---------------------- | ------------------------------------------ | --------------------------- |
| `--regscale-id`        | RegScale Security Plan ID (required)       | `--regscale_id 123`         |
| `--format`             | Output format: `native`, `ocsf`, or `both` | `--format ocsf`             |
| `--account-id`         | Filter by AWS account ID                   | `--account-id 123456789012` |
| `--tags`               | Filter by resource tags                    | `--tags Env=prod,Team=sec`  |
| `--region`             | AWS region                                 | `--region us-west-2`        |
| `--generate-evidence`  | Link findings to controls as evidence      | `--generate-evidence`       |
| `--control-ids`        | RegScale control IDs for evidence          | `--control-ids 456,789,101` |
| `--evidence-frequency` | Evidence timeframe in days                 | `--evidence-frequency 30`   |
| `--force-refresh`      | Bypass cache                               | `--force-refresh`           |
| `--profile`            | AWS profile name                           | `--profile production`      |

## Finding Types

Security Hub aggregates findings from multiple sources:

### AWS Security Hub Built-In Checks

* CIS AWS Foundations Benchmark
* PCI DSS
* AWS Foundational Security Best Practices
* NIST 800-53

### AWS Inspector

* EC2 instance vulnerabilities
* Container image vulnerabilities
* Lambda function vulnerabilities
* Network reachability issues

### AWS GuardDuty

* Threat detections
* Malicious activity
* Unauthorized access attempts
* Compromised instances

### Third-Party Integrations

* Qualys
* Tenable
* Palo Alto Networks
* Trend Micro
* Many others

## Best Practices

### 1. Format Selection

* **Use `ocsf`** for SIEM integration and multi-cloud environments
* **Use `native`** when AWS-specific fields are critical
* **Use `both`** for maximum flexibility during transition periods

### 2. Filtering Strategy

* **Use tags** to define compliance boundaries
* **Filter by account** in multi-account organizations
* **Target regions** where resources are deployed
* **Combine filters** for precise scoping

### 3. Evidence Collection

* Always specify `--control-ids` to link evidence properly
* Use `--evidence-frequency 30` for monthly compliance assessments
* Generate evidence for key controls (AU, AC, IA, SC families)

### 4. Performance Optimization

* Use caching (default 4 hours) - only use `--force-refresh` when needed
* Filter by tags to reduce finding volume
* Target specific regions to limit API calls
* Schedule syncs during off-peak hours

### 5. Automation

Schedule regular finding syncs:

```bash
#!/bin/bash
# Daily Security Hub sync (cron: 0 3 * * *)

regscale aws sync_findings \
  --regscale-id 123 \
  --format ocsf \
  --tags Environment=production \
  --generate-evidence \
  --control-ids 100,101,102
```

## Troubleshooting

### No Findings Returned

**Cause:** No active findings or filters too restrictive.

**Solution:**

* Verify Security Hub is enabled in AWS
* Check findings exist in Security Hub console
* Try without filters: `regscale aws sync_findings --regscale_id 123`
* Verify account-id and tags match resources

### OCSF Format Errors

**Cause:** OCSF conversion issues with certain finding types.

**Solution:**

* Use `--format both` to capture findings in both formats
* Check RegScale logs for specific conversion errors
* Report unsupported finding types to RegScale support

### Missing Assets

**Cause:** Using `sync_findings` without existing assets.

**Solution:**

* Run `regscale aws sync_assets` first, OR
* Use `regscale aws sync_findings_and_assets` to create assets automatically

### Duplicate Findings

**Cause:** Running sync multiple times without deduplication.

**Solution:**

* RegScale automatically deduplicates by finding ID
* Clear cache with `--force-refresh` if needed
* Check for multiple scheduled jobs