Skip to main content
← back to extensions

Aws/securityhub Findings

@webframp/aws/securityhub-findingsv2026.10.23.1· Apache-2.0· 8d agoBEHAVIORSWORKFLOWSREPORTS
01README

Query and manage AWS Security Hub findings from a delegated administrator account. Leverages cross-region aggregation to cover the entire AWS Organization in a single API call.

Complements (does NOT duplicate) the upstream @swamp/aws/securityhub extension which manages Security Hub infrastructure (hubs, rules, policies, controls). This extension focuses on the findings operational lifecycle: query, triage, archive, resolve, and reopen.

Authentication

Uses the default AWS credential chain. Point at the delegated admin account (e.g. via AWS_PROFILE) to query findings across all member accounts.

Required IAM Permissions

  • securityhub:GetFindings (read)
  • securityhub:BatchUpdateFindings (write — for archive/resolve/reopen)

Usage

# Create model (pointed at delegated admin account)
AWS_PROFILE="my-account/ReadOnlyPlus" \
  swamp model create @webframp/aws/securityhub-findings sh-findings --global-arg region=us-east-1

# List all findings from last 24h
swamp model method run sh-findings list_findings --input startTime=24h

# List only HIGH severity GuardDuty findings
swamp model method run sh-findings list_findings --input productName=GuardDuty --input severityLabel=HIGH

# Get severity summary across org
swamp model method run sh-findings get_severity_summary --input startTime=7d

# Archive false positives
swamp model method run sh-findings archive_findings \
  --input 'findingArns=["arn:aws:securityhub:..."]' \
  --input 'note=Known EKS deployment pattern, suppressing'

# Resolve findings
swamp model method run sh-findings resolve_findings \
  --input 'findingArns=["arn:aws:securityhub:..."]' \
  --input 'note=Remediated by disabling public access'

Methods

  • list_findings - Query findings with filters for product, severity, account, time
  • get_finding_details - Get full ASFF details for specific finding ARNs
  • get_severity_summary - Aggregate findings by severity across all accounts
  • archive_findings - Suppress findings (false positive / expected behavior)
  • resolve_findings - Mark findings as resolved
  • reopen_findings - Reopen previously archived/resolved findings
02Release Notes

2026.10.23.1

Fixed: get_severity_summary paged through findings with no sort order. Under its five-page (500-finding) cap, a busy organization could truncate the result to an arbitrary slice, which for a count aggregation undercounts the severity tallies rather than just dropping rows. It now sorts SeverityNormalized descending like every other query, so a truncated summary counts the most severe findings first.

Fixed: list_findings and list_all_findings now encode the sort field and order in their resource instance name. Previously two calls with identical filters but different sorts hashed to the same resource slot, so a second call could silently overwrite a prior truncated slice (e.g. replacing the 100 most severe findings with the 100 oldest) with no signal to any consumer. Sort order is a correctness property under truncation, so it now participates in instance identity.

Added: list_findings and list_all_findings accept optional sortField and sortOrder arguments. sortField is one of SeverityNormalized, SeverityLabel, UpdatedAt, CreatedAt, FirstObservedAt, LastObservedAt, Confidence, Criticality, ProductName, Title, or AwsAccountId; sortOrder is asc or desc. An invalid value is rejected at the swamp boundary rather than surfacing as an opaque AWS error. The override is deliberately absent from get_severity_summary, list_findings_by_type, and diff_findings: those consume the truncated set (diff refuses to diff when truncated), so their severity-descending order is a correctness guarantee, not a preference.

Changed: Every GetFindings query now sorts by severity descending by default.

Upgrade note: Backward compatible. The new arguments are optional and default to the prior severity-descending behavior; existing instances and callers are unaffected and need no changes.

2026.10.21.1

