Skip to main content

CommitGuard

The local security control plane that runs before your commit.

Secrets, risky code, dependencies, and imported analyzer findings. One policy, one baseline, one fast gate. No telemetry. No source upload. No waiting for CI.

CI Python 3.11+ License Offline first Zero telemetry Release

Quickstart · Why CommitGuard · Features · CLI · Architecture · Docs


$ commit-guard scan --staged

  COMMITGUARD  policies: balanced  rules: 701  mode: staged diff
  ------------------------------------------------------------
  CRITICAL  0    HIGH  1    MEDIUM  1    LOW  0    INFO  0
  ------------------------------------------------------------
  src/payments/client.py:42   cg-python-weak-random-secret   HIGH
  src/settings.py:17          cg-python-django-wildcard-hosts MEDIUM

  STATUS: FAILED  (>= high severity)
  Scanned 214 line(s) in 0.42s

Why CommitGuard

Most security tools tell you what was wrong after the code left your machine. CommitGuard moves the control point to the developer's local loop.

  • Sub-second feedback. Warm staged scans complete under one second on the reference diff. Fix the issue while the context is still fresh.
  • Offline by default. Normal scans make no network calls, collect no telemetry, and never upload source code. Optional online features are explicit.
  • One decision engine. Regex, secrets, Python AST taint, SCA, and imported SARIF findings all flow through the same baseline, triage, and policy gate.
  • Built for real repositories. Stable fingerprints, new-code ratchets, owner/expiry metadata, path allowlists, and committed triage decisions.
  • CI parity. The same rules and exit codes run in a pre-commit hook, locally, in GitHub Actions, or from a raw SARIF report.
  • A local console, not a cloud dashboard. The loopback GUI handles triage, fixes, policies, pipelines, Git operations, and rule inspection on your machine.

Quickstart in 60 Seconds

# Install from PyPI.
pipx install commitguard-kynsec

# Or install the signed wheel from GitHub Releases:
# pipx install "https://github.com/KynSec/commitguard-kynsec/releases/download/v3.4.2/commitguard_kynsec-3.4.2-py3-none-any.whl"

# Or install from source:
# pipx install "git+https://github.com/KynSec/commitguard-kynsec.git"

# Initialize in any Git repository
cd /path/to/your/repo
commit-guard init

# Stage your work and run the local gate
git add .
commit-guard scan --staged

That is the whole loop: install, initialize, scan. No account, API key, cloud project, or network connection is needed for a normal scan.

To make the gate run automatically before every commit:

commit-guard install .

The installer keeps a self-contained copy in .commit_guard/, writes the hook, and preserves your existing configuration and ignore files.

Release status

CommitGuard 3.4.2 is the current release. All four planned phases (0–4) are implemented. GitHub Releases provide signed wheels, sdists, a single-file zipapp, the VS Code extension, SBOMs, build provenance, and container images. The remaining Phase 4 organizational evidence is tracked in Phase 4 exit.

Phase Status
0 — Hygiene Complete
1 — MVP Complete
2 — Credible 3.0 Complete
3 — Category tool Complete
4 — Ecosystem Implemented and released; external evidence pending
5 — Zero-friction adoption Next
6 — Team adoption and trust Planned
7 — Default local gate & ecosystem Planned

Install Options

Method Command Best for
pipx pipx install commitguard-kynsec Isolated CLI install from PyPI
PyPI python -m pip install commitguard-kynsec Existing virtual environments
Release wheel pipx install "https://github.com/KynSec/commitguard-kynsec/releases/download/v3.4.2/commitguard_kynsec-3.4.2-py3-none-any.whl" Signed wheel from GitHub Releases
Source git clone https://github.com/KynSec/commitguard-kynsec.git Development and review
VS Code Install release VSIX (code --install-extension commitguard-kynsec-1.0.1.vsix) Live diagnostics and the 1.0.1 scan panel
pre-commit commit-guard install . --no-hook Framework-managed hooks
GitHub Action uses: KynSec/commitguard-kynsec@v3.4.2 CI enforcement
Docker docker pull ghcr.io/kynsec/commitguard-kynsec:v3.4.2 Isolated or CI runs
Homebrew Formula in packaging/homebrew/commitguard.rb macOS/Linux package management
Scoop Manifest in packaging/scoop/commitguard.json Windows package management

