AWS Security Hub

Overview

The AWS Security Hub integration imports security findings and compliance results from AWS Security Hub into RegScale. It provides vulnerability management, compliance posture tracking, and OCSF (Open Cybersecurity Schema Framework) format support for standardized security data.

There are two groups of commands:

Findings sync - sync_findings, sync_findings_and_assets and sync_findings_by_plan_field import Security Hub findings as vulnerabilities and issues, optionally with assets and evidence.
Compliance sync (CLI 6.50.0 and later) - sync_securityhub_compliance, sync_securityhub, sync_securityhub_by_plan_field and sync_securityhub_by_component_map assess the standards you have enabled in Security Hub (NIST 800-53 R5 or R4) against a Security Plan's controls and record the results as control assessments.

Command Syntax

# Findings sync
regscale aws sync_findings [OPTIONS]
regscale aws sync_findings_and_assets [OPTIONS]
regscale aws sync_findings_by_plan_field [OPTIONS]

# Compliance sync (assets, findings and control assessments)
regscale aws sync_securityhub_compliance [OPTIONS]
regscale aws sync_securityhub [OPTIONS]
regscale aws sync_securityhub_by_plan_field [OPTIONS]
regscale aws sync_securityhub_by_component_map [OPTIONS]

# Save findings to a local file without syncing
regscale aws findings collect [OPTIONS]

Choosing a Command

I want to...	Use
Import findings into one Security Plan whose assets already exist	`sync_findings`
Import findings into one Security Plan and create the assets they reference	`sync_findings_and_assets`
Send each finding to a different Security Plan, matched by an identifier on the finding	`sync_findings_by_plan_field`
Record PASS/FAIL control assessments for one Security Plan	`sync_securityhub_compliance`
Do assets, findings and control assessments for one Security Plan in a single run	`sync_securityhub`
Do the full pipeline for many Security Plans, matched by a Security Plan field	`sync_securityhub_by_plan_field`
Do the full pipeline for many Security Plans, routed by a resource tag and a `component_id,ssp_id` CSV	`sync_securityhub_by_component_map`
Save Security Hub findings to a JSON file	`regscale aws findings collect`

Pick one path per Security Plan. sync_findings ingests control findings as ordinary findings, while the sync_securityhub* commands handle them only in the compliance stage. Running both against the same Security Plan records a failed control twice.

Basic Usage

Sync All Security Hub Findings

regscale aws sync_findings --regscale-id 123

Sync Findings in OCSF Format

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

Sync Both Native and OCSF Formats

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

Sync Findings with Asset Discovery

regscale aws sync_findings_and_assets --regscale-id 123

Preview Counts Without Syncing

sync_findings and sync_findings_and_assets accept --dry-run (-dr), which discovers item counts without syncing and returns a JSON summary. Use --offset and --limit to split a large sync across parallel jobs.

regscale aws sync_findings --regscale-id 123 --dry-run

Format Options

--format applies to sync_findings.

Native AWS Format (Default)

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

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:

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:

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

Filtering Options

These filters work on every command on this page.

By AWS Account ID

Filter findings by specific AWS account:

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

By Tags

Filter by AWS resource tags (AND logic, all tags must match):

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:

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

Multi-Region Monitoring:

# 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

For the compliance sync commands, feed each Security Plan from one AWS region (or from a Security Hub finding aggregator region). See Region Scope.

Findings Without a Matching Asset

By default, a finding whose asset does not exist in RegScale is skipped. Add --import-all-findings to import it anyway:

regscale aws sync_findings --regscale-id 123 --import-all-findings

Evidence Generation

Link Security Hub findings to compliance controls as evidence with sync_findings:

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

