How lesis-lat/security-gate works
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).