Using Snyk with GitHub Enterprise

Snyk can be used with private GitHub Enterprise installations via a custom proxy, referred to as the Snyk “broker”. A Snyk broker can also be used between Snyk and github.com itself, to reduce Snyk’s access to your GitHub repositories.

These instructions will get you up and running with a Snyk broker, allowing your private GitHub Enterprise to connect to Snyk.io.

How it works

The Snyk broker is made up of two web servers that proxy requests over a secure web socket connection. The broker “client” runs within your network, in a location with connectivity to your GitHub Enterprise. On start-up it establishes a secure web socket connection to a broker “server” running at https://broker.snyk.io. Requests from Snyk to your GitHub Enterprise and web-hook initiated requests from your GitHub Enterprise to Snyk are sent over this tunnel.

The client has a white list of allowed requests (expressed as a JSON file), ensuring that only requests which are required for Snyk to function are proxied. All other requests are dropped. Requests are filtered on both request path, and JSON body.

Snyk set-up

In order to use Snyk with your GitHub Enterprise, Snyk will first need to enable broker support for one of your Snyk organisations.

To request broker support, contact support@snyk.io with the name of the organisation that you’d like to connect to your GitHub Enterprise.

Each broker is identified by a unique token. Once broker support has been enabled for your organisation, you can access your unique broker token on the organisation’s settings page. This token is private, and must not be shared.

GitHub / GitHub Enterprise set-up

In order to interact with your GitHub Enterprise repositories, Snyk needs to use a GitHub Enterprise personal access token with “repo” and “admin:repo_hook” scopes.

To create a GitHub Enterprise token:

  1. log in to your GitHub Enterprise (or github.com, if that’s what you’re connecting via the broker)
  2. navigate to “/settings/tokens” in your web browser. e.g. for github.com, go to https://github.com/settings/tokens
  3. click on the “Generate new token” button
  4. enter a description for the token, and select the “repo” and “admin:repo_hook” scope
  5. click on the “Generate token” button
  6. save the token so that you can configure your broker with it

This GitHub token must be provided to the broker client, which then inserts it into requests as they are proxied from Snyk to your GitHub Enterprise.

The GitHub token never leaves your network!

Broker client

The broker client is a web server which securely relays requests between Snyk’s servers and your GitHub Enterprise. It needs to run on a network which has both outbound internet access and access to your GitHub Enterprise.

To set up and run a Snyk broker client:

  1. Install snyk-broker

    $ npm install -g snyk-broker

  2. Initialise the broker for use with Snyk

    $ broker init snyk

    This will generate two files:

    • “.env” : the brokers configuration
    • “accept.json” : the rules used to filter the requests being proxied to and from the Snyk servers
  3. Edit the “.env” file, providing the following details:

    Variable name Description
    BROKER_TOKEN Your unique broker token. This is displayed on the organisation settings page on snyk.io. This is a private token and must not be shared.
    GITHUB_TOKEN A GitHub Enterprise (or GitHub) personal access token for the user that Snyk will use to access your repositories.
    GITHUB The host (and port if necessary) of your private GitHub server. For github.com this should be set to github.com.
    GITHUB_API The url to the api of your private GitHub server. For github.com this should be set to api.github.com.
    GITHUB_RAW The url to access raw contents of files in git repos on your private GitHub server, excluding scheme. For github.com this should be set to raw.githubusercontent.com.
    BROKER_CLIENT_URL The url that your broker client is accessible at, which will be used for GitHub webhooks that notify Snyk of relevant changes to your repositories
    BROKER_SERVER_URL Set to https://broker.snyk.io. This is the url that your broker client will use to connect to Snyk’s broker server
    ACCEPT The path to the filter rules generated by broker snyk init in step 2 above. Set to accept.json.
    CA_CERT (optional) Path to the Certificate Authority root certificate that was used to sign your GitHub Enterprise’s TLS certificate. Only needed if your GitHub Enterprise uses a TLS certificate signed by a custom Certificate Authority

    The .env file itself is optional, all of these details may be provided to the broker as environment variables.

    Note: The .env file is generated with defaults appropriate for use with GitHub Enterprise. It also includes instructions for values to use with github.com.

  4. Start the broker

    $ broker client

    The broker can be started in debugging mode with:

    $ broker client --verbose

    Note: your BROKER_TOKEN will be output on stdout when the broker is started with --verbose.

Alternatively, the broker can also be installed as part of a private npm package. See https://github.com/Snyk/broker-snyk-client-example for an example of this.

Connect Snyk to your brokered GitHub Enterprise / GitHub

Once your broker client is up and running, you can connect you Snyk account to your GitHub Enterprise.

  1. Important: log out of https://snyk.io
  2. log back in to https://snyk.io
  3. select the organisation that you’re using with your broker
  4. navigate to the “Projects” page
  5. click on “Test my GitHub repositories”
  6. you will be prompted for GitHub permissions, which must be provided. This is required while the broker is in early-access, but this access is not used
  7. you should see repositories from your brokered GitHub Enterprise / GitHub

Troubleshooting

If you do not see any repositories, you may need to click the “Re-sync” button.

If you see your GitHub.com repositories then log out, then log back in and try again.

If you have access to both brokered and non-brokered Snyk organisations then you may need to “Re-sync” the first time you test repositories for each organisation.