How th3-j0k3r/supplyshield works
Project Type & Purpose
• SupplyShield is an orchestration engine focused on automating the security checks of your supply chain (dependencies, container images, etc.).
• Its key purpose is to integrate security scanning (both software composition analysis and container scanning) with CI/CD pipelines, using tools like grype, osv, cdxgen, and syft.
• It leverages Python and Flask for the API, PostgreSQL for persistence, and Docker for containerization alongside supporting SQS messaging.
Analyzing the File Structure
• Top-Level Directories & Files: Notice the presence of several Dockerfiles, a docker-compose.yml, and environment sample files (docker.env.sample). This demonstrates a containerized deployment strategy.
• The “libinv” directory contains the majority of the Python source, split into submodules – “api,” “cli,” and multiple “scanners” directories – indicating separation of concerns:
• The “api” module (including app.py, graph.py, and various HTML templates) likely handles the web-facing interfaces and healthchecks.
• The “cli” folder contains command-line tools used for starting daemons, initiating scans, or processing messages.
• The “scanners” submodules are where the scanning logic resides (for images, repositories, and SAST scanning). This suggests isolated but cooperative components, probably organized by scanning type.
• Supporting directories like “etc” include scripts (for cron jobs and third-party integrations). This underscores integrations necessary for scheduled tasks and external tool dependencies.
a. MAIN COMPONENTS:
• API Service: Represented by the Flask application housed in libinv/api (e.g., app.py, templates). Indicate its role in triggering health checks and handling incoming requests.
• Messaging Layer: Show the integration with AWS SQS – messages are sent to trigger the scanning pipeline.
• CLI Tools & Daemons: Include a separate block that highlights the CLI utilities and process-monitoring components (from libinv/cli and modules such as daemon.py). These often work alongside the API layer to execute scans and manage scheduling.
• Data Persistence/Storage: Represent PostgreSQL (as mentioned in the README) used for storing results, SBOMs, and potentially vulnerability data.
• External Integrations: Add components like Jira integration (libinv/jira_integration.py) and any third-party scripts found in etc/third_party.
b. COMPONENT RELATIONSHIPS AND INTERACTIONS:
• From the API service receiving user or CI/CD initiated requests to SQS for message distribution.
• From SQS messaging to the CLI/daemon processes that trigger the scanning workflows.
• From scanning modules (both image and repository scanning) pushing vulnerability data back to the persistence layer (PostgreSQL) or logging systems.
• Dependency links where, for instance, the API might call utilities or helper modules (like libinv/helpers.py) and where scanners might delegate to submodules (e.g., image_scanner -> sbom generation).
• Integration points with external systems (e.g., sending results to Jira or calling external services via API endpoints).
c. ARCHITECTURAL PATTERNS & DESIGN PRINCIPLES:
• Separation of concerns with distinct modules for API, CLI, and scanning.
• Orchestration of asynchronous workflows (SQS-prompted processing, cron jobs) and a modular design that allows different scanners to operate independently.
• Containerized deployment approach that isolates different functionality within Docker environments, coordinated via Docker Compose.
d. TECH STACK & IMPORTANT TECHNOLOGIES:
• Python (with Flask for the API).
• PostgreSQL as the database.
• Docker (Dockerfiles, docker-compose).
• AWS SQS for message queuing.
• External scanning tools/integrations as noted in the scanners’ modules (grype, osv, SBOM generators).
FINAL RECOMMENDATIONS
• That your design is both modular and detailed, reflecting each major function: message processing, scanning, and orchestration.
• Notes key to SupplyShield’s unique features like automated SBOM generation and integration with multiple scanning products.