### Install via Script

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Use the provided installation script to fetch and install the binary.

```bash
curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b /usr/local/bin
```

```bash
curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -v -b /usr/local/bin
```

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

### Install Pre-commit Framework

Source: https://github.com/trufflesecurity/trufflehog/blob/main/PreCommit.md

Installation commands for the pre-commit framework.

```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 Permission Generator

Source: https://github.com/trufflesecurity/trufflehog/blob/main/pkg/analyzer/README.md

Install the `generate_permissions` tool from TruffleHog using `go install`.

```bash
go install github.com/trufflesecurity/trufflehog/v3/pkg/analyzer/generate_permissions
```

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

### Download Binary Releases

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Manual installation by downloading the release archive.

```bash
Download and unpack from https://github.com/trufflesecurity/trufflehog/releases
```

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

### Install Husky

Source: https://github.com/trufflesecurity/trufflehog/blob/main/PreCommit.md

Commands to install Husky for Node.js projects.

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

# yarn
yarn add husky --dev
```

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

### Run Sniff Test

Source: https://github.com/trufflesecurity/trufflehog/blob/main/hack/snifftest/README.md

Execute the snifftest command to access its help pages or get started quickly.

```bash
go run hack/snifftest/main.go
```

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

### Populate SecretParts for single-part credentials

Source: https://github.com/trufflesecurity/trufflehog/blob/main/hack/docs/Adding_Detectors_external.md

Example of creating a detectors.Result for a single-part credential, populating SecretParts with a 'key' entry.

```go
s1 := detectors.Result{
    DetectorType: detector_typepb.DetectorType_Example,
    Raw:          []byte(match),
    SecretParts:  map[string]string{"key": match},
}
```

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

### Install TruffleHog

Source: https://github.com/trufflesecurity/trufflehog/blob/main/PreCommit.md

Commands to install TruffleHog via Homebrew or the official installation script.

```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
```

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

### Populate SecretParts for multi-part credentials

Source: https://github.com/trufflesecurity/trufflehog/blob/main/hack/docs/Adding_Detectors_external.md

Example of creating a detectors.Result for a multi-part credential, populating SecretParts with descriptive keys for each part.

```go
s1 := detectors.Result{
    DetectorType: detector_typepb.DetectorType_Example,
    Raw:          []byte(accessKeyID),
    RawV2:        []byte(accessKeyID + secretAccessKey),
    SecretParts: map[string]string{
        "access_key_id":     accessKeyID,
        "secret_access_key": secretAccessKey,
    },
}
```

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

### Install Pre-commit Hook

Source: https://github.com/trufflesecurity/trufflehog/blob/main/PreCommit.md

Command to install the configured hooks into the repository.

```bash
pre-commit install
```

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

### Example of Structured Logging

Source: https://github.com/trufflesecurity/trufflehog/blob/main/CONTRIBUTING.md

Demonstrates how to use structured logging with fields for better log filtering and searching. Use fields over format strings for contextual information.

```go
Logger().V(2).Info("skipping file: extension is ignored", "ext", mimeExt)
```

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

### Install dos2unix utility

Source: https://github.com/trufflesecurity/trufflehog/blob/main/hack/docs/Adding_Detectors_external.md

Installs the dos2unix utility on Ubuntu, which is used to convert file formats.

```bash
sudo apt install dos2unix
```

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

### Install TruffleHog with Specific Version

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Installs a specific version of TruffleHog using the installation script. Replace `<ReleaseTag like v3.56.0>` with the desired version tag.

```bash
curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b /usr/local/bin <ReleaseTag like v3.56.0>
```

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

### Install TruffleHog on MacOS

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Use Homebrew to install the TruffleHog binary.

```bash
brew install trufflehog
```

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

### Example: Detecting a Secret with a Custom Detector

Source: https://github.com/trufflesecurity/trufflehog/blob/main/pkg/custom_detectors/CUSTOM_DETECTORS.md

Demonstrates running TruffleHog with a custom detector against a sample file. Shows the command and expected output.

```text
// this is a custom example
this file has some random text and maybe a secret
hog token: pOIAj9x47WT5qElx5JrI3e7O714HgaAIz2ck9sVn
// end of file
```

```bash
trufflehog filesystem /tmp --config=config.yaml
```

```text
🐷🔑🐷  TruffleHog. Unearth your secrets. 🐷🔑🐷

Found verified result 🐷🔑
Detector Type: CustomRegex
Decoder Type: PLAIN
Raw result: pOIAj9x47WT5qElx5JrI3e7O714HgaAIz2ck9sVn
File: /tmp/data.txt
Line: 3
```

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

### Configure Standard Git Hook Script

Source: https://github.com/trufflesecurity/trufflehog/blob/main/PreCommit.md

Scripts for standard local installations using either auto-configuration or manual flags.

```bash
#!/bin/sh
export TRUFFLEHOG_PRE_COMMIT=1
trufflehog git file://.
```

```bash
#!bin/sh
trufflehog git file://. --since-commit HEAD --results=verified,unknown --fail --trust-local-git-config
```

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

### Example GitHub Source Configuration

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

This YAML configuration defines a GitHub source for TruffleHog's multi-scan functionality. It specifies repositories to scan and uses an unauthenticated connection.