Requirements: Python 3.11+, git, and PyYAML 6+ (installed automatically). Linux, macOS, Windows, Git worktrees, and custom core.hooksPath are supported.

The GHCR package may require docker login ghcr.io until its visibility is set to public. In-repo Homebrew and Scoop manifests are updated for 3.4.1; upstream submission is tracked as part of Phase 5.

VS Code extension

Install the signed commitguard-kynsec-1.0.1.vsix from the 3.4.2 release, or build it from editors/vscode/. Marketplace publication is pending.

The extension starts the local language server for live diagnostics and adds an Activity Bar scan panel. Version 1.0.1 can scan the current file, staged changes, or the full repository; select any combination of rule databases (custom, gitleaks, nuclei, devskim, semgrep, semgrep:semgrep_python, python_ast, javascript_ast, java_ast, go_ast); scan on save; export JSON; browse the last 20 scans in the History tab; and show finding counts in the status bar. It runs only in trusted workspaces.

Feature Matrix

Capability What CommitGuard gives you Offline
Staged commit gate Scans only added lines with stable exit codes and a policy decision. Yes
Secret detection 220+ gitleaks-style rules with entropy, keywords, path filters, and allowlists. Values are redacted by default. Yes
SAST 280+ curated native and MIT-licensed DevSkim rules for Python, JS/TS, Go, Java, PHP, Ruby, Rust, C/C++, shell, frameworks, web, CI, Kubernetes, Terraform, and Docker. Yes
Python + JS/TS taint Standard-library AST checks for request/input flows into SQL, shell, code-exec, SSRF, path, and XSS sinks, with cross-file helper summaries for Python. Yes
Interprocedural taint Cross-file summaries for JavaScript/TypeScript, Java, and Go wrappers, plus Python helper flows. Yes
SCA reachability + VEX Import evidence for first-party code, OpenVEX/CycloneDX VEX import/export, and non-blocking not_affected/fixed decisions. Yes
Signed rule packs + registry HMAC-signed packs, digest-pinned git registry, install/verify/sign/remove, and revocation. Yes
Local-first AI assistant Deterministic, redacted, token-bounded context packages; remote providers are disabled unless explicitly enabled. Yes / opt-in
AI evaluation + leaderboard Reproducible AI evaluation and benchmark leaderboard artifacts. Yes
Native binaries Optional Linux/macOS/Windows builds for environments without Python. Yes
Governance + security response Maintainer council, release managers, key custodians, CODEOWNERS, and a 48-hour handoff runbook. Yes
VS Code 1.0.1 Current-file, staged, and repo scans; scan-on-save; history; JSON export; status-bar counts. Yes
Dependencies Pinned-dependency checks against an offline OSV snapshot with optional HMAC-signed sidecars, plus opt-in OSV.dev lookup. Yes / opt-in
Analyzer interop Normalize and merge SARIF or native output from Semgrep, CodeQL, Trivy, Grype, Checkov, Bandit, and gitleaks. Yes
SBOM and licenses CycloneDX 1.6, SPDX 2.3, and an allow/deny/review license policy with separate exit status. Yes
Compliance Control mapping packs for OWASP Top 10, CWE Top 25, ASVS 5.0, PCI DSS 4.0, and SOC 2 technical evidence, with explicit caveats. Yes
Editor and watch loops Stdio LSP diagnostics/code actions, a VS Code extension, and watch --once incremental snapshots. Yes
Dashboard Self-contained HTML/JSON with severity, category, owner, trend, and report provenance. Yes
Plugins Signed manifests, verified install/remove, out-of-process execution, capability limits, timeouts, and output caps. Yes
Policy engine strict, balanced, and audit profiles; thresholds, budgets, ratchets, and new-code gating. Yes
Baseline and triage Fingerprints, accepted-risk metadata, owners, expiry, stale-entry audits, and committed triage YAML. Yes
Quarterly audit Local reports, triage state, bounded history, and optional compliance packs without scanning or network access. Yes
Fix workflow Preview and apply rule-provided fixes, then re-stage safely. Yes
Reports Markdown, JSON schema 3, SARIF 2.1.0, self-contained HTML, JUnit, GitLab Code Quality, and Checkstyle. Yes
Local GUI Loopback-only console for scans, policy, triage, fixes, pipelines, Git, rules, reports, and configuration. Yes
CI and hooks Composite GitHub Action, GitLab MR summaries/inline suggestions, native pre-commit/pre-push hooks, and pre-commit framework support. Yes
Release artifacts Wheel, sdist, single-file zipapp, signed checksums, build provenance, SBOM, and a container image. Yes
Rule QA Schema validation, regex compilation, positive/negative corpus tests, and rule inspection. Yes
Privacy Zero telemetry, no source upload, local reports, and redaction across every output format. Yes

