Talisman

チェックインされる秘密情報を検出・防止するツール

目次

• Talismanとは？
• インストール
  • パスにインストール（推奨）
  • グローバルフックテンプレートとしてのインストール
• プロジェクトの設定
  • フックフレームワークとの併用
    • Pre-commit
    • Husky
  • Talismanを直接実行する
• アップグレード
• Talismanの動作
  • 検証
  • ファイルの無視
    • 対話モード
    • 特定の検出器を無視する
    • 特定のキーワードを無視する
    • 同じタイプの複数ファイルを無視する（ワイルドカード使用）
    • 言語スコープを指定してファイルを無視する
    • カスタム検索パターン
  • 重大度しきい値の設定
  • CLIユーティリティとしてのTalisman
    • 対話モード
    • Git履歴スキャナー
    • チェックサム計算機
• Talisman HTMLレポート
  • サンプルスクリーンショット
• アンインストール
  • グローバルフックテンプレートからのアンインストール
  • 単一リポジトリからのアンインストール
• Talismanへの貢献

Talismanとは？

Talismanとは、gitのチェンジセットをスキャンして、潜在的な秘密情報や機密情報が開発者のワークステーションから流出しないようにするツールです。

送信されるチェンジセットを検証し、疑わしいもの（SSHキー、認証トークン、秘密鍵など）を検出します。

インストール

TalismanはMAC OSX、Linux、Windowsをサポートしています。

Talismanは以下のいずれかの方法でインストールして使用できます。

1. スタンドアロン実行ファイルとして
2. グローバルなgitフックテンプレートとして、およびCLIユーティリティ（gitリポジトリスキャン用）としてのgitフック
3. 単一のgitリポジトリへのgitフックとして

Talismanは、gitリポジトリに対してpre-commitまたはpre-pushフックとして設定できます。

以下の手順に従ってください。

免責事項：強制プッシュによってgitリポジトリに紛れ込んだ秘密情報は、Talismanでは検出できません。強制プッシュはそれ自体が悪名高い行為と考えられており、リポジトリ管理者はそのような活動を許可するための適切な対策を講じることをお勧めします。

パスにインストール（推奨）

talismanをパスにインストールすることをお勧めします。これにより、gitフックフレームワークやスクリプトから利用できるようになります。リリースページからお使いのシステムに合った正しいバイナリを選択するか、インストールスクリプトを実行してください：```bash bash -c "$(curl --silent https://raw.githubusercontent.com/thoughtworks/talisman/main/install.sh)"

または環境変数 `INSTALL_LOCATION` を設定してバイナリのカスタム場所を指定してください:```bash
INSTALL_LOCATION=/usr/local/bin bash -c "$(curl --silent https://raw.githubusercontent.com/thoughtworks/talisman/main/install.sh)"

または、環境変数 VERSION をリリースタグに設定して、特定のバージョンをインストールします::```bash VERSION=v1.36.0 bash -c "$(curl --silent https://raw.githubusercontent.com/thoughtworks/talisman/main/install.sh)"

または、Linuxではlinuxbrew、macOSではhomebrewを使用して、ターミナルで次のコマンドを実行してください：```bash
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)"

または

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

2. $PATHにTALISMAN_HOMEが設定されていない場合は、適切な場所を設定するよう求められます。マシン上でプロファイルソースを設定したオプション番号を選択してください。 パスファイルでsourceを実行するか、端末を再起動することを忘れないでください。 後で$PATHを設定する場合は、export TALISMAN_HOME=$HOME/.talisman/binをパスに追加してください。

3. Talismanがすべてのgitリポジトリをスキャンするベースディレクトリを選択し、gitフック（ステップ1で選択したpre-commitまたはpre-push）をシンボリックリンクとして設定します。 このスクリプトは既存のフックを上書きしません。既存のフックがある場合は、フックフレームワークを使ってtalismanを追加できます。

• インストールを実行する前に、ベースディレクトリのパスをSEARCH_ROOT環境変数に設定しておくと、インストール中に手動で入力する必要がなくなります。

プロジェクトの設定

フックフレームワークの使用

フックとしてtalismanをグローバルにインストールしても、既存のフックは上書きされません。インストールスクリプトが既存のフックを検出した場合、コンソール上でその旨が示されるだけです。複数のフックを実行するには、pre-commitやhuskyなどのフックフレームワークを使用することをお勧めします。これらの手順では、talismanの実行ファイルがシステムのパス上のどこかにインストールされていることを前提としています。

Pre-commit

