sentinel

The repository's default workflow permissions are set to read (the minimum). Additionally, every workflow either declares a top-level permissions: block restricting to the minimum required scopes, or declares per-job permissions: on each job individually. No workflow relies on the repository default for write access — elevated permissions (write to packages, pages, issues, pull-requests) are always explicitly requested at the narrowest scope needed.

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.

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

The build and release pipeline uses uv (with a lockfile uv.lock) to resolve and install Python dependencies deterministically. Dependencies are declared in backend/pyproject.toml using standard PEP 621 metadata, and uv sync --frozen in CI ensures the lockfile is the sole source of installed versions — no ad-hoc pip install or unmanaged dependency resolution occurs during build. The Dockerfile similarly uses uv sync --frozen for reproducible image builds.

The project documents its dependency management approach across multiple files: CONTRIBUTING.md describes how to install dependencies (uv sync), docs/deployment.md documents the tooling (uv with lockfile), the CI security gate (pip-audit on every merge), and the Dockerfile build strategy (uv sync --frozen). Dependabot is configured (.github/dependabot.yml) to track and propose updates for three ecosystems — Python/uv, GitHub Actions, and Docker base images — on a weekly schedule. The lockfile (uv.lock) pins exact versions for reproducibility, pip-audit gates every PR against known vulnerabilities, and Dependabot automates tracking of new upstream releases.

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.

CONTRIBUTING.md documents the roles and responsibilities: the repository has a single maintainer/owner responsible for reviewing and merging contributions, managing releases, and triaging security reports. SECURITY.md identifies the security contact role (security@suse.com). The CODEOWNERS mechanism is implicit (single owner); GitHub's collaborator settings surface access levels. For a single-maintainer project this is sufficient — there are no additional roles (committers, release managers, etc.) to document.

CONTRIBUTING.md provides a comprehensive contributor guide covering: development environment setup, code style and linting requirements (ruff check, ruff format, mypy --strict), testing requirements (all changes must include tests, pytest must pass), commit message format (Conventional Commits), PR process (title format, issue linkage, required CI checks), and the specs-first workflow (feature specifications must exist before implementation). The document also includes a table of which changes require a specification and which do not.

Branch protection on master requires all 7 status checks to pass before merge (Backend Lint, Backend Type Check, Backend Security Scan, Backend Tests, Image Smoke Test, Shell Lint, PR Metadata), with strict status checks enabled. Direct pushes to master are blocked — all commits arrive via squash merge of a PR that has passed CI. Bypassing requires admin override (enforce_admins is disabled, allowing the repository owner to bypass in exceptional circumstances — this satisfies the "pass or be manually bypassed" wording).

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.

docs/architecture.md documents the system boundary, layer architecture, and integration patterns. docs/system-map.md provides component diagrams and data flow visuals covering all actors (vulnerability analysts, team leads, automation/CLI, external systems) and actions (CVE ingestion, ticket lifecycle, release detection, eligibility evaluation). Feature specifications in docs/features/ detail every action per domain (identity, tickets, packages, integrations, platform) including state machines, API operations, and background task behaviors.

docs/api-spec.md provides the complete external API specification including endpoint paths, HTTP methods, request/response schemas, error codes, pagination, filtering, and authentication requirements. docs/data-sources.md catalogs all external system interfaces (NVD, MITRE, IBS/OBS, SMELT, AIMAAS, Bugzilla, RabbitMQ) with protocols, hosts, and data contracts. docs/cli-reference.md documents the CLI interface. The OpenAPI contract is auto-generated and published to GitHub Pages on each release, providing a machine-readable description of the full REST API surface.

The project maintains an extensive docs/reviews/ directory with security review findings for every major component — over 50 review documents covering authentication, RBAC, networking, API specification, fetcher infrastructure, and all integration points. Each review includes findings from a dedicated @security-reviewer agent (among others), threat model assessments (e.g., brute-force resistance in local-authentication, trusted-upstream assumptions in networking, pre-disclosure data exposure in RBAC), and explicit risk acceptance decisions with rationale. The CI pipeline also runs bandit (static security analysis) and pip-audit (dependency vulnerability scanning) on every merge. Security-sensitive areas are subject to mandatory review per Guardrail 10.

SECURITY.md defines a coordinated vulnerability disclosure policy: vulnerabilities are reported privately to security@suse.com, the team acknowledges receipt within 5 business days, provides an initial assessment within 15 business days, and coordinates disclosure timing with the reporter. The document explicitly requests reporters to allow a reasonable timeframe for remediation before public disclosure.

SECURITY.md directs reporters to email security@suse.com for private vulnerability disclosure. Additionally, GitHub's Private Vulnerability Reporting feature is enabled on the repository (visible in the Security tab), providing a second private channel directly integrated with GitHub's advisory workflow. Both mechanisms allow reporters to communicate directly with the project's security contacts without public exposure.

GitHub's Security Advisories feature is enabled on the repository, providing the standard mechanism to publicly publish data about discovered vulnerabilities (CVE assignment, affected versions, severity, remediation). SECURITY.md references the coordinated disclosure process that leads to public advisory publication once a fix is available. Any confirmed vulnerability would be published as a GitHub Security Advisory with full details (description, affected versions, CVSS score, remediation steps).