# aboutcode-org/vulnerablecode architecture

> Architecture diagram of the GitHub repository aboutcode-org/vulnerablecode, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aboutcode-org/vulnerablecode
- Repository: https://github.com/aboutcode-org/vulnerablecode

## Overview

VulnerableCode is a Django-backed database and web/API for software-package vulnerabilities, with PURLs as a central package identifier. Its main workflow is to ingest advisory data from public sources, normalize and persist it, improve package/version impact information, then expose vulnerability results through the UI and API. The repository also includes VulnTotal, a CLI and datasource layer for checking packages across vulnerability providers. The tree and README establish these product areas; sampled excerpts confirm runner, pipeline, advisory, and model responsibilities, but not every route or integration detail.

Main entry points: [`vulnerabilities/models.py`](https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/models.py) (Vulnerability database), [`vulnerabilities/pipes/advisory.py`](https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/pipes/advisory.py) (Advisory persistence), [`vulntotal/datasources/__init__.py`](https://github.com/aboutcode-org/vulnerablecode/blob/main/vulntotal/datasources/__init__.py) (Vulnerability providers), [`vulnerabilities/tasks.py`](https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/tasks.py) (Run scheduler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["User access"]
  node_webui["Web UI<br/>[views.py]"]
  node_api["Vulnerability API<br/>[api.py]"]
end

subgraph group_ingestion["Advisory ingestion"]
  node_scheduler["Run scheduler<br/>[tasks.py]"]
  node_pipeline["Pipeline engine<br/>[__init__.py]"]
  node_source_importers["Source importers<br/>[apache_tomcat.py]"]
  node_legacy_import["Legacy import runner<br/>[import_runner.py]"]
  node_advisory_contract["Advisory data<br/>[importer.py]"]
end

subgraph group_analysis["Impact analysis"]
  node_improve_runner["Improve runner<br/>[improve_runner.py]"]
  node_improver["Improvement rules<br/>[valid_versions.py]"]
  node_scoring["Severity scoring"]
  node_oval["OVAL processing<br/>[lib_oval.py]"]
end

subgraph group_storage["Data and federation"]
  node_db[("Vulnerability database<br/>[models.py]")]
  node_advisory_persistence["Advisory persistence<br/>[advisory.py]"]
  node_federation["Federated export"]
end

subgraph group_cli["VulnTotal lookup"]
  node_vulntotal_cli["VulnTotal CLI<br/>[vulntotal_cli.py]"]
  node_provider_sources["Vulnerability providers<br/>[__init__.py]"]
  node_vc_source["VulnerableCode datasource<br/>[vulnerablecode.py]"]
  node_vendor_validation["Provider results<br/>[validator.py]"]
end

node_user(("Package user"))

node_user -->|"queries packages"| node_webui
node_user -->|"requests results"| node_api
node_webui -->|"reads vulnerability data"| node_db
node_api -->|"reads vulnerability data"| node_db
node_scheduler -->|"dispatches pipeline"| node_pipeline
node_scheduler -->|"dispatches legacy run"| node_legacy_import
node_pipeline -->|"imports advisories"| node_advisory_persistence
node_source_importers -->|"produces advisory data"| node_advisory_contract
node_legacy_import -->|"uses import contract"| node_advisory_contract
node_advisory_persistence -->|"writes advisory records"| node_db
node_improve_runner -.->|"runs improvement rules"| node_improver
node_improver -->|"reads package advisories"| node_db
node_advisory_persistence -->|"computes risk score"| node_scoring
node_oval -.->|"processes vulnerability data"| node_db
node_federation -.->|"exports vulnerability data"| node_db
node_vulntotal_cli -->|"dispatches datasource checks"| node_provider_sources
node_provider_sources -.->|"offers datasource"| node_vc_source
node_provider_sources -->|"uses result contract"| node_vendor_validation

click node_webui "https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/views.py"
click node_api "https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/api.py"
click node_db "https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/models.py"
click node_scheduler "https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/tasks.py"
click node_pipeline "https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/pipelines/__init__.py"
click node_source_importers "https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/importers/apache_tomcat.py"
click node_legacy_import "https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/import_runner.py"
click node_advisory_contract "https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/importer.py"
click node_advisory_persistence "https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/pipes/advisory.py"
click node_improve_runner "https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/improve_runner.py"
click node_improver "https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/improvers/valid_versions.py"
click node_scoring "https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/severity_systems.py"
click node_oval "https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/lib_oval.py"
click node_federation "https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/pipelines/exporters/federate_vulnerabilities.py"
click node_vulntotal_cli "https://github.com/aboutcode-org/vulnerablecode/blob/main/vulntotal/vulntotal_cli.py"
click node_provider_sources "https://github.com/aboutcode-org/vulnerablecode/blob/main/vulntotal/datasources/__init__.py"
click node_vc_source "https://github.com/aboutcode-org/vulnerablecode/blob/main/vulntotal/datasources/vulnerablecode.py"
click node_vendor_validation "https://github.com/aboutcode-org/vulnerablecode/blob/main/vulntotal/validator.py"

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_webui,node_api,node_user toneBlue
class node_scheduler,node_pipeline,node_source_importers,node_legacy_import,node_advisory_contract toneAmber
class node_improve_runner,node_improver,node_scoring,node_oval toneMint
class node_db,node_advisory_persistence,node_federation toneRose
class node_vulntotal_cli,node_provider_sources,node_vc_source,node_vendor_validation toneIndigo
```

## Components

### User access

- [Web UI](https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/views.py): `vulnerabilities/views.py`
- [Vulnerability API](https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/api.py): `vulnerabilities/api.py`

### Advisory ingestion

- [Run scheduler](https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/tasks.py): `vulnerabilities/tasks.py`
- [Pipeline engine](https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/pipelines/__init__.py): `vulnerabilities/pipelines/__init__.py`
- [Source importers](https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/importers/apache_tomcat.py): `vulnerabilities/importers/apache_tomcat.py`
- [Legacy import runner](https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/import_runner.py): `vulnerabilities/import_runner.py`
- [Advisory data](https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/importer.py): `vulnerabilities/importer.py`

### Impact analysis

- [Improve runner](https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/improve_runner.py): `vulnerabilities/improve_runner.py`
- [Improvement rules](https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/improvers/valid_versions.py): `vulnerabilities/improvers/valid_versions.py`
- [Severity scoring](https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/severity_systems.py): `vulnerabilities/severity_systems.py`
- [OVAL processing](https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/lib_oval.py): `vulnerabilities/lib_oval.py`

### Data and federation

- [Vulnerability database](https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/models.py): `vulnerabilities/models.py`
- [Advisory persistence](https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/pipes/advisory.py): `vulnerabilities/pipes/advisory.py`
- [Federated export](https://github.com/aboutcode-org/vulnerablecode/blob/main/vulnerabilities/pipelines/exporters/federate_vulnerabilities.py): `vulnerabilities/pipelines/exporters/federate_vulnerabilities.py`

### VulnTotal lookup

- [VulnTotal CLI](https://github.com/aboutcode-org/vulnerablecode/blob/main/vulntotal/vulntotal_cli.py): `vulntotal/vulntotal_cli.py`
- [Vulnerability providers](https://github.com/aboutcode-org/vulnerablecode/blob/main/vulntotal/datasources/__init__.py): `vulntotal/datasources/__init__.py`
- [VulnerableCode datasource](https://github.com/aboutcode-org/vulnerablecode/blob/main/vulntotal/datasources/vulnerablecode.py): `vulntotal/datasources/vulnerablecode.py`
- [Provider results](https://github.com/aboutcode-org/vulnerablecode/blob/main/vulntotal/validator.py): `vulntotal/validator.py`

### Other components

- **Package user**

## Connections

- Package user → Web UI: queries packages
- Package user → Vulnerability API: requests results
- Web UI → Vulnerability database: reads vulnerability data
- Vulnerability API → Vulnerability database: reads vulnerability data
- Run scheduler → Pipeline engine: dispatches pipeline (evidence: `vulnerabilities/tasks.py`)
- Run scheduler → Legacy import runner: dispatches legacy run (evidence: `vulnerabilities/tasks.py`)
- Pipeline engine → Advisory persistence: imports advisories (evidence: `vulnerabilities/pipelines/__init__.py`)
- Source importers → Advisory data: produces advisory data (evidence: `vulnerabilities/importers/apache_tomcat.py`)
- Legacy import runner → Advisory data: uses import contract (evidence: `vulnerabilities/import_runner.py`)
- Advisory persistence → Vulnerability database: writes advisory records (evidence: `vulnerabilities/pipes/advisory.py`)
- Improve runner → Improvement rules: runs improvement rules
- Improvement rules → Vulnerability database: reads package advisories (evidence: `vulnerabilities/improvers/valid_versions.py`)
- Advisory persistence → Severity scoring: computes risk score (evidence: `vulnerabilities/pipes/advisory.py`)
- OVAL processing → Vulnerability database: processes vulnerability data
- Federated export → Vulnerability database: exports vulnerability data
- VulnTotal CLI → Vulnerability providers: dispatches datasource checks (evidence: `vulntotal/vulntotal_cli.py`)
- Vulnerability providers → VulnerableCode datasource: offers datasource
- Vulnerability providers → Provider results: uses result contract
