# google/osv-scanner architecture

> Architecture diagram of the GitHub repository google/osv-scanner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/google/osv-scanner
- Repository: https://github.com/google/osv-scanner

## Overview

##### Main Components
- CLI Interface Layer:
– Includes the commands in the cmd/ directory (e.g., cmd/osv-scanner, cmd/osv-reporter) and integrations (GitHub actions in the actions/ directory). This is the entry point for user interactions.
- Scanning Engine:
– Core scanning logic is implemented in modules like pkg/osvscanner and internal/sourceanalysis. This subsystem is responsible for detecting dependency files (e.g., package.json, go.mod, pom.xml) in a given project.
- Vulnerability Database Interface:
– This module connects to the external OSV database (osv.dev) and retrieves vulnerability information. It likely abstracts a client from internal/clients and internal/osvdev.
- Dependency Resolution & Analysis:
– Modules under internal/resolution and internal/imodels correspond to constructing dependency graphs, processing lockfiles, and handling package-specific resolution.
- Remediation Subsystem:
– Under internal/remediation (and cmd/osv-scanner/fix) you find the guided remediation logic that recommends or auto-fixes dependency issues (in-place, relock, or override strategies).
- Output/Reporting Component:
– Implemented under internal/output and internal/reporter, this component formats scan results into various output formats such as HTML, SARIF, CycloneDX, machine-readable JSON, etc.
- Utility & Helper Components:
– Supporting functionalities like logging (internal/cmdlogger), configuration (internal/config), custom matching clients (internal/clients/clientimpl), and language-specific extraction (internal/scalibrextract).

##### Interactions and Data Flow
- User (via CLI or GitHub action) initiates a scan.
- The CLI calls the Scanning Engine to traverse directories and identify supported project files.
- The Scanning Engine uses dependency resolution modules to parse manifests and lockfiles.
- For each detected dependency, a query is made to the Vulnerability Database through the client interface.
- Once scan results are obtained, the Remediation Subsystem may be engaged (if remediation commands are issued) to recommend upgrades or adjustments.
- The Output/Reporting Component then formats the results and may output them to the console, generate HTML reports, or create SARIF annotations for CI integration.