```yaml
sources:
- connection:
    '@type': type.googleapis.com/sources.GitHub
    repositories:
    - https://github.com/trufflesecurity/test_keys.git
    unauthenticated: {}
  name: example config scan
  type: SOURCE_TYPE_GITHUB
  verify: true
```

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

### Configure Husky Pre-commit Hook with TruffleHog

Source: https://github.com/trufflesecurity/trufflehog/blob/main/PreCommit.md

Add this command to your `.husky/pre-commit` file to automatically scan Git commits with TruffleHog. This is the simplest setup.

```bash
echo "trufflehog git file://." > .husky/pre-commit
```

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

### Integrate TruffleHog into GitLab CI

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Example job configuration for scanning filesystems in a GitLab CI pipeline.

```yaml
stages:
  - security

security-secrets:
  stage: security
  allow_failure: false
  image: alpine:latest
  variables:
    SCAN_PATH: "." # Set the relative path in the repo to scan
  before_script:
    - apk add --no-cache git curl jq
    - curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b /usr/local/bin
  script:
    - trufflehog filesystem "$SCAN_PATH" --results=verified,unknown --fail --json | jq
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
```

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

### TruffleHog GitHub Action - Shallow Cloning

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

This example shows how to optimize TruffleHog's GitHub Action workflow by using shallow cloning to reduce checkout time. It dynamically calculates the fetch depth based on the event type (push or pull request).

```yaml
      - shell: bash
        run: |
          if [ "${{ github.event_name }}" == "push" ]; then
            echo "depth=$(($(jq length <<< '${{ toJson(github.event.commits) }}') + 2))" >> $GITHUB_ENV
            echo "branch=${{ github.ref_name }}" >> $GITHUB_ENV
          fi
          if [ "${{ github.event_name }}" == "pull_request" ]; then
            echo "depth=$((${{ github.event.pull_request.commits }}+2))" >> $GITHUB_ENV
            echo "branch=${{ github.event.pull_request.head.ref }}" >> $GITHUB_ENV
          fi
      - uses: actions/checkout@v3
        with:
          ref: ${{env.branch}}
          fetch-depth: ${{env.depth}}
      - uses: trufflesecurity/trufflehog@main
        with:
          extra_args: --results=verified,unknown
```

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

### Scan Git Repository with TruffleHog

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Use this command to scan a Git repository for secrets. Ensure you have TruffleHog installed and accessible in your PATH.

```bash
trufflehog git https://github.com/trufflesecurity/trufflehog.git
```

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

### Scan Stdin Input

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Pipe data to TruffleHog via stdin for scanning. This example shows piping gzipped data from an S3 bucket after decompression.

```bash
aws s3 cp s3://example/gzipped/data.gz - | gunzip -c | trufflehog stdin
```

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

### TruffleHog GitHub Action - General Usage

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

This GitHub Actions workflow demonstrates a basic setup for secret scanning on push and pull request events. It uses the `trufflesecurity/trufflehog` action with specified results filters.

```yaml
on:
  push:
    branches:
      - main
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout code
      uses: actions/checkout@v4
      with:
        fetch-depth: 0
    - name: Secret Scanning
      uses: trufflesecurity/trufflehog@main
      with:
        extra_args: --results=verified,unknown
```

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

### Compile from Source

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Build the project directly from the repository using Go.

```bash
git clone https://github.com/trufflesecurity/trufflehog.git
cd trufflehog; go install
```

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

### Set up local test secrets

Source: https://github.com/trufflesecurity/trufflehog/blob/main/hack/docs/Adding_Detectors_external.md

Create a .env file with secrets for local testing and export the TEST_SECRET_FILE environment variable.

```bash
SECRET_TYPE_ONE=value
SECRET_TYPE_ONE_INACTIVE=v@lue
```

```bash
export TEST_SECRET_FILE=".env"
```

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

### Enable Husky Hooks

Source: https://github.com/trufflesecurity/trufflehog/blob/main/PreCommit.md

Command to initialize Husky hooks.

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

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

### View TruffleHog Git Help

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Displays the help menu and available flags for the git sub-command.

