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).

Sentinel does not depend on cryptographic algorithms or modes with known serious weaknesses. HMAC-SHA256 (not SHA-1) is used for JWT signing. bcrypt (not PBKDF2-SHA1) is used for password hashing. TLS connections via httpx/Python's ssl module negotiate modern cipher suites (AES-GCM, ChaCha20-Poly1305) — not CBC mode. No SSH protocol is implemented. The project exclusively uses algorithms considered secure by current standards (NIST SP 800-131A).

Sentinel uses cryptographic algorithms in two areas, both supporting alternatives:

• Password hashing: uses bcrypt (via the bcrypt library) with configurable work factor. The passlib-compatible approach allows switching to alternative algorithms (argon2, scrypt) if bcrypt is compromised
• JWT signing: uses HMAC-SHA256 (HS256) via PyJWT, which supports multiple algorithms (HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512) — switching is a configuration change
• TLS: relies on Python's ssl module and the system OpenSSL library, which supports multiple cipher suites and can be configured to exclude broken algorithms

No custom cryptographic implementations exist in the codebase — all crypto is delegated to well-maintained FLOSS libraries (bcrypt, PyJWT, OpenSSL). See docs/conventions.md (https://github.com/StayPirate/sentinel/blob/master/docs/conventions.md) (Secret Field Typing) and docs/features/identity/authentication.md (https://github.com/StayPirate/sentinel/blob/master/docs/features/identity/authentication.md).

Sentinel stores all authentication credentials and cryptographic keys in environment variables, separate from application code, configuration files, and logs:

• JWT secret key: JWT_SECRET_KEY environment variable, typed as SecretStr in config.py to prevent accidental exposure via repr/logging
• Database password: embedded in DATABASE_URL environment variable, with Field(..., repr=False) to hide from repr
• Redis credentials: embedded in REDIS_URL environment variable, with Field(..., repr=False)
• IBS password: IBS_PASSWORD environment variable, typed as SecretStr
• NVD API key: NVD_API_KEY environment variable, typed as SecretStr
• RabbitMQ credentials: IBS_RABBITMQ_URL environment variable, with Field(..., repr=False)

All credentials can be updated without code recompilation (Python is interpreted) and without rebuilding the container image — changing the environment variable value is sufficient. Secrets are never baked into images or committed to the repository (enforced by GitHub Secret Scanning + Push Protection). See docs/conventions.md (https://github.com/StayPirate/sentinel/blob/master/docs/conventions.md) (Secret Field Typing) and docs/configuration.md (https://github.com/StayPirate/sentinel/blob/master/docs/configuration.md).

Sentinel supports secure protocols for all network communications and does not enable insecure protocols by default:

• API server: serves over HTTPS; TLS configuration is handled at the deployment layer (reverse proxy / load balancer)
• External service integrations: all HTTP clients (IBS, SMELT, AIMAAS, NVD, MITRE, Bugzilla, etc.) use HTTPS exclusively. The networking infrastructure (docs/features/platform/networking.md) configures TLS with certificate verification enabled by default
• Database: connects to PostgreSQL via asyncpg, which supports TLS connections (sslmode parameter in DATABASE_URL)
• Redis: connects via REDIS_URL, which supports rediss:// (TLS) scheme
• RabbitMQ: connects via IBS_RABBITMQ_URL, which supports amqps:// (TLS) scheme
• Git transport: git-based fetchers clone via HTTPS
• No insecure defaults: no HTTP, FTP, telnet, or unencrypted protocols are used in application code. Plain HTTP is only accepted for local development (CORS_ORIGINS may include http://localhost:*)

See docs/features/platform/networking.md (https://github.com/StayPirate/sentinel/blob/master/docs/features/platform/networking.md) and docs/data-sources.md (https://github.com/StayPirate/sentinel/blob/master/docs/data-sources.md) for the full external service catalog and protocol details.

Sentinel's TLS configuration supports TLS 1.2 and later:

• Python runtime: Python 3.13's ssl module uses OpenSSL's default minimum protocol version, which is TLS 1.2 on all modern distributions (TLS 1.0 and 1.1 were deprecated in OpenSSL 1.1.1 and disabled by default in OpenSSL 3.x)
• HTTP clients: the httpx library (used for all external service integrations) uses Python's ssl module, which enforces TLS 1.2+ by default
• Database: asyncpg TLS connections negotiate TLS 1.2+ via the system OpenSSL
• Redis/RabbitMQ: TLS connections via rediss:// and amqps:// schemes use Python's ssl module, defaulting to TLS 1.2+
• Custom TLS context: the networking infrastructure (docs/features/platform/networking.md) supports configurable TLS contexts with certificate verification enabled by default, using the system trust store

TLS versions prior to 1.2 (SSL 2.0, SSL 3.0, TLS 1.0, TLS 1.1) are disabled by the underlying OpenSSL library in the Python 3.13 base image (python:3.13-slim).

Sentinel performs TLS certificate verification by default on all outgoing connections:

• HTTP clients: the httpx library verifies TLS certificates by default using the system trust store (certifi). The networking infrastructure (docs/features/platform/networking.md) configures TLS with verify=True as the default — disabling verification requires explicit configuration
• Database: asyncpg TLS connections verify certificates when sslmode=verify-ca or sslmode=verify-full is configured in the DATABASE_URL
• Redis: Python redis library verifies TLS certificates by default when using rediss:// scheme
• RabbitMQ: aio-pika verifies TLS certificates by default when using amqps:// scheme
• Git transport: HTTPS clones via git verify server certificates by default (OpenSSL/system trust store)
• Internal CA support: for SUSE internal services using an internal CA, the project supports configuring a custom CA bundle (REQUESTS_CA_BUNDLE / SSL_CERT_FILE) rather than disabling verification

No connection in the codebase disables certificate verification by default. See docs/features/platform/networking.md (https://github.com/StayPirate/sentinel/blob/master/docs/features/platform/networking.md) for TLS configuration details.

Sentinel's TLS implementation ensures certificate verification completes before any private data is transmitted. This is inherent in how the underlying libraries operate:

• httpx: the TLS handshake (including certificate verification) completes during connection establishment, before any HTTP headers (including cookies, authorization tokens, API keys) are sent. This is enforced by the TLS protocol itself — the HTTP layer cannot transmit data until the TLS session is established and verified
• asyncpg: database connection authentication credentials are sent only after the TLS handshake succeeds
• aio-pika / Redis: AMQP and Redis authentication credentials are transmitted only after TLS negotiation completes

Sentinel transmits private information (JWT tokens, API keys, IBS/NVD credentials) exclusively over HTTPS connections where certificate verification is the default. The TLS protocol guarantees that verification precedes any application-layer data exchange — no application-level ordering logic is needed because the transport layer enforces it.

Sentinel validates all inputs from untrusted sources using allowlist-based validation at multiple layers:

• API input validation: all request bodies are validated via Pydantic schemas (backend/app/schemas/) with strict type checking, field constraints, and allowed value enumerations before reaching service logic. Invalid inputs are rejected with 422 VALIDATION_ERROR responses
• Query parameter validation: a shared dependency enforces a 500-character string parameter length limit across all endpoints (docs/api-spec.md). Enum-typed query parameters (status filters, sort fields) only accept explicitly defined values
• Username validation: allowlist pattern — must match [a-z0-9._-], 1-64 characters, start with a letter. Enforced at every entry point (API, CLI)
• Password validation: domain-specific policy validation (PasswordValidationError) before storage
• CVE identifiers: validated against the CVE-YYYY-NNNNN+ format pattern
• Database-level constraints: CHECK constraints enforce valid enum values for state-machine columns (ticket status, audit event types). VARCHAR(N) length limits on all string columns
• External data ingestion: fetchers that ingest data from external sources (NVD, MITRE, GHSA, OSV, etc.) validate and normalize incoming data before database storage (e.g., ecosystem normalization to OSSF canonical values, CVSS score validation)
• Path/identifier parameters: UUID and username resolution validates format before database lookup, rejecting malformed identifiers early

See docs/api-spec.md (https://github.com/StayPirate/sentinel/blob/master/docs/api-spec.md) and docs/conventions.md (https://github.com/StayPirate/sentinel/blob/master/docs/conventions.md) (Username Format, Pydantic Conventions).

Sentinel employs multiple hardening mechanisms to reduce the likelihood that software defects result in security vulnerabilities:

• Memory-safe language: Python is memory-safe by design — no buffer overflows, use-after-free, or memory corruption
• Strict static type checking: mypy --strict is a mandatory CI gate, catching type errors, unhandled None values, and forgotten await calls before production
• SQL injection prevention: all database queries use SQLAlchemy's parameterized query API — no raw SQL string concatenation
• Input validation at boundaries: Pydantic schemas reject malformed input before business logic; database CHECK constraints provide defense-in-depth
• Secret masking: SecretStr type prevents accidental credential exposure in tracebacks, logs, and repr output
• SAST: bandit detects common Python security anti-patterns (hardcoded passwords, eval, insecure deserialization) in CI
• SCA: pip-audit blocks dependencies with known vulnerabilities pre-merge
• Container scanning: Trivy scans the Docker image for OS and library vulnerabilities
• Least-privilege CI: workflows default to permissions: read-all; jobs escalate only specific permissions needed
• Secret scanning: GitHub Secret Scanning with Push Protection prevents accidental credential commits
• Pessimistic locking: centralized mutation modules use SELECT ... FOR UPDATE to prevent race conditions
• No custom cryptography: all crypto delegates to vetted FLOSS libraries (bcrypt, PyJWT, OpenSSL)

These mechanisms are documented across docs/conventions.md (https://github.com/StayPirate/sentinel/blob/master/docs/conventions.md), docs/architecture.md (https://github.com/StayPirate/sentinel/blob/master/docs/architecture.md), and docs/deployment.md (https://github.com/StayPirate/sentinel/blob/master/docs/deployment.md) (CI Pipeline).

bandit is specifically designed to find common security vulnerabilities in Python code (SQL injection, hardcoded passwords, insecure use of subprocess, weak cryptographic algorithms, etc.). It runs as part of the "Backend Security Scan" CI gate on every PR. Additionally, pip-audit scans dependencies against known vulnerability databases (OSV, PyPI advisory DB). Both tools are FLOSS and target security-specific weaknesses beyond general code quality.

Sentinel is written entirely in Python (a memory-safe language). Its dependencies include some C/Rust extensions (asyncpg, pydantic-core, bcrypt), but these are third-party libraries maintained by their own projects with their own testing — Sentinel does not produce or modify memory-unsafe code. This criterion does not apply.