secret-bridge
A bridge to help increase your ability to detect secrets shared on Github.
More details on the methodology can be found in our blog post.
How It Works
There are two ways this can operate:
- Event Polling - In this mode, the script polls the Github Events API for an organization, developer, or set or repositories. This is useful when you may not have control over the thing you're watching.
- Webhook - In this mode, the script sets up a server which can receive webhook events. This is useful when you have control over the thing you're watching, since it provides data in near real-time.
Once events are received indicating that new code has been pushed, this script executes configured detectors to detect secrets in the changes. At this time, the following detectors are supported:
A more general listing of tools which can be used to detect secrets in Git repositories can be found in TOOLS.md
If a secret is found, it is sent upstream to a notifier. At this time, we support notifying both via stdout as well as Slack and Microsoft Teams.
Installation
Via Docker
The easiest way to get started is by using our Docker image. You can see how to run the Docker image in the Usage section.
Installation from Source
First, you need to clone the repository:
git clone https://github.com/duo-labs/secret-bridge.git
Then, install the required dependencies:
pip install -r requirements.txt
Configuration
Configuration is done through config.toml. In this file, you set your access_token, the organizations, developers, and repositories you want to monitor for secrets, and more.
Setting Up the Access Token
You may wish to avoid having the access token in a file. Instead, you can set this value to env, and put the access token in the GITHUB_WATCHER_TOKEN environment variable.
Setting Up the Monitors
If you're monitoring via event polling (as opposed to using the webhook server), then you can configure what to monitor via the monitors configuration value.
You have the option of configuring one or more Github organization, user, or repository.
Setting Up the Detectors
This tool doesn't actually implement secret detection for Git repositories, since we consider that largely a solved problem. Instead, we handle running various secret detection tools for you in near real-time.
Detectors are configured via the detectors configuration value. Right now, the following values are accepted:
detect-secretsgit-secretstrufflehog
Note: It's expected that the detector you use is installed and available on your
$PATH. If you are running this via the Docker image, all the required tools are pre-installed.
Setting Up the Notifiers
If a secret is detected, we will notify you using your configured notifiers. Currently, the two notification methods are printing to the console, and notifying via a Slack/Teams webhook.
For webhook notifications, both Slack and Microsoft Teams implementations work identically: the JSON structure used to call the Slack webhook is the same as for Microsoft Teams, the implementation is just currently not updated to reflect this. To configure Teams notifications, follow these same steps but with a Teams Connector.
To configure Slack/Teams notifications, create the following configuration option with the webhook_url provided by Slack:
[notifiers.slack_webhook]
webhook_url='your_webhook_url'Usage
python main.py --help
Usage: main.py [OPTIONS] COMMAND [ARGS]...
Options:
-f, --config PATH [default: config.toml]
-v, --verbose Print verbose debug information
--help Show this message and exit.
Commands:
poll
webhook
Running Via Docker
docker run -ti --rm -e GITHUB_WATCHER_TOKEN=your_access_token duolabs/secret-bridge poll
Note that this is the only docker command needed to get the tool up and running. Relevant images will be automatically pulled if they are not found locally.