Vulnerability Scanning

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

Mode	Use
full	Default local security scan; SBOM, hygiene, supply-chain, and licenses remain explicit
dependencies	Known vulnerable dependency checks
secrets	Secret scanning and git-tracked .env* checks
ci	GitHub Actions and CI workflow checks
supply-chain	Package-intake and malicious-package behavior checks
sast	Source-code security scanning
sbom	SBOM generation and optional SBOM vulnerability checks
hygiene	Repo security hygiene checks
remediation-prep	Group findings by likely fix strategy without editing

Scanner Selection

Evidence or request	Preferred scanner
Supported dependency manifests or lockfiles	OSV Scanner first, then native audit
bun.lock or bun.lockb	bun audit --json
package-lock.json	npm audit --json
pnpm-lock.yaml	pnpm audit --json
Python manifests	pip-audit
Rust manifests	cargo audit
Go or JVM manifests	OSV Scanner; add dedicated tooling only when implemented or direct-run and reported
Dockerfile, Compose, Terraform, Kubernetes, Helm	Trivy filesystem scan
Image target	Trivy image scan
License review	Add --include-licenses
Secrets-only or git repo	Gitleaks; TruffleHog for verified credential checks
Missing secret tools	Built-in metadata-only secret-pattern scan
New npm or PyPI dependency	GuardDog; optional OSV API lookup only when enabled or requested
GitHub Action intake	GuardDog, zizmor, action pinning checks
.github/workflows	zizmor and actionlint
Source security scan	Semgrep CE with --config=auto
SBOM requested	Syft, then Grype when vulnerability scan from SBOM is needed
Repo hygiene requested	OpenSSF Scorecard, noting network/API requirements

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.