```bash
$ trufflehog git --help
usage: TruffleHog [<flags>] <command> [<args> ...]

TruffleHog is a tool for finding credentials.


Flags:
  -h, --[no-]help                Show context-sensitive help (also try --help-long and --help-man).
      --log-level=0              Logging verbosity on a scale of 0 (info) to 5 (trace). Can be
                                 disabled with "-1".
      --[no-]profile             Enables profiling and sets a pprof and fgprof server on :18066.
  -j, --[no-]json                Output in JSON format.
      --[no-]json-legacy         Use the pre-v3.0 JSON format. Only works with git, gitlab,
                                 and github sources.
      --[no-]github-actions      Output in GitHub Actions format.
      --concurrency=12           Number of concurrent workers.
      --[no-]no-verification     Don't verify the results.
      --results=RESULTS          Specifies which type(s) of results to output: verified (confirmed
                                 valid by API), unknown (verification failed due to error),
                                 unverified (detected but not verified), filtered_unverified
                                 (unverified but would have been filtered out). Defaults to
                                 verified,unverified,unknown.
      --[no-]no-color            Disable colorized output
      --[no-]allow-verification-overlap
                                 Allow verification of similar credentials across detectors
      --[no-]filter-unverified   Only output first unverified result per chunk per detector if there
                                 are more than one results.
      --filter-entropy=FILTER-ENTROPY
                                 Filter unverified results with Shannon entropy. Start with 3.0.
      --config=CONFIG            Path to configuration file.
      --[no-]print-avg-detector-time
                                 Print the average time spent on each detector.
      --[no-]no-update           Don't check for updates.
      --[no-]fail                Exit with code 183 if results are found.
      --[no-]fail-on-scan-errors
                                 Exit with non-zero error code if an error occurs during the scan.
      --verifier=VERIFIER ...    Set custom verification endpoints.
      --[no-]custom-verifiers-only
                                 Only use custom verification endpoints.
      --detector-timeout=DETECTOR-TIMEOUT
                                 Maximum time to spend scanning chunks per detector (e.g., 30s).
      --archive-max-size=ARCHIVE-MAX-SIZE
                                 Maximum size of archive to scan. (Byte units eg. 512B, 2KB, 4MB)
      --archive-max-depth=ARCHIVE-MAX-DEPTH
                                 Maximum depth of archive to scan.
      --archive-timeout=ARCHIVE-TIMEOUT
                                 Maximum time to spend extracting an archive.
      --include-detectors="all"  Comma separated list of detector types to include. Protobuf name or
                                 IDs may be used, as well as ranges.
      --exclude-detectors=EXCLUDE-DETECTORS
                                 Comma separated list of detector types to exclude. Protobuf name
                                 or IDs may be used, as well as ranges. IDs defined here take
                                 precedence over the include list.
      --[no-]no-verification-cache
                                 Disable verification caching
      --[no-]force-skip-binaries
                                 Force skipping binaries.
      --[no-]force-skip-archives
                                 Force skipping archives.
      --[no-]skip-additional-refs
                                 Skip additional references.
      --user-agent-suffix=USER-AGENT-SUFFIX
                                 Suffix to add to User-Agent.
      --[no-]version             Show application version.

Commands:
help [<command>...]
    Show help.

git [<flags>] <uri>

    Find credentials in git repositories.

github [<flags>]
    Find credentials in GitHub repositories.

github-experimental --repo=REPO [<flags>]
    Run an experimental GitHub scan. Must specify at least one experimental sub-module to run:
    object-discovery.

gitlab --token=TOKEN [<flags>]
    Find credentials in GitLab repositories.

filesystem [<flags>] [<path>...]
    Find credentials in a filesystem.

s3 [<flags>]
    Find credentials in S3 buckets.

gcs [<flags>]
    Find credentials in GCS buckets.

syslog --format=FORMAT [<flags>]
    Scan syslog

circleci --token=TOKEN
    Scan CircleCI
```

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

### Initialize Global Git Hooks Directory

Source: https://github.com/trufflesecurity/trufflehog/blob/main/PreCommit.md

Commands to create and configure a global directory for Git hooks.

```bash
mkdir -p ~/.git-hooks
```

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

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

### Run Generic Detector via CLI

Source: https://github.com/trufflesecurity/trufflehog/blob/main/examples/README.md

Downloads a generic detector configuration and executes a filesystem scan. The second command demonstrates filtering output for specific generic credentials.

```bash
wget https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/examples/generic.yml
trufflehog filesystem --config=$PWD/generic.yml $PWD

# to filter so that _only_ generic credentials are logged:
trufflehog filesystem --config=$PWD/generic.yml --json --no-verification $PWD | awk '/generic-api-key/{print $0}'
```

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

### Accessing Latest Secret Version from GCP Secrets Manager

Source: https://github.com/trufflesecurity/trufflehog/blob/main/hack/docs/Adding_Detectors_Internal.md

This bash command retrieves the latest version of a secret from Google Cloud Secrets Manager. Ensure you have the Google Cloud SDK installed and authenticated.

```bash
gcloud secrets versions access --project trufflehog-testing --secret detectors5 latest > /tmp/s
```

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

### Scan All Images Under a Namespace (Beta)

Source: https://github.com/trufflesecurity/trufflehog/blob/main/pkg/sources/docker/README.md

Scan all images within a given namespace. This feature is currently in beta.

```bash
trufflehog docker --namespace trufflesecurity
```

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

### Scan Namespace Including Private Images (Beta)

Source: https://github.com/trufflesecurity/trufflehog/blob/main/pkg/sources/docker/README.md

Scan all images within a namespace, including private ones, by providing a registry token.

```bash
trufflehog docker --namespace trufflesecurity --registry-token ghp_xxxxxxxxxxxxxxxxxxxx
```

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

### Run TruffleHog with Custom Detector Configuration

Source: https://github.com/trufflesecurity/trufflehog/blob/main/pkg/custom_detectors/CUSTOM_DETECTORS.md

Execute TruffleHog with a custom detector configuration file. Replace placeholders with your actual file paths.

```bash
trufflehog filesystem <path_to_folder_or_file> --config=<path_to_file>/config.yaml
```

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

### Generate Permission Types

Source: https://github.com/trufflesecurity/trufflehog/blob/main/pkg/analyzer/README.md

Run the `go generate` command to generate permission types for your analyzer. This command should be placed at the top of your analyzer implementation file.

```bash
go generate ./...
```

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

### Namespace Scanning Configuration (YAML)

Source: https://github.com/trufflesecurity/trufflehog/blob/main/pkg/sources/docker/README.md