--control-ids takes RegScale control IDs. --generate-evidence and --control-ids are available on sync_findings only. The compliance sync commands collect their own evidence by default; see Evidence Collection for the Compliance Sync.

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`

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:

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

When to Use Separate Commands

# 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

Route Findings to Many Security Plans

sync_findings_by_plan_field pulls Security Hub findings once and sends each finding to the Security Plan it belongs to. Each finding's identifier is read from the location in the finding that you name, then matched against the Security Plan field that you name. There are no defaults for either name, because the same field name can mean different things on different tenants. There is no --regscale-id.

regscale aws sync_findings_by_plan_field \
  --plan-match-field "JCAM ID" \
  --finding-match-source resource-tags \
  --finding-match-field "JCAM ID"

Required options:

--plan-match-field - the Security Plan field that holds the identifier, native or custom (for example Tracking ID or Component IDs)
--finding-match-source - where the identifier lives on the finding: user-defined-fields or resource-tags
--finding-match-field - the UserDefinedFields key or resource tag key that holds the identifier

Optional:

--plan-match-multi-value - the Security Plan field holds a list of identifiers separated by commas or semicolons (a multi-select field works too). Each identifier routes to that plan, for example one ComponentID per component of a system.
--ignore-id-prefix - a prefix that is not part of the identifier, compared without case. With COMP-, a record tagged COMP-1254016 matches a plan listing 1254016. Repeat the option for several prefixes.
--fallback-ssp-id - a Security Plan for records whose identifier matches no plan. Omit it to skip those records.
--region, --profile, --account-id, --tags, --import-all-findings - same meaning as above.

Tip: run regscale aws findings collect first to see which location in your findings your account actually populates, then name that key.

Security Hub Compliance Sync

Four commands turn AWS Security Hub into RegScale assets, findings and control assessments. Use them when you want the standards enabled in Security Hub (for example NIST 800-53) assessed against a Security Plan's controls. They are separate from regscale aws sync_compliance, which is the AWS Audit Manager sync.

Command	What it does
`regscale aws sync_securityhub_compliance`	One Security Plan (`--regscale-id`). Reads Security Hub control findings, maps `Compliance.RelatedRequirements` to controls, and records PASS/FAIL per control as control assessments. Failed controls are submitted as vulnerabilities and the server creates the issues, one per vulnerability. It creates no resource assets (it adds one `AWS::::Account:<id>` asset per AWS account if that account has none) and imports no non-control findings.
`regscale aws sync_securityhub`	One Security Plan (`--regscale-id`). Pulls Security Hub once and runs three stages in order: assets, findings, compliance.
`regscale aws sync_securityhub_by_plan_field`	The same three stages, fanned out to many Security Plans. Each finding's identifier (read from `--finding-match-source` / `--finding-match-field`) is matched against the Security Plan field named by `--plan-match-field`. No `--regscale-id`.
`regscale aws sync_securityhub_by_component_map`	The same three stages, fanned out to many Security Plans by a `component_id,ssp_id` CSV (`--component-map-file`) keyed on a resource tag (`--tag-key`, default `ComponentID`). No `--regscale-id`.

Examples

# One plan, control assessments only
regscale aws sync_securityhub_compliance --regscale-id 42 --region us-east-1

# One plan, assets then findings then compliance
regscale aws sync_securityhub --regscale-id 42 --region us-east-1

# One plan, limited to one account and one tag
regscale aws sync_securityhub --regscale-id 42 --account-id 123456789012 --tags Env=prod

# Many plans, routed per finding by a Security Plan field
regscale aws sync_securityhub_by_plan_field \
  --plan-match-field "JCAM ID" \
  --finding-match-source resource-tags \
  --finding-match-field "JCAM ID"

# Many plans, routed by the ComponentID resource tag and a mapping file
regscale aws sync_securityhub_by_component_map \
  --component-map-file components.csv \
  --region us-east-1

# Same, with a different tag key and a catch-all plan for records that do not route
regscale aws sync_securityhub_by_component_map \
  --component-map-file components.csv \
  --tag-key System \
  --fallback-ssp-id 99

Compliance Sync Options

Options common to all four commands:

Option	Description	Default
`--region`	AWS region to read Security Hub findings from	`$AWS_REGION`, else `us-east-1`
`--session-name`	Name of a cached AWS session (from `regscale aws auth login`)
`--profile`	AWS profile name from `~/.aws/credentials`
`--aws-access-key-id`, `--aws-secret-access-key`, `--aws-session-token`	Explicit AWS credentials (override the profile)
`--account-id`	Only findings from this AWS account ID
`--tags`	Only findings whose resources carry these tags (`key1=value1,key2=value2`, all must match)
`--framework`	`nist800-53r5` or `nist800-53r4`. The framework whose control IDs are read from `Compliance.RelatedRequirements`	`nist800-53r5`
`--create-issues` / `--no-create-issues`	Submit failed controls as vulnerabilities; the server creates the issues	on
`--update-control-status` / `--no-update-control-status`	Update control implementation status from the compliance results	on
`--create-poams`, `-cp`	Mark created issues as POAMs	off
`--import-all-findings`	Import findings even when no matching asset exists. Affects only the findings and assets stages; `sync_securityhub_compliance` accepts it but ignores it	off
`--collect-evidence` / `--no-collect-evidence`	Record the Security Hub results as evidence	on
`--evidence-control-ids`	Comma-separated control IDs to collect evidence for (for example `AC-2,AC-3`). Narrows the evidence only, never the control assessments	every control
`--evidence-frequency`	Days until the Evidence record is due for refresh	`30`
`--max-evidence-per-control`	Most findings kept per control and AWS account in the evidence attachment (`0` keeps every finding)	`100`

Both fan-out commands (sync_securityhub_by_plan_field and sync_securityhub_by_component_map) also take --fallback-ssp-id. sync_securityhub_by_plan_field additionally takes --plan-match-field, --finding-match-source and --finding-match-field (all required), plus --plan-match-multi-value and --ignore-id-prefix, described under Route Findings to Many Security Plans. sync_securityhub_by_component_map takes --component-map-file (required) and --tag-key.

There is no --dry-run on these commands.

Stage Order and Where Control Findings Go

sync_securityhub and both fan-out commands run assets, then findings, then compliance, over a single Security Hub pull (active findings that are not suppressed). Each finding goes to one place:

A control finding (a Security Hub finding that carries Compliance.Status) is handled only by the compliance stage. It is not ingested as an ordinary finding, so a failed control produces one vulnerability and issue, not two.
Any other finding in workflow state NEW or NOTIFIED is handled by the findings stage.
The assets stage creates assets from the resources of those findings and from FAILED control findings. PASSED control findings never create assets.

Controls, Frameworks and Results

--framework is nist800-53r5 (the default) or nist800-53r4; no other framework is supported. The control ID is read from the Compliance.RelatedRequirements entries that start with NIST.800-53.r5 or NIST.800-53.r4 respectively. If the Security Plan's controls look like a non-NIST framework you get a warning and the run continues.

One result is computed per control and AWS account: FAIL if any evaluation FAILED, otherwise PASS if any PASSED. A control with results in several accounts is FAIL if it failed in any one of them, however many others passed. WARNING and NOT_AVAILABLE are inconclusive and produce no assessment and no vulnerability. Failed controls are submitted as vulnerabilities (the server creates the issues one to one) unless you pass --no-create-issues.

Evidence Collection for the Compliance Sync

All four commands keep the Security Hub results as evidence by default, in the same way that regscale aws sync_compliance --collect-evidence does for Audit Manager (which is opt-in). Pass --no-collect-evidence to turn it off.

# Evidence is on by default: this records one Evidence record for plan 42
regscale aws sync_securityhub_compliance --regscale-id 42

# Limit the evidence to two controls and keep up to 500 findings per control and account
regscale aws sync_securityhub_compliance \
  --regscale-id 42 \
  --evidence-control-ids AC-2,AC-3 \
  --max-evidence-per-control 500

# Opt out
regscale aws sync_securityhub_compliance --regscale-id 42 --no-collect-evidence

Because evidence is on by default, every run creates a new Evidence record per plan; a daily schedule adds one per plan per day. Use --no-collect-evidence for runs (or schedules) that should not.

What is recorded. One Evidence record per run per Security Plan, titled AWS Security Hub Evidence - <framework> - <YYYYMMDD_HHMMSS>. Its description summarizes the source, framework, accounts, controls, the failed / inconclusive / passed finding counts and a per-control table (capped at 50 rows). The record is linked to the Security Plan and to every control implementation in the plan that the evidence covers.
The attachment is the unmodified Security Hub findings. A gzipped JSONL file (security_hub_compliance_evidence_<timestamp>.jsonl.gz) with one line per Security Hub control finding: the raw record exactly as Security Hub returned it, wrapped only in a small envelope, {"control_ids": [...], "framework": "...", "finding": {...}}, that gives the control IDs of --framework the finding maps to. The last line is {"summary": {...}} with the counts and anything left out. In a fan-out run each plan's copy of a finding has its Resources narrowed to that plan's resources and is otherwise verbatim.
Pass, fail and inconclusive are all evidence. PASSED, FAILED, WARNING and NOT_AVAILABLE control findings that map to a control of --framework are included, even though only passed and failed drive control status. Non-control findings, and control findings that map only to another framework, are not.
Only the findings pulled are evidence. That is Security Hub findings whose record state is ACTIVE and whose workflow status is not SUPPRESSED, narrowed by --account-id and --tags when you give them.
--max-evidence-per-control keeps at most that many findings per control and AWS account, failed findings first, then WARNING/NOT_AVAILABLE, then passed. What was left out is stated in the Evidence description and in the attachment's final summary line.
Scoped to its own plan. In the fan-out commands each plan's evidence is built from only that plan's findings. A plan that has no control findings gets no Evidence record.
It runs after the assessments. If the evidence cannot be recorded, or the attachment cannot be uploaded, the failure is logged and the command exits non-zero (in a fan-out run that plan is reported failed), but the assessments are kept. Pass --no-collect-evidence if you do not want the run to depend on the evidence step.
A negative --evidence-frequency or --max-evidence-per-control is a usage error.

Mapping File (`sync_securityhub_by_component_map`)

A two-column CSV with a header row:

component_id,ssp_id
744,12
COMP-744,12
COMP-900,15

Matching is exact, after trimming whitespace. COMP-744 and 744 are different component IDs; list each spelling your resources actually carry (as in the example, where both map to plan 12). Case also counts, and so does the --tag-key spelling.
The header must contain component_id and ssp_id (any order; the check is not case-sensitive).
ssp_id must be a positive integer, and a component_id may appear on several lines only if every line names the same plan.
Blank rows are ignored. A file with no mappings is rejected.

The whole file is validated before any call to AWS: a missing header, an empty component_id or ssp_id, a non-integer or non-positive ssp_id, one component mapped to two different plans, and any ssp_id (or --fallback-ssp-id) that does not exist in RegScale are all rejected, and every problem found in the file is reported together.

Keeping Plans Separate

The fan-out commands are built so one plan's data cannot land in another:

Security Hub is queried once; the findings are then split locally.
Each finding is split per resource by the routing tag (or, for --finding-match-source user-defined-fields, kept whole), so a finding spanning resources owned by different systems is divided among their plans.
Control PASS/FAIL is computed per plan from that plan's resources only.
Records with no routing identifier (untagged), or whose identifier matches no plan (unmapped), are skipped and reported, with the identifiers and counts, unless --fallback-ssp-id sends them to a plan you choose. Ambiguous matches in sync_securityhub_by_plan_field (two plans carrying the same identifier) are skipped, never sent to the fallback.
A plan that fails does not stop the others. Within a plan, an exception in one stage skips that plan's remaining stages; the other plans still run.

Exit Status

The command prints a summary of every plan and every skipped record. It exits non-zero if any plan failed (after the remaining plans have run) and zero when records were merely skipped as unmapped, untagged or ambiguous. A rejected mapping file, a missing Security Plan or an unresolvable plan field fails the command before any call to AWS.

Region Scope

Feed each Security Plan from one AWS region (or from a Security Hub finding aggregator region that already consolidates the others). A compliance finding ID carries no region, so an unscoped run against region B sees none of the findings region A reported and its compliance mop-up can close issues that failed only in region A.

A Failed or Partial Fetch Stops the Run

If Security Hub rejects any page of the pull (access denied, an unsubscribed account, throttling that outlasts the retries) the command exits non-zero with the error and writes nothing. It never proceeds on a partial set of findings, because a control whose failed finding sat on the missing page could otherwise be assessed as passing.

Mop-Up (Closing Resolved Issues)

Assets are never mopped up, in any stage of these commands.
The findings stage never mops up issues or vulnerabilities.
The compliance stage mops up issues and vulnerabilities only for an unscoped single-plan run (sync_securityhub_compliance or sync_securityhub without --account-id or --tags), so there a control that now passes can close its issue. The fan-out commands, and any run narrowed with --account-id or --tags, never close issues, because they see only part of the region's control findings. If no control fails at all in a run, existing issues are not closed automatically; close them in RegScale.
The compliance stage uses its own source title, AWS Security Hub Compliance, so its mop-up can never close issues created by the findings stage (source AWS).

Permissions

The commands read Security Hub with securityhub:GetFindings. Security Hub must have the NIST 800-53 standard enabled in the region you pass with --region, or there are no control findings to assess.

What Gets Created in RegScale

1. Vulnerabilities

From Security Hub vulnerability findings, and from failed controls in the compliance sync:

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` or `sync_securityhub*`)

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. Control Assessments (if using `sync_securityhub*`)

