# SimplyScan secret scanning in a CLI, pre-commit hook and GitHub Actions

Requires Node 20+ and an entitled SimplyScan API key from Dashboard → API. Uses the existing allowance (20 Pro scans per UTC day); no npm package or paid third-party scanner. Selected source is uploaded to SimplyScan, processed in memory and not retained. Masked findings are saved in the account. Do not upload code you are not authorized to send.

Download the CLI from https://simplyscan.io/integrations/simplyscan-secrets.mjs into `.simplyscan/simplyscan-secrets.mjs`. Review the file before use. Set `SIMPLYSCAN_API_KEY` in your shell's secret environment (never a committed file).

```sh
node .simplyscan/simplyscan-secrets.mjs src/app.ts src/auth.ts --fail-on high
node .simplyscan/simplyscan-secrets.mjs --staged --fail-on high
```

`--stdin` accepts one text file. `--staged` scans the index, including staged contents that differ from your working files. Binary files, symlinks, over-budget files, API failures and unavailable quota return exit 2; they never silently pass. Maximum 50 files, 200 KB per file and 1 MB total. Exit 0 means no secret findings at the threshold in the inspected source, exit 1 means findings, and exit 2 means no valid verdict.

## Pre-commit hook

Download https://simplyscan.io/integrations/pre-commit and review it. Check `git config --get core.hooksPath` and your existing hook first. If a pre-commit hook already exists, add the CLI invocation to it rather than overwriting it. Otherwise install the downloaded hook in your configured hooks directory and make it executable. Do not commit the API key. A missing key blocks the commit with exit 2. Hook installation is an explicit local choice; downloading the CLI does not modify Git settings.

## GitHub Action

The action source is in the SimplyScan repository under `.github/actions/secret-scan`. For use in any repository, download the public action files from SimplyScan into a new `.github/actions/simplyscan/` directory:

- https://simplyscan.io/integrations/github-action.yml → `action.yml`
- https://simplyscan.io/integrations/simplyscan-secrets.mjs → `simplyscan-secrets.mjs`

Review and commit both files to pin the version in your repository. These downloads make the integration usable without access to SimplyScan's private application repository. Store the key as the Actions secret `SIMPLYSCAN_API_KEY`. Check out your source before running the local action:

```yaml
name: Secrets
on: [push]
jobs:
  secrets:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ./.github/actions/simplyscan
        with:
          api-key: ${{ secrets.SIMPLYSCAN_API_KEY }}
          files: |
            src/app.ts
            src/auth.ts
          fail-on: high
```

The action and CLI must be in the same directory. Never expose the key to untrusted pull-request code with `pull_request_target`. No npm package has been published; publishing requires Daniel's npm organization and approval.