Configure namespace scanning using a YAML file. Specify the source type as 'docker', provide a name for the scan, and define the namespace and optional registry token within the docker configuration.

```yaml
sources:
  - type: docker
    name: org-scan
    docker:
      namespace: myorg
      registry_token: "ghp_xxxxxxxxxxxxxxxxxxxx"
```

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

### Generate Protocol Buffer files

Source: https://github.com/trufflesecurity/trufflehog/blob/main/hack/docs/Adding_Detectors_external.md

Generates protocol buffer files after adding new detectors to the proto definition. This command requires Docker to be running.

```bash
make protos
```

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

### Run detector tests

Source: https://github.com/trufflesecurity/trufflehog/blob/main/hack/docs/Adding_Detectors_external.md

Execute tests for a specific detector using the go test command with the detectors tag.

```bash
go test ./pkg/detectors/<detector> -tags=detectors
```

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

### Go Verification Server Implementation

Source: https://github.com/trufflesecurity/trufflehog/blob/main/pkg/custom_detectors/CUSTOM_DETECTORS.md

A Go HTTP server implementation for verifying secrets detected by custom regex. It checks for a specific authorization header and parses JSON payloads containing secret tokens.

```go
package main

import (
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
)

const authHeader = "super secret authorization header"

type HogTokenDetector struct {
	Token string `json:"token"`
}

type RequestBody struct {
	HogTokenDetector HogTokenDetector `json:"HogTokenDetector"`
}

func validateTokens(token string) bool {
	return false // Implement actual validation logic
}

func verifierHandler(w http.ResponseWriter, r *http.Request) {
	if r.Method != http.MethodPost {
		http.Error(w, "Method Not Allowed", http.StatusMethodNotAllowed)
		return
	}

	if r.Header.Get("Authorization") != authHeader {
		http.Error(w, "Unauthorized", http.StatusUnauthorized)
		return
	}

	body, err := io.ReadAll(r.Body)
	if err != nil {
		http.Error(w, "Bad Request", http.StatusBadRequest)
		return
	}
	defer r.Body.Close()

	var requestBody RequestBody
	if err := json.Unmarshal(body, &requestBody); err != nil {
		http.Error(w, "Bad Request", http.StatusBadRequest)
		return
	}

	log.Printf("Received Request: %+v", requestBody)

	if validateTokens(requestBody.HogTokenDetector.Token) {
		http.Error(w, "Forbidden", http.StatusForbidden)
	} else {
		w.WriteHeader(http.StatusOK)
	}
}

func main() {
	http.HandleFunc("/", verifierHandler)
	serverAddr := ":8000"
	fmt.Printf("Starting server on %s...\n", serverAddr)
	if err := http.ListenAndServe(serverAddr, nil); err != nil {
		log.Fatalf("Server failed: %s", err)
	}
}

```

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

### Run TruffleHog via Docker

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Execute a GitHub scan using the official Docker image.

```bash
docker run --rm -it -v "$PWD:/pwd" trufflesecurity/trufflehog:latest github --org=trufflesecurity
```

```bash
docker run --rm -it -v "$PWD:/pwd" trufflesecurity/trufflehog:latest github --repo https://github.com/trufflesecurity/test_keys
```

```cmd
docker run --rm -it -v "%cd:/=\%:/pwd" trufflesecurity/trufflehog:latest github --repo https://github.com/trufflesecurity/test_keys
```

```powershell
docker run --rm -it -v "${PWD}:/pwd" trufflesecurity/trufflehog github --repo https://github.com/trufflesecurity/test_keys
```

```bash
docker run --platform linux/arm64 --rm -it -v "$PWD:/pwd" trufflesecurity/trufflehog:latest github --repo https://github.com/trufflesecurity/test_keys
```

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

### Make Pre-commit Hook Executable

Source: https://github.com/trufflesecurity/trufflehog/blob/main/PreCommit.md

Ensure the `.git/hooks/pre-commit` file has execute permissions. This is a common troubleshooting step if the hook is not running.

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

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

### Set Global Git Hooks Path

Source: https://github.com/trufflesecurity/trufflehog/blob/main/PreCommit.md

Command to point Git to the custom hooks directory.

```bash
git config --global core.hooksPath ~/.git-hooks
```

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

### Scan Specific Directories with checksecretparts

Source: https://github.com/trufflesecurity/trufflehog/blob/main/hack/checksecretparts/README.md

Run the checksecretparts tool on specific directories instead of the default ./pkg/detectors. This allows for targeted analysis of particular detector packages.

```sh
go run ./hack/checksecretparts ./pkg/detectors/aws ./pkg/detectors/github
```

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

### Configure Pre-commit Hook

Source: https://github.com/trufflesecurity/trufflehog/blob/main/PreCommit.md

YAML configuration for the pre-commit framework.

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

```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 --trust-local-git-config'
        language: system
        stages: ["pre-commit", "pre-push"]
```

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

### Run checksecretparts in Warning Mode

Source: https://github.com/trufflesecurity/trufflehog/blob/main/hack/checksecretparts/README.md

Execute the checksecretparts tool to identify detector packages that do not populate the SecretParts field. This mode prints findings and exits with a success code unless scanning fails.

```sh
go run ./hack/checksecretparts
```

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

### Dockerized Husky Pre-commit Hook Configuration

Source: https://github.com/trufflesecurity/trufflehog/blob/main/PreCommit.md

