coditation-sentinel 0.1.0

Local-first git commit guardrails: block secrets, forbidden files, and disallowed git identities before they are committed.

Coditation Sentinel

Local-first git commit guardrails. Sentinel installs a global git hook that runs on every git commit, in every repository on the machine, and blocks the commit before anything leaves the laptop when it finds:

• 🔑 Secrets — API keys, tokens, private keys (via gitleaks)
• 📄 Forbidden files — .env, *.pem, *.key, keystores, dumps, …
• 🧑‍💻 Disallowed git identity — commits authored with a personal email

It is built for a services company: developers commit to customer repositories whose remotes and CI we may not control, so enforcement lives on the developer's machine and never writes anything into the customer's repo.

How it works

git commit
   │  git runs the global hook → sentinel scan --staged
   ▼  (scans only the staged diff, so commits stay fast)
 secrets? · forbidden file? · git identity?
   │
 clean → commit proceeds      problem → friendly message + fix, commit aborted

The hook is wired via git config --global core.hooksPath, so a single install covers every repo automatically — nothing per-project, nothing added to customer code.

Git identity — three tiers

Identity	Example	Behavior
Company	[e-mail]	✅ silent pass
Customer / corporate	[e-mail]	⚠️ allowed — shown once per repo, recorded locally
Personal	@gmail.com, @outlook.com, …	❌ always blocked

We don't allow-list customer domains (impossible to maintain). Instead policy.yaml keeps a deny-list of personal providers; the company domain passes, personal is blocked, and everything else is treated as a legitimate customer identity.

Install

Quick install (recommended) — one-shot scripts

Hand a developer the script for their OS from runner/. It ensures Python 3.11, installs Sentinel into an isolated virtualenv, installs gitleaks, and wires the global git hook — no manual steps.

OS	Run
macOS	bash runner/run-macos.sh
Ubuntu / Debian	bash runner/run-ubuntu.sh
Windows	powershell -ExecutionPolicy Bypass -File runner/run-windows.ps1

Open a new terminal afterwards so the PATH change applies. Override the install source or versions via SENTINEL_PACKAGE, PYTHON_VERSION, GITLEAKS_VERSION (see runner/README.md). Prerequisite: git, plus a package manager (Homebrew / apt / winget) so Python 3.11 can be installed if missing.

Manual install

pip install coditation-sentinel      # (or: pip install -e . from a checkout)
sentinel install                     # sets global core.hooksPath + writes default policy
brew install gitleaks                # required for secret scanning (macOS)
sentinel status                      # verify enforcement + gitleaks

Commands

Command	Purpose
sentinel install [--force]	Install the global hook and default policy
sentinel scan --staged	Scan staged changes (this is what the hook calls)
sentinel status	Show enforcement status, policy source, gitleaks version
sentinel uninstall	Remove the hook and revert core.hooksPath

Configuration

Policy lives at ~/.coditation-sentinel/policy.yaml (a copy of the packaged default). Edit it to adjust company domains, the personal-provider deny-list, and forbidden-file patterns. gitleaks rules live alongside it in gitleaks.toml.

A metadata-only log of non-Coditation identities used is kept at ~/.coditation-sentinel/identity-usage.log (timestamp, repo, email — never code).

Scope (Phase 1)

In: secrets, forbidden files, three-tier identity, global hook, CLI. Out (later): dependency/IaC scanning, PII detection, MDM/device enforcement, central dashboards. The local hook is the guarantee; server-side CI is intentionally not relied on.

Development

python3 -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest