# trailofbits/it-depends architecture

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

- Interactive diagram: https://gitdiagram.com/trailofbits/it-depends
- Repository: https://github.com/trailofbits/it-depends

## Overview

##### Project type and purpose
- This is an open-source CLI tool (written in Python) that builds dependency graphs and SBOMs for arbitrary code repositories or package specs.
- It supports multiple ecosystems (Python, JavaScript, Rust, Go, C/C++), resolves native dependencies (via Ubuntu’s apt metadata or Docker), and audits vulnerabilities against OSV.

##### File structure
- Top-level CLI and packaging:
– `it_depends/__main__.py` & `it_depends/cli.py` → entrypoint and argument parsing
– `pyproject.toml`, `setup.py` → build and packaging config
- Core modules under `it_depends/`:
– Language handlers: `pip.py`, `npm.py`, `cargo.py`, `go.py`, `autotools.py`, `cmake.py`
– Native/OS handlers: `native.py`, `docker.py`, `ubuntu/apt.py`, `ubuntu/docker.py`
– Resolution engine: `resolver.py`, `dependencies.py`
– Persistence/cache: `db.py`
– SBOM export: `sbom.py`, `html.py`
– Graph generation: `graphs.py`
– Audit integration: `audit.py`
– VCS scanning: `vcs.py`
- Tests in `test/` validate each component; CI workflows automate lint, test, and publish.

##### README details
- Confirms multi-language support and reliance on external systems (npm, pip, cargo, apt-file, Docker, OSV).
- Mentions output formats: JSON, Graphviz/Dot, vis.js/HTML.
- Notes caching via local DB and parallelized tasks.

