coditation-sentinel 0.1.1

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

coditation-sentinel is published on public PyPI, so this needs no credentials:

pip install coditation-sentinel      # from PyPI (or: pip install -e . from a checkout)
sentinel install                     # sets global core.hooksPath + writes default policy
brew install gitleaks                # required for secret scanning (macOS; see gitleaks docs for Linux/Windows)
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 selftest	Verify the hook blocks a bad commit (throwaway repo, auto-deleted)
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

Publishing to PyPI (maintainers)

Automated (recommended) — push a version tag

.github/workflows/publish.yml runs tests, builds, and publishes whenever a v* tag is pushed (the tag must match version in pyproject.toml):

# bump version in pyproject.toml, commit, then:
git tag v0.1.1 && git push origin v0.1.1

This uses PyPI Trusted Publishing (OIDC) — no token stored in GitHub. One-time setup on PyPI: project → Settings → Publishing → Add a trusted publisher: owner rajeshd-coditation, repo coditation-sentinel, workflow publish.yml, environment pypi. (Prefer a token? See the commented alternative in the workflow.)

Manual

. .venv/bin/activate && pip install build twine
# bump `version` in pyproject.toml first (PyPI rejects re-uploading an existing version)
rm -rf dist build *.egg-info && python -m build && twine check dist/*
twine upload dist/*    # auth: __token__ + a PyPI API token

After it lands, pip install coditation-sentinel and the runner/ scripts work with no credentials. The import package is coditation_sentinel; the CLI is sentinel.