stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity

feat: Add guild charters and task boards for various components
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details

Browse Source 
- Introduced guild charters for Scanner Deno, PHP, Ruby, Native, WebService, Java, Surface.Env, Surface.FS, Surface.Secrets, Surface.Validation, UI, Zastava Observer, Zastava Webhook, Zastava Core, and Plugin Platform.
- Each charter outlines the mission, scope, required reading, and working agreements for the respective guilds.
- Created task boards for Surface.Env, Surface.FS, Surface.Secrets, Surface.Validation, and Zastava components to track progress and dependencies.
- Ensured all documents emphasize determinism, offline readiness, security, and integration with shared Surface libraries.
This commit is contained in:
master
2025-11-01 02:21:46 +02:00
parent e5629454cf
commit 66cb6c4b8a
227 changed files with 9913 additions and 6210 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
docs/modules/scanner/AGENTS.md
View File

@@ -1,22 +1,34 @@
# Scanner agent guide
## Mission
Scanner analyses container images layer-by-layer, producing deterministic SBOM fragments, diffs, and signed reports.
## Key docs
- [Module README](./README.md)
- [Architecture](./architecture.md)
- [Implementation plan](./implementation_plan.md)
- [Task board](./TASKS.md)
## How to get started
1. Open ../../implplan/SPRINTS.md and locate the stories referencing this module.
2. Review ./TASKS.md for local follow-ups and confirm status transitions (TODO → DOING → DONE/BLOCKED).
3. Read the architecture and README for domain context before editing code or docs.
4. Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan.
## Guardrails
- Honour the Aggregation-Only Contract where applicable (see ../../ingestion/aggregation-only-contract.md).
- Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts.
- Keep Offline Kit parity in mind—document air-gapped workflows for any new feature.
- Update runbooks/observability assets when operational characteristics change.
# Scanner agent guide
## Mission
Scanner analyses container images layer-by-layer, producing deterministic SBOM fragments, diffs, and signed reports.
## Key docs
- [Module README](./README.md)
- [Architecture](./architecture.md)
- [Implementation plan](./implementation_plan.md)
- [Task board](./TASKS.md)
## How to get started
1. Open ../../implplan/SPRINTS.md and locate the stories referencing this module.
2. Review ./TASKS.md for local follow-ups and confirm status transitions (TODO → DOING → DONE/BLOCKED).
3. Read the architecture and README for domain context before editing code or docs.
4. Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan.
## Guardrails
- Honour the Aggregation-Only Contract where applicable (see ../../ingestion/aggregation-only-contract.md).
- Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts.
- Keep Offline Kit parity in mind—document air-gapped workflows for any new feature.
- Update runbooks/observability assets when operational characteristics change.
## Required Reading
- `docs/modules/scanner/README.md`
- `docs/modules/scanner/architecture.md`
- `docs/modules/scanner/implementation_plan.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

147
docs/modules/scanner/design/surface-env.md Normal file
View File

@@ -0,0 +1,147 @@
# Surface.Env Design (Epic: SURFACE-SHARING)
> **Status:** Draft v1.0 — aligns with tasks `SURFACE-ENV-01..05`, `SCANNER-ENV-01..03`, `ZASTAVA-ENV-01..02`, `OPS-ENV-01`.
>
> **Audience:** Scanner Worker/WebService engineers, Zastava engineers, DevOps/Ops teams.
## 1. Goals
Surface.Env centralises configuration discovery for every component that touches the shared Scanner “surface” (cache, manifests, secrets). The library replaces ad-hoc environment lookups with a deterministic, validated contract that:
1. Works identically across Scanner Worker, Scanner WebService, BuildX plug-ins, Zastava Observer/Webhook, and future consumers (Scheduler planners, CLI runners).
2. Supports both connected and air-gapped deployments with clear defaults.
3. Records configuration intent (tenant isolation, cache limits, TLS, feature flags) so Surface.Validation can enforce preconditions before any work executes.
## 2. Architecture Overview
```
+-----------------------+
| Host (Worker/WebSvc) |
| - IConfiguration |
| - ILogger |
| |
| +-----------------+ |
| | SurfaceEnv | | loads env vars / config file
| | - Provider |--+------------------------------+
| | - Validators | |
| +-----------------+ |
| | |
| | IResolvedSurfaceConfiguration |
| v v
| Surface.FS / Surface.Secrets / Surface.Validation consumers
+-------------------------------------------------------------
```
Surface.Env exposes `ISurfaceEnvironment` which returns an immutable `SurfaceEnvironmentSettings` record. Hosts call `SurfaceEnvBuilder.Build()` during startup, passing optional configuration overrides (for example, Helm chart values). The builder resolves environment variables, applies defaults, and executes Surface.Validation rules before handing settings to downstream services.
## 3. Configuration Schema
### 3.1 Common keys
| Variable | Description | Default | Notes |
|----------|-------------|---------|-------|
| `SCANNER_SURFACE_FS_ENDPOINT` | Base URI for Surface.FS service (RustFS, S3-compatible). | _required_ | e.g. `https://surface-cache.svc.cluster.local`. Zastava uses `ZASTAVA_SURFACE_FS_ENDPOINT`; when absent, falls back to scanner value. |
| `SCANNER_SURFACE_FS_BUCKET` | Bucket/container name used for manifests and artefacts. | `surface-cache` | Must be unique per tenant. |
| `SCANNER_SURFACE_FS_REGION` | Optional region (S3-style). | `null` | Required for AWS S3. |
| `SCANNER_SURFACE_CACHE_ROOT` | Local filesystem directory for warm caches. | `/var/lib/stellaops/surface` | Should reside on fast SSD. |
| `SCANNER_SURFACE_CACHE_QUOTA_MB` | Soft limit for local cache usage. | `4096` | Enforced by Surface.FS eviction policy. |
| `SCANNER_SURFACE_TLS_CERT_PATH` | Path to PEM bundle for mutual TLS with Surface.FS. | `null` | If provided, library loads cert/key pair. |
| `SCANNER_SURFACE_TENANT` | Tenant identifier used for cache namespaces. | derived from Authority token | Can be overridden for multi-tenant workers. |
| `SCANNER_SURFACE_PREFETCH_ENABLED` | Toggle surface prefetch threads. | `false` | If `true`, Worker prefetches manifests before analyzer stage. |
| `SCANNER_SURFACE_FEATURES` | Comma-separated feature switches. | `""` | e.g. `validation,prewarm,runtime-diff`. |
### 3.2 Secrets provider keys
| Variable | Description | Notes |
|----------|-------------|-------|
| `SCANNER_SURFACE_SECRETS_PROVIDER` | Provider ID (`kubernetes`, `file`, `inline`). | Controls Surface.Secrets back-end. |
| `SCANNER_SURFACE_SECRETS_ROOT` | Path or secret namespace. | Example: `/etc/stellaops/secrets` for file provider. |
| `SCANNER_SURFACE_SECRETS_TENANT` | Tenant override for secret lookup. | Defaults to `SCANNER_SURFACE_TENANT`. |
### 3.3 Zastava-specific keys
Zastava containers read the same primary variables but may override names under the `ZASTAVA_` prefix (e.g., `ZASTAVA_SURFACE_CACHE_ROOT`, `ZASTAVA_SURFACE_FEATURES`). Surface.Env automatically checks component-specific prefixes before falling back to the scanner defaults.
### 3.4 Configuration precedence
1. Explicit overrides passed to `SurfaceEnvBuilder` (e.g., from appsettings).
2. Component-specific env (e.g., `ZASTAVA_SURFACE_FS_ENDPOINT`).
3. Scanner global env (e.g., `SCANNER_SURFACE_FS_ENDPOINT`).
4. `SurfaceEnvDefaults.json` (shipped with library for sensible defaults).
5. Emergency fallback values defined in code (only for development scenarios).
## 4. API Surface
```csharp
public interface ISurfaceEnvironment
{
SurfaceEnvironmentSettings Settings { get; }
IReadOnlyDictionary<string, string> RawVariables { get; }
}
public sealed record SurfaceEnvironmentSettings
(
Uri SurfaceFsEndpoint,
string SurfaceFsBucket,
string? SurfaceFsRegion,
DirectoryInfo CacheRoot,
int CacheQuotaMegabytes,
X509Certificate2Collection? ClientCertificates,
string Tenant,
bool PrefetchEnabled,
IReadOnlyCollection<string> FeatureFlags,
SecretProviderConfiguration Secrets,
IDictionary<string,string> ComponentOverrides
);
```
Consumers access `ISurfaceEnvironment.Settings` and pass the record into Surface.FS / Surface.Secrets factories. The interface memoises results so repeated access is cheap.
## 5. Validation
Surface.Env invokes the following validators (implemented in Surface.Validation):
1. **EndpointValidator** – ensures endpoint URI is absolute HTTPS and not localhost in production.
2. **CacheQuotaValidator** – verifies quota > 0 and below host max.
3. **FilesystemValidator** – checks cache root exists/writable; attempts to create directory if missing.
4. **SecretsProviderValidator** – ensures provider-specific settings (e.g., Kubernetes namespace) are present.
5. **FeatureFlagValidator** – warns on unknown feature flag tokens.
Failures throw `SurfaceEnvironmentException` with error codes (`SURFACE_ENV_MISSING_ENDPOINT`, `SURFACE_ENV_CACHE_DIR_UNWRITABLE`, etc.). Hosts log the error and fail fast during startup.
## 6. Integration Guidance
- **Scanner Worker**: call `services.AddSurfaceEnvironment()` in `Program.cs` before registering analyzers. Pass `hostContext.Configuration.GetSection("Surface")` for overrides.
- **Scanner WebService**: build environment during startup, then expose selected values via diagnostics (`/internal/surface` when diagnostics enabled).
- **Zastava Observer/Webhook**: use the same builder; ensure Helm charts set `ZASTAVA_` variables.
- **Scheduler Planner (future)**: treat Surface.Env as read-only input; do not mutate settings.
## 7. Security & Observability
- Never log raw secrets; Surface.Env redacts values by default.
- Emit metric `surface_env_validation_total{status}` to observe validation outcomes.
- Provide `/metrics` gauge for cache quota/residual via Surface.FS integration.
## 8. Offline & Air-Gap Support
- Defaults assume no public network access; endpoints should point to internal RustFS or S3-compatible system.
- Offline kit templates supply env files under `offline/scanner/surface-env.env`.
- Document steps in `docs/modules/devops/runbooks/zastava-deployment.md` and `offline-kit` tasks for synchronising env values.
## 9. Testing Strategy
- Unit tests for each resolver/validator.
- Integration tests for Worker & Observer verifying that missing configuration causes deterministic failures.
- Golden tests for configuration precedence (component overrides, defaults).
## 10. Open Questions / Future Work
- Dynamic refresh of environment (watch ConfigMap) is out of scope for v1.
- Evaluate adding support for environment discovery via `IConfiguration` only (no env vars) for Windows service deployments.
## 11. References
- Surface.FS Design (`docs/modules/scanner/design/surface-fs.md`)
- Surface.Secrets Design (`docs/modules/scanner/design/surface-secrets.md`)
- Surface.Validation Design (`docs/modules/scanner/design/surface-validation.md`)
- AirGap mode overview (`docs/airgap/airgap-mode.md`)

