CLI

CLI scans are designed for local developer workflows and are typically used in git hooks.

Prerequisites

• A git repository with your codebase
• Stashbase CLI installed locally
• A personal API key configured for CLI usage

Git hook workflows

You can automate scans with two git hooks:

• Pre-commit hook: scan staged changes
• Pre-push hook: scan unpushed commits

Pre-commit hook

Before committing your changes, the pre-commit git hook scans staged changes for hard-coded secrets.

Example .git/hooks/pre-commit:

#!/bin/sh

stashbase scan staged --config "../../stashbase-scan.yaml"

Pre-push hook

Before pushing your changes to a remote repository, the pre-push git hook scans unpushed commits for hard-coded secrets.

Example .git/hooks/pre-push:

#!/bin/sh

stashbase scan commits --config "../../stashbase-scan.yaml"

Configuration

Create stashbase-scan.yaml in your repository root.

In your codebase, you can configure the scans by creating stashbase-scan.yaml file in the root of your repository. Currently, you can configure the following options:

• enabled: boolean, default: true
• output-dir: string, default: none
• excluded-files: array of strings (gitignore-style patterns for files/folders to exclude), default: none
• match: string (find matching secrets), default: none
  • project: object with following properties (find secret matches in the project):
    • identifier: string (ID or name of the project)
    • environments: array of strings (IDs or names or groups api-* of environments to scan), default: all environments in the project
  • files: array of strings (local file paths with secrets to find matches), default: none
• ignored-secrets: object with optional properties:
  • hashes: array of strings (SHA256 hashes of secrets to ignore), default: none
  • regexes: array of strings (regexes for ignoring secret values), default: none

Example:

excluded-files:
  - '*.tsx'
  - 'src/utils/test.ts'

output-dir: 'scan-results'

match:
  project:
    identifier: 'our-project'
    environments:
      - 'dev'
      - 'api-*'

ignored-secrets:
  hashes:
    - 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
  regexes:
    - '^test_.*'

Skipping scans

To bypass git hooks when needed, use --no-verify:

git push --no-verify
git commit -m "feat: add new feature" --no-verify

Skipping specific secrets

If a specific value should be ignored (for example testing keys), add @stashbase-ignore on the previous line or add hash/regex ignore rules in configuration.

Scan results

If a scan finds potential hard-coded secrets, it exits with non-zero status and writes findings output (for configured output options).

Rate limits

Scan operations are subject to rate limits to ensure fair usage and system stability.

• /v1/scan/file-changes and /v1/scan/commits: 60 requests per 60 seconds

Direct scan payload caps (file-changes, commits):

• Maximum 200 files
• Maximum 10,000 diff lines
• Maximum 1,000,000 diff bytes (~1 MB)

Rate limit will be reached if you exceed one of the limits. You will receive 429 Too Many Requests error with corresponding error details in the response.

Troubleshooting

• Authorization errors: verify your API key is configured in CLI
• No output: verify output path is valid/writable
• False positives: use @stashbase-ignore or ignore hashes/regexes
• Hook not running: ensure hook is executable (chmod +x .git/hooks/pre-commit)