Eliminating credential leaks at the commit stage.

Why local validation is the final line of defense

In modern DevSecOps, secret scanning is often offloaded to continuous integration (CI) platforms or post-push webhooks. While valuable, these remote validations operate after the secret has already reached the remote hosting repository. Once a credential resides in the git database, it must be considered compromised—triggering costly key rotation, access log audits, and multi-team incident responses.

"Once a private credential escapes the local workstation, security changes from prevention to remediation."

Sentinel blocks leaks at the edge. By installing as a native git pre-commit hook directly in your local environment, it evaluates staged deltas and aborts the commit if an active credential, private key, or password configuration is matched. Because it operates locally, it requires no internet connection and does not log data to external analytics collectors.

Verifying credentials in under 20 milliseconds

Developer velocity is a major constraint for pre-commit verification. Hooks that introduce noticeable latency encourage developers to bypass the validation workflow entirely. To meet this constraint, Sentinel implements a three-tier pipeline that processes staging areas in milliseconds while maintaining high recall accuracy.

Tier 1: Prefix Automaton

Every file is parsed through an $O(N)$ Aho-Corasick multi-pattern search trie. Custom user signatures and known credential templates are compiled directly into the state machine, allowing the engine to discover candidates in a single linear character pass.

Tier 2: Shannon Entropy Filtering

Candidate tokens matched in the first pass are evaluated for character randomness. Sentinel calculates the exact entropy of the string to differentiate actual randomized access tokens from standard code templates or placeholder variables.

Tier 3: Context Analysis

Finally, the parser audits surrounding lines, variable assignments, and comments. This layer suppresses findings located in test assertions, mock environments, or lines specifically appended with a // sentinel:ignore directive.

Output Demonstration

When Sentinel identifies a leak, it aborts the commit process and renders a detailed breakdown of the findings in the console:

Workstation footprint and latency

To evaluate Sentinel's performance, we run comparative workstation scans against gitleaks and trufflehog. Measurements are collected locally on an octa-core ARM64 workstation, tracking total execution latency and peak resident set size (RSS).

Deployment and local setup

Sentinel is statically compiled to run natively across Linux, macOS, and Android/Termux. It does not require Go, Python, or additional runtime setups on the workstation.

Option A: Pre-compiled Binaries (Recommended)

The fastest way to install Sentinel without Go dependencies. Perfect for Termux/Android and Linux systems.

# 1. Download the target binary
wget https://github.com/sentinel-cli/sentinel/releases/download/v2.0.5/sentinel-v2.0.5-linux-arm64 -O sentinel

# 2. Add execution permissions
chmod +x sentinel

# 3. Move to your binary path ($PREFIX/bin for Termux, or /usr/local/bin for Linux/macOS)
mv sentinel $PREFIX/bin/

# 4. Verify deployment
sentinel version

Option B: Go package installer

If you have Go installed on your path, fetch and compile the latest release directly:

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

Option C: Compile from source

Clone the repository and build manually using our Makefile configurations:

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

Activating the Git Hook

Once the binary is in your path, initialize the pre-commit validator inside your target repository:

# Enable for the current repository
sentinel install

# Enable globally for all future clones/initializations
sentinel install --global

Workstation run modes and directives

Sentinel supports several CLI run modes to fit different developer workflows, ranging from automated Git pre-commit hooks to manual, ad-hoc filesystem scans.

1. The Commit-Time Validator

Executed automatically by the Git pre-commit hook during the staging process. It reads the index, extracts staged diff blobs, and scans them in-memory. If findings are found, the commit is aborted.

sentinel run

2. Local Directory Scan

Used to run manual ad-hoc audits on any directory or file tree recursively. Excellent for auditing directories before initial commits.

sentinel scan -r ./path/to/project

3. Continuous Integration Export

Generate structured logs in JSON or SARIF format for integration into external pipelines and alert aggregators.

sentinel scan -r -f sarif . > report.sarif

Tailoring Sentinel to your codebase

Sentinel works out of the box with production-ready defaults. For enterprise teams or complex workspaces, behavior can be customized by placing a .sentinel.yaml file in the repository root.

Custom API Signatures

You can define proprietary rules and compile them directly into the Aho-Corasick automaton alongside built-in rules, avoiding regex overhead:

# .sentinel.yaml
custom_signatures:
  - id: "internal-api-key"
    description: "Proprietary internal service credential"
    prefix: "mycompany_key_"
    severity: "CRITICAL"
    regex: "^mycompany_key_[a-zA-Z0-9]{32}$"

Path & Extension Exclusions

Skip specific folders (e.g. vendored dependencies) and file types to minimize scan time:

exclude_paths:
  - "vendor/**"
  - "node_modules/**"
exclude_extensions:
  - ".png"
  - ".zip"

Global Allowlist Patterns

Prevent false positives for known mock/test keys used across multiple directories:

allowlist_patterns:
  - "AKIAIOSFODNN7EXAMPLE"   # Exact match
  - "sk_test_*"              # Stripe test keys

Technical insights & system logs

Articles written by the developers covering the design, optimization, and security philosophy of Sentinel.

Other engineering masterpieces

Explore other security, networking, and system-level applications built in our network ecosystem.

Get in touch & discuss security

Sentinel is an open-source security tool built in collaboration with the developer community. We value feedback, rule suggestions, and reports from all users.

If you would like to report a security issue, propose a new credential signature, or ask questions about workstation deployments, please use our community channels:

• GitHub Discussions & Issues: Share feature requests, rule contributions, and report issues on our GitHub Repository.
• Direct Developer Channel: You can contact Khaled Hani directly on Telegram at https://t.me/A245F for support, direct feedback, or custom integrations.