Back to pinned projects

Public repository

Vulnerability-Scanning

A Hermes skill for recurring vulnerability scans across JavaScript/TypeScript, Python, containers, CI/CD, and secret-exposure checks.

A Hermes skill package for local-first vulnerability and supply-chain scanning.

The goal is to let an agent inspect each codebase, identify its packages and project types, choose the right scanner tools, run the scanner CLI or direct tools, and return evidence-backed findings without requiring SaaS services for normal repo scans. Package intake can optionally query the public OSV API when package_intake.osv_api_enabled is enabled.

Contents

  • SKILL.md: agent instructions, scanner selection matrix, reporting contract, and safety rules
  • INSTALL.md: install and setup guide for Hermes, Codex, OpenClaw, and other local agent runtimes
  • scripts/vuln-scan.py: scanner CLI for deterministic local scans, planning, tool validation, and report rendering
  • scripts/nightly-vuln-scan.py: backwards-compatible wrapper for existing cron runs
  • scripts/validate-config.sh: starter config and Python syntax validation
  • templates/config-starter.yaml: local scan configuration template
  • references/: install, behavior, parser, report, remediation, and package-intake contracts

Current Scanner CLI

Run a full local scan:

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

Run dependency-only CI behavior:

python3 scripts/vuln-scan.py scan \
  --config templates/config-starter.yaml \
  --root "$PWD" \
  --scan-mode dependencies \
  --fail-on-findings \
  --output ./vuln-summary.json

Run explicit remediation after scan findings are produced:

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

Token usage warning: If --auto-remediate is enabled and --root points at a directory with many projects, expect heavy Codex token usage on at least the first run. The scanner may discover and prepare remediation for many independent repositories before the vulnerability tracker has enough state to skip already-handled findings. Start with a narrow repo root, or run plan/remediation-prep first, before enabling auto-remediation across a broad workspace.

List scanner engines:

python3 scripts/vuln-scan.py list-engines --format text

Check tool availability:

python3 scripts/vuln-scan.py validate-tools --format text

Run installed-tool smoke checks:

python3 scripts/vuln-scan.py validate-tools --format text --deep

Plan a scan without running scanners:

python3 scripts/vuln-scan.py plan \
  --root "$HOME/projects" \
  --scan-mode full \
  --format text

Retest only specific scanners after a tool install or parser change:

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

Render a saved JSON report:

python3 scripts/vuln-scan.py render-report ./vuln-summary.json --format text

Scan Modes

Supported CLI values:

  • full
  • dependencies
  • secrets
  • ci
  • supply-chain
  • sast
  • sbom
  • hygiene
  • remediation-prep

full means the normal local security scan: dependency, broad repo, secrets, workflow, and SAST engines. SBOM, repo hygiene, and GuardDog supply-chain scans stay explicit because they can add heavier artifacts, network/API behavior, or package-intake semantics. Trivy license scanning is also explicit; pass --include-licenses when license review is part of the task. Gitleaks history scanning is off in the starter config for broad workspace scans; enable engines.gitleaks.scan_history: true for deep secret-history audits or focused retests.

Use --only-engine to limit execution to specific scanner engines during retests. The option is repeatable and comma-separated. Valid names are the engine names from list-engines, plus aliases such as ci, secrets, sbom, and javascript-native.

The current implementation covers dependency scanning through OSV, native JavaScript audits, pip-audit, and cargo audit; broad Trivy filesystem/image scans; and secret scanning through Gitleaks, TruffleHog, and the metadata-only fallback scanner; GitHub Actions scanning through zizmor and actionlint; Semgrep CE SAST through --config=auto or custom rule paths; and SBOM generation/scanning through Syft plus Grype; and explicit repo-hygiene scans through OpenSSF Scorecard; and GuardDog supply-chain/package-intake scans for npm, PyPI, Go, RubyGems, GitHub Actions, and VS Code extensions. Package intake stays local-first unless OSV API lookup is enabled in config. The scanner also reports per-project coverage state so a clean finding set is not confused with missing, skipped, unsupported, failed, or timed-out scanner coverage. Unsupported targets, missing tools, and scanner failures are reported as setup debt instead of being mistaken for clean coverage. remediation-prep is read-only and groups findings by likely fix strategy without launching Codex.

scripts/nightly-vuln-scan.py remains available for existing cron jobs and passes through to the same CLI implementation.

Scanner Stack Direction

The package should prioritize coverage that normal CVE scanning misses:

  • malicious package behavior
  • install scripts
  • credential theft
  • GitHub Actions injection
  • overbroad workflow permissions
  • untrusted or unpinned actions
  • unsigned or unpinned dependencies
  • secrets in git history

Highest-value tools:

  • OSV Scanner for known vulnerable dependencies
  • Trivy for broad local filesystem, image, IaC, and secret coverage
  • Trivy license scanning through explicit --include-licenses
  • Gitleaks for fast secret scanning
  • TruffleHog for verified credential scanning
  • GuardDog for malicious package behavior
  • zizmor and actionlint for GitHub Actions
  • Semgrep CE for local SAST
  • Syft and Grype for SBOM and SBOM vulnerability scans
  • OpenSSF Scorecard for repo hygiene when network/GitHub access is acceptable

Do not add redundant CVE scanners unless they cover a real gap beyond OSV, Trivy, and optional Grype.

Safety Defaults

  • The scan phase is read-only.
  • Starter full scans run current-tree Gitleaks by default, not full git history, to keep broad workspace scans usable. Turn on engines.gitleaks.scan_history for deep secret-history audits.
  • Remediation is opt-in with --auto-remediate or a separate config that explicitly enables remediation.auto_fix and remediation.codex.enabled.
  • Broad roots plus auto-remediation are expensive. A first run against a folder containing many projects should be expected to use heavy Codex token volume, and follow-up runs may also be expensive until the tracker has enough state to skip already-handled findings.
  • Missing tools, timeouts, parser failures, and unsupported targets are setup debt, not clean results.
  • Secret values must never be printed or summarized.
  • The scanner must not branch, commit, push, delete files, rotate credentials, or rewrite history during scan mode.
  • Strict unattended scans should use --allowed-root and --fail-on-scope-violation.
  • Scorecard is disabled outside explicit --scan-mode hygiene runs because complete results may require network access and GitHub/GitLab API tokens.

Vulnerability Tracker

The configured tracker path, defaulting to $HOME/.hermes/vuln_knowledge.json, keeps fixed, fixable, unfixable, and blocked findings from being reprocessed every run. Fixed, unfixable, and blocked entries are skipped until their retry window expires. The default retry window is 30 days, after which the scanner surfaces the finding again so Codex can retry remediation if the ecosystem has changed.

Install

For full setup instructions, read INSTALL.md.

If you want an agent to install it for you, give Hermes, Codex, OpenClaw, or another local agent this prompt:

Follow the instructions in INSTALL.md to install the vulnerability-scanning skill.
Set it up for my local agent runtime, install and validate the required scanner tools, create a local config from templates/config-starter.yaml, and ask me the setup questions from INSTALL.md 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 the exact commands and results.

Privacy

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

Maintenance

External scanner command syntax changes over time. Before default-enabling a new engine, verify current CLI flags, add parser tests, add fake-binary integration coverage, define setup-debt behavior, and document the engine in this README and SKILL.md.

License

MIT