# tulasinayak/depscan architecture

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

- Interactive diagram: https://gitdiagram.com/tulasinayak/depscan
- Repository: https://github.com/tulasinayak/depscan

## Overview

depscan scans Python repositories for dependencies and vulnerabilities, locates vulnerable-package usage, then optionally assesses impact as affected, not affected, or needs review. The principal flow is scan → optional repository context → vulnerability check, exposed through CLI and Streamlit interfaces. Checks use deterministic code analysis and, where needed, an LLM; repository code is parsed, never executed. The README documents evaluation and suite workflows as additional product capabilities. Some subsystem internals are unsampled, so their uncertain connections are omitted.

Main entry points: [`depscan/orchestrator.py`](https://github.com/tulasinayak/depscan/blob/main/depscan/orchestrator.py) (Orchestrator), [`depscan/llm/client.py`](https://github.com/tulasinayak/depscan/blob/main/depscan/llm/client.py) (LLM client), [`depscan/cli.py`](https://github.com/tulasinayak/depscan/blob/main/depscan/cli.py) (CLI), [`depscan/agents/stepwise.py`](https://github.com/tulasinayak/depscan/blob/main/depscan/agents/stepwise.py) (Stepwise check)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_streamlit["Streamlit app<br/>[app.py]"]
  node_check_page["Check page<br/>[check_page.py]"]
  node_ui_components["UI components<br/>[components.py]"]
end

subgraph group_scan["Repository scanning"]
  node_repo_mapper["Repository mapper<br/>[repo_mapper.py]"]
  node_manifest_parser["Manifest parser"]
  node_cve_matcher["CVE matcher<br/>[cve_matcher.py]"]
  node_usage_locator["Usage locator<br/>[usage_locator.py]"]
  node_repo_context["Repository context<br/>[repo_context.py]"]
end

subgraph group_analysis["Impact analysis"]
  node_orchestrator["Orchestrator<br/>[orchestrator.py]"]
  node_code_index["Reachability index<br/>[codeindex.py]"]
  node_trigger_store["Trigger specs<br/>[triggers.py]"]
  node_stepwise["Stepwise check<br/>[stepwise.py]"]
  node_holistic["Holistic check<br/>[exploitability.py]"]
  node_grounding["Package grounding<br/>[grounding.py]"]
end

subgraph group_services["External services and state"]
  node_osv["OSV.dev"]
  node_llm_client["LLM client<br/>[client.py]"]
  node_llm_service["Local LLM"]
  node_cache[("Cache<br/>[cache.py]")]
end

subgraph group_results["Results and evaluation"]
  node_result_files["Saved results"]
  node_report["Report rendering<br/>[report.py]"]
  node_evaluation["Evaluation<br/>[evaluate.py]"]
  node_suite["Evaluation suites<br/>[suite.py]"]
end

node_user(("Engineer"))

node_user -->|"runs commands"| node_cli
node_user -->|"opens interface"| node_streamlit
node_streamlit -->|"routes to"| node_check_page
node_check_page -->|"renders via"| node_ui_components
node_cli -->|"invokes scans and checks"| node_orchestrator
node_ui_components -->|"invokes analysis"| node_orchestrator
node_orchestrator -->|"maps repository"| node_repo_mapper
node_repo_mapper -->|"parses manifests"| node_manifest_parser
node_orchestrator -->|"matches advisories"| node_cve_matcher
node_cve_matcher -->|"queries advisories"| node_osv
node_orchestrator -->|"locates usage"| node_usage_locator
node_orchestrator -->|"builds context"| node_repo_context
node_orchestrator -->|"runs six gates"| node_stepwise
node_stepwise -->|"checks reachability"| node_code_index
node_orchestrator -->|"constructs index"| node_code_index
node_stepwise -->|"uses trigger specs"| node_trigger_store
node_orchestrator -->|"loads trigger specs"| node_trigger_store
node_orchestrator -->|"runs holistic check"| node_holistic
node_orchestrator -->|"uses package facts"| node_grounding
node_stepwise -->|"asks narrow questions"| node_llm_client
node_holistic -->|"requests verdict"| node_llm_client
node_repo_context -->|"requests summary"| node_llm_client
node_trigger_store -->|"generates specs"| node_llm_client
node_llm_client -->|"sends prompts"| node_llm_service
node_cve_matcher -->|"caches advisories"| node_cache
node_orchestrator -->|"saves scan and verdicts"| node_result_files
node_cli -->|"shows results"| node_report
node_cli -->|"evaluates results"| node_evaluation
node_suite -->|"scores cases"| node_evaluation
node_suite -->|"runs suite analyses"| node_orchestrator

click node_cli "https://github.com/tulasinayak/depscan/blob/main/depscan/cli.py"
click node_streamlit "https://github.com/tulasinayak/depscan/blob/main/app.py"
click node_check_page "https://github.com/tulasinayak/depscan/blob/main/depscan/ui/check_page.py"
click node_ui_components "https://github.com/tulasinayak/depscan/blob/main/depscan/ui/components.py"
click node_repo_mapper "https://github.com/tulasinayak/depscan/blob/main/depscan/agents/repo_mapper.py"
click node_manifest_parser "https://github.com/tulasinayak/depscan/blob/main/depscan/parsers/python_manifests.py"
click node_cve_matcher "https://github.com/tulasinayak/depscan/blob/main/depscan/agents/cve_matcher.py"
click node_usage_locator "https://github.com/tulasinayak/depscan/blob/main/depscan/agents/usage_locator.py"
click node_repo_context "https://github.com/tulasinayak/depscan/blob/main/depscan/agents/repo_context.py"
click node_orchestrator "https://github.com/tulasinayak/depscan/blob/main/depscan/orchestrator.py"
click node_code_index "https://github.com/tulasinayak/depscan/blob/main/depscan/codeindex.py"
click node_trigger_store "https://github.com/tulasinayak/depscan/blob/main/depscan/triggers.py"
click node_stepwise "https://github.com/tulasinayak/depscan/blob/main/depscan/agents/stepwise.py"
click node_holistic "https://github.com/tulasinayak/depscan/blob/main/depscan/agents/exploitability.py"
click node_grounding "https://github.com/tulasinayak/depscan/blob/main/depscan/grounding.py"
click node_llm_client "https://github.com/tulasinayak/depscan/blob/main/depscan/llm/client.py"
click node_cache "https://github.com/tulasinayak/depscan/blob/main/depscan/cache.py"
click node_report "https://github.com/tulasinayak/depscan/blob/main/depscan/report.py"
click node_evaluation "https://github.com/tulasinayak/depscan/blob/main/depscan/evaluate.py"
click node_suite "https://github.com/tulasinayak/depscan/blob/main/depscan/suite.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_streamlit,node_check_page,node_ui_components toneBlue
class node_repo_mapper,node_manifest_parser,node_cve_matcher,node_usage_locator,node_repo_context toneAmber
class node_orchestrator,node_code_index,node_trigger_store,node_stepwise,node_holistic,node_grounding toneMint
class node_osv,node_llm_client,node_llm_service,node_cache toneRose
class node_result_files,node_report,node_evaluation,node_suite,node_user toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/tulasinayak/depscan/blob/main/depscan/cli.py): `depscan/cli.py`
- [Streamlit app](https://github.com/tulasinayak/depscan/blob/main/app.py): `app.py`
- [Check page](https://github.com/tulasinayak/depscan/blob/main/depscan/ui/check_page.py): `depscan/ui/check_page.py`
- [UI components](https://github.com/tulasinayak/depscan/blob/main/depscan/ui/components.py): `depscan/ui/components.py`

### Repository scanning

- [Repository mapper](https://github.com/tulasinayak/depscan/blob/main/depscan/agents/repo_mapper.py): `depscan/agents/repo_mapper.py`
- [Manifest parser](https://github.com/tulasinayak/depscan/blob/main/depscan/parsers/python_manifests.py): `depscan/parsers/python_manifests.py`
- [CVE matcher](https://github.com/tulasinayak/depscan/blob/main/depscan/agents/cve_matcher.py): `depscan/agents/cve_matcher.py`
- [Usage locator](https://github.com/tulasinayak/depscan/blob/main/depscan/agents/usage_locator.py): `depscan/agents/usage_locator.py`
- [Repository context](https://github.com/tulasinayak/depscan/blob/main/depscan/agents/repo_context.py): `depscan/agents/repo_context.py`

### Impact analysis

- [Orchestrator](https://github.com/tulasinayak/depscan/blob/main/depscan/orchestrator.py): `depscan/orchestrator.py`
- [Reachability index](https://github.com/tulasinayak/depscan/blob/main/depscan/codeindex.py): `depscan/codeindex.py`
- [Trigger specs](https://github.com/tulasinayak/depscan/blob/main/depscan/triggers.py): `depscan/triggers.py`
- [Stepwise check](https://github.com/tulasinayak/depscan/blob/main/depscan/agents/stepwise.py): `depscan/agents/stepwise.py`
- [Holistic check](https://github.com/tulasinayak/depscan/blob/main/depscan/agents/exploitability.py): `depscan/agents/exploitability.py`
- [Package grounding](https://github.com/tulasinayak/depscan/blob/main/depscan/grounding.py): `depscan/grounding.py`

### External services and state

- **OSV.dev**
- [LLM client](https://github.com/tulasinayak/depscan/blob/main/depscan/llm/client.py): `depscan/llm/client.py`
- **Local LLM**
- [Cache](https://github.com/tulasinayak/depscan/blob/main/depscan/cache.py): `depscan/cache.py`

### Results and evaluation

- **Saved results**
- [Report rendering](https://github.com/tulasinayak/depscan/blob/main/depscan/report.py): `depscan/report.py`
- [Evaluation](https://github.com/tulasinayak/depscan/blob/main/depscan/evaluate.py): `depscan/evaluate.py`
- [Evaluation suites](https://github.com/tulasinayak/depscan/blob/main/depscan/suite.py): `depscan/suite.py`

### Other components

- **Engineer**

## Connections

- Engineer → CLI: runs commands (evidence: `README.md`)
- Engineer → Streamlit app: opens interface (evidence: `README.md`)
- Streamlit app → Check page: routes to (evidence: `app.py`)
- Check page → UI components: renders via (evidence: `depscan/ui/check_page.py`)
- CLI → Orchestrator: invokes scans and checks (evidence: `depscan/cli.py`)
- UI components → Orchestrator: invokes analysis (evidence: `depscan/ui/components.py`)
- Orchestrator → Repository mapper: maps repository (evidence: `depscan/orchestrator.py`)
- Repository mapper → Manifest parser: parses manifests (evidence: `depscan/agents/repo_mapper.py`)
- Orchestrator → CVE matcher: matches advisories (evidence: `depscan/orchestrator.py`)
- CVE matcher → OSV.dev: queries advisories (evidence: `README.md`)
- Orchestrator → Usage locator: locates usage (evidence: `depscan/orchestrator.py`)
- Orchestrator → Repository context: builds context (evidence: `depscan/orchestrator.py`)
- Orchestrator → Stepwise check: runs six gates (evidence: `depscan/orchestrator.py`)
- Stepwise check → Reachability index: checks reachability (evidence: `depscan/agents/stepwise.py`)
- Orchestrator → Reachability index: constructs index (evidence: `depscan/orchestrator.py`)
- Stepwise check → Trigger specs: uses trigger specs (evidence: `depscan/agents/stepwise.py`)
- Orchestrator → Trigger specs: loads trigger specs (evidence: `depscan/orchestrator.py`)
- Orchestrator → Holistic check: runs holistic check (evidence: `depscan/orchestrator.py`)
- Orchestrator → Package grounding: uses package facts (evidence: `depscan/orchestrator.py`)
- Stepwise check → LLM client: asks narrow questions (evidence: `README.md`)
- Holistic check → LLM client: requests verdict (evidence: `depscan/agents/exploitability.py`)
- Repository context → LLM client: requests summary (evidence: `depscan/agents/repo_context.py`)
- Trigger specs → LLM client: generates specs (evidence: `depscan/triggers.py`)
- LLM client → Local LLM: sends prompts (evidence: `depscan/llm/client.py`)
- CVE matcher → Cache: caches advisories (evidence: `depscan/agents/cve_matcher.py`)
- Orchestrator → Saved results: saves scan and verdicts (evidence: `depscan/orchestrator.py`)
- CLI → Report rendering: shows results (evidence: `depscan/cli.py`)
- CLI → Evaluation: evaluates results (evidence: `depscan/cli.py`)
- Evaluation suites → Evaluation: scores cases (evidence: `depscan/suite.py`)
- Evaluation suites → Orchestrator: runs suite analyses (evidence: `depscan/suite.py`)
