/gap-assessment

/grc-engineer:gap-assessment

Produce a multi-framework gap assessment by joining cached connector findings with the Secure Controls Framework crosswalk (1,468 controls × 249 frameworks).

Usage

/grc-engineer:gap-assessment <frameworks> [options]

Arguments:

• <frameworks> (required): comma-separated list. Use common names or SCF framework IDs.
  • Aliases: SOC2, ISO-27001-2022, NIST-800-53-r5, PCI-DSS-4, FedRAMP-Moderate, FedRAMP-High, CMMC-2, HITRUST-CSF, CIS-v8, HIPAA, GDPR, NYDFS, DORA, Essential-8, IRAP, ISMAP, PBMM, GLBA
  • Or: any SCF framework_id (see curl https://hackidle.github.io/scf-api/api/crosswalks.json | jq '.frameworks[].framework_id')

Options:

• --sources=<csv> — restrict to specific connectors (e.g. aws-inspector,github-inspector). Default: all connectors with cached findings.
• --output=<fmt> — markdown (default), json, sarif, oscal-ar
• --cache-dir=<path> — override ~/.cache/claude-grc/findings
• --report-dir=<path> — where to write the report bundle (default: ./gap-assessment-<run_id>/)
• --refresh — force a fresh collection from each source (delegates to each /<tool>:collect --refresh)
• --offline — use cached SCF data only; skip network
• --quiet — suppress progress output to stderr

What it does

1. Discover sources: scan ~/.cache/claude-grc/findings/<source>/*.json for Findings documents matching schemas/finding.schema.json v1.
2. Validate: every document is checked for schema conformance. Invalid documents are listed in the report under "Data quality warnings" but don't stop the run.
3. Resolve to SCF: each evaluation's (control_framework, control_id) is resolved to one or more SCF control IDs.
4. Expand to requested frameworks: each SCF control is expanded via the forward crosswalk into every framework you requested.
5. Score and tier:
   • Tier 1 (blockers): failing evaluations with severity=critical or severity=high. Resolve before audit.
   • Tier 2 (findings): failing evaluations with severity=medium.
   • Tier 3 (recommendations): failing evaluations with severity=low.
   • Inconclusive: evaluations where the tool couldn't determine status — re-run.
   • Passing: controls satisfied across all evaluated resources.
6. Emit report: markdown by default; JSON, SARIF, or OSCAL Assessment Results available via --output.

How to run this command

When the user invokes /grc-engineer:gap-assessment, run the orchestrator directly:

node plugins/grc-engineer/scripts/gap-assessment.js <frameworks> [options]

The script reads args from argv. Pass through the user's flags unchanged. The script prints the report to stdout and progress/errors to stderr. It also writes a report bundle directory containing:

• gap-report.md (or .json / .sarif / .oscal-ar)
• findings.normalized.json — intermediate canonical form, useful for re-rendering or downstream tooling

Examples

First run — SOC 2 against a GitHub-only environment:

/grc-engineer:gap-assessment SOC2 --sources=github-inspector

Multi-framework optimization scan:

/grc-engineer:gap-assessment SOC2,FedRAMP-Moderate,ISO-27001-2022,NIST-800-53-r5

CI/CD integration (non-interactive):

node plugins/grc-engineer/scripts/gap-assessment.js SOC2,PCI-DSS-4 --output=sarif --quiet > gap.sarif

OSCAL export for a FedRAMP package:

/grc-engineer:gap-assessment FedRAMP-Moderate --output=oscal-ar --sources=aws-inspector

Interpreting the report

The markdown report has six sections:

1. Header — frameworks, sources, SCF version, run ID
2. Coverage table — per-framework evaluated/total, pass rate, failing counts
3. Tier 1 blockers — table of critical/high failures with failing-resource counts
4. Tier 2 findings — medium-severity failures
5. Tier 3 recommendations — low-severity findings
6. Remediation detail — per-Tier-1 finding, the list of failing resources with remediation refs

Remediation refs of the form grc-engineer://generate-implementation/<control>/<cloud> are direct invocations of /grc-engineer:generate-implementation — the tool generates the Terraform, Python, or policy-as-code to fix it.

Exit codes

• 0 — success
• 2 — usage error
• 3 — no cached findings (nothing to assess)
• 4 — no frameworks requested
• 5 — SCF API unreachable and no cache
• 6 — all findings failed validation

Prerequisites

• At least one connector plugin configured and collected. Without cached findings, this command has nothing to assess. Run /<tool>:setup followed by /<tool>:collect first.
• Network access for the first run (SCF data is fetched and cached). Subsequent runs work offline for ~7 days before refresh, or indefinitely with --offline.

Related commands

• /grc-engineer:pipeline-status — which connectors are configured, last-run, cache freshness
• /grc-engineer:map-controls-unified — one control across every framework
• /grc-engineer:optimize-multi-framework — "implement once, satisfy many" ROI analysis
• /grc-engineer:generate-implementation — produce remediation code for a control
• /grc-engineer:monitor-continuous — schedule recurring gap assessments with alerting