TruffleHog Scanning Options & Repository Path: How to Use file:/// and --repo_path in Docker‑Based Labs

Learn exactly what file:/// points to, how the --repo_path flag works inside a container, and how to control branch scanning with TruffleHog.

Introduction

TruffleHog is a popular open‑source tool for detecting secrets (API keys, passwords, tokens, etc.) in Git repositories. In many DevSecOps labs the tool runs inside a Docker container, and learners often wonder:

• What does the file:/// URL refer to – the host filesystem or the container’s filesystem?
• Why does the command use a --repo_path flag that isn’t listed in trufflehog --help?
• Can we replace --repo_path with a plain git URL?
• Does TruffleHog scan every branch automatically, or only a specific one?

This article answers those questions step‑by‑step, provides ready‑to‑copy command examples, and offers tips for scanning private repositories and limiting the scope of a scan.

1. Understanding file:/// and the Mounted /src Directory

1.1 What file:/// Means

file:/// is a URI scheme that tells TruffleHog to treat the following path as a local filesystem location, not a remote Git URL. When you run:

docker run --rm -v $(pwd):/src \
    hysnsec/trufflehog \
    --repo_path /src file:///src \
    --json > trufflehog-output.json

the file:///src part resolves to /src inside the Docker container.

1.2 How the Host Directory Becomes /src

• $(pwd) – the current working directory on the GitLab Runner (or your local machine).
• -v $(pwd):/src – Docker’s volume flag that bind‑mounts the host directory into the container at the path /src.

Result: everything you see in your host’s $(pwd) is available to the container at /src. TruffleHog will therefore scan the exact same files that exist on the host.

1.3 Quick Visual

Host (GitLab Runner)                Container
-------------------                ----------
/home/gitlab-runner/project   <--  /src   (mounted via -v)

When TruffleHog receives file:///src, it walks the /src directory inside the container, which mirrors the host project directory.

2. The --repo_path Flag – Why It Works Even If Not Listed

2.1 Where the Flag Comes From

The official TruffleHog binary supports a --repo_path option, but the Docker image’s entrypoint script often wraps the binary and exposes a simplified CLI. The --help output you see when you run docker run hysnsec/trufflehog --help shows only the top‑level commands, not every underlying flag. The image still forwards --repo_path to the binary, so it works.

2.2 What --repo_path Does

• --repo_path <path> tells TruffleHog to treat <path> as the root of the repository to scan.
• It is required when you are scanning a local checkout (as opposed to a remote Git URL).

2.3 Can You Use a Git URL Instead?

Yes. If you have a public repository, you can replace the file:/// syntax with a standard Git URL:

docker run --rm hysnsec/trufflehog \
    --repo_path /tmp \
    https://github.com/example/public-repo.git \
    --json > trufflehog-output.json

For private repositories you must provide authentication (SSH keys, personal access tokens, or --username/--password flags). The simple file:/// approach avoids authentication because it scans a local copy that you already have access to.

3. Branch Scanning – All Branches vs. Specific Branch

3.1 Default Behavior

By default, TruffleHog walks the entire commit history of every branch in the repository. This includes:

• master / main
• Feature branches
• Remote tracking branches (if they exist locally)

3.2 Scanning a Single Branch

If you only care about a particular branch, use the --branch flag:

docker run --rm -v $(pwd):/src hysnsec/trufflehog \
    --repo_path /src \
    file:///src \
    --branch develop \
    --json > trufflehog-output.json

Only the develop branch’s history will be examined.

3.3 Practical Test

1. Create a secret on a new branch:

   git checkout -b secret-branch
   echo "API_KEY=abcd1234" > .env
   git add .env && git commit -m "Add secret"
   git push origin secret-branch
   

2. Run TruffleHog without --branch – you’ll see the secret reported.

3. Run TruffleHog with --branch main – the secret is ignored because it lives only on secret-branch.

4. Scanning Private Repositories

• TruffleHog can scan private repos only when you provide credentials.
• Common approaches:

If you cannot expose credentials, clone the repository on the host first, then scan the local copy with file:///.

5. Full Example: Scanning a Local Repo in GitLab CI

# .gitlab-ci.yml
trufflehog_scan:
  image: hysnsec/trufflehog:latest
  stage: test
  script:
    - |
      docker run --rm \
        -v $(pwd):/src \
        hysnsec/trufflehog \
        --repo_path /src \
        file:///src \
        --branch main \
        --json > trufflehog-output.json
    - cat trufflehog-output.json   # optional: upload as artifact
  artifacts:
    paths:
      - trufflehog-output.json
    expire_in: 1 week

The job mounts the repository, scans only the main branch, and stores the JSON report as a CI artifact.

Common Questions & Tips

Tip: Always run TruffleHog on a local copy of a private repository to avoid leaking credentials in CI logs.

Conclusion

Understanding how file:/// interacts with Docker volume mounts, why the --repo_path flag works, and how to control branch scanning empowers you to integrate TruffleHog confidently into DevSecOps pipelines. Whether you’re scanning public open‑source projects or private codebases, the patterns shown here will help you get reliable secret‑detection results without unnecessary complexity. Happy hunting!