ghas-report-grunt

ghas-report-grunt turns GitHub Advanced Security alert data into a manager-facing report. It combines deterministic collection and aggregation with a controlled Copilot SDK enrichment pipeline.

What it produces

• report.md: a Markdown report with deterministic tables and short narrative sections.
• report.json: the frozen evidence bundle, generated sections, eval results, challenger findings, judge verdict, and reproducibility metadata.
• report.failed.md / report.failed.json: inspection artifacts when validation blocks the final output.

Pipeline

1. Collect GHAS alerts with REST loaders.
2. Aggregate into a frozen EvidenceBundle.
3. Enrich with Copilot SDK agents and markdown skills.
4. Validate with deterministic checks, challenger, and judge.
5. Render Markdown and JSON.

Agents do not query live GHAS data. Numeric and entity claims must trace to the frozen evidence bundle. The enrichment agent may use a small read-only GitHub MCP allowlist for repository context only.

Install

git clone https://github.com/<your-org>/ghas-report-grunt
cd ghas-report-grunt

uv venv
uv sync --extra dev
cp .env.example .env   # set GITHUB_TOKEN

Use a token with security_events scope, or equivalent fine-grained read permissions for Code Scanning, Dependabot, and Secret Scanning.

Quick start

# Check alert access.
uv run ghas-report-grunt smoke myorg/myrepo

# Deterministic report only.
uv run ghas-report-grunt report myorg/myrepo --output reports/report.md

# Full agentic report.
uv run ghas-report-grunt generate myorg/myrepo \
  --output reports/report.md \
  --json reports/report.json

Useful options:

--mock                         # deterministic mock agent
--agent-timeout 1200           # per-agent SDK wait timeout
--enrichment-model gpt-5.5     # override one role's model for a run
--allow-failed-output          # write final path even when validation failed
--context posture.json         # add product/owner/criticality facts
--template report.md.j2        # custom Markdown layout

Documentation

File	Purpose
docs/usage.md	CLI usage and common workflows
docs/architecture.md	Pipeline, invariants, module map
docs/skills-and-agents.md	Agent roles and skill loading
docs/extending.md	Custom skills, prompts, templates, evals, loaders

References

• advanced-security/secret-validator-grunt
• github/copilot-sdk