# th3-j0k3r/supplyshield architecture

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

- Interactive diagram: https://gitdiagram.com/th3-j0k3r/supplyshield
- Repository: https://github.com/th3-j0k3r/supplyshield

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    CIUsers["CI/CD & Users Entry"]:::entry
    FlaskAPI["Flask API (Python/Flask)"]:::api
    SQS["Messaging (AWS SQS)"]:::msg
    CLI["CLI & Daemon Processes"]:::cli
    ImageScanner["Image Scanner Module"]:::scanner
    RepoScanner["Repository Scanner (with SAST)"]:::scanner
    PSQL[(PostgreSQL)]:::db
    DockerEnv["Container Environment (Docker Compose)"]:::container
    ExtIntegrations["External Integrations (Jira)"]:::external
    Cron["Scheduled Tasks & Cron Jobs"]:::cron

    CIUsers -->|"triggers"| FlaskAPI
    FlaskAPI -->|"queues"| SQS
    SQS -->|"delivers"| CLI
    CLI -->|"starts"| ImageScanner
    CLI -->|"starts"| RepoScanner
    ImageScanner -->|"stores"| PSQL
    RepoScanner -->|"stores"| PSQL
    ImageScanner -->|"notifies"| ExtIntegrations
    RepoScanner -->|"notifies"| ExtIntegrations
    CLI -->|"schedules"| Cron

    DockerEnv ---|"deploys"| FlaskAPI
    DockerEnv ---|"deploys"| CLI
    DockerEnv ---|"deploys"| SQS
    DockerEnv ---|"deploys"| PSQL

    classDef entry fill:#fffae6,stroke:#333,stroke-width:2px;
    classDef api fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef msg fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef cli fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef scanner fill:#ede7f6,stroke:#333,stroke-width:2px;
    classDef db fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef container fill:#d1ecf1,stroke:#333,stroke-width:2px;
    classDef external fill:#f0d9ff,stroke:#333,stroke-width:2px;
    classDef cron fill:#d4e6f1,stroke:#333,stroke-width:2px;

    click FlaskAPI "https://github.com/th3-j0k3r/supplyshield/blob/master/libinv/api/app.py"
    click FlaskAPI "https://github.com/th3-j0k3r/supplyshield/blob/master/libinv/api/graph.py"
    click SQS "https://github.com/th3-j0k3r/supplyshield/blob/master/libinv/sqs.py"
    click ImageScanner "https://github.com/th3-j0k3r/supplyshield/tree/master/libinv/scanners/image_scanner"
    click RepoScanner "https://github.com/th3-j0k3r/supplyshield/tree/master/libinv/scanners/repository_scanner"
    click CLI "https://github.com/th3-j0k3r/supplyshield/tree/master/libinv/cli"
    click PSQL "https://github.com/th3-j0k3r/supplyshield/blob/master/docker-compose.yml"
    click DockerEnv "https://github.com/th3-j0k3r/supplyshield/tree/master/Dockerfile"
    click DockerEnv "https://github.com/th3-j0k3r/supplyshield/blob/master/Dockerfile.crons"
    click DockerEnv "https://github.com/th3-j0k3r/supplyshield/blob/master/Dockerfile.daemon"
    click DockerEnv "https://github.com/th3-j0k3r/supplyshield/blob/master/docker-compose.yml"
    click ExtIntegrations "https://github.com/th3-j0k3r/supplyshield/blob/master/libinv/jira_integration.py"
    click ExtIntegrations "https://github.com/th3-j0k3r/supplyshield/tree/master/etc/third_party"
    click Cron "https://github.com/th3-j0k3r/supplyshield/blob/master/etc/scripts/metabase_cron.sh"
```
