sentinel

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

GitHub requires 2FA as of March 2023. [osps_ac_01_01]

The project's GitHub organization/account uses GitHub's two-factor authentication, which supports cryptographic mechanisms — TOTP (time-based one-time passwords via authenticator apps), hardware security keys (WebAuthn/FIDO2), and GitHub Mobile push notifications. SMS-based 2FA is not relied upon as the sole mechanism. GitHub's 2FA enforcement has been mandatory for all contributors since 2023.

Sentinel's code review requirements are comprehensively documented in CONTRIBUTING.md (https://github.com/StayPirate/sentinel/blob/master/CONTRIBUTING.md), which references the detailed conventions. The full review process includes:

• Automated reviewer agents: 15+ specialized reviewer agents (security, design, data-model, test, API convention, spec coherence, docs, etc.) are invoked per guardrail rules defined in AGENTS.md (https://github.com/StayPirate/sentinel/blob/master/AGENTS.md) — each guardrail specifies when to invoke which reviewer and what must be checked
• What must be checked: mandatory testing for all changes (Guardrail 6), security review for security-sensitive code (Guardrail 10), data model review for schema changes (Guardrail 8), documentation completeness (Guardrail 9), spec coherence (Guardrail 15), API convention conformity (Guardrail 20), and more
• Acceptance criteria: all CI checks must pass (ruff, mypy --strict, bandit, pip-audit, pytest), applicable reviewer agents must be invoked and findings addressed, PR description must include test evidence and manual verification notes
• PR requirements: documented in docs/conventions.md (https://github.com/StayPirate/sentinel/blob/master/docs/conventions.md) (Pull Request Requirements) — title format, issue linkage, scope summary, reviewer results, verification evidence
• Finding evaluation: Guardrail 26 documents how reviewer findings are evaluated — independent verification, discard criteria, proportionality, escalation procedure
• CI enforcement: required status checks on master branch protection (7 checks), conversation resolution required before merge

URL: https://github.com/StayPirate/sentinel/blob/master/CONTRIBUTING.md

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

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.

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

Sentinel achieves 99% statement coverage (98.99% measured precisely), well above the 90% threshold. Coverage is measured by pytest-cov (a FLOSS tool) and enforced in CI with a minimum threshold of 85%. Results are uploaded to Codecov on every CI run. The latest successful CI run shows TOTAL: 3113 statements, 27 missed, 568 branches, 10 missed — 99% coverage.

URL: https://app.codecov.io/github/staypirate/sentinel

From the same CI run, Sentinel's test suite achieves high branch coverage as well. The coverage report shows 568 branches, 10 missed — which is 98% branch coverage, well above the 80% threshold. Branch coverage is measured by pytest-cov (a FLOSS tool) using the --cov-branch flag, and results are uploaded to Codecov on every CI run.

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's repository and website are hosted on GitHub, which serves all pages with hardening headers including:

• Content-Security-Policy: restrictive policy limiting script and resource sources
• X-Content-Type-Options: nosniff
• X-Frame-Options: DENY
• Strict-Transport-Security: HSTS with long max-age, includeSubDomains, and preload
• X-XSS-Protection: 0 (modern approach — CSP replaces this deprecated header)
• Referrer-Policy: restrictive policy

These are enforced by GitHub's infrastructure for all repositories and GitHub Pages sites. The project does not operate a separate website or download site outside of GitHub.

URL: https://github.com/StayPirate/sentinel

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

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