Configure the `.husky/pre-commit` file to use a Docker container for running TruffleHog. This ensures consistent execution across different environments.

```bash
echo 'docker run --rm -v "$(pwd):/workdir" -i --rm trufflesecurity/trufflehog:latest git file:///workdir' > .husky/pre-commit
```

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

### Scan Multiple Docker Images

Source: https://github.com/trufflesecurity/trufflehog/blob/main/pkg/sources/docker/README.md

Scan multiple Docker images sequentially by listing them with the --image flag multiple times.

```bash
trufflehog docker --image nginx:latest --image postgres:13 --image redis:alpine
```

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

### Check Git Hooks Path Configuration

Source: https://github.com/trufflesecurity/trufflehog/blob/main/PreCommit.md

Verify the Git configuration for `core.hooksPath`. This command helps diagnose issues where pre-commit hooks are not being found or executed.

```bash
git config --get core.hooksPath
```

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

### Scan Image from Local Docker Daemon

Source: https://github.com/trufflesecurity/trufflehog/blob/main/pkg/sources/docker/README.md

Scan a Docker image that is available in your local Docker daemon by prefixing the image name with 'docker://'.

```bash
trufflehog docker --image docker://myapp:local
```

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

### Scan All Images Under a Namespace (CLI)

Source: https://github.com/trufflesecurity/trufflehog/blob/main/pkg/sources/docker/README.md

Use this command to scan all Docker images within a specified namespace. Docker Hub is used by default if no registry prefix is provided. For other registries, include the full registry path.

```bash
trufflehog docker --namespace myorg
```

```bash
trufflehog docker --namespace quay.io/my_namespace
```

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

### Configure TruffleHog GitHub Action

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Standard configuration for the TruffleHog GitHub Action. Use the base and head arguments to specify commit ranges for scanning.

```yaml
- name: TruffleHog
  uses: trufflesecurity/trufflehog@main
  with:
    # Repository path
    path:
    # Start scanning from here (usually main branch).
    base:
    # Scan commits until here (usually dev branch).
    head: # optional
    # Extra args to be passed to the trufflehog cli.
    extra_args: --log-level=2 --results=verified,unknown
```

```yaml
- name: scan-push
        uses: trufflesecurity/trufflehog@main
        with:
          base: ""
          head: ${{ github.ref_name }}
          extra_args: --results=verified,unknown
```

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

### Scan All Hugging Face Resources for an Organization or User

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Scan all models, datasets, and spaces belonging to a specific Hugging Face organization or user. Options to skip or ignore specific resource types or IDs are available.

```bash
trufflehog huggingface --org <orgname> --user <username>
```

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

### Clone and Scan Local Git Repository

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Clones a local Git repository and then scans it for secrets. TruffleHog clones to a temporary directory by default for security.

```bash
git clone git@github.com:trufflesecurity/test_keys.git
```

```bash
trufflehog git file://test_keys --results=verified,unknown
```

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

### Scan Hugging Face Model, Dataset, or Space

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Scan individual Hugging Face resources like models, datasets, or spaces by providing their respective IDs.

```bash
trufflehog huggingface --model <model_id> --space <space_id> --dataset <dataset_id>
```

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

### Docker Image Reference Formats

Source: https://github.com/trufflesecurity/trufflehog/blob/main/pkg/sources/docker/README.md

Specifies the different formats for referencing Docker images, including remote registries, local Docker daemon, and tarball files.

```text
// Remote registry (default)
"nginx:latest"
"myregistry.com/myapp:v1.0.0"
"gcr.io/project/image@sha256:abcd1234..."
```

```text
// Local Docker daemon
"docker://nginx:latest"
```

```text
// Tarball file
"file:///path/to/image.tar"
```

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

### Configure Docker Git Hook Script

Source: https://github.com/trufflesecurity/trufflehog/blob/main/PreCommit.md

Scripts for running TruffleHog via Docker as a pre-commit hook.

```bash
#!/bin/sh
# Set environment variable inside container (recommended)
docker run --rm \
  -v "$(pwd):/workdir" \
  -e "TRUFFLEHOG_PRE_COMMIT=1" \
  trufflesecurity/trufflehog:latest \
  git file:///workdir
```

```bash
#!/bin/sh

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

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

### Scan Private Registry Image with Authentication

Source: https://github.com/trufflesecurity/trufflehog/blob/main/pkg/sources/docker/README.md

Scan a private Docker image from a registry. Ensure you are logged into the registry (e.g., using `docker login`) before running the scan. TruffleHog will use the credentials configured in your Docker environment.

```bash
docker login my-registry.io
trufflehog docker --image my-registry.io/private-app:v1.0.0
```

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

### Scan S3 Bucket with TruffleHog (Local Credentials)

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Scan a specific S3 bucket using locally set credentials or instance metadata. Replace `<bucket-name>` with your actual bucket name.

```bash
trufflehog s3 --bucket=<bucket-name>
```

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

### Manual Husky Pre-commit Hook Configuration

Source: https://github.com/trufflesecurity/trufflehog/blob/main/PreCommit.md

If auto-detection fails, manually specify TruffleHog settings for the pre-commit hook. This includes specifying commit range, results, and failure conditions.

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

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

### Run checksecretparts in Fail Mode

Source: https://github.com/trufflesecurity/trufflehog/blob/main/hack/checksecretparts/README.md

Execute the checksecretparts tool in fail mode. This mode will exit with a status code of 1 if any findings are reported, making it suitable for gating CI/CD pipelines once all detectors are compliant.

```sh
go run ./hack/checksecretparts -fail
```

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

### Scan Git Repository for Verified Secrets with JSON Output

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Scans a Git repository for verified secrets and outputs the results in JSON format. Useful for programmatic processing.

```bash
trufflehog git https://github.com/trufflesecurity/test_keys --results=verified --json
```

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

### Scan All Scanners

Source: https://github.com/trufflesecurity/trufflehog/blob/main/hack/snifftest/README.md

Perform a scan using all configured secret scanners. Requires a database path and prints the results.

```bash
go run snifftest/main.go scan --db ~/sdb --scanner all --print
```

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

### Python Verification Server Implementation

Source: https://github.com/trufflesecurity/trufflehog/blob/main/pkg/custom_detectors/CUSTOM_DETECTORS.md

A Python HTTP server implementation for verifying secrets detected by custom regex. It expects a specific authorization header and processes POST requests containing secret tokens.

```python
import json
from http.server import BaseHTTPRequestHandler, HTTPServer

