/record-automation-metrics

Record Automation Metrics

Writes reporting-friendly automation metric rows into ./grc-data/metrics/ so /report:automation-coverage has real historical snapshots to compare.

The command always writes these metric IDs:

• automation.coverage_pct
• automation.controls_automated
• automation.controls_manual
• automation.controls_total

Use it in one of three modes:

1. Derived mode for fedramp-low, fedramp-moderate, fedramp-high, or fedramp-20x-ksi, where the toolkit can count automated controls from the evidence collector config. This is a tooling-capability baseline, not proof that your program is already running every automation in production.
2. Manual mode for any framework alias, where you provide the total and automated counts directly. Use this for operator-observed reporting.
3. Batch mode with --config=<path>, where a scheduler can write multiple framework snapshots in one run.

Metric rows follow docs/GRC-DATA.md and schemas/metric.schema.json.

Usage

/grc-engineer:record-automation-metrics <framework> [provider] [options]

Arguments

• $1 - Framework alias or FedRAMP scope
• $2 - Provider in derived mode (optional, defaults to aws)

Common options

• --controls-total=<n> - Required for manual mode unless paired with --controls-manual
• --controls-automated=<n> - Required for manual mode
• --controls-manual=<n> - Optional manual count override
• --recorded-at=<iso8601> - Observation timestamp (defaults to now)
• --window-start=<iso8601> - Optional reporting window start
• --window-end=<iso8601> - Optional reporting window end
• --window-label=<label> - Optional period label like 2026-W16 or current-week
• --dimension=<key=value> - Extra dimensions; may be repeated
• --source=<string> - Optional provenance override
• --out-dir=<path> - Override ./grc-data/metrics/
• --config=<path> - YAML or JSON config for batch mode
• --dry-run - Print rows instead of writing files

Instructions

1. Run the writer directly:

   node plugins/grc-engineer/scripts/record-automation-metrics.js "$ARGUMENTS"
   

   For batch mode, point it at the example config:

   node plugins/grc-engineer/scripts/record-automation-metrics.js \
     --config=plugins/grc-engineer/examples/automation-metrics.yaml \
     --window-label=current-week
   

2. Commit the generated files under ./grc-data/metrics/, or let your CI job publish them into the repo on a schedule.

3. Rerun /report:automation-coverage after you have at least two snapshots seven or more days apart.

Examples

# Derive coverage for FedRAMP Moderate on AWS
/grc-engineer:record-automation-metrics fedramp-moderate aws --window-label=2026-W16

# Derive coverage for FedRAMP 20x on GCP
/grc-engineer:record-automation-metrics fedramp-20x-ksi gcp --window-label=2026-W16

# Record an operator-observed SOC 2 snapshot
/grc-engineer:record-automation-metrics soc2 --controls-total=64 --controls-automated=22 --window-label=2026-W16

# Add an extra business-unit dimension
/grc-engineer:record-automation-metrics iso27001 --controls-total=93 --controls-automated=40 --dimension=business_unit=platform --window-label=2026-W16

# Write multiple snapshots from a config file
/grc-engineer:record-automation-metrics --config=plugins/grc-engineer/examples/automation-metrics.yaml --window-label=current-week