How to Verify a Local Vulnerability Database Before Trusting Scan Results

A vulnerability scan is only as useful as the database profile behind it. Before treating a local result as release evidence, verify which snapshot was selected, whether its signature and digest passed, how complete the source is, and which input the scan actually evaluated. CodeRiskTools Scanner 3.1.1 documents this local-first workflow for a signed starter database and makes the coverage boundary explicit.

This guide is based on the official CodeRiskTools Scanner 3.1.1 release, the versioned README, and the public changelog. Those sources document the tool and release; they do not represent a scan of your repository, image, or production environment. A clean result is not proof that code is secure.

Why database verification belongs in the scan record

A finding is a relationship between an input inventory, a vulnerability database, matching rules, and a policy threshold. If any of those are missing from the record, a later reviewer cannot tell whether the result is reproducible. “The scan was clean” is not enough: the team also needs the scanner version, database identity, database hash, input hash, completeness label, and command-line policy.

The distinction matters especially when a default database is bootstrapped automatically. The operator may get a usable local snapshot without manually choosing a file, but the snapshot still needs to be identified and its limitations carried into the report.

What Scanner 3.1.1 documents

The 3.1.1 release describes a signed starter snapshot containing 243,381 real CVE/OSV records. It is explicitly partial, not a complete representation of the OSV source. The release also documents a future update path that can grow toward the stated full OSV source count of 813,101 records. The starter snapshot is therefore useful first-use coverage, not a promise that every advisory is present.

The release notes say the signed snapshot is verified with SHA-256 and Ed25519 checks. They also report a positive local smoke using pkg:bitnami/abantecart@1.3.1 against osv-partial-2026-07-23. That is release evidence for the published workflow, not a finding in your own software.

The minimum evidence bundle

• Tool identity: exact Scanner version and installation artifact digest.
• Database identity: snapshot ID, profile, source, record count, completeness label, database SHA-256, and signature verification result.
• Input identity: repository commit, image digest, or SBOM SHA-256 and creation time.
• Execution policy: command, output format, severity threshold, baseline or suppression inputs, and exit code.
• Interpretation: owner, remediation decision, and any limitations that prevent a clean conclusion.

Verify the installed scanner before the database

Start by pinning the public release asset rather than installing an unversioned package. The 3.1.1 release publishes both a wheel and source archive with SHA-256 digests. Compare the downloaded artifact to the digest shown on the release page, then install it in an isolated virtual environment. Confirm the executable reports the expected version:

python -m venv .venv
. .venv/bin/activate
python -m pip install --no-deps coderisktools_scanner-3.1.1-py3-none-any.whl
secret-scanner --version

Record the artifact filename and digest beside the scan report. This does not replace signature verification for the vulnerability snapshot; it establishes which scanner code produced the result.

Let first-use bootstrap fail closed

For a default vulnerability scan, the README documents automatic first-use download, verification, extraction, and activation of the pinned signed partial snapshot when the default database is absent. If verification fails, the archive is incomplete, the SQLite integrity check fails, or the snapshot identity does not match the manifest, stop. Do not substitute a random SQLite file and label the result “clean.”

If your workflow requires no network access during the scan itself, bootstrap and verify the database as a separate controlled preparation step. Then pass the verified local file explicitly. The documented --no-bootstrap control is useful when a missing default database must be treated as an operational failure rather than triggering acquisition.

Run an explicit local scan

For a repository, the documented shape is:

secret-scanner vuln scan \
  --root . \
  --database ~/.local/share/coderisktools/vuln-db/osv-partial.sqlite \
  --format json \
  --output reports/vulnerability-report.json

For an inventory already exported as CycloneDX, SPDX, or Syft JSON, use the SBOM boundary instead:

secret-scanner vuln scan \
  --sbom ./bom.json \
  --database ~/.local/share/coderisktools/vuln-db/osv-partial.sqlite \
  --format json \
  --output reports/sbom-vulnerability-report.json

Hash the root commit or SBOM before execution and save the command with the output. A database match supports triage and validation; it does not, by itself, prove exploitability in a deployed service.

Interpret coverage without overclaiming

Observed evidence	Defensible statement	Do not claim
Signature and digest verified	The selected snapshot passed its integrity checks.	Every advisory source is complete.
243,381-record starter profile selected	The scan used the documented partial starter coverage.	The project has no vulnerabilities outside that profile.
No matching record	No match was observed in this database and input.	The dependency is safe.
Finding returned	Investigate the package, advisory, version, and deployment context.	The service is exploitable without validation.
Exit code 3	Input or operation needs correction or investigation.	The scan was clean.

A five-step pre-release checklist

1. Pin. Record the exact scanner release and verify its published artifact digest.
2. Identify. Capture the database snapshot ID, record count, profile, source, and completeness state.
3. Verify. Confirm signature, compressed asset digest, expanded database digest, and SQLite integrity before activation.
4. Bind. Hash the repository commit, image digest, or SBOM and store it with the report.
5. Review. Keep partial-coverage warnings visible, triage findings with deployment context, and publish only redacted evidence.

Common database-review mistakes

• Confusing package installation with database verification: the wheel digest and snapshot digest are separate checks.
• Silently falling back to an old file: an older snapshot changes the evidence boundary and must be named.
• Hiding the partial label: dashboards and release notes should preserve completeness and source-count fields.
• Using a screenshot as provenance: retain machine-readable manifests, hashes, and command output.
• Calling no match “safe”: absence in a partial snapshot is not a security guarantee.

FAQ

Does the starter database contain invented test records?

The 3.1.1 release and README describe 243,381 real CVE/OSV records and explicitly distinguish the starter snapshot from synthetic fixtures. Verify the signed manifest and exact count for the release you install.

Can I choose a larger database later?

The release documents an update path that can build a larger snapshot toward the stated OSV source ceiling. Treat every updated snapshot as a new evidence identity and re-record its manifest, digest, profile, and completeness state.

Is a verified database enough for a security decision?

No. Verification establishes provenance and integrity for one input source. A decision still needs accurate inventory, version and reachability review, remediation context, configuration analysis, and human ownership.

Sources and next step

• Scanner 3.1.1 release — release assets, digests, tests, and database claims.
• Versioned README — commands, local database workflow, supported inputs, and limitations.
• Versioned changelog — database and SBOM changes in 3.1.1.
• Public Scanner repository — source and product-boundary documentation.

For a compact review of an AI-generated change, use the free 5-point AI code review checklist. For intent-bound local change review before merge, see the documented scope of the AI Change Firewall. Use the single CodeRiskTools comparison hub when you need scope context.