130
docs/modules/scanner/design/surface-fs.md Normal file
View File

@@ -0,0 +1,130 @@
# Surface.FS Design (Epic: SURFACE-SHARING)
> **Status:** Draft v1.0 — aligns with tasks `SURFACE-FS-01..06`, `SCANNER-SURFACE-01..05`, `ZASTAVA-SURFACE-01..02`, `SCHED-SURFACE-01`, `OPS-SECRETS-01..02`.
>
> **Audience:** Scanner Worker/WebService, Zastava, Scheduler, DevOps.
## 1. Purpose
Surface.FS provides a unified content-addressable cache for Scanner-derived artefacts (layer manifests, entry traces, SBOM fragments, runtime deltas). It enables:
- Sharing scan results between Worker, WebService, Zastava Observer/Webhook, Scheduler planners, Export Center, and future CLI operations.
- Deterministic reproduction of scan evidence (manifests and payloads) in both connected and air-gapped environments.
- Efficient data movement by storing manifests once and referencing them via stable pointers.
## 2. Core Concepts
### 2.1 Artefact Key
Each artefact is addressed by a tuple `(tenant, surfaceKind, contentDigest)` where `contentDigest` is a SHA256 of the canonical payload. `surfaceKind` identifies artefact type (see Manifest schema below).
### 2.2 Manifest
Manifests describe the artefact metadata and storage pointers. They are stored in the `surface-manifests` bucket and fetched by consumers before retrieving bulk data.
```json
{
"schema": "stellaops.surface.manifest@1",
"tenant": "acme",
"kind": "layer-entry-trace",
"digest": "sha256:ab12...",
"createdAt": "2025-10-29T12:00:00Z",
"expiresAt": "2025-11-05T12:00:00Z",
"source": {
"scannerBuild": "stellaops/scanner@sha256:deadbeef",
"imageDigest": "sha256:cafe...",
"scanId": "scan-1234"
},
"storage": {
"bucket": "surface-cache",
"objectKey": "tenants/acme/layer-entry-trace/sha256/ab/12/.../payload.json.zst",
"sizeBytes": 524288,
"contentType": "application/json+zstd"
},
"integrity": {
"hash": "sha256:ab12...",
"signature": null
}
}
```
### 2.3 Payload Storage
Large payloads (SBOM fragments, entry traces, runtime events) live in the same object store as manifests (RustFS/S3). Manifests record relative paths so offline bundles can copy both manifest and payload without modification.
## 3. APIs
Surface.FS exposes a gRPC/HTTP API consumed by .NET clients:
| Method | Description |
|--------|-------------|
| `PutManifest(PutManifestRequest)` | Stores manifest + optional payload. Idempotent via `digest`. |
| `GetManifest(GetManifestRequest)` | Returns manifest metadata; 404 if missing. |
| `GetPayload(GetPayloadRequest)` | Streams payload bytes (optionally decompressing). |
| `ListManifests(ListManifestRequest)` | Enumerates manifests for tenant/kind with pagination. |
| `DeleteManifest(DeleteManifestRequest)` | (Optional) Removes manifest/payload based on retention policies. |
.NET client wraps these calls and handles retries using Polly policies.
## 4. Library Responsibilities
Surface.FS library for .NET hosts provides:
- `ISurfaceManifestWriter` / `ISurfaceManifestReader` interfaces.
- Content-addressed path builder (`SurfacePathBuilder`).
- Tenant namespace isolation and bucket configuration (via Surface.Env).
- Local cache management (using `SCANNER_SURFACE_CACHE_ROOT` and quota).
- Metrics: `surface_manifest_put_seconds`, `surface_manifest_cache_hit_total`, etc.
## 5. Retention & Eviction
- Manifests include optional `expiresAt`; Worker defaults to 30 days for SBOM fragments, 7 days for entry traces.
- Background job `SurfaceCacheMaintenanceService` evicts local cache entries exceeding quota, oldest-first.
- Object storage retention policies are managed by DevOps; library exposes metrics but does not auto-delete unless instructed.
## 6. Offline Kit Handling
Offline kits include:
```
offline/surface/
manifests/
tenants/<tenant>/<kind>/<digest>.json
payloads/
tenants/<tenant>/<kind>/<digest>.json.zst
manifest-index.json
```
Import script calls `PutManifest` for each manifest, verifying digests. This enables Zastava and Scheduler running offline to consume cached data without re-scanning.
## 7. Security & Tenancy
- Tenant ID is mandatory; Surface.Validation enforces match with Authority token.
- Manifests/payloads stored in tenant-specific prefixes to prevent leakage.
- Optional manifest signing (future) will use `Surface.Secrets` to load signing keys.
- TLS enforced between hosts and Surface.FS endpoint; certificate pins configured via Surface.Env.
## 8. Observability
- Logs include manifest SHA, tenant, and kind; payload paths truncated for brevity.
- Metrics exported via Prometheus with labels `{tenant, kind, result}`.
- Tracing spans: `surface.fs.put`, `surface.fs.get`, `surface.fs.cache`.
## 9. Testing Strategy
- Unit tests for path builder, manifest serializer, and local cache eviction.
- Integration tests using embedded RustFS or MinIO container to validate API interactions.
- Offline kit tests verifying export/import cycle round-trips manifests and payloads.
## 10. Future Enhancements
- Manifest signing (DSSE) to support tamper detection in hostile environments.
- Differential manifests to optimise large SBOM updates.
- Cross-region replication for multi-site deployments.
## 11. References
- Surface.Env Design (`docs/modules/scanner/design/surface-env.md`)
- Surface.Secrets Design (`docs/modules/scanner/design/surface-secrets.md`)
- Surface.Validation Design (`docs/modules/scanner/design/surface-validation.md`)
- Zastava Deployment Runbook (`docs/modules/devops/runbooks/zastava-deployment.md`)

