@ministryofjustice/hmpps-precommit-hooks 0.0.1-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Change log
+
+
+## 0.0.1-alpha.1
+
+Pre-releases which should not be used in projects.

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Crown Copyright (Ministry of Justice)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# @ministryofjustice/precommit-hooks
+
+This package aims to automatically install and configure husky with gitleaks to help catch potential secrets before committing them to github.
+
+## Status
+
+This library is in alpha. Teams are free to use this library but further breaking changes may occur.
+
+## Migrating existing projects
+
+#### Automatically installing the library
+
+The package will self install and initialised by running via npx:
+`npx @ministryofjustice/precommit-hooks`
+
+Note: The project needs to be initialised before use - solely adding the library will make no difference.
+Once the project has been initialised, other developers should be able to develop against it without further configuration.
+
+### How this works
+
+Initialising will add new precommit scripts and a new prepare script in `package.json`:
+
+```json
+"scripts": {
+     //...
+    "prepare": "hmpps-precommit-hooks",
+    "precommit:secrets": "gitleaks git --pre-commit --redact --staged --verbose",
+    "precommit:lint": "node_modules/.bin/lint-staged",
+    "precommit:verify": "npm run typecheck && npm test"
+}
+```
+
+It will also configure a husky precommit hook using these scripts:
+
+```sh
+#!/bin/bash
+NODE_ENV=dev \
+npm run precommit:secrets \
+&& npm run precommit:lint \
+&& npm run precommit:verify
+```
+
+The prepare script will trigger on any install and ensure that `gitleaks` is installed and `husky` is initiated.
+
+Note: `gitleaks` is installed by `brew`, if `brew` is not available then `prepare` will currently fail loudly and display a message.
+
+### Dealing with false positives
+
+When a secret is detected, gitleaks will create a fingerprint. If the secret is a false positive then this can be added to the `./gitleaks/.gitleaksignore` to exclude from future scans.
+
+Alternatively you can add a gitleaks:allow comment to a line to ignore a secret on it. Eg:
+
+```
+my_secret = 'some-secret'  #gitleaks:allow
+```
+
+### Adding custom rules
+
+HMPPS wide rules can be added to `.config.toml` in this project so that it can be picked up by teams when they upgrade to the next released version of this library.
+
+Repo specific rules can be added by teams in `.gitleaks/config.toml` in their individual repos.
+
+See the gitleaks documentation for how to create rules and [examples](https://github.com/gitleaks/gitleaks/blob/master/config/gitleaks.toml) or use the [online rule wizard](https://gitleaks.io/playground).
+
+### Testing that hooks are configured correctly
+
+Secret protection can be tested using the following command:
+
+```bash
+npx -p @ministryofjustice/precommit-hooks -c test-secret-protection
+```
+
+This should fail similarly to:
+
+```bash
+> npx -p @ministryofjustice/precommit-hooks -c test-secret-protection
+Creating test file containing dummy AWS_KEY=AKIA<SOME-VALUE>ASD
+Attempting to commit file containing secret
+
+> some-project@0.0.1 precommit:secrets
+> gitleaks git --pre-commit --redact --staged --verbose
+
+
+    ○
+    │╲
+    │ ○
+    ○ ░
+    ░    gitleaks
+
+Finding:     fake_aws_key=REDACTED
+Secret:      REDACTED
+RuleID:      aws-access-token
+Entropy:     3.546439
+File:        demo-password.txt
+Line:        1
+Fingerprint: demo-password.txt:aws-access-token:1
+
+12:49PM INF 1 commits scanned.
+12:49PM INF scanned ~34 bytes (34 bytes) in 20.7ms
+12:49PM WRN leaks found: 1
+```
+
+(This will create a `./demo-password.txt` file that will need to be deleted separately)

package/bin/init.sh

@@ -0,0 +1,80 @@
+#!/bin/bash
+#
+# Used to install husky with gitleaks
+# 
+
+set -euo pipefail
+
+startStage() {
+  printf "\x1b[1;97m%s\x1b[0m" "$1"
+}
+
+endStage() {
+  printf "\x1b[1;97m%s\x1b[0m\n" "$1"
+}
+
+printError() {
+  printf "\x1b[1;31m%s\x1b[0m\n" "$1"
+}
+
+endStage "Setting up precommit hooks" 
+endStage "Checking prerequisites..." 
+
+if ! [ -f ./package.json ]; then
+  printError "Not a node project: $(pwd)! exiting!"
+  exit 1
+fi
+
+startStage "  * Setting prepare script"
+npm pkg set --silent scripts.prepare="hmpps-precommit-hooks" 
+endStage "  ✅"
+
+if npm list husky > /dev/null 2>&1; then
+  startStage "  * Uninstalling husky"
+  npm uninstall --silent husky
+  endStage " ✅"
+fi
+
+if ! npm list @ministryofjustice/precommit-hooks > /dev/null 2>&1; then
+  startStage "  * Installing @ministryofjustice/precommit-hooks"
+  npm install --silent --save-dev @ministryofjustice/precommit-hooks
+  endStage " ✅"
+else
+  endStage "  * @ministryofjustice/precommit-hooks already installed ✅"
+  # Run npm install to trigger prepare script
+  npm --silent  install
+fi
+
+endStage "Installing precommit hooks..."
+
+startStage "  * Adding npm scripts"
+npm pkg --silent set scripts.precommit:secrets="gitleaks git --pre-commit --redact --staged --verbose --config .gitleaks/config.toml" 
+npm pkg --silent set scripts.precommit:lint="node_modules/.bin/lint-staged"
+npm pkg --silent set scripts.precommit:verify="npm run typecheck && npm test"
+endStage " ✅"
+
+startStage "  * Setting precommit hook"
+mkdir -p .husky
+printf "%s\n" \
+     "#!/bin/bash" \
+     "NODE_ENV=dev \\" \
+     "npm run precommit:secrets \\" \
+     "&& npm run precommit:lint \\" \
+     "&& npm run precommit:verify" \
+       > .husky/pre-commit
+endStage " ✅"
+
+startStage "  * Creating .gitleaksignore "
+mkdir -p .gitleaks
+echo "# The Fingerprint of false positive alerts can be added here to be excluded from future scans." >  .gitleaks/.gitleaksignore
+endStage " ✅"
+
+startStage "  * Creating project gitleaks config"
+printf "%s\n" \
+     "title = \"HMPPS Gitleaks configuration\"" \
+     "[extend]" \
+     "path = \"./node_modules/@ministryofjustice/precommit-hooks/config.toml\"" \
+       > .gitleaks/config.toml
+endStage " ✅"
+
+endStage "FIN!"

package/bin/prepare.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+#
+# This runs as part of any `npm install` via `prepare`
+# 
+
+set -euo pipefail
+
+startStage() {
+  printf "\x1b[1;97m%s\x1b[0m" "$1"
+}
+
+endStage() {
+  printf "\x1b[1;97m%s\x1b[0m\n" "$1"
+}
+
+printError() {
+  printf "\x1b[1;31m%s\x1b[0m\n" "$1"
+}
+
+# Initialise husky
+node_modules/.bin/husky
+
+# Check brew exists
+if ! command -v brew &> /dev/null; then
+  printError "Brew is not installed, WARNING: no precommit hook protection. exiting..."
+  exit 0
+fi
+
+# Initialise gitleaks
+if ! command -v gitleaks &> /dev/null; then
+  startStage "Installing gitleaks"
+  brew install gitleaks
+  endStage " ✅ "
+fi
+

package/bin/test.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+
+# Test that secret protection is set up correctly. 
+# This will create a separate file ./demo-password.txt which will need to be deleted separately. 
+
+RANDOM_NUMBER="$(LC_ALL=C tr -cd '[:digit:]' < /dev/urandom | fold -w 13 | head -n 1)"
+AWS_KEY="AKIA${RANDOM_NUMBER}ASD"
+
+echo "Creating test file containing dummy AWS_KEY=${AWS_KEY}"
+echo "fake_aws_key=${AWS_KEY}" > ./demo-password.txt
+
+echo "Attempting to commit file containing secret"
+git add ./demo-password.txt && git commit -m "This should fail due to detecting dummy AWS creds"

package/config.toml

@@ -0,0 +1,11 @@
+title = "HMPPS Gitleaks configuration"
+
+[extend]
+useDefault = true
+
+[[rules]]
+id = "token"
+description = "Possible token detected"
+regex = '''(?i)\b(.{55,65})(?:[\x60'"\s;]|\\[nr]|$)'''
+secretGroup = 1
+entropy = 5.1

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@ministryofjustice/hmpps-precommit-hooks",
+  "version": "0.0.1-alpha.1",
+  "description": "Precommit hooks for HMPPS typescript projects",
+  "keywords": [
+    "precommit"
+  ],
+  "author": "hmpps-developers",
+  "license": "MIT",
+  "homepage": "https://github.com/ministryofjustice/hmpps-typescript-lib/tree/main/packages/precommit-hooks#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ministryofjustice/hmpps-typescript-lib.git"
+  },
+  "bin": {
+    "@ministryofjustice/precommit-hooks": "./bin/init.sh",
+    "hmpps-precommit-hooks": "./bin/prepare.sh",
+    "test-secret-protection": "./bin/test.sh"
+  },
+  "files": [
+    "*.md",
+    "bin/*.sh",
+    "config.toml"
+  ],
+  "engines": {
+    "node": "20 || 22"
+  },
+  "dependencies": {
+    "husky": "^9.1.7"
+  }
+}