up

CLAUDE.md

@@ -0,0 +1,219 @@
+# 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:** Tests use Mongo2Go which requires OpenSSL 1.1 on Linux. Run `scripts/enable-openssl11-shim.sh` before testing if needed.
+
+## 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/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)