Skip to main content

Set up the Semgrep Network Broker

The Semgrep Network Broker facilitates secure access between Semgrep and your private network. It accomplishes this by establishing a WireGuard VPN tunnel with the Semgrep infrastructure, then proxying inbound HTTP requests from Semgrep to your network through this tunnel. This approach allows Semgrep to interact with on-premise resources without exposing them to the public internet.

Examples of inbound traffic include:

  • Pull request (PR) or merge request (MR) comments
  • Webhooks
Tier availability

The Semgrep Network Broker is available to Enterprise tier users.

Prerequisites and feature availability​

  • The Semgrep Network Broker is a feature that must be enabled in your Semgrep organization (org) before setup. It is only available to paying customers. Contact the Semgrep support team to discuss having it enabled for your organization.
  • Docker must be installed on the server where you install the network broker.

Configure Semgrep Network Broker​

Ensure that you are logged in to the server where you want to run Semgrep Network Broker. Complete the following steps while logged in to that server.

  1. Create a config.yaml file similar to the following snippet. The steps required to generate values for the placeholders SEMGREP_LOCAL_ADDRESS, YOUR_PRIVATE_KEY, and YOUR_BASE_URL, are provided in subsequent steps of this guide.

    inbound:
      wireguard:
        localAddress: SEMGREP_LOCAL_ADDRESS
        privateKey: YOUR_PRIVATE_KEY
        peers:
          - publicKey: 4EqJwDZ8X/qXB5u3Wpo2cxnKlysec93uhRvGWPix0lg=
            endpoint: wireguard.semgrep.dev:51820
            allowedIps: fdf0:59dc:33cf:9be9:0000:0000:0000:0001/128
      heartbeat:
        url: http://[fdf0:59dc:33cf:9be9:0000:0000:0000:0001]/ping
      allowlist: []
      gitlab:
        baseUrl: YOUR_BASE_URL

    The publicKey value should be entered precisely as follows:

    4EqJwDZ8X/qXB5u3Wpo2cxnKlysec93uhRvGWPix0lg=

  2. The broker requires a WireGuard keypair to establish a secure connection. To generate your private key YOUR_PRIVATE_KEY:

    1. Determine the network broker version you want to use. The format should be similar to v0.14.0.

    2. Run the following command in the CLI to generate your private key, replacing the placeholder with the network broker version number:

      docker run ghcr.io/semgrep/semgrep-network-broker:VERSION_NUMBER genkey

  3. Run the following command in the CLI to generate your public key, replacing the placeholders with your private key generated in the previous step and the network broker version number:

    echo `YOUR_PRIVATE_KEY` | sudo docker run -i ghcr.io/semgrep/semgrep-network-broker:VERSION_NUMBER pubkey
    Key sharing

    Your public key is safe to share. Do not share your private key with anyone, including Semgrep.

  4. Update the config.yaml file with your private key:

    inbound:
      wireguard:
        localAddress: SEMGREP_LOCAL_ADDRESS
        privateKey: YOUR_PRIVATE_KEY
        ...

  5. Add your public key to the Semgrep AppSec Platform:

    1. Log in to Semgrep AppSec Platform.
    2. Navigate to Settings > Broker.
    3. Paste your public key and click Add Public Key.

    Screenshot of Semgrep AppSec Platform's Network Broker page

  6. Update the config.yaml by replacing YOUR_BASE_URL with your GitLab or GitHub URL:

    # for GitLab 
    gitlab:
      baseUrl: <https://gitlab.exampleCo.net/api/v4>

    # for GitHub 
    github:
      baseUrl: <https://github.exampleCo.com/api/v3>

  7. Convert your deployment ID to hexadecimal for use in creating your deployment's local address SEMGREP_LOCAL_ADDRESS. You can use a tool such as Decimal to Hexadecimal converter if needed.

    fdf0:59dc:33cf:9be8:0:DEPLOYMENT_ID:0:1

    Update the localAddress field of config.yaml; 

    inbound:
      wireguard:
        localAddress: fdf0:59dc:33cf:9be8:0:DEPLOYMENT_ID:0:1

  8. Run the following command to start Semgrep Network Broker with your updated configuration file:

    sudo docker run -d -it --rm -v $(pwd):/emt ghcr.io/semgrep/semgrep-network-broker:VERSION_NUMBER -c /emt/config.yaml

Check Semgrep Network Broker logs​

You can check the logs for Semgrep Network Broker by running:

sudo docker logs CONTAINER_ID