Security update management platform for SUSE and openSUSE-based Linux distributions. Sentinel automates CVE tracking, impact analysis, and update coordination across multiple maintained distribution versions, following the SUSE maintenance workflow and integrating with SUSE-internal services.

Overview

What Sentinel does

• Ingests CVE data from public sources (NVD, MITRE, Red Hat, GHSA, OSV, CISA KEV, EPSS, Linux Kernel CNA)
• Creates and manages security tickets from CVE detections
• Tracks which packages, codestreams, and products are affected
• Synchronizes the product catalog, lifecycle dates, and CVSS thresholds from SUSE-internal services (SMELT, AIMAAS), and resolves each package's codestreams, products, and maintainers through SMELT
• Evaluates product eligibility based on CVSS thresholds and lifecycle
• Detects when security fixes are released via IBS, the SUSE-internal build service
• Provides a REST API for vulnerability analysts, team leads, and automation
• Offers a CLI for administrative operations

What Sentinel does NOT do

• Build or submit packages (IBS handles builds)
• Manage product lifecycle or release schedules (SMELT/AIMAAS own this)
• Provision user identities (deferred to external identity provider)
• Provide a web UI (the UI is developed in the separate sentinel-aura repository)

Architecture

graph TB
    subgraph External Sources
        CVE[CVE APIs and feeds<br/>NVD, Red Hat, GHSA, OSV,<br/>CISA KEV, EPSS]
        GIT[CVE Git repositories<br/>MITRE cvelistV5, Linux Kernel CNA]
        IBS[IBS]
        RMQ[IBS RabbitMQ]
        SMELT[SMELT / AIMAAS]
    end

    subgraph Sentinel
        API[FastAPI<br/>REST API]
        Worker[Celery Worker<br/>Fetchers & Tasks]
        GitWorker[Git Worker<br/>Git-based Fetchers]
        Beat[Celery Beat<br/>Scheduler]
        Consumer[IBS RabbitMQ<br/>Consumer]
        CLI[CLI<br/>Admin Commands]
    end

    subgraph Infrastructure
        PG[(PostgreSQL 18)]
        Redis[(Redis 8)]
    end

    CVE & IBS & SMELT --> Worker
    GIT --> GitWorker
    RMQ & IBS --> Consumer
    Worker & GitWorker & Consumer & API & CLI --> PG
    Beat & Worker & GitWorker & Consumer & API & CLI --> Redis

Loading

All runtime processes (API server, Celery worker, Git worker, Celery Beat, and IBS RabbitMQ consumer) run from a single OCI image with different entrypoints. See docs/architecture.md for the architectural decisions and docs/system-map.md for detailed component and data-flow diagrams.

Project Status

Sentinel is in active pre-1.0 development. The API is not yet considered stable — breaking changes may occur in minor version bumps, but 1.0.0 is never selected automatically by a breaking commit. Graduation is intentional after the documented criteria are verified. See the Release Process.

Implementation progress is tracked in the milestones.

Verifying Releases

Each versioned container release includes a CycloneDX SBOM plus signed SBOM and build-provenance attestations bound to the immutable image digest. Download the SBOM and the Sigstore bundles of both attestations from the GitHub Release assets and verify the image attestations with gh attestation verify. A published release is final: the release workflow never replaces its exact-version image tag or its assets. See Release Supply-Chain Artifacts for artifact meanings, locations, scope, limitations, and tested verification commands.

Tech Stack

Component	Technology
Language	Python 3.14
Package Manager	uv
API Framework	FastAPI on uvicorn
ORM	SQLAlchemy (async, asyncpg)
Database	PostgreSQL 18
Task Queue	Celery with Redis broker
Cache / Coordination	Redis 8
Migrations	Alembic
Validation	Pydantic
CLI	Click
HTTP Client	httpx

Documentation

Document	Description
Architecture	System design and architectural decisions
System Map	Visual overview of components, data model, and data flows
API Specification	REST API conventions, envelope format, errors
Data Model	Database schema and relationships
Configuration	Environment variables reference
Deployment	Deployment guide and CI/CD pipeline
Conventions	Code patterns and style guide
CLI Reference	CLI commands documentation
Data Sources	External data sources catalog
Feature Specs	Detailed feature specifications

API Documentation

Interactive API documentation (Swagger UI) is published to GitHub Pages on every version tag: API Docs. A running Sentinel API serves the same page for its own version at /api/docs.

The OpenAPI document of each version is attached to its GitHub Release as sentinel-<version>.openapi.json; use it to pin the contract of a specific version.