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: Tests use Mongo2Go which requires OpenSSL 1.1 on Linux. Run scripts/enable-openssl11-shim.sh before testing if needed.

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/UI/StellaOps.UI)
• Database: MongoDB (driver version ≥ 3.0)
• Testing: xUnit with Mongo2Go, Moq, Microsoft.AspNetCore.Mvc.Testing
• Observability: Structured logging, OpenTelemetry traces
• NuGet: Use the single curated feed and cache at local-nugets/

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 provides MongoDB 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
• 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, Mongo2Go for MongoDB 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

• Sprint files follow format: SPRINT_<IMPLID>_<BATCHID>_<SPRINTID>_<topic>.md
• IMPLID epochs: 1000 basic libraries, 2000 ingestion, 3000 backend services, 4000 CLI/UI, 5000 docs, 6000 marketing
• 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
• 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_MONGO_URI - MongoDB connection string for integration tests
• StellaOpsEnableCryptoPro - Enable GOST crypto support (set to true in build)