PASS/FAIL per control and AWS account, from the NIST 800-53 R5 or R4 control findings
Control implementation status updated from the results (unless --no-update-control-status)
Issues and POAMs for failed controls (unless --no-create-issues; add --create-poams for POAMs)

5. Evidence (if `--generate-evidence` is used with `sync_findings`, or by default with `sync_securityhub*`)

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

Common Use Cases

Use Case 1: Production Security Monitoring

# 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

# FedRAMP ATO compliance findings, with assets created from the findings
regscale aws sync_findings_and_assets \
  --regscale-id 123 \
  --tags ATO=FedRAMP,Boundary=Moderate

Use Case 3: Multi-Account Organization

# 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

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

Use Case 5: Initial Compliance Assessment

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

Use Case 6: NIST 800-53 Control Assessment for One System

# Assets, findings and PASS/FAIL control assessments for Security Plan 42
regscale aws sync_securityhub \
  --regscale-id 42 \
  --region us-east-1 \
  --create-poams

Use Case 7: Many Systems in One AWS Organization

# Route every finding to the Security Plan that owns the resource,
# using the ComponentID resource tag and a component_id,ssp_id CSV
regscale aws sync_securityhub_by_component_map \
  --component-map-file components.csv \
  --region us-east-1 \
  --fallback-ssp-id 99

