259 lines
11 KiB
Markdown
259 lines
11 KiB
Markdown
# 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 |
|
|
|--------|------|---------|
|
|
| **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)
|