115 lines
5.2 KiB
Markdown
115 lines
5.2 KiB
Markdown
# Security boundaries (platform-level)
|
|
|
|
This document describes the baseline security boundaries expected across StellaOps modules. Module dossiers may impose stricter requirements.
|
|
|
|
## Authentication and authorization
|
|
|
|
All externally reachable services are expected to enforce:
|
|
1. Token validation (short-lived, tenant-scoped access tokens).
|
|
2. Sender constraints where configured (DPoP / mTLS).
|
|
3. Scope-based authorization (least privilege).
|
|
4. Tenant isolation: requests and data access are filtered by tenant context.
|
|
|
|
### Hard gates (typical examples)
|
|
|
|
Exact gates are module-specific, but common patterns include:
|
|
- **Authority**: nonce-based sender constraints (DPoP), strict token lifetimes, tenant-scoped issuance, and rate limiting.
|
|
- **Signing/attestation services**: narrow scopes, service identity requirements (often mTLS), and verification of the artifact being signed/attested (for example digest checks) before producing evidence.
|
|
|
|
Authoritative references:
|
|
- `docs/security/scopes-and-roles.md`
|
|
- `docs/modules/authority/architecture.md`
|
|
- `docs/modules/signer/architecture.md`
|
|
- `docs/modules/attestor/architecture.md`
|
|
|
|
## Network segmentation (typical deployment)
|
|
|
|
- **Front door / ingress**: TLS termination, rate limiting, and WAF controls.
|
|
- **Gateway layer**: authenticated routing and tenant resolution; exposes only required service surfaces.
|
|
- **Private service network**: internal service-to-service traffic (least privilege, explicit allowlists).
|
|
- **Stateful infrastructure**: PostgreSQL, Valkey, object storage, message brokers (not directly internet-exposed).
|
|
|
|
Deployment bundles under `deploy/` are the authoritative source of concrete network layouts.
|
|
|
|
## Cross-Origin Resource Sharing (CORS)
|
|
|
|
All Stella Ops web services use a shared CORS extension provided by `StellaOps.AspNet.Extensions` (`StellaOpsCorsExtensions`), with settings resolved by `StellaOps.Settings` (`StellaOpsCorsSettings`).
|
|
|
|
### Development mode
|
|
|
|
When the host environment is `Development`, CORS is automatically enabled with specific origins, `AllowAnyHeader`, `AllowAnyMethod`, and `AllowCredentials`.
|
|
|
|
Default dev origins (used when no explicit origin is configured):
|
|
- `https://stella-ops.local`
|
|
- `https://stella-ops.local:10000`
|
|
- `https://localhost:10000`
|
|
|
|
Override the defaults by setting `STELLAOPS_WEBSERVICES_CORS_ORIGIN`.
|
|
|
|
### Non-development (staging / production)
|
|
|
|
CORS is **disabled by default**. To enable, set the following environment variables (or their YAML/appsettings equivalents):
|
|
|
|
| Environment variable | Config key | Dev default | Prod default | Description |
|
|
|---|---|---|---|---|
|
|
| `STELLAOPS_WEBSERVICES_CORS` | `StellaOps:WebServices:Cors:Enabled` | `true` | `false` | Set to `true` or `1` to enable CORS |
|
|
| `STELLAOPS_WEBSERVICES_CORS_ORIGIN` | `StellaOps:WebServices:Cors:Origin` | `https://stella-ops.local, https://stella-ops.local:10000, https://localhost:10000` | *(must be set)* | Comma-separated list of allowed origins |
|
|
|
|
#### Legacy fallback
|
|
|
|
The following legacy env vars and config keys are still supported as fallbacks (resolved after the primary keys above):
|
|
|
|
| Legacy env var | Legacy config key |
|
|
|---|---|
|
|
| `STELLAOPS_CORS_ENABLED` | `StellaOps:Cors:Enabled` |
|
|
| `STELLAOPS_CORS_ALLOWED_ORIGIN` | `StellaOps:Cors:AllowedOrigin` |
|
|
|
|
#### Resolution order
|
|
|
|
Settings are resolved with a priority cascade (first non-empty value wins):
|
|
1. Primary env var (`STELLAOPS_WEBSERVICES_CORS` / `STELLAOPS_WEBSERVICES_CORS_ORIGIN`)
|
|
2. Primary config key (`StellaOps:WebServices:Cors:Enabled` / `StellaOps:WebServices:Cors:Origin`)
|
|
3. Legacy env var (`STELLAOPS_CORS_ENABLED` / `STELLAOPS_CORS_ALLOWED_ORIGIN`)
|
|
4. Legacy config key (`StellaOps:Cors:Enabled` / `StellaOps:Cors:AllowedOrigin`)
|
|
5. Default: `true` in Development, `false` otherwise
|
|
|
|
When CORS is enabled, the policy always uses:
|
|
- `WithOrigins(...)` (only the configured/default origins — never `AllowAnyOrigin`)
|
|
- `AllowAnyHeader`
|
|
- `AllowAnyMethod`
|
|
- `AllowCredentials`
|
|
|
|
### Integration in services
|
|
|
|
Every web service's `Program.cs` includes:
|
|
|
|
```csharp
|
|
using StellaOps.Auth.ServerIntegration;
|
|
|
|
// In service registration (before builder.Build())
|
|
builder.Services.AddStellaOpsCors(builder.Environment, builder.Configuration);
|
|
|
|
// In middleware pipeline (before UseAuthentication)
|
|
app.UseStellaOpsCors();
|
|
```
|
|
|
|
### Source
|
|
|
|
The implementation lives in:
|
|
- `src/__Libraries/StellaOps.Settings/StellaOpsCorsSettings.cs` (POCO + resolution logic)
|
|
- `src/__Libraries/StellaOps.AspNet.Extensions/StellaOpsCorsExtensions.cs` (ASP.NET DI + middleware)
|
|
- Transitive reference via `StellaOps.Auth.ServerIntegration` (so existing service references continue to work)
|
|
|
|
## Data protection
|
|
|
|
- TLS for in-transit protection (including internal traffic where required by the profile).
|
|
- Secrets must not be embedded in documentation examples; use a secrets provider (file, Docker secrets, Kubernetes secrets, vault).
|
|
- Evidence artifacts should be written to content-addressed or immutable stores where replay/audit requires it.
|
|
|
|
## Auditability
|
|
|
|
The platform is designed for audits:
|
|
- Deterministic outputs for the same inputs.
|
|
- Evidence artifacts (SBOM slices, advisories/VEX observations, explain traces) linkable to digests.
|
|
- Structured logs and correlation IDs for tracing request paths across services.
|