Skip to content
secret-scan
Menu

Get started

Get started

There is no hosted service and no account to sign up for. You install the package, run your scanner and gate on its filtered output, on your machine or in CI.

Read the install guideHow it works
  1. Step 1

    Get read access

    @catesworks/secret-scan is a restricted package on GitHub Packages. You need a GitHub token with read:packages on it. Without access, ask us through the contact form.

  2. Step 2

    Install into a scratch directory

    Install the package outside the repository you scan, so an install inside it cannot resolve to an ancestor’s node_modules.

  3. Step 3

    Scan and filter

    From the repository root: generate the config, run gitleaks, then run the gitleaks filter on its report.

  4. Step 4

    Gate on the result

    Fail when .summary.private is above zero. The same steps run as a CI job.

Quickstart

mkdir -p /tmp/secret-scan-tool && cd /tmp/secret-scan-tool
export NODE_AUTH_TOKEN="$(gh auth token)"   # any token with read:packages
echo '@catesworks:registry=https://npm.pkg.github.com' > .npmrc
echo '//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}' >> .npmrc
npm init -y >/dev/null
npm install --no-audit --no-fund @catesworks/secret-scan@0.2.0
export SCAN_SCRIPTS="$PWD/node_modules/@catesworks/secret-scan/scripts/secret-scan"

cd path/to/your-repo
node "$SCAN_SCRIPTS/generate-gitleaks-config.mjs"
gitleaks detect --source . --config "$SCAN_SCRIPTS/generated.gitleaks.toml" \
  --report-format json --report-path /tmp/gitleaks.json --exit-code 0
node "$SCAN_SCRIPTS/filter-gitleaks-output.mjs" /tmp/gitleaks.json > /tmp/gitleaks-filtered.json
node -e "process.exit(require('/tmp/gitleaks-filtered.json').summary.private > 0 ? 1 : 0)"

What you need

  • Node 24 or later and git
  • gitleaks; trufflehog is optional
  • A GitHub token with read:packages on @catesworks/secret-scan
  • For the gitleaks filter: the cwd at the scanned repository root