git.stella-ops.org/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

StellaOps is a self-hostable, sovereign container-security platform released under AGPL-3.0-or-later. It provides reproducible vulnerability scanning with VEX-first decisioning, SBOM generation (SPDX 3.0.1 and CycloneDX 1.6), in-toto/DSSE attestations, and optional Sigstore Rekor transparency. The platform is designed for offline/air-gapped operation with regional crypto support (eIDAS/FIPS/GOST/SM).

Build Commands

# Build the entire solution
dotnet build src/StellaOps.sln

# Build a specific module (example: Concelier web service)
dotnet build src/Concelier/StellaOps.Concelier.WebService/StellaOps.Concelier.WebService.csproj

# Run the Concelier web service
dotnet run --project src/Concelier/StellaOps.Concelier.WebService

# Build CLI for current platform
dotnet publish src/Cli/StellaOps.Cli/StellaOps.Cli.csproj --configuration Release

# Build CLI for specific runtime (linux-x64, linux-arm64, osx-x64, osx-arm64, win-x64)
dotnet publish src/Cli/StellaOps.Cli/StellaOps.Cli.csproj --configuration Release --runtime linux-x64

Test Commands

# Run all tests
dotnet test src/StellaOps.sln

# Run tests for a specific project
dotnet test src/Scanner/__Tests/StellaOps.Scanner.WebService.Tests/StellaOps.Scanner.WebService.Tests.csproj

# Run a single test by filter
dotnet test --filter "FullyQualifiedName~TestMethodName"

# Run tests with verbosity
dotnet test src/StellaOps.sln --verbosity normal

Note: Integration tests use Testcontainers for PostgreSQL. Ensure Docker is running before executing tests.

Linting and Validation

# Lint OpenAPI specs
npm run api:lint

# Validate attestation schemas
npm run docs:attestor:validate

# Validate Helm chart
helm lint deploy/helm/stellaops

Architecture

Technology Stack

• Runtime: .NET 10 (net10.0) with latest C# preview features
• Frontend: Angular v17 (in src/Web/StellaOps.Web)
• Database: PostgreSQL (≥16) with per-module schema isolation; see docs/db/ for specification
• Testing: xUnit with Testcontainers (PostgreSQL), Moq, Microsoft.AspNetCore.Mvc.Testing
• Observability: Structured logging, OpenTelemetry traces
• NuGet: Uses standard NuGet feeds configured in nuget.config (dotnet-public, nuget-mirror, nuget.org)

Module Structure

The codebase follows a monorepo pattern with modules under src/:

Module	Path	Purpose
Core Platform
Authority	src/Authority/	Authentication, authorization, OAuth/OIDC, DPoP
Gateway	src/Gateway/	API gateway with routing and transport abstraction
Router	src/__Libraries/StellaOps.Router.*	Transport-agnostic messaging (TCP/TLS/UDP/RabbitMQ/Valkey)
Data Ingestion
Concelier	src/Concelier/	Vulnerability advisory ingestion and merge engine
Excititor	src/Excititor/	VEX document ingestion and export
VexLens	src/VexLens/	VEX consensus computation across issuers
IssuerDirectory	src/IssuerDirectory/	Issuer trust registry (CSAF publishers)
Scanning & Analysis
Scanner	src/Scanner/	Container scanning with SBOM generation (11 language analyzers)
BinaryIndex	src/BinaryIndex/	Binary identity extraction and fingerprinting
AdvisoryAI	src/AdvisoryAI/	AI-assisted advisory analysis
Artifacts & Evidence
Attestor	src/Attestor/	in-toto/DSSE attestation generation
Signer	src/Signer/	Cryptographic signing operations
SbomService	src/SbomService/	SBOM storage, versioning, and lineage ledger
EvidenceLocker	src/EvidenceLocker/	Sealed evidence storage and export
ExportCenter	src/ExportCenter/	Batch export and report generation
VexHub	src/VexHub/	VEX distribution and exchange hub
Policy & Risk
Policy	src/Policy/	Policy engine with K4 lattice logic
VulnExplorer	src/VulnExplorer/	Vulnerability exploration and triage UI backend
Operations
Scheduler	src/Scheduler/	Job scheduling and queue management
Orchestrator	src/Orchestrator/	Workflow orchestration and task coordination
TaskRunner	src/TaskRunner/	Task pack execution engine
Notify	src/Notify/	Notification delivery (Email, Slack, Teams, Webhooks)
Integration
CLI	src/Cli/	Command-line interface (Native AOT)
Zastava	src/Zastava/	Container registry webhook observer
Web	src/Web/	Angular 17 frontend SPA
Infrastructure
Cryptography	src/Cryptography/	Crypto plugins (FIPS, eIDAS, GOST, SM, PQ)
Telemetry	src/Telemetry/	OpenTelemetry traces, metrics, logging
Graph	src/Graph/	Call graph and reachability data structures
Signals	src/Signals/	Runtime signal collection and correlation
Replay	src/Replay/	Deterministic replay engine

Note: See docs/modules/<module>/architecture.md for detailed module dossiers.

Code Organization Patterns

• Libraries: src/<Module>/__Libraries/StellaOps.<Module>.*
• Tests: src/<Module>/__Tests/StellaOps.<Module>.*.Tests/
• Plugins: Follow naming StellaOps.<Module>.Connector.* or StellaOps.<Module>.Plugin.*
• Shared test infrastructure: StellaOps.Concelier.Testing and StellaOps.Infrastructure.Postgres.Testing provide PostgreSQL fixtures

Naming Conventions

