scanning-security

name	scanning-security
description	Runs a multi-tool security scan: AgentShield for Claude config, zizmor for GitHub Actions, and optionally Socket CLI for dependency scanning. Produces an A-F graded security report. Use after modifying `.claude/` config, hooks, agents, or GitHub Actions workflows, and before releases.

scanning-security

Multi-tool security scanning pipeline for the repository.

When to Use

• After modifying .claude/ config, settings, hooks, or agent definitions
• After modifying GitHub Actions workflows
• Before releases (called as a gate by the release pipeline)
• Periodic security hygiene checks

Prerequisites

See _shared/security-tools.md for tool detection and installation.

Process

Phase 1: Environment Check

Follow _shared/env-check.md. Initialize a queue run entry for scanning-security.

---

Phase 2: AgentShield Scan

Scan Claude Code configuration for security issues:

pnpm exec agentshield scan

Checks .claude/ for:

• Hardcoded secrets in CLAUDE.md and settings
• Overly permissive tool allow lists (e.g. Bash(*))
• Prompt injection patterns in agent definitions
• Command injection risks in hooks
• Risky MCP server configurations

Capture the grade and findings count.

Update queue: current_phase: agentshield → completed_phases: [env-check, agentshield]

---

Phase 3: Zizmor Scan

Scan GitHub Actions workflows for security issues.

See _shared/security-tools.md for zizmor detection. If not installed, skip with a warning.

zizmor .github/

Checks for:

• Unpinned actions (must use full SHA, not tags)
• Secrets used outside env: blocks
• Injection risks from untrusted inputs (template injection)
• Overly permissive permissions

Capture findings. Update queue phase.

---

Phase 4: Grade + Report

Spawn the security-reviewer agent (see agents/security-reviewer.md) with the combined output from AgentShield and zizmor.

The agent:

1. Applies CLAUDE.md security rules to evaluate the findings
2. Calculates an A-F grade per _shared/report-format.md
3. Generates a prioritized report (CRITICAL first)
4. Suggests fixes for HIGH and CRITICAL findings
5. For every Critical / High finding, runs variant analysis per _shared/variant-analysis.md. The same misconfiguration likely exists in sibling workflow files, sibling Claude config blocks, or other repos.

Output a HANDOFF block per _shared/report-format.md for pipeline chaining.

Update queue: status: done, write findings_count and final grade.

Adjacent scans

Code-side security (insecure defaults, fail-open patterns, security-regression in a diff) lives in scanning-quality's modular scans:

• scanning-quality/scans/insecure-defaults.md: code-side fail-open defaults.
• scanning-quality/scans/differential.md: security regressions introduced by the current diff.

This skill stays focused on config security (Claude config + GitHub Actions). The split keeps the surface predictable: scanning-security = "is the harness safe?", scanning-quality/scans/ = "is the code safe?".

Commit cadence

This skill is read-only: scan + grade + report, no fixes. Cadence rules apply to handing the report off:

• Save the report before acting. Commit the report file in its own commit (docs(reports): scanning-security YYYY-MM-DD: grade <A-F>). The grade in the message makes the trend visible without opening the file.
• Don't fix in-skill. Security findings need careful per-finding triage; they're not safe to batch-fix mechanically. Open per-finding fixes as separate commits driven by the appropriate skill (or hand-edit when the fix is a one-liner like a workflow SHA bump).
• One report per scan run. Re-running produces a new report; commit each so the security trend line is auditable.