Vulnerability-Scanning: AI tool project

Local-first vulnerability and supply-chain scanning for agent runtimes.

This project packages a compact agent skill, a scanner CLI, a starter config, and reference docs for running security scans against local codebases. It helps an agent find vulnerable dependencies, leaked secrets, risky GitHub Actions, source-code security issues, and supply-chain concerns while keeping scan artifacts local by default. Optional package-intake checks can query the public OSV API when package_intake.osv_api_enabled is enabled.

Quick Start

For installation and runtime setup, read INSTALL.md. Scanner tool setup lives in references/install-tools.md.

Agent install prompt:

Follow https://raw.githubusercontent.com/TheSethRose/Vulnerability-Scanning/refs/heads/main/INSTALL.md to install the vulnerability-scanning skill. Set it up for my local agent runtime, install and validate required scanner tools, create a local config from templates/config-starter.yaml, and ask me before changing remediation, tracker, OSV API, license scanning, Scorecard, or Gitleaks history behavior. Use read-only scanning by default, keep artifacts and reports outside target repos, enable tracker/cache behavior unless I decline it, and do not enable Codex auto-remediation unless I explicitly approve it. After setup, run config validation, validate-tools, validate-tools --deep, and a plan run against the workspace I provide. Report exact commands and results.

Validate scanner availability. This checks whether the scanner tools configured for this repo are installed and visible on your PATH:

python3 scripts/vuln-scan.py validate-tools \
  --config templates/config-starter.yaml \
  --format text

Preview what would be scanned. This is the safest first command for a new repo because it discovers targets without running scanners:

python3 scripts/vuln-scan.py plan \
  --config templates/config-starter.yaml \
  --root "$PWD" \
  --scan-mode full \
  --format text

Run a full local scan. The JSON summary and raw scanner artifacts are written under /tmp so scan output does not clutter the target repo:

python3 scripts/vuln-scan.py scan \
  --config templates/config-starter.yaml \
  --root "$PWD" \
  --scan-mode full \
  --output /tmp/vuln-summary.json \
  --artifact-dir /tmp/vuln-artifacts \
  --format text

Run deeper tool checks, list available scanner engines, or render a saved JSON summary as a readable report:

python3 scripts/vuln-scan.py validate-tools --config templates/config-starter.yaml --format text --deep
python3 scripts/vuln-scan.py list-engines --format text
python3 scripts/vuln-scan.py render-report /tmp/vuln-summary.json --format text

Retest one scanner after installing a tool, changing parser behavior, or checking a focused finding:

python3 scripts/vuln-scan.py scan \
  --config templates/config-starter.yaml \
  --root "$PWD" \
  --scan-mode full \
  --only-engine trivy \
  --output /tmp/vuln-summary.json \
  --artifact-dir /tmp/vuln-artifacts \
  --format text

What It Scans

The default full mode covers the common repo-security path: vulnerable dependencies, broad filesystem findings, current-tree secrets, GitHub Actions workflows, and source-code security rules.

Additional modes are explicit so scans stay predictable:

dependencies: known vulnerable dependency checks
secrets: secret scanning and tracked .env* checks
ci: GitHub Actions and CI workflow checks
supply-chain: checks for risky package behavior before or after adding dependencies
sast: source-code security scanning
sbom: SBOM generation and SBOM vulnerability checks
hygiene: repository security hygiene checks
remediation-prep: read-only grouping of findings by likely fix path

Use --only-engine for focused retests. It is repeatable and comma-separated; valid names come from list-engines, plus aliases such as ci, secrets, sbom, and javascript-native.

Scanner Coverage

The CLI coordinates these tools when they match the repo and requested scan mode:

OSV Scanner plus native JavaScript audits, pip-audit, and cargo audit
Trivy filesystem/image scans
Gitleaks, TruffleHog, and metadata-only secret fallback
zizmor and actionlint for GitHub Actions
Semgrep CE SAST
Syft and Grype for SBOM generation/scanning
OpenSSF Scorecard for explicit repo hygiene scans
GuardDog package-intake checks for npm, PyPI, Go, RubyGems, GitHub Actions, and VS Code extensions

If a tool is unavailable, unsupported for a target, times out, or produces output the CLI cannot parse, the report calls that out separately instead of presenting the scan as clean.

Safety Defaults

Normal scans are read-only.
Starter full scans use current-tree Gitleaks, not full git history.
Enable Gitleaks history only for deep secret-history audits or focused retests.
Scorecard runs only when --scan-mode hygiene is requested.
License scanning runs only when explicitly requested.
Remediation is opt-in with --auto-remediate or config that explicitly enables it.
Reports and raw artifacts should live outside target repos for broad or multi-repo scans.
Secret values should never be printed or summarized.
Scan mode must not branch, commit, push, delete files, rotate credentials, or rewrite history.

Package Layout

The repository is split between the short prompt-facing skill file, executable scanner code, starter configuration, and longer reference docs:

SKILL.md: compact runtime instructions for agents
INSTALL.md: setup guide for Codex, OpenClaw, Hermes, and other local agent runtimes
scripts/vuln-scan.py: scan, plan, validate, package-intake, and report CLI
scripts/nightly-vuln-scan.py: backwards-compatible wrapper for existing cron jobs
scripts/validate-config.sh: starter config and Python syntax validation
templates/config-starter.yaml: starter local scan config
references/: install, scanner behavior, parser, report, remediation, and package-intake contracts

Finding Tracker

The tracker is a local cache of findings the scanner has already handled. It prevents repeat runs from spending time on the same fixed, unfixable, or temporarily blocked items. Configure its location in templates/config-starter.yaml or with --tracker-path; entries are retried after their configured window so newly available fixes can still be picked up later.

References

references/scanner-behavior.md: engine behavior and scan assumptions
references/parser-contract.md: parser and normalized finding expectations
references/report-schema.md: report fields and coverage states
references/remediation-policy.md: remediation grouping and guardrails
references/package-intake.md: package-intake decision contract
references/install-tools.md: scanner installation and validation

Privacy

This repository intentionally contains no private paths, personal repo names, tokens, scan results, or environment-specific tracker data.

Maintenance

Before default-enabling a new engine, verify current CLI flags, add parser tests, add fake-binary integration coverage, define failure handling, and document the engine in README.md and SKILL.md.