themed the bulk of advisories
This commit is contained in:
StellaOps Bot
@@ -0,0 +1,399 @@
|
||||
# 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
|
||||
|
||||
---
|
||||
|
||||
## 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 `IoCConfigurator`
|
||||
- **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
|
||||
|
||||
## 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` (no leading `_`)
|
||||
- **Constants**: `SCREAMING_SNAKE_CASE`
|
||||
- **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]` or `IoCConfigurator : IDependencyInjectionRoutine`
|
||||
- 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 MyPluginIoCConfigurator : IDependencyInjectionRoutine
|
||||
{
|
||||
public void Configure(IServiceCollection services, IConfiguration config)
|
||||
{
|
||||
services.AddScoped<IMyContract, MyService>();
|
||||
services.Configure<MyOptions>(config.GetSection("MyPlugin"));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 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
|
||||
- **Property-based**: FsCheck
|
||||
- **Integration**: API with Testcontainers, DB/merge with Mongo + Redis
|
||||
- **Contracts**: gRPC breakage checks with Buf
|
||||
- **Frontend**: Jest (unit), Playwright (e2e), Lighthouse (performance/a11y)
|
||||
- **Non-functional**: k6 (load), Docker (chaos), dependency/license scanning, SBOM reproducibility
|
||||
|
||||
## 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
|
||||
dotnet new stellaops-plugin-schedule -n MyPlugin.Schedule
|
||||
```
|
||||
|
||||
### 9.2 Plugin Publishing
|
||||
|
||||
- Publish signed artifacts to `src/backend/Stella.Ops.Plugin.Binaries/<MyPlugin>/`
|
||||
- Backend verifies Cosign signature
|
||||
- Enforces `[StellaPluginVersion]` compatibility
|
||||
- Loads plugins in isolated `AssemblyLoadContext`s
|
||||
|
||||
### 9.3 Plugin Signing
|
||||
|
||||
```bash
|
||||
dotnet publish -c Release -p:PublishSingleFile=true -o out
|
||||
cosign sign --key $COSIGN_KEY out/MyPlugin.Schedule.dll
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
## 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
|
||||
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.0
|
||||
**Target Platform**: .NET 10, PostgreSQL ≥16, Angular v17
|
||||
Reference in New Issue
Block a user