GitHub Security Agent

Agent framework for reducing GitHub security alerts across many repositories. Profile-driven, local-first, and scoped to remediation patterns that are mechanically verifiable.

Scope

The current scaffold supports:

• GitHub Dependabot alerts — exhaustive remediation within one locked run
• Selected GitHub code scanning rules with deterministic fixes — allowlisted per profile
• GitHub secret scanning response — review-required cleanup PRs when deterministic repository cleanup is possible

Not supported for automatic merge:

• code scanning rules outside the selected profile allowlist
• secret scanning cleanup PRs (always review-required)
• any finding that requires infrastructure, product, or compliance decisions

The scaffold never rotates credentials, dismisses alerts, rewrites git history, or pushes commits to Dependabot-authored branches.

Quick Start

1. Fork or clone this repository.
2. Create profiles/local/<your-owner>/, then copy profiles/template/profile.yaml to profiles/local/<your-owner>/profile.yaml. The profiles/local/ directory is gitignored.
3. Fill in profile_id, owner, owner_type, runtime.local_clone_root, and per-repo local_path to match your environment.
4. For each repository entry, set automation_mode: active only when every enabled target has real verification commands. Otherwise use manual_only. See docs/operating-model.md for the verification command contract.
5. Authenticate gh with a PAT or fine-grained token that has the required capabilities (see docs/runtime-contract.md).
6. Invoke the root SKILL.md with your selected profile.

Install Agent Skill

Copy this into a new Codex or Claude Code session:

Set up github-security-agent, the profile-driven GitHub security remediation skill for agents.

If npm is available:
npx skills add nickzren/github-security-agent --skill github-security-agent -y -g

Otherwise:
dir="${XDG_DATA_HOME:-$HOME/.local/share}/agent-skills"
repo="$dir/github-security-agent"
mkdir -p "$dir"
test -d "$repo" || gh repo clone nickzren/github-security-agent "$repo"
"$repo/install.sh"

Manual install from this checkout:

./install.sh

Operating Model

The framework is organized around a profile that describes one GitHub owner. Each profile contains repository entry definitions, each with stable target_id values for remediation targets (e.g. root, ui, api-server).

Every locked run acquires a profile-scoped lock under the clone root, then processes eligible work in this order: exhaustive Dependabot → allowlisted code scanning → secret scanning response → review gate → reconcile → report.

Each remediation unit has a stable dedup key (owner/repo + alert_class + base_branch + target_id, with normalized rule id or GitHub alert number appended for code_scanning and secret_scanning respectively) that flows through branch naming, PR body metadata, and run reporting.

Contract Documents

Public contracts live in docs/:

• docs/runtime-contract.md — clone handling, authentication, concurrency, rate limits, target environment handling, secret handling, PR body metadata schema
• docs/operating-model.md — vocabulary, repository modes, remediation unit, branch naming, native PR strategy, outcome states, reason codes, exhaustive run model
• docs/code-scanning-policy.md — allowlist model, coverage states, rule contracts
• docs/secret-scanning-policy.md — deterministic cleanup contract, response buckets, PR rules
• docs/review-gate.md — pre-merge verification per alert class
• docs/reporting-model.md — summary fields, outcome semantics, reporting rules
• docs/discovery-model.md — remediation-unit discovery work list: schema, triage taxonomy, coverage gaps

Reporting

Every locked run writes one JSON Lines record per remediation unit to {clone_root}/.github-security-agent/runs/{profile_id}/{iso8601_utc}.jsonl, plus a companion latest.json summary overwritten on each run. Keep this directory local; it may contain repository names and alert references needed for operator follow-up. Blocked and skipped findings appear in the same report with their reason code and any relevant platform_constraints or manual follow-up actions. See docs/reporting-model.md for the per-unit summary schema.

Weekly Reporting

The scaffold includes a weekly issue path. Use scripts/run_report_only.py to read open GitHub security alerts and write the local latest.json, scripts/collect_github_security_overview.py to collect sanitized fallback alert counts, scripts/render_weekly_report.py to turn the summary into compact Markdown, then scripts/dispatch_weekly_report.py to dispatch .github/workflows/publish-weekly-report.yml. The dispatcher requires explicit --publish-repo, --issue-repo, and a supported defaults.mutation_mode; pass --heading for account-specific issue titles. The published issue body may show sanitized names and PR links for repositories explicitly marked public. Private or unknown-visibility repositories remain aggregate counts only, and the issue must not include secret types, alert numbers, raw alert payloads, or token-like strings.

Repository Layout

SKILL.md
README.md
LICENSE
requirements-dev.txt
docs/
  code-scanning-policy.md
  secret-scanning-policy.md
  operating-model.md
  review-gate.md
  runtime-contract.md
  reporting-model.md
  discovery-model.md
skills/
  account-discovery/
  code-scanning-triage/
  code-scanning-remediator/
  dependabot-remediator/
  secret-scanning-response/
  review-gate/
  reporting/
profiles/
  template/
  examples/
  local/          # gitignored account-specific overlays
scripts/
  collect_github_security_overview.py
  discover_remediation_units.py
  dispatch_weekly_report.py
  gh_security.py
  render_weekly_report.py
  run_report_only.py
  validate_profile.py
tests/
.github/workflows/
  publish-weekly-report.yml
  validate-profiles.yml

Skills

• SKILL.md — canonical entrypoint for one selected profile
• skills/account-discovery/SKILL.md — profile and runtime validation
• skills/dependabot-remediator/SKILL.md — Dependabot alert remediation
• skills/code-scanning-triage/SKILL.md — classify code scanning alerts
• skills/code-scanning-remediator/SKILL.md — allowlisted deterministic remediation
• skills/secret-scanning-response/SKILL.md — cleanup PRs with manual follow-up recording
• skills/review-gate/SKILL.md — pre-merge policy decision
• skills/reporting/SKILL.md — run summary

Profiles

• profiles/template/profile.yaml — canonical schema
• profiles/template/README.md — profile vocabulary and rules
• profiles/examples/acme-org/profile.yaml — organization profile example

Account-specific runnable overlays should live under profiles/local/, which is gitignored.

Development

Scripts and tests need PyYAML (the only dev dependency):

python3 -m pip install -r requirements-dev.txt
python3 -m unittest discover -s tests

Or without installing anything:

uv run --with-requirements requirements-dev.txt -- python -m unittest discover -s tests

scripts/validate_profile.py enforces the profile invariants from docs/operating-model.md: owner_type must be org or user, active repositories need verification commands for every target, targets that enable dependabot need declared ecosystems, protected-manual entries must exist and stay manual_only, and repository/target ids must be unique. Add --check-local on an operator machine to also verify local clone paths and origin remotes. CI (validate-profiles.yml) runs the test suite and lints the committed profiles.

Generate a remediation work list (read-only) for one profile:

python3 scripts/discover_remediation_units.py \
  --profile profiles/template/profile.yaml \
  --output /tmp/security-worklist.json

License

MIT — see LICENSE.