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