ghqr-report

name	ghqr-report
description	Generate an executive assessment report from GitHub Quick Review (ghqr) scan data. Produces an executive summary, a dedicated section per validated subject with all findings, and a prioritized 30/60/90-day remediation plan. Use when the user asks for a report, executive summary, best practices posture overview, or a remediation roadmap from ghqr scan results.

GitHub Quick Review — Executive Report Skill

Expert guidance for transforming ghqr scan JSON output into a structured executive report with findings by category and a prioritized 30/60/90-day remediation plan.

Overview

This skill enables agents to:

• Trigger a ghqr scan (or consume an existing scan result) for an enterprise, organization, or repository
• Produce a polished executive summary with overall best practices posture and key KPIs
• Generate one dedicated section per validated category with its issues and recommendations
• Build a prioritized remediation roadmap split into 30, 60, and 90-day milestones

When to Use This Skill

Trigger this skill when the user asks for:

• "Generate a report", "executive report", "best practices report", or "posture report"
• "Remediation plan", "action plan", "30/60/90 plan"
• "What are the findings from the ghqr scan?"
• "Show me the issues and how to fix them"

Data Sources

The ghqr JSON output contains the following top-level structure:

{
  "generated_at": "<RFC3339 timestamp>",
  "summary": { "total_scanned": N, "non_compliant": N, "by_severity": {} },
  "enterprises": {
    "<slug>": {
      "ghas_settings": {
        "advanced_security": "enabled|disabled|not_set",
        "secret_scanning": "enabled|disabled|not_set",
        "secret_scanning_push_protection": "enabled|disabled|not_set",
        "dependabot_alerts": "enabled|disabled|not_set",
        "dependabot_security_updates": "enabled|disabled|not_set",
        "dependency_graph": "enabled|disabled|not_set",
        "secret_scanning_non_provider_patterns": "enabled|disabled|not_set"
      },
      "evaluation": { "recommendations": [] }
    }
  },
  "organizations": {
    "<name>": {
      "settings": {
        "security": {
          "advanced_security_enabled_for_new_repos": true,
          "secret_scanning_enabled_for_new_repos": true,
          "secret_scanning_push_protection_enabled_for_new_repos": true,
          "dependabot_alerts_enabled_for_new_repos": true,
          "dependabot_security_updates_enabled_for_new_repos": true,
          "dependency_graph_enabled_for_new_repos": true
        }
      },
      "evaluation": { "recommendations": [] }
    }
  },
  "repositories":  { "<owner/name>": { "evaluation": { "recommendations": [] } } }
}

Each evaluation object contains:

• recommendations[]: all findings (both hard issues and advisory items), each with severity, category, issue, recommendation, and an optional learn_more URL

Severity Levels

Severity	Meaning
critical	Immediate risk, must fix now
high	Serious gap, fix within 30 days
medium	Important improvement, fix within 60 days
low	Minor gap, fix within 90 days
info	Advisory only

Categories Validated by ghqr

Category	Description
security	Enterprise GHAS policy defaults; org-wide secret scanning, push protection, and GHAS defaults for new repos; org-level open code scanning and secret scanning alerts
branch_protection	Branch rules, required reviews, status checks
access_control	Collaborator permissions, deploy keys, admin access
copilot_security	Public code suggestions, content exclusions
copilot_cost	Seat utilization, inactive seats
copilot_features	IDE chat, CLI, platform chat enablement
copilot_models	Allowed/blocked model configuration
copilot_mcp	MCP server policy
copilot_extensions	Extension allowlist
actions	Workflow permissions, allowed actions, SHA pinning
community	SECURITY.md, CODEOWNERS, contributing guidelines
dependencies	Enterprise/org Dependabot alert defaults for new repos; Dependabot security updates defaults; aggregate open Dependabot alerts by severity
permissions	Default repo permissions, member privileges
deployment	Environment protection rules
maintenance	Stale branches, archived repos, empty repos
risk	Repository criticality, public visibility
features	Advanced Security, wiki, issue tracker

Workflow

Phase 1 — Acquire Scan Data

If the user provides a scan result file path or JSON, use it directly. Otherwise:

1. Use the ghqr_scan tool to run a new scan:
   • Pass enterprises, organizations, or repositories based on the user's scope
   • The tool returns a file URI pointing to the JSON output
2. Read the JSON output file to load the scan data

Phase 2 — Build the Report

Produce the full report in Markdown following the Report Template below. Populate every section with real data from the scan; never invent findings.

Phase 3 — Validate Completeness

Before delivering the report, verify:

• Executive summary reflects actual issue counts
• Every category with at least one finding has its own section
• Every issue listed in the scan appears somewhere in the report
• Each finding in the 30/60/90 plan maps directly to a scan issue or recommendation
• No findings are duplicated across plan phases

---

Report Template

# GitHub Assessment Report — [Enterprise/Organization/Repository Name]

**Scope:** [Enterprise / Organization / Repository]
**Generated:** [Date]
**Scan Coverage:** [N enterprises / N organizations / N repositories]

---

## Executive Summary

> One paragraph (4–6 sentences) for a non-technical audience. State the overall
> security posture, the number of critical and high findings, the biggest
> risk areas, and the top improvement opportunity.

### Posture Scorecard

| Entity | Type | Critical | High | Medium | Low | Info |
|--------|------|----------|------|--------|-----|------|
| [name] | org  | 0 | 2 | 3 | 1 | 4 |
| [repo] | repo | 1 | 1 | 2 | 0 | 2 |