Talismanと一緒に既存のフックを管理するには、pre-commitを使用します。.pre-commit-config.yaml内で、pre-commit-hooksを参照してください：```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](https://typicode.github.io/husky) はフックを管理するための npm モジュールです。
`package.json` 内の husky の pre-commit 設定に次の行を追加してください。```
talisman --githook pre-commit

talismanを直接呼び出す

talisman実行ファイルをインストールしたら、Gitリポジトリ用のスタンドアロンpre-commitフックを設定できます:```bash cd my-git-project echo "talisman -g pre-commit" >> .git/hooks/pre-commit chmod +x .git/hooks/pre-commit

# アップグレード
リリースv0.4.4以降、Talismanは<b>自動的に</b>フックが呼び出されたとき（プリコミット/プリプッシュ時、セットアップに応じて）バイナリを最新リリースに更新します。そのため、何もせずにリラックスして、追加の手間をかけずに最新のTalismanを使い続けられます。

以下の環境変数を設定できます：

1. TALISMAN_SKIP_UPGRADE: 自動アップグレードチェックをスキップしたい場合はtrueに設定します。デフォルトはfalseです。
2. TALISMAN_UPGRADE_CONNECT_TIMEOUT: アップグレードがキャンセルされるまでの最大接続タイムアウト（秒単位）。デフォルトは10秒です。

万が一、手動でアップグレードする必要がある場合、手順は次のとおりです：
<br>[推奨] Talismanバイナリとフックスクリプトを最新リリースに更新します：```bash
curl --silent  https://raw.githubusercontent.com/thoughtworks/talisman/main/global_install_scripts/update_talisman.bash > /tmp/update_talisman.bash && /bin/bash /tmp/update_talisman.bash

実行してTalismanバイナリのみを更新する：```bash curl --silent https://raw.githubusercontent.com/thoughtworks/talisman/main/global_install_scripts/update_talisman.bash > /tmp/update_talisman.bash && /bin/bash /tmp/update_talisman.bash talisman-binary

# 動作中のTalisman

インストールが成功した後、Talismanは（インストール時に選択したように）各コミットまたはプッシュの前に自動的に明白な秘密情報のチェックを実行します。セキュリティ侵害が検出された場合、talismanはエラーの詳細なレポートを表示します。```bash
$ git push
Talisman Report:
+-----------------+-------------------------------------------------------------------------------+
|     FILE        |                                    ERRORS                                     |
+-----------------+-------------------------------------------------------------------------------+
| danger.pem      | The file name "danger.pem"                                                    |
|                 | failed checks against the                                                     |
|                 | pattern ^.+\.pem$                                                             |
+-----------------+-------------------------------------------------------------------------------+
| danger.pem      | Expected file to not contain hex encoded texts such as:                       |
|                 | awsSecretKey=c64e8c79aacf5ddb02f1274db2d973f363f4f553ab1692d8d203b4cc09692f79 |
+-----------------+-------------------------------------------------------------------------------+

上記の例では、ファイル danger.pem が以下の理由によりセキュリティ侵害としてフラグが立てられています。

• ファイル名が事前設定されたパターンのいずれかに一致しています。
• ファイルには awsSecretKey が含まれており、Talisman によってスキャンされフラグが立てられています。

Talisman を pre-commit フックとしてインストールした場合、各コミット内の diff のみをスキャンします。つまり、変更されたファイルの部分についてのみエラーを報告します。

Talisman を pre-push フックとしてインストールした場合、変更が行われたファイル全体をスキャンします。上記の通り、Talisman は pre-commit フック として使用することをお勧めします。

検証

以下の検出器がチェンジセットに対して実行され、シークレット/機密情報を検出します。

• エンコードされた値 - Base64、16進数などでエンコードされたシークレットをスキャンします。
• ファイル内容 - 潜在的なシークレットやパスワードとなる可能性のある不審なコンテンツをファイル内でスキャンします。
• ファイルサイズ - キーやその他のシークレットを含む可能性のある大きなファイルをスキャンします。
• エントロピー - パスワードを含む可能性が高い高エントロピーのコンテンツをスキャンします。
• クレジットカード番号 - 潜在的なクレジットカード番号である可能性のあるコンテンツをスキャンします。
• ファイル名 - キーや資格情報などのシークレットを含む可能性を示すファイル名や拡張子をスキャンします。

ファイルの無視

