TruffleHog

https://docs.trufflesecurity.com/
Admin
TruffleHog is a powerful tool for the discovery, classification, validation, and analysis of secrets...
Tokens:19,818
Snippets:132
Trust Score:10
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Pre-commit Framework

Source: https://docs.trufflesecurity.com/pre-commit-hooks

Installs the pre-commit framework, a tool for managing Git hooks across different programming languages. Installation can be done using pip, Homebrew, or conda.

```bash
# Using pip (Python)
pip install pre-commit

# Using Homebrew (macOS)
brew install pre-commit

# Using conda
conda install -c conda-forge pre-commit
```

--------------------------------

### Install TruffleHog CLI Tool

Source: https://docs.trufflesecurity.com/pre-commit-hooks

Installs TruffleHog locally using either Homebrew on macOS or a provided script for Linux, macOS, and Windows. This is a prerequisite for using TruffleHog in pre-commit hooks.

```bash
# Using Homebrew (macOS)
brew install trufflehog

# Using installation script for Linux, macOS, and Windows (and WSL)
curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b /usr/local/bin
```

--------------------------------

### Set Up Husky Pre-commit Hook (Local Binary)

Source: https://docs.trufflesecurity.com/pre-commit-hooks

Configures the `.husky/pre-commit` script to execute TruffleHog using the locally installed binary. This hook will run before each commit to scan for secrets.

```bash
echo "trufflehog git file://. --since-commit HEAD --results=verified,unknown --fail" > .husky/pre-commit
```

--------------------------------

### Install Husky for Node.js Projects

Source: https://docs.trufflesecurity.com/pre-commit-hooks

Installs Husky, a Git hooks manager for JavaScript/Node.js projects, as a development dependency. This is the first step to integrating custom Git hooks like secret scanning.

```bash
# npm
npm install husky --save-dev

# yarn
yarn add husky --dev
```

--------------------------------

### Set Up Husky Pre-commit Hook (Docker)

Source: https://docs.trufflesecurity.com/pre-commit-hooks

Configures the `.husky/pre-commit` script to execute TruffleHog using a Docker container. This ensures secret scanning occurs before each commit, regardless of local TruffleHog installation.

```bash
echo 'docker run --rm -v "$(pwd):/workdir" -i --rm trufflesecurity/trufflehog:latest git file:///workdir --since-commit HEAD --results=verified,unknown --fail' > .husky/pre-commit
```

--------------------------------

### Configure Global Git Hooks with TruffleHog (Local Binary)

Source: https://docs.trufflesecurity.com/pre-commit-hooks

Sets up a global pre-commit hook using Git's `core.hooksPath`. This configuration uses the locally installed TruffleHog binary to scan for secrets on every commit.

```bash
#!/bin/sh

trufflehog git file://. --since-commit HEAD --results=verified,unknown --fail
```

--------------------------------

### Shell Commands for Systemd Service Management

Source: https://docs.trufflesecurity.com/systemd

A set of essential shell commands for managing a systemd service. These commands are used to reload the systemd daemon after creating or modifying a service file, enable the service to start on boot, start the service immediately, check its status, and view its logs.

```shell
sudo systemctl daemon-reload
sudo systemctl enable trufflehog.service
sudo systemctl start trufflehog.service
sudo systemctl status trufflehog.service
sudo journalctl -u trufflehog
sudo journalctl -fu trufflehog
```

--------------------------------

### TruffleHog Docker Execution Example

Source: https://docs.trufflesecurity.com/scanning-in-ci

This command demonstrates how to run TruffleHog using Docker for secret scanning. It mounts the current directory, specifies the image, and executes the scan with verified findings causing a failure. The output shows an example of a detected secret.

```bash
$ docker run -v "$(pwd):/workdir" -it --rm us-docker.pkg.dev/thog-artifacts/public/scanner:latest git --fail-verified main HEAD /workdir

🐷🔑🐷 TruffleHog. Unearth your secrets. 🐷🔑🐷
version:  dev

WARN[0004] found secret                                  commit=unstaged email=unstaged file=aws redacted=AKIAXYZDQCENUFS46CE4 type=AWS verified=true
INFO[0004] scanned 4 commits                            
WARN[0004] found 1 VERIFIED secrets                     
exit status 1
```

--------------------------------

### Enable Git Hooks with Husky

Source: https://docs.trufflesecurity.com/pre-commit-hooks

Initializes Husky in a Node.js project, setting up the necessary infrastructure to manage Git hooks. This command creates the `.husky` directory and prepares it for hook scripts.

```bash
# npm
npx husky init
```

--------------------------------

### Configure Global Git Hooks with TruffleHog (Docker)

Source: https://docs.trufflesecurity.com/pre-commit-hooks

Sets up a global pre-commit hook using Git's `core.hooksPath`. This configuration uses a Docker container to run TruffleHog, scanning for secrets on every commit without requiring a local installation.

```bash
#!/bin/sh

docker run --rm -v "$(pwd):/workdir" -i --rm trufflesecurity/trufflehog:latest git file:///workdir --since-commit HEAD --results=verified,unknown --fail
```

--------------------------------

### Kubernetes: Install TruffleHog with Helm

Source: https://docs.trufflesecurity.com/helm-chart

Installs TruffleHog using Helm with default configurations. Custom configurations can be applied using a custom values.yaml file, referencing the chart's README for details.

```shell
helm install trufflehog . --namespace trufflehog
```

--------------------------------

### Example TruffleHog Configuration with Custom Detectors (YAML)

