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.