release orchestrator pivot, architecture and planning
This commit is contained in:
281
docs/modules/release-orchestrator/security/overview.md
Normal file
281
docs/modules/release-orchestrator/security/overview.md
Normal file
@@ -0,0 +1,281 @@
|
||||
# Security Architecture Overview
|
||||
|
||||
## Security Principles
|
||||
|
||||
| Principle | Implementation |
|
||||
|-----------|----------------|
|
||||
| **Defense in depth** | Multiple layers: network, auth, authz, audit |
|
||||
| **Least privilege** | Role-based access; minimal permissions |
|
||||
| **Zero trust** | All requests authenticated; mTLS for agents |
|
||||
| **Secrets hygiene** | Secrets in vault; never in DB; ephemeral injection |
|
||||
| **Audit everything** | All mutations logged; evidence trail |
|
||||
| **Immutable evidence** | Evidence packets append-only; cryptographically signed |
|
||||
|
||||
## Authentication Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ AUTHENTICATION ARCHITECTURE │
|
||||
│ │
|
||||
│ Human Users Service/Agent │
|
||||
│ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ Browser │ │ Agent │ │
|
||||
│ └────┬─────┘ └────┬─────┘ │
|
||||
│ │ │ │
|
||||
│ │ OAuth 2.0 │ mTLS + JWT │
|
||||
│ │ Authorization Code │ │
|
||||
│ ▼ ▼ │
|
||||
│ ┌──────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ AUTHORITY MODULE │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
|
||||
│ │ │ OAuth 2.0 │ │ mTLS │ │ API Key │ │ │
|
||||
│ │ │ Provider │ │ Validator │ │ Validator │ │ │
|
||||
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────────────────────────────────────────────────┐ │ │
|
||||
│ │ │ TOKEN ISSUER │ │ │
|
||||
│ │ │ - Short-lived JWT (15 min) │ │ │
|
||||
│ │ │ - Contains: user_id, tenant_id, roles, permissions │ │ │
|
||||
│ │ │ - Signed with RS256 │ │ │
|
||||
│ │ └─────────────────────────────────────────────────────────────┘ │ │
|
||||
│ └──────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ API GATEWAY │ │
|
||||
│ │ │ │
|
||||
│ │ - Validate JWT signature │ │
|
||||
│ │ - Check token expiration │ │
|
||||
│ │ - Extract tenant context │ │
|
||||
│ │ - Enforce rate limits │ │
|
||||
│ └──────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Authorization Model
|
||||
|
||||
### Permission Structure
|
||||
|
||||
```typescript
|
||||
interface Permission {
|
||||
resource: ResourceType;
|
||||
action: ActionType;
|
||||
scope?: ScopeType;
|
||||
conditions?: Condition[];
|
||||
}
|
||||
|
||||
type ResourceType =
|
||||
| "environment"
|
||||
| "release"
|
||||
| "promotion"
|
||||
| "target"
|
||||
| "agent"
|
||||
| "workflow"
|
||||
| "plugin"
|
||||
| "integration"
|
||||
| "evidence";
|
||||
|
||||
type ActionType =
|
||||
| "create"
|
||||
| "read"
|
||||
| "update"
|
||||
| "delete"
|
||||
| "execute"
|
||||
| "approve"
|
||||
| "deploy"
|
||||
| "rollback";
|
||||
|
||||
type ScopeType =
|
||||
| "*" // All resources
|
||||
| { environmentId: UUID } // Specific environment
|
||||
| { labels: Record<string, string> }; // Label-based
|
||||
```
|
||||
|
||||
### Role Definitions
|
||||
|
||||
| Role | Permissions |
|
||||
|------|-------------|
|
||||
| `admin` | All permissions on all resources |
|
||||
| `release-manager` | Full access to releases, promotions; read environments/targets |
|
||||
| `deployer` | Read releases; create/read promotions; read targets |
|
||||
| `approver` | Read/approve promotions |
|
||||
| `viewer` | Read-only access to all resources |
|
||||
|
||||
### Environment-Scoped Roles
|
||||
|
||||
Roles can be scoped to specific environments:
|
||||
|
||||
```typescript
|
||||
// Example: Production deployer can only deploy to production
|
||||
const prodDeployer = {
|
||||
role: "deployer",
|
||||
scope: { environmentId: "prod-environment-uuid" }
|
||||
};
|
||||
```
|
||||
|
||||
## Policy Enforcement Points
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ POLICY ENFORCEMENT POINTS │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ API LAYER (PEP 1) │ │
|
||||
│ │ - Authenticate request │ │
|
||||
│ │ - Check resource-level permissions │ │
|
||||
│ │ - Enforce tenant isolation │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ SERVICE LAYER (PEP 2) │ │
|
||||
│ │ - Check business-level permissions │ │
|
||||
│ │ - Validate separation of duties │ │
|
||||
│ │ - Enforce approval policies │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ DECISION ENGINE (PEP 3) │ │
|
||||
│ │ - Evaluate security gates │ │
|
||||
│ │ - Evaluate custom OPA policies │ │
|
||||
│ │ - Produce signed decision records │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ DATA LAYER (PEP 4) │ │
|
||||
│ │ - Row-level security (tenant_id) │ │
|
||||
│ │ - Append-only enforcement (evidence) │ │
|
||||
│ │ - Encryption at rest │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Agent Security Model
|
||||
|
||||
See [Agent Security](agent-security.md) for detailed agent security architecture.
|
||||
|
||||
Key features:
|
||||
- mTLS authentication with CA-signed certificates
|
||||
- One-time registration tokens
|
||||
- Short-lived JWT for task execution
|
||||
- Encrypted task payloads
|
||||
- Scoped credentials per task
|
||||
|
||||
## Secrets Management
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ SECRETS FLOW (NEVER STORED IN DB) │
|
||||
│ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ VAULT │ │ STELLA CORE │ │ AGENT │ │
|
||||
│ │ (Source) │ │ (Broker) │ │ (Consumer) │ │
|
||||
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
|
||||
│ │ │ │ │
|
||||
│ │ │ Task requires secret │ │
|
||||
│ │ │ │ │
|
||||
│ │ Fetch with service │ │ │
|
||||
│ │ account token │ │ │
|
||||
│ │◄─────────────────────── │ │
|
||||
│ │ │ │ │
|
||||
│ │ Return secret │ │ │
|
||||
│ │ (wrapped, short TTL) │ │ │
|
||||
│ │───────────────────────► │ │
|
||||
│ │ │ │ │
|
||||
│ │ │ Embed in task payload │ │
|
||||
│ │ │ (encrypted) │ │
|
||||
│ │ │───────────────────────► │
|
||||
│ │ │ │ │
|
||||
│ │ │ │ Decrypt │
|
||||
│ │ │ │ Use for task │
|
||||
│ │ │ │ Discard │
|
||||
│ │
|
||||
│ Rules: │
|
||||
│ - Secrets NEVER stored in Stella database │
|
||||
│ - Only Vault references stored │
|
||||
│ - Secrets fetched at execution time only │
|
||||
│ - Secrets not logged (masked in logs) │
|
||||
│ - Secrets not persisted in agent memory beyond task scope │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Threat Model
|
||||
|
||||
| Threat | Attack Vector | Mitigation |
|
||||
|--------|---------------|------------|
|
||||
| **Credential theft** | Database breach | Secrets never in DB; only vault refs |
|
||||
| **Token replay** | Stolen JWT | Short-lived tokens (15 min); refresh tokens rotated |
|
||||
| **Agent impersonation** | Fake agent | mTLS with CA-signed certs; registration token one-time |
|
||||
| **Digest tampering** | Modified image | Digest verification at pull time; mismatch = failure |
|
||||
| **Evidence tampering** | Modified audit records | Append-only table; cryptographic signing |
|
||||
| **Privilege escalation** | Compromised account | Role-based access; SoD enforcement; audit logs |
|
||||
| **Supply chain attack** | Malicious plugin | Plugin sandbox; capability declarations; review process |
|
||||
| **Lateral movement** | Compromised target | Short-lived task credentials; scoped permissions |
|
||||
| **Data exfiltration** | Log/artifact theft | Encryption at rest; network segmentation |
|
||||
| **Denial of service** | Resource exhaustion | Rate limiting; resource quotas; circuit breakers |
|
||||
|
||||
## Audit Trail
|
||||
|
||||
### Audit Event Structure
|
||||
|
||||
```typescript
|
||||
interface AuditEvent {
|
||||
id: UUID;
|
||||
timestamp: DateTime;
|
||||
tenantId: UUID;
|
||||
|
||||
// Actor
|
||||
actorType: "user" | "agent" | "system" | "plugin";
|
||||
actorId: UUID;
|
||||
actorName: string;
|
||||
actorIp?: string;
|
||||
|
||||
// Action
|
||||
action: string; // "promotion.approved", "deployment.started"
|
||||
resource: string; // "promotion"
|
||||
resourceId: UUID;
|
||||
|
||||
// Context
|
||||
environmentId?: UUID;
|
||||
releaseId?: UUID;
|
||||
promotionId?: UUID;
|
||||
|
||||
// Details
|
||||
before?: object; // State before (for updates)
|
||||
after?: object; // State after
|
||||
metadata?: object; // Additional context
|
||||
|
||||
// Integrity
|
||||
previousEventHash: string; // Hash chain for tamper detection
|
||||
eventHash: string;
|
||||
}
|
||||
```
|
||||
|
||||
### Audited Operations
|
||||
|
||||
| Category | Operations |
|
||||
|----------|------------|
|
||||
| **Authentication** | Login, logout, token refresh, failed attempts |
|
||||
| **Authorization** | Permission denied events |
|
||||
| **Environments** | Create, update, delete, freeze window changes |
|
||||
| **Releases** | Create, deprecate, archive |
|
||||
| **Promotions** | Request, approve, reject, cancel |
|
||||
| **Deployments** | Start, complete, fail, rollback |
|
||||
| **Targets** | Register, update, delete, health changes |
|
||||
| **Agents** | Register, heartbeat gaps, capability changes |
|
||||
| **Integrations** | Create, update, delete, test |
|
||||
| **Plugins** | Enable, disable, config changes |
|
||||
| **Evidence** | Create (never update/delete) |
|
||||
|
||||
## References
|
||||
|
||||
- [Authentication & Authorization](auth.md)
|
||||
- [Agent Security](agent-security.md)
|
||||
- [Threat Model](threat-model.md)
|
||||
- [Audit Trail](audit-trail.md)
|
||||
Reference in New Issue
Block a user