Source: https://docs.trufflesecurity.com/custom-detectors

This is an example of a TruffleHog configuration file demonstrating the use of custom detectors. It includes settings for concurrency, a list of detectors (including a custom regex detector with verification), filtering, logging level, worker count, and TruffleHog service addresses.

```yaml
concurrency: "8"
detectors:
- keywords:
  - keyword1
  - keyword2
  name: custom regex detector
  regex:
    id: id-[a-zA-Z0-9]{16}
    secret: '[a-zA-Z0-9]{32}'
  verify:
  - endpoint: http://localhost:8000
    headers:
    - 'Authorization: Bearer token'
    unsafe: true
filterUnverified: true
logLevel: info
numWorkers: 16
trufflehogAddress: https://gnarly-flying-pancake.c1.prod.trufflehog.org
trufflehogScannerGroup: account 1 - us-west-2
trufflehogScannerToken: thog-agent-XXXXXXXXXXXXXXXXXXXXXXXXXX
```

--------------------------------

### Install TruffleHog Dependencies on Ubuntu

Source: https://docs.trufflesecurity.com/resource-requirements

Installs necessary tools for TruffleHog, including Git for repository management, and rpm2cpio, binutils, and cpio for package extraction. These commands update package lists and then install the required packages.

```shell
sudo apt update
sudo apt install git rpm2cpio binutils cpio
```

--------------------------------

### Run TruffleHog Scanner with Configuration File

Source: https://docs.trufflesecurity.com/running-the-scanner

This command executes the TruffleHog scanner using a configuration file. Ensure the path to your YAML configuration is correctly specified. The output indicates the scanner has started and provides a motivational message.

```shell
./scanner scan --config=path/to/config.yaml
🐷🔑🐷 TruffleHog. Unearth your secrets. 🐷🔑🐷
```

--------------------------------

### Shell Commands for Creating a Non-Root User

Source: https://docs.trufflesecurity.com/systemd

Commands to create a new user for running the TruffleHog scanner as a non-root user. It provides variations for Debian-based systems (like Ubuntu) using `adduser` and for other Linux distributions using `useradd`. This enhances security by limiting the scanner's privileges.

```shell
sudo adduser truffle
# For other Linux distributions:
sudo useradd -m truffle
```

--------------------------------

### Troubleshoot Executable Permissions for Hooks

Source: https://docs.trufflesecurity.com/pre-commit-hooks

Ensures that the pre-commit hook file has execute permissions. This is a common troubleshooting step if the Git hook is not running as expected.

```bash
chmod +x .git/hooks/pre-commit
```

--------------------------------

### Notifier Configurations (YAML)

Source: https://docs.trufflesecurity.com/configuration-file-reference

Configures a list of notifiers for sending notifications. Examples include Slack and Webhook notifiers, specifying connection details and target sources.

```yaml
notifiers:
- connection:
    '@type': type.googleapis.com/notifiers.Slack
    url: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
  name: slack secrets notifications
  type: NOTIFIER_TYPE_SLACK
- connection:
    '@type': type.googleapis.com/notifiers.Webhook
    token: secret_token
    url: https://example.trufflesec.com:8081/webhook
  name: slack secrets notifications
  # sourcesToNotify can also be set to ALL to receive
  # all notifications
  sourcesToNotify: SOURCES_IN_THIS_CONFIG
  type: NOTIFIER_TYPE_WEBHOOK
```

--------------------------------

### Azure Repos Configuration Example

Source: https://docs.trufflesecurity.com/azure-repos-cloud

This YAML snippet demonstrates how to configure Azure Repos as a data source for TruffleHog. It includes settings for token-based authentication, repository inclusion/exclusion, and scanning behavior like skipping binaries. Ensure the 'token' is replaced with a valid PAT.

```yaml
sources:
- connection:
    '@type': type.googleapis.com/sources.AzureRepos
    ignoreProjects:
    - Project2
    ignoreRepos:
    - https://dev.azure.com/trufflescurity/IgnoreRepo
    includeForks: false
    skipBinaries: true
    token: XXXXXXXXXXXXXXXXXXXXXXXXXX
  name: Azure Repos
  scanPeriod: 12h
  type: SOURCE_TYPE_AZURE_REPOS
  verify: true
```

--------------------------------

### Configure Buildkite Source with YAML

Source: https://docs.trufflesecurity.com/buildkite

Example of configuring a Buildkite source in a local YAML file for Truffle Security. This configuration requires a Buildkite API token with specific GraphQL scopes. The token and other source details like scan period and verification are specified.

```yaml
sources:
- connection:
    '@type': type.googleapis.com/sources.Buildkite
    # Token must have GraphQL API access enabled.
    # Token requires Organization Access, Read Artifacts, 
    # Read Builds, Read Build Logs, and Read Pipelines.
    token: XXXXXXXXXXXXXXXXXXXXXXXXXX
  name: Buildkite logs and artifacts
  scanPeriod: 12h
  type: SOURCE_TYPE_BUILDKITE
  verify: true
```

--------------------------------

### Systemd Service Configuration for TruffleHog Scanner

Source: https://docs.trufflesecurity.com/systemd

A basic systemd service unit file for running the TruffleHog scanner. This configuration defines the service description, execution command, restart policy, and the user under which the service will run. It assumes the scanner binary and configuration file are located in the user's home directory.

