# pyupio/safety architecture

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

- Interactive diagram: https://gitdiagram.com/pyupio/safety
- Repository: https://github.com/pyupio/safety

## Overview

##### Project type and purpose
- This is an open-source, full-featured Command-Line Interface (CLI) tool named “Safety CLI.”
- Purpose: to scan Python dependency manifests (requirements.txt, Pipfile, pyproject.toml, system site-packages) and detect known vulnerabilities or malicious packages, then report or remediate them.

##### File structure
Top-level overview:
- safety/             ← Python package
– __main__.py       ← CLI entrypoint
– cli.py, commands  ← command routing
– scan/             ← core scanning engine & ecosystem adapters
– auth/             ← authentication flow & server
– events/           ← in-process event bus (pub/sub)
– alerts/           ← alert generation & GitHub integration
– formatters/       ← output formatting (JSON, HTML, text)
– tool/             ← abstractions for pip, poetry, uv, interceptors
– init/, firewall/  ← initialization & firewall support
- scripts/            ← release/build helpers
- entrypoint.sh       ← Docker entrypoint
- Dockerfile, devcontainer/ ← development & CI container configs
- .github/workflows/  ← CI/CD pipelines
- docs/, README.md    ← user guides & quickstart
- tests/              ← unit/integration tests organized by subsystem

##### README for additional insights
- Describes CLI commands (`safety scan`, `safety auth`, `safety system-scan`)
- Mentions integration points (CI/CD, GitHub Actions)
- Highlights output formats (JSON, SBOM, HTML, text)
- Points to an SLA and hosted services (authentication server)

a. Main components
1. CLI Interface & Command Dispatcher
2. Authentication Module & Remote Auth Server
3. File Finder & Ecosystem Adapters (pip, poetry, system)
4. DependencyResolver & Model Layer (tools, requirements objects)
5. Vulnerability Database (Safety DB, local cache or remote pull)
6. Policy Engine (safety-policy-template.yml)
7. Scan Engine (scanner core, validators, “fun mode”)
8. Events Bus (publish/subscribe) & Event Handlers
9. Alerts & Notifications (GitHub issues/PRs via alerts/github.py)
10. Output Formatters (JSON, SBOM, HTML, text) & Templating (Jinja2)
11. External Integrations (CI/CD pipelines, GitHub Actions)
12. Build & Deployment (Docker, devcontainer, GitHub workflows)

b. Relationships and data flow
1. User invokes `safety` CLI → CLI Interface module
2. Command Dispatcher routes to `scan` or `auth` subcommand
3. For scanning:
– File Finder locates requirement manifests
– Ecosystem Adapters parse dependencies → pass to Resolver
– Resolver builds in-memory dependency model
– Policy Engine applies allow/deny rules
– Scan Engine queries local or remote Safety DB for vulnerability data
– Events Bus emits “vulnerability_detected” events
– Event Handlers collect findings
– Alerts module may post GitHub issues/PRs via REST
– Formatters render final report (JSON/HTML/text)
– CLI outputs to STDOUT or writes files
4. For authentication:
– CLI calls Auth client → communicates over HTTPS to Auth Server
– Stores token locally for future CLI calls
5. Build & CI: GitHub workflows ➔ run tests, build binaries via scripts, package CLI

c. Architectural patterns & design principles
- Modular package structure by concern (Single Responsibility)
- Publish/Subscribe via in-process Event Bus (decoupling scan core from reporting)
- Adapter pattern for multiple ecosystems (pip, poetry, uv)
- Template pattern for output (formatters with common interface)
- CLI Routing (Command pattern)
- Separation of local vs. remote data (vulnerability DB caching)