##### Architectural Patterns & Design Principles
- Modular Design: The project is divided into well-defined packages (cmd, internal, pkg) which enforce separation of concerns.
- Extensibility: New package managers or remediation strategies can be incorporated (notice the structure in internal/clients and internal/remediation).
- Plugin-like APIs: OSV-Scanner integrates with OSV-Scalibr (as noted in the README) and can support additional languages and ecosystems.
- CI/CD and GitHub Workflows: The presence of .github/workflows files indicates automated testing, linting, and release processes.
- Containerization: With provided Dockerfiles and multi-platform release scripts (goreleaser), the system provides built-in support for containerized scanning.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        UI1["CLI Scanner (cmd/osv-scanner)"]
        UI2["CLI Reporter (cmd/osv-reporter)"]
        UI3["GitHub Actions Scanner (actions/scanner)"]
        UI4["GitHub Actions Reporter (actions/reporter)"]
    end

    %% Core Scanning Engine
    subgraph "Core Scanning Engine"
        SC1["Scanning Logic (pkg/osvscanner)"]
        SC2["Source Analysis (internal/sourceanalysis)"]
    end

    %% Dependency Resolution & Analysis
    subgraph "Dependency Resolution & Analysis"
        DR1["Dependency Resolution (internal/resolution)"]
        DR2["Ecosystem Models (internal/imodels)"]
    end

    %% Vulnerability Database Interface
    subgraph "Vulnerability Database Interface"
        DB1["OSV Database Client (internal/osvdev)"]
        DB2["Vulnerability Matcher (internal/clients/clientimpl/osvmatcher)"]
    end

    %% Remediation Subsystem
    subgraph "Remediation Subsystem"
        RM1["Guided Remediation (internal/remediation)"]
        RM2["CLI Remediation (cmd/osv-scanner/fix)"]
    end

    %% Output/Reporting Component
    subgraph "Output/Reporting Component"
        OP1["Output Formatting (internal/output)"]
        OP2["Reporting Logic (internal/reporter)"]
    end

    %% Utility & Helper Components
    subgraph "Utility & Helper Components"
        UT1["Logging (internal/cmdlogger)"]
        UT2["Configuration (internal/config)"]
        UT3["Language Extraction (internal/scalibrextract)"]
        UT4["Custom Matching (internal/clients/clientimpl)"]
    end

    %% Data Flow Connections
    UI1 -->|"initiates_scan"| SC1
    UI3 -->|"automated_scan"| SC1

    SC1 -->|"analyzes_source"| SC2
    SC1 -->|"resolves_deps"| DR1
    SC1 -->|"queries_vuln"| DB1
    SC1 -->|"matches_vuln"| DB2
    DR1 -->|"builds_graph"| DR2

    SC1 -->|"formats_output"| OP1
    SC1 -->|"reports_results"| OP2

    UI1 -->|"remediation_cmd"| RM2
    RM2 -->|"executes_remediation"| RM1
    RM1 -->|"remediation_result"| OP2

    UT1 --> SC1
    UT2 --> SC1
    UT3 --> SC1
    UT4 --> SC1

    %% Click Events for User Interface Layer
    click UI1 "https://github.com/google/osv-scanner/tree/main/cmd/osv-scanner"
    click UI2 "https://github.com/google/osv-scanner/tree/main/cmd/osv-reporter"
    click UI3 "https://github.com/google/osv-scanner/tree/main/actions/scanner"
    click UI4 "https://github.com/google/osv-scanner/tree/main/actions/reporter"

    %% Click Events for Core Scanning Engine
    click SC1 "https://github.com/google/osv-scanner/tree/main/pkg/osvscanner"
    click SC2 "https://github.com/google/osv-scanner/tree/main/internal/sourceanalysis"

    %% Click Events for Dependency Resolution & Analysis
    click DR1 "https://github.com/google/osv-scanner/tree/main/internal/resolution"
    click DR2 "https://github.com/google/osv-scanner/tree/main/internal/imodels"

    %% Click Events for Vulnerability Database Interface
    click DB1 "https://github.com/google/osv-scanner/tree/main/internal/osvdev"
    click DB2 "https://github.com/google/osv-scanner/tree/main/internal/clients/clientimpl/osvmatcher"

    %% Click Events for Remediation Subsystem
    click RM1 "https://github.com/google/osv-scanner/tree/main/internal/remediation"
    click RM2 "https://github.com/google/osv-scanner/tree/main/cmd/osv-scanner/fix"

    %% Click Events for Output/Reporting Component
    click OP1 "https://github.com/google/osv-scanner/tree/main/internal/output"
    click OP2 "https://github.com/google/osv-scanner/tree/main/internal/reporter"

    %% Click Events for Utility & Helper Components
    click UT1 "https://github.com/google/osv-scanner/tree/main/internal/cmdlogger"
    click UT2 "https://github.com/google/osv-scanner/tree/main/internal/config"
    click UT3 "https://github.com/google/osv-scanner/tree/main/internal/scalibrextract"
    click UT4 "https://github.com/google/osv-scanner/tree/main/internal/clients/clientimpl"

    %% Styles
    class UI1,UI2,UI3,UI4 ui
    class SC1,SC2 scanning
    class DR1,DR2 resolution
    class DB1,DB2 db
    class RM1,RM2 remediation
    class OP1,OP2 output
    class UT1,UT2,UT3,UT4 utility

    %% Class Definitions with Colors
    classDef ui fill:#a6cee3,stroke:#1f78b4,stroke-width:2px;
    classDef scanning fill:#b2df8a,stroke:#33a02c,stroke-width:2px;
    classDef resolution fill:#fb9a99,stroke:#e31a1c,stroke-width:2px;
    classDef db fill:#fdbf6f,stroke:#ff7f00,stroke-width:2px;
    classDef remediation fill:#cab2d6,stroke:#6a3d9a,stroke-width:2px;
    classDef output fill:#ffff99,stroke:#b15928,stroke-width:2px;
    classDef utility fill:#d9d9d9,stroke:#636363,stroke-width:2px;
```