```ini
[Unit]
Description=Run the TruffleHog scanner as a daemon

[Service]
Type=simple
ExecStart=/home/ec2-user/scanner scan --config=/home/ec2-user/config.yaml
Restart=on-failure
RestartSec=15s
User=ec2-user

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Configure Repository-Specific Pre-commit Hook (Local Binary)

Source: https://docs.trufflesecurity.com/pre-commit-hooks

Defines a TruffleHog hook within a `.pre-commit-config.yaml` file for a specific repository. This configuration uses the locally installed TruffleHog binary to scan for secrets during the commit process.

```yaml
repos:
  - repo: local
    hooks:
      - id: trufflehog
        name: TruffleHog
        description: Detect secrets in your data.
        entry: bash -c 'trufflehog git file://. --since-commit HEAD --results=verified,unknown --fail'
        language: system
        stages: ["commit", "push"]
```

--------------------------------

### Filesystem Payload Example

Source: https://docs.trufflesecurity.com/webhook

Example JSON payload for detecting secrets from the filesystem. It includes the source type, metadata with the file path, secret type, secret value, and a verification flag. This format is useful for scanning local files.

```json
{
	"SourceType": "SOURCE_TYPE_FILESYSTEM",
	"Metadata": {
    	"Data": {
      		"Filesystem": {
        		"file": "/Users/hrich/go/src/github.com/org/repo/file"
			}
		}
  },
  "SecretType": "Github",
  "Secret": "SOMESECRET",
  "Verified": false
}
```

--------------------------------

### TruffleHog GitHub Source Configuration

Source: https://docs.trufflesecurity.com/github

Example YAML configuration for TruffleHog to scan GitHub repositories using a GitHub App. This configuration requires specifying the GitHub source type and a list of repositories to scan. Ensure you have generated a private key and obtained the AppID and InstallationID from your GitHub App settings.

```yaml
sources:
- connection:
    '@type': type.googleapis.com/sources.GitHub
    repositories:

```

--------------------------------

### GitHub App Configuration for TruffleHog

Source: https://docs.trufflesecurity.com/github

This snippet shows how to configure a GitHub App for TruffleHog scanning. It requires a private key, installation ID, and App ID. This configuration enables TruffleHog to authenticate and access GitHub repositories.

```yaml
githubApp:
  privateKey: |
   -----BEGIN RSA PRIVATE KEY-----
   xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   -----END RSA PRIVATE KEY-----
  installationId: "54544692"
  appId: "989473"
```

--------------------------------

### BitBucket Payload Example

Source: https://docs.trufflesecurity.com/webhook

Example JSON payload for secrets found in BitBucket. It specifies the source type, metadata with file details, repository, commit, link, timestamp, and line number, along with secret type and value. Suitable for BitBucket integration.

```json
{
	"SourceType": "SOURCE_TYPE_BITBITBUCKET",
	"Metadata": {
		"Data": {
			"Bitbucket": {
				"file": "file-1",
				"repository": "repo-1",
				"workspace": "workspace-1",
				"snippetId": "snippet-1",
				"title": "title-1",
				"commit": "ae3e9d0f0516d52113386c1e75032536143a241c",
				"email": "user-1@atlassian.net",
				"link": "https://bitbucket.org/workspace-1/repo-1/src/ae3e9d0f0516d52113386c1e75032536143a241c/file-1",
				"timestamp": "2020-05-01T00:00:00Z",
				"line": 42
			}
		}
	},
	"SecretType": "Github",
	"Secret": "SOMESECRET",
	"Verified": false
}
```

--------------------------------

### GitLab Payload Example

Source: https://docs.trufflesecurity.com/webhook

Example JSON payload for secrets found in GitLab repositories. It details the source type, metadata including file, repository, commit, link, timestamp, and line number, along with secret type and value. Suitable for GitLab integration.

```json
{
	"SourceType": "SOURCE_TYPE_GITLAB",
	"Metadata": {
		"Data": {
			"Gitlab": {
				"file": "file-1",
				"link": "https://gitlab.com/org/repo/blob/ae3e9d0f0516d52113386c1e75032536143a241c/file-1",
				"repository": "repo-1",
				"line": 42,
				"timestamp": "2020-05-01T00:00:00Z",
				"commit": "ae3e9d0f0516d52113386c1e75032536143a241c",
				"email": "test@example.com"
			}
		}
	},
	"SecretType": "Github",
	"Secret": "SOMESECRET",
	"Verified": false
}
```

--------------------------------

### GitHub Payload Example

Source: https://docs.trufflesecurity.com/webhook

Example JSON payload for secrets found in GitHub repositories. It details the source type, metadata including repository link, commit hash, file, line number, and timestamp, alongside secret information. Useful for GitHub integrations.

```json
{
	"SourceType": "SOURCE_TYPE_GITHUB",
	"Metadata": {
		"Data": {
			"Github": {
				"link": "https://github.com/org/repo/blob/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/file",
				"username": "user-1",
				"repository": "repo-1",
				"commit": "ae3e9d0f0516d52113386c1e75032536143a241c",
				"email": "test@example.com",
				"file": "file.txt",
				"timestamp": "2020-05-01T00:00:00Z",
				"line": 42
			}
		}
	},
	"SecretType": "Github",
	"Secret": "OTHERSECRET",
	"Verified": true
}
```

--------------------------------

### Monitor Kubernetes Pod Status

Source: https://docs.trufflesecurity.com/kubernetes-manifest

This command watches the pods within the 'trufflehog' namespace and displays their status. It's useful for verifying that the TruffleHog deployment has started successfully and is running.

```shell
kubectl get pods --namespace trufflehog --watch
```

--------------------------------

### Confluence Payload Example

Source: https://docs.trufflesecurity.com/webhook

Example JSON payload for secrets detected within Confluence pages. It includes the source type, metadata with page details, space, version, link, email, and timestamp, plus secret type and value. Useful for Confluence integration.

```json
{
	"SourceType": "SOURCE_TYPE_CONFLUENCE",
	"Metadata": {
		"Data": {
			"Jira": {
				"page": "page-1",
				"space": "space-1",
				"version": "version-1",
				"link": "http://confluence.example.com/pages/viewpage.action?pageId=page-1",
				"email": "user-1@atlassian.net",
				"timestamp": "2020-05-01T00:00:00Z"
			}
		}
	},
	"SecretType": "Github",
	"Secret": "OTherSecret",
	"Verified": true
}
```

--------------------------------

### Configure Repository-Specific Pre-commit Hook (Docker)

Source: https://docs.trufflesecurity.com/pre-commit-hooks

Defines a TruffleHog hook within a `.pre-commit-config.yaml` file for a specific repository. This configuration uses a Docker container to run TruffleHog, scanning for secrets during the commit process.

```yaml
repos:
  - repo: local
    hooks:
      - id: trufflehog
        name: TruffleHog
        description: Detect secrets in your data.
        entry: bash -c 'docker run --rm -v "$(pwd):/workdir" -i --rm trufflesecurity/trufflehog:latest git file:///workdir --since-commit HEAD --results=verified,unknown --fail'
        language: system
        stages: ["commit", "push"]