CLI at a Glance

# Gate the staged diff
commit-guard scan --staged
commit-guard scan --staged --threshold medium
commit-guard scan --staged --fix-dry-run
commit-guard scan --staged --gate --policy-profile balanced

# Scan a branch, history, or the whole tree
commit-guard scan --diff origin/main...HEAD
commit-guard scan --history 50
commit-guard scan --all

# Determinant profiles and explicit file/rule selection
commit-guard scan --list-profiles
commit-guard scan --profile app-code
commit-guard scan --profile python-security --include "src/**" --rule "cg-python-*"
commit-guard scan --profile secrets-only --exclude "tests/fixtures/**"

# Dependencies and reports
commit-guard scan --sca
commit-guard scan --sca --sca-online        # explicit network opt-in
commit-guard scan --format sarif
commit-guard scan --format html
commit-guard sbom . --format cyclonedx --output sbom.json
commit-guard license . --policy license-policy.toml
commit-guard dashboard . --output dashboard.html

# Developer loops
commit-guard watch .                       # incremental re-scan on save
commit-guard watch . --once --all          # one audit scan, then exit
commit-guard lsp .                         # stdio language server

# Ecosystem surfaces
commit-guard scan --sca-reachability
commit-guard compliance . --report report.json --pack owasp-top10-2021
commit-guard vex export --report report.json --output openvex.json
commit-guard vex apply --report report.json --vex openvex.json
commit-guard ai explain --report report.json --fingerprint <fp>
commit-guard ai context --report report.json --output context.json
commit-guard packs install --source ./pack
commit-guard packs verify --dir ~/.config/commitguard/packs
commit-guard packs registry-install --registry registry.json --name <pack>
commit-guard plugin list
commit-guard plugin install --source plugins/example
commit-guard plugin verify --dir plugins

# Policy, baseline, and triage
commit-guard gate --staged
commit-guard baseline update --owner security --expiry 2026-12-31
commit-guard triage list
commit-guard triage audit
commit-guard audit . --reports commit_guard_reports --since 2026-01-01

