stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
main
git.stella-ops.org/docs/product-advisories/14-Dec-2025 - Developer Onboarding Technical Reference.md
StellaOps Bot b058dbe031 up
2025-12-14 23:20:14 +02:00

13 KiB
Raw Permalink Blame History

Developer Onboarding Technical Reference

Source Advisories:

  • 01-Dec-2025 - Common Developers guides
  • 29-Nov-2025 - StellaOps – Mid-Level .NET Onboarding (Quick Start)
  • 30-Nov-2025 - Implementor Guidelines for Stella Ops
  • 30-Nov-2025 - Standup Sprint Kickstarters

Last Updated: 2025-12-14 Revision: 1.1 (Corrected to match actual implementation)

0. WHERE TO START (IN-REPO)

  • docs/README.md (doc map and module dossiers)
  • docs/07_HIGH_LEVEL_ARCHITECTURE.md (end-to-end system model)
  • docs/18_CODING_STANDARDS.md (C# conventions, repo rules, gates)
  • docs/19_TEST_SUITE_OVERVIEW.md (test layers, CI expectations)
  • docs/technical/development/README.md (developer tooling and workflows)
  • docs/10_PLUGIN_SDK_GUIDE.md (plugin SDK + packaging)
  • LICENSE (AGPL-3.0-or-later obligations)

1. CORE ENGINEERING PRINCIPLES

  • SOLID First: Interface and dependency inversion required
  • 100-line File Rule: Files >100 lines must be split/refactored
  • Contracts vs Runtime: Public DTOs/interfaces in *.Contracts projects
  • Single Composition Root: DI wiring in StellaOps.Web/Program.cs and plugin IDependencyInjectionRoutine
  • No Service Locator: Constructor injection only
  • Fail-fast Startup: Validate configuration before web host starts
  • Hot-load Compatibility: Avoid static singletons that survive plugin unload

1.1 Product Non-Negotiables

  • Determinism first: stable ordering + canonicalization; no hidden clocks/entropy in core algorithms
  • Offline-first: no silent network dependency; every workflow has an offline/mirrored path
  • Evidence over UI: the API + signed artifacts must fully explain what the UI shows
  • Contracts are contracts: version schemas; add fields with defaults; never silently change semantics
  • Golden fixtures required: any change to scanning/policy/proofs must be covered by deterministic fixtures + replay tests
  • Respect service boundaries: do not re-implement scanner/policy logic in downstream services or UI

2. REPOSITORY LAYOUT RULES

  • No "Module" folders or nested solution hierarchies
  • Tests mirror src/ structure 1:1
  • No test code in production projects
  • Feature folder layout: Scan/ScanService.cs, Scan/ScanController.cs

3. NAMING & STYLE CONVENTIONS

3.1 Namespaces & Files

  • Namespaces: File-scoped, StellaOps.*
  • Classes/records: PascalCase
  • Interfaces: I prefix (IScannerRunner)
  • Private fields: _camelCase (with leading underscore, standard C# convention)
  • Constants: PascalCase (standard C# convention, e.g., MaxRetries)
  • Async methods: End with Async

3.2 Usings

  • Outside namespace
  • Sorted
  • No wildcards

4. C# FEATURE USAGE

  • Nullable reference types enabled
  • Use record for immutable DTOs
  • Prefer pattern matching over long switch cascades
  • Span/Memory only when measured as necessary
  • Use await foreach instead of manual iterator loops

5. DI POLICY

5.1 Composition Root

  • One composition root per process
  • Plugins contribute via [ServiceBinding] attribute or IDependencyInjectionRoutine implementations
  • Default lifetime: scoped
  • Singletons only for stateless, thread-safe helpers
  • Never use service locator or manually build nested service providers

5.2 Service Binding Attributes

[ServiceBinding(typeof(IMyContract), ServiceLifetime.Scoped)]
public class MyService : IMyContract
{
    // Implementation
}

5.3 Advanced DI Configuration

public class MyPluginDependencyInjectionRoutine : IDependencyInjectionRoutine
{
    public IServiceCollection Register(IServiceCollection services, IConfiguration configuration)
    {
        services.AddScoped<IMyContract, MyService>();
        services.Configure<MyOptions>(configuration.GetSection("MyPlugin"));
        return services;
    }
}

6. ASYNC & THREADING

  • All I/O is async; avoid .Result / .Wait()
  • Library code uses ConfigureAwait(false)
  • Control concurrency with channels or Parallel.ForEachAsync

7. TEST LAYERS

  • Unit: xUnit with FluentAssertions
  • Property-based: FsCheck (for fuzz testing in Attestor module)
  • Integration: API with Testcontainers (PostgreSQL)
  • Contracts: OpenAPI validation with Spectral
  • Frontend: Karma/Jasmine (unit), Playwright (e2e), Lighthouse CI (performance/a11y)
  • Non-functional: Dependency/license scanning, SBOM reproducibility, Axe accessibility audits

8. QUALITY GATES

  • API unit test coverage ≥ ~85%
  • API P95 latency ≤ ~120ms
  • Δ-SBOM warm scan P95 ≤ ~5s
  • Lighthouse perf ≥ ~90, a11y ≥ ~95

9. PLUGIN SYSTEM

9.1 Plugin Templates

# Install templates
dotnet new install ./templates

# Create a connector plugin
dotnet new stellaops-plugin-connector -n MyCompany.AcmeConnector

# Create a scheduled job plugin
dotnet new stellaops-plugin-scheduler -n MyCompany.CleanupJob

9.2 Plugin Publishing

  • Publish signed artifacts to <Module>.PluginBinaries/<MyPlugin>/
  • Backend verifies Cosign signature when EnforceSignatureVerification is enabled
  • Enforces [StellaPluginVersion] compatibility when HostVersion is configured
  • Loads plugins in isolated AssemblyLoadContexts

9.3 Plugin Signing

dotnet publish -c Release -o out
cosign sign --key $COSIGN_KEY out/StellaOps.Plugin.MyConnector.dll

9.4 Plugin Version Attribute

// In AssemblyInfo.cs or any file
[assembly: StellaPluginVersion("1.0.0", MinimumHostVersion = "1.0.0")]

10. POLICY DSL (stella-dsl@1)

10.1 Goals

  • Deterministic
  • Declarative
  • Explainable
  • Offline-friendly
  • Reachability-aware

10.2 Structure

  • One policy block per .stella file
  • Contains: metadata, profile blocks, rule blocks, optional settings

10.3 Context Namespaces

  • sbom
  • advisory
  • vex
  • env
  • telemetry
  • secret
  • profile.*

10.4 Helpers

  • normalize_cvss
  • risk_score
  • vex.any
  • vex.latest
  • sbom.any_component
  • exists
  • coalesce

10.5 Rules

  • Always include clear because when changing status or severity
  • Avoid catch-all suppressions (when true + status := "suppressed")
  • Use stella policy lint/compile/simulate in CI
  • Test in sealed (offline) mode

11. PR CHECKLIST

  1. Use Conventional Commit prefixes (feat:, fix:, docs:)
  2. Run dotnet format and dotnet test (both must be green)
  3. Keep files within 100-line guideline
  4. Update XML-doc comments for new public API
  5. Update docs and JSON schema for contract changes
  6. Ensure analyzers and CI jobs pass

12. ONBOARDING DETERMINISM REQUIREMENTS

  • Use fixed seeds and pinned toolchain versions
  • Avoid live network calls; prefer cached feeds/mirrors
  • Note mirror paths in examples

13. SPRINT READINESS CHECKLIST

  • Scanner regressions verification
  • Postgres slice validation
  • DSSE/Rekor sweep complete
  • Pin tool versions in scripts

14. MODULE-SPECIFIC GUIDANCE

14.1 Scanner Module

  • Reachability algorithms only in Scanner.WebService
  • Cache lazy and keyed by deterministic inputs
  • Output includes explicit evidence pointers
  • UI endpoints expose reachability state in structured form

14.2 Authority Module

  • Trust roots: pinned via out-of-band distribution
  • Key rotation: maintain version history in trust store
  • Revocation: maintain revoked_keys list in trust anchors

14.3 Excititor (VEX) Module

  • VEX schema includes pointers to all upstream artifacts
  • No duplication of SBOM/scan content inside VEX
  • DSSE used as standard envelope type

14.4 Policy Module

  • Facts and policies serialized separately
  • Lattice code in allowed services only
  • Merge strategies named and versioned
  • Artifacts record which lattice algorithm used

14.5 SbomService Module

Note: This module is implemented as src/SbomService/ in the codebase.

  • Emit SPDX 3.0.1 and CycloneDX 1.6 with stable ordering and deterministic IDs
  • Persist raw bytes + canonical form; hash canonical bytes for digest binding
  • Produce DSSE attestations for SBOM linkage and generation provenance

14.6 Concelier Feed Handling

Note: Feed handling is implemented within the Concelier module via connectors in src/Concelier/__Libraries/.

  • Treat every feed import as a versioned snapshot (URI + time + content hashes)
  • Support deterministic export/import for offline bundles
  • Imports are idempotent (same snapshot digest is a no-op)

14.7 Concelier Module

  • Never mutate evidence; attach business context and build views only
  • Never re-implement scanner/policy risk logic; consume signed decisions + proofs

14.8 UI / Console

  • UI is an explainer and navigator; the evidence chain must be retrievable via API and export
  • Any UI state must be reproducible from persisted evidence + graph revision identifiers

14.9 Zastava / Advisory AI

  • AI consumes evidence graph IDs/digests; it is never a source of truth for vulnerability states
  • Pipelines must never pass/fail based on AI text; enforcement is always policy + lattice + evidence
  • Any AI output must reference evidence IDs and remain optional/offline-safe

15. COMMON PITFALLS & SOLUTIONS

15.1 Avoid

  • ❌ Service Locator pattern
  • ❌ Static mutable state
  • ❌ Async void (except event handlers)
  • ❌ Blocking on async code (.Result, .Wait())
  • ❌ Non-deterministic ordering
  • ❌ Hard-coded timestamps
  • ❌ Environment variables in core algorithms

15.2 Prefer

  • ✅ Constructor injection
  • ✅ Immutable data structures
  • ✅ async Task
  • ✅ await or Task.Run for CPU-bound work
  • ✅ Stable sorting with explicit comparers
  • ✅ Explicit asOf parameters
  • ✅ Configuration objects passed as parameters

16. DEBUGGING WORKFLOW

16.1 Local Development

# Run all services
docker-compose up -d

# Run specific service
dotnet run --project src/Scanner/StellaOps.Scanner.WebService

# Attach debugger
# Use VS Code launch.json or Visual Studio F5

16.2 Log Correlation

// Note: Private fields use _camelCase convention
using var activity = Activity.Current;
activity?.SetTag("scan.id", _scanId);
_logger.LogInformation("Processing scan {ScanId}", _scanId);

16.3 OpenTelemetry

services.AddOpenTelemetry()
    .WithTracing(builder => builder
        .AddAspNetCoreInstrumentation()
        .AddNpgsql()
        .AddOtlpExporter());

17. PERFORMANCE OPTIMIZATION

17.1 Database

  • Use indexes for hot queries
  • Batch inserts/updates
  • Use COPY for bulk data
  • Avoid N+1 queries

17.2 Memory

  • Use Span<T> for hot paths
  • Pool large objects
  • Dispose IDisposable promptly
  • Profile with dotMemory

17.3 Caching

  • Cache deterministically (keyed by input hashes)
  • Use distributed cache (Valkey/Redis) for shared state
  • TTL appropriate to data volatility

18. SECURITY GUIDELINES

18.1 Input Validation

  • Validate all user inputs
  • Use allowlists, not denylists
  • Sanitize for SQL, XSS, path traversal

18.2 Authentication & Authorization

  • Never roll your own crypto
  • Use standard protocols (OAuth2, OIDC)
  • Implement principle of least privilege

18.3 Secrets Management

  • Never commit secrets
  • Use environment variables or KMS
  • Rotate credentials regularly

19. DOCUMENTATION STANDARDS

19.1 XML Documentation

/// <summary>
/// Scans the specified artifact for vulnerabilities.
/// </summary>
/// <param name="artifactId">The artifact identifier.</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>Scan results with reachability analysis.</returns>
/// <exception cref="ArgumentNullException">If artifactId is null.</exception>
public Task<ScanResult> ScanAsync(string artifactId, CancellationToken ct);

19.2 Architecture Decision Records (ADRs)

# ADR-XXX: Title

## Status
Proposed | Accepted | Deprecated | Superseded

## Context
What is the issue?

## Decision
What did we decide?

## Consequences
What are the implications?

20. CI/CD INTEGRATION

20.1 Build Pipeline

stages:
  - restore
  - build
  - test
  - analyze
  - package
  - deploy

20.2 Required Checks

  • Unit tests pass
  • Integration tests pass
  • Code coverage ≥85%
  • No high/critical vulnerabilities
  • SBOM generated
  • Determinism tests pass

21. MIGRATION GUIDE

21.1 From .NET 8 to .NET 10

  • Update <TargetFramework>net10.0</TargetFramework>
  • Review breaking changes
  • Update NuGet packages
  • Test thoroughly

21.2 Database Migrations

# Create migration
dotnet ef migrations add MigrationName -p src/Module -s src/WebService

# Apply migration
dotnet ef database update -p src/Module -s src/WebService

Document Version: 1.1 Target Platform: .NET 10, PostgreSQL ≥16, Angular v17

Revision History

Version Date Changes
1.1 2025-12-14 Corrected naming conventions (_camelCase for fields, PascalCase for constants), updated DI interface name to IDependencyInjectionRoutine, corrected test frameworks (PostgreSQL not Mongo/Redis, Karma/Jasmine not Jest), added plugin templates and version attribute documentation, clarified module names (SbomService, Concelier feed handling)
1.0 2025-12-14 Initial consolidated reference