```

--------------------------------

### Slack Payload Example

Source: https://docs.trufflesecurity.com/webhook

Example JSON payload for secrets detected in Slack messages. It includes the source type, metadata with channel information, user ID, file reference, link, email, and timestamp, along with secret type and value. Useful for Slack integration.

```json
{
	"SourceType": "SOURCE_TYPE_SLACK",
	"Metadata": {
		"Data": {
			"Slack": {
				"channelID": "channel-1",
				"channelName": "some channel",
				"timestamp": "2020-05-01T00:00:00Z",
				"userId": "user-1",
				"link": "https://slack.com/app_redirect?channel=channel-1",
				"file": "file-1",
				"email": "test@slack.com"
			}
		}
	},
	"SecretType": "Github",
	"Secret": "SOMESECRET42",
	"Verified": true
}
```

--------------------------------

### Shell Command for Setting Directory Permissions

Source: https://docs.trufflesecurity.com/systemd

A shell command to recursively change the ownership of a directory and its contents to a specified user and group. This is crucial for ensuring that the user running the TruffleHog scanner has the necessary read and write permissions to the scanner's directory and any directories it needs to scan.

```shell
chown -R truffle: /path-containing-trufflehog/
```

--------------------------------

### Systemd Service Configuration with Proxy Settings for TruffleHog

Source: https://docs.trufflesecurity.com/systemd

This systemd service unit file configures the TruffleHog scanner to run as a daemon with HTTP and HTTPS proxy settings. It specifies the proxy server address and port via environment variables, alongside the standard service execution and user configuration. This is useful for nodes without direct outbound network connectivity.

```ini
[Unit]
Description=Run the TruffleHog scanner as a daemon

[Service]
Environment="HTTP_PROXY=http://proxy.server.com:8000"
Environment="HTTPS_PROXY=https://proxy.server.com:8000"
Type=simple
ExecStart=/home/ubuntu/scanner scan --config=/home/ubuntu/config.yaml
Restart=on-failure
RestartSec=15s
User=ubuntu

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Bypass Pre-commit Hooks

Source: https://docs.trufflesecurity.com/pre-commit-hooks

Provides the command to bypass pre-commit hooks during a Git commit operation. This is useful in situations where hooks need to be skipped intentionally, such as during specific maintenance commits.

```bash
git commit --no-verify -m "Your commit message"
```

--------------------------------

### TruffleHog Git Command Help (Bash)

Source: https://docs.trufflesecurity.com/scanning-in-ci

This bash snippet shows the help output for the `trufflehog-launcher git` command, detailing its usage, available flags, and arguments for scanning local git repositories. It's useful for understanding the command's options before execution.

```bash
$ trufflehog-launcher git --help
usage: TruffleHog git [<flags>] <base> <head> [<workdir>]

Scans a local git repo.

Flags:
      --help                  Show context-sensitive help (also try --help-long and --help-man).
  -v, --debug                 Enable debug mode.
      --trace                 Enable tracing of code line numbers.
      --json                  Enable JSON output.
      --send-error-telemetry  Turns error telemetry off.
      --fail-verified         Only emit failure code for verified findings.
      --quiet                 Only show results.
      --config=CONFIG         Path to configuration file. You can also specify Google Secrets Manager secrets with
                              'gsm://<project_id>/<secret_name>'.

Args:
  <base>       Start scanning from here (usually main branch).
  <head>       Scan commits until here (usually dev branch).
  [<workdir>]  Optional path to the repo to scan.
```

--------------------------------

### Run Truffle Security Scanner with Docker

Source: https://docs.trufflesecurity.com/creating-a-scanner

This command executes the Truffle Security scanner using its Docker image. It maps the local configuration file to the container and specifies the configuration path. Ensure the Docker image is accessible and the configuration file is correctly placed.

```shell
docker run --net=host -v $(pwd)/config.yaml:/tmp/config.yaml -it --rm us-docker.pkg.dev/thog-artifacts/public/scanner:latest scan --config=/tmp/config.yaml
```