121
docs/modules/scanner/design/surface-secrets.md Normal file
View File

@@ -0,0 +1,121 @@
# Surface.Secrets Design (Epic: SURFACE-SHARING)
> **Status:** Draft v1.0 — aligns with tasks `SURFACE-SECRETS-01..06`, `SCANNER-SECRETS-01..03`, `ZASTAVA-SECRETS-01..02`, `OPS-SECRETS-01..02`.
>
> **Audience:** Scanner/Zastava engineers, Security Guild, DevOps/Ops teams.
## 1. Goals
Surface.Secrets standardises how Scanner, Zastava, Scheduler, and related services obtain credentials and sensitive material required for surface operations (registry pull secrets, CAS tokens, manifest signing keys). Key requirements:
- Consistent, pluggable providers (Kubernetes Secret, file, inline, future vaults).
- Deterministic lookup keyed by tenant/component to avoid accidental leakage.
- Integration with Surface.Env & Surface.Validation for configuration and pre-flight checks.
- Minimal in-memory exposure; secrets wrapped in secure handles with automatic disposal.
## 2. Secret Types
| Secret Type | Description | Example Consumers |
|-------------|-------------|-------------------|
| `cas-access` | Credentials for RustFS/S3 object storage (access key/secret, session token). | Scanner Worker/WebService, Zastava Observer/Webhook |
| `registry` | Container registry auth (username/password or token). | Scanner Worker (pulling layers for SBOM) |
| `attestation` | DSSE signing key material, Rekor API tokens. | Scanner WebService (delegation), Attestor (future integration) |
| `tls` | Client TLS certificates for Surface.FS or other services. | Scanner Worker, Zastava Observer |
Additional secret types can be registered via `ISurfaceSecretTypeRegistry`.
## 3. Provider Model
```csharp
public interface ISurfaceSecretProvider
{
ValueTask<SurfaceSecretHandle> GetAsync(SurfaceSecretRequest request, CancellationToken ct = default);
}
public sealed record SurfaceSecretRequest
(
string Tenant,
string Component, // e.g. "Scanner.Worker"
string SecretType, // e.g. "cas-access"
string? Name // optional override (e.g., "primary", "mirror-eu")
);
```
### 3.1 Built-in providers
1. **Kubernetes** – Reads from `Secret` objects. Configuration:
- `namespace`: derived from `SCANNER_SURFACE_SECRETS_ROOT` or component override.
- Secret name format: `surface-{tenant}-{component}-{secretType}`.
- Supports key mapping (e.g., `accessKey`, `secretKey`, `sessionToken`).
2. **File** – Loads JSON/YAML files from a directory (for offline kit, dev). File path derived from root + tenant/component.
3. **Inline** – Accepts base64 encoded JSON from env (useful for tests).
### 3.2 Secret Handle
`SurfaceSecretHandle` exposes typed accessors (`AsCredentials()`, `AsTlsCertificate()`) and ensures sensitive data is cleared when disposed.
## 4. Configuration
Surface.Env supplies provider configuration (`SecretsProviderConfiguration`). Example:
```json
{
"provider": "kubernetes",
"namespace": "stellaops-runtime",
"prefix": "surface-",
"fallbackProvider": "file",
"file": {
"root": "/etc/stellaops/secrets"
}
}
```
Fallback provider allows offline development (use file provider if K8s secret missing).
## 5. Validation
Surface.Validation supplies validators:
- `SecretProviderValidator` – ensures provider ID is known; checks required configuration (namespace/root).
- `SecretExistenceValidator` – optional check verifying required secret types exist at startup (configurable list).
- `SecretRotationValidator` – warns when secrets are older than rotation window (uses metadata stored in provider).
Failures produce error codes (`SURFACE_SECRET_PROVIDER_UNKNOWN`, `SURFACE_SECRET_MISSING`, `SURFACE_SECRET_STALE`).
## 6. Security Considerations
- Secrets returned as `SecureString`/byte arrays; never log values.
- Kubernetes provider caches secrets in-memory with TTL (default 10 minutes) to reduce API calls; cache invalidated when `generation` changes.
- File provider enforces permissions (`0600`); rejects world-readable files.
- Inline provider meant for tests only; flag `Surface:Secrets:AllowInline` enables it explicitly.
## 7. Offline & Air-Gap Support
- Offline kits include `offline/secrets/` with encrypted archive plus manifest file enumerating secret metadata (tenant, component, type, checksum).
- Import script decrypts archive using site-specific key and populates file provider root.
- Documented workflow lives in `ops/offline-kit/TASKS.md` and associated runbooks.
## 8. Observability
- Metrics: `surface_secrets_requests_total{provider,result}`.
- Logs: only log secret identifiers, never values.
- Traces: `surface.secrets.get` span showing provider latency.
## 9. Testing Strategy
- Unit tests per provider with fake backends.
- Integration tests in Scanner/Zastava verifying provider selection, fallback, and rotation.
- Security tests ensuring secrets aren’t leaked in logs or exceptions.
## 10. Future Enhancements
- Support for HashiCorp Vault / AWS Secrets Manager providers.
- Built-in DSSE signing key management for Attestor/Signer.
- Automatic rotation notifications via Notifier.
## 11. References
- `docs/modules/scanner/design/surface-env.md`
- `docs/modules/scanner/design/surface-fs.md`
- `docs/modules/scanner/design/surface-validation.md`
- `docs/modules/airgap/airgap-mode.md`

