How it works
The Broker workflow comprises these main components:
- Snyk SaaS backend (on Google Cloud Platform)/Broker server
- Snyk Broker client (a Docker image running on a virtual machine behind your firewall)
- Either a Git repo instance (Github Enterprise, Gitlab, Bitbucket Server) or Jira
Once implemented the components communicate similarly to the following diagram:
The Broker workflow is as described in the following steps:
- Your organization’s IT administrator installs Snyk Broker client, with a Docker image, on a host that has access to the on-prem Git repo as well as outbound access to https://broker.dev.snyk.io (the Broker server). It is preferable to install at least two instances for every integration planned for your deployment to support redundancy.
- Your organization’s admin configures the Broker client by providing a personal access token or credentials (from your repo or Jira account as described in Retrieve a unique Broker client token). The Broker client uses those credentials to create webhooks on particular events performed against your Git repos (for example, when a PR is created), which trigger events on the Snyk backend to run the appropriate tests (scans). The token or credentials must have the appropriate scope (as described in Retrieve a unique Broker client token) and be tied to a user or service account that has enough privileges to create these webhooks. These credentials remain within your perimeter at all times and are never sent to the Snyk SaaS backend. They are also obfuscated in the Broker client logs.
- Snyk support enables the Broker functionality, exposing a Snyk token in the Project settings area of the dev.snyk.io UI (and as further described in Retrieve a unique Broker client token). This token is used by the Broker client to authenticate itself whenever communicating with Snyk.
- Your admin initiates the Broker with a simple Docker command, which “activates” the container/s.
- When initiating, the Broker client container/s calls “home” (establishing contact with the Broker server at https://broker.dev.snyk.io) using the TLS protocol (through port 443 out/HTTPS, which must be allowed by your firewalls) and establishes a websocket (2-way connection) over that open pipe. Each running Broker client container opens a persistent bi-directional websocket connection to the Snyk servers that facilitates ongoing communication with your on-premise repo. The Broker client also establishes communication with your Git repo with an HTTPS connection.
- Once connection is established, your developers can each access dev.snyk.io to commence work, as outlined in the remainder of this process.
- When a developer clicks Add projects from the Integrations area of dev.snyk.io, dev.snyk.io sends a request to the Broker server to fetch the list of repositories available (HTTPS).
- The Broker server tunnels this request to the Broker client. The Broker client validates this request type against its approved list, and then relays that request to the customer’s Git repository only if included in that list.
- The response is the list of repositories to which Snyk has access. Access is determined by the token that the admin created from the Git repo, and is also based on the permissions of the account itself that was used to create that token. The response list is then returned to the Snyk backend for display to the end user from the UI.
- The user selects a repo (or repos) to import from the dev.snyk.io UI and clicks Import.
- Via the Broker server, dev.snyk.io then sends the Broker client a request to fetch a manifest file/s from the repositories that the developer selected. As before, the Broker server tunnels this request to the customer's Broker client. The Broker client validates the request against the approved list, and then sends that request to the customer's Git repo.
- The manifest file/s is then returned to the Snyk SaaS backend over a secure encrypted connection (Snyk uses TLS 1.2 protocol and above with strongest ciphers).
- Snyk extracts the dependency tree for the repo and matches the dependencies against our vulnerability database.
- In addition to the import and analysis, webhooks are also set (using HTTPS) on the specific repo to trigger on future events for new Pull Requests.
- The dependency tree and findings are displayed in the Snyk UI, and the notification mechanisms, monitoring, reporting, Slack integration and more are enabled.
- Whenever your developers submit new pull or merge requests, your Git notifies (HTTP) Snyk of that Pull Request by using the webhook that was set upon Import. The extraction mechanism is identical, but this time against the manifest file(s) in the PR, which is used to compare the delta with the base/branch.