--------------------------------

### Git Integration: Basic Authentication Configuration (YAML)

Source: https://docs.trufflesecurity.com/git

This YAML configuration demonstrates how to set up TruffleHog to scan Git repositories using basic authentication. It specifies the username, password, and repositories to scan, along with options for including/excluding paths and skipping binary files.

```yaml
sources:
- connection:
    '@type': type.googleapis.com/sources.Git
    basicAuth:
      password: clonePassword
      username: cloneUser
    excludePathsFile: /home/me/dev/exclude.txt
    includePathsFile: /home/me/dev/include.txt
    repositories:
    - https://github.com/dustin-decker/secretsandstuff.git
    skipBinaries: true
  name: Git
  scanPeriod: 12h
  type: SOURCE_TYPE_GIT
  verify: true
```

--------------------------------

### Microsoft Teams Payload Example

Source: https://docs.trufflesecurity.com/webhook

Example JSON payload for secrets detected in Microsoft Teams messages. It specifies the source type, detailed metadata including channel information, user ID, and file reference, along with secret details. This is for integrating with Teams.

```json
{
	"SourceType": "SOURCE_TYPE_TEAMS",
	"Metadata": {
		"Data": {
			"Teams": {
				"channelID": "channel-1",
				"channelName": "some channel",
				"timestamp": "2020-05-01T00:00:00Z",
				"userId": "user-1",
				"link": "https://teams.microsoft.com/l/message/19:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
				"file": "file-1",
				"email": "test@microsoft.com"
			}
		}
	},
	"SecretType": "Github",
	"Secret": "SOMESECRET",
	"Verified": false
}
```

--------------------------------

### JIRA Payload Example

Source: https://docs.trufflesecurity.com/webhook

Example JSON payload for secrets detected within JIRA issues. It includes the source type, metadata with JIRA issue details, author, location URL, email, and timestamp, along with secret type and value. Useful for JIRA integrations.

```json
{
	"SourceType": "SOURCE_TYPE_JIRA",
	"Metadata": {
		"Data": {
			"Jira": {
				"issue": "issue-1",
				"author": "user-1",
				"location": "https://ourbusiness.atlassian.net/browse/issue-1",
				"email": "user-1@atlassian.net",
				"timestamp": "2020-05-01T00:00:00Z"
			}
		}
	},
	"SecretType": "Github",
	"Secret": "SOMESECRET",
	"Verified": false
}
```

--------------------------------

### Kubernetes: Create Namespace

Source: https://docs.trufflesecurity.com/helm-chart

Creates a new Kubernetes namespace named 'trufflehog' to isolate TruffleHog resources. This command is a prerequisite for deploying TruffleHog using Helm.

```shell
kubectl create namespace trufflehog
namespace/trufflehog created
```

--------------------------------

### Source Integrations Configuration (YAML)

Source: https://docs.trufflesecurity.com/configuration-file-reference

Defines a list of source configurations for scanning data, such as GitHub and S3. Each source includes connection details, scan period, and type.

```yaml
sources:
- connection:
    '@type': type.googleapis.com/sources.GitHub
    endpoint: https://github.ourbusiness.com
    token: XXXXXXXXXXXXXXXXXXXXXXXXXX
  name: GitHub
  scanPeriod: 12h
  type: SOURCE_TYPE_GITHUB
  verify: true
- connection:
    '@type': type.googleapis.com/sources.S3
    cloudEnvironment: {}
  name: S3
  scanPeriod: 12h
  type: SOURCE_TYPE_S3
  verify: true
```

--------------------------------

### Local Filesystem Configuration (YAML)

Source: https://docs.trufflesecurity.com/filesystem

This YAML snippet defines the local configuration for a filesystem source in TruffleHog. It specifies connection details, including the source type, paths to scan, and optional include/exclude path files. The configuration also includes a name for the source, the scan period, and a verification flag.

```yaml
sources:
- connection:
    '@type': type.googleapis.com/sources.Filesystem
    paths:
    - /home/me/dev
    excludePathsFile: /home/me/dev/exclude.txt
    includePathsFile: /home/me/dev/include.txt
  name: Filesystem
  scanPeriod: 12h
  type: SOURCE_TYPE_FILESYSTEM
  verify: true
```

--------------------------------

### Configure GitHub Source with Bearer Token (YAML)

Source: https://docs.trufflesecurity.com/github

This configuration snippet demonstrates how to set up the GitHub source integration using a bearer token. It specifies connection details like the endpoint, token, and various options for repository inclusion and scanning. Ensure the token has 'repo', 'gist', and 'read:org' scopes.

```yaml
sources:
- connection:
    '@type': type.googleapis.com/sources.GitHub
    endpoint: https://github.ourbusiness.com
    token: XXXXXXXXXXXXXXXXXXXXXXXXXX
    ignoreRepos:
    - trufflesecurity/trufflehog
    includeForks: false
    includeGistComments: true
    includeIssueComments: true
    includePullRequestComments: true
    scanUsers: false
    skipBinaries: true
  name: GitHub
  scanPeriod: 12h
  type: SOURCE_TYPE_GITHUB
  verify: true
```

--------------------------------

### Scan with File Configuration

Source: https://docs.trufflesecurity.com/secrets-management

This snippet demonstrates how to run a TruffleHog scan using a configuration file. Environment variables within the config file can be expanded at runtime. The file path is provided via the --config flag.