Command Options Reference

Findings Sync

Option	Applies to	Description	Example
`--regscale-id`	`sync_findings`, `sync_findings_and_assets`	RegScale Security Plan ID (required)	`--regscale-id 123`
`--format`	`sync_findings`	Output format: `native`, `ocsf`, or `both`	`--format ocsf`
`--account-id`	all	Filter by AWS account ID	`--account-id 123456789012`
`--tags`	all	Filter by resource tags	`--tags Env=prod,Team=sec`
`--region`	all	AWS region	`--region us-west-2`
`--generate-evidence`	`sync_findings`	Link findings to controls as evidence	`--generate-evidence`
`--control-ids`	`sync_findings`	RegScale control IDs for evidence	`--control-ids 456,789,101`
`--import-all-findings`	all	Import findings even when no matching asset exists in RegScale	`--import-all-findings`
`--dry-run`, `-dr`	`sync_findings`, `sync_findings_and_assets`	Discover item counts without syncing; returns a JSON summary	`--dry-run`
`--offset`	`sync_findings`, `sync_findings_and_assets`	Skip this many items from the start (for parallel job splitting)	`--offset 500`
`--limit`	`sync_findings`, `sync_findings_and_assets`	Process at most this many items (for parallel job splitting)	`--limit 500`
`--session-name`	`sync_findings`, `sync_findings_and_assets`	Name of a cached AWS session (from `regscale aws auth login`)	`--session-name my-session`
`--profile`	all	AWS profile name	`--profile production`
`--aws-access-key-id`, `--aws-secret-access-key`, `--aws-session-token`	`sync_findings`, `sync_findings_and_assets`	Explicit AWS credentials (override the profile)

