blog.lesis.lat

A simple and practical Security Gate for GitHub Security Alerts

September 16, 2024 | 13 Minute Read

Ensuring code security before it reaches production is essential. However, achieving this requires solutions that seamlessly integrate into the continuous integration and development process. As the complexity of applications grows and the urge for faster responses rises, the Shift Left approach becomes critical, shifting security to the earlier stages of the development cycle. In this article, we introduce and explore the concept of Security Gates, inspired by Quality Gates and aligned with the Shift Left methodology. We also present Security Gate, a practical solution that uses GitHub Actions to monitor repositories and enforce security measures by blocking the pipeline based on security alerts. We explore how this tool can be configured to serve as an effective security gate, aiming for the continuous security of the repository or project.

This publication is also available in: Portuguese

Background

In today’s software development landscape, security has become a cornerstone, integrated throughout every phase of the development life cycle. With the growing adoption of agile methodologies and DevOps practices, the concept of Shift Left has gained prominence, advocating for early testing and security validation during the initial stages of development. This approach aims to address vulnerabilities as early as possible, which not only reduces remediation costs but also minimizes the risks associated with security flaws that, if discovered too late, could severely compromise system integrity.

The Shift Left approach, by shifting security checks to the early stages of the development cycle, integrates security as an intrinsic component of the workflow, rather than relegating it to a later or isolated phase. This proactive integration enables development teams to detect and mitigate potential vulnerabilities before they proliferate, leading to more secure and robust software. Moreover, this practice aligns with the imperative to sustain agility in development processes while maintaining a strong defense against emerging threats.

In this context, Quality Gates function as critical checkpoints within the development pipeline, ensuring that only code meeting predefined quality standards advances to subsequent stages. Building upon this concept, the Security Gate represents a logical extension, concentrating specifically on security aspects. Serving as verification points within the CI/CD pipeline, Security Gates evaluate code against established security policies. They halt progress if the code fails to meet these criteria, thereby preventing the introduction of vulnerabilities into the production environment and ensuring that the final software complies with rigorous security standards.

Thus, the Security Gate actualizes this concept into a practical and accessible solution for GitHub. Designed to integrate automated security checks directly within the CI/CD pipeline, the Security Gate monitors the repository and halts pipeline progression based on security alerts, such as those generated by DependaBot, Code Scanning, and Secret Scanning. This approach aims to ensure that only code meeting established security criteria can advance through the pipeline, thereby reinforcing the Shift Left philosophy and contributing to continuous, proactive protection for the repository.

Objective

The Security Gate seeks to enhance security within the software development cycle by embedding a control mechanism directly into GitHub’s CI/CD pipeline. Rooted in the Shift Left philosophy and the principles of Quality Gates, this project adapts these concepts to address security concerns. Its objective is to ensure that only code meeting stringent security criteria is permitted to advance through the development and production phases.

The tool integrates with GitHub Actions and leverages security alerts from DependaBot, Code Scanning, and Secret Scanning as a basis for decision-making. The Security Gate enables the definition of vulnerability policies based on severity—such as the quantity of vulnerabilities categorized by threat severity—and operates proactively by halting the CI/CD pipeline if these policies are not adhered to.

To accomplish this objective, the Security Gate fulfills the following requirements:

  • Integration with GitHub Actions: for continuous monitoring of the repository, employing security alerts to ensure adherence to defined security policies;
  • Support for Security Alerts: from DependaBot, Code Scanning, and Secret Scanning, facilitating a thorough assessment of vulnerabilities and threats within the code;
  • Impact-Based Vulnerability Policy: such as the number of vulnerabilities categorized by severity, defined through severity threshold flags, to halt the CI/CD pipeline if these policies are not met;
  • Flexibility and Control: by enabling the configuration of which alert types to verify, through flags like --dependency-alerts, --secret-alerts, and --code-alerts, allowing users to tailor alert monitoring to their specific needs.

Introduction to Security Gate

The Security Gate is designed to integrate with software development pipelines, providing a practical solution for managing GitHub security alerts. Developed in Perl, the system leverages GitHub’s security alert capabilities and integrates with GitHub Actions, providing a mechanism to enforce security policies and ensure that code meets specified criteria before it progresses to production.

Overview

