Sentinel

  ███████╗███████╗███╗   ██╗████████╗██╗███╗   ██╗███████╗██╗
  ██╔════╝██╔════╝████╗  ██║╚══██╔══╝██║████╗  ██║██╔════╝██║
  ███████╗█████╗  ██╔██╗ ██║   ██║   ██║██╔██╗ ██║█████╗  ██║
  ╚════██║██╔══╝  ██║╚██╗██║   ██║   ██║██║╚██╗██║██╔══╝  ██║
  ███████║███████╗██║ ╚████║   ██║   ██║██║ ╚████║███████╗███████╗
  ╚══════╝╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚═╝╚═╝  ╚═══╝╚══════╝╚══════╝

What is Sentinel?

Sentinel is a statically compiled, zero-dependency Git pre-commit hook and credentials scanner written in Go. It automatically blocks accidental commits of API keys, SSH private keys, cloud credentials, database connection strings, and other sensitive material before they enter version control.

It is a lightweight, developer-friendly alternative to Gitleaks and git-secrets, with broader detection coverage and significantly lower resource usage.

Sentinel uses a three-tier detection pipeline built for speed and near-zero false positives:

A finding must survive all three tiers before it is reported.

Quick Start

Install and protect your repository in under 60 seconds:

# 1. Install
go install github.com/sentinel-cli/sentinel/v2/cmd/sentinel@latest

# 2. Protect the current repository
sentinel install

# 3. Verify — Sentinel will now scan every commit automatically
git add . && git commit -m "test"

Or scan any directory right now, without a hook:

sentinel scan --recursive ./src

That is all. No configuration file required. No runtime dependencies. Works on Linux, macOS, Windows, and Android/Termux.

Terminal Demo

asciinema play https://sentinel-cli.github.io/sentinel/demo.cast

Table of Contents

• What is Sentinel
• Quick Start
• Performance
• Why Sentinel
• Architecture
• Signature Coverage
• Installation
• Configuration
• Usage
• Output Reference
• False Positive Handling
• Running Tests
• Contributing
• License

Performance

Measured on real-world repositories with Sentinel against the two most popular alternatives.

Summary:

Why Sentinel

Architecture

Detection Pipeline

  git commit (staged changes)
         |
  [Git Interop — internal/git]
   ListStagedFiles()   →  git diff --cached --name-status
   GetStagedDiff()     →  git diff --cached -- <path>  (modified files, added lines only)
   GetStagedContent()  →  git show :<path>              (new files, full content)
         |
  [Pre-flight Filters]
   - Binary detection: null-byte scan of first 8 KB (isBinaryFileFast)
   - Extension exclusion: case-insensitive match
   - Path exclusion: filepath.Match glob patterns
   - File size cap: files > 10 MB skipped
         |
  [Tier 1 — Aho-Corasick Trie  —  internal/trie/trie.go]
   Built once at startup via trie.Build() — allocation-free hot path
   Case-insensitive O(n) scan per line
   BIP-39 mnemonic detection: 12/15/18/21/24 words validated against 2048-word dictionary
   Single-layer Base64 decoding: re-feeds decoded value through trie (catches K8s secrets)
   Blob aggregation: 3+ consecutive high-entropy lines → single CRITICAL finding
         |
  [Tier 2 — Shannon Entropy  —  internal/entropy/entropy.go]
   Base64 tokens: entropy >= entropy_threshold (default 4.5 bits/symbol)
   Hex tokens:    entropy >= threshold × (4.0 / 6.0), min floor 3.0
   Skips: tokens < min_secret_length (default 20), all-identical chars, Java-style identifiers
         |
  [Tier 3 — Context Filter  —  internal/context/context.go]
   Checks (in order): test file path → commented line → unquoted RHS in source → UUID → version string
                    → env var placeholder → config placeholder → variable name → short alpha token
   Only Real decisions are forwarded to the reporter
         |
  [Reporter  —  internal/reporter/reporter.go]
   pretty / plain  → stderr    (human-readable, ANSI color)
   json / sarif    → stdout    (or directly to file if --output is used)
         |
  exit 0 (CLEAN)  |  exit 1 (BLOCKED)

H(X) = - sum over i of P(xi) * log2(P(xi))

Inline Suppression

Place sentinel:ignore on the flagged line or the preceding comment line:

// sentinel:ignore
apiKey := "sk_live_example_for_documentation"

apiKey := "sk_live_example_for_documentation" // sentinel:ignore

# sentinel:ignore
STRIPE_KEY="sk_live_example"

<!-- sentinel:ignore -->
<secret>sk-ant-api03-documented-example</secret>

A same-line annotation suppresses only that line. A comment-line annotation suppresses the immediately following line.

Signature Coverage

Installation

Pre-compiled Binary (Recommended)

Download the binary for your platform from the Releases page:

