sentinel

Repository on GitHub, which provides public git repositories with URLs.

Repository on GitHub, which uses git. git can track the changes, who made them, and when they were made.

The repository uses GitHub Flow with all development on topic branches merged via pull request to master. Every commit and PR is visible between releases — the full development history (interim versions, work-in-progress PRs, review discussions) is public. The repository does not squash history into release-only snapshots; master contains all merged incremental changes between tags (v0.1.0, v0.2.0, v0.3.0), and branches/PRs show the collaborative review process.

Repository on GitHub, which uses git. git is distributed.

Every official release is assigned a unique SemVer identifier (e.g. v0.3.0) via release-please automation. The version source of truth is backend/pyproject.toml; on merge of a Release PR, release-please creates a Git tag (v<major>.<minor>.<patch>) and a corresponding GitHub Release with auto-generated changelog. Tags are never reused or manually created — uniqueness is enforced by Git's tag semantics and the automation's monotonic bump logic. [osps_br_02_01]

Every release is identified by a Git tag (v0.1.0, v0.2.0, v0.3.0) created automatically by release-please upon merge of the Release PR. Tags are immutable (no force-push, no manual tag creation per docs/conventions.md) and each tag has a corresponding GitHub Release with a full changelog.

Non-trivial release notes file in repository: https://github.com/StayPirate/sentinel/blob/master/CHANGELOG.md.

There have been no publicly known run-time vulnerabilities in Sentinel's own code that received a CVE assignment prior to any release. The project is pre-1.0 with no reported security vulnerabilities to date. Dependency vulnerabilities are handled separately (gated by pip-audit in CI), and this criterion applies only to the project's own results, not its dependencies.

Non-trivial SECURITY[.md] file found file in repository: https://github.com/StayPirate/sentinel/blob/master/SECURITY.md. [osps_do_02_01]

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.

The project acknowledges bug reports promptly — issues are tracked in GitHub Issues, and the single maintainer actively triages and responds to submitted issues. The repository shows consistent issue activity with responses, status updates, and closures throughout its active development period. No bug reports have gone unacknowledged.

Enhancement requests submitted as GitHub Issues receive responses from the maintainer — either acknowledgment, discussion, prioritization, or implementation via linked PRs. The project's workflow requires issues for all substantive changes, and the active development cadence demonstrates consistent engagement with feature requests throughout the project's lifetime.