Compliance Sync

See Compliance Sync Options for the options shared by sync_securityhub_compliance, sync_securityhub, sync_securityhub_by_plan_field and sync_securityhub_by_component_map.

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

The compliance sync commands assess the NIST 800-53 R5 or R4 standard.

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

With sync_findings, always specify --control-ids to link evidence properly
With the compliance sync, evidence is on by default; use --evidence-control-ids to narrow it and --evidence-frequency 30 for monthly assessments
Generate evidence for key controls (AU, AC, IA, SC families)

4. Choosing the Right Pipeline

Use one pipeline per Security Plan: either sync_findings* or sync_securityhub*, not both
Use the fan-out commands when one AWS account serves many systems
Feed each Security Plan from a single AWS region
Use --no-collect-evidence on schedules that should not create a new Evidence record each run

5. Performance Optimization

Filter by tags to reduce finding volume
Target specific regions to limit API calls
Use --offset and --limit to split a large sync_findings run across parallel jobs
Schedule syncs during off-peak hours

6. Automation

Schedule regular finding syncs:

#!/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

No Control Assessments Created

Cause: The compliance sync found no control findings for the framework.

Solution:

Confirm the NIST 800-53 standard is enabled in Security Hub in the region you pass with --region
Check that --framework matches the revision you enabled (nist800-53r5 or nist800-53r4)
Remember that WARNING and NOT_AVAILABLE results are inconclusive and produce no assessment

