sentinel

The project uses Alembic database migrations with a forward-migration path — each release includes migration scripts that upgrade the database schema from any previous version to the current one (alembic upgrade head). The deployment documentation (https://github.com/StayPirate/sentinel/blob/master/docs/deployment.md) covers migration procedures and the SemVer policy in conventions (https://github.com/StayPirate/sentinel/blob/master/docs/conventions.md) clearly defines what constitutes a breaking change (MAJOR bump). The project is pre-1.0, where breaking changes may occur in minor bumps — consumers are advised to pin exact versions. Release changelogs (generated by release-please) document all changes between versions, and the API versioning strategy (/api/v1/) ensures backward compatibility within a major version.

The project uses GitHub Issues as its issue tracker. Every substantive change is tracked by an issue (enforced by pr-metadata.yml which requires Closes #N or N/A - <reason> in every PR body). Issue templates ("Work item" form) are configured for structured reporting. Issues track bugs, features, documentation changes, and CI/CD improvements with labels, direct blockers, and linkage to owning specifications.

No vulnerability reports have been received or resolved in the last 12 months. The project has had no reported security vulnerabilities since its creation.

SECURITY.md (https://github.com/StayPirate/sentinel/blob/master/SECURITY.md) documents the complete vulnerability response process: private reporting via security@suse.com, acknowledgment within 5 business days, initial assessment within 15 business days, coordinated disclosure timeline with the reporter, and the commitment to issue security advisories with fixes. GitHub's Private Vulnerability Reporting is also enabled as an alternative intake channel.

CONTRIBUTING.md (https://github.com/StayPirate/sentinel/blob/master/CONTRIBUTING.md) references the project's coding conventions, and docs/conventions.md (https://github.com/StayPirate/sentinel/blob/master/docs/conventions.md) is the comprehensive coding style guide. It covers Python style (ruff format + ruff check, line length, quotes, imports, naming), type hints (strict mypy), FastAPI conventions, SQLAlchemy conventions, Pydantic conventions, CLI conventions, shell scripting (shellcheck + shfmt), git/commit conventions, and specification writing standards. Compliance is enforced automatically in CI via ruff, mypy --strict, shellcheck, shfmt, and actionlint.

Coding style is automatically enforced in CI (.github/workflows/ci.yml):

• Python formatting: ruff format --check . — fails the build if code is not formatted per the project's black-compatible style
• Python linting: ruff check . — enforces import sorting, naming conventions, and style rules
• Python type checking: mypy --strict — enforces type annotations on all function signatures
• Shell formatting: shfmt -d -i 4 -ci — fails the build if shell scripts are not formatted per project conventions
• Shell linting: shellcheck — enforces shell scripting best practices
• Workflow linting: actionlint — validates GitHub Actions workflow syntax and embedded shell

The pre-commit hook (.githooks/pre-commit) also runs ruff, shellcheck, and shfmt locally before commits reach CI. All tools are FLOSS.

Sentinel is a pure Python application — no native binaries are compiled during the build process. The Dockerfile installs Python wheels (pre-built or pure-Python) via uv pip install. No C/C++ compiler or linker is invoked.

Sentinel is a pure Python application with no compiled artifacts. The build process (uv pip install / uv sync) installs Python packages — there are no native binaries to strip or preserve debugging information for.

Sentinel is a pure Python application. The build process uses uv pip install / uv sync with a single pyproject.toml — there is no recursive subdirectory build system and no cross-dependency resolution between subdirectories.

Sentinel is a pure Python application — the source code is interpreted directly, not compiled into binary artifacts. The Docker image build involves installing Python packages from a lockfile (uv.lock), but the application itself has no compilation step that would produce bit-for-bit reproducible build artifacts.

Sentinel provides standard installation mechanisms:

• Python package: installable via uv pip install . or pip install . using the standard pyproject.toml with declared dependencies and a console script entry point (sentinel). Uninstall via uv pip uninstall sentinel or pip uninstall sentinel
• Docker image: installable via docker pull / podman pull from the container registry. Uninstall by removing the container and image (docker rmi)
• Development setup: uv sync creates a virtualenv with the project installed in editable mode, following Python ecosystem conventions

Sentinel is a pure Python application installed via pip / uv pip into a Python environment (virtualenv or system site-packages), which follows Python's own installation conventions (not POSIX DESTDIR). The production deployment is containerized (Docker/Podman) where the concept of DESTDIR does not apply — the image is the installation unit. There is no make install or similar POSIX installation target.

CONTRIBUTING.md provides step-by-step build instructions: install uv, run uv sync (which automatically downloads the correct Python 3.13 interpreter and all dependencies from the lockfile), start infrastructure via ./scripts/dev-env.sh up, run migrations, and launch the server. docs/deployment.md documents the production build process (multi-stage Dockerfile with uv sync --frozen), required infrastructure (PostgreSQL, Redis), and the software requirements table listing all runtime dependencies with minimum versions. [osps_do_07_01]

backend/pyproject.toml (https://github.com/StayPirate/sentinel/blob/master/backend/pyproject.toml) lists all external dependencies in the standard Python [project.dependencies] format, which is computer-processable by pip, uv, and any PEP 621-compliant tool. Additionally, backend/uv.lock (https://github.com/StayPirate/sentinel/blob/master/backend/uv.lock) pins exact versions of all transitive dependencies in a machine-readable lockfile.

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. [osps_vm_05_03]

backend/pyproject.toml declares all direct Python dependencies under [project.dependencies]. uv.lock is committed to the repository as a lockfile pinning exact resolved versions (including transitive dependencies). [osps_qa_02_01]

Sentinel actively avoids deprecated and obsolete APIs:

• Python: targets Python 3.13 (current stable). Uses datetime.now(UTC) instead of the deprecated datetime.utcnow(). Uses SQLAlchemy 2.0 style (mapped_column, declarative base) instead of the legacy 1.x API. Uses Pydantic v2 (model_config = ConfigDict(...)) instead of the deprecated v1 class Config
• Dependencies: Dependabot is configured (.github/dependabot.yml) for weekly updates across Python (uv), GitHub Actions, and Docker ecosystems, keeping the stack current
• CI enforcement: ruff check flags usage of deprecated Python standard library APIs (via pyupgrade and pyflakes rules), and pip-audit flags dependencies with known vulnerabilities (which often correlate with obsolescence)

The CI pipeline (ci.yml) runs on every pull request targeting master and includes a full automated test suite: uv run pytest executes 850+ unit and integration tests. Branch protection requires the "Backend Tests" status check to pass before merge — no commit reaches master without the test suite passing. [osps_qa_06_01]

Sentinel's development workflow requires regression tests for all bug fixes — this is enforced by project conventions (AGENTS.md Guardrail 6: "Bug fixes: add a regression test that reproduces the bug") and verified by @test-reviewer invocations on bug fix PRs. The CI pipeline runs 850+ tests (uv run pytest) as a required status check before any PR can merge. All fix: commits in the last six months include corresponding regression tests in backend/tests/.

Sentinel uses pytest-cov (https://github.com/pytest-cov/pytest-cov) (a FLOSS tool) to measure statement coverage, with results uploaded to Codecov (https://app.codecov.io/) on every CI run. The project currently has 850+ tests achieving high statement coverage. The CI pipeline (.github/workflows/ci.yml) runs uv run pytest --cov and the Codecov badge is displayed in the README (https://github.com/StayPirate/sentinel/blob/master/README.md).

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. [osps_qa_06_03]

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. [osps_qa_06_03]

The project applies maximally strict settings where practical: mypy --strict enables all optional strictness flags (no implicit Optional, disallow untyped defs, disallow any generics, warn return any, etc.). ruff check runs with a broad rule set covering multiple linting categories. bandit runs without severity filters (all findings block). shellcheck runs without suppressed categories. The only permitted relaxations are narrowly-scoped, per-line suppressions with mandatory justification comments — blanket disables and file-level suppressions are forbidden by convention.

Sentinel implements secure design principles throughout its architecture:

• Least privilege: capability-based RBAC with per-endpoint authorization checks (require_capability()); CI workflows default to permissions: read-all; database roles scoped to required operations
• Defense in depth: input validation at multiple layers (Pydantic schemas, SQLAlchemy constraints, CHECK constraints); SAST (bandit), SCA (pip-audit), and static type checking (mypy --strict) all enforced in CI
• Fail-safe defaults: new users have no capabilities until roles are assigned; API endpoints deny access unless the required capability is explicitly granted; strict mode branch protection on master
• Complete mediation: all mutations go through centralized service modules (user_service, ticket_mutations, package_service) — direct model manipulation from API handlers is forbidden by architecture
• Separation of privilege: authentication (JWT + API keys) is separate from authorization (capability checks); credential kind is tracked via AuthenticatedPrincipal
• Economy of mechanism: single Docker image for all process roles; single source of truth in PostgreSQL; async-only database layer eliminates an entire class of sync/async mixing bugs
• Open design: the security model is fully documented in specifications (rbac.md, authentication.md, SECURITY.md); no security through obscurity
• Psychological acceptability: password policy uses bcrypt with configurable rounds; API error responses use consistent envelope format with actionable error codes

These principles are documented across docs/architecture.md (https://github.com/StayPirate/sentinel/blob/master/docs/architecture.md), docs/conventions.md (https://github.com/StayPirate/sentinel/blob/master/docs/conventions.md), and the feature specifications in docs/features/identity/ (https://github.com/StayPirate/sentinel/tree/master/docs/features/identity).