Talisman

A tool to detect and prevent secrets from getting checked in

Table of Contents

• What is Talisman?
• Installation
  • Install onto path (recommended approach)
  • Installation as a global hook template
• Configuring a project
  • Using with hook frameworks
    • Pre-commit
    • Husky
  • Directly invoking talisman
• Upgrading
• Talisman in action
  • Validations
  • Ignoring Files
    • Interactive mode
    • Ignoring specific detectors
    • Ignoring specific keywords
    • Ignoring multiple files of same type (with wildcards)
    • Ignoring files by specifying language scope
    • Custom search patterns
  • Configuring severity threshold
  • Talisman as a CLI utility
    • Interactive mode
    • Git history Scanner
    • Checksum Calculator
• Talisman HTML Reporting
  • Sample Screenshots
• Uninstallation
  • Uninstallation from a global hook template
  • Uninstallation from a single repository
• Contributing to Talisman

What is Talisman?

Talisman is a tool that scans git changesets to ensure that potential secrets or sensitive information do not leave the developer's workstation.

It validates the outgoing changeset for things that look suspicious - such as potential SSH keys, authorization tokens, private keys etc.

Installation

Talisman supports MAC OSX, Linux and Windows.

Talisman can be installed and used in one of the following ways:

1. As a standalone executable
2. As a git hook as a global git hook template and a CLI utility (for git repo scanning)
3. As a git hook into a single git repository

Talisman can be set up as either a pre-commit or pre-push hook on the git repositories.

Find the instructions below.

Disclaimer: Secrets creeping in via a forced push in a git repository cannot be detected by Talisman. A forced push is believed to be notorious in its own ways, and we suggest git repository admins to apply appropriate measures to authorize such activities.

Install onto path (recommended approach)

We recommend installing talisman onto your path so that it is available for git hook frameworks and scripts. Pick the correct binary for your system from our Releases Page, or run our install script:

bash -c "$(curl --silent https://raw.githubusercontent.com/thoughtworks/talisman/main/install.sh)"

Or set environment variable INSTALL_LOCATION to specify a custom location for the binary:

INSTALL_LOCATION=/usr/local/bin bash -c "$(curl --silent https://raw.githubusercontent.com/thoughtworks/talisman/main/install.sh)"

Or set environment variable VERSION to a released tag to install a specific version::

VERSION=v1.36.0 bash -c "$(curl --silent https://raw.githubusercontent.com/thoughtworks/talisman/main/install.sh)"

Or using linuxbrew in Linux and homebrew in macOS by running the following command in terminal:

brew install talisman

Installation as a global hook template

We offer scripts that will install Talisman as a pre-commit git hook template, as that will cause Talisman to be present, not only in your existing git repositories, but also in any new repository that you 'init' or 'clone'.

1. Run the following command on your terminal, to download and install the binary at $HOME/.talisman/bin

As a pre-commit hook:

bash -c "$(curl --silent https://raw.githubusercontent.com/thoughtworks/talisman/main/global_install_scripts/install.bash)"

OR

As a pre-push hook:

bash -c "$(curl --silent https://raw.githubusercontent.com/thoughtworks/talisman/main/global_install_scripts/install.bash)" -- pre-push

2. If you do not have TALISMAN_HOME set up in your $PATH, you will be asked an appropriate place to set it up. Choose the option number where you set the profile source on your machine.

Remember to execute source on the path file or restart your terminal. If you choose to set the $PATH later, please export TALISMAN_HOME=$HOME/.talisman/bin to the path.

3. Choose a base directory where Talisman should scan for all git repositories, and set up a git hook (pre-commit or pre-push, as chosen in step 1) as a symlink. This script will not clobber pre-existing hooks. If you have existing hooks you can add talisman through a hook framework

• you can set SEARCH_ROOT environment variable with the path of the base directory before executing the installation so you don't need to input it manually during the installation

Configuring a project

Using with hook frameworks

Globally installing talisman as a hook will not clobber any existing hooks. If the installation script finds any existing hooks, it will only indicate so on the console. To run multiple hooks we suggest using a hook framework, such as pre-commit or husky. These instructions assume that the talisman executable is installed somewhere on your system's path.

Pre-commit

Use pre-commit to manage existing hooks along with Talisman. Reference our pre-commit-hooks in your .pre-commit-config.yaml:

-   repo: https://github.com/thoughtworks/talisman
    rev: 'v1.32.2'  # Update me!
    hooks:
      # both pre-commit and pre-push supported
      # -   id: talisman-push
      - id: talisman-commit

Husky

husky is an npm module for managing hooks. Add the following line to the husky pre-commit configuration in your package.json:

talisman --githook pre-commit

Directly invoking talisman

Once the talisman executable is installed you can configure a standalone pre-commit hook for a git repository:

cd my-git-project
echo "talisman -g pre-commit" >> .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

Upgrading

Since release v0.4.4, Talisman automatically updates the binary to the latest release, when the hook is invoked (at pre-commit/pre-push, as set up). So, just sit back, relax, and keep using the latest Talisman without any extra efforts.