# satwiksaxena1804-dev/vulnreach architecture

> Architecture diagram of the GitHub repository satwiksaxena1804-dev/vulnreach, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/satwiksaxena1804-dev/vulnreach
- Repository: https://github.com/satwiksaxena1804-dev/vulnreach

## Overview

VulnReach scans a Python project, resolves its dependencies and advisory data, builds a conservative call graph, and evaluates whether vulnerable symbols are reachable from application entry points. Users initiate scans through the CLI, desktop GUI, or programmatic API; results include evidence-backed verdicts and console, JSON, Markdown, or OpenVEX reports. Dependency discovery, OSV retrieval, symbol enrichment, and static call analysis are distinct stages. The API source shows the main orchestration; the README documents report formats and optional AI explanations. Some report and GUI wiring is supported by the source index rather than full excerpts.

Main entry points: [`vulnreach/api.py`](https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/api.py) (Analysis API), [`vulnreach/cli.py`](https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/cli.py) (CLI), [`vulnreach/gui.py`](https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/gui.py) (Desktop GUI), [`vulnreach/reachability.py`](https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/reachability.py) (Reachability Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_gui["Desktop GUI<br/>[gui.py]"]
  node_api["Analysis API<br/>[api.py]"]
end

subgraph group_analysis["Static Analysis"]
  node_scanner["Project Scanner<br/>[scanner.py]"]
  node_dependencies["Dependency Resolver<br/>[dependencies.py]"]
  node_resolution["Name Resolver<br/>[resolution.py]"]
  node_callgraph["Call Graph<br/>[callgraph.py]"]
  node_model["Analysis Data Model<br/>[model.py]"]
end

subgraph group_advisory["Advisory Intelligence"]
  node_osv["OSV Advisory Client<br/>[osv.py]"]
  node_versions["Version Matching<br/>[versions.py]"]
  node_symbols["Vulnerable Symbols<br/>[symbols.py]"]
end

subgraph group_results["Verdicts and Reports"]
  node_reachability["Reachability Engine<br/>[reachability.py]"]
  node_console["Console Report<br/>[console.py]"]
  node_json["JSON Report<br/>[json_report.py]"]
  node_markdown["Markdown Report<br/>[markdown.py]"]
  node_vex["OpenVEX Report<br/>[vex.py]"]
end

subgraph group_explain["Finding Explanations"]
  node_explain["Finding Explainer<br/>[explain.py]"]
end

node_user(("Project User"))
node_osvservice{{"OSV.dev"}}
node_llm{{"LLM Service"}}

node_user -->|"runs scan"| node_cli
node_user -->|"opens interface"| node_gui
node_user -->|"calls API"| node_api
node_cli -->|"starts analysis"| node_api
node_gui -->|"starts analysis"| node_api
node_api -->|"scans project"| node_scanner
node_api -->|"collects dependencies"| node_dependencies
node_api -->|"resolves names"| node_resolution
node_api -->|"builds graph"| node_callgraph
node_api -->|"queries advisories"| node_osv
node_api -->|"enriches advisories"| node_symbols
node_api -->|"analyzes findings"| node_reachability
node_osv -.->|"fetches advisories"| node_osvservice
node_reachability -->|"searches paths"| node_callgraph
node_reachability -->|"checks affected versions"| node_versions
node_cli -->|"renders output"| node_console
node_cli -->|"writes report"| node_json
node_cli -->|"renders report"| node_markdown
node_cli -->|"builds report"| node_vex
node_gui -->|"saves report"| node_json
node_cli -->|"explains findings"| node_explain
node_explain -.->|"requests narration"| node_llm

click node_cli "https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/cli.py"
click node_gui "https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/gui.py"
click node_api "https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/api.py"
click node_scanner "https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/scanner.py"
click node_dependencies "https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/dependencies.py"
click node_resolution "https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/resolution.py"
click node_callgraph "https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/callgraph.py"
click node_model "https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/model.py"
click node_osv "https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/osv.py"
click node_versions "https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/versions.py"
click node_symbols "https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/symbols.py"
click node_reachability "https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/reachability.py"
click node_console "https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/report/console.py"
click node_json "https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/report/json_report.py"
click node_markdown "https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/report/markdown.py"
click node_vex "https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/report/vex.py"
click node_explain "https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/ai/explain.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_cli,node_gui,node_api,node_user toneBlue
class node_scanner,node_dependencies,node_resolution,node_callgraph,node_model toneAmber
class node_osv,node_versions,node_symbols toneMint
class node_reachability,node_console,node_json,node_markdown,node_vex toneRose
class node_explain,node_osvservice,node_llm toneIndigo
```

## Components

### User Interfaces

- [CLI](https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/cli.py): `vulnreach/cli.py`
- [Desktop GUI](https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/gui.py): `vulnreach/gui.py`
- [Analysis API](https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/api.py): `vulnreach/api.py`

### Static Analysis

- [Project Scanner](https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/scanner.py): `vulnreach/scanner.py`
- [Dependency Resolver](https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/dependencies.py): `vulnreach/dependencies.py`
- [Name Resolver](https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/resolution.py): `vulnreach/resolution.py`
- [Call Graph](https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/callgraph.py): `vulnreach/callgraph.py`
- [Analysis Data Model](https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/model.py): `vulnreach/model.py`

### Advisory Intelligence

- [OSV Advisory Client](https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/osv.py): `vulnreach/osv.py`
- [Version Matching](https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/versions.py): `vulnreach/versions.py`
- [Vulnerable Symbols](https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/symbols.py): `vulnreach/symbols.py`

### Verdicts and Reports

- [Reachability Engine](https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/reachability.py): `vulnreach/reachability.py`
- [Console Report](https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/report/console.py): `vulnreach/report/console.py`
- [JSON Report](https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/report/json_report.py): `vulnreach/report/json_report.py`
- [Markdown Report](https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/report/markdown.py): `vulnreach/report/markdown.py`
- [OpenVEX Report](https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/report/vex.py): `vulnreach/report/vex.py`

### Finding Explanations

- [Finding Explainer](https://github.com/satwiksaxena1804-dev/vulnreach/blob/main/vulnreach/ai/explain.py): `vulnreach/ai/explain.py`

### Other components

- **Project User**
- **OSV.dev**
- **LLM Service**

## Connections

- Project User → CLI: runs scan (evidence: `README.md`)
- Project User → Desktop GUI: opens interface (evidence: `README.md`)
- Project User → Analysis API: calls API (evidence: `vulnreach/api.py`)
- CLI → Analysis API: starts analysis (evidence: `vulnreach/cli.py`)
- Desktop GUI → Analysis API: starts analysis (evidence: `vulnreach/gui.py`)
- Analysis API → Project Scanner: scans project (evidence: `vulnreach/api.py`)
- Analysis API → Dependency Resolver: collects dependencies (evidence: `vulnreach/api.py`)
- Analysis API → Name Resolver: resolves names (evidence: `vulnreach/api.py`)
- Analysis API → Call Graph: builds graph (evidence: `vulnreach/api.py`)
- Analysis API → OSV Advisory Client: queries advisories (evidence: `vulnreach/api.py`)
- Analysis API → Vulnerable Symbols: enriches advisories (evidence: `vulnreach/api.py`)
- Analysis API → Reachability Engine: analyzes findings (evidence: `vulnreach/api.py`)
- OSV Advisory Client → OSV.dev: fetches advisories (evidence: `README.md`)
- Reachability Engine → Call Graph: searches paths (evidence: `vulnreach/reachability.py`)
- Reachability Engine → Version Matching: checks affected versions (evidence: `vulnreach/reachability.py`)
- CLI → Console Report: renders output (evidence: `vulnreach/cli.py`)
- CLI → JSON Report: writes report (evidence: `vulnreach/cli.py`)
- CLI → Markdown Report: renders report (evidence: `vulnreach/cli.py`)
- CLI → OpenVEX Report: builds report (evidence: `vulnreach/cli.py`)
- Desktop GUI → JSON Report: saves report (evidence: `vulnreach/gui.py`)
- CLI → Finding Explainer: explains findings (evidence: `vulnreach/cli.py`)
- Finding Explainer → LLM Service: requests narration (evidence: `README.md`)
