Snyk Broker Code Agent
This feature is currently in Beta. Please contact your CSM if you are interested in participating.
You can natively connect Snyk Code to your local git server. This allows customers who are using a self-hosted git provider to find, prioritize, and fix potential vulnerabilities in their first-party code.

Code access components

  • Broker server: Running on Snyk SaaS backend
  • Broker client: A Docker image deployed in your infrastructure.
  • Code agent: Another Docker image that is deployed in your infrastructure. Note: Code agent is only supported with Snyk Broker v4.108.0 and later versions. If you have a running Broker client, pull the latest update.
The Broker client and code agent components are deployed in your infrastructure, creating two separate services, responsible for cloning local repositories in a secured manner and sending the associated information to Snyk.
The Broker client provides the Agent with the connection details. The Agent uses these details to connect to your local git repository, clone the relevant files, and send the results through the brokered communications using callbacks. The brokered communication happens when a Broker client connects (using your Broker ID) to a Broker server running in Snyk environment:
Brokered communication
See Snyk Broker documentation for more details.

Setup

Prerequisites

Before you begin with the setup process, make sure to have a server that supports these minimal requirements for running the Broker client and Code agent:
  • CPU: 1 vcpu
  • Memory: 2Gb (should be reflected in node memory setting)
  • Disk space: 2Gb (available disk size determines maximum cloneable repository size)
  • Network: code upload performance will be affected by slow Internet connection

Set up the network

To run both the broker client and the broker agent, establish a network connection between them. There are different solutions to expose one container connection with tools like Ngrok (which is also possible here if you want), but this description focuses on docker bridge networks.
Run docker network create <network>
For example:
1
docker network create mySnykBrokerNetwork
Copied!
You can confirm that it was created by running docker network ls, this will show results like this:
1
NETWORK ID NAME DRIVER SCOPE
2
d1353a2b0f66 mySnykBrokerNetwork bridge local
Copied!

Set up Code Agent

First, pull the code-agent image:
1
docker pull snyk/code-agent
Copied!
The following environment variables are mandatory to configure the code agent:
  • SNYK_TOKEN - your Snyk API token, as also used by the CLI, see Authenticate the CLI with your account for additional details.
  • PORT - the local port, for which the code agent accepts connections, Default is 3000.
To run the code-agent:
1
docker run --name code-agent \
2
-p 3000:3000 \
3
-e PORT=3000 -e SNYK_TOKEN=<Snyk API token> --network mySnykBrokerNetwork \
4
snyk/code-agent
Copied!
In this example:
  • We set the current container to use the new network we created --network mySnykBrokerNetwork
  • We gave the current container a name --name code-agent. It will be used to define the GIT_CLIENT_URL for the broker client that we will run next.

Set up Broker client

Code agent depends on broker client. Follow the instructions on How to install and configure your Snyk Broker client for detailed instructions how to set up broker for specific SCMs.
If you already have a broker client running, consider the following additional requirements:
  • Code agent is only supported with Snyk Broker v4.108.0 and later versions; make sure to pull the latest version first.
  • Code agent needs permission to clone the full repository; make sure that the SCM token passed to the broker has the corresponding permissions.

Extend Broker setup

Extend your broker setup with the following arguments:
1
-e GIT_CLIENT_URL=http://<code agent container>:<code agent port>
2
--network <name of created network>
Copied!
For example, to extend an existing broker client configured for GitLab, run:
1
docker run \
2
-p 8001:8000 \
3
-e BROKER_TOKEN=<xxxxxxx-xxxx-xxxx-xxxx-xxxxxxx> \
4
-e GITLAB_TOKEN=glpat-<xxxxxxxxxxxxxxx> \
5
-e GITLAB=url.com \
6
-e BROKER_CLIENT_URL=http://my.broker.client:8001
7
-e PORT=8000 \
8
-e GIT_CLIENT_URL=http://code-agent:3000 \
9
--network mySnykBrokerNetwork \
10
-e ACCEPT=/private/accept.json \
11
-v /path/to/private:/private \
12
snyk/broker:gitlab
Copied!
In this example:
  • We set the current container to use the new network we created --network mySnykBrokerNetwork
  • In GIT_CLIENT_URL we used the name we defined in the code-agent container as the host here.

Enable with custom whitelist

If you have a running Snyk broker with a custom whitelist (accept.json), then ensure the following rule is present in the whitelist:
1
{
2
"//": "used to redirect requests to snyk git client",
3
"method": "any",
4
"path": "/snykgit/*",
5
"origin": "${GIT_CLIENT_URL}"
6
}
Copied!
(The rule is present by default, so only needed if you override the rule with a custom whitelist.)
At this point please contact your Customer Success Manager or Support to enable the integration

Advanced settings

Enable code snippets

To enable code snippets, additional rules must be added to the private array in the accept.json file.
See https://github.com/snyk/broker#custom-approved-listing-filter for detailed instructions how to extend accept.json.
For GitHub:
1
{
2
"//": "needed to load code snippets",
3
"method": "GET",
4
"path": "/repos/:name/:repo/contents/:path",
5
"origin": "https://${GITHUB_TOKEN}@${GITHUB_API}"
6
}
Copied!
For GitLab:
1
{
2
"//": "needed to load code snippets",
3
"method": "GET",
4
"path": "/api/v4/projects/:project/repository/files/:path",
5
"origin": "https://${GITLAB}"
6
}
Copied!
For BitBucket Server and Bitbucket Data Center:
1
{
2
"//": "needed to load code snippets",
3
"method": "GET",
4
"path": "/projects/:project/repos/:repo/browse*/:file",
5
"origin": "https://${BITBUCKET_API}",
6
"auth": {
7
"scheme": "basic",
8
"username": "${BITBUCKET_USERNAME}",
9
"password": "${BITBUCKET_PASSWORD}"
10
}
11
}
Copied!
For Azure Repos:
1
{
2
"//": "needed for code snippets",
3
"method": "GET",
4
"path": "/:owner/_apis/git/repositories/:repo/items",
5
"origin": "https://${AZURE_REPOS_HOST}/${AZURE_REPOS_ORG}",
6
"auth": {
7
"scheme": "basic",
8
"token": "${BROKER_CLIENT_VALIDATION_BASIC_AUTH}"
9
}
10
}
Copied!
After these snippets are added, all content from the repository can be accessed through Snyk Broker.

Proxy support

For instructions how to run Broker client through a proxy, see https://github.com/snyk/broker. Make sure that requests to the Code Agent are not sent through the proxy, bypassing NO_PROXY=<code agent container>, for example:
1
-e HTTP_PROXY=http://my.proxy.address:8080
2
-e HTTPS_PROXY=http://my.proxy.address:8080
3
-e NO_PROXY=code-agent
Copied!
For Code Agent, add the following environment variables to the docker run command:
1
-e HTTP_PROXY=http://my.proxy.address:8080
2
-e HTTPS_PROXY=http://my.proxy.address:8080
Copied!
To disable certificate verification, for example., in the case of self-signed certificates, add to the code-agent docker run command:
1
-e NODE_TLS_REJECT_UNAUTHORIZED=0
Copied!

Troubleshooting

Please visit Troubleshooting Broker for more information on how to troubleshoot Snyk Broker Code Agent