owasp/cve-lite-cli

1. Repository shape

This is a TypeScript monorepo for an OWASP CLI security tool, plus a separate Docusaurus documentation website. The core product lives under src/, with end-to-end and unit coverage in tests/, example target projects in examples/, and public docs in website/. The repo is organized around a single local-first scanning engine rather than a server application.

2. Primary runtime boundary: the CLI

The entry point is src/index.ts, which wires command-line parsing, subcommands, scanning, reporting, remediation, and exit codes. The CLI supports multiple modes: normal dependency scanning, override hygiene auditing, advisory database sync, AI skill installation, and output generation. This is the main user-facing boundary and the place where all flows converge.

3. Core scan pipeline

The scan path starts with discovering project metadata and lockfiles, then parsing the dependency graph, then resolving advisories, then classifying and formatting findings. src/parsers/ handles package-manager-specific lock formats for npm, pnpm, Yarn, and Bun, while src/scanner.ts and src/scan/multi-folder-scan.ts orchestrate single-root and multi-root scans. The output of this pipeline is a normalized finding set used by the terminal, JSON, SARIF, CycloneDX, and HTML reporters.

4. Dependency graph and package-manager support

The parser layer is the architecture’s compatibility boundary. It translates different lockfile ecosystems into a common internal package graph so downstream components do not care whether the project is npm, pnpm, Yarn, or Bun. The repo also contains workspace-oriented and multi-package logic, which matters for monorepos and nested package roots.

5. Advisory lookup and offline support

Vulnerability data comes from OSV, with a local SQLite-backed advisory cache for offline scans. src/advisory/osv-advisory-source.ts, src/advisory/local-advisory-source.ts, src/advisory/local-db.ts, and src/advisory/osv-sync.ts form the advisory subsystem. The architectural split is important: online scans can query OSV directly, while offline scans read the local DB only, allowing air-gapped or restricted-network operation.

6. Remediation engine

A distinctive subsystem is remediation, not just detection. src/remediation/ computes package-manager-aware fix commands, parent-upgrade guidance for transitive npm issues, and validation around the lowest known safe version. This is where the tool turns advisories into actionable install/update commands rather than outputting raw CVE identifiers.

7. Usage-aware filtering

Optional usage analysis is a separate concern from lockfile scanning. src/usage/ performs source-level inspection to determine whether vulnerable packages are actually imported or reachable from application code. This is an opt-in noise reduction layer that sits after dependency scanning and before final reporting, because it is more expensive and less deterministic than pure lockfile analysis.

8. Override hygiene as a parallel product line

The src/overrides/ tree implements a second major feature set: auditing and fixing npm/pnpm/Yarn/Bun overrides and resolutions. It has its own parsing, context-building, detector rules (OA001–OA008), and fixer path. Architecturally, this is separate from vulnerability scanning but shares the same CLI and reporting infrastructure, and can emit its own audit log stream.

9. Output and reporting subsystem

Findings can be rendered into multiple consumable formats under src/output/: terminal output, JSON-like structured output, SARIF, CycloneDX, HTML dashboards, and multi-folder summaries. These are downstream adapters over the same normalized findings model, which keeps presentation logic isolated from scan logic. The HTML reporter is a local artifact generator; it does not depend on a web backend.

10. Auditability and change tracking

The src/audit-log/ subsystem emits NDJSON event streams for override changes and related workflows. This is a change-control boundary distinct from human-readable reports: reports summarize results, while audit logs capture structured events for traceability and automation.

11. Local utilities and cross-cutting helpers

src/utils/ contains shared concerns such as network access, filesystem helpers, baseline suppression/ratcheting, version handling, severity mapping, PR creation helpers, and output formatting support. These are cross-cutting modules that stabilize the CLI behavior but are not primary architectural domains by themselves.

12. Repository validation strategy

The tests/ tree is broad and architecture-revealing: it covers CLI integration, parsers, advisory sources, remediation, output formats, override rules, scanning behavior, and end-to-end fixtures. The large tests/fixtures/ and examples/ directories act as reproducible dependency graphs across package managers and project shapes, which is critical for validating lockfile parsing and remediation accuracy.

13. Docs and external-facing delivery

The website/ folder is a separate documentation application built with Docusaurus. It publishes how-it-works guides, case studies, API references, and workflow docs, and is the source of truth for public documentation. This is a documentation delivery boundary, not part of the runtime scanner.

14. Operational and release boundaries

GitHub Actions workflows cover CI, CodeQL, docs publishing, release packaging, and self-scan validation. The repo also includes an action.yml, indicating the CLI is packaged for GitHub Marketplace use. External dependencies that materially shape the architecture are OSV for advisories, local SQLite for offline mode, the package managers themselves for fix execution, and GitHub for CI/release distribution.