### Overall Risk Distribution

| Severity | Count | % of Total |
|----------|-------|-----------|
| 🔴 Critical | N | X% |
| 🟠 High     | N | X% |
| 🟡 Medium   | N | X% |
| 🟢 Low      | N | X% |
| ℹ️ Info     | N | X% |

---

## Findings by Subject

<!-- Repeat this block for every category that has at least one issue or recommendation -->

### [Category Display Name]  <!-- e.g. "Security — Dependabot & Code Scanning" -->

**Risk Level:** [Critical / High / Medium / Low]  
**Affected Entities:** [list of org/repo names]

#### Findings

| Severity | Entity | Finding | Action | Learn More |
|----------|--------|---------|--------|------------|
| 🔴 Critical | org/repo | [issue text from scan] | [recommendation text] | [link from `learn_more`] |
| 🟠 High     | org/repo | [issue text] | [recommendation text] | [link from `learn_more`] |

#### Why This Matters

[2–3 sentences explaining the business/security risk of this category in plain language]

---

<!-- Categories with zero findings are omitted -->

---

## Remediation Plan

### 30-Day Sprint — Immediate Actions 🔴

> Address all **critical** and **high** severity issues. These represent the
> highest risk to your organization and should be resolved within the first month.

| Priority | Entity | Action | Category | Effort | Owner |
|----------|--------|--------|----------|--------|-------|
| 1 | [entity] | [specific fix] | [category] | [S/M/L] | [team] |
| 2 | [entity] | [specific fix] | [category] | [S/M/L] | [team] |

 [Risk reduction summary]

---






| Priority | Entity | Action | Category | Effort | Owner |
|----------|--------|--------|----------|--------|-------|
| 1 | [entity] | [specific fix] | [category] | [S/M/L] | [team] |

 [Risk reduction summary]

---






| Priority | Entity | Action | Category | Effort | Owner |
|----------|--------|--------|----------|--------|-------|
| 1 | [entity] | [specific fix] | [category] | [S/M/L] | [team] |

 [Risk reduction summary]

---



The following security areas  via the GitHub
API and require manual review:

| Area | What to Check | Where |
|------|--------------|-------|
| Audit log streaming | Connected to SIEM | Enterprise → Settings → Audit log |
| Secret scanning alerts | Open critical alerts reviewed and resolved | Repo → Security → Secret scanning |
| Secret scanning: custom patterns | Org/enterprise-level custom patterns defined | Org → Settings → Code security → Secret scanning |
| Secret scanning: bypass requests | Bypass request reviewers configured for push protection | Org → Settings → Code security → Secret scanning |
| Code scanning: default setup | Default setup enabled on all active repos (no workflow required) | Repo → Settings → Code security → Code scanning |
| Code scanning: alert triage | Open high/critical code scanning alerts reviewed | Repo → Security → Code scanning |
| Code scanning: tool coverage | All relevant languages covered by a scanning tool | Repo → Security → Code scanning |
| Dependency review | dependency-review-action present in PR workflows | Repo →  |
| Actions: self-hosted runners | Present on public repos | Repo → Settings → Actions → Runners |
| Branch protection: enforce admins | Enabled | Repo → Settings → Branches |
| Environment protection rules | Reviewers configured | Repo → Settings → Environments |
| SAML SSO enforcement & SCIM | SSO enforced; SCIM provisioning active | Org → Settings → Authentication Security |
| IP Allow List | Configured and enabled | Org → Settings → Authentication Security |
| Org webhooks | SSL verification enabled, shared secret set on all hooks | Org → Settings → Webhooks |
| Org-level rulesets | At least one ruleset defined for repo governance | Org → Settings → Rules → Rulesets |

---






Expand all findings

| Severity | Category | Finding | Action | Learn More |
|----------|----------|---------|--------|------------|
| [sev] | [cat] | [issue] | [recommendation] | [learn

---

Category Display Name Mapping

When rendering category names in the report use these human-readable titles:

Raw category	Display name
security	Security — Vulnerability Management
branch_protection	Branch Protection
access_control	Access Control & Permissions
copilot_security	GitHub Copilot — Security & Compliance
copilot_cost	GitHub Copilot — Cost & Seat Utilization
copilot_features	GitHub Copilot — Feature Enablement
copilot_models	GitHub Copilot — Model Policy
copilot_mcp	GitHub Copilot — MCP Configuration
copilot_extensions	GitHub Copilot — Extensions
actions	GitHub Actions — Workflow Security
community	Community Health & Documentation
dependencies	Dependency Management
permissions	Member & Repository Permissions
deployment	Deployment & Environment Controls
maintenance	Repository Maintenance
risk	Visibility & Risk Exposure
features	Advanced Security Features

Effort Sizing Guide

When populating the Effort column in the plan tables:

Label	Definition
S — Small	Single setting toggle or one-click configuration; < 1 hour
M — Medium	Requires creating a file, policy, or workflow; 1–4 hours
L — Large	Requires team coordination, design decision, or phased rollout; 1+ days

Output Requirements

The agent MUST:

1. Always use real scan data — never fabricate issues
2. Include every category that has at least one finding; skip categories with zero findings
3. Map every finding to exactly one plan phase based on its severity:
   • critical + high → 30-day sprint
   • medium → 60-day sprint
   • low + info → 90-day sprint
4. Estimate effort using S/M/L sizing for each action item
5. List manual checks that ghqr cannot automate (reference references/MANUAL_CHECKS.md categories)