sentra 0.1.0

Deterministic safety gate for code changes

Sentra

A CLI tool that analyzes git diffs and decides whether a PR is safe to merge.

Installation

pip install -e .

Or install directly:

python -m pip install .

Usage

Basic Scan

sentra scan

This compares your current branch against main (default base branch).

Custom Base Branch

sentra scan --base develop

Show Banner

Display the optional ASCII banner (enterprise users prefer clean by default):

sentra scan --banner

Generate PR Comment

Generate a formatted PR comment (markdown) for posting to pull requests:

sentra scan --pr-comment

This outputs a professional, human-readable comment that satisfies three audiences:

• Developer: Clear action items
• Lead/Manager: Risk assessment
• CI: Deterministic signal

The comment includes confidence breakdowns when confidence < 80%, making Sentra defensible in audits.

Theming

Sentra uses a professional purple theme (#9D4EDD) for brand identity. Colors are applied semantically:

• Purple: Headers, decisions, highlights (brand identity)
• Green: ALLOW decisions (success)
• Yellow: WARN decisions (warning)
• Red: BLOCK decisions (error)
• Grey: Secondary text (muted)

Color Control

Sentra respects enterprise standards:

• NO_COLOR: Automatically disables colors when NO_COLOR=1 is set
• JSON output: No colors, no emojis (--json flag)
• CI-safe: Clean output for automation

# Disable colors
NO_COLOR=1 sentra scan

# JSON output (always no colors)
sentra scan --json

Exit Codes

Decision	Exit Code	Meaning
ALLOW	0	Safe to merge
WARN	0	Review recommended (allowed to merge)
BLOCK	1	Merge blocked (requires manual review)

CI/CD pipelines can use these exit codes to automatically block or warn on PRs. This makes Sentra predictable for enterprises.

Safety Rules

The tool checks for:

1. Sensitive File Detection - Flags changes to security, auth, gateway, config files (MEDIUM → HIGH risk)
2. Cross-Service Changes - Detects changes across multiple services or shared modules (MEDIUM risk)
3. Infrastructure Changes - Flags port, Eureka, env var, Docker, CI file changes (HIGH risk)
4. Large AI-Style Diffs - Detects many files, large blocks, repeated patterns (MEDIUM risk)
5. Test Coverage - Warns if production code changed without tests (MEDIUM risk)

Policy Packs

Create a policy.yaml file in your repo root to customize enforcement:

version: 1

defaults:
  allow_severity: LOW
  block_severity: HIGH

paths:
  auth/:
    block_severity: MEDIUM

rules:
  INFRA_CHANGE:
    always_block: true

AI Escalation (Optional)

Enable AI escalation via environment variables:

export OPENROUTER_API_KEY=sk-xxxx
export AI_ESCALATOR_ENABLED=true
export AI_ESCALATOR_MODEL=mistralai/devstral-2-2512:free

AI can only escalate MEDIUM → HIGH/CRITICAL. It never downgrades or decides.

Example Output

{
  "decision": "BLOCK",
  "confidence": 0.9,
  "reasons": [
    {
      "rule_id": "INFRA_CHANGE",
      "severity": "HIGH",
      "message": "Infrastructure configuration modified",
      "files": ["test_config/application.yml"]
    }
  ],
  "metadata": {
    "changed_files": 2,
    "affected_areas": ["auth", "config"],
    "base_branch": "main",
    "ai_escalation": "enabled",
    "policy_applied": true,
    "policy_file": "policy.yaml",
    "policy_version": 1
  }
}

CI Integration

GitHub Actions

See .github/workflows/sentra.yml for a complete example.

- uses: ./.github/actions/sentra
  with:
    base_branch: main

GitLab CI

See .gitlab-ci.yml for configuration.

Jenkins

See Jenkinsfile for pipeline configuration.

Docker

Build and run:

docker build -t sentra .
docker run \
  -e OPENROUTER_API_KEY=$OPENROUTER_API_KEY \
  -e AI_ESCALATOR_ENABLED=true \
  -v $(pwd):/scan \
  sentra scan --base main

Or use docker-compose:

docker-compose run sentra

Development

# Run locally
python cli.py scan

# Run with custom base
python cli.py scan --base develop

Failure Scenarios

Scenario	Result
No policy.yaml	Defaults apply
No AI key	AI skipped
Git missing	BLOCK (exit 1)
AI timeout	AI skipped
Network down	AI skipped
Policy syntax error	Defaults apply

CI must never hang.