AUTH_HEADER = 'super secret authorization header'

class Verifier(BaseHTTPRequestHandler):
    def do_GET(self):
        self.send_response(405)
        self.end_headers()

    def do_POST(self):
        try:
            if self.headers['Authorization'] != AUTH_HEADER:
                self.send_response(401)
                self.end_headers()
                return

            length = int(self.headers['Content-Length'])
            request = json.loads(self.rfile.read(length))
            self.log_message("%s", request)

            if not validateTokens(request['HogTokenDetector']['token']):
                self.send_response(200)
                self.end_headers()
            else:
                self.send_response(403)
                self.end_headers()
        except Exception:
            self.send_response(400)
            self.end_headers()

def validateTokens(token):
    return False  # Implement actual validation logic

with HTTPServer(('', 8000), Verifier) as server:
    try:
        server.serve_forever()
    except KeyboardInterrupt:
        pass

```

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

### Scan Git Repository for Verified Secrets

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Scans a specified Git repository for verified secrets. This is a quick way to find known secrets.

```bash
trufflehog git https://github.com/trufflesecurity/test_keys --results=verified
```

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

### Scan Namespace Including Private Images (CLI)

Source: https://github.com/trufflesecurity/trufflehog/blob/main/pkg/sources/docker/README.md

To include private images within a namespace scan, provide a registry token using the --registry-token flag.

```bash
trufflehog docker --namespace myorg --registry-token <access_token>
```

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

### Show Available Secret Scanners

Source: https://github.com/trufflesecurity/trufflehog/blob/main/hack/snifftest/README.md

Use this command to display a list of all secret scanners available within the snifftest tool.

```bash
go run hack/snifftest/main.go show-scanners
```

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

### Scan Docker Image from Tarball

Source: https://github.com/trufflesecurity/trufflehog/blob/main/pkg/sources/docker/README.md

Scan a Docker image that has been saved to a tarball. Use the 'file://' prefix followed by the path to the tarball.

```bash
docker save myapp:latest -o myapp.tar
trufflehog docker --image file:///path/to/myapp.tar
```

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

### Scan GCS Buckets for Verified Secrets

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Use this command to scan Google Cloud Storage buckets for verified secrets. Requires a project ID.

```bash
trufflehog gcs --project-id=<project-ID> --cloud-environment --results=verified
```

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

### Scan S3 Bucket with TruffleHog (Assumed Role)

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Scan a specific S3 bucket by assuming an IAM role. Replace `<bucket-name>` and `<iam-role-arn>` with your specific values.

```bash
trufflehog s3 --bucket=<bucket-name> --role-arn=<iam-role-arn>
```

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

### YAML Configuration for Basic Authentication

Source: https://github.com/trufflesecurity/trufflehog/blob/main/pkg/sources/docker/README.md

Configure TruffleHog to scan private Docker images using basic authentication with a username and password in YAML. This method is for registries that support username/password login.

```yaml
sources:
  - type: docker
    name: private-registry
    docker:
      basic_auth:
        username: myuser
        password: mypassword
      images:
        - myregistry.com/private-image:latest
        - myregistry.com/another-image:v1.0.0
```

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

### Prerequisites for Docker Keychain Authentication

Source: https://github.com/trufflesecurity/trufflehog/blob/main/pkg/sources/docker/README.md

Commands to authenticate with Docker registries and verify that credentials are being stored locally, which is required for the Docker keychain authentication method.

```bash
# Authenticate with your registry first
docker login
docker login ghcr.io
docker login quay.io

