Skip to content

Commit db7e5fe

Browse files
rrajagoprrajagop
authored
Merge pull request #77 from harinee/master
Updated Readme to re-structure and add more details
2 parents 6c71cd3 + cb8b768 commit db7e5fe

File tree

2 files changed

+196
-139
lines changed

2 files changed

+196
-139
lines changed

‎README.md

Lines changed: 196 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,154 @@
1-
# Talisman
2-
3-
Talisman is a tool to validate code changes that are to be pushed out
4-
of a local Git repository on a developer's workstation. By hooking
5-
into the pre-push hook provided by Git, it validates the outgoing
6-
changeset for things that look suspicious - such as potential SSH
1+
<div style="display: flex; justify-content: center;">
2+
<h1 align="center">
3+
<img class=logo align=bottom width="5%" height="5%" src="https://thoughtworks.github.io/talisman/logo.svg" />
4+
Talisman</h1>
5+
</div>
6+
<p align="center">A tool to detect and prevent secrets from getting checked in</p>
7+
8+
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Go Report Card](https://goreportcard.com/badge/thoughtworks/talisman)](https://goreportcard.com/report/thoughtworks/talisman) [![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/thoughtworks/talisman/issues)
9+
10+
11+
## Table of Contents
12+
- [What is Talisman?](#what-is-talisman)
13+
- [Installation](#installation)
14+
- [As a global hook template (Recommended)](#installation-as-a-global-hook-template)
15+
- [To a single repository](#installation-to-a-single-project)
16+
- [As a CLI to find file types](#installation-as-a-cli)
17+
- [Talisman in action](#talisman-in-action)
18+
- [Validations](#validations)
19+
- [Ignoring files](#ignoring-files)
20+
- [Uninstallation](#uninstallation)
21+
- [From a global hook template](#uninstallation-from-a-global-hook-template)
22+
- [From a single repository](#uninstallation-from-a-single-repository)
23+
- [Contributing to Talisman](#contributing-to-talisman)
24+
- [Developing locally](#developing-locally)
25+
- [Releasing](#releasing)
26+
27+
# What is Talisman?
28+
Talisman is a tool that installs a hook to your repository to ensure that potential secrets or sensitive information do not leave the developer's workstation.
29+
30+
It validates the outgoing changeset for things that look suspicious - such as potential SSH
731
keys, authorization tokens, private keys etc.
832

9-
The aim is for this tool to do this through a variety of means
10-
including file names and file content. We hope to have it be an
11-
effective check to prevent potentially harmful security mistakes from
12-
happening due to secrets which get accidentally checked in to a
13-
repository.
1433

15-
The implementation as it stands is very bare bones and only has the
16-
skeleton structure required to add the full range of functionality we
17-
wish to incorporate. However, we encourage folks that want to
18-
contribute to have a look around and contribute ideas/suggestions or
19-
ideally, code that implements your ideas and suggestions!
34+
# Installation
35+
36+
Talisman supports MAC OSX, Linux and Windows.
2037

21-
## Installation
38+
Talisman can be installed and used in one of three different ways:
2239

23-
Talisman can either be installed and used in three different ways
24-
1. As a git hook into a single git repository
25-
2. As a git hook as a global [git hook template](https://git-scm.com/docs/git-init#_template_directory)
40+
1. As a git hook as a global [git hook template](https://git-scm.com/docs/git-init#_template_directory)
41+
2. As a git hook into a single git repository
2642
3. As a CLI with the `--pattern` argument to find files
2743

28-
As a git hook, Talisman can be set up a as a pre-push or pre-commit hook on git repositories.
44+
Talisman can be set up as either a pre-commit or pre-push hook on the git repositories.
45+
46+
Find the instructions below.
47+
48+
## [Recommended approach]
49+
## Installation as a global hook template
50+
51+
We recommend installing Talisman as a git hook template, as that will cause
52+
Talisman to be present, not only in your existing git repositories, but also in any new repository that you 'init' or
53+
'clone'.
54+
55+
1. Run the following command on your terminal, to download and install the binary at $HOME/.talisman/bin
56+
57+
As a pre-commit hook:
58+
59+
```
60+
curl --silent https://raw.githubusercontent.com/thoughtworks/talisman/master/global_install_scripts/install.bash > /tmp/install_talisman.bash && /bin/bash /tmp/install_talisman.bash
61+
```
62+
63+
OR
64+
65+
As a pre-push hook:
66+
67+
```
68+
curl --silent https://raw.githubusercontent.com/thoughtworks/talisman/master/global_install_scripts/install.bash > /tmp/install_talisman.bash && /bin/bash /tmp/install_talisman.bash pre-push
69+
```
70+
71+
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.
72+
73+
74+
Remember to execute *source* on the path file or restart your terminal.
75+
If you choose to set the `$PATH` later, please export TALISMAN\_HOME=$HOME/.talisman/bin to the path.
2976

30-
### Installation to a single project
77+
78+
3. Choose a base directory where Talisman should scan for all git repositories, and setup a git hook (pre-commit or pre-push, as chosen in step 1) as a symlink.
79+
This script will not clobber pre-existing hooks. If you have existing hooks, [look for ways to chain Talisman into them.] (#handling-existing-hooks)
80+
81+
82+
### Handling existing hooks
83+
Installation of Talisman globally does not clobber pre-existing hooks on repositories. <br>
84+
If the installation script finds any existing hooks, it will only indicate so on the console. <br>
85+
To achieve running multiple hooks we suggest (but not limited to) the following two tools
86+
87+
#### 1. Pre-commit (Linux/Unix)
88+
Use [pre-commit](https://pre-commit.com) tool to manage all the existing hooks along with Talisman.
89+
In the suggestion, it will prompt the following code to be included in .pre-commit-config.yaml
90+
91+
```
92+
- repo: local
93+
hooks:
94+
- id: talisman-precommit
95+
name: talisman
96+
entry: bash -c 'if [ -n "${TALISMAN_HOME:-}" ]; then ${TALISMAN_HOME}/talisman_hook_script pre-commit; else echo "TALISMAN does not exist. Consider installing from https://github.com/thoughtworks/talisman . If you already have talisman installed, please ensure TALISMAN_HOME variable is set to where talisman_hook_script resides, for example, TALISMAN_HOME=${HOME}/.talisman/bin"; fi'
97+
language: system
98+
pass_filenames: false
99+
types: [text]
100+
verbose: true
101+
```
102+
103+
#### 2. Husky (Linux/Unix/Windows)
104+
[husky](https://github.com/typicode/husky/blob/master/DOCS.md) is an npm module for managing git hooks.
105+
In order to use husky, make sure you have already set TALISMAN_HOME to `$PATH`.
106+
107+
+ **Existing Users**
108+
109+
If you already are using husky, add the following lines to husky pre-commit in package.json
110+
111+
###### Windows
112+
113+
```
114+
"bash -c '\"%TALISMAN_HOME%\\${TALISMAN_BINARY_NAME}\" -githook pre-commit'"
115+
```
116+
117+
###### Linux/Unix
118+
119+
```
120+
$TALISMAN_HOME/talisman_hook_script pre-commit
121+
```
122+
+ **New Users**
123+
124+
If you want to use husky with multiple hooks along with talisman, add the following snippet to you package json.
125+
###### Windows
126+
127+
```
128+
{
129+
"husky": {
130+
"hooks": {
131+
"pre-commit": "bash -c '\"%TALISMAN_HOME%\\${TALISMAN_BINARY_NAME}\" -githook pre-commit'" && "other-scripts"
132+
}
133+
}
134+
}
135+
```
136+
137+
###### Linux/Unix
138+
139+
```
140+
{
141+
"husky": {
142+
"hooks": {
143+
"pre-commit": "$TALISMAN_HOME/talisman_hook_script pre-commit" && "other-scripts"
144+
}
145+
}
146+
}
147+
```
148+
149+
150+
151+
## Installation to a single project
31152

32153
```bash
33154
# Download the talisman binary
@@ -41,26 +162,8 @@ cd my-git-project
41162
~/install-talisman.sh
42163
```
43164

44-
### Installation as a CLI
45-
46-
1. Download the Talisman binary from the [Releases page](https://github.com/thoughtworks/talisman/releases) corresponding to your system type
47-
2. Place the binary somewhere (either directly in your repository, or by putting it somewhere in your system and adding it to your `$PATH`)
48-
3. Run talisman with the `--pattern` argument (matches glob-like patterns, [see more](https://github.com/bmatcuk/doublestar#patterns))
49-
```bash
50-
# finds all .go and .md files in the current directory (recursively)
51-
talisman --pattern="./**/*.{go,md}"
52-
```
53-
54-
### Installation as a global hook template (recommended)
55-
We recommend installing it as a git hook template, as that will cause
56-
Talisman to be present, not only in your existing git repositories, but also in any new repository that you 'init' or
57-
'clone'.
58-
59-
Use the [Global scripts Readme](global_install_scripts/Readme.md) to guide you through the installation process.
60-
61-
### Installation
62-
63-
#### Usage with the [pre-commit](https://pre-commit.com) git hooks framework
165+
### Handling existing hooks
166+
Talisman will need to be chained with any existing git hooks.You can use [pre-commit](https://pre-commit.com) git hooks framework to handle this.
64167

65168
Add this to your `.pre-commit-config.yaml` (be sure to update `rev` to point to
66169
a real git revision!)
@@ -74,9 +177,19 @@ a real git revision!)
74177
# - id: talisman-push
75178
```
76179

77-
## Talisman in action
180+
## Installation as a CLI
181+
1. Download the Talisman binary from the [Releases page](https://github.com/thoughtworks/talisman/releases) corresponding to your system type
182+
2. Place the binary somewhere (either directly in your repository, or by putting it somewhere in your system and adding it to your `$PATH`)
183+
3. Run talisman with the `--pattern` argument (matches glob-like patterns, [see more](https://github.com/bmatcuk/doublestar#patterns))
78184

79-
After the installation is successful, Talisman will run checks for obvious secrets automatically before each push:
185+
```bash
186+
# finds all .go and .md files in the current directory (recursively)
187+
talisman --pattern="./**/*.{go,md}"
188+
```
189+
190+
# Talisman in action
191+
192+
After the installation is successful, Talisman will run checks for obvious secrets automatically before each commit or push (as chosen during installation):
80193

81194
```bash
82195
$ git push
@@ -86,7 +199,18 @@ The following errors were detected in danger.pem
86199
error: failed to push some refs to 'git@github.com:jacksingleton/talisman-demo.git'
87200
```
88201

89-
### Ignoring Files
202+
## Validations
203+
The following detectors execute against the changesets to detect secrets/sensitive information:
204+
205+
* **Encoded values** - scans for encoded secrets in Base64, hex etc.
206+
* **File content** - scans for suspicious content in file that could be potential secrets or passwords
207+
* **File size** - scans for large files that may potentially contain keys or other secrets
208+
* **Entropy** - scans for content with high entropy that are likely to contain passwords
209+
* **Credit card numbers** - scans for content that could be potential credit card numbers
210+
* **File names** - scans for file names and extensions that could indicate them potentially containing secrets, such as keys, credentials etc.
211+
212+
213+
## Ignoring Files
90214

91215
If you're *really* sure you want to push that file, you can add it to
92216
a `.talismanignore` file in the project root:
@@ -124,6 +248,32 @@ At the moment, you can ignore
124248
* `filename`
125249
* `filesize`
126250

251+
# Uninstallation
252+
The uninstallation process depends on how you had installed Talisman.
253+
You could have chosen to install as a global hook template or at a single repository.
254+
255+
Please follow the steps below based on which option you had chosen at installation.
256+
257+
## Uninstallation from a global hook template
258+
To uninstall talisman globally from your machine, run:
259+
260+
```
261+
curl --silent https://raw.githubusercontent.com/thoughtworks/talisman/master/global_install_scripts/uninstall.bash > /tmp/uninstall_talisman.bash && /bin/bash /tmp/uninstall_talisman.bash
262+
```
263+
This will
264+
265+
1. ask you for the base dir of all your repos, find all git repos inside it and remove talisman hooks
266+
2. remove talisman hook from .git-template
267+
3. remove talisman from the central install location ($HOME/.talisman/bin).<br>
268+
269+
<i>You will have to manually remove TALISMAN_HOME from your environment variables</i>
270+
271+
## Uninstallation from a single repository
272+
When you installed Talisman, it must have created a pre-commit or pre-push hook (as selected) in your repository during installation.
273+
274+
You can remove the hook manually by deleting the Talisman pre-commit or pre-push hook from .git/hooks folder in repository.
275+
276+
# Contributing to Talisman
127277

128278
## Developing locally
129279

@@ -147,9 +297,8 @@ To build Talisman, we can use [gox](https://github.com/mitchellh/gox):
147297

148298
Convenince scripts ```./build``` and ```./clean``` perform build and clean-up as mentioned above.
149299

150-
#### Contributing to Talisman
151300

152-
##### Releasing
301+
## Releasing
153302

154303
* Follow the instructions at the end of 'Developing locally' to build the binaries
155304
* Bump the [version in install.sh](https://github.com/thoughtworks/talisman/blob/d4b1b1d11137dbb173bf681a03f16183a9d82255/install.sh#L10) according to [semver](https://semver.org/) conventions

‎global_install_scripts/Readme.md

Lines changed: 0 additions & 92 deletions
This file was deleted.

0 commit comments

Comments
 (0)