```shell
trufflehog scan --config="/path/to/config.yaml"
```

--------------------------------

### Run TruffleHog Analyze (Open Source)

Source: https://docs.trufflesecurity.com/analyzers

This command initiates the TruffleHog Analyze process in its open-source version. It performs an analysis of secrets to identify potential risks and metadata. No specific inputs or outputs are detailed here, but it's the primary CLI command for basic analysis.

```bash
trufflehog analyze
```

--------------------------------

### Generate Bitbucket OAuth Tokens using Bash Script

Source: https://docs.trufflesecurity.com/bitbucket

This bash script facilitates the OAuth authentication process for Bitbucket Data Center. It allows for the initial generation of access and refresh tokens by authorizing through a browser, and also supports refreshing the access token using a valid refresh token. Ensure you replace placeholder values with your actual Bitbucket OAuth consumer details.

```bash
#!/bin/bash
# Replace these with your OAuth consumer details
CLIENT_ID="<generated client id in Bitbucket application link>"
CLIENT_SECRET="<generated client secret in Bitbucket application link>"
REDIRECT_URI="<redirect uri inputted in Bitbucket application link>"
AUTH_URL="https://bitbucket.ourbusiness.com/rest/oauth2/latest/authorize"
TOKEN_URL="https://bitbucket.ourbusiness.com/rest/oauth2/latest/token"
SCOPES="REPO_READ"
# Function to authorize access and get access token for the first time
oauth_access_token() {
	echo "Step 1: Open the following URL in your browser and authorize access:"
	echo ""
	echo "${AUTH_URL}?client_id=${CLIENT_ID}&response_type=code&scope=${SCOPES}&redirect_uri=${REDIRECT_URI}"
	echo ""
	echo "After authorizing, you will be redirected to ${REDIRECT_URI}?code=YOUR_AUTH_CODE"
	echo "Copy the 'code' from the URL and enter it below."
	# User inputs the authorization code
	read -p "Enter the authorization code: " AUTH_CODE
	# Step 2: Exchange the authorization code for an access token
	echo "Requesting access token..."
	RESPONSE=$(curl --request POST --url \
	    "${TOKEN_URL}?client_id=${CLIENT_ID}&client_secret=${CLIENT_SECRET}&code=${AUTH_CODE}&grant_type=authorization_code&redirect_uri=${REDIRECT_URI}" \
	    --header 'Content-Type: application/x-www-form-urlencoded' )
        echo $RESPONSE
	# Extract the access token
	ACCESS_TOKEN=$(echo $RESPONSE | grep -o '"access_token":"[^"]*' | cut -d'"' -f4)
	REFRESH_TOKEN=$(echo $RESPONSE | grep -o '"refresh_token":"[^"]*' | cut -d'"' -f4)
	if [[ -z "$ACCESS_TOKEN" ]]; then
	    echo "Failed to retrieve access token. Response: $RESPONSE"
	    exit 1
	fi
	echo "OAuth token generated successfully!"
	echo "Access Token: $ACCESS_TOKEN"
	echo "Refresh Token: $REFRESH_TOKEN"
}
# Function to generate access tokens using refresh tokens
oauth_refresh_token() {
	# User inputs the refresh token
	read -p "Enter the refresh token: " REFRESH_TOKEN
	# Step 1: Run the refresh token API
	echo "Requesting access token..."
	RESPONSE=$(curl --request POST --url \
	    "${TOKEN_URL}?client_id=${CLIENT_ID}&client_secret=${CLIENT_SECRET}&refresh_token=${REFRESH_TOKEN}&grant_type=refresh_token&redirect_uri=${REDIRECT_URI}" \
	    --header 'Content-Type: application/x-www-form-urlencoded' )
            echo $RESPONSE
			# Extract the access token
			ACCESS_TOKEN=$(echo $RESPONSE | grep -o '"access_token":"[^"]*' | cut -d'"' -f4)
			REFRESH_TOKEN=$(echo $RESPONSE | grep -o '"refresh_token":"[^"]*' | cut -d'"' -f4)
			if [[ -z "$ACCESS_TOKEN" ]]; then
			    echo "Failed to retrieve access token. Response: $RESPONSE"
			    exit 1
			fi
			echo "OAuth token generated successfully!"
			echo "Access Token: $ACCESS_TOKEN"
			echo "Refresh Token: $REFRESH_TOKEN"
}
# Check input arguments
if [[ $# -eq 0 ]]; then
    echo "Usage: $0 -a | -b"
    echo "Where -a: Authorise and generate OAUTH Token and -b: Use Refresh token to get new access token"
    exit 1
fi
# Process options
while getopts "ab" opt; do
    case $opt in
        a) oauth_access_token ;;
        b) oauth_refresh_token ;;
        *) echo "Invalid option: -$OPTARG"; exit 1 ;;
    esac
done
```

--------------------------------

### Configure Jenkins Basic Auth Integration (YAML)

Source: https://docs.trufflesecurity.com/jenkins

This configuration snippet demonstrates how to set up the Jenkins integration using basic authentication. It requires a username, password, and the Jenkins endpoint. The scan period is set to 12 hours.

```yaml
sources:
- connection:
    '@type': type.googleapis.com/sources.Jenkins
    basicAuth:
      password: XXXXXXXXXXXXXXXXXXXXXXXXXX
      username: scanner-account
    endpoint: https://jenkins.example.com
  name: Jenkins logs
  scanPeriod: 12h
  type: SOURCE_TYPE_JENKINS
  verify: true
```

--------------------------------

