github.com/pkumar631/talisman@v0.3.2/README.md (about) 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 7 keys, authorization tokens, private keys etc. 8 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. 14 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! 20 21 #### Running Talisman 22 23 Talisman can either be installed into a single git repo, or as a 24 [git hook template](https://git-scm.com/docs/git-init#_template_directory). 25 26 We recommend installing it as a git hook template, as that will cause 27 Talisman to be present in any new repository that you 'init' or 28 'clone'. 29 30 You could download the 31 [Talisman binary](https://github.com/thoughtworks/talisman/releases) 32 manually and copy it into your project/template `hooks` directory -- 33 or you can use our `install.sh` script. 34 35 ```bash 36 curl https://thoughtworks.github.io/talisman/install.sh > ~/install-talisman.sh 37 chmod +x ~/install-talisman.sh 38 ``` 39 40 If you run this script from inside a git repo, it will add Talisman to 41 that repo. Otherwise, it will prompt you to install as a git hook 42 template. 43 44 ```bash 45 # Install to a single project 46 cd my-git-project 47 ~/install-talisman.sh 48 ``` 49 50 ```bash 51 # Install as a git hook template 52 cd ~ 53 ~/install-talisman.sh 54 ``` 55 56 From now on Talisman will run checks for obvious secrets automatically before each push: 57 58 ```bash 59 $ git push 60 The following errors were detected in danger.pem 61 The file name "danger.pem" failed checks against the pattern ^.+\.pem$ 62 63 error: failed to push some refs to 'git@github.com:jacksingleton/talisman-demo.git' 64 ``` 65 66 #### Ignoring Files 67 68 If you're *really* sure you want to push that file, you can add it to 69 a `.talismanignore` file in the project root: 70 71 ```bash 72 echo 'danger.pem' >> .talismanignore 73 ``` 74 75 Note that we can ignore files in a few different ways: 76 77 * If the pattern ends in a path separator, then all files inside a 78 directory with that name are matched. However, files with that name 79 itself will not be matched. 80 81 * If a pattern contains the path separator in any other location, the 82 match works according to the pattern logic of the default golang 83 glob mechanism. 84 85 * If there is no path separator anywhere in the pattern, the pattern 86 is matched against the base name of the file. Thus, the pattern will 87 match files with that name anywhere in the repository. 88 89 #### Usage with the [pre-commit](https://pre-commit.com) git hooks framework 90 91 Add this to your `.pre-commit-config.yaml` (be sure to update `rev` to point to 92 a real git revision!) 93 94 ```yaml 95 - repo: https://github.com/thoughtworks/talisman 96 rev: '' # Update me! 97 hooks: 98 # either `commit` or `push` support 99 - id: talisman-commit 100 # - id: talisman-push 101 ``` 102 103 #### Developing locally 104 105 To contribute to Talisman, you need a working golang development 106 environment. Check [this link](https://golang.org/doc/install) to help 107 you get started with that. 108 109 Once that is done, you will need to have the godep dependency manager 110 installed. To install godep, you will need to fetch it from Github. 111 112 ```` go get github.com/tools/godep ```` 113 114 Once you have godep installed, clone the talisman repository. In your 115 working copy, fetch the dependencies by having godep fetch them for 116 you. 117 118 ```` godep restore ```` 119 120 To run tests ```` godep go test ./... ```` 121 122 To build Talisman, we can use [gox](https://github.com/mitchellh/gox): 123 124 ```` gox -osarch="darwin/amd64 linux/386 linux/amd64" ```` 125 126 #### Contributing to Talisman 127 128 ##### Working off a fork 129 130 Keep in mind that Go namespaces imports by git repo, so if you fork Talisman to work on a PR you will likely have to change imports in a few places -- for example, [`talisman.go:11`](https://github.com/thoughtworks/talisman/blob/d4b1b1d11137dbb173bf681a03f16183a9d82255/talisman.go#L11). 131 132 ##### Releasing 133 134 * Follow the instructions at the end of 'Developing locally' to build the binaries 135 * Bump the [version in install.sh](https://github.com/thoughtworks/talisman/blob/d4b1b1d11137dbb173bf681a03f16183a9d82255/install.sh#L10) according to [semver](https://semver.org/) conventions 136 * Update the [expected hashes in install.sh](https://github.com/thoughtworks/talisman/blob/d4b1b1d11137dbb173bf681a03f16183a9d82255/install.sh#L16-L18) to match the new binaries you just created (`shasum -b -a256 ...`) 137 * Make release commit and tag with the new version prefixed by `v` (like `git tag v0.3.0`) 138 * Push your release commit and tag: `git push && git push --tags` 139 * [Create a new release in github](https://github.com/thoughtworks/talisman/releases/new), filling in the new commit tag you just created 140 * Update the install script hosted on github pages: `git checkout gh-pages`, `git checkout master -- install.sh`, `git commit -m ...` 141 142 The latest version will now be accessible to anyone who builds their own binaries, downloads binaries directly from github releases, or uses the install script from the website.