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

```bash
# 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

```bash
# 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

```bash
# 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)