### View TruffleHog Container Logs

Source: https://docs.trufflesecurity.com/kubernetes-manifest

This command streams the logs from the TruffleHog pods in the 'trufflehog' namespace. It allows you to monitor the scanner's activity and troubleshoot any issues by observing its output in real-time.

```shell
kubectl logs --namespace trufflehog -f -l app=trufflehog
```

--------------------------------

### Create Kubernetes Namespace

Source: https://docs.trufflesecurity.com/kubernetes-manifest

This command creates a dedicated namespace for the TruffleHog deployment within a Kubernetes cluster. A namespace helps in organizing and isolating resources.

```shell
kubectl create namespace trufflehog
```

--------------------------------

### Configure Email Notifications via YAML

Source: https://docs.trufflesecurity.com/email

This YAML configuration snippet sets up email notifications using AWS SES. It requires AWS credentials (key and secret), specifies sender and recipient email addresses, and defines the notification type as 'NOTIFIER_TYPE_EMAIL'. The 'ccLeaker' option is available but not included in this example.

```yaml
notifiers:
- connection:
    '@type': type.googleapis.com/notifiers.Email
    ses:
      creds:
        key: AKIAXXXXXXXXXXXXXXXX
        region: us-west1
        secret: XXXXXXXXXXXXXXXXXXXXXXXXXX
      recipients:
      - security@ourbusiness.org
      sender: <trufflehog> trufflehog@ourbusiness.org
  name: email secrets notifications
  type: NOTIFIER_TYPE_EMAIL
```

--------------------------------

### Configure GitLab Integration with Basic Auth (YAML)

Source: https://docs.trufflesecurity.com/gitlab

This YAML configuration snippet shows how to integrate TruffleHog with GitLab using basic authentication. It includes the GitLab endpoint, username, password, and options to ignore specific repositories using globbing patterns and to skip binary files. The scan is set to run every 12 hours.

```yaml
sources:
- connection:
    '@type': type.googleapis.com/sources.GitLab
    endpoint: https://gitlab.ourbusiness.com
    basicAuth:
      password: XXXXXXXXXXXXXXX
      username: svc-user
    ignoreRepos:
    - trufflesecurity/test_keys
    skipBinaries: true
  name: GitLab
  scanPeriod: 12h
  type: SOURCE_TYPE_GITLAB
  verify: true
```

--------------------------------

### Configure GitLab Integration with Access Token (YAML)

Source: https://docs.trufflesecurity.com/gitlab

This YAML configuration snippet demonstrates how to set up TruffleHog to scan GitLab repositories using an access token. It specifies the GitLab endpoint, the access token (requiring the `read_api` scope), and options to skip binary files. The integration is named 'GitLab' and is set to scan every 12 hours.

```yaml
sources:
- connection:
    '@type': type.googleapis.com/sources.GitLab
    endpoint: https://gitlab.ourbusiness.com
    # The GitLab token must be created with the 
    # `read_api` scope.
    token: XXXXXXXXXXXXXXXXXXXXXXXXXX
    skipBinaries: true
  name: GitLab
  scanPeriod: 12h
  type: SOURCE_TYPE_GITLAB
  verify: true
```

--------------------------------

### IAM Trust Policy for Role Assumption

Source: https://docs.trufflesecurity.com/aws-s3

This JSON policy defines the trust relationship for an IAM role, specifying which principals (e.g., AWS users or services) are allowed to assume this role. In this example, the user 'Bob' from account '123456789012' is permitted to assume the role. This is crucial for enabling role assumption configurations.

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
	  "AWS": "arn:aws:iam::123456789012:user/Bob"
	},
      "Action": "sts:AssumeRole"
    }
  ]
}
```

--------------------------------

### Slack Notifier Configuration (YAML)

Source: https://docs.trufflesecurity.com/slack

This YAML snippet demonstrates the local configuration for the Slack notifier in TruffleHog. It requires the Slack webhook URL and specifies the notifier name and type. The 'endpoint' key in the options is required and should be the Slack webhook URL.

```yaml
notifiers:
- connection:
    '@type': type.googleapis.com/notifiers.Slack
    url: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
  name: slack secrets notifications
  type: NOTIFIER_TYPE_SLACK
```

--------------------------------

### Supported Capabilities

Source: https://docs.trufflesecurity.com/confluence

This section outlines the features supported by the Truffle Security project, indicating which types of data and scanning methods are compatible.

```APIDOC
## Supported Capabilities

### Description
Lists the features and data types supported by the Truffle Security project, including archive file scanning, attachment scanning, binary analysis, and version history scanning.

### Method
N/A (Informational)

### Endpoint
N/A (Informational)

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **Feature** (string) - Name of the capability
- **Supported** (boolean) - Indicates if the feature is supported

#### Response Example
```json
[
  {
    "Feature": "Scan archive files",
    "Supported": true
  },
  {
    "Feature": "Scan attachments",
    "Supported": true
  },
  {
    "Feature": "Scan base64 encoded data",
    "Supported": true
  },
  {
    "Feature": "Scan binaries",
    "Supported": true
  },
  {
    "Feature": "Comments",
    "Supported": false
  },
  {
    "Feature": "Exclude Filter",
    "Supported": true
  },
  {
    "Feature": "Auto resume",
    "Supported": true
  },
  {
    "Feature": "Scan version history",
    "Supported": true
  }
]
```
```

--------------------------------

### Slack Source Configuration (YAML)

Source: https://docs.trufflesecurity.com/source-slack

This YAML configuration snippet defines a Slack source for TruffleHog. It specifies the connection details, including the endpoint, a refresh token, and optional channel inclusion/exclusion lists. The scan period and verification settings are also included. If no channels are specified, all accessible channels will be scanned.

```yaml
sources:
- connection:
    '@type': type.googleapis.com/sources.Slack
    endpoint: https://slack.ourbusiness.com
    token: XXXXXXXXXXXXXXXXXXXXXXXXXX
    # If channels are not provided, all channels associate with
    # the token will be scanned.
    channels:
    - include-channel
    ignoreList:
    - exclude-channel
  name: Slack
  scanPeriod: 12h
  type: SOURCE_TYPE_SLACK
  verify: true