• All modules are .NET 10 projects, except the UI (Angular)
• Module projects: StellaOps.<ModuleName>
• Libraries/plugins common to multiple modules: StellaOps.<LibraryOrPlugin>
• Each project lives in its own folder

Key Glossary

• OVAL — Vendor/distro security definition format; authoritative for OS packages
• NEVRA / EVR — RPM and Debian version semantics for OS packages
• PURL / SemVer — Coordinates and version semantics for OSS ecosystems
• KEV — Known Exploited Vulnerabilities (flag only)

Coding Rules

Core Principles

1. Determinism: Outputs must be reproducible - stable ordering, UTC ISO-8601 timestamps, immutable NDJSON where applicable
2. Offline-first: Remote host allowlist, strict schema validation, avoid hard-coded external dependencies unless explicitly allowed
3. Plugin architecture: Concelier connectors, Authority plugins, Scanner analyzers are all plugin-based
4. VEX-first decisioning: Exploitability modeled in OpenVEX with lattice logic for stable outcomes

Implementation Guidelines

• Follow .NET 10 and Angular v17 best practices
• Apply SOLID principles (SRP, OCP, LSP, ISP, DIP) when designing services, libraries, and tests
• Maximise reuse and composability
• Never regress determinism, ordering, or precedence
• Every change must be accompanied by or covered by tests
• Gated LLM usage (only where explicitly configured)

Test Layout

• Module tests: StellaOps.<Module>.<Component>.Tests
• Shared fixtures/harnesses: StellaOps.<Module>.Testing
• Tests use xUnit, Testcontainers for PostgreSQL integration tests

Documentation Updates

When scope, contracts, or workflows change, update the relevant docs under:

• docs/modules/** - Module architecture dossiers
• docs/api/ - API documentation
• docs/risk/ - Risk documentation
• docs/airgap/ - Air-gap operation docs

Role-Based Behavior

When working in this repository, behavior changes based on the role specified:

As Implementer (Default for coding tasks)

• Work only inside the module's directory defined by the sprint's "Working directory"
• Cross-module edits require explicit notes in commit/PR descriptions
• Do not ask clarification questions - if ambiguity exists:
  • Mark the task as BLOCKED in the sprint Delivery Tracker
  • Add a note in Decisions & Risks describing the issue
  • Skip to the next unblocked task
• Maintain status tracking: TODO → DOING → DONE/BLOCKED in sprint files
• Read the module's AGENTS.md before coding in that module

As Project Manager

Create implementation sprint files under docs/implplan/ using the mandatory sprint filename format:

SPRINT_<IMPLID>_<BATCHID>_<MODULEID>_<topic_in_few_words>.md

• <IMPLID>: implementation epoch (e.g., 20251219). Determine by scanning existing docs/implplan/SPRINT_*.md and using the highest epoch; if none exist, use today's epoch.
• <BATCHID>: 001, 002, etc. — grouping when more than one sprint is needed for a feature.
• <MODULEID>: FE (Frontend), BE (Backend), AG (Agent), LB (library), BE (Backend), AG (Agent), LB (library), 'SCANNER' (scanner), 'AUTH' (Authority), 'CONCEL' (Concelier), 'CONCEL-ASTRA' - (Concelier Astra source connecto) and etc.
• <topic_in_few_words>: short topic description.
• If any existing sprint file name or internal format deviates from the standard, rename/normalize it and record the change in its Execution Log.
• Normalize sprint files to standard template while preserving content
• Ensure module AGENTS.md files exist and are up to date

As Product Manager

• Review advisories in docs/product-advisories/
• Check for overlaps with docs/product-advisories/archived/
• Validate against module docs and existing implementations
• Hand over to project manager role for sprint/task definition

Task Workflow

Status Discipline

Always update task status in docs/implplan/SPRINT_*.md:

• TODO - Not started
• DOING - In progress
• DONE - Completed
• BLOCKED - Waiting on decision/clarification

Prerequisites

Before coding, confirm required docs are read:

• docs/README.md
• docs/07_HIGH_LEVEL_ARCHITECTURE.md
• docs/modules/platform/architecture-overview.md
• Relevant module dossier (e.g., docs/modules/<module>/architecture.md)
• Module-specific AGENTS.md file

Git Rules

• Never use git reset unless explicitly told to do so
• Never skip hooks (--no-verify, --no-gpg-sign) unless explicitly requested

Configuration

• Sample configs: etc/concelier.yaml.sample, etc/authority.yaml.sample
• Plugin manifests: etc/authority.plugins/*.yaml
• NuGet sources: Curated packages in local-nugets/, public sources configured in Directory.Build.props

Documentation

• Architecture overview: docs/07_HIGH_LEVEL_ARCHITECTURE.md
• Module dossiers: docs/modules/<module>/architecture.md
• Database specification: docs/db/SPECIFICATION.md
• PostgreSQL operations: docs/operations/postgresql-guide.md
• API/CLI reference: docs/09_API_CLI_REFERENCE.md
• Offline operation: docs/24_OFFLINE_KIT.md
• Quickstart: docs/10_CONCELIER_CLI_QUICKSTART.md
• Sprint planning: docs/implplan/SPRINT_*.md

CI/CD

Workflows are in .gitea/workflows/. Key workflows:

• build-test-deploy.yml - Main build, test, and deployment pipeline
• cli-build.yml - CLI multi-platform builds
• scanner-determinism.yml - Scanner output reproducibility tests
• policy-lint.yml - Policy validation

Environment Variables

• STELLAOPS_BACKEND_URL - Backend API URL for CLI
• STELLAOPS_TEST_POSTGRES_CONNECTION - PostgreSQL connection string for integration tests
• StellaOpsEnableCryptoPro - Enable GOST crypto support (set to true in build)