@srikanthmanivannan/sentinel-cli

v0.1.7

Published

21 days ago

CLI tool for Sentinel security scanning with git hook integration

0High
0Medium
0Low

srikanthmanivannan

security secrets cli git-hooks leak-prevention

Sentinel CLI

🔒 Stop secrets before they reach GitHub.

Sentinel CLI scans your codebase and staged Git changes for API keys, tokens, credentials, private keys, and other sensitive data — catching secrets before they become part of your Git history. Designed for individual developers, open-source maintainers, and teams that want a pre-commit safety net without relying on everyone remembering to check by hand.

Command-line counterpart to the Sentinel VS Code extension, which brings similar detection into the editor as you type.

Why Sentinel?

A leaked credential in a commit is a permanent record — even if you delete it in the next commit, it's still in the Git history. Sentinel is meant to catch it at the two points where it's still cheap to fix: while scanning a directory, and at the git commit boundary via a pre-commit hook.

Requirements

Node.js 18 or later

Install

npm install -g @srikanthmanivannan/sentinel-cli

Or run it without installing:

npx @srikanthmanivannan/sentinel-cli scan

Quick start

cd your-project

sentinel scan  # Scan the current directory
sentinel init  # Install the Git pre-commit hook

Commands

| Command | Description | | --- | --- | | scan [path] | Scan a directory or file for secrets (default: current directory) | | commit-hook | Check staged Git changes for secrets (used by the pre-commit hook) | | init | Install Sentinel as a Git pre-commit hook | | help | Show the help message |

Example: scanning a directory

$ sentinel scan .

🔍 Scanning . for secrets...

⚠️  Found secrets in 1 file(s):

  📄 src/config.ts: 2 secret(s)

❌ Total: 2 potential secret(s) detected

Example: git hook blocking a commit

$ git commit -m "add config"

🔍 Scanning staged files for secrets...

⚠️  Found 1 potential secret(s):

  ❌ AWS Access Key [high] - AWS

🛑 1 HIGH SEVERITY secret(s) detected!

To bypass this check, use: git commit --no-verify

Git hook integration

sentinel init

sentinel init installs a Git pre-commit hook. It does not check for or preserve an existing pre-commit hook — if one is already present, it is overwritten.

What happens on `git commit`

git diff --cached is scanned as one block of text (the full staged diff, not file-by-file). Only a high-severity finding blocks the commit; other severities are printed as warnings but don't block. A --force flag on commit-hook itself would downgrade a block to a warning, but the hook script init installs doesn't pass it — so in practice, the installed hook always blocks on a high-severity finding.

git commit
    │
    ▼
pre-commit hook runs: sentinel commit-hook
    │
    ▼
Any files staged? ──No──▶ exit 0, commit proceeds
    │ Yes
    ▼
Get full staged diff, run detection engine
    │
    ▼
Any findings? ──No──▶ exit 0, commit proceeds
    │ Yes
    ▼
Any HIGH severity finding?
    │
  ┌─┴─────────────┐
  No               Yes
  │                │
  ▼                ▼
print warnings   exit 1
exit 0, commit   commit blocked
proceeds

(Full Mermaid version: ARCHITECTURE.md)

To skip the check for a specific commit:

git commit --no-verify

Exit codes

| Command | Exit code | Meaning | | --- | --- | --- | | scan | 0 | no secrets found | | scan | 1 | secrets found | | commit-hook | 0 | no high-severity secrets in staged changes | | commit-hook | 1 | high-severity secret found (commit blocked) |

What it detects

Cloud credentials

AWS access keys, secret keys, session tokens

Google Cloud

Google Cloud API keys

Payments

Stripe live, test, and publishable keys

Source control & CI

GitHub personal access, OAuth, and app installation tokens

Messaging

Slack bot tokens
Slack webhooks

Communications & infra

Twilio API keys
SendGrid API keys
Docker registry tokens
npm tokens

Auth

JWTs
Bearer tokens

Databases

MongoDB, PostgreSQL, MySQL, SQL Server connection strings

Private keys

RSA, DSA, EC, OpenSSH, PGP key blocks

PII

Email addresses, credit card numbers, Social Security numbers

CI/CD

Run it as a check in GitHub Actions:

name: Secret Scan

on: [push, pull_request]

jobs:
  sentinel:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx @srikanthmanivannan/sentinel-cli scan .

The scan command exits non-zero when secrets are found, causing the workflow step to fail — nothing CI-specific happens beyond running the command.

CI job starts
    │
    ▼
npx sentinel-cli scan .
    │
    ▼
Any secrets found? ──No──▶ exit 0, step succeeds
    │ Yes
    ▼
exit 1, step fails, workflow marked failed

License

MIT