Security Scan

An Agent Skills security workflow for dependency audits,
Semgrep code-pattern scanning, OWASP Top 10:2025 mapping, and reviewable findings.

See the changelog for release history.

Safety Model

Scanning is read-only by default. The skill does not install tools, update dependencies, execute
project scripts, build images, or change global agent settings without explicit approval. Missing
or failed scanners are reported as incomplete coverage, never as a clean result.

Installation

For Claude Code:

git clone https://github.com/Ray0907/security-scan.git ~/.claude/skills/security-scan

Other clients use their own skills directory. Consult the client's documentation for its install
location and invocation UI.

Code scanning requires Python 3.10 or newer and Semgrep. Officially recommended Semgrep installs:

pipx install semgrep
# or
uv tool install semgrep

Dependency tools are needed only for ecosystems detected in the target repository. See
references/SCANNERS.md for commands and limitations.

Usage

Ask naturally or use slash-command-style arguments if the client supports them:

Scan this repository for security issues.
/security-scan
/security-scan --deps-only
/security-scan --code-only
/security-scan --owasp A05
/security-scan --severity critical,high
/security-scan --export-bypass

--deps-only and --code-only are mutually exclusive. Persistent reminders are client-specific;
the skill will not claim --auto-remind is active until a supported hook or automation is chosen.

Example

For a monorepo with a pnpm app, a Python API with a Dockerfile, and an unlocked Rust crate:

python3 scripts/scan_plan.py /work/app --exclude web/fixtures --pretty

{
  "excluded": ["web/fixtures"],
  "projects": [
    {
      "kind": "rust",
      "path": ".",
      "status": "needs-lockfile",
      "tool": "cargo-audit",
      "command": null,
      "reason": "Cargo.toml exists without Cargo.lock"
    },
    {
      "kind": "container",
      "path": "api",
      "status": "ready",
      "tool": "trivy",
      "coverage": "misconfiguration-only",
      "command": ["trivy", "fs", "--format", "json", "--scanners", "misconfig", "."]
    },
    {
      "kind": "python",
      "path": "api",
      "status": "ready",
      "tool": "pip-audit",
      "command": ["pip-audit", "--format", "json", "-r", "requirements.txt"]
    },
    {
      "kind": "node",
      "path": "web",
      "status": "ready",
      "tool": "pnpm",
      "command": ["pnpm", "audit", "--json"]
    }
  ],
  "root": "/work/app",
  "schema_version": 1
}

A completed report records every scanner state explicitly:

Supported Dependency Evidence

A Dockerfile or Containerfile alone is not an image vulnerability inventory. Image scanning
requires an existing image supplied by the user; this skill does not build untrusted repositories
during a scan.

How It Works

1. scripts/scan_plan.py recursively inventories supported projects and emits a JSON execution
   plan without running a scanner.
2. Each planned dependency command runs independently from its project directory.
3. Semgrep runs with p/owasp-top-ten and metrics disabled for code-pattern coverage.
4. Findings retain native advisory IDs and are normalized to OWASP 2025 only when supported.
5. Reports list every scanner as clean, findings, failed, skipped, or inconclusive.

Detailed contracts:

• references/SCANNERS.md: commands, exit handling, and NVD enrichment.
• references/OWASP.md: 2025 categories and legacy-label translation.
• references/REPORTING.md: redaction, report schema, and false positives.

Development

Run the deterministic tests and official format validator:

python3 -m unittest discover -s tests -v
uvx --from skills-ref agentskills validate "$(pwd)"

Validate the external Semgrep ruleset separately:

semgrep scan --config p/owasp-top-ten --validate --metrics=off

Structure

security-scan/
├── .github/workflows/validate.yml
├── docs/                       # Design documents
├── scripts/scan_plan.py
├── tests/test_scan_plan.py
├── references/
│   ├── OWASP.md
│   ├── REPORTING.md
│   └── SCANNERS.md
├── CHANGELOG.md
├── SECURITY.md
├── SKILL.md
├── README.md
└── LICENSE

Contributing

Contributions are welcome. Include a regression test for planner behavior and run all validation
commands before opening a pull request.

License

MIT