Vulnerability Scanning

Use this skill to inspect codebases, choose local security scanners, run the repo CLI or direct tools, and report evidence-backed findings without requiring SaaS services for normal scans.

Start Here

1. Read the user's scope and scan mode.
2. Inspect manifests, lockfiles, workflows, Docker/IaC files, and extension metadata.
3. Validate tools before scanning:

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

Use --deep before broad or unattended scans. Do not install scanners unless the user explicitly asks for setup or approves host changes. Missing scanners, timeouts, unsupported targets, and parse failures are setup debt, not clean coverage. Install guidance lives in references/install-tools.md.

Default Posture

• Use scripts/vuln-scan.py scan when it supports the requested mode.
• Start from templates/config-starter.yaml; override narrowly.
• Keep full focused on security: dependencies, broad repo, secrets, workflow, and SAST.
• Keep SBOM, hygiene, supply-chain/package-intake, and license scanning explicit.
• Keep Gitleaks history scans off for broad workspaces unless doing a deep secret audit.
• Keep Scorecard disabled unless --scan-mode hygiene is requested.
• Keep package_intake.osv_api_enabled: false unless the user wants public OSV lookup.
• Put --output and --artifact-dir outside target repos for multi-repo scans, usually under /tmp.

Core Commands

Run a normal scan:

python3 scripts/vuln-scan.py scan \
  --config templates/config-starter.yaml \
  --root /path/to/repo-or-workspace \
  --scan-mode full \
  --output /tmp/vuln-summary.json \
  --artifact-dir /tmp/vuln-artifacts \
  --format text

Plan without scanner execution:

python3 scripts/vuln-scan.py plan --config templates/config-starter.yaml --root /path/to/repo --scan-mode full --format text

List engines or validate tools:

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

Retest focused engines:

python3 scripts/vuln-scan.py scan --root /path/to/repo --scan-mode full --only-engine trivy --output /tmp/vuln-summary.json --artifact-dir /tmp/vuln-artifacts --format text

Render an existing JSON summary:

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

For more examples, direct tool fallback syntax, and parser expectations, read README.md and references/.

Compatibility Notes

• scripts/nightly-vuln-scan.py may remain in use for existing cron jobs.
• If setup is requested, use references/install-tools.md for install commands and tool-specific troubleshooting.
• When the repo CLI does not support a needed engine, run the direct tool only after verifying syntax against the installed version, and save raw output under the artifact directory.
• Use $HOME/.hermes/vuln_knowledge.json or the configured tracker path to avoid reprocessing known fixed, unfixable or blocked findings until their retry window expires.

Scan Modes

Scanner Selection

Scope Rules

• Keep monorepo subprojects separate and label targets by stable relative path.
• Skip generated, vendored, archived, fixture, example, cache, build, and dependency directories unless requested.
• Use --allowed-root, --allowed-label-prefix, --forbidden-label-prefix, and --fail-on-scope-violation for unattended scans.
• Treat scope violations as blockers for strict unattended scans.

Reporting Contract

Every non-silent report must include:

• scope, scan mode, exact commands, artifact paths
• findings grouped by repo/project
• setup debt grouped separately
• skipped targets and remaining uncertainty when relevant
• counts by severity, category, and scanner
• coverage status by category: scanned, verified_clean, not_requested, not_applicable, skipped, unsupported, scanner_missing, scanner_failed, or timed_out

Never print secret values. Report metadata only: file, line, detector, severity, confidence, git-tracked state, and remediation hint. Normalized report fields are documented in references/report-schema.md.

Silent Cron

For unattended cron delivery, respond exactly:

[SILENT]

Only do this when there are zero findings, actionable setup-debt items, scope violations, parse failures, and scanner timeouts. Do not return [SILENT] if a missing tool prevented coverage.

Package Intake

For dependency intake, identify ecosystem and package, then run:

python3 scripts/vuln-scan.py package-intake npm package-name --output /tmp/package-intake.json --artifact-dir /tmp/package-intake-artifacts --format text

Supported ecosystems: npm, pypi, go, rubygems, github_action, extension. Return one of allow, allow with caution, avoid, or blocked pending review. Do not add the dependency unless separately asked.

Remediation

The scan phase is read-only. Run Codex remediation only when the user explicitly asks or the command includes --auto-remediate.

For remediation, preserve one log per repo under the artifact directory and guard each task:

• work only inside the affected repo
• do not branch, commit, push, delete unrelated files, rotate credentials, or rewrite history
• prefer narrow package manager or manifest changes
• rerun the scanner engine that produced the finding
• report changed files, commands, fixed findings, remaining findings, and blocked items

Use $HOME/.hermes/vuln_knowledge.json or the configured tracker path to skip known fixed/unfixable/blocked findings until their retry window expires.

Safety

• Do not use this for exploit attempts, credential extraction, production credential rotation, git history rewriting, or compliance certification claims.
• Do not bypass auth, validation, permissions, CORS, rate limits, sandboxing, or data protections as a workaround.
• Do not treat missing tools, unsupported targets, parse failures, or scanner timeouts as clean results.
• Do not run destructive git, database, credential, or deployment commands during scan mode.