The Security Gate aims to meet the need for a structured security approach within CI/CD pipelines. Its goal is to provide a mechanism for monitoring and enforcing security policies based on alerts generated by GitHub. The tool offers extensive configuration options and is designed to align with the specific security requirements of varied projects.

Core Features

The Security Gate offers the following core features:

  • Dependencies Scanning

    This module leverages DependaBot alerts from GitHub to monitor vulnerabilities in project dependencies. It queries the GitHub API for open dependency alerts, classifies vulnerabilities by severity levels (critical, high, medium, and low), and compares these counts against predefined thresholds. If the thresholds are exceeded, the CI/CD pipeline can be halted, ensuring that vulnerabilities in third-party libraries do not compromise the integrity of the project.

  • Secrets Scanning

    The secret scanning feature integrates with GitHub’s Secret Scanning alerts to detect sensitive information that may have been inadvertently exposed in the repository. The tool retrieves and processes open secret alerts, providing detailed information on the total number of alerts and their specific locations within the code. Configuring thresholds for these alerts helps prevent the deployment of code containing exposed secrets, thereby enhancing the overall security of the project. Alerts based on secret detections are classified as high severity.

  • Code Scanning

    The code scanning module leverages GitHub’s Code Scanning alerts to detect and manage vulnerabilities within the codebase. The system aggregates open code scanning alerts, classifies them by severity, and assesses whether the number of alerts surpasses predefined thresholds. This methodology enables the resolution of code vulnerabilities prior to deployment to a production branch (e.g., main), thereby mitigating potential security risks.

Through its integration with GitHub Actions and the management of a range of security alerts, the Security Gate offers a mechanism for maintaining software security throughout the development life cycle.

GitHub Integration

The Security Gate is designed to integrate seamlessly with GitHub, enabling security checks to be executed directly within CI/CD pipelines. This integration facilitates the automatic monitoring and management of security alerts throughout the software development process.

To incorporate the Security Gate into GitHub workflows, it is a must to configure a GitHub Action to execute the tool during the CI/CD process. This setup requires adding a YAML workflow file to the repository and generating a GitHub token with the necessary permissions.

The operation of the Security Gate requires configuring a GitHub token with specific permissions (https://github.com/settings/tokens?type=beta). These permissions are needed to access and manage the various types of security alerts provided by GitHub.

Granular Token Permissions

The Security Gate requires the following permissions to operate:

  1. DependaBot Alerts:

    • Required Permission: security_events:read
    • Reason: The security_events:read permission is required for the SecurityGate::Engine::Dependencies module to access DependaBot alerts, enabling it to monitor vulnerabilities in the project’s dependencies.

  2. Secrets Scanning Alerts:

    • Required Permission: secrets:read
    • Reason: The SecurityGate::Engine::Secrets module requires the secrets:read permission to retrieve secret scanning alerts, enabling the identification of sensitive information that may be exposed in the repository.

  3. Code Analysis Alerts:

    • Required Permission: security_events:read
    • Reason: The security_events:read permission is required for the SecurityGate::Engine::Code module to access code analysis alerts and identify potential vulnerabilities in the codebase.

Summary of Required Permissions:

  • security_events:read: Required for reading alerts from Dependabot and code analysis.
  • secrets:read: Required for reading secret scanning alerts.

Additional Considerations:

  • The token must have, at least, read access to the repository.
  • For private repositories, the token must have explicit access to the repository to enable the retrieval of alerts.

When setting the token on GitHub, it is essential to ensure that these permissions are enabled to ensure the proper functioning of the Security Gate, while adhering to the principle of least privilege.

Adding the YAML File to the Repository

After setting the token, the next step is to add a YAML file to the repository. This file outlines the necessary steps for executing the Security Gate within the CI/CD process. The security-gate.yaml file should be placed in the .github/workflows/ directory and should contain the following content:

name: Security Gate - LESIS

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      MAX_CRITICAL: 1
      MAX_HIGH: 2
      MAX_MEDIUM: 3
      MAX_LOW: 4
      GITHUB_TOKEN: $
    steps:
    - name: Checkout repository
      uses: actions/checkout@v4

    - name: Pull Docker image from GitHub Container Registry
      run: docker pull ghcr.io/instriq/security-gate/security-gate:latest

    - name: Verify security alerts from dependabot
      run: |
        docker run ghcr.io/instriq/security-gate/security-gate:latest \
        -t $GITHUB_TOKEN \
        -r $ \
        --critical $MAX_CRITICAL \
        --high $MAX_HIGH \
        --medium $MAX_MEDIUM \
        --low $MAX_LOW \
        --dependency-alerts \
        --code-alerts \
        --secret-alerts

In this example, the workflow triggers the Security Gate on each push or pull request. The workflow checks out the code, configures environment variables with the specified thresholds for each type of alert, and then executes the Security Gate tool.

Integrating the Security Gate into the GitHub Actions workflow facilitates the enforcement of security policies, ensuring that only code meeting the specified criteria can advance through the CI/CD pipeline.

Demo

This demonstration illustrates the functionality of Security Gate within a CI/CD pipeline using a fork of a vulnerable Python project, Vulpy. The pipeline integrates Security Gate to detect security alerts associated with code vulnerabilities, outdated and vulnerable dependencies, and exposed secrets.

The same workflow configuration described earlier is employed in this demonstration.

To simulate security a exposed secrets scenario, fake exposed secrets were intentionally introduced in the vulpy.py file, as shown below:

GOOGLE_API_KEY = "AIzaSyDCvp5MTJLUdtBYEKYWXJrlLju3ysphChw"

STRIPE_API_KEY = "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"

SLACK_WEBHOOK = "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"

Additionally, older and vulnerable versions of dependencies were selected in the requirements.txt file to illustrate how Security Gate handles with an scenario of outdated and vulnerable dependencies:

cryptography==3.3.1
Flask==0.12.3
PyJWT==1.5.0

When the pipeline is triggered, either by a push or pull request, Security Gate scans the codebase for potential security issues related to code vulnerabilities, dependencies, and exposed secrets. The output from the workflow run includes the following summary:

As the number of high-severity alerts exceeded the predefined thresholds, the pipeline was automatically halted, preventing the deployment of potentially insecure code.

This example illustrates the functionality of Security Gate, which integrates security alerts within the development process using GitHub Actions. By analyzing code vulnerabilities, dependencies, and exposed secrets, the tool facilitates the monitoring of security risks in the CI/CD pipeline, ensuring that only code meeting specified security criteria proceeds to deployment.

Future Work

Currently, the Security Gate supports the verification of security alerts related to dependencies, secrets, and code, ensuring that projects meet predefined security criteria before deployment. However, there are several potential areas for enhancement that could be explored in future releases to extend its functionality and refine the user experience.

One area for consideration is extending support to additional repository management platforms, such as Bitbucket and GitLab.

Furthermore, there is potential to broaden the Security Gate integration to encompass alerts from other security tools. This would facilitate a more comprehensive analysis by integrating security data from multiple sources, thereby offering a more holistic view of the project’s security posture.

With these further enhancements, the Security Gate will be positioned to extend its security coverage and enhance its integration with software development processes, thereby supporting the continuous enforcement of security practices throughout the software lifecycle.

Conclusion

The Security Gate implementation is intended to enhance CI/CD pipeline security by integrating security alerts directly into the development process via GitHub Actions. The tool is designed to monitor and manage security risks associated with dependencies, secrets, and code, and to block the pipeline if the specified security criteria are not met.

To date, the Security Gate has demonstrated its ability to effectively integrate security checks, aligning with the Shift Left philosophy by shifting vulnerability detection to earlier stages. The tool provides a practical and accessible solution to ensure that only code meeting security criteria progresses through the CI/CD pipeline.

Future versions of the Security Gate are planned to enhance its functionality by incorporating support for additional repository management platforms, including GitLab and Bitbucket.

  • This article was written by Giovanni Sagioro: a Computer Science student, seeker of the Perl wisdom, and security researcher. Focused on application security, vulnerability discovery, and exploit development. As Larry Wall says—‘Easy things should be easy, and hard things should be possible’—so I’m trying to make the hard things possible.

Authorship

Giovanni Sagioro: a Computer Science student, seeker of the Perl wisdom, and security researcher. Focused on application security, vulnerability discovery, and exploit development. As Larry Wall says—‘Easy things should be easy, and hard things should be possible’—so I’m trying to make the hard things possible.

References

© 2024 Laboratory of Engineering Studies in Information Security