# Verify credentials are stored
cat ~/.docker/config.json
```

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

### Convert script to Unix format

Source: https://github.com/trufflesecurity/trufflehog/blob/main/hack/docs/Adding_Detectors_external.md

Converts the gen_proto.sh script to Unix format using dos2unix. This is a prerequisite for running the script on Unix-like systems.

```bash
dos2unix ./scripts/gen_proto.sh
```

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

### Scan Filesystem for Secrets

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Scans individual files or directories on the local filesystem for secrets. Provide the paths to the files or directories to be scanned.

```bash
trufflehog filesystem path/to/file1.txt path/to/file2.txt path/to/dir
```

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

### Scan GitHub Organization for Verified Secrets

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Scans all repositories within a GitHub organization for verified secrets. Requires appropriate GitHub permissions.

```bash
trufflehog github --org=trufflesecurity --results=verified
```

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

### Scan Particular Scanner with Chunk Printing

Source: https://github.com/trufflesecurity/trufflehog/blob/main/hack/snifftest/README.md

Scan using a specific scanner (e.g., 'github'), print results in chunks, and set a failure threshold.

```bash
go run snifftest/main.go scan --db ~/sdb --scanner github --print --print-chunk --fail-threshold 5
```

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

### Scan Docker Images for Verified Secrets

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Scan Docker images for verified secrets. Supports scanning from remote registries, local Docker daemons, or tarball archives.

```bash
# to scan from a remote registry
trufflehog docker --image trufflesecurity/secrets --results=verified
```

```bash
# to scan from the local docker daemon
trufflehog docker --image docker://new_image:tag --results=verified
```

```bash
# to scan from an image saved as a tarball
trufflehog docker --image file://path_to_image.tar --results=verified
```

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

### Scan GitHub Repository and its Comments

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Scans a GitHub repository, including its issue comments and pull request comments, for secrets. This provides a more comprehensive scan.

```bash
trufflehog github --repo=https://github.com/trufflesecurity/test_keys --issue-comments --pr-comments
```

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

### Audit Mode: Local Binary Version

Source: https://github.com/trufflesecurity/trufflehog/blob/main/PreCommit.md

Run TruffleHog in audit mode using the local binary to test the pre-commit hook functionality without enforcing failures. This command suppresses stderr output.

```bash
trufflehog git file://. --since-commit HEAD --results=verified,unknown 2>/dev/null
```

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

### CLI Usage for Docker Keychain Authentication

Source: https://github.com/trufflesecurity/trufflehog/blob/main/pkg/sources/docker/README.md

Scan a Docker image using credentials stored in your local Docker keychain. Ensure you have logged in to the registry using `docker login` beforehand.

```bash
# First, authenticate with Docker
docker login myregistry.com

# Then scan using stored credentials
trufflehog docker --image myregistry.com/private-image:latest
```

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

### Generate a New Secret Detector

Source: https://github.com/trufflesecurity/trufflehog/blob/main/hack/docs/Adding_Detectors_external.md

Use the provided Go script to generate boilerplate code for a new secret detector based on its enum name.

```bash
go run hack/generate/generate.go detector <DetectorType enum name>
example: go run hack/generate/generate.go detector SampleAPI
```

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

### Scan GitHub Repo via SSH in Docker

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Scans a GitHub repository for secrets using SSH authentication within a Docker container. Mounts the SSH keys for authentication.

```bash
docker run --rm -v "$HOME/.ssh:/root/.ssh:ro" trufflesecurity/trufflehog:latest git ssh://github.com/trufflesecurity/test_keys
```

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

### YAML Configuration for Docker Keychain Authentication

Source: https://github.com/trufflesecurity/trufflehog/blob/main/pkg/sources/docker/README.md

Configure TruffleHog to use credentials stored in the local Docker configuration file (`~/.docker/config.json`) for authentication. Set 'docker_keychain: true' in the YAML.

```yaml
sources:
  - type: docker
    name: local-docker-creds
    docker:
      docker_keychain: true
      images:
        - myregistry.com/private-image:latest
        - docker.io/myorg/app:latest
```

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

### Scan S3 Bucket for Verified and Unknown Secrets

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Scans a specified S3 bucket for secrets, including both verified and unknown types. Ensure the bucket name is correctly provided.

```bash
trufflehog s3 --bucket=<bucket name> --results=verified,unknown
```

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

### Scan Jenkins Server for Secrets

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Scan a Jenkins server for secrets using its URL, username, and password.

```bash
trufflehog jenkins --url https://jenkins.example.com --username admin --password admin
```

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

### YAML Configuration for Bearer Token Authentication

Source: https://github.com/trufflesecurity/trufflehog/blob/main/pkg/sources/docker/README.md

Configure TruffleHog to scan Docker images using a bearer token for authentication, commonly used with registries like Docker Hub or GitHub Container Registry. Provide the token in the 'bearer_token' field.

```yaml
sources:
  - type: docker
    name: truffle-packages
    docker:
      bearer_token: "ghp_xxxxxxxxxxxxxxxxxxxx"
      images:
        - myorg/myapp:latest
        - myorg/frontend:v2.1.0
```

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

### Scan Hugging Face Discussions and PR Comments

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Scan Hugging Face models for secrets within their associated discussions and pull request comments.

```bash
trufflehog huggingface --model <model_id> --include-discussions --include-prs
```

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

### Custom Detector Template

Source: https://github.com/trufflesecurity/trufflehog/blob/main/pkg/custom_detectors/CUSTOM_DETECTORS.md

A basic template for defining a custom detector in TruffleHog's config.yaml. Use this to specify detector name, keywords, and a regex pattern for secret detection.

```yaml
# config.yaml
detectors:
  - name: HogTokenDetector
    keywords:
      - hog
    regex:
      token: '[^A-Za-z0-9+\/]{0,1}([A-Za-z0-9+\/]{40})[^A-Za-z0-9+\/]{0,1}'
    verify:
      - endpoint: http://localhost:8000/
        # 'unsafe' must be set to true if the endpoint uses HTTP
        unsafe: true
        headers:
          - "Authorization: super secret authorization header"