```

--------------------------------

### Configure Jira Server/Datacenter with Basic Auth

Source: https://docs.trufflesecurity.com/source-jira

This YAML configuration allows TruffleHog to authenticate with Jira Server or Datacenter using basic authentication. It requires the Jira endpoint, a username, and a password. Optionally, you can specify a list of `projects` to scan or `ignoreProjects`. The `scanPeriod` sets the scanning frequency.

```yaml
sources:
- connection:
    '@type': type.googleapis.com/sources.JIRA
    basicAuth:
      # Jira Server / Datacenter accepts username 
      # and password for basic auth. Jira Cloud
      # uses email + access token!
      username: scanner-account@ourbusiness.com
      password: XXXXXXXXXXXXXXXXXXXXXXXXXX
    endpoint: https://ourbusiness.atlassian.net
    projects:
    - ENG
    - ITSYS
  name: JIRA
  scanPeriod: 12h
  type: SOURCE_TYPE_JIRA
  verify: true
```

--------------------------------

### Custom Regex Detectors Configuration (YAML)

Source: https://docs.trufflesecurity.com/configuration-file-reference

Defines custom regex detectors for identifying secrets. Each detector includes a name, keywords, regex patterns, and verification details.

```yaml
detectors:
  - name: "Custom Detector 1"
    keywords:
      - "keyword1"
      - "keyword2"
    regex:
      pattern1: "regex_pattern_1"
      pattern2: "regex_pattern_2"
    verify:
      - endpoint: "https://verify.example.com/api"
        unsafe: false
        headers:
          - "Authorization: Bearer token"
        successRanges:
          - "200-299"
    description: "Description of the custom detector"
  - name: "Custom Detector 2"
    # Other configuration
```

--------------------------------

### Apply Kubernetes Manifest

Source: https://docs.trufflesecurity.com/kubernetes-manifest

This command applies the specified Kubernetes manifest file (deployment.yaml) to the cluster. It instructs Kubernetes to create or update the resources defined in the file, such as the TruffleHog deployment.

```shell
kubectl apply -f /tmp/thog.yaml --namespace trufflehog
```

--------------------------------

### Logging Level Configuration (YAML)

Source: https://docs.trufflesecurity.com/configuration-file-reference

Sets the verbosity of TruffleHog logs. Options include 'info', 'debug', and 'trace', with increasing detail.

```yaml
logLevel: "info"
```

--------------------------------

### TruffleHog Pre-receive Hook Script

Source: https://docs.trufflesecurity.com/pre-receive-hooks

A bash script to execute the TruffleHog scanner as a pre-receive hook. This script runs `trufflehog` with specific options to scan the repository in a bare Git environment, ensuring compliance before commits are accepted. Ensure `trufflehog` is executable and in the system's PATH.

```shell
#!/bin/bash

/trufflehog --no-update git --bare file://. --only-verified --fail
```

--------------------------------

### Run TruffleHog Enterprise as Docker Daemon

Source: https://docs.trufflesecurity.com/docker

This command runs TruffleHog Enterprise as a Docker daemon. It mounts a configuration file and specifies the image to use, followed by the scan command and its configuration argument. Ensure you replace 'YOUR_CONFIG.yaml' with your actual configuration file name.

```shell
docker run --net=host --restart=unless-stopped \
  -v $(pwd)/YOUR_CONFIG.yaml:/tmp/YOUR_CONFIG.yaml \
  -it us-docker.pkg.dev/thog-artifacts/public/scanner:latest \
  scan --config=/tmp/YOUR_CONFIG.yaml
```

--------------------------------

### Kubernetes: Tail TruffleHog Logs

Source: https://docs.trufflesecurity.com/helm-chart

Follows the logs from TruffleHog pods in the 'trufflehog' namespace. This is useful for monitoring the application's activity and troubleshooting issues.

```shell
kubectl logs --namespace trufflehog -f -l app=trufflehog
🐷🔑🐷 TruffleHog. Unearth your secrets. 🐷🔑🐷
version:  v1.50.22

INFO[0000] starting scanner service client               scanner_group=On-prem
```

--------------------------------

### Configure Jira Server/Datacenter with Access Token

Source: https://docs.trufflesecurity.com/source-jira

This YAML configuration enables TruffleHog to connect to Jira Server or Datacenter using a token. You need to provide the Jira endpoint and a personal access token (PAT) for authentication. The `scanPeriod` defines the interval for scanning.

```yaml
sources:
- connection:
    '@type': type.googleapis.com/sources.JIRA
    endpoint: https://ourbusiness.atlassian.net
    token: XXXXXXXXXXXXXXXXXXXXXXXXXX
  name: JIRA
  scanPeriod: 12h
  type: SOURCE_TYPE_JIRA
  verify: true
```
Tokens:
Raw