99
docs/modules/scanner/design/surface-validation.md Normal file
View File

@@ -0,0 +1,99 @@
# Surface.Validation Design (Epic: SURFACE-SHARING)
> **Status:** Draft v1.0 — aligns with tasks `SURFACE-VAL-01..05`, `LANG-SURFACE-01..03`, `ENTRYTRACE-SURFACE-01..02`, `ZASTAVA-SURFACE-02`, `SCANNER-SECRETS-01..03`.
>
> **Audience:** Engineers integrating Surface Env/FS/Secrets, QA guild, Security guild.
## 1. Objectives
Surface.Validation provides a shared validator framework to ensure all surface consumers meet configuration and data preconditions before performing work. It prevents subtle runtime errors by failing fast with actionable diagnostics.
## 2. Core Interfaces
```csharp
public interface ISurfaceValidator
{
ValueTask<ValidationResult> ValidateAsync(SurfaceValidationContext context, CancellationToken ct = default);
}
public sealed record SurfaceValidationContext
(
SurfaceEnvironmentSettings Environment,
IServiceProvider Services,
string ComponentName
);
public sealed record ValidationResult
(
bool IsSuccess,
IReadOnlyCollection<SurfaceValidationIssue> Issues
);
public sealed record SurfaceValidationIssue
(
string Code,
string Message,
SurfaceValidationSeverity Severity,
string? Hint = null
);
```
Validators register with DI (`services.AddSurfaceValidation()`). Hosts call `ISurfaceValidatorRunner.RunAllAsync()` during startup and periodically (optional) to re-check configuration.
## 3. Built-in Validators
| Code | Severity | Description |
|------|----------|-------------|
| `SURFACE_ENV_MISSING_ENDPOINT` | Error | Raised when `SurfaceFsEndpoint` absent. |
| `SURFACE_ENV_CACHE_DIR_UNWRITABLE` | Error | Cache root not writable or disk full. |
| `SURFACE_SECRET_MISSING` | Error | Secret provider cannot locate required secret type. |
| `SURFACE_SECRET_STALE` | Warning | Secret older than rotation window. |
| `SURFACE_FS_ENDPOINT_REACHABILITY` | Error | HEAD request to Surface.FS endpoint failed. |
| `SURFACE_FS_BUCKET_MISMATCH` | Error | Provided bucket does not exist / lacks permissions. |
| `SURFACE_FEATURE_UNKNOWN` | Warning | Feature flag not recognised. |
| `SURFACE_TENANT_MISMATCH` | Error | Tenant from environment differs from Authority token tenant. |
Validation pipeline stops on the first error (severity `Error`) unless `Surface:Validation:ContinueOnError=true` is set (useful for diagnostics mode).
## 4. Extensibility
Consumers can register custom validators:
```csharp
services.AddSurfaceValidation(builder =>
builder.AddValidator<RegistryCredentialsValidator>()
.AddValidator<RuntimeCacheWarmupValidator>());
```
Validators can access DI services (e.g., HttpClient, Authority token provider) through the context. To avoid long-running checks, recommended max validation time is 500ms per validator.
## 5. Reporting & Observability
- Results exposed via `ISurfaceValidationReporter` (default logs structured JSON to `Validation` category).
- Metrics: `surface_validation_issues_total{code,severity}`.
- Optional debug endpoint `/internal/surface/validation` (Scanner WebService) returns last validation run.
## 6. Integration Guidelines
- **Scanner Worker/WebService**: fail startup if any error-level issue occurs; log warnings but continue running.
- **Zastava Webhook**: treat validation errors as fatal (webhook should not enforce policies when surface preconditions fail). Display validation error summary in `/readyz` response to aid debugging.
- **Analysers**: call `SurfaceValidation.Ensure()` before executing heavy work to catch misconfiguration during integration tests.
## 7. Testing Strategy
- Unit tests for built-in validators using in-memory providers.
- Integration tests in Scanner/Zastava verifying validators run during startup and produce expected outcomes.
- Negative tests simulating missing secrets, unreachable endpoints, or mismatched tenants.
## 8. Error Handling & Remediation
- Each issue includes a hint describing remediation steps (e.g., “Verify `SCANNER_SURFACE_FS_ENDPOINT` is reachable from worker nodes”).
- DevOps runbooks should reference issue codes in troubleshooting sections.
- `surface_validation.json` file stored alongside application logs summarises the last run for offline support.
## 9. References
- `docs/modules/scanner/design/surface-env.md`
- `docs/modules/scanner/design/surface-fs.md`
- `docs/modules/scanner/design/surface-secrets.md`
- `docs/modules/devops/runbooks/zastava-deployment.md`