Changed: Documentation only: the README no longer lists environment variables or a static shared-credentials file as a way to supply AWS credentials. It now recommends AWS SSO or a named profile (aws sso login --profile <name>, then --global-arg profile=<name>), or an IAM role attached to where swamp runs. Credential resolution is unchanged: the model still uses the AWS SDK default credential chain when profile is unset.

Upgrade note: No code, schema, or behavioral changes. The model version moves to 2026.10.21.1 with an identity upgrade.

03Behaviors1
@webframp/aws/securityhub-findingsv2026.10.23.1aws/securityhub_findings.ts
fn list_findings()
List Security Hub findings with filters for product, severity, account, and time window
fn get_finding_details()
Get full ASFF details for specific findings by ARN
fn get_severity_summary()
Aggregate findings by severity across all accounts in the organization
fn archive_findings()
Suppress findings (mark as false positive or expected behavior). Sets Workflow.Status to SUPPRESSED with a required note.
fn resolve_findings()
Mark findings as resolved. Sets Workflow.Status to RESOLVED with a required note.
fn reopen_findings()
Reopen previously archived or resolved findings. Sets Workflow.Status to NEW with a required note.
fn list_findings_by_type()
List findings grouped by finding type with severity breakdown per group
fn diff_findings()
Compare current findings with the previous run to identify new and resolved findings
fn resolve_accounts()
Fetch AWS Organizations account list to map account IDs to friendly names
fn list_all_findings()
Paginated full export of findings (up to 500). Fetches multiple pages internally.

Resources

finding_list(30m)— List of Security Hub finding summaries
finding_details(1h)— Full ASFF finding details
severity_summary(30m)— Severity aggregation across accounts
update_result(1h)— Result of a findings workflow status update
findings_by_type(30m)— Findings grouped by finding type
diff_findings(1h)— New and resolved findings since last run
account_map(24h)— AWS Organizations account ID to name mapping
full_export(1h)— Paginated full findings export
04Workflows1
@webframp/securityhub-triage74349b0e-bd34-4ffa-ad2f-b5b1c0baad6a

On-demand Security Hub findings triage workflow. Collects severity summary, critical/high findings, and diff since last run from a single Security Hub delegated admin model instance. Usage: AWS_PROFILE="my-account/ReadOnlyPlus" \ swamp workflow run securityhub-triage --input modelName=sh-findings # Custom time window: AWS_PROFILE="my-account/ReadOnlyPlus" \ swamp workflow run securityhub-triage --input modelName=sh-findings --input startTime=7d

collectCollect findings data from Security Hub
1.severity-summary${{ inputs.modelName }}.get_severity_summary— Get severity counts across all accounts
2.critical-findings${{ inputs.modelName }}.list_findings— List CRITICAL severity findings
3.high-findings${{ inputs.modelName }}.list_findings— List HIGH severity findings
4.diff-findings${{ inputs.modelName }}.diff_findings— Identify new and resolved findings since last run
5.by-type${{ inputs.modelName }}.list_findings_by_type— Group findings by type for pattern analysis
05Reports1
@webframp/securityhub-triage-reportworkflow
security_findings_triage.ts

Aggregates Security Hub triage workflow data into an actionable summary

securitytriagefindings
06Previous Versions18
2026.10.21.1Apache-2.0

2026.10.21.1

Changed: Documentation only: the README no longer lists environment variables or a static shared-credentials file as a way to supply AWS credentials. It now recommends AWS SSO or a named profile (aws sso login --profile <name>, then --global-arg profile=<name>), or an IAM role attached to where swamp runs. Credential resolution is unchanged: the model still uses the AWS SDK default credential chain when profile is unset.

Upgrade note: No code, schema, or behavioral changes. The model version moves to 2026.10.21.1 with an identity upgrade.

2026.10.14.1Apache-2.0(was none)

2026.10.14.1

Added: The manifest now declares license: Apache-2.0 (SPDX). The registry quality rubric scores a declared license separately from the bundled LICENSE.md.