本当にそのファイルをプッシュしたい場合は、プロジェクトルートの .talismanrc ファイルに設定することができます。失敗したファイルを無視するために必要な内容は、Talisman エラーレポートの直後に Talisman によってコンソールに表示されます。```bash If you are absolutely sure that you want to ignore the above files from talisman detectors, consider pasting the following format in .talismanrc file in the project root fileignoreconfig:

• filename: danger.pem checksum: cf97abd34cebe895417eb4d97fbd7374aa138dcb65b1fe7f6b6cc1238aaf4d48 ignore_detectors: []

`.talismanrc` ファイルにこれを入力すると、チェックサムが `checksum` フィールドに指定された値と一致する限り、Talisman は `danger.pem` ファイルを無視します。

### インタラクティブモード

**Windows 以外のユーザーのみ利用可能**

Talisman からエラーが発生するたびに `.talismanrc` に内容をコピーし続けるのが面倒な場合は、インタラクティブモードを有効にして、Talisman に無視するファイルの追加を促すことができます。
以下の簡単な手順に従ってください：
1. 環境変数が設定されている bash プロファイル（.bashrc、.bash_profile、.profile、またはその他の場所）を開きます。
2. `# >>> talisman >>>` の下に `TALISMAN_INTERACTIVE` 変数があることを確認します。
3. まだ true に設定されていない場合は、`export TALISMAN_INTERACTIVE=true` を追加します。
4. 保存してファイルを source するのを忘れないでください。

これで完了です！Talisman フックが pre-push/pre-commit 中にエラーを見つけるたびに、Talisman の指示に従ってください。
ファイルの内容を確認せずに無視しないように注意してください。秘密情報が漏洩していないことを確信する必要があります。

### 特定の検出器を無視する

以下は、`.talismanrc` ファイルに設定できるさまざまなフィールドの詳細な説明です。

* `filename` : このフィールドには、完全修飾ファイル名を指定する必要があります。
* `checksum` : このフィールドには、常に Talisman が上記のメッセージで指定した値を設定する必要があります。ファイルに新しい変更が加えられた場合、新しいチェックサムが生成され、Talisman は潜在的なセキュリティ脅威がないかファイルを再度スキャンします。
* `ignore_detectors` : このフィールドは、特定のファイルに対して特定の検出器を無効にします。
例えば、`init-env.sh` ファイル名が警告をトリガーする場合、ファイル内容など他の問題が発生しても警告を無効にすることができます。```yaml
fileignoreconfig:
- filename: init-env.sh
  checksum: cf97abd34cebe895417eb4d97fbd7374aa138dcb65b1fe7f6b6cc1238aaf4d48
  ignore_detectors: [filename, filesize]

注: ここでは init-env.sh に対して、filename 検出器と filesize 検出器の両方が無視されますが、 filecontent 検出器は init-env.sh に対して引き続き有効です。

現時点では、以下を無視できます

• filecontent
• filename
• filesize

特定のキーワードの無視

ファイルの中には、必ずしも秘密情報に関連しない key や pass などのキーワードが含まれている可能性があるため、これらのキーワードを無視して誤検出を減らしたい場合があります。 これは、ファイルレベルやリポジトリレベルで allowed_patterns フィールドを使用することで実現できます。```yaml fileignoreconfig:

• filename: test allowed_patterns: [key] allowed_patterns:
• keyword
• pass

前の例では、`key`は`test`ファイルで許可され、`keyword`と`pass`はリポジトリレベルで許可されています。

`allowed_patterns`フィールドはGolangの正規表現もサポートしています。以下はGolang正規表現が有用な簡単なコード例です：```sh
export AWS_ACCESS_KEY_ID = AKIAIO5FODNN7EXAMPLE
export AWS_ACCESS_KEY_ID=$(vault read -field=value path/to/aws-access-key-id)

デフォルトでは、Talismanは両方の行に対してアラートを発します。2行目では、Hashicorp VaultからAWS Access Key IDを抽出していますが、これはシークレットをコードに公開しません。このような使用法がコードで頻繁に見られる場合、Vaultを使用しているときにTalismanがアラートを発しないように設定したいかもしれません。これは以下のような設定で実現できます：```yaml allowed_patterns:

• export\ AWS[ \w]KEY[ \w]=.vault\ read.

### 同じ種類の複数ファイルを無視する（ワイルドカード使用）

特定の種類のファイルは常に安全であると分かっているため、Talismanがそれらをスキャンしないように無視することができます。

手順:

1. 無視したいファイルのワイルドカードパターンを指定します。例: `*.lock`
2. [チェックサム計算機](#checksum-calculator)を使用して、そのパターンを入力し、集約チェックサムを取得します。例: `talisman --checksum="*.lock"`
3. コンソールに出力されたfileconfigブロックをコピーして、.talismanrcファイルに追加します。

いずれかのファイルが変更された場合、新しいチェックサムを再計算して.talismanrcファイル内の値を置き換えない限り、talismanは再度ファイルをスキャンします。

### 言語スコープを指定してファイルを無視する

プロジェクトの言語スコープをtalismanrcで指定することで、ファイルを無視することができます。```yaml
scopeconfig:
  - scope: go
  - scope: node
  - scope: images
  - scope: php
  - scope: python

Talismanは指定されたスコープに基づいて特定のファイルを無視するように設定されています。例えば、scopeconfigでnodeスコープを指定すると、yarn.lockやpackage-lock.jsonなどのファイルをtalismanがスキャンしなくなります。

複数のスコープを指定できます。

現在、.talismanrcはgo、node、php、imagesのスコープのみをサポートしています。他のスコープは後日追加される予定です。

カスタム検索パターン

現在のリポジトリで検索するためのカスタムregexパターンを指定できます。```yaml custom_patterns:

• pattern1
• pattern2

<br/><i>
**注記**: `.talismanignore` の使用は非推奨となりました。代わりにファイル `.talismanrc` が以下の理由で使用されます。

* `.talismanrc` はより読みやすい yaml 形式です
* また、機密性の高い値が含まれる可能性のあるファイルの変更をすべてレビューするという、より安全なプラクティスをもたらします
* 新しい形式は、新しい使用可能な機能を導入するための拡張性ももたらします。今後のアップデートにご注目ください </i>

## 重大度しきい値の設定

各検証には次のような重要度が関連付けられています。
1. Low
2. Medium
3. High

`.talismanrc` でしきい値を指定できます。```yaml
threshold: medium

これは、中程度以上の深刻度の問題をすべて報告します（しきい値未満の潜在的なリスクは警告に報告されます）

1. すべてのリスクとその深刻度レベルの一覧は、この設定ファイルにあります。
2. デフォルトでは、しきい値は低（low）に設定されています。
3. 追加するカスタム検索パターンは、すべて高（high）の深刻度と見なされます。

カスタム深刻度の設定

.talismanrcファイル内で、Talismanが提供する検出器のセキュリティレベルをカスタマイズできます。```yaml custom_severities:

• detector: Base64Content severity: medium
• detector: HexContent severity: low

カスタム重大度と重大度しきい値を使用することで、Talismanはコンテキストに基づいて重要なものだけをアラートするように設定できます。これは誤検出の数を減らすのに役立ちます。

## Talisman as a CLI utility

コマンドラインで `talisman` を実行すると、渡すことができるすべてのパラメータオプションを表示できます```
  -c, --checksum string          checksum calculator calculates checksum and suggests .talismanrc format
  -d, --debug                    enable debug mode (warning: very verbose)
  -g, --githook string           either pre-push or pre-commit (default "pre-push")
      --ignoreHistory            scanner scans all files on current head, will not scan through git commit history
  -i, --interactive              interactively update talismanrc (only makes sense with -g/--githook)
  -p, --pattern string           pattern (glob-like) of files to scan (ignores githooks)
  -r, --reportdirectory string   directory where the scan reports will be stored
  -s, --scan                     scanner scans the git commit history for potential secrets
  -w, --scanWithHtml             generate html report (**Make sure you have installed talisman_html_report to use this, as mentioned in Readme**)
  -v, --version                  show current version of talisman

インタラクティブモード

talismanフックによって頻繁にフラグが立てられるファイルが多数あり、それらがチェックインしても問題ないと分かっている場合、この機能を使用してtalismanによる処理を容易にすることができます。インタラクティブモードを使用すると、Talismanはコマンドプロンプトから直接、無視したいファイルを.talismanrcに追加するように促します。 この機能を有効にするには、bashファイル内でTALISMAN_INTERACTIVE変数をtrueに設定する必要があります。

以下の2つの方法のいずれかで、インタラクティブモードでtalismanを起動できます。

1. bashファイルを開き、次の行を追加します。export TALISMAN_INTERACTIVE=true Don't forget to source the bash file for the variable to take effect!

2. Alternatively, you can also invoke the interactive mode by using the CLI utility (for using pre-commit hook) talisman -i -g pre-commit 注: IDEのバージョン管理機能をGit操作に使用している場合、この機能は動作しません。提案されたファイル名とチェックサムを手動で.talismanrcファイルに入力することは可能です。

Git履歴スキャナー

CLIからTalismanを実行し、CI/CDパイプラインに追加して、リポジトリのGit履歴をスキャンし、機密コンテンツを検出できるようになりました。 これには.talismanrcファイルにリストされているファイルのスキャンも含まれます。

手順:

1. スキャンするGitディレクトリパスに移動 cd <スキャンするディレクトリ>
2. スキャンコマンドを実行 talisman --scan
   • このコマンドを実行すると、現在のディレクトリのルートにtalisman_reportsという名前のフォルダが作成され、レポートファイルが保存されます。
   • レポートの場所は、追加パラメータとして--reportdirectoryまたは--rdで指定することもできます。
     例: talisman --scan --reportdirectory=/Users/username/Desktop

上記で指定した他のオプションもスキャンに使用できます。

Talismanは現在、スキャン時のファイルの無視をサポートしていません。

チェックサム計算機

Talismanチェックサム計算機は、Talisman検出器から特定のファイル形式を無視するために.talismanrcファイルに直接コピー＆ペーストできるyaml形式を出力します。

チェックサムを実行するには、リポジトリのルートに"cd"で移動し、以下のコマンドを実行してください。

例: talisman --checksum="*.pem *.txt"

1. このコマンドは、リポジトリ内のすべての.pemファイルを検索し、それらすべてのファイルの集合チェックサムを計算し、.talismanrc用のyaml形式を出力します。同様に.txtファイルも処理します。
2. 複数のファイル名/パターンはスペース区切りで指定できます。

出力例:

.talismanrc format for given file names / patterns
fileignoreconfig:
- filename: '*.pem'
  checksum: f731b26be086fd2647c40801630e2219ef207cb1aacc02f9bf0559a75c0855a4
  ignore_detectors: []
- filename: '*.txt'
  checksum: d9e9e94868d7de5b2a0706b8d38d0f79730839e0eb4de4e9a2a5a014c7c43f35
  ignore_detectors: []

注: チェックサム計算機は、ファイルの集合チェックサムを計算する際にステージングされたファイルを考慮します。

Talisman HTMLレポート

Powered by

Talisman CLIツールtalismanには、詳細で共有可能なHTMLレポートを提供する機能もあります。Talismanをインストールしたら、talisman-html-reportの手順に従って、.talismanフォルダにレポートパッケージをインストールしてください。HTMLレポートを生成するには、以下を実行します:

• talisman --scanWithHtml

これによりリポジトリがスキャンされ、スキャンしたリポジトリの下にtalisman_html_reportフォルダが作成されます。このリポジトリ内でHTTPサーバーを起動してレポートにアクセスする必要があります。HTTPサーバーを起動する推奨方法は以下のとおりです:

• python -m SimpleHTTPServer <ポート> (例: 8000)

次のURLにアクセスしてレポートを表示できます:

http://localhost:8000

サンプルスクリーンショット

• Welcome

• Summary

• 詳細レポート

• エラーレポート

注: CIやその他のホスト環境でTalismanを実行する場合は、サーバーを起動する必要はありません。

アンインストール

アンインストールの手順は、Talismanのインストール方法によって異なります。 グローバルフックテンプレートとしてインストールしたか、単一のリポジトリにインストールしたかのいずれかです。

インストール時に選択したオプションに基づいて、以下の手順に従ってください。

グローバルフックテンプレートからのアンインストール

以下のコマンドをターミナルで実行して、マシンからTalismanをグローバルにアンインストールします。

pre-commitフックの場合:``` bash -c "$(curl --silent https://raw.githubusercontent.com/thoughtworks/talisman/main/global_install_scripts/uninstall.bash)"

pre-push フックの場合:```
bash -c "$(curl --silent https://raw.githubusercontent.com/thoughtworks/talisman/main/global_install_scripts/uninstall.bash)" -- pre-push

これにより、以下の操作が行われます。

1. すべてのリポジトリのベースディレクトリを尋ね、その中のすべてのgitリポジトリを見つけて、talismanフックを削除します。
2. .git-templateからtalismanフックを削除します。
3. 中央インストール場所（$HOME/.talisman/bin）からtalismanを削除します。
   

TALISMAN_HOMEを環境変数から手動で削除する必要があります。

単一リポジトリからのアンインストール

Talismanのインストール時、選択に応じてリポジトリにpre-commitまたはpre-pushフックが作成されているはずです。

リポジトリの.git/hooksフォルダからTalismanのpre-commitまたはpre-pushフックを削除することで、手動でフックを削除できます。

Talismanへの貢献

Talismanに貢献するには、貢献ガイドをご覧ください。