# google/osv-scalibr architecture

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

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

## Overview

OSV-SCALIBR is an extensible software-composition-analysis library. Its principal workflow configures and runs a scan over filesystem or container inputs, extracts inventory, detects vulnerabilities, optionally enriches and annotates findings, and returns scan results; results can also be converted to SPDX. A separate guided-remediation capability proposes upgrade patches for transitive vulnerabilities. The README documents these capabilities and the scan workflow; sampled source was limited, so internal wiring beyond that documented flow is not asserted.

Main entry points: [`scalibr.go`](https://github.com/google/osv-scalibr/blob/main/scalibr.go) (Scan API), [`guidedremediation/guidedremediation.go`](https://github.com/google/osv-scalibr/blob/main/guidedremediation/guidedremediation.go) (Remediation workflow), [`enricher`](https://github.com/google/osv-scalibr/tree/main/enricher) (Finding enrichment), [`result/result.go`](https://github.com/google/osv-scalibr/blob/main/result/result.go) (Scan results)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scan["Scanning"]
  node_scan_api["Scan API<br/>[scalibr.go]"]
  node_fs_extract["Filesystem extraction"]
  node_container_extract["Container extraction<br/>[containerimage.go]"]
  node_inventory["Software inventory<br/>[inventory.go]"]
end

subgraph group_plugins["Analysis plugins"]
  node_detectors["Vulnerability detectors"]
  node_enrichers["Finding enrichment"]
  node_annotators["Inventory annotation"]
  node_plugins_config["Plugin configuration"]
end

subgraph group_results["Results and output"]
  node_scan_results["Scan results<br/>[result.go]"]
  node_proto["Result schema"]
  node_spdx["SPDX conversion<br/>[spdx.go]"]
  node_cli["Wrapper binary<br/>[scalibr.go]"]
end

subgraph group_remediation["Guided remediation"]
  node_remediation["Remediation workflow"]
  node_manifest["Manifest parsing"]
  node_vuln_resolution["Vulnerability resolution"]
  node_upgrade["Upgrade strategies"]
  node_patch_result["Upgrade patch<br/>[result.go]"]
end

subgraph group_integrations["External data"]
  node_osv{{"OSV vulnerability data"}}
  node_depsdev{{"deps.dev package data"}}
end

node_user(("Library caller"))

node_user -->|"configures and calls"| node_scan_api
node_scan_api -->|"selects plugins"| node_plugins_config
node_scan_api -->|"scans filesystem"| node_fs_extract
node_scan_api -->|"scans image"| node_container_extract
node_fs_extract -->|"extracts packages"| node_inventory
node_container_extract -->|"extracts packages"| node_inventory
node_scan_api -->|"runs detectors"| node_detectors
node_scan_api -->|"runs enrichers"| node_enrichers
node_scan_api -->|"runs annotators"| node_annotators
node_scan_api -->|"returns results"| node_scan_results
node_scan_results -->|"serializes as"| node_proto
node_scan_results -->|"converts inventory"| node_spdx
node_user -.->|"invokes optionally"| node_cli
node_cli -->|"runs scan"| node_scan_api
node_user -->|"requests patches"| node_remediation
node_remediation -->|"parses project files"| node_manifest
node_remediation -->|"resolves vulnerable dependencies"| node_vuln_resolution
node_remediation -->|"selects upgrade strategy"| node_upgrade
node_remediation -->|"produces patch"| node_patch_result
node_enrichers -.->|"queries vulnerability data"| node_osv
node_enrichers -.->|"queries package data"| node_depsdev

click node_scan_api "https://github.com/google/osv-scalibr/blob/main/scalibr.go"
click node_fs_extract "https://github.com/google/osv-scalibr/tree/main/extractor/filesystem"
click node_container_extract "https://github.com/google/osv-scalibr/blob/main/extractor/containerimage.go"
click node_inventory "https://github.com/google/osv-scalibr/blob/main/inventory/inventory.go"
click node_detectors "https://github.com/google/osv-scalibr/tree/main/detector"
click node_enrichers "https://github.com/google/osv-scalibr/tree/main/enricher"
click node_annotators "https://github.com/google/osv-scalibr/tree/main/annotator"
click node_plugins_config "https://github.com/google/osv-scalibr/tree/main/plugin"
click node_scan_results "https://github.com/google/osv-scalibr/blob/main/result/result.go"
click node_proto "https://github.com/google/osv-scalibr/tree/main/binary/proto"
click node_spdx "https://github.com/google/osv-scalibr/blob/main/converter/spdx/spdx.go"
click node_cli "https://github.com/google/osv-scalibr/blob/main/binary/scalibr/scalibr.go"
click node_remediation "https://github.com/google/osv-scalibr/blob/main/guidedremediation/guidedremediation.go"
click node_manifest "https://github.com/google/osv-scalibr/tree/main/guidedremediation/internal/manifest"
click node_vuln_resolution "https://github.com/google/osv-scalibr/tree/main/guidedremediation/internal/resolution"
click node_upgrade "https://github.com/google/osv-scalibr/tree/main/guidedremediation/internal/strategy"
click node_patch_result "https://github.com/google/osv-scalibr/blob/main/guidedremediation/result/result.go"

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_scan_api,node_fs_extract,node_container_extract,node_inventory toneBlue
class node_detectors,node_enrichers,node_annotators,node_plugins_config toneAmber
class node_scan_results,node_proto,node_spdx,node_cli toneMint
class node_remediation,node_manifest,node_vuln_resolution,node_upgrade,node_patch_result toneRose
class node_osv,node_depsdev,node_user toneIndigo
```

## Components

### Scanning

- [Scan API](https://github.com/google/osv-scalibr/blob/main/scalibr.go): `scalibr.go`
- [Filesystem extraction](https://github.com/google/osv-scalibr/tree/main/extractor/filesystem): `extractor/filesystem`
- [Container extraction](https://github.com/google/osv-scalibr/blob/main/extractor/containerimage.go): `extractor/containerimage.go`
- [Software inventory](https://github.com/google/osv-scalibr/blob/main/inventory/inventory.go): `inventory/inventory.go`

### Analysis plugins

- [Vulnerability detectors](https://github.com/google/osv-scalibr/tree/main/detector): `detector`
- [Finding enrichment](https://github.com/google/osv-scalibr/tree/main/enricher): `enricher`
- [Inventory annotation](https://github.com/google/osv-scalibr/tree/main/annotator): `annotator`
- [Plugin configuration](https://github.com/google/osv-scalibr/tree/main/plugin): `plugin`

### Results and output

- [Scan results](https://github.com/google/osv-scalibr/blob/main/result/result.go): `result/result.go`
- [Result schema](https://github.com/google/osv-scalibr/tree/main/binary/proto): `binary/proto`
- [SPDX conversion](https://github.com/google/osv-scalibr/blob/main/converter/spdx/spdx.go): `converter/spdx/spdx.go`
- [Wrapper binary](https://github.com/google/osv-scalibr/blob/main/binary/scalibr/scalibr.go): `binary/scalibr/scalibr.go`

### Guided remediation

- [Remediation workflow](https://github.com/google/osv-scalibr/blob/main/guidedremediation/guidedremediation.go): `guidedremediation/guidedremediation.go`
- [Manifest parsing](https://github.com/google/osv-scalibr/tree/main/guidedremediation/internal/manifest): `guidedremediation/internal/manifest`
- [Vulnerability resolution](https://github.com/google/osv-scalibr/tree/main/guidedremediation/internal/resolution): `guidedremediation/internal/resolution`
- [Upgrade strategies](https://github.com/google/osv-scalibr/tree/main/guidedremediation/internal/strategy): `guidedremediation/internal/strategy`
- [Upgrade patch](https://github.com/google/osv-scalibr/blob/main/guidedremediation/result/result.go): `guidedremediation/result/result.go`

### External data

- **OSV vulnerability data**
- **deps.dev package data**

### Other components

- **Library caller**

## Connections

- Library caller → Scan API: configures and calls
- Scan API → Plugin configuration: selects plugins
- Scan API → Filesystem extraction: scans filesystem
- Scan API → Container extraction: scans image
- Filesystem extraction → Software inventory: extracts packages
- Container extraction → Software inventory: extracts packages
- Scan API → Vulnerability detectors: runs detectors
- Scan API → Finding enrichment: runs enrichers
- Scan API → Inventory annotation: runs annotators
- Scan API → Scan results: returns results
- Scan results → Result schema: serializes as
- Scan results → SPDX conversion: converts inventory
- Library caller → Wrapper binary: invokes optionally
- Wrapper binary → Scan API: runs scan
- Library caller → Remediation workflow: requests patches
- Remediation workflow → Manifest parsing: parses project files
- Remediation workflow → Vulnerability resolution: resolves vulnerable dependencies
- Remediation workflow → Upgrade strategies: selects upgrade strategy
- Remediation workflow → Upgrade patch: produces patch
- Finding enrichment → OSV vulnerability data: queries vulnerability data
- Finding enrichment → deps.dev package data: queries package data