Upgrade note: Metadata only. No code, schema, or behavioral changes.

2026.10.06.1

Changed: Workflow step names are now kebab-case (severity-summary, critical-findings, high-findings, diff-findings, by-type) instead of snake_case, following the direction of swamp-club lab #3060. The triage report matches both forms, so runs recorded before this version still render.

Upgrade note: In a future version the report will be updated to use only the new kebab-case step names, and runs recorded with the old snake_case names will no longer be picked up. Re-run the workflow to produce data under the new names.

2026.09.24.1

Changed: Bump @aws-sdk/* 3.1133.0 → 3.1139.0 (3 packages)

2026.09.18.1

Upgrade note: Normalized npm:zod dependency version to 4.6.5 across the repo. No behavioral changes in this extension.

2026.10.06.1

2026.10.06.1

Changed: Workflow step names are now kebab-case (severity-summary, critical-findings, high-findings, diff-findings, by-type) instead of snake_case, following the direction of swamp-club lab #3060. The triage report matches both forms, so runs recorded before this version still render.

Upgrade note: In a future version the report will be updated to use only the new kebab-case step names, and runs recorded with the old snake_case names will no longer be picked up. Re-run the workflow to produce data under the new names.

2026.09.24.1

Changed: Bump @aws-sdk/* 3.1133.0 → 3.1139.0 (3 packages)

2026.09.18.1

Upgrade note: Normalized npm:zod dependency version to 4.6.5 across the repo. No behavioral changes in this extension.

2026.09.24.1

2026.09.24.1

Changed: Bump @aws-sdk/* 3.1133.0 → 3.1139.0 (3 packages)

2026.09.18.1

Upgrade note: Normalized npm:zod dependency version to 4.6.5 across the repo. No behavioral changes in this extension.

2026.09.18.1

2026.09.18.1

Upgrade note: Normalized npm:zod dependency version to 4.6.5 across the repo. No behavioral changes in this extension.

2026.09.17.1

2026.09.17.1

Changed: Bump @aws-sdk/* 3.1131.0 → 3.1133.0 (3 packages)

2026.09.15.1

Changed: Bump zod 4.4.3 → 4.6.5

2026.09.14.1

Changed: Bump @aws-sdk/* 3.1126.0 → 3.1131.0 (3 packages)

2026.09.04.1

Changed: Bump @aws-sdk/* 3.1121.0 → 3.1126.0 (3 packages)

2026.08.29.1

Changed: Bump @aws-sdk/* 3.1120.0 → 3.1121.0. Dependency-only update; no schema, API, or behavioral changes.

2026.08.28.2

Changed: Normalized the extension license to Apache-2.0 and corrected the copyright holder to "Sean Escriva". Extensions that previously shipped an MIT LICENSE.md are now Apache-2.0, consistent with the repository root and every other extension. No code or behavioral changes.

Upgrade note: License text only. No API, schema, or runtime behavior changed.

2026.08.28.1

Changed: Bump @aws-sdk/* 3.1114.0 → 3.1120.0 (3 packages)

2026.08.26.3

Fixed: Restored inline npm:zod@4.4.3 import specifiers so the registry quality scorer can resolve dependencies and score the extension. An earlier release used a bare "zod" import-map specifier, which published but scored as unscored.

Changed: Retained explicit compilerOptions.strict in deno.json. No behavioral or schema changes.

2026.09.15.1

2026.09.15.1

Changed: Bump zod 4.4.3 → 4.6.5

2026.09.14.1

Changed: Bump @aws-sdk/* 3.1126.0 → 3.1131.0 (3 packages)

2026.09.04.1

Changed: Bump @aws-sdk/* 3.1121.0 → 3.1126.0 (3 packages)

2026.08.29.1

Changed: Bump @aws-sdk/* 3.1120.0 → 3.1121.0. Dependency-only update; no schema, API, or behavioral changes.

2026.08.28.2

Changed: Normalized the extension license to Apache-2.0 and corrected the copyright holder to "Sean Escriva". Extensions that previously shipped an MIT LICENSE.md are now Apache-2.0, consistent with the repository root and every other extension. No code or behavioral changes.

Upgrade note: License text only. No API, schema, or runtime behavior changed.

2026.08.28.1

Changed: Bump @aws-sdk/* 3.1114.0 → 3.1120.0 (3 packages)

2026.08.26.3

Fixed: Restored inline npm:zod@4.4.3 import specifiers so the registry quality scorer can resolve dependencies and score the extension. An earlier release used a bare "zod" import-map specifier, which published but scored as unscored.

Changed: Retained explicit compilerOptions.strict in deno.json. No behavioral or schema changes.

2026.09.04.1

2026.09.04.1

Changed: Bump @aws-sdk/* 3.1121.0 → 3.1126.0 (3 packages)

2026.08.29.1

Changed: Bump @aws-sdk/* 3.1120.0 → 3.1121.0. Dependency-only update; no schema, API, or behavioral changes.

2026.08.28.2

Changed: Normalized the extension license to Apache-2.0 and corrected the copyright holder to "Sean Escriva". Extensions that previously shipped an MIT LICENSE.md are now Apache-2.0, consistent with the repository root and every other extension. No code or behavioral changes.

Upgrade note: License text only. No API, schema, or runtime behavior changed.

2026.08.28.1

Changed: Bump @aws-sdk/* 3.1114.0 → 3.1120.0 (3 packages)

2026.08.26.3

Fixed: Restored inline npm:zod@4.4.3 import specifiers so the registry quality scorer can resolve dependencies and score the extension. An earlier release used a bare "zod" import-map specifier, which published but scored as unscored.

Changed: Retained explicit compilerOptions.strict in deno.json. No behavioral or schema changes.

2026.08.29.1

2026.08.29.1

Changed: Bump @aws-sdk/* 3.1120.0 → 3.1121.0. Dependency-only update; no schema, API, or behavioral changes.

2026.08.28.2

Changed: Normalized the extension license to Apache-2.0 and corrected the copyright holder to "Sean Escriva". Extensions that previously shipped an MIT LICENSE.md are now Apache-2.0, consistent with the repository root and every other extension. No code or behavioral changes.

Upgrade note: License text only. No API, schema, or runtime behavior changed.

2026.08.28.1

Changed: Bump @aws-sdk/* 3.1114.0 → 3.1120.0 (3 packages)

2026.08.26.3

Fixed: Restored inline npm:zod@4.4.3 import specifiers so the registry quality scorer can resolve dependencies and score the extension. An earlier release used a bare "zod" import-map specifier, which published but scored as unscored.

Changed: Retained explicit compilerOptions.strict in deno.json. No behavioral or schema changes.

2026.08.28.2

2026.08.28.2

Changed: Normalized the extension license to Apache-2.0 and corrected the copyright holder to "Sean Escriva". Extensions that previously shipped an MIT LICENSE.md are now Apache-2.0, consistent with the repository root and every other extension. No code or behavioral changes.

Upgrade note: License text only. No API, schema, or runtime behavior changed.

2026.08.28.1

Changed: Bump @aws-sdk/* 3.1114.0 → 3.1120.0 (3 packages)

2026.08.26.3

Fixed: Restored inline npm:zod@4.4.3 import specifiers so the registry quality scorer can resolve dependencies and score the extension. An earlier release used a bare "zod" import-map specifier, which published but scored as unscored.

Changed: Retained explicit compilerOptions.strict in deno.json. No behavioral or schema changes.

2026.08.28.1

2026.08.28.1

Changed: Bump @aws-sdk/* 3.1114.0 → 3.1120.0 (3 packages)

2026.08.26.3

Fixed: Restored inline npm:zod@4.4.3 import specifiers so the registry quality scorer can resolve dependencies and score the extension. An earlier release used a bare "zod" import-map specifier, which published but scored as unscored.

Changed: Retained explicit compilerOptions.strict in deno.json. No behavioral or schema changes.

2026.08.26.3

2026.08.26.3

Fixed: Restored inline npm:zod@4.4.3 import specifiers so the registry quality scorer can resolve dependencies and score the extension. An earlier release used a bare "zod" import-map specifier, which published but scored as unscored.

Changed: Retained explicit compilerOptions.strict in deno.json. No behavioral or schema changes.

2026.08.26.1

2026.08.26.1

Fixed: Added missing description field to upgrade entry for version 2026.08.24.2. The omission caused swamp extension pull to fail with a catalog validation error ("upgrades.N.description: Invalid input: expected string, received undefined").

2026.08.25.1

2026.08.25.1

Changed: Updated labels for improved extension discoverability. Added cross-cutting category labels (security, observability, finops, infrastructure, networking, compliance, devops, ai, incident-response) where applicable.

updated labels

2026.08.24.3

2026.08.24.3

Added: Output metadata attributes for observability.

  • durationMs: Method execution duration in milliseconds.
  • collectedBy: Extension name that produced the data.
  • fetchedAt: ISO 8601 timestamp when data was fetched (added to resources that previously lacked it).
2026.08.24.2

2026.08.24.2

Added: Troubleshooting section documenting cross-region aggregation requirements, single-page list_findings vs paginated list_all_findings, diff_findings truncation suppression, Organizations API region behavior, hardcoded WorkflowStatus: "NEW" filters, write-permission requirements for lifecycle methods, and profile configuration options.

2026.08.21.1

2026.08.21.1

Changed: Security Hub and Organizations API failures now surface with the operation and inputs that were in flight instead of a bare SDK error. Every GetFindings, BatchUpdateFindings, and ListAccounts call across list_findings, get_finding_details, get_severity_summary, list_findings_by_type, diff_findings, resolve_accounts, list_all_findings, and the shared archive/resolve/reopen update path now catches failures and rethrows with the method name, the filters or finding ARNs involved, and the original error preserved as cause. Previously a throttled or permission-denied call would bubble up as a generic AWS SDK exception with no indication of which query or update triggered it.

2026.08.20.1

2026.08.20.1

Changed: Bump @aws-sdk/* 3.1111.0 → 3.1114.0 (3 packages)

2026.08.15.1

Changed: Bump @aws-sdk/* 3.1104.0 → 3.1111.0 (3 packages)

2026.08.05.1

Changed: Bump @aws-sdk/* 3.1101.0 → 3.1104.0 (3 packages)

2026.08.02.1

Changed: Bump @aws-sdk/* 3.1100.0 → 3.1101.0 (3 packages)

2026.08.01.1

Fixed: Broken model-upgrade chain. The prior version bump (to 2026.07.31.1) updated version but left the upgrades array terminating one step short, which blocks swamp extension push ("model upgrade chain errors"). That version never actually published — the registry was still serving 2026.07.30.1. This release closes the chain with a no-op upgrade entry and republishes everything that had accumulated since 2026.07.30.1.

2026.07.31.1

Changed: Bump @aws-sdk/* 3.1096.0 → 3.1100.0 (3 packages)

2026.07.30.1

Added: Optional profile global argument for multi-account credential resolution. When set, credentials resolve via fromIni (supports SSO token cache and shared-config profiles). When omitted, the default credential chain applies as before. Fully backward compatible — no changes required for existing instances.

07Stats
A
100 / 100
Downloads
62
Archive size
293.0 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Docs keep secrets in a vault1/1earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License2/2earned
  • Verified public repository2/2earned
Repository
https://github.com/webframp/swamp-extensions
08Platforms
09Labels
#aws#compliance#findings#incident-response#infrastructure#security#securityhub