Usage¶
History Scan¶
By default, tartufo will scan the entire history of a git repo. The repo to be scanned can be specified in one of two ways. The first, default behavior, is by passing a git URL to tartufo. For example:
$ tartufo https://github.com/godaddy/tartufo.git
For docker
:
$ docker run --rm godaddy/tartufo https://github.com/godaddy/tartufo.git
When used this way, tartufo will clone the repository to a temporary directory, scan the local clone, and then delete it.
Alternatively, if you already have a local clone, you can scan that directly without the need for the temporary clone:
$ tartufo --repo-path /path/to/my/repo
For docker
, mount the local clone to the /git
folder in the docker image:
$ docker run --rm -v "/path/to/my/repo:/git" godaddy/tartufo
When scanning private repositories, the docker
runtime needs to have access to SSH keys for authorization.
Make sure ssh-agent
is running on your host machine and has the key added. (Verify using ssh-add -L
on host machine).
For Docker for Linux, mount the location of SSH_AUTH_SOCK
to a location in the docker container, and point the environment variable SSH_AUTH_SOCK
to the same location:
$ docker run --rm -v "/path/to/my/repo:/git" -v $SSH_AUTH_SOCK:/agent -e SSH_AUTH_SOCK=/agent godaddy/tartufo
If using Docker Desktop for Mac, use /run/host-services/ssh-auth.sock
both as source and target, and point the environment variable SSH_AUTH_SOCK
to the same location:
$ docker run --rm -v "/path/to/my/repo:/git" -v /run/host-services/ssh-auth.sock:/run/host-services/ssh-auth.sock -e SSH_AUTH_SOCK="/run/host-services/ssh-auth.sock" godaddy/tartufo
Pre-commit¶
The --pre-commit
flag instructs tartufo to scan staged, uncommitted changes
in a local repository. The repository location can be specified using
--repo-path
, but it is legal to not supply a location; in this case, the
caller’s current working directory is assumed to be somewhere within the local
clone’s tree and the repository root is determined automatically.
The following example demonstrates how tartufo can be used in .git/hooks/pre-commit
to verify that secrets
will not be committed to a git repository in error:
#!/bin/sh
# Redirect output to stderr.
exec 1>&2
# Check for suspicious content.
tartufo --pre-commit --regex --entropy
Git will execute tartufo before committing any content. If problematic changes are detected, they are reported by tartufo and git aborts the commit process. Only when tartufo returns a success status (indicating no potential secrets were discovered) will git commit the staged changes.
Note that it is always possible, although not recommended, to bypass the
pre-commit hook by using git commit --no-verify
.
If you would like to automate these hooks, you can use either the Python
or Docker
approach to setting up tartufo as a pre-commit hook
Python pre-commit hook¶
Add a .pre-commit-config.yaml
file to your repository. You can copy and paste the following to get you started:
- repo: https://github.com/godaddy/tartufo
rev: master
hooks:
- id: tartufo
That’s it! Now your contributors only need to run pre-commit install
--install-hooks
, and tartufo will automatically be run as a pre-commit hook.
Warning
You probably don’t actually want to use the master rev. This is the active development branch for this project, and can not be guaranteed stable. Your best bet would be to choose the latest version, currently 1.1.2.
Docker pre-commit hook¶
Use the docker image as pre-commit hook by adding the docker run command to .git/hooks/pre-commit
:
docker pull godaddy/tartufo
cat <<EOF > .git/hooks/pre-commit
docker run -t --rm -v "$PWD:/git" godaddy/tartufo --pre-commit
EOF
Temporary File Cleanup¶
tartufo stores the results in temporary files, which are left on disk by
default, to allow inspection if problems are found. To automatically delete
these files when tartufo completes, specify the --cleanup
flag:
tartufo --cleanup