# lesis-lat/security-gate architecture

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

- Interactive diagram: https://gitdiagram.com/lesis-lat/security-gate
- Repository: https://github.com/lesis-lat/security-gate

## Overview

##### Project type and purpose
- This is an open‑source, CLI‑based “Security Gate” tool implemented in Perl.
- It’s packaged as a Docker image and a GitHub Action to enforce vulnerability policies on Dependabot, Code Scanning, and Secret Scanning alerts before merging or deploying code.
- Its purpose is to block CI/CD pipelines when configured alert thresholds are exceeded.

##### File structure
- Top‑level files:
- Dockerfile – builds the Docker image containing Perl runtime and the security‑gate script.
- action.yml – metadata to make this a reusable GitHub Action.
- security‑gate.pl – the main CLI entry point.
- cpanfile – declares CPAN module dependencies.
- lib/SecurityGate/Engine:
- Code.pm – logic to fetch and evaluate code scanning alerts via GitHub API.
- Dependencies.pm – logic to fetch and evaluate Dependabot alerts.
- Secrets.pm – logic to fetch and evaluate secret‑scanning alerts.
- lib/SecurityGate/Utils/Helper.pm – shared helper methods (API calls, formatting).
- .github/workflows – CI configuration (linting, testing, building Docker image, and security‑gate runs).
- tests/ – unit tests for each Engine module and overall behavior.

##### README for additional insights
- Describes how to configure environment variables (GITHUB_TOKEN, thresholds).
- Shows the flow: “checkout → pull Docker image → run container → specify flags → analyze alerts → succeed or fail.”
- Notes it’s published to GitHub Container Registry (ghcr.io/instriq/security‑gate).

a. Main components
- GitHub Repository & GitHub Actions runner
- GitHub Container Registry (Docker image host)
- Docker Host / Runner environment
- Security Gate container (Perl runtime + application code)
- GitHub Security Alerts APIs (Dependabot, Code Scanning, Secret Scanning)
- Local developer environment (Perl + CPAN modules) – optional
b. Relationships & data flow
1. Push or PR event triggers GitHub Actions workflow.
2. Runner pulls the security‑gate Docker image from ghcr.io.
3. Runner invokes `docker run` with environment variables (GITHUB_TOKEN, thresholds, flags).
4. Inside the container, `security‑gate.pl` uses Helper.pm to call GitHub REST APIs:
- /repos/{owner}/{repo}/dependency‑alerts
- /repos/{owner}/{repo}/secret‑scanning/alerts
- /repos/{owner}/{repo}/code-scanning/alerts
5. Each Engine module (Dependencies, Secrets, Code) processes the JSON response, counts severities, compares against thresholds.
6. The container exits with code 0 if all checks pass, non‑zero otherwise.
7. GitHub Actions reads the exit code: passes or fails the job.
8. (Optional) In local usage, developers run `perl security‑gate.pl` directly after installing CPAN dependencies.
c. Architectural patterns & design principles
- Modular design: separate Engines for each alert type, shared utilities for API calls.
- Single responsibility: each module handles one alert source.
- Containerization for environment consistency across CI.
- Declarative GitHub Action metadata for reusability.
d. Key technologies & libraries
- Perl 5, CPAN modules (HTTP::Tiny or similar, JSON parsing).
- Docker for packaging.
- GitHub REST API v3.
- GitHub Actions workflow syntax and GitHub Container Registry.

##### Elements
- Clear labels for:
- “GitHub Event Trigger”
- “GitHub Actions Runner”
- “Docker Image (ghcr.io/instriq/security-gate)”
- “Containerized Security Gate App”
- “Engine: Dependencies, Code, Secrets”
- “Helper Utilities”
- “GitHub Security Alerts APIs”
- “Exit Code → Action Status”
- Trigger → Runner → Pull Image → Run Container → API Calls → Response → Exit
- Green for containerized application components
- Yellow for external services (Container Registry)
- Gray for local dev environment (optional).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Repository Files"
        R1["Dockerfile"]:::repo
        R2["action.yml"]:::repo
        subgraph ".github/workflows"
            R3a["security-gate.yml"]:::repo
            R3b["linter.yml"]:::repo
            R3c["test-suite.yml"]:::repo
            R3d["docker-image.yml"]:::repo
            R3e["deploy-image.yml"]:::repo
        end
        R4["tests/"]:::repo
    end

    subgraph "User & CI Trigger Layer"
        A["GitHub Event Trigger"]:::github
    end

    subgraph "Execution Environment Layer"
        B["GitHub Actions Runner"]:::github
        C["Pull Docker Image"]:::github
        D["Container Registry\n(ghcr.io/instriq/security-gate)"]:::external
        E["Run Container\n(env vars)"]:::github
    end

    subgraph "Application Logic Layer"
        F["Containerized Security Gate App"]:::container
        subgraph "Perl Runtime + Libraries"
            G["CLI Entry Point\nsecurity-gate.pl"]:::container
            H["CPAN Dependencies\ n(cpanfile)"]:::container
        end
        subgraph "Shared Utilities"
            I["Helper Utilities"]:::container
        end
        subgraph "Engine Modules"
            J["Code Scanning Engine"]:::container
            K["Dependencies Engine"]:::container
            L["Secret Scanning Engine"]:::container
        end
    end

    subgraph "External Integration Layer"
        M["GitHub Security Alerts APIs"]:::github
    end

    N["Exit Code"]:::github
    O["Action Status\n(passed/failed)"]:::github
    P["Local Dev Env\n(Perl + CPAN)"]:::local

    %% Connections
    R1 --> B
    R2 --> B
    R3a --> B
    R3b --> B
    R3c --> B
    R3d --> B
    R3e --> B
    R4 --> B

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F

    F --> G
    F --> H
    G --> I
    H --> I
    I --> J
    I --> K
    I --> L

    J --> M
    K --> M
    L --> M

    M --> N
    N --> O

    P --> G

    %% Click Events
    click R1 "https://github.com/lesis-lat/security-gate/tree/main/Dockerfile"
    click R2 "https://github.com/lesis-lat/security-gate/blob/main/action.yml"
    click R3a "https://github.com/lesis-lat/security-gate/blob/main/.github/workflows/security-gate.yml"
    click R3b "https://github.com/lesis-lat/security-gate/blob/main/.github/workflows/linter.yml"
    click R3c "https://github.com/lesis-lat/security-gate/blob/main/.github/workflows/test-suite.yml"
    click R3d "https://github.com/lesis-lat/security-gate/blob/main/.github/workflows/docker-image.yml"
    click R3e "https://github.com/lesis-lat/security-gate/blob/main/.github/workflows/deploy-image.yml"
    click R4 "https://github.com/lesis-lat/security-gate/tree/main/tests/"
    click G "https://github.com/lesis-lat/security-gate/blob/main/security-gate.pl"
    click H "https://github.com/lesis-lat/security-gate/tree/main/cpanfile"
    click J "https://github.com/lesis-lat/security-gate/blob/main/lib/SecurityGate/Engine/Code.pm"
    click K "https://github.com/lesis-lat/security-gate/blob/main/lib/SecurityGate/Engine/Dependencies.pm"
    click L "https://github.com/lesis-lat/security-gate/blob/main/lib/SecurityGate/Engine/Secrets.pm"
    click I "https://github.com/lesis-lat/security-gate/blob/main/lib/SecurityGate/Utils/Helper.pm"

    %% Styles
    classDef github fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef container fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef external fill:#fff9c4,stroke:#333,stroke-width:1px
    classDef local fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef repo fill:#f0f4c3,stroke:#333,stroke-width:1px
```
