sentinel

Every workflow declares permissions at either the top level or per-job, restricted to the minimum required for that specific activity. Examples: ci.yml uses only contents: read; build-images.yml grants packages: write only to the publish job; deploy-api-docs.yml splits permissions per job (contents: read for build, pages: write + id-token: write only for the deploy job); release-please.yml sets top-level permissions: {} and grants contents: write, issues: write, pull-requests: write only to the single job that needs them. The repository default workflow permissions are set to read, ensuring any job without explicit permissions receives the minimum.

All workflows that consume collaborator-controlled input (PR title, PR body, branch names) pass those values exclusively through environment variables (env:) rather than inline ${{ }} interpolation in run: blocks — preventing shell injection. The pr-metadata.yml workflow (the only one that processes attacker-controllable input like PR titles and bodies) explicitly uses env: PR_TITLE: ${{ github.event.pull_request.title }} and then references "${PR_TITLE}" with proper quoting in the shell script. The build-images.yml workflow similarly passes image tags via env: IMAGE_TAGS with an inline comment explaining this is done "to avoid shell-injection risk from untrusted ref/tag content." No workflow interpolates untrusted input directly into a run: script.

Each GitHub Release is associated with its unique version tag (v0.3.0, etc.). The container images published to ghcr.io are tagged with the corresponding semver release tag (e.g., ghcr.io/staypirate/sentinel:0.3.0) alongside latest, ensuring the OCI artifact is clearly tied to the release identifier. The release changelog in the GitHub Release body references the exact Git commits (SHAs) included in that version. The uv.lock file is version-bumped by release-please as part of the release commit, associating the locked dependency set with the release.

The project defines a multi-layered secrets management policy across its documentation:

• Storage: docs/deployment.md (No secrets in workflow files) mandates that CI credentials are stored exclusively in GitHub Secrets (${{ secrets.* }}), never as literals in workflow files. The Repository Secrets section documents each secret's purpose and required permissions.
• Access: docs/conventions.md (Secret Field Typing) requires all secret configuration fields to use Pydantic SecretStr, preventing accidental exposure via repr/logging/serialization. Log statements are forbidden from including secrets (Secrets and PII Discipline in logging.md).
• Rotation: docs/deployment.md documents JWT_SECRET_KEY rotation impact (session invalidation, off-peak maintenance window). Environment-variable injection ensures secrets are never baked into images.
• Prevention: gitleaks pre-commit hook scans for accidentally committed secrets; GitHub Push Protection is enabled at the repository level.

The repository is currently single-maintainer (sole owner of all repository permissions). GitHub's built-in access model requires the repository owner to explicitly grant collaborator access — no one can self-escalate. Branch protection rules enforce PR review requirements for all code reaching master. The CONTRIBUTING.md documents the contribution workflow (fork, PR, CI must pass), and the repository owner is the sole merge authority. For a single-maintainer project, this satisfies the criterion — there is no delegation of sensitive access without the owner's explicit action.

Sentinel is a single-repository project. There is no multi-repo release comprising subprojects — the backend, migrations, task definitions, and specifications all live in this single repository and ship as one OCI image. The frontend will be developed in a separate repository but is not yet released. This criterion does not apply until a release spans mul

docs/features/platform/testing-strategy.md is the authoritative document for the testing strategy, including when and how tests are run. It defines the test pyramid (unit, integration, e2e), the CI pipeline gate composition, required markers (@pytest.mark.unit, @pytest.mark.integration, @pytest.mark.e2e), and execution model. docs/deployment.md (Workflow Inventory) documents that the CI workflow runs on every push to master and every pull request. CONTRIBUTING.md documents how developers run tests locally (make test, uv run pytest). The pre-commit hook automatically runs the unit test subset on every commit.

AGENTS.md (Guardrail 6, Mandatory Testing) defines an explicit policy: "Every code change (new feature or modification) MUST include tests." It requires tests for new API endpoints (happy path, validation, auth), new models (creation, constraints, relationships), new services (business logic, edge cases, error handling), and bug fixes (regression tests). The policy explicitly states "NEVER skip tests" and instructs that if asked to skip, the developer must be reminded of the requirement. CONTRIBUTING.md reinforces this under the "Pull Request Checklist" — all PRs must include tests and CI must pass before merge.

The project performs systematic threat modeling and attack surface analysis through its mandatory @security-reviewer invocations (Guardrail 10) on every security-sensitive change. The docs/reviews/ directory contains 50+ review documents with explicit threat model assessments for critical code paths — authentication (local-authentication.md documents brute-force resistance, offline attack models), networking (networking.md documents trusted-upstream assumptions, connection security), RBAC (rbac.md documents pre-disclosure data exposure), and all external integrations. Specifications themselves document threat considerations inline (e.g., API key self-replication prevention, JWT secret minimum length enforcement, session fixation protections, rate limiting requirements). The attack surface is analyzed per-component rather than in a single monolithic document, with each review recording findings, risk acceptance decisions with rationale, and residual risk.

The CI pipeline enforces a strict gate: pip-audit runs on every pull request and blocks merge if any known-vulnerable dependency is detected (backend-security job in ci.yml). This means no release can be created with a known Python dependency vulnerability — the release path requires CI to pass on master, and release-please.yml only triggers after a successful CI run. Additionally, image-scan.yml runs weekly Trivy scans against the published container image for OS-level vulnerabilities and opens tracking issues. The combination ensures SCA violations are addressed (Python deps) or tracked (OS-level) prior to and between releases.

Every change to the codebase is automatically evaluated by the CI pipeline before merge: pip-audit (in the backend-security job of ci.yml) checks all Python dependencies against known vulnerability databases and blocks the PR if a violation is found. bandit runs static security analysis in the same job. Branch protection requires the "Backend Security Scan" status check to pass — no code reaches master without passing these gates. Dependabot is configured to propose dependency updates weekly, providing proactive notification of vulnerable or outdated dependencies. The suppression mechanism exists via pip-audit's --ignore-vuln flag (though currently unused), which would require explicit declaration of non-exploitability.

All changes to the codebase are automatically evaluated for security weaknesses before merge: bandit (SAST) runs in the backend-security job of ci.yml and blocks the PR on findings. mypy --strict (static type checking) catches type-safety issues that can lead to security weaknesses. Branch protection requires "Backend Security Scan" and "Backend Type Check" to pass — no code reaches master without passing these gates. Suppression is supported via bandit's # nosec inline annotations for declared false positives, and mypy's per-line type-ignore with required error codes (blanket suppressions are forbidden per docs/conventions.md).