The Command Exits Non-Zero but the Assessments Were Saved

Cause: The evidence step failed (the Evidence record could not be created, or its attachment could not be uploaded). Assessments are saved before evidence runs and are kept.

Solution:

Read the logged error, which names the empty Evidence record if one was created
Re-run, or pass --no-collect-evidence if you do not need evidence for this run

Findings Skipped as Unmapped or Untagged

Cause: In a fan-out run, a finding's identifier is missing or matches no Security Plan.

Solution:

Read the summary the command prints; it lists the skipped identifiers and counts
Check the spelling and case of the identifier, and of --tag-key (matching is exact)
Add the identifier to the mapping file or to the Security Plan field, or pass --fallback-ssp-id to send unmatched records to a catch-all plan
Run regscale aws findings collect to confirm which location in your findings actually holds the identifier

Mapping File Rejected

Cause: sync_securityhub_by_component_map validates the whole file before it calls AWS.

Solution:

Make sure the header has component_id and ssp_id
Make sure every ssp_id is a positive integer for a Security Plan that exists
Make sure no component_id maps to two different plans
Every problem found is reported together, so fix them all in one pass

Failed Controls Counted Twice

Cause: sync_findings and a sync_securityhub* command were both run against the same Security Plan.

Solution:

Use one pipeline per Security Plan

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, OR
Add --import-all-findings to import findings that have no matching asset

Duplicate Findings

Cause: Running sync multiple times without deduplication.

Solution:

RegScale automatically deduplicates by finding ID
Check for multiple scheduled jobs

AWS Security Hub

Overview

Command Syntax

Choosing a Command

Basic Usage

Sync All Security Hub Findings

Sync Findings in OCSF Format

Sync Both Native and OCSF Formats

Sync Findings with Asset Discovery

Preview Counts Without Syncing

Format Options

Native AWS Format (Default)

OCSF Format

Both Formats

Filtering Options

By AWS Account ID

By Tags

By Region

Findings Without a Matching Asset

Evidence Generation

Sync Findings with Assets

Understanding the Difference

When to Use sync_findings_and_assets

When to Use Separate Commands

Route Findings to Many Security Plans

Security Hub Compliance Sync

Examples

Compliance Sync Options

Stage Order and Where Control Findings Go

Controls, Frameworks and Results

Evidence Collection for the Compliance Sync

Mapping File (sync_securityhub_by_component_map)

Keeping Plans Separate

Exit Status

Region Scope

A Failed or Partial Fetch Stops the Run

Mop-Up (Closing Resolved Issues)

Permissions

What Gets Created in RegScale

1. Vulnerabilities

2. Issues

3. Assets (if using sync_findings_and_assets or sync_securityhub*)

4. Control Assessments (if using sync_securityhub*)

5. Evidence (if --generate-evidence is used with sync_findings, or by default with sync_securityhub*)

Common Use Cases

Use Case 1: Production Security Monitoring

Use Case 2: Compliance-Focused Assessment

Use Case 3: Multi-Account Organization

Use Case 4: Incident Response Investigation

Use Case 5: Initial Compliance Assessment

Use Case 6: NIST 800-53 Control Assessment for One System

Use Case 7: Many Systems in One AWS Organization

Command Options Reference

Findings Sync

Compliance Sync

Finding Types

AWS Security Hub Built-In Checks

AWS Inspector

AWS GuardDuty

Third-Party Integrations

Best Practices

1. Format Selection

2. Filtering Strategy

3. Evidence Collection

4. Choosing the Right Pipeline

5. Performance Optimization

6. Automation

Troubleshooting

No Findings Returned

No Control Assessments Created

The Command Exits Non-Zero but the Assessments Were Saved

Findings Skipped as Unmapped or Untagged

Mapping File Rejected

Failed Controls Counted Twice

OCSF Format Errors

Missing Assets

Duplicate Findings

When to Use `sync_findings_and_assets`

Mapping File (`sync_securityhub_by_component_map`)

3. Assets (if using `sync_findings_and_assets` or `sync_securityhub*`)

4. Control Assessments (if using `sync_securityhub*`)

5. Evidence (if `--generate-evidence` is used with `sync_findings`, or by default with `sync_securityhub*`)