How google/osv-scanner works
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.