Add reference architecture and testing strategy documentation
- Created a new document for the Stella Ops Reference Architecture outlining the system's topology, trust boundaries, artifact association, and interfaces. - Developed a comprehensive Testing Strategy document detailing the importance of offline readiness, interoperability, determinism, and operational guardrails. - Introduced a README for the Testing Strategy, summarizing processing details and key concepts implemented. - Added guidance for AI agents and developers in the tests directory, including directory structure, test categories, key patterns, and rules for test development.
This commit is contained in:
@@ -1,474 +0,0 @@
|
||||
# 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
|
||||
|
||||
```csharp
|
||||
[ServiceBinding(typeof(IMyContract), ServiceLifetime.Scoped)]
|
||||
public class MyService : IMyContract
|
||||
{
|
||||
// Implementation
|
||||
}
|
||||
```
|
||||
|
||||
### 5.3 Advanced DI Configuration
|
||||
|
||||
```csharp
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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 `AssemblyLoadContext`s
|
||||
|
||||
### 9.3 Plugin Signing
|
||||
|
||||
```bash
|
||||
dotnet publish -c Release -o out
|
||||
cosign sign --key $COSIGN_KEY out/StellaOps.Plugin.MyConnector.dll
|
||||
```
|
||||
|
||||
### 9.4 Plugin Version Attribute
|
||||
|
||||
```csharp
|
||||
// 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```csharp
|
||||
// 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
|
||||
|
||||
```csharp
|
||||
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
|
||||
|
||||
```csharp
|
||||
/// <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)
|
||||
|
||||
```markdown
|
||||
# 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
|
||||
|
||||
```yaml
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user