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

Installation

You can install in your repository directory with:

stashbase scan install pre-commit

stashbase scan install pre-push

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_.*'

Agent sandboxes

The installed hook blocks also work when a coding agent commits or pushes from inside stashbase agent run. The sandbox has no API key, so the hook asks the Agent Proxy to run the scan on the host. Enable it with allow_hooks = ["secret_scan"] in the agent profile. Hooks installed before this was supported need stashbase scan install once more. See Secret scan hooks.

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)