All bug reports, enhancement requests, and their responses are publicly archived in GitHub Issues (https://github.com/StayPirate/sentinel/issues). GitHub Issues provides full-text search, label filtering, and permanent URLs for every report and response. Pull request discussions and review comments are similarly archived and searchable.

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

SECURITY.md (https://github.com/StayPirate/sentinel/blob/master/SECURITY.md) explicitly instructs reporters to email security@suse.com for private vulnerability disclosure. Additionally, GitHub's Private Vulnerability Reporting feature is enabled on the repository, providing a second private channel accessible via the Security tab (https://github.com/StayPirate/sentinel/security/advisories/new).

No vulnerability reports have been received in the last 6 months. The project has not had any security vulnerabilities reported since its creation. This criterion cannot be evaluated without actual vulnerability reports to measure response time against.

Non-trivial build file in repository: https://github.com/StayPirate/sentinel/blob/master/Makefile.

Non-trivial build file in repository: https://github.com/StayPirate/sentinel/blob/master/Makefile.

The entire build toolchain is FLOSS: Python (CPython, PSF license), uv (MIT), ruff (MIT), mypy (MIT), pytest (MIT), SQLAlchemy (MIT), FastAPI (MIT), Celery (BSD), Alembic (MIT), Docker/Podman (Apache 2.0), GitHub Actions runners (open-source runner). No proprietary compiler, build tool, or runtime is required to build, test, or run the project.

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 test suite is invocable using pytest, the standard Python testing framework:

• Standard invocation: cd backend && uv run pytest — the conventional command documented in the project
• Configuration: test settings are defined in backend/pyproject.toml (https://github.com/StayPirate/sentinel/blob/master/backend/pyproject.toml) under [tool.pytest.ini_options], following the standard pytest configuration convention
• CI invocation: the CI pipeline (.github/workflows/ci.yml) invokes the same uv run pytest command with coverage flags
• Markers: tests use standard pytest markers (@pytest.mark.unit, @pytest.mark.integration, @pytest.mark.e2e) for selective execution

URL: https://github.com/StayPirate/sentinel/blob/master/backend/pyproject.tomlard invocation is required.

The project has a comprehensive test suite with 850+ tests covering unit, integration, and e2e levels. Guardrail 6 (Mandatory Testing) enforces coverage requirements: new API endpoints must test happy path, validation errors, and auth/permissions; new models must test creation, constraints, and relationships; new services must test business logic, edge cases, and error handling; bug fixes require regression tests. The CI pipeline uploads coverage reports to Codecov (CODECOV_TOKEN integration in ci.yml), providing visibility into branch and line coverage metrics.

Sentinel implements continuous integration via GitHub Actions. Every push and pull request to master triggers the CI pipeline, which runs the full automated test and analysis suite:

• Linting: ruff check . + ruff format --check .
• Static type checking: mypy --strict
• Security analysis: bandit (SAST) + pip-audit (SCA)
• Shell analysis: shellcheck + shfmt -d + actionlint
• Automated tests: uv run pytest (850+ tests with coverage)
• Container scanning: Trivy image scan
• PR title validation: Conventional Commits format enforcement
• PR metadata validation: issue linkage requirement

Branch protection on master requires 7 status checks to pass before merge. All changes arrive via pull request with squash merge — no direct pushes to master.

URL: https://github.com/StayPirate/sentinel/blob/master/.github/workflows/ci.yml

The project has an explicit, formal policy in AGENTS.md (Guardrail 6, Mandatory Testing): "Every code change (new feature or modification) MUST include tests." The policy specifies required coverage per category (API endpoints, models, services, bug fixes) and states "NEVER skip tests." This is enforced both procedurally (CI requires the test suite to pass) and by convention (PRs without tests are rejected). CONTRIBUTING.md reinforces this requirement in the PR checklist.

Recent merged PRs demonstrate consistent adherence: PR #207 (open-source readiness files) included no code changes requiring tests (cosmetic/documentation — exempt). The most recent feature PRs in the git history all include corresponding test additions — the CI pipeline runs 850+ tests and the pre-commit hook executes the unit test subset on every commit. The backend/tests/ directory mirrors the app/ structure with comprehensive test files for every implemented service, model, and endpoint. Evidence is visible in the commit history where feat: and fix: commits consistently include test additions alongside implementation.

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 enables multiple linting and static analysis tools: ruff check (linter covering hundreds of rules including pyflakes, pycodestyle, isort, and more), ruff format --check (formatter enforcement), and mypy --strict (static type checking in strict mode). All three are mandatory CI gates — "Backend Lint" and "Backend Type Check" must pass before merge. Additionally, bandit runs for security-specific static analysis, and shellcheck lints all shell scripts. These tools are all FLOSS and are enforced on every change via CI and pre-commit hooks.

The CI pipeline is configured to treat all linter and type checker findings as errors (non-zero exit code blocks the PR). ruff check runs with default severity (all warnings are errors), mypy --strict rejects any type error, bandit fails on findings, and shellcheck fails on any shell script warning. Branch protection requires all these checks to pass — unaddressed warnings prevent merge. The project's conventions also forbid blanket suppressions: mypy type-ignore must specify the exact error code, and shellcheck disables must be inline, narrowly scoped, and justified with a comment.

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.

The project demonstrates secure software design knowledge throughout: the architecture implements capability-based RBAC, pessimistic locking for concurrency safety, caller-owned transactions with audit atomicity, secret field typing (SecretStr), CVSS resolution cascades, rate limiting specifications, JWT with configurable secret length enforcement, bcrypt password hashing with tunable cost, session management with liveness tracking, and comprehensive threat modeling in security reviews. The mandatory @security-reviewer guardrail (Guardrail 10) ensures every security-sensitive change is evaluated. The specifications document threat models, attack surfaces, and mitigations for authentication, authorization, and external integrations — indicating the primary developer understands secure design principles (input validation, least privilege, defense in depth, fail-secure defaults).

The project demonstrates awareness of common vulnerability classes and their mitigations throughout the codebase and specifications:

• Injection (SQL, shell, command): SQLAlchemy ORM with parameterized queries; pr-metadata.yml passes user input via env: not inline interpolation; git-based fetchers use asyncio.create_subprocess_exec (not shell=True)
• Broken authentication: bcrypt with tunable cost, JWT minimum secret length enforced at startup, session liveness tracking with Redis, rate limiting on login attempts
• Sensitive data exposure: SecretStr typing, repr=False on credential URLs, logging secrets/PII discipline, gitleaks pre-commit hook, GitHub Push Protection
• Broken access control: capability-based RBAC, require_capability() dependency, confidential ticket filtering, credential-kind restrictions (API key cannot create API keys)
• Security misconfiguration: least-privilege CI permissions, strict CORS, environment-variable secrets (never baked into images)
• XSS/CSRF: API-only backend with JSON responses (no template rendering); CSRF protection via SameSite cookies and origin validation in SSO flow
• Race conditions: pessimistic locking pattern, transaction hygiene rules, no network I/O under locks

The project uses only publicly published, expert-reviewed cryptographic protocols and algorithms: bcrypt (password hashing), HMAC-SHA256 (JWT signing via PyJWT), TLS 1.2+ (external service communication via httpx with system trust store), and OIDC/OAuth2 (SSO authentication). No custom or unpublished cryptographic algorithms are used. The specifications explicitly reference industry standards (RFC 7519 for JWT, OpenID Connect Discovery, bcrypt adaptive cost). The networking.md specification defines TLS trust store layering with standard CA certificate management.

Sentinel does not implement any cryptographic primitives itself. It delegates all cryptography to purpose-built, expert-maintained libraries: bcrypt (password hashing), PyJWT (JWT creation/verification using HMAC-SHA256), httpx with Python's ssl module (TLS), and authlib/OIDC provider libraries (OAuth2/OIDC flows). No hand-rolled encryption, hashing, or key derivation exists in the codebase.

All cryptographic functionality in Sentinel is implemented using FLOSS libraries: bcrypt (Apache 2.0), PyJWT (MIT), cryptography (Apache 2.0/BSD), httpx (BSD) with Python's built-in ssl module (PSF license), and authlib (BSD). No proprietary cryptographic library or module is required. The entire cryptographic stack can be built from source using only open-source tools.

Sentinel's cryptographic defaults meet NIST minimums through 2030:

• JWT signing: HMAC-SHA256 (256-bit key). The application enforces a minimum 32-character JWT_SECRET_KEY at startup (validated in config.py), meeting the 128-bit minimum for symmetric keys.
• Password hashing: bcrypt with configurable work factor (default cost 12), providing well above 128-bit equivalent security against brute-force.
• TLS: httpx uses Python's ssl module which defaults to TLS 1.2+ with modern cipher suites. The system trust store governs CA validation.

Smaller keylengths are effectively disabled: the startup validation rejects JWT_SECRET_KEY shorter than 32 characters (application refuses to start), and bcrypt's minimum cost factor ensures no weak password hashing configuration is possible. TLS negotiation relies on the system's OpenSSL defaults which disable deprecated protocols (SSLv3, TLS 1.0/1.1).

Sentinel does not use any broken cryptographic algorithms. The project uses exclusively modern, secure primitives: HMAC-SHA256 (JWT), bcrypt (password hashing), and TLS 1.2+ (external communications). No MD4, MD5, single DES, RC4, or other deprecated algorithms appear in the application code. Python's ssl module (used via httpx) disables broken protocols and ciphers by default. No interoperable protocol requiring legacy algorithms is implemented.

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 does not implement key agreement protocols directly — it delegates TLS to Python's ssl module (via httpx), which negotiates ECDHE (Elliptic Curve Diffie-Hellman Ephemeral) key exchange by default on modern systems, providing perfect forward secrecy. Session keys are derived from ephemeral key pairs, so compromise of the server's long-term TLS private key does not compromise past sessions. The SSO/OIDC flow also operates over TLS with PFS-capable cipher suites.

Sentinel uses bcrypt for storing local user passwords — a key stretching algorithm with per-user salt (bcrypt generates a unique random salt per hash automatically) and configurable work factor (cost 12 by default). The specification in docs/features/identity/local-authentication.md documents the choice explicitly, including resistance to offline brute-force attacks. Passwords are never stored in plaintext or as simple hashes. The bcrypt library handles salt generation, iteration, and storage in the standard modular crypt format ($2b$).

Sentinel delegates all cryptographic random number generation to libraries that use cryptographically secure sources: bcrypt generates salts using the OS CSPRNG (/dev/urandom), PyJWT relies on Python's secrets/os.urandom for any nonce generation, and Python's uuid.uuid4() (used for primary keys) is backed by os.urandom. The application code does not use Python's random module (which is not cryptographically secure) for any security-sensitive purpose. No custom random number generation is implemented.

Distribution channels use HTTPS exclusively. [osps_br_03_02]

The project does not retrieve cryptographic hashes over unencrypted HTTP for integrity verification. All dependency resolution occurs over HTTPS via uv with lockfile-pinned hashes. Docker base images are pulled over HTTPS with content-addressable digests. No CI/CD step or application code downloads a hash over plain HTTP and trusts it without cryptographic signature verification.

The project has no known unpatched vulnerabilities of medium or higher severity. pip-audit blocks every merge against known Python dependency vulnerabilities (no code reaches master with a known-vulnerable dependency). image-scan.yml runs weekly Trivy scans against the published container image for OS-level CVEs and opens tracking issues. bandit gates every PR for application-level security weaknesses. The CI pipeline enforces that no vulnerability persists unaddressed — findings are either fixed before merge or (for OS-level findings) tracked via issues and addressed through base image updates.

The CI pipeline prevents critical vulnerabilities from persisting: pip-audit blocks merge on any known-vulnerable dependency, and bandit blocks on application-level findings. For OS-level vulnerabilities in the container image, image-scan.yml runs weekly Trivy scans and opens tracking issues for rapid triage. The project's pre-merge enforcement model means critical vulnerabilities in dependencies or application code are fixed immediately (before they reach master), not after a delay.

Three layers of defense: (1) a pre-commit hook runs gitleaks on every local commit, blocking commits containing detected secrets; (2) GitHub Push Protection (enabled) blocks pushes containing recognized secret patterns server-side; (3) .gitignore excludes private key and certificate files (*.pem, *.key, *.p12, *.pfx, id_rsa, id_ed25519). [osps_br_07_01]

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). [osps_vm_06_02]

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.

The CI pipeline blocks merge on any bandit finding (the "Backend Security Scan" job is a required status check). Since no code reaches master without passing this gate, static analysis vulnerabilities are fixed before they enter the codebase — not after. This is a stricter posture than "fixed in a timely way after confirmed"; vulnerabilities are prevented from being introduced in the first place. The project has no backlog of known unaddressed bandit findings.

Static source code analysis runs on every commit that targets master — both on pull requests and on push to master via the ci.yml workflow. ruff check, mypy --strict, and bandit all execute on every PR and every merge. The pre-commit hook additionally runs ruff check, ruff format, and mypy on every local commit before it is even pushed. This exceeds the "at least daily" suggestion.

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.

No dynamic analysis is currently performed (as noted in prior criteria), so there are no dynamic analysis findings to remediate. This criterion cannot be evaluated without a dynamic analysis practice in place. If dynamic analysis were adopted in the future, this criterion would become applicable.