d. Key technologies/frameworks
- Python >=3.7 (packaging via pyproject.toml)
- Click (or argparse) for CLI
- Jinja2 for templating alert PR/issue bodies & HTML output
- JSON Schema for SBOM output
- GitHub REST API for alerts integration
- Docker for containerized runs & devcontainer

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        ENTRY["Entrypoint (__main__.py)"]:::cli
        CLI["CLI Dispatcher (cli.py)"]:::cli
        CLI_UTILS["CLI Utils (cli_utils.py)"]:::cli
    end

    %% Auth Module
    subgraph "Authentication Module"
        direction TB
        AUTH_CLI["Auth CLI (auth/cli.py)"]:::cli
        AUTH_MAIN["Auth Main (auth/main.py)"]:::cli
        AUTH_SERVER["Auth Server (auth/server.py)"]:::external
        AUTH_MODELS["Auth Models (auth/models.py)"]:::datastore
        AUTH_UTILS["Auth Utils (auth/utils.py)"]:::core
    end

    %% Core Engine
    subgraph "Core Scanning Engine"
        direction TB
        FILE_FINDER["File Finder (file_finder.py)"]:::core
        HANDLERS["Finder Handlers (handlers.py)"]:::core
        subgraph "Ecosystem Adapters"
            direction TB
            ADAPTER_BASE["Base Adapter (base.py)"]:::core
            ADAPTER_PY_DEPS["Python Deps (dependencies.py)"]:::core
            ADAPTER_PY_MAIN["Python Adapter (main.py)"]:::core
            ADAPTER_TARGET["Target Adapter (target.py)"]:::core
        end
        RESOLVER["Resolver (resolver.py)"]:::core
        REQ_MODEL["Requirements Model (requirements.py)"]:::datastore
        TOOL_MODEL["Tool Model (tools.py)"]:::datastore
        VULN_MODEL["Vulnerability Model (vulnerabilities.py)"]:::datastore
        POLICY["Policy Engine (safety-policy-template.yml)"]:::datastore
        SCAN_MAIN["Scan Main (main.py)"]:::core
        INIT_SCAN["Init Scan (init_scan.py)"]:::core
        VALIDATORS["Validators (validators.py)"]:::core
        SCAN_MODELS["Scan Models (models.py)"]:::datastore
        RENDER["Scan Render (render.py)"]:::core
    end

    %% Events
    subgraph "Event Bus & Handlers"
        direction TB
        BUS["Event Bus (bus.py)"]:::core
        EV_BASE["Handler Base (base.py)"]:::core
        EV_COMMON["Common Handlers (common.py)"]:::core
        EV_TYPES["Event Types (types/base.py)"]:::datastore
        EV_UTILS["Event Utils (utils/)"]:::core
    end

    %% Alerts
    subgraph "Alerts & Notifications"
        direction TB
        ALERT_REQ["Requirements Alert (requirements.py)"]:::core
        ALERT_GH["GitHub Alert (github.py)"]:::external
        ALERT_UTILS["Alerts Utils (utils.py)"]:::core
        TEMPLATE_ISSUE["Issue Template (issue.jinja2)"]:::datastore
        TEMPLATE_PR["PR Template (pr.jinja2)"]:::datastore
    end

    %% Formatters
    subgraph "Output Formatters"
        direction TB
        FORMATTER_MAIN["Formatter Loader (formatter.py)"]:::core
        JSON_FMT["JSON Formatter (json.py)"]:::core
        HTML_FMT["HTML Formatter (html.py)"]:::core
        TEXT_FMT["Text Formatter (text.py)"]:::core
        BARE_FMT["Bare Formatter (bare.py)"]:::core
        SCREEN_FMT["Screen Formatter (screen.py)"]:::core
    end

    %% External Services
    subgraph "External Services & Integrations"
        direction TB
        VULN_DB["Vulnerability DB"]:::datastore
        GITHUB_API["GitHub API"]:::external
        CI_PIPELINE["CI/CD Pipelines"]:::build
    end

    %% Build & Deployment
    subgraph "Build & Deployment"
        direction TB
        DOCKERFILE["Dockerfile"]:::build
        ENTRYPOINT_SH["Entrypoint.sh"]:::build
        DEVCONTAINER[".devcontainer"]:::build
        GH_WORKFLOWS[".github/workflows"]:::build
    end

    %% Connections
    ENTRY --> CLI
    CLI --> CLI_UTILS

    CLI -->|scan command| FILE_FINDER
    FILE_FINDER --> HANDLERS
    HANDLERS --> ADAPTER_BASE
    ADAPTER_BASE --> ADAPTER_PY_DEPS
    ADAPTER_PY_DEPS --> ADAPTER_PY_MAIN
    ADAPTER_PY_MAIN --> ADAPTER_TARGET
    ADAPTER_TARGET --> RESOLVER
    RESOLVER --> REQ_MODEL
    RESOLVER --> TOOL_MODEL
    RESOLVER --> VULN_MODEL
    REQ_MODEL --> POLICY
    POLICY --> SCAN_MAIN
    SCAN_MAIN --> INIT_SCAN
    INIT_SCAN --> VALIDATORS
    VALIDATORS --> SCAN_MODELS
    SCAN_MODELS --> RENDER
    RENDER --> BUS
    BUS --> EV_BASE
    EV_BASE --> EV_COMMON
    EV_COMMON --> EV_TYPES
    EV_COMMON --> EV_UTILS
    EV_COMMON --> ALERT_REQ
    ALERT_REQ --> ALERT_GH
    ALERT_GH --> GITHUB_API
    BUS --> FORMATTER_MAIN
    FORMATTER_MAIN --> JSON_FMT
    FORMATTER_MAIN --> HTML_FMT
    FORMATTER_MAIN --> TEXT_FMT
    FORMATTER_MAIN --> BARE_FMT
    FORMATTER_MAIN --> SCREEN_FMT

    CLI -->|auth command| AUTH_CLI
    AUTH_CLI --> AUTH_MAIN
    AUTH_MAIN --> AUTH_SERVER
    AUTH_MAIN --> AUTH_MODELS
    AUTH_MAIN --> AUTH_UTILS

    CI_PIPELINE --> TESTS["Run Tests"]:::build
    CI_PIPELINE --> DOCKERFILE
    CI_PIPELINE --> ENTRYPOINT_SH

    %% Click Events
    click ENTRY "https://github.com/pyupio/safety/blob/main/safety/__main__.py"
    click CLI "https://github.com/pyupio/safety/blob/main/safety/cli.py"
    click CLI_UTILS "https://github.com/pyupio/safety/blob/main/safety/cli_utils.py"
    click AUTH_CLI "https://github.com/pyupio/safety/blob/main/safety/auth/cli.py"
    click AUTH_MAIN "https://github.com/pyupio/safety/blob/main/safety/auth/main.py"
    click AUTH_SERVER "https://github.com/pyupio/safety/blob/main/safety/auth/server.py"
    click AUTH_MODELS "https://github.com/pyupio/safety/blob/main/safety/auth/models.py"
    click AUTH_UTILS "https://github.com/pyupio/safety/blob/main/safety/auth/utils.py"
    click FILE_FINDER "https://github.com/pyupio/safety/blob/main/safety/scan/finder/file_finder.py"
    click HANDLERS "https://github.com/pyupio/safety/blob/main/safety/scan/finder/handlers.py"
    click ADAPTER_BASE "https://github.com/pyupio/safety/blob/main/safety/scan/ecosystems/base.py"
    click ADAPTER_PY_DEPS "https://github.com/pyupio/safety/blob/main/safety/scan/ecosystems/python/dependencies.py"
    click ADAPTER_PY_MAIN "https://github.com/pyupio/safety/blob/main/safety/scan/ecosystems/python/main.py"
    click ADAPTER_TARGET "https://github.com/pyupio/safety/blob/main/safety/scan/ecosystems/target.py"
    click RESOLVER "https://github.com/pyupio/safety/blob/main/safety/tool/resolver.py"
    click REQ_MODEL "https://github.com/pyupio/safety/blob/main/safety/models/requirements.py"
    click TOOL_MODEL "https://github.com/pyupio/safety/blob/main/safety/models/tools.py"
    click VULN_MODEL "https://github.com/pyupio/safety/blob/main/safety/models/vulnerabilities.py"
    click POLICY "https://github.com/pyupio/safety/blob/main/safety/safety-policy-template.yml"
    click BUS "https://github.com/pyupio/safety/blob/main/safety/events/event_bus/bus.py"
    click EV_BASE "https://github.com/pyupio/safety/blob/main/safety/events/handlers/base.py"
    click EV_COMMON "https://github.com/pyupio/safety/blob/main/safety/events/handlers/common.py"
    click EV_TYPES "https://github.com/pyupio/safety/blob/main/safety/events/types/base.py"
    click EV_UTILS "https://github.com/pyupio/safety/tree/main/safety/events/utils/"
    click ALERT_GH "https://github.com/pyupio/safety/blob/main/safety/alerts/github.py"
    click ALERT_REQ "https://github.com/pyupio/safety/blob/main/safety/alerts/requirements.py"
    click ALERT_UTILS "https://github.com/pyupio/safety/blob/main/safety/alerts/utils.py"
    click TEMPLATE_ISSUE "https://github.com/pyupio/safety/blob/main/safety/alerts/templates/issue.jinja2"
    click TEMPLATE_PR "https://github.com/pyupio/safety/blob/main/safety/alerts/templates/pr.jinja2"
    click FORMATTER_MAIN "https://github.com/pyupio/safety/blob/main/safety/formatter.py"
    click JSON_FMT "https://github.com/pyupio/safety/blob/main/safety/formatters/json.py"
    click HTML_FMT "https://github.com/pyupio/safety/blob/main/safety/formatters/html.py"
    click TEXT_FMT "https://github.com/pyupio/safety/blob/main/safety/formatters/text.py"
    click BARE_FMT "https://github.com/pyupio/safety/blob/main/safety/formatters/bare.py"
    click SCREEN_FMT "https://github.com/pyupio/safety/blob/main/safety/formatters/screen.py"
    click DOCKERFILE "https://github.com/pyupio/safety/tree/main/Dockerfile"
    click ENTRYPOINT_SH "https://github.com/pyupio/safety/blob/main/entrypoint.sh"
    click DEVCONTAINER "https://github.com/pyupio/safety/tree/main/.devcontainer/Dockerfile"
    click GH_WORKFLOWS "https://github.com/pyupio/safety/tree/main/.github/workflows/"

    %% Styles
    classDef cli fill:#D0E6FF,stroke:#2B6CB0,color:#2B6CB0
    classDef core fill:#E6FFFA,stroke:#2C7A7B,color:#2C7A7B
    classDef datastore fill:#FEF3C7,stroke:#B7791F,color:#B7791F
    classDef external fill:#FFF5F5,stroke:#C53030,color:#C53030
    classDef build fill:#EDF2F7,stroke:#4A5568,color:#4A5568
```
