VulnScan

A language-agnostic dependency vulnerability scanner CLI, written in Go.

⚠️ Scope of this build — read this first

The original spec for this project (12 ecosystems, 8+ vulnerability databases, SARIF/HTML/SBOM output, GitHub/GitLab/Jenkins CI integrations, a Bubble Tea TUI, malicious-package/typosquat detection, dependency graphs, fuzz tests, sample vulnerable repos, etc.) describes something on the scale of Trivy or osv-scanner — real multi-person-year projects. Generating thousands of lines of plausible-looking but non-functional stub code for all of that would be worse than useless.

Instead, this is a smaller, genuinely working core built around the same architecture, so it's an honest foundation rather than a mockup:

Implemented and real:

• Ecosystem detection by walking the project tree
• Real parsers: Go (go.mod), npm (package-lock.json, v1–v3 lockfile formats), Python (requirements.txt, pinned deps)
• Real OSV.dev API client (batch query + per-vulnerability detail fetch)
• A real CVSS v3.1 base-score calculator (for when an advisory only ships a vector, not a pre-bucketed severity)
• Concurrent worker-pool scanning with context cancellation and a progress indicator
• On-disk response cache with TTL (--offline mode uses cache only)
• Reports: colored terminal table, JSON, Markdown, CSV
• Security score, severity counts, remediation commands
• .vulnscan.json config (ignore list, concurrency, cache TTL, min severity)
• scan, fix (generates a review-before-you-run remediation script), cache clear, update-db (explains why there's no local DB to update), version

Deliberately not implemented (would need to be built next, and each is a real chunk of work, not a config flag):

• Rust/Java/.NET/PHP/Ruby/Docker/Actions/Terraform/K8s ecosystem parsers (the parsers.Parser interface is designed so each is a self-contained addition — see "Adding an ecosystem" below)
• Additional providers beyond OSV (GHSA direct, NVD, Trivy DB) — same story, see scanner.Provider
• SARIF/HTML output formats
• SBOM generation (CycloneDX/SPDX)
• A Bubble Tea/Lip Gloss interactive TUI (the current terminal output is colored plain text, not an interactive widget)
• Typosquatting/malicious-package heuristics, license detection, dependency confusion checks
• CI templates (GitHub Actions/GitLab/Jenkins/pre-commit) — trivial to add once you know your CI's specifics, but not included here
• Test suite (unit/integration/benchmark/fuzz)

One more important caveat: this code has not been compiled. The sandbox this was built in has no Go toolchain and no network access to install one, so I could not run go build or go vet. I did a careful manual read-through for type/import/syntax correctness, but please run go build ./... yourself before relying on it, and treat it as a strong first draft rather than tested software.

Usage

go build -o vulnscan ./cmd/vulnscan

./vulnscan scan .
./vulnscan scan ~/Projects/MyApp --format json --output report.json
./vulnscan scan . --format markdown --min-severity high
./vulnscan scan . --offline
./vulnscan fix .
./vulnscan cache clear
./vulnscan version

Exit code is 2 if any CRITICAL or HIGH finding is present (useful for CI gating), 1 on scan errors, 0 otherwise.

.vulnscan.json

{
  "ignore": ["GHSA-xxxx-xxxx-xxxx", "CVE-2021-23337"],
  "concurrency": 15,
  "cache_ttl_hours": 24,
  "min_severity": "MEDIUM"
}

Architecture

cmd/vulnscan/        entry point
internal/
  cli/                argument parsing + command dispatch
  detector/            walks the project tree, matches files to parsers
  parsers/             Parser interface + Go/npm/PyPI implementations
  models/              shared types (Dependency, Vulnerability, ScanResult)
  osv/                 OSV.dev provider + CVSS v3.1 scoring
  scanner/             orchestration: detect -> parse -> query -> score
  report/              terminal/JSON/Markdown/CSV renderers
  cache/               on-disk TTL cache for provider responses
  config/              .vulnscan.json loading

Everything is stdlib-only (no external Go modules), so go build works with zero network access to a module proxy.

Adding an ecosystem

Implement parsers.Parser (Ecosystem(), FileNames(), FileGlobs(), Parse(path) ([]models.Dependency, error)) in a new file under internal/parsers/, and call parsers.Register(YourParser{}) from an init(). Nothing else needs to change — the detector and scanner pick it up automatically.

Adding a vulnerability provider

Implement scanner.Provider (QueryBatch, FetchVuln) — see internal/osv/client.go for the reference implementation — and pass it into scanner.New([]scanner.Provider{osv.New(), yourProvider}, opts). Findings from multiple providers are merged automatically.

Adding an output format

Add a Write<Format>(w io.Writer, r *models.ScanResult) function to internal/report/, then wire it into the -format switch in internal/cli/cli.go.

Security score

There is no single industry-standard "security score" formula (npm audit, Trivy, and Snyk all compute this differently). VulnScan's is a simple, documented heuristic in internal/scanner/scanner.go (computeSecurityScore): start at 100, subtract weighted points per severity bucket, floor at 0. Treat it as a relative signal across scans of the same project over time, not an absolute industry benchmark.