```

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

### Scan Elasticsearch Local Cluster with Service Token

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Connect to a local Elasticsearch cluster using a service token for authentication. Specify the nodes by their IP addresses.

```bash
trufflehog elasticsearch --nodes 192.168.14.3 192.168.14.4 --service-token ‘AAEWVaWM...Rva2VuaSDZ’
```

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

### Verify TruffleHog Artifact Signature

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Verifies the signature of downloaded TruffleHog artifact checksums using cosign. Ensure you have the checksums, certificate, and signature files.

```shell
cosign verify-blob <path to trufflehog_{version}_checksums.txt> \
--certificate <path to trufflehog_{version}_checksums.txt.pem> \
--signature <path to trufflehog_{version}_checksums.txt.sig> \
--certificate-identity-regexp 'https://github\.com/trufflesecurity/trufflehog/\.github/workflows/.+' \
--certificate-oidc-issuer "https://token.actions.githubusercontent.com"
```

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

### Scan S3 Buckets with Multiple Assumed Roles

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Scan S3 buckets by assuming multiple IAM roles. TruffleHog will attempt to scan buckets accessible by each provided role ARN.

```bash
trufflehog s3 --role-arn=<iam-role-arn-1> --role-arn=<iam-role-arn-2>
```

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

### Scan Elasticsearch Local Cluster with Username/Password

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Connect to a local Elasticsearch cluster using username and password authentication. Specify the nodes by their IP addresses.

```bash
trufflehog elasticsearch --nodes 192.168.14.3 192.168.14.4 --username truffle --password hog
```

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

### CLI Usage for Bearer Token Authentication

Source: https://github.com/trufflesecurity/trufflehog/blob/main/pkg/sources/docker/README.md

Scan a Docker image using the TruffleHog CLI with a bearer token. This is useful for accessing private images in registries that support token-based authentication.

```bash
trufflehog docker --image myorg/myapp:latest --bearer-token eyJ_xxxxxxxxxxxxxxxxxxxx
```

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

### Scan in CI for Verified and Unknown Secrets with Failure

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Configure TruffleHog for CI/CD pipelines. Use `--since-commit` and `--branch` to specify the scan scope. The `--fail` flag will exit with an error code if secrets are found.

```bash
trufflehog git file://. --since-commit main --branch feature-1 --results=verified,unknown --fail
```

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

### CLI Usage for Unauthenticated Docker Images

Source: https://github.com/trufflesecurity/trufflehog/blob/main/pkg/sources/docker/README.md

Scan a specific Docker image using the TruffleHog CLI without requiring authentication. This is suitable for public images.

```bash
trufflehog docker --image nginx:latest
```

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

### Scan Elastic Cloud Cluster

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Scan a cluster hosted on Elastic Cloud using its Cloud ID and API key for authentication.

```bash
trufflehog elasticsearch \
  --cloud-id 'search-prod:dXMtY2Vx...YjM1ODNlOWFiZGRlNjI0NA==' \
  --api-key 'MlVtVjBZ...ZSYlduYnF1djh3NG5FQQ=='
```

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

### YAML Configuration for Unauthenticated Docker Images

Source: https://github.com/trufflesecurity/trufflehog/blob/main/pkg/sources/docker/README.md

Configure TruffleHog to scan public Docker images without authentication using YAML. Ensure the 'docker' type is specified with 'unauthenticated: {}'.

```yaml
sources:
  - type: docker
    name: public-images
    docker:
      unauthenticated: {}
      images:
        - nginx:latest
        - alpine:3.18
```

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

### Custom Detector with Verification Ranges

Source: https://github.com/trufflesecurity/trufflehog/blob/main/pkg/custom_detectors/CUSTOM_DETECTORS.md

An advanced custom detector configuration that includes specific ranges for success and rotated status codes when verifying secrets. This allows for more granular control over how detected secrets are classified.

```yaml
# config.yaml
detectors:
  - name: HogTokenDetector
    keywords:
      - hog
    regex:
      token: '[^A-Za-z0-9+\/]{0,1}([A-Za-z0-9+\/]{40})[^A-Za-z0-9+\/]{0,1}'
    verify:
      - endpoint: http://localhost:8000/
        unsafe: true
        headers:
          - "Authorization: super secret authorization header"
        successRanges:
          - "200"
        rotatedRanges:
          - "401"
          - "403"
```

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

### Validate TruffleHog Artifact Checksums

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Validates the SHA256 sums of downloaded TruffleHog artifacts against the checksum file. This command should be run after signature verification.

```shell
sha256sum --ignore-missing -c trufflehog_{version}_checksums.txt
```

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

### Bypass Pre-commit Hooks

Source: https://github.com/trufflesecurity/trufflehog/blob/main/PreCommit.md

Use this command to skip all pre-commit hooks, including TruffleHog, for a specific commit. This is useful in rare situations where hooks need to be bypassed.

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

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

### Scan Postman Workspace for Secrets

Source: https://github.com/trufflesecurity/trufflehog/blob/main/README.md

Scan a Postman workspace for secrets using a provided API token and workspace ID. Multiple targets can be scanned using flags like `--workspace-id` and `--collection-id`.

```bash
trufflehog postman --token=<postman api token> --workspace-id=<workspace id>
```