# owasp/cve-lite-cli architecture

> Architecture diagram of the GitHub repository owasp/cve-lite-cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/owasp/cve-lite-cli
- Repository: https://github.com/owasp/cve-lite-cli

## Overview

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.

Main entry points: [`src/index.ts`](https://github.com/owasp/cve-lite-cli/blob/main/src/index.ts) (CLI entry), [`src/scanner.ts`](https://github.com/owasp/cve-lite-cli/blob/main/src/scanner.ts) (Scanner), [`src/output/write-outputs.ts`](https://github.com/owasp/cve-lite-cli/blob/main/src/output/write-outputs.ts) (Output write), [`src/overrides/api.ts`](https://github.com/owasp/cve-lite-cli/blob/main/src/overrides/api.ts) (Overrides API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_cli_entry["CLI entry<br/>command-line bootstrap<br/>[index.ts]"]
  node_cli_args["Arg parsing<br/>cli options<br/>[args.ts]"]
  node_scanner["Scanner<br/>scan orchestrator<br/>[scanner.ts]"]
  node_multi_scan["Multi-folder<br/>scan coordinator"]
  node_parsers["Parsers<br/>lockfile adapters<br/>[index.ts]"]
end

subgraph group_security["Security logic"]
  node_advisory_source["OSV source<br/>advisory lookup"]
  node_local_db[("Local DB<br/>sqlite cache<br/>[local-db.ts]")]
  node_osv_sync["OSV sync<br/>db sync<br/>[osv-sync.ts]"]
  node_usage_scan["Usage scan<br/>source analysis<br/>[scanner.ts]"]
  node_remediation["Remediation<br/>fix engine<br/>[fix-commands.ts]"]
  node_overrides_api["Overrides API<br/>override audit engine<br/>[api.ts]"]
  node_override_detectors["Detectors<br/>override rules<br/>[index.ts]"]
end

subgraph group_delivery["Delivery"]
  node_output_write["Output write<br/>report dispatcher<br/>[write-outputs.ts]"]
  node_html_report["HTML report<br/>local reporter<br/>[html-reporter.ts]"]
  node_sarif_report["SARIF<br/>structured export<br/>[sarif.ts]"]
  node_cyclonedx_report["CycloneDX<br/>sbom export<br/>[cyclonedx.ts]"]
  node_audit_log["Audit log<br/>ndjson stream<br/>[ndjson-writer.ts]"]
  node_website["Docs site<br/>docusaurus docs<br/>[index.md]"]
end

node_cli_entry -->|"parse"| node_cli_args
node_cli_entry -->|"scan"| node_scanner
node_cli_entry -->|"batch scan"| node_multi_scan
node_cli_entry -->|"override mode"| node_overrides_api
node_cli_entry -->|"sync advisories"| node_osv_sync
node_cli_entry -->|"render"| node_output_write
node_scanner -->|"load graph"| node_parsers
node_scanner -->|"query advisories"| node_advisory_source
node_scanner -->|"offline lookup"| node_local_db
node_scanner -.->|"optional filter"| node_usage_scan
node_scanner -->|"compute fixes"| node_remediation
node_multi_scan -->|"invoke"| node_scanner
node_osv_sync -->|"store"| node_local_db
node_overrides_api -->|"detect"| node_override_detectors
node_overrides_api -->|"emit events"| node_audit_log
node_overrides_api -->|"report"| node_output_write
node_output_write -->|"html"| node_html_report
node_output_write -->|"sarif"| node_sarif_report
node_output_write -->|"sbom"| node_cyclonedx_report
node_output_write -.->|"trace"| node_audit_log
node_website -.->|"document"| node_cli_entry

click node_cli_entry "https://github.com/owasp/cve-lite-cli/blob/main/src/index.ts"
click node_cli_args "https://github.com/owasp/cve-lite-cli/blob/main/src/cli/args.ts"
click node_scanner "https://github.com/owasp/cve-lite-cli/blob/main/src/scanner.ts"
click node_multi_scan "https://github.com/owasp/cve-lite-cli/blob/main/src/scan/multi-folder-scan.ts"
click node_parsers "https://github.com/owasp/cve-lite-cli/blob/main/src/parsers/index.ts"
click node_advisory_source "https://github.com/owasp/cve-lite-cli/blob/main/src/advisory/osv-advisory-source.ts"
click node_local_db "https://github.com/owasp/cve-lite-cli/blob/main/src/advisory/local-db.ts"
click node_osv_sync "https://github.com/owasp/cve-lite-cli/blob/main/src/advisory/osv-sync.ts"
click node_usage_scan "https://github.com/owasp/cve-lite-cli/blob/main/src/usage/scanner.ts"
click node_remediation "https://github.com/owasp/cve-lite-cli/blob/main/src/remediation/fix-commands.ts"
click node_overrides_api "https://github.com/owasp/cve-lite-cli/blob/main/src/overrides/api.ts"
click node_override_detectors "https://github.com/owasp/cve-lite-cli/blob/main/src/overrides/detectors/index.ts"
click node_output_write "https://github.com/owasp/cve-lite-cli/blob/main/src/output/write-outputs.ts"
click node_html_report "https://github.com/owasp/cve-lite-cli/blob/main/src/output/html-reporter.ts"
click node_sarif_report "https://github.com/owasp/cve-lite-cli/blob/main/src/output/sarif.ts"
click node_cyclonedx_report "https://github.com/owasp/cve-lite-cli/blob/main/src/output/cyclonedx.ts"
click node_audit_log "https://github.com/owasp/cve-lite-cli/blob/main/src/audit-log/ndjson-writer.ts"
click node_website "https://github.com/owasp/cve-lite-cli/blob/main/website/docs/index.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli_entry,node_cli_args,node_scanner,node_multi_scan,node_parsers toneBlue
class node_advisory_source,node_local_db,node_osv_sync,node_usage_scan,node_remediation,node_overrides_api,node_override_detectors toneAmber
class node_output_write,node_html_report,node_sarif_report,node_cyclonedx_report,node_audit_log,node_website toneMint
```

## Components

### Runtime

CLI and scan engine

- [CLI entry](https://github.com/owasp/cve-lite-cli/blob/main/src/index.ts): command-line bootstrap · Parses args and routes subcommands into scan, overrides, validate, and skill flows. · `src/index.ts`
- [Arg parsing](https://github.com/owasp/cve-lite-cli/blob/main/src/cli/args.ts): cli options · Command parsing, help text, config wiring, and command-specific validation. · `src/cli/args.ts`
- [Scanner](https://github.com/owasp/cve-lite-cli/blob/main/src/scanner.ts): scan orchestrator · Single-root scan orchestration and top-level finding pipeline. · `src/scanner.ts`
- [Multi-folder](https://github.com/owasp/cve-lite-cli/blob/main/src/scan/multi-folder-scan.ts): scan coordinator · Coordinates scans across multiple folders and aggregates results. · `src/scan/multi-folder-scan.ts`
- [Parsers](https://github.com/owasp/cve-lite-cli/blob/main/src/parsers/index.ts): lockfile adapters · Package-manager-specific lockfile and package graph normalization. · `src/parsers/index.ts`

### Security logic

Advisories, remediation, overrides, usage

- [OSV source](https://github.com/owasp/cve-lite-cli/blob/main/src/advisory/osv-advisory-source.ts): advisory lookup · Online OSV advisory access and severity classification boundary. · `src/advisory/osv-advisory-source.ts`
- [Local DB](https://github.com/owasp/cve-lite-cli/blob/main/src/advisory/local-db.ts): sqlite cache · Offline advisory store and local cache-backed lookup layer. · `src/advisory/local-db.ts`
- [OSV sync](https://github.com/owasp/cve-lite-cli/blob/main/src/advisory/osv-sync.ts): db sync · Synchronizes advisory data into the local offline database. · `src/advisory/osv-sync.ts`
- [Usage scan](https://github.com/owasp/cve-lite-cli/blob/main/src/usage/scanner.ts): source analysis · Optional code-level reachability analysis used to reduce noisy findings. · `src/usage/scanner.ts`
- [Remediation](https://github.com/owasp/cve-lite-cli/blob/main/src/remediation/fix-commands.ts): fix engine · Computes package-manager-aware fix commands and safe upgrade guidance. · `src/remediation/fix-commands.ts`
- [Overrides API](https://github.com/owasp/cve-lite-cli/blob/main/src/overrides/api.ts): override audit engine · Audits and fixes npm, pnpm, Yarn, and Bun overrides and resolutions. · `src/overrides/api.ts`
- [Detectors](https://github.com/owasp/cve-lite-cli/blob/main/src/overrides/detectors/index.ts): override rules · Rule set for override hygiene findings such as OA001 through OA008. · `src/overrides/detectors/index.ts`

### Delivery

Reporters, audit logs, docs

- [Output write](https://github.com/owasp/cve-lite-cli/blob/main/src/output/write-outputs.ts): report dispatcher · Dispatches normalized findings to terminal, JSON, SARIF, CycloneDX, HTML, and folder summaries. · `src/output/write-outputs.ts`
- [HTML report](https://github.com/owasp/cve-lite-cli/blob/main/src/output/html-reporter.ts): local reporter · Generates local HTML dashboards and multi-folder HTML summaries. · `src/output/html-reporter.ts`
- [SARIF](https://github.com/owasp/cve-lite-cli/blob/main/src/output/sarif.ts): structured export · Produces SARIF output for security tooling and platform ingestion. · `src/output/sarif.ts`
- [CycloneDX](https://github.com/owasp/cve-lite-cli/blob/main/src/output/cyclonedx.ts): sbom export · Exports findings into CycloneDX-compatible output. · `src/output/cyclonedx.ts`
- [Audit log](https://github.com/owasp/cve-lite-cli/blob/main/src/audit-log/ndjson-writer.ts): ndjson stream · Structured event stream for override changes and traceability. · `src/audit-log/ndjson-writer.ts`
- [Docs site](https://github.com/owasp/cve-lite-cli/blob/main/website/docs/index.md): docusaurus docs · Separate documentation application for public guidance and references. · `website/docs/index.md`

## Connections

- CLI entry → Arg parsing: parse · CLI bootstraps subcommands and options.
- CLI entry → Scanner: scan · Primary dependency scanning flow.
- CLI entry → Multi-folder: batch scan · Runs scans across multiple roots.
- CLI entry → Overrides API: override mode · Audits and fixes override data.
- CLI entry → OSV sync: sync advisories · Populates local advisory cache.
- CLI entry → Output write: render · Routes normalized results to reporters.
- Scanner → Parsers: load graph · Normalizes package-manager lockfiles into a common graph.
- Scanner → OSV source: query advisories · Looks up vulnerabilities from OSV when online.
- Scanner → Local DB: offline lookup · Uses local SQLite-backed advisory cache when offline.
- Scanner → Usage scan: optional filter · Applies usage-aware reachability filtering.
- Scanner → Remediation: compute fixes · Turns findings into actionable upgrade commands.
- Multi-folder → Scanner: invoke · Reuses single-root scan pipeline per folder.
- OSV sync → Local DB: store · Writes advisory data into local cache.
- Overrides API → Detectors: detect · Runs hygiene rules over override and resolution structures.
- Overrides API → Audit log: emit events · Produces structured change-control events.
- Overrides API → Output write: report · Shares the same reporting boundary as scan findings.
- Output write → HTML report: html · Generates local dashboard artifacts.
- Output write → SARIF: sarif · Produces SARIF export.
- Output write → CycloneDX: sbom · Produces CycloneDX export.
- Output write → Audit log: trace · Can stream structured audit events alongside reports.
- Docs site → CLI entry: document · Public docs explain CLI, scanning, remediation, and outputs.