##### Main components and their interactions
– CLI Frontend
– Core Engine
- Command Parser (cli.py)
- Dependency Resolver (resolver.py)
- Language Adapters (pip, npm, cargo, go, autotools, cmake)
- Native/OS Adapter (native, docker, ubuntu)
- Database Cache (db.py)
– Audit Module (audit.py → OSV API)
– Exporters
- Graph Generator (graphs.py → Dot/vis.js)
- SBOM Generator (sbom.py → JSON/SPDX-in-dev)
- HTML Reporter (html.py)
– External Services
- Package Registries (PyPI, npm, crates.io, GOPROXY)
- OS Package Metadata (apt-file via Docker)
- Vulnerability DB (OSV)
1. User invokes CLI → passes flags to Command Parser
2. Parser invokes Core Engine → kicks off Resolution
3. Resolver calls appropriate Language Adapter(s) + Native Adapter → fetches manifest/deps
4. Resolver writes/reads cache in Database Cache
5. Full dependency graph flows into Exporters (Graph + SBOM + HTML)
6. If `--audit` passed → Graph/SBOM results flow into Audit Module → calls OSV → augments results
7. Final output → stdout/files
c. Architectural patterns & principles
– Plugin/Adapter pattern for each ecosystem (loose coupling)
– Single-process modular design, parallel task execution (concurrency with worker pools)
– Cache-aside pattern for immutable package metadata
d. Technologies & frameworks
– Python3 & pip
– SQLite (or similar) via `db.py` for caching
– Docker for native dependency resolution on non-Ubuntu hosts
– Graphviz/Dot or vis.js for visualization
– OSV REST API for auditing

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Frontend
    subgraph "CLI Frontend"
        CLI_main["__main__.py"]:::internal
        CLI_cli["cli.py"]:::internal
    end
    CLI_main -->|"invoke"| CLI_cli

    %% Core Engine
    subgraph "Core Engine"
        Parser["Command Parser"]:::internal
        Resolver["Dependency Resolver"]:::internal
        Deps["Dependencies"]:::internal
    end
    CLI_cli -->|"to Parser"| Parser
    Parser -->|"kickoff"| Resolver
    Resolver -->|"use dependency logic"| Deps

    %% VCS Scanner
    VCS["VCS Scanner"]:::internal
    Parser -->|"scan repos"| VCS

    %% Language Adapters
    subgraph "Language Adapters"
        Pip["Python Adapter (pip)"]:::internal
        Npm["JS Adapter (npm)"]:::internal
        Cargo["Rust Adapter (cargo)"]:::internal
        Go["Go Adapter"]:::internal
        Autotools["C/C++ Adapter (autotools)"]:::internal
        CMake["CMake Adapter"]:::internal
    end
    Resolver -->|"fetch manifest"| Pip
    Resolver -->|"fetch manifest"| Npm
    Resolver -->|"fetch manifest"| Cargo
    Resolver -->|"fetch manifest"| Go
    Resolver -->|"fetch manifest"| Autotools
    Resolver -->|"fetch manifest"| CMake

    %% Native / OS Adapters
    subgraph "Native/OS Adapters"
        Native["Generic Native"]:::internal
        Docker["Docker Adapter"]:::internal
        Apt["Ubuntu APT Metadata"]:::internal
        UbxDocker["Ubuntu Docker Wrapper"]:::internal
        UbxResolver["Ubuntu Resolver"]:::internal
    end
    Resolver -->|"fetch native deps"| Native
    Resolver -->|"docker calls"| Docker
    Docker -->|"uses"| Apt
    Docker -->|"uses"| UbxDocker
    Apt -->|"query"| UbxResolver

    %% Database Cache
    DB["Database Cache"]:::persistence
    Resolver -->|"read/write cache"| DB

    %% Exporters
    subgraph "Exporters"
        Graph["Graph Generator"]:::exporter
        SBOM["SBOM Generator"]:::exporter
        HTML["HTML Reporter"]:::exporter
    end
    Resolver -->|"generate graph"| Graph
    Resolver -->|"generate SBOM"| SBOM
    Resolver -->|"generate HTML"| HTML

    %% Audit Module
    Audit["Audit Module"]:::internal
    Graph -->|"audit input"| Audit
    SBOM -->|"audit input"| Audit
    Audit -->|"OSV REST API"| OSV_service

    %% Output
    Output["Stdout / Files"]:::external
    Graph -->|"output results"| Output
    SBOM -->|"output results"| Output
    HTML -->|"output results"| Output
    Audit -->|"augment & output"| Output

    %% Packaging & Build Config
    subgraph "Packaging & Build"
        PyProj["pyproject.toml"]:::external
        Setup["setup.py"]:::external
    end

    %% External Services
    subgraph "External Services"
        Registries["Package Registries\n(PyPI, npm, crates.io, GOPROXY)"]:::external
        OS_Pkg_Meta["OS Package Metadata\n(apt-file via Docker)"]:::external
        OSV_service["Vulnerability DB (OSV)"]:::external
    end
    Pip -->|"registry API"| Registries
    Npm -->|"registry API"| Registries
    Cargo -->|"registry API"| Registries
    Go -->|"registry API"| Registries
    Native -->|"apt-file"| OS_Pkg_Meta
    Docker -->|"apt-file"| OS_Pkg_Meta

    %% Click Events
    click CLI_main "https://github.com/trailofbits/it-depends/blob/master/it_depends/__main__.py"
    click CLI_cli "https://github.com/trailofbits/it-depends/blob/master/it_depends/cli.py"
    click Parser "https://github.com/trailofbits/it-depends/blob/master/it_depends/it_depends.py"
    click Resolver "https://github.com/trailofbits/it-depends/blob/master/it_depends/resolver.py"
    click Deps "https://github.com/trailofbits/it-depends/blob/master/it_depends/dependencies.py"
    click Pip "https://github.com/trailofbits/it-depends/blob/master/it_depends/pip.py"
    click Npm "https://github.com/trailofbits/it-depends/blob/master/it_depends/npm.py"
    click Cargo "https://github.com/trailofbits/it-depends/blob/master/it_depends/cargo.py"
    click Go "https://github.com/trailofbits/it-depends/blob/master/it_depends/go.py"
    click Autotools "https://github.com/trailofbits/it-depends/blob/master/it_depends/autotools.py"
    click CMake "https://github.com/trailofbits/it-depends/blob/master/it_depends/cmake.py"
    click Native "https://github.com/trailofbits/it-depends/blob/master/it_depends/native.py"
    click Docker "https://github.com/trailofbits/it-depends/blob/master/it_depends/docker.py"
    click Apt "https://github.com/trailofbits/it-depends/blob/master/it_depends/ubuntu/apt.py"
    click UbxDocker "https://github.com/trailofbits/it-depends/blob/master/it_depends/ubuntu/docker.py"
    click UbxResolver "https://github.com/trailofbits/it-depends/blob/master/it_depends/ubuntu/resolver.py"
    click DB "https://github.com/trailofbits/it-depends/blob/master/it_depends/db.py"
    click SBOM "https://github.com/trailofbits/it-depends/blob/master/it_depends/sbom.py"
    click HTML "https://github.com/trailofbits/it-depends/blob/master/it_depends/html.py"
    click Graph "https://github.com/trailofbits/it-depends/blob/master/it_depends/graphs.py"
    click Audit "https://github.com/trailofbits/it-depends/blob/master/it_depends/audit.py"
    click VCS "https://github.com/trailofbits/it-depends/blob/master/it_depends/vcs.py"
    click PyProj "https://github.com/trailofbits/it-depends/blob/master/pyproject.toml"
    click Setup "https://github.com/trailofbits/it-depends/blob/master/setup.py"

    %% Classes
    classDef internal fill:#cce5ff,stroke:#004085,color:#004085
    classDef persistence fill:#d4edda,stroke:#155724,color:#155724
    classDef exporter fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef external fill:#fff3cd,stroke:#856404,color:#856404
```
