How pyupio/safety works
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