repo-sentinel-lite

Deterministic Python CLI for repository hygiene checks, lightweight secret-adjacent scanning, and baseline-backed pre-commit validation.

repo-sentinel-lite scans a repository and emits stable JSON for:

• suspicious filenames such as .env, *.pem, id_rsa, and *.kdbx
• high-entropy strings that look like secrets
• structured secret-adjacent patterns such as PEM private-key headers, GitHub-token-like prefixes, AWS access-key-like prefixes, and generic token= or api_key= assignment contexts
• missing standard files such as README.md, LICENSE, and .gitignore

It also supports .reposentinel.toml overrides, scoped allowlists, JSON baselines for suppressing known findings, baseline drift audits, changed-file scans, and a pre-commit provider for repository-local enforcement. Token-like values are redacted in CLI output and generated baselines by default.

The detector set is intentionally heuristic. A clean scan is useful repository hygiene evidence, not proof that no credential exists in the repository or its history.

Install

Install from production PyPI:

python -m pip install repo-sentinel-lite

Requires Python 3.11 or newer.

Usage

More copy-pasteable CLI workflows are in docs/cli-recipes.md. For the shortest consumer setup path, see docs/consumer-minimal-setup.md. For baseline review expectations and a sample baseline, see docs/baseline-review.md. For output stability and CI artifact guidance, see docs/output-format-stability.md. For pre-commit provider setup, see docs/pre-commit-integration.md. For threat model boundaries and non-goals, see docs/threat-model.md. For the v0.8 synthetic performance envelope, see docs/performance-envelope-v0.8.md. For self-dogfooding status, see docs/self-dogfooding.md. For the short external case study, see How repo-sentinel-lite Dogfoods Repository Hygiene. For near-term review boundaries, see ROADMAP.md. For before-and-after scanner examples, see examples/. The v0.7 adoption plan is tracked in docs/v0.7-adoption-release.md. Release notes for v0.7.1 are tracked in docs/release-notes-v0.7.1.md. Release notes for v0.8.0 are tracked in docs/release-notes-v0.8.0.md.

Scan the current repository. This defaults to deterministic JSON output:

repo-sentinel scan

Emit deterministic JSON explicitly for a specific path:

repo-sentinel scan --format json path/to/repo

Render a concise text summary for a specific path:

repo-sentinel scan --format text path/to/repo

Scan a specific path and save a baseline:

repo-sentinel scan --write-baseline baseline.json path/to/repo

Scan with an existing baseline applied:

repo-sentinel scan --baseline baseline.json path/to/repo

Audit baseline drift without suppressing the classification output:

repo-sentinel baseline audit --baseline baseline.json path/to/repo

If the scanned repository already contains .reposentinel-baseline.json, repo-sentinel scan applies it automatically.

Temporarily scan without the repository-root default baseline:

repo-sentinel scan --no-default-baseline path/to/repo

Fail with exit code 1 when unsuppressed findings remain:

repo-sentinel scan --fail-on-findings path/to/repo

Reveal full high-entropy tokens only when you explicitly need to inspect them:

repo-sentinel scan --reveal-secrets path/to/repo

Use a .reposentinel.toml config to ignore paths or adjust thresholds:

ignore_globs = ["dist/**", ".venv/**"]
entropy_threshold = 4.2
max_text_file_size = 1048576

[allowlist]
paths = ["fixtures/**"]
rules = ["repo.suspicious_filename"]
token_hashes = ["sha256:3eb1bd439947"]

Use rule_id values from JSON findings when writing rule-scoped allowlists.

Child-glob ignores such as fixtures/*, fixtures/**, and fixtures/**/* prune the matching directory during traversal.

Common generated and dependency directories such as .venv, venv, .venv-*, node_modules, dist, dist-*, build, .tox, .nox, .pytest_cache, .ruff_cache, .mypy_cache, *.egg-info, coverage, htmlcov, and __pycache__ are ignored by default. Text files larger than max_text_file_size bytes are skipped for high-entropy content scanning by default.

For pre-commit or local review paths that already know the changed files, scan only those files while keeping repository-level required-file checks:

repo-sentinel scan --changed-files path/to/repo src/app.py docs/example.md

Local development

Use Python 3.11 or newer, then run:

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
python -m pytest -q
ruff check .

These commands match the GitHub Actions CI workflow: .github/workflows/ci.yml