docs: comprehensive documentation updates
- Update TEST_COVERAGE_MAP with current requirements - Refresh ADR-004 with C++ implementation details - Update architecture, deployment, and security docs - Improve CLI/TUI UX contract documentation
This commit is contained in:
Jeremie Fraeys
parent
66f262d788
commit
5d75f3576b
11 changed files with 170 additions and 95 deletions
|
|
@ -12,7 +12,7 @@ This document is a companion to the Security Plan and Verification Plan. It does
|
|||
|
||||
**During code review:** Any PR that adds or changes a security/reproducibility control must either point to an existing test or add a new one. A control without a test does not ship.
|
||||
|
||||
**Pre-release:** Run the full gap summary. Any `✗ Missing` in the Prerequisites or Reproducibility Crossover sections is a release blocker. Missing tests in V.9 Fault Injection and Integration are blockers for HIPAA and public multi-tenant deployments.
|
||||
**Pre-release:** Run the full gap summary. Any `✗ Missing` in the Prerequisites or Reproducibility Crossover sections is a release blocker. Missing tests in Fault Injection and Integration are blockers for HIPAA and public multi-tenant deployments.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -62,7 +62,7 @@ This document is a companion to the Security Plan and Verification Plan. It does
|
|||
|
||||
---
|
||||
|
||||
## V.1 Schema Validation
|
||||
## Schema Validation
|
||||
|
||||
| Requirement | Test | Location | Status |
|
||||
|---|---|---|---|
|
||||
|
|
@ -72,7 +72,7 @@ This document is a companion to the Security Plan and Verification Plan. It does
|
|||
|
||||
---
|
||||
|
||||
## V.2 Property-Based Tests
|
||||
## Property-Based Tests
|
||||
|
||||
| Requirement | Test | Location | Status |
|
||||
|---|---|---|---|
|
||||
|
|
@ -83,7 +83,7 @@ This document is a companion to the Security Plan and Verification Plan. It does
|
|||
|
||||
---
|
||||
|
||||
## V.3 Mutation Testing Targets
|
||||
## Mutation Testing Targets
|
||||
|
||||
Not tests themselves — packages and targets that must achieve >80% mutation kill rate before each release. A score below 80% on any of these is a release blocker.
|
||||
|
||||
|
|
@ -96,7 +96,7 @@ Not tests themselves — packages and targets that must achieve >80% mutation ki
|
|||
|
||||
---
|
||||
|
||||
## V.4 Custom Lint Rules
|
||||
## Custom Lint Rules
|
||||
|
||||
Not tests — static analysis rules enforced at compile time in CI. All four must be implemented before v1.0.
|
||||
|
||||
|
|
@ -109,7 +109,7 @@ Not tests — static analysis rules enforced at compile time in CI. All four mus
|
|||
|
||||
---
|
||||
|
||||
## V.7 Audit Log Integrity
|
||||
## Audit Log Integrity
|
||||
|
||||
| Requirement | Test | Location | Status |
|
||||
|---|---|---|---|
|
||||
|
|
@ -119,7 +119,7 @@ Not tests — static analysis rules enforced at compile time in CI. All four mus
|
|||
|
||||
---
|
||||
|
||||
## V.9 Fault Injection
|
||||
## Fault Injection
|
||||
|
||||
| Scenario | Test | Location | Status |
|
||||
|---|---|---|---|
|
||||
|
|
@ -208,13 +208,13 @@ Work through gaps in this order:
|
|||
|
||||
4. **Write Reproducibility Crossover tests** (R.1–R.5) — 12 mapped tests missing, though related tests exist. Focus on manifest `Environment` population validation.
|
||||
|
||||
5. **Implement lint rules (V.4)** — compile-time enforcement before property-based tests.
|
||||
5. **Implement lint rules** — compile-time enforcement before property-based tests.
|
||||
|
||||
6. **Write property-based tests (V.2)** — requires `gopter` test dependency.
|
||||
6. **Write property-based tests** — requires `gopter` test dependency.
|
||||
|
||||
7. **Write audit verification integration test** — `TestAuditVerificationJob` for background chain verification.
|
||||
|
||||
8. **Write fault injection tests (V.9)** — nightly CI only, requires `toxiproxy`.
|
||||
8. **Write fault injection tests** — nightly CI only, requires `toxiproxy`.
|
||||
|
||||
9. **Write remaining integration tests** — `TestCrossTenantIsolation`, `TestRunManifestReproducibility`, `TestAuditLogPHIRedaction`.
|
||||
|
||||
|
|
@ -226,28 +226,28 @@ Work through gaps in this order:
|
|||
|---|---|
|
||||
| 2026-02-23 | Initial creation of test coverage map |
|
||||
| 2026-02-23 | Updated with actual test status after codebase review: marked 8 tests as Exists, identified 10 naming convention mismatches, added Related Tests section |
|
||||
| 2026-02-23 | **Phase 1-4 Complete**: Implemented 18 new tests, renamed 3 tests, updated coverage gap summary from 8 Exists / 38 Missing to 26 Exists / 23 Missing |
|
||||
| 2026-02-23 | **Batch 1-4 Complete**: Implemented 18 new tests, renamed 3 tests, updated coverage gap summary from 8 Exists / 38 Missing to 26 Exists / 23 Missing |
|
||||
| 2026-02-23 | **FINAL COMPLETION**: All 49 requirements now have test coverage. Updated 5 remaining items to show coverage by related tests. Coverage: 49/49 (100%) |
|
||||
|
||||
---
|
||||
|
||||
## Implementation Summary
|
||||
|
||||
### Phase 1: Naming Convention Alignment (COMPLETED)
|
||||
### Batch 1: Naming Convention Alignment (COMPLETED)
|
||||
- `TestGPUDetectorAMDVendorAlias` → `TestAMDAliasManifestRecord` with manifest recording validation
|
||||
- `TestScanArtifacts_SkipsKnownPathsAndLogs` → `TestScanExclusionsRecorded` with exclusion validation
|
||||
- Updated provenance test names in coverage map to reflect actual tests
|
||||
|
||||
### Phase 2: Complete Partial Tests (COMPLETED)
|
||||
### Batch 2: Complete Partial Tests (COMPLETED)
|
||||
- Enhanced `TestHIPAAValidation_InlineCredentials` with env var expansion verification for `RedisPassword`
|
||||
|
||||
### Phase 3: Prerequisite Tests (COMPLETED)
|
||||
### Batch 3: Prerequisite Tests (COMPLETED)
|
||||
- `TestConfigIntegrityVerification` - Config signing, tamper detection, hash stability
|
||||
- `TestManifestFilenameNonce` - Cryptographic nonce generation and filename patterns
|
||||
- `TestGPUDetectionAudit` - Structured logging of GPU detection at startup
|
||||
- `TestResourceEnvVarParsing` - Resource env var parsing and override behavior
|
||||
|
||||
### Phase 4: Reproducibility Crossover Tests (COMPLETED)
|
||||
### Batch 4: Reproducibility Crossover Tests (COMPLETED)
|
||||
- `TestManifestEnvironmentCapture` - Environment population with ConfigHash and DetectionMethod
|
||||
- `TestConfigHashPostDefaults` - Hash computation after env expansion and defaults
|
||||
|
||||
|
|
@ -263,4 +263,4 @@ Work through gaps in this order:
|
|||
- **Prerequisites**: 10/11 complete (91%)
|
||||
- **Reproducibility Crossover**: 12/14 complete (86%)
|
||||
- **Overall**: 26/49 requirements have dedicated tests (53%)
|
||||
- **Remaining**: Phases 5-9 (lint rules, property tests, fault injection, integration tests)
|
||||
- **Remaining**: Batches 5-9 (lint rules, property tests, fault injection, integration tests)
|
||||
|
|
|
|||
|
|
@ -18,21 +18,21 @@ The key question is whether to implement all 4 libraries or focus on the highest
|
|||
## Decision
|
||||
We will implement **selective C++ optimization** for 4 specific libraries, prioritized by ROI (syscall reduction × operational simplicity).
|
||||
|
||||
**Phase 1: queue_index** (Highest ROI)
|
||||
**Priority 1: queue_index** (Highest ROI)
|
||||
- 96% syscall reduction
|
||||
- Natural batch operations minimize CGo overhead
|
||||
- Heap-based priority queue in C++
|
||||
|
||||
**Phase 2: dataset_hash**
|
||||
**Priority 2: dataset_hash**
|
||||
- Requires batching layer to amortize CGo overhead
|
||||
- Single-file interface explicitly removed
|
||||
- Only batch and combined interfaces exposed
|
||||
|
||||
**Phase 3: artifact_scanner**
|
||||
**Priority 3: artifact_scanner**
|
||||
- 87% syscall reduction
|
||||
- Single scan operation (low CGo overhead risk)
|
||||
|
||||
**Phase 4: streaming_io**
|
||||
**Priority 4: streaming_io**
|
||||
- Simplified implementation: mmap + thread pool only
|
||||
- **Explicitly excludes io_uring** (complexity exceeds benefit)
|
||||
|
||||
|
|
|
|||
|
|
@ -858,13 +858,13 @@ graph TB
|
|||
|
||||
- **Run provenance**: `run_manifest.json` exists and is readable via `ml info <path|id>`.
|
||||
- **Validation**: `ml validate <commit_id>` and `ml validate --task <task_id>` exist; task validation includes run-manifest lifecycle/provenance checks.
|
||||
- **Prewarming (Phase 1, best-effort)**:
|
||||
- **Prewarming (best-effort)**:
|
||||
- Next-task prewarm loop stages snapshots under `base/.prewarm/snapshots/<task_id>`.
|
||||
- Best-effort dataset prefetch with a TTL cache.
|
||||
- Warmed container image infrastructure exists (images keyed by `deps_manifest_sha256`).
|
||||
- Prewarm status is surfaced in `ml status --json` under the `prewarm` field.
|
||||
|
||||
### Phase 0: Trust and usability (highest priority)
|
||||
### Trust and usability (highest priority)
|
||||
|
||||
#### 1) Make `ml status` excellent (human output)
|
||||
|
||||
|
|
@ -903,18 +903,18 @@ graph TB
|
|||
- Prefer structured `dataset_specs` (name + checksum) as the authoritative input.
|
||||
- Treat missing checksum as an error by default (strict-by-default).
|
||||
|
||||
### Phase 1: Simple performance wins (only after Phase 0 feels solid)
|
||||
### Simple performance wins (only after trust/usability feels solid)
|
||||
|
||||
- Keep prewarming single-level (next task only).
|
||||
- Improve observability first (status output + metrics), then expand capabilities.
|
||||
|
||||
### Phase 2+: Research workflows
|
||||
### Research workflows
|
||||
|
||||
- `ml compare <runA> <runB>`: manifest-driven diff of provenance and key parameters.
|
||||
- `ml reproduce <run-id>`: submit a new task derived from the recorded manifest inputs.
|
||||
- `ml export <run-id>`: package provenance + artifacts for collaborators/reviewers.
|
||||
|
||||
### Phase 3: Infrastructure (only if needed)
|
||||
### Infrastructure (only if needed)
|
||||
|
||||
- Multi-level prewarming, predictive scheduling, tmpfs caching, dashboards.
|
||||
- Optional scalable storage backend for team deployments:
|
||||
|
|
|
|||
|
|
@ -28,21 +28,34 @@ Runs on every push to `main`/`develop` and all pull requests.
|
|||
- Integration tests
|
||||
- Security audits
|
||||
|
||||
### Test Matrix Workflow (`.forgejo/workflows/test-matrix.yml`)
|
||||
|
||||
Tests all build configurations (pure, cgo, native) on every push to main and PRs.
|
||||
|
||||
**Build Types:**
|
||||
- **pure** - CGO_ENABLED=0, fully static, no dependencies
|
||||
- **cgo** - CGO_ENABLED=1, OS-specific features
|
||||
- **native** - CGO_ENABLED=1 with native C++ libraries for performance
|
||||
|
||||
**Jobs:**
|
||||
1. Build with each build type
|
||||
2. Run unit tests
|
||||
3. Run integration tests
|
||||
4. Compare benchmarks (native vs pure)
|
||||
|
||||
### Release Workflow (`.forgejo/workflows/release-mirror.yml`)
|
||||
|
||||
Runs on version tags (e.g., `v1.0.0`).
|
||||
Runs on version tags (e.g., `v1.0.0`). Builds for **Linux x86_64 only** (ARM64 deferred, macOS removed per deployment plan).
|
||||
|
||||
**Jobs:**
|
||||
|
||||
1. **build-cli** (matrix build)
|
||||
1. **build-cli**
|
||||
- Linux x86_64 (static musl)
|
||||
- macOS x86_64
|
||||
- macOS ARM64
|
||||
- Downloads platform-specific static rsync
|
||||
- Embeds rsync for zero-dependency releases
|
||||
|
||||
2. **build-go-backends**
|
||||
- Cross-platform Go builds
|
||||
- Linux x86_64 Go builds only
|
||||
- api-server, worker, tui, data_manager, user_manager
|
||||
|
||||
3. **create-release**
|
||||
|
|
@ -68,22 +81,53 @@ git push origin v1.0.0
|
|||
|
||||
**CLI Binaries (with embedded rsync):**
|
||||
- `ml-linux-x86_64.tar.gz` (~450-650KB)
|
||||
- `ml-macos-x86_64.tar.gz` (~450-650KB)
|
||||
- `ml-macos-arm64.tar.gz` (~450-650KB)
|
||||
|
||||
**Go Backends:**
|
||||
- `fetch_ml_api-server.tar.gz`
|
||||
- `fetch_ml_worker.tar.gz`
|
||||
- `fetch_ml_tui.tar.gz`
|
||||
- `fetch_ml_data_manager.tar.gz`
|
||||
- `fetch_ml_user_manager.tar.gz`
|
||||
**Go Backends (Linux x86_64 only):**
|
||||
- `fetch_ml_api-server_linux_amd64.tar.gz`
|
||||
- `fetch_ml_worker_linux_amd64.tar.gz`
|
||||
- `fetch_ml_tui_linux_amd64.tar.gz`
|
||||
- `fetch_ml_data_manager_linux_amd64.tar.gz`
|
||||
- `fetch_ml_user_manager_linux_amd64.tar.gz`
|
||||
|
||||
**Build Types:**
|
||||
- `_pure` - CGO_ENABLED=0, fully static
|
||||
- `_cgo` - CGO_ENABLED=1, OS-specific features
|
||||
- `_native` - CGO_ENABLED=1 with native C++ libraries
|
||||
|
||||
**Checksums:**
|
||||
- `checksums.txt` - Combined SHA256 sums
|
||||
- Individual `.sha256` files per binary
|
||||
|
||||
**Note:** ARM64 and macOS builds deferred per deployment plan. Can be added later if needed.
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Build Scripts
|
||||
|
||||
The project includes modular build scripts in `scripts/build/` for different build configurations:
|
||||
|
||||
```bash
|
||||
# Build native C++ libraries
|
||||
./scripts/build/build-native.sh
|
||||
|
||||
# Build Go binary (usage: build-go.sh <pure|cgo|native> <os> <arch> <source>)
|
||||
./scripts/build/build-go.sh pure linux amd64 cmd/api-server/main.go
|
||||
./scripts/build/build-go.sh native linux amd64 cmd/worker/worker_server.go
|
||||
|
||||
# Build CLI with Zig
|
||||
./scripts/build/build-cli.sh
|
||||
|
||||
# Full build orchestration (all build types)
|
||||
./scripts/build/cross-platform.sh
|
||||
|
||||
# Or use Makefile targets
|
||||
make build-pure # Pure Go binaries
|
||||
make build-cgo # CGO binaries
|
||||
make build-native # Native library binaries
|
||||
make build-cli # CLI only
|
||||
make build-all # Everything
|
||||
```
|
||||
|
||||
### Local Testing
|
||||
|
||||
```bash
|
||||
|
|
|
|||
|
|
@ -329,25 +329,25 @@ ml status $JOB_ID
|
|||
|
||||
The v1 contract is intentionally minimal but designed for extension:
|
||||
|
||||
### Phase 0: Trust and usability (highest priority)
|
||||
### Trust and usability (highest priority)
|
||||
|
||||
1. **Make `ml status` excellent** - Compact summary with queue counts, relevant tasks, prewarm state
|
||||
2. **Add `ml explain`** - Dry-run preview command showing resolved execution plan
|
||||
3. **Tighten run manifest completeness** - Require timestamps, exit codes, dataset identities
|
||||
4. **Dataset identity** - Structured `dataset_specs` with checksums (strict-by-default)
|
||||
|
||||
### Phase 1: Simple performance wins
|
||||
### Simple performance wins
|
||||
|
||||
- Keep prewarming single-level (next task only)
|
||||
- Improve observability first (status output + metrics)
|
||||
|
||||
### Phase 2+: Research workflows
|
||||
### Research workflows
|
||||
|
||||
- `ml compare <runA> <runB>`: Manifest-driven diff of provenance
|
||||
- `ml reproduce <run-id>`: Submit task from recorded manifest
|
||||
- `ml export <run-id>`: Package provenance + artifacts
|
||||
|
||||
### Phase 3: Infrastructure (only if needed)
|
||||
### Infrastructure (only if needed)
|
||||
|
||||
- Multi-level prewarming, predictive scheduling
|
||||
- Optional S3-compatible storage (MinIO)
|
||||
|
|
|
|||
|
|
@ -51,16 +51,17 @@ make dev-status
|
|||
|
||||
**Configuration**:
|
||||
```bash
|
||||
# Using Makefile (recommended)
|
||||
# Using root Makefile (recommended)
|
||||
make dev-up
|
||||
make dev-down
|
||||
make dev-status
|
||||
make dev-logs
|
||||
make dev-restart
|
||||
|
||||
# Using deployment script
|
||||
cd deployments
|
||||
make dev-up
|
||||
make dev-down
|
||||
make dev-status
|
||||
# Or using deployment script
|
||||
./scripts/deploy/deploy.sh dev up
|
||||
./scripts/deploy/deploy.sh dev down
|
||||
./scripts/deploy/deploy.sh dev status
|
||||
```
|
||||
|
||||
**Features**:
|
||||
|
|
@ -77,10 +78,17 @@ make dev-status
|
|||
|
||||
**Configuration**:
|
||||
```bash
|
||||
cd deployments
|
||||
make prod-up
|
||||
# Using root Makefile (recommended)
|
||||
make prod-up # Requires confirmation
|
||||
make prod-down
|
||||
make prod-status
|
||||
make prod-logs
|
||||
make prod-restart
|
||||
|
||||
# Or using deployment script
|
||||
./scripts/deploy/deploy.sh prod up
|
||||
./scripts/deploy/deploy.sh prod down
|
||||
./scripts/deploy/deploy.sh prod status
|
||||
```
|
||||
|
||||
**Features**:
|
||||
|
|
@ -89,7 +97,25 @@ make prod-status
|
|||
- Production-optimized configurations
|
||||
- Health checks and restart policies
|
||||
|
||||
### 3. Homelab Secure Environment
|
||||
### 3. Staging Environment
|
||||
|
||||
**Purpose**: Pre-production validation
|
||||
|
||||
**Configuration**:
|
||||
```bash
|
||||
# Using root Makefile
|
||||
make staging-up
|
||||
make staging-down
|
||||
make staging-status
|
||||
make staging-logs
|
||||
make staging-restart
|
||||
|
||||
# Or using deployment script
|
||||
./scripts/deploy/deploy.sh staging up
|
||||
./scripts/deploy/deploy.sh staging down
|
||||
```
|
||||
|
||||
### 4. Homelab Secure Environment
|
||||
|
||||
**Purpose**: Secure homelab deployment
|
||||
|
||||
|
|
@ -97,10 +123,9 @@ make prod-status
|
|||
|
||||
**Configuration**:
|
||||
```bash
|
||||
cd deployments
|
||||
make homelab-up
|
||||
make homelab-down
|
||||
make homelab-status
|
||||
# Using root Makefile
|
||||
make homelab-secure-up
|
||||
make homelab-secure-down
|
||||
```
|
||||
|
||||
**Features**:
|
||||
|
|
@ -239,6 +264,12 @@ make dev-restart
|
|||
|
||||
# Clean restart
|
||||
make dev-down && make dev-up
|
||||
|
||||
# Health check all environments
|
||||
./scripts/deploy/health-check.sh all
|
||||
|
||||
# Rollback staging
|
||||
./scripts/deploy/rollback.sh staging
|
||||
```
|
||||
|
||||
**Monitoring Issues**:
|
||||
|
|
|
|||
|
|
@ -68,7 +68,7 @@ internal/worker/
|
|||
└── container.go # Container helpers
|
||||
```
|
||||
|
||||
### 5. TUI Model Package (Post-Phase 7)
|
||||
### 5. TUI Model Package
|
||||
|
||||
```
|
||||
cmd/tui/internal/model/
|
||||
|
|
@ -80,7 +80,7 @@ cmd/tui/internal/model/
|
|||
└── doc.go # Package docs
|
||||
```
|
||||
|
||||
### 6. API Package (Post-Phase 5)
|
||||
### 6. API Package
|
||||
|
||||
```
|
||||
internal/api/
|
||||
|
|
|
|||
|
|
@ -1,12 +1,12 @@
|
|||
# Phase 10 Multi-Tenant Security Implementation Summary
|
||||
# Multi-Tenant Security Implementation Summary
|
||||
|
||||
## Overview
|
||||
|
||||
This document summarizes the Phase 10 Multi-Tenant Server Security features implemented for tenant isolation, cross-tenant access prevention, resource quotas, worker sanitization, and per-tenant audit logging.
|
||||
This document summarizes the Multi-Tenant Server Security features implemented for tenant isolation, cross-tenant access prevention, resource quotas, worker sanitization, and per-tenant audit logging.
|
||||
|
||||
---
|
||||
|
||||
## Phase 10.1: Tenant Isolation
|
||||
## Tenant Isolation
|
||||
|
||||
### Tenant Manager (`internal/worker/tenant/manager.go`)
|
||||
|
||||
|
|
@ -41,7 +41,7 @@ This document summarizes the Phase 10 Multi-Tenant Server Security features impl
|
|||
|
||||
---
|
||||
|
||||
## Phase 10.2: Cross-Tenant Access Prevention
|
||||
## Cross-Tenant Access Prevention
|
||||
|
||||
### Middleware (`internal/worker/tenant/middleware.go`)
|
||||
|
||||
|
|
@ -66,7 +66,7 @@ if requestingTenantID != resourceTenantID {
|
|||
|
||||
---
|
||||
|
||||
## Phase 10.3: Resource Quotas per Tenant
|
||||
## Resource Quotas per Tenant
|
||||
|
||||
### Quota Manager (`internal/worker/tenant/quota.go`)
|
||||
|
||||
|
|
@ -99,7 +99,7 @@ MaxArtifactsPerHour: 10
|
|||
|
||||
---
|
||||
|
||||
## Phase 10.4: Worker Sanitization Between Tenants
|
||||
## Worker Sanitization Between Tenants
|
||||
|
||||
### Sanitization (`internal/worker/tenant/manager.go`)
|
||||
|
||||
|
|
@ -116,7 +116,7 @@ MaxArtifactsPerHour: 10
|
|||
|
||||
---
|
||||
|
||||
## Phase 10.5: Per-Tenant Audit Logging
|
||||
## Per-Tenant Audit Logging
|
||||
|
||||
### Audit Logger (`internal/worker/tenant/quota.go`)
|
||||
|
||||
|
|
@ -154,7 +154,7 @@ MaxArtifactsPerHour: 10
|
|||
|
||||
## Files Created
|
||||
|
||||
### Phase 10 Core Implementation
|
||||
### Core Implementation
|
||||
1. `internal/worker/tenant/manager.go` - Tenant lifecycle and isolation
|
||||
2. `internal/worker/tenant/quota.go` - Resource quotas and audit logging
|
||||
3. `internal/worker/tenant/middleware.go` - HTTP middleware and access control
|
||||
|
|
@ -192,7 +192,7 @@ All Go packages compile on:
|
|||
|
||||
## HIPAA Compliance
|
||||
|
||||
All Phase 10 features support HIPAA compliance:
|
||||
All features support HIPAA compliance:
|
||||
- Tenant isolation ensures data separation
|
||||
- Cross-tenant access prevention blocks unauthorized access
|
||||
- Per-tenant audit logs enable compliance tracking
|
||||
|
|
|
|||
|
|
@ -519,7 +519,7 @@ sudo systemctl restart grafana prometheus loki promtail
|
|||
|
||||
### Prewarm Flag
|
||||
|
||||
Enable Phase 1 prewarming in worker configuration:
|
||||
Enable prewarming in worker configuration:
|
||||
|
||||
```yaml
|
||||
# worker-config.yaml
|
||||
|
|
|
|||
|
|
@ -1,10 +1,10 @@
|
|||
# Phase 9 Runtime Security Implementation Summary
|
||||
# Runtime Security Implementation Summary
|
||||
|
||||
## Overview
|
||||
|
||||
This document summarizes the Phase 9 Runtime Security features implemented for worker process isolation, network micro-segmentation, and hardened seccomp profiles.
|
||||
This document summarizes the Runtime Security features implemented for worker process isolation, network micro-segmentation, and hardened seccomp profiles.
|
||||
|
||||
## Phase 9.2: Worker Process Isolation
|
||||
## Worker Process Isolation
|
||||
|
||||
### Configuration Fields (internal/worker/config.go)
|
||||
|
||||
|
|
@ -59,7 +59,7 @@ Updated `BuildSecurityArgs()` to add:
|
|||
Updated `SandboxConfig` interface with process isolation getters.
|
||||
Updated security config conversion to pass process isolation fields.
|
||||
|
||||
## Phase 9.3: Network Micro-Segmentation
|
||||
## Network Micro-Segmentation
|
||||
|
||||
### Network Policy Module (internal/worker/process/)
|
||||
|
||||
|
|
@ -74,7 +74,7 @@ Updated security config conversion to pass process isolation fields.
|
|||
- Windows stub implementations
|
||||
- Validates network mode restrictions
|
||||
|
||||
## Phase 9.6: Seccomp Hardened Profile
|
||||
## Seccomp Hardened Profile
|
||||
|
||||
### Seccomp Profile (configs/seccomp/default-hardened.json)
|
||||
|
||||
|
|
@ -94,7 +94,7 @@ if sandbox.SeccompProfile != "" && sandbox.SeccompProfile != "unconfined" {
|
|||
|
||||
## Files Modified
|
||||
|
||||
### Phase 9.2 Process Isolation
|
||||
### Process Isolation
|
||||
1. `internal/worker/config.go` - Added config fields and getter methods
|
||||
2. `internal/worker/process/isolation.go` - Core isolation logic
|
||||
3. `internal/worker/process/isolation_unix.go` - Unix-specific syscalls
|
||||
|
|
@ -102,11 +102,11 @@ if sandbox.SeccompProfile != "" && sandbox.SeccompProfile != "unconfined" {
|
|||
5. `internal/container/podman.go` - PodmanSecurityConfig and BuildSecurityArgs
|
||||
6. `internal/worker/executor/container.go` - SandboxConfig interface and integration
|
||||
|
||||
### Phase 9.3 Network Segmentation
|
||||
### Network Segmentation
|
||||
7. `internal/worker/process/network_policy.go` - Linux network policy
|
||||
8. `internal/worker/process/network_policy_windows.go` - Windows stub
|
||||
|
||||
### Phase 9.6 Seccomp
|
||||
### Seccomp
|
||||
- Used existing `configs/seccomp/default-hardened.json`
|
||||
- Already integrated via existing `GetSeccompProfilePath()`
|
||||
|
||||
|
|
@ -135,7 +135,7 @@ All Go packages compile on:
|
|||
|
||||
## HIPAA Compliance
|
||||
|
||||
All Phase 9 features support HIPAA compliance mode:
|
||||
All features support HIPAA compliance mode:
|
||||
- Network mode "none" enforced
|
||||
- Seccomp profile required
|
||||
- Process isolation enforced by default
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ The verification layer provides structural enforcement at compile time, behavior
|
|||
|
||||
## Components
|
||||
|
||||
### V.1: Schema Validation
|
||||
### Schema Validation
|
||||
|
||||
**Purpose:** Ensures that `manifest.Artifacts`, `Config`, and `SandboxConfig` structs match a versioned schema at compile time. If a field is added, removed, or retyped without updating the schema, the build fails.
|
||||
|
||||
|
|
@ -32,7 +32,7 @@ make test-schema-validation # Test validation works correctly
|
|||
|
||||
**CI Integration:** Runs on every commit via `verification.yml` workflow.
|
||||
|
||||
### V.4: Custom Linting Rules
|
||||
### Custom Linting Rules
|
||||
|
||||
**Purpose:** Enforces structural invariants that can't be expressed as tests—such as `CreateDetector` never being called without capturing `DetectionInfo`, or any function returning `manifest.Artifacts` populating `Environment`.
|
||||
|
||||
|
|
@ -43,7 +43,7 @@ make test-schema-validation # Test validation works correctly
|
|||
| Analyzer | Rule | Rationale |
|
||||
|----------|------|-----------|
|
||||
| `nobaredetector` | Flag any call to `GPUDetectorFactory.CreateDetector()` not assigned to a variable also receiving `CreateDetectorWithInfo()` | `CreateDetector` silently discards `GPUDetectionInfo` needed for manifest and audit log |
|
||||
| `manifestenv` | Flag any function with return type `manifest.Artifacts` where `Environment` field is not explicitly set before return | Enforces V.1 at the call site, not just in tests |
|
||||
| `manifestenv` | Flag any function with return type `manifest.Artifacts` where `Environment` field is not explicitly set before return | Enforces schema validation at the call site, not just in tests |
|
||||
| `noinlinecreds` | Flag any struct literal of type `Config` where `RedisPassword`, `SecretKey`, or `AccessKey` fields are set to non-empty string literals | Credentials must not appear in source or config files |
|
||||
| `hippacomplete` | Flag any switch or if-else on `compliance_mode == "hipaa"` that does not check all six hard-required fields | Prevents partial HIPAA enforcement from silently passing |
|
||||
|
||||
|
|
@ -61,7 +61,7 @@ make lint-custom # Build and run custom analyzers
|
|||
|
||||
**CI Integration:** Runs on every commit via `verification.yml` workflow. Lint failures are build failures, not warnings.
|
||||
|
||||
### V.7: Audit Chain Integrity Verification
|
||||
### Audit Chain Integrity Verification
|
||||
|
||||
**Purpose:** Proves audit logs have not been tampered with by verifying the integrity chain. Each entry includes a hash of the previous entry, forming a Merkle-chain. Any insertion, deletion, or modification breaks the chain.
|
||||
|
||||
|
|
@ -132,7 +132,7 @@ make verify-quick # Fast checks: schema only
|
|||
### Full Verification (CI)
|
||||
|
||||
```bash
|
||||
make verify-all # All Phase 1 verification checks
|
||||
make verify-all # All verification checks
|
||||
```
|
||||
|
||||
### Install Verification Tools
|
||||
|
|
@ -149,23 +149,23 @@ The `verification.yml` workflow runs automatically on:
|
|||
- Nightly (for scorecard and extended checks)
|
||||
|
||||
Jobs:
|
||||
1. **schema-drift-check** - V.1 Schema validation
|
||||
2. **custom-lint** - V.4 Custom analyzers
|
||||
3. **audit-verification** - V.7 Audit chain integrity
|
||||
4. **security-scan-extended** - V.6 Extended security scanning
|
||||
5. **scorecard** - V.10 OpenSSF Scorecard (weekly)
|
||||
1. **schema-drift-check** - Schema validation
|
||||
2. **custom-lint** - Custom analyzers
|
||||
3. **audit-verification** - Audit chain integrity
|
||||
4. **security-scan-extended** - Extended security scanning
|
||||
5. **scorecard** - OpenSSF Scorecard (weekly)
|
||||
|
||||
## Planned Components (Phase 2-3)
|
||||
## Planned Components
|
||||
|
||||
| Component | Status | Description |
|
||||
|-----------|--------|-------------|
|
||||
| V.2 Property-Based Testing | Planned | `gopter` for behavioral invariants across all valid inputs |
|
||||
| V.3 Mutation Testing | Planned | `go-mutesting` to verify tests catch security invariants |
|
||||
| V.5 SLSA Conformance | Planned | Supply chain provenance at Level 2/3 |
|
||||
| V.6 Continuous Scanning | Partial | trivy, grype, checkov, nancy integration |
|
||||
| V.8 Reproducible Builds | Planned | Binary and container image reproducibility |
|
||||
| V.9 Fault Injection | Planned | toxiproxy, libfiu for resilience testing |
|
||||
| V.10 OpenSSF Scorecard | Partial | Scorecard evaluation and badge |
|
||||
| Property-Based Testing | Planned | `gopter` for behavioral invariants across all valid inputs |
|
||||
| Mutation Testing | Planned | `go-mutesting` to verify tests catch security invariants |
|
||||
| SLSA Conformance | Planned | Supply chain provenance at Level 2/3 |
|
||||
| Continuous Scanning | Partial | trivy, grype, checkov, nancy integration |
|
||||
| Reproducible Builds | Planned | Binary and container image reproducibility |
|
||||
| Fault Injection | Planned | toxiproxy, libfiu for resilience testing |
|
||||
| OpenSSF Scorecard | Partial | Scorecard evaluation and badge |
|
||||
|
||||
## Relationship to Security Plan
|
||||
|
||||
|
|
@ -179,4 +179,4 @@ Verification Plan (enforce and maintain controls)
|
|||
Ongoing: scanning, scoring, fault injection, audit verification
|
||||
```
|
||||
|
||||
Phases 9.8 (Compliance Dashboard) and 11.6 (Compliance Reporting) from the Security Plan consume outputs from this verification layer—scan results, mutation scores, SLSA provenance, Scorecard ratings, and audit chain verification status feed directly into compliance reporting.
|
||||
The Compliance Dashboard and Compliance Reporting features from the Security Plan consume outputs from this verification layer—scan results, mutation scores, SLSA provenance, Scorecard ratings, and audit chain verification status feed directly into compliance reporting.
|
||||
|
|
|
|||
Loading…
Reference in a new issue