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
Concelier	src/Concelier/	Vulnerability advisory ingestion and merge engine
CLI	src/Cli/	Command-line interface for scanner distribution and job control
Scanner	src/Scanner/	Container scanning with SBOM generation
Authority	src/Authority/	Authentication and authorization
Signer	src/Signer/	Cryptographic signing operations
Attestor	src/Attestor/	in-toto/DSSE attestation generation
Excititor	src/Excititor/	VEX document ingestion and export
Policy	src/Policy/	OPA/Rego policy engine
Scheduler	src/Scheduler/	Job scheduling and queue management
Notify	src/Notify/	Notification delivery (Email, Slack, Teams)
Zastava	src/Zastava/	Container registry webhook observer

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)