Crenox

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

What is Crenox?

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

It is an alternative to tools like Gitleaks and git-secrets, focusing on lower resource utilization and local workflow integration.

Crenox uses a three-tier detection pipeline designed for speed and false positive reduction:

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/crenoxhq/crenox/v2/cmd/crenox@latest

# 2. Protect the current repository
crenox install

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

Or scan any directory right now, without a hook:

crenox 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://crenoxhq.github.io/crenox/demo.cast

Table of Contents

• What is Crenox
• Quick Start
• Performance
• Why Crenox
• Architecture
• Signature Coverage
• Installation
• Configuration
• Usage
• Output Reference
• False Positive Handling
• In the Wild (Live Archive)
• Running Tests
• Contributing
• License

Performance

Measured on real-world repositories with Crenox against the most popular alternatives, on a standard GitHub Actions Ubuntu cloud runner — the same infrastructure used in real-world CI/CD pipelines.

Transparent & Auditable — These results were generated by an open-source automated benchmark script running on a standard GitHub Actions Ubuntu cloud runner. The full methodology, tooling, and workflow configuration are publicly visible — results are triggered and verified by the maintainer on each release. View the latest benchmark run →

Summary:

Why Crenox — Comparison (vs Gitleaks, Betterleaks)

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]
   - Bounded streaming queue (size 1024) to keep memory footprint bounded under concurrent load
   - Early directory pruning: walks ignore excluded paths (e.g. node_modules, vendor) on the fly
   - 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 DFA matching
   Case-insensitive O(n) scan using a branchless 256-byte toLower lookup table
   and sync.Pool-recycled 64 KB streaming buffers to cap heap memory to ~3 MB
   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 crenox:ignore on the flagged line or the preceding comment line:

// crenox:ignore
apiKey := "sk_live_example_for_documentation"

apiKey := "sk_live_example_for_documentation" // crenox:ignore

# crenox:ignore
STRIPE_KEY="sk_live_example"

<!-- crenox: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/crenoxhq/crenox/releases/download/<version>/crenox-<version>-<arch> -O crenox
chmod +x crenox
mv crenox /usr/local/bin/       # Linux / macOS
# mv crenox $PREFIX/bin/        # Termux (Android)
crenox version

Go Install

go install github.com/crenoxhq/crenox/v2/cmd/crenox@latest

Build from Source

git clone https://github.com/crenoxhq/crenox.git
cd crenox
make build            # outputs to dist/crenox
./dist/crenox version

Android / Termux

Crenox can be easily installed on Android using Termux via the Termux User Repository (TUR):

pkg install tur-repo
pkg install crenox

Git Hook Setup

Protect the current repository:

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

Protect every repository on this machine (global):

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

Remove global hook:

git config --global --unset core.hooksPath

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

crenox uninstall

Native pre-commit Framework

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

Configuration

Crenox searches for .crenox.yaml in this order:

1. --config / -c flag value
2. .crenox.yaml in the current working directory (repository root)
3. ~/.crenox.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/**"
  - "dist/**"
  - "build/**"
  - "out/**"
  - "target/**"
  - "bin/**"
  - ".next/**"
  - ".nuxt/**"
  - ".yarn/**"
  - ".git/**"
  - "*.lock"
  - "go.sum"
  - "package-lock.json"
  - "pnpm-lock.yaml"
  - "yarn.lock"
  - "**/locales/**"
  - "**/i18n/**"
  - "**/*.min.js"
  - "**/*.min.css"

# 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"
  - ".cache"
  - ".pb.go"
  - ".gen.go"
  - ".g.go"
  - ".map"

# 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 crenox 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
crenox scan config/production.yaml

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

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

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

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

# SARIF output saved directly to file (keeps pretty terminal logs)
crenox scan -f sarif -o crenox.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 Crenox into your GitHub Actions workflow is by using our official reusable action. It handles Go installation, compilation cache, and scanning automatically:

- name: Run Crenox Git Secrets Scanner
  uses: crenoxhq/crenox@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: crenox-results.sarif

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

Command Reference

Output Reference

Clean (exit 0):

  CRENOX 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):

{
  "crenox_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:

# .crenox.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.