# Replace <version> and <arch>  e.g.  linux-amd64  linux-arm64  darwin-amd64  darwin-arm64
wget https://github.com/sentinel-cli/sentinel/releases/download/<version>/sentinel-<version>-<arch> -O sentinel
chmod +x sentinel
mv sentinel /usr/local/bin/       # Linux / macOS
# mv sentinel $PREFIX/bin/        # Termux (Android)
sentinel version

Go Install

go install github.com/sentinel-cli/sentinel/v2/cmd/sentinel@latest

Build from Source

git clone https://github.com/sentinel-cli/sentinel.git
cd sentinel
make build            # outputs to dist/sentinel
./dist/sentinel version

Git Hook Setup

Protect the current repository:

sentinel install          # installs .git/hooks/pre-commit
sentinel install --force  # overwrites an existing hook

Protect every repository on this machine (global):

sentinel install --global
# Creates ~/.config/sentinel/hooks/pre-commit
# Runs: git config --global core.hooksPath ~/.config/sentinel/hooks

Remove global hook:

git config --global --unset core.hooksPath

Full uninstall — removes binary, hooks, and config directory:

sentinel uninstall

Native pre-commit Framework

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/sentinel-cli/sentinel
    rev: v2.0.6 # Replace with the latest release version
    hooks:
      - id: sentinel

Configuration

Sentinel searches for .sentinel.yaml in this order:

1. --config / -c flag value
2. .sentinel.yaml in the current working directory (repository root)
3. ~/.sentinel.yaml in the home directory

With no config file, built-in defaults apply. The file is merged on top of defaults, so omitted fields keep their default values.

# Shannon entropy threshold (bits/symbol). Range: 0.0 to 8.0.
# Raise to reduce false positives. Lower to increase sensitivity.
# Default: 4.5
entropy_threshold: 4.5

# Minimum token length for entropy analysis.
# Tokens shorter than this produce unreliable scores.
# Default: 20
min_secret_length: 20

# Maximum file size to scan. Files exceeding this are skipped.
# Default: 10485760 (10 MB)
max_file_size_bytes: 10485760

# Whether to scan binary files (detected by null-byte in first 8 KB).
# Default: false
scan_binary_files: false

# Glob patterns (relative to repo root) to skip entirely.
# Default list below:
exclude_paths:
  - "vendor/**"
  - "node_modules/**"
  - "*.lock"
  - "go.sum"
  - "package-lock.json"
  - "**/locales/**"
  - "**/i18n/**"

# File extensions to skip (case-insensitive).
# Default includes images, fonts, audio, video, archives, binaries, office documents.
exclude_extensions:
  - ".png"
  - ".jpg"
  - ".jpeg"
  - ".gif"
  - ".bmp"
  - ".ico"
  - ".svg"
  - ".woff"
  - ".woff2"
  - ".ttf"
  - ".eot"
  - ".mp4"
  - ".webm"
  - ".mp3"
  - ".ogg"
  - ".zip"
  - ".tar"
  - ".gz"
  - ".bz2"
  - ".xz"
  - ".7z"
  - ".pdf"
  - ".doc"
  - ".docx"
  - ".xls"
  - ".xlsx"
  - ".exe"
  - ".dll"
  - ".so"
  - ".dylib"
  - ".a"
  - ".o"
  - ".css"
  - ".scss"
  - ".csv"
  - ".hex"
  - ".eml"
  - ".msg"
  - ".mbox"
  - ".vcf"
  - ".ics"

# Allowlist: findings whose token matches are silently ignored.
# Supports exact strings and filepath.Match glob patterns.
allowlist_patterns:
  - "AKIAIOSFODNN7EXAMPLE"
  - "sk_test_*"
  - "*-dummy-token-*"

# Disable individual detection tiers. Use with caution.
disable_tiers:
  trie: false     # disables Tier 1 Aho-Corasick matching
  entropy: false  # disables Tier 2 entropy analysis
  context: false  # disables Tier 3 suppression — expect many false positives

# Stop after the first finding. Useful in CI fail-fast loops.
fail_fast: false

# Print debug output to stderr.
verbose: false

# Custom signatures compiled into the Aho-Corasick automaton alongside builtins.
# Severity must be one of: CRITICAL, HIGH, MEDIUM, LOW  (defaults to HIGH if omitted).
custom_signatures:
  - id: "internal-api-key"
    description: "Proprietary internal service credential"
    prefix: "mycompany_key_"
    severity: "CRITICAL"
    regex: "^mycompany_key_[a-zA-Z0-9]{32}$"

Entropy Threshold Reference

Usage

Automatic (Pre-commit Hook)

After sentinel install, the hook fires on every git commit and scans only staged content:

• New files — full content via git show :<path>
• Modified files — added lines only via git diff --cached -- <path>

Ad-hoc Scanning

# Single file
sentinel scan config/production.yaml

# Directory (non-recursive)
sentinel scan ./config

# Directory, recursive (skips .git, build, node_modules automatically)
sentinel scan -r ./src

# Full Git history audit (streams git log --all -p; deduplicates by token)
sentinel scan --history .

# JSON output — written to stdout for piping
sentinel scan -f json -r ./src | jq '.findings[] | select(.severity == "CRITICAL")'

# SARIF output saved directly to file (keeps pretty terminal logs)
sentinel scan -f sarif -o sentinel.sarif .

In ad-hoc mode, files are processed concurrently using max(runtime.NumCPU(), 4) goroutines. In history mode, the Git log is streamed with a 10 MB line buffer; unique findings are deduplicated by token value.

CI Integration

GitHub Actions (Official Reusable Action)

The easiest way to integrate Sentinel into your GitHub Actions workflow is by using our official reusable action. It handles Go installation, compilation cache, and scanning automatically:

- name: Run Sentinel Git Secrets Scanner
  uses: sentinel-cli/sentinel@v2
  with:
    version: 'latest' # Optional: specific version to use (e.g. 'v2.x.x')
    args: '.'         # Optional: arguments to pass (e.g. "." or "--history .")
    sarif: 'true'     # Optional: set to 'true' to export findings as a SARIF report

To upload the results to GitHub Advanced Security (Code Scanning Alerts), configure the upload step:

- name: Upload SARIF report
  if: always()
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: sentinel-results.sarif

# GitLab CI
sentinel-scan:
  stage: test
  image: golang:1.22
  before_script:
    - go install github.com/sentinel-cli/sentinel/v2/cmd/sentinel@latest
  script:
    # Run scan; output JSON to file and print pretty results to console
    - sentinel scan -f pretty -o sentinel-report.json .
  artifacts:
    when: always
    paths:
      - sentinel-report.json

Command Reference

Output Reference

Clean (exit 0):

  SENTINEL CLEAN  --  4 file(s) scanned in 3.2ms

Blocked (exit 1):

   CRITICAL   cmd/main.go:12
               [PATTERN] GitHub Personal Access Token (classic)
               Token:  ghp_AB****************************cdef
               -> token := "ghp_AB...cdef"

   HIGH       config/settings.go:8
               [ENTROPY] High-entropy BASE64 string (entropy=6.23)
               Token:  wJalrX****************************EY
               -> AWS_SECRET = "wJalrX...EY"

---------------------------------------------------------------------
  Files scanned : 4  |  Elapsed : 5.1ms
  CRITICAL:1   HIGH:1   MEDIUM:0   LOW:0
---------------------------------------------------------------------
  COMMIT BLOCKED -- remove the secrets above and try again.

JSON schema (-f json — written to stdout):

{
  "sentinel_version": "v2.x.x",
  "status": "blocked",
  "scanned_files": 4,
  "elapsed_ms": 5,
  "findings": [
    {
      "file_path": "cmd/main.go",
      "line": 12,
      "severity": "CRITICAL",
      "tier": "PATTERN",
      "signature_id": "github-pat-classic",
      "description": "GitHub Personal Access Token (classic)",
      "token": "ghp_AB****************************cdef",
      "entropy": 5.23,
      "line_snippet": "token := \"ghp_AB...cdef\""
    }
  ]
}

When clean: "status": "clean", "findings": [].

SARIF (-f sarif — written to stdout): SARIF 2.1.0, compatible with GitHub Advanced Security Code Scanning.

False Positive Handling

Tier 3 automatically eliminates the vast majority of false positives. For persistent cases:

# .sentinel.yaml
allowlist_patterns:
  - "AKIAIOSFODNN7EXAMPLE"   # exact match
  - "sk_test_*"              # all Stripe test keys
  - "*-placeholder-*"

Running Tests

make test     # all tests with race detector
make bench    # benchmarks
make cover    # HTML coverage report → coverage.html
make lint     # staticcheck

Representative benchmark output (shows zero allocations on the hot scan path):

BenchmarkAutomatonBuild-8        3     195,234 ns/op    327,680 B/op
BenchmarkSearch-8             3000     341,012 ns/op          0 B/op   <- 0 allocs
BenchmarkSearchWithHit-8      2000     412,887 ns/op      3,456 B/op
BenchmarkShannonSmall-8    5000000         234 ns/op          0 B/op
BenchmarkFullPipeline-8         500   2,341,201 ns/op     12,340 B/op

Contributing

Contributions are welcome. All contributors must agree to the Contributor License Agreement. By submitting a pull request you confirm that you transfer copyright of the contribution to Khaled Hani. This protects the project's dual-licensing model.

Author

Developed by Khaled Hani — https://t.me/A245F

License

GNU Affero General Public License v3.0.

Commercial SaaS deployment or distribution of a modified version without releasing the source under AGPL-3.0 is prohibited. See LICENSE for full terms.