# Bring findings from other analyzers into the same gate
commit-guard ingest semgrep.sarif trivy.json grype.json checkov.sarif
commit-guard report merge reports/*.sarif --format sarif --output merged.sarif

# Local console and maintenance
commit-guard gui
commit-guard status
commit-guard doctor
commit-guard rules check

Exit codes are intentionally simple:

Code Meaning
0 Clean, or every finding is below the blocking policy.
1 Blocking findings or a policy failure. Treat this as a failed gate.
2 CommitGuard could not run: bad repo, config, rules, or dependency.

One Policy for Every Analyzer

CommitGuard does not care whether a finding came from its own regex engine, a Python taint pass, an offline dependency snapshot, or a Semgrep report. Every finding is normalized into the same schema, fingerprinted, checked against the baseline and triage state, and evaluated by one local policy.

[gate]
enabled = true
profile = "balanced"       # strict | balanced | audit
threshold = "high"
fail_on = "new"
ratchet = true
max_new = { critical = 0, high = 0, medium = 25, low = 100 }

The result is one reviewable decision instead of five dashboards:

commit-guard scan --staged --gate
commit-guard gate --report merged.sarif --format json
commit-guard policy validate
commit-guard policy explain cg-python-eval

Architecture

+----------------------- developer machine ------------------------+
|                                                                  |
|   git index                                                      |
|       |                                                          |
|       v                                                          |
|   staged diff ---> secret / regex rules ---+                     |
|       |            Python AST taint --------+                     |
|       |            SCA + OSV snapshot ------+                     |
|       |            SARIF / native reports --+                     |
|       |                                     |                    |
|       +------------------+------------------+                    |
|                          v                                       |
|                 normalized findings                              |
|                 (schema v3, fingerprints)                        |
|                          |                                       |
|               baseline + triage + policy                         |
|                          |                                       |
|                 PASS / FAIL + reports                            |
|                          |                                       |
|              terminal + loopback GUI + CI artifacts              |
|                                                                  |
+------------------------------------------------------------------+
        no telemetry  |  no cloud dependency  |  no source upload

Core modules:

  • core/rule_loader.py loads and caches gitleaks, native, Semgrep-compatible, and nuclei-style rules.
  • core/scanner.py applies path, context, entropy, allowlist, suppression, and redaction rules.
  • core/engines/ provides the isolated regex and AST engine adapters.
  • core/interprocedural.py builds cross-file taint summaries for JS/TS, Java, and Go.
  • core/reachability.py records SCA import evidence; core/vex.py applies VEX decisions.
  • core/rule_packs.py verifies, signs, installs, and resolves signed third-party packs.
  • core/ai_assistant.py builds redacted, local-first context packages.
  • core/policy.py and core/triage.py turn findings into a deterministic gate.
  • core/reporter.py writes every output format, including SARIF 2.1.0.
  • gui_server.py serves the token-protected loopback control center.

See Architecture for the full data flow and design tradeoffs.

Local GUI Console

commit-guard gui
# opens http://127.0.0.1:8765/?t=<one-time-token>

commit-guard gui --no-open
commit-guard gui --port 0
commit-guard gui --report-only --report-path out/report.html

The console includes overview, scan controls, determinant profile/file/rule selection, policy gate, triage, pipelines, fix preview/apply, report PRs, baseline management, Git operations, rule inspection, an in-app profiles guide, reports, maintenance, and a validated config editor.

CommitGuard local control center

The loopback control center (shown in v3.1.0; v3.4.2 keeps the same layout).

Security defaults: binds to 127.0.0.1, requires a per-run token, validates the Host header, caps request bodies, keeps secrets redacted, and runs pipelines without a shell inside the repository. Hooks and CI never start the GUI.

Privacy Model

  • No telemetry. CommitGuard does not phone home, collect usage data, or call an LLM by default.
  • Local-first AI. commit-guard ai builds deterministic, redacted context packages locally; remote providers require --allow-network and explicit configuration.
  • No source upload. A normal scan reads the local index, working tree, or selected reports and writes local output.
  • Explicit network surfaces. --sca-online, GitHub report/PR actions, and rule-pack downloads are opt-in and require your action.
  • Redaction everywhere. Secrets are masked in terminal output, Markdown, JSON, SARIF, HTML, annotations, and the GUI unless you explicitly opt out.
  • Local artifacts. Reports and the GUI stay on your machine; CI uploads are controlled by your workflow.

Read the Threat Model and Security Policy for the full trust boundaries.

CI in One Step

name: CommitGuard

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read
  security-events: write   # only needed for SARIF upload

jobs:
  gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: KynSec/commitguard-kynsec@v3.4.2
        with:
          format: sarif
          scan-mode: all
          gate: true
          policy-profile: balanced
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: commit_guard_reports/report.sarif

Pin the Action to a reviewed tag or commit SHA for production. See CI integrations for GitLab, Jenkins, pre-commit, SARIF, and report-artifact examples.

Performance

The reference benchmark runs 120 files x 20 added lines with a warm rule cache. CI enforces a 2,000 ms median ceiling; recorded medians vary by host and are published in BASELINE.md. First scans after a rule-pack change parse and cache the rules, so they take longer. The cache invalidates automatically when rule files change.

commit-guard scan --staged
commit-guard scan --staged --no-cache   # debugging or read-only environments

Known Boundaries

  • Native detection is intentionally high-signal and reviewable; it is not a claim of complete semantic coverage.
  • Python taint uses conservative cross-file function summaries. Ambiguous helpers with the same name can increase false positives, and arbitrary abstractions, aliases, and sanitizers are still not fully modelled.
  • Interprocedural summaries for JS/TS, Java, and Go are name-based and conservative; Java and Go analysis is syntax-driven, not type-resolved.
  • Native binaries are convenience artifacts, not the canonical signed release.
  • The benchmark leaderboard does not compare against commercial products.
  • Local AI context is review material, not a substitute for human triage.
  • Most Semgrep rules require AST support. CommitGuard executes regex-compatible rules and records AST-only rules as skipped rather than approximating them.
  • Offline SCA depends on the quality and freshness of your local OSV snapshot.
  • A leaked credential must be rotated. Suppression and redaction do not undo exposure.

Documentation

Guide Start here for
Configuration Every setting, default, profile, and precedence rule.
Policy Gates, budgets, ratchets, triage, and exit codes.
Rules Native schema, rule packs, context windows, selection, and validation.
Scan profiles Determinant file/rule selections in rules/scan_profiles.yaml, CLI/GUI usage, and PyPI packaging.
Interoperability SARIF/native ingestion and report merging.
Ecosystem SBOM, licenses, dashboard, watch, LSP, compliance, quarterly audits, plugins, signed rule packs, AI evaluation, native binaries, and the benchmark leaderboard.
Governance Roles, decision making, maintainer continuity, and release rotation.
Maintainers Current role assignments and responsibilities.
Security response Incident runbook, severity targets, and maintainer-absence handoff.
Phase 4 exit Deliverable and exit-criterion evidence, reproduction commands, and known limits.
CI GitHub Actions, GitLab, Jenkins, and pre-commit.
GitLab MR summaries, inline suggestions, and signed offline snapshots.
Benchmarks Benchmark card, fixed-commit accuracy corpus, and limitations.
Releasing Signed artifacts, offline verification, zipapp, and container image.
Architecture Scan flow, modules, caching, and tradeoffs.
Threat Model Assets, adversaries, controls, and abuse cases.
Troubleshooting Hooks, paths, caches, and false positives.
Support Support guide, evidence bundle, triage matrix, and escalation.
Upgrade Guide Schema 2 / 2.x to schema 3 / 3.x.
Contributing Development setup, tests, DCO, and rule contributions.
Changelog Release history and notable changes.

License

Apache-2.0. See LICENSE, NOTICE, and THIRD_PARTY_NOTICES.md.


Author & Lead Maintainer

CommitGuard is created, designed, and led by Amr Khaled Ahmed.

Lead Author & Creator Amr Khaled Ahmed (Amr Eldhshan)
GitHub Profile @Amr-Khaled-Ahmed
Email amr171516@gmail.com
Official Organization CommitGuard Security (@KynSec)
Official Repository github.com/KynSec/commitguard-kynsec

For security reports, follow SECURITY.md. For bugs and feature requests, use the official issue tracker.

Metadata

Release files for commitguard-kynsec 3.4.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for commitguard-kynsec 3.4.2
File Size Uploaded Provenance Actions
commitguard_kynsec-3.4.2.tar.gz 473.6 kB With provenance Details for commitguard_kynsec-3.4.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for commitguard-kynsec 3.4.2
File Interpreter ABI Platform Actions
commitguard_kynsec-3.4.2-py3-none-any.whl Python 3 none any Details for commitguard_kynsec-3.4.2-py3-none-any.whl

Total release size: 923.6 kB

Release files / commitguard_kynsec-3.4.2.tar.gz

Download URL commitguard_kynsec-3.4.2.tar.gz
Size 473.6 kB
Tags Source
SHA-256 checksum
How to use checksums
40ee44083f2ea3a69df3838de8d097409da95a692c31658be3d216d152af2151
BLAKE2b-256 checksum
How to use checksums
cf2bee907dd6376f4321d27dcbfdbb5c6cf173a0e3d93fa57ff3d02cf1fdafef
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / commitguard_kynsec-3.4.2-py3-none-any.whl

Download URL commitguard_kynsec-3.4.2-py3-none-any.whl
Size 450.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
37c70a022360fa901bd4e1895d6a61fd1de51fb9af721d95ea5035f2ff58a3b2
BLAKE2b-256 checksum
How to use checksums
2a0101acd210c5fd33584a0a45f059bfa40b15db8210b490ff24496b150db062
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for commitguard-kynsec 3.4.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for commitguard_kynsec-3.4.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.4.2 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page