Setting Up GitHub Advanced Security Scans with CodeQL on GitHub Enterprise Server in a VPC, VNet or a Private Network

Enabling GitHub Advanced Security (GHAS) Trial

If you haven't already enabled GitHub Advanced Security (GHAS) for your GitHub Enterprise Server, you may need to do so to use the features discussed in this guide. For instructions on how to enable the GHAS trial, please refer to this document.

Scripting languages like JavaScript, Python, and Ruby are often easier to start implementing with CodeQL for several reasons:

  • No Compilation Required: Unlike compiled languages such as C++ or Java, scripting languages do not require a separate build step. This means you can start running CodeQL scans on the source code without having to worry about successful compilation.

  • Simpler Dependency Management: If your project relies on private packages, these need to be pulled down during the build process for compiled languages. This adds an extra step to configure and can increase the complexity of the setup. With scripting languages, dependency management is often simpler and does not require a separate build step and connection to an external package repository.

To explore the complete range of languages and frameworks that CodeQL supports, please visit the official CodeQL documentation. For a comprehensive understanding of code scanning using CodeQL, we recommend reading this detailed guide on GitHub's documentation site.

Configuring Self-Hosted Runners

Installation of Runners

Follow the guide to set up self-hosted runners: Managing self-hosted runners.

Additional Utilities for CodeQL Action

Ensure the necessary utilities for running CodeQL builds are installed on the self-hosted runner.

VPC/VNet Allow-List Configuration

When using actions on a self-hosted runner in a GitHub Enterprise Server (GHES) within a VPC (AWS), VNet (Azure), or other private networks, configure the network to allow necessary outbound connections:

Outbound Connectivity Configuration

To ensure the successful operation of the self-hosted runner and CodeQL actions, the following network configurations must be in place:

  • Outbound connections on port 443 must be allowed. This is the standard port for HTTPS traffic, which is used for secure communication with GitHub's servers.
  • The proxy configuration, if a proxy is used in your network, must permit connectivity to the following domains. These domains are essential for various GitHub operations:
    • github.com: This is the main domain for GitHub's services.
    • api.github.com: This domain is used for GitHub's API, which is used by the self-hosted runner and CodeQL actions to interact with GitHub.
    • uploads.github.com: This domain is used for uploading data to GitHub, such as the results of CodeQL scans.

IP Allow-listing

You can allow specific IPs by running the following command to retrieve the current IP ranges:

curl https://api.github.com/meta

Note: IP-based filtering can be cumbersome; if possible, use domain-based filtering for greater flexibility and ease of management.

Using and Testing Actions for Third-Party APIs

While CodeQL is a powerful tool for security scanning, you might want to leverage other GitHub Actions that interact with third-party APIs to extend your CI/CD workflows. These actions can provide additional functionality, such as integrating with external tools, automating deployments, or managing cloud resources.

However, be aware that these actions might encounter issues due to network restrictions, especially in a VPC/VNet or private network setup. The ability of an action to successfully interact with a third-party API is highly dependent on the specific action being used and the network configuration.

Actions available on the GitHub Marketplace should provide a list of requirements and dependencies. It's recommended to review these before running the action to ensure your network setup allows the necessary connections. Additionally, since all actions are open-source, you can review the code to gain a deeper understanding of the dependencies and requirements.

Uploading CodeQL SARIF Results

CodeQL scans will need to upload SARIF results to your GitHub Enterprise Server. Even though the self-hosted runner is expected to have connectivity with the GitHub Enterprise Server, it's crucial to explicitly ensure this. Verify that the self-hosted runner can connect to api.<ghes-ip>.com, where <ghes-ip> is your own GitHub Enterprise Server IP or domain name. This is important as certain types of traffic or specific ports may be restricted even within the internal network, depending on your network configuration.

Handling Connectivity Issues

In scenarios where outbound connectivity to the CodeQL Action is not possible due to network restrictions, you can use the codeql-action-sync-tool. This tool is designed to download the necessary actions and synchronize them with your GitHub Enterprise Server (GHES) instance. By doing so, it ensures that the CodeQL action can function correctly even in environments with strict network constraints.