Snyk can be used with private source code management systems (SCMs) such as GitHub Enterprise installations via an applicative tunnel, referred to as the Snyk “Broker”. A Snyk Broker allows moderated access to a private SCM deployment, securely connecting Snyk to your locally managed code repositories. It keeps sensitive data such as your access tokens within the perimeter of your private network, while narrowing down SCM access to the bare minimum required for Snyk.
These instructions will get you up and running with a Snyk Broker, allowing your private SCM to connect to Snyk.io.
Snyk Broker currently supports the following SCMs:
- GitHub Enterprise
- Bitbucket Server
- On-premise GitLab deployment
- On-premise Jira
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 private SCM. On start-up it establishes a secure web socket connection to a Broker server running at https://broker.dev.snyk.io. Requests from Snyk to your private SCM and web-hook initiated requests from your private SCM to Snyk are sent over this tunnel.
The Broker 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.
The default provided white list allows only the following requests:
- Snyk.io is only allowed to fetch dependency manifest files and the Snyk policy file. All other requests are dropped.
- SCM web-hooks are only allowed if they notify of a relevant event (push to branch, pull request opened), AND the event data includes a dependency manifest file or a Snyk policy file. All other web-hooks are dropped.
In order to use Snyk with your SCM, Snyk will first need to enable Broker support for one of your Snyk organisations.
To request Broker support, contact email@example.com with the name of the organisation that you’d like to connect to your SCM.
Each Broker is identified by a UUID 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 setup
In order to interact with your GitHub.com or GitHub Enterprise repositories, Snyk needs to use a personal access token with “repo” scope.
To create a GitHub personal access token:
- log in to your GitHub.com or GitHub Enterprise account
- navigate to “/settings/tokens” in your web browser. e.g. for GitHub.com, go to https://github.com/settings/tokens
- click on the “Generate new token” button
- enter a description for the token, and select the “repo” scope
- click on the “Generate token” button
- securely save the token so that you can configure your Broker client with it
This GitHub token must be provided to the Broker client, which then identifies with it on requests as they are proxied from Snyk to your GitHub.com or GitHub Enterprise.
The GitHub token never leaves your network!
Bitbucket Server setup
In order to interact with your Bitbucket Server repositories, Snyk needs to use the credentials of a Bitbucket user. The username and password must be provided to the Broker client, which then identifies with these credentials on requests as they are proxied from Snyk to your Bitbucket Server deployment.
The Bitbucket Server credentials never leave your network!
In order to interact with your Gitlab projects, Snyk needs to use an access token with an
api scope. The access token must be provided to the broker client, which then identifies with these credentials on requests as they are proxied from Snyk to your Gitlab deployment.
The Gitlab access token never leaves your network!
First, create a new user with API access in your Jira instance that can be used by Snyk. These credentials need to be provided to the Broker client, which then identifies with these credentials on requests as they are proxied from Snyk to your Jira instance. Note that the Jira user credentials never leave your network. If you wish to authenticate with an API token, then provide the username (usually an email address) as the
JIRA_USERNAME and the API token as the
Next, you’ll need to generate a new Broker UUID token. Go to “Integrations” in your org settings area, then click on “Jira” in the list, and “Edit Settings”. If you are installing the Jira Broker for the first time, click on the link “For installation of Jira within a private network”.
Here, you can configure how Snyk will interact with the Jira instance. Click “generate” to create a new token for use in the Broker client.
For more information about setting up and integrating Snyk with Jira, please refer to the Jira integration documentation.
The Broker client is a web server which securely relays requests between Snyk’s servers and your repositories hosted on supported SCMs. It needs to run on a network which has both outbound internet access and access to your SCM.
The Broker client is best installed as a docker image. See the Dockerhub page for further details on installing and configuring your Broker client.
The Broker is an open source project hosted at GitHub.
Connect Snyk to your Brokered SCM
Once your Broker client is up and running, you can connect you Snyk account to your SCM in a secure manner.
- Important: log out of https://app.dev.snyk.io
- log back in to https://app.dev.snyk.io
- select the organisation that you’re using with your Broker
- navigate to the “Projects” page
- click on “Add Projects”
- you will be prompted to select the type of SCM - GitHub (for both GitHub.com or GitHub Enterprise) or Bitbucket Server, depending on your organisation’s settings
- if you choose GitHub, you will be prompted for GitHub.com permissions, which must be provided. This is required while the Broker is in early-access, but this access is not used
- you should see repositories from your Brokered SCM
If you do not see any repositories, you may need to click the “Refresh results” link.
If you see your GitHub.com repositories then log out, then log back in and try again.