129 lines
6.0 KiB
Markdown
129 lines
6.0 KiB
Markdown
|
---
|
||
|
|
name: security-boundary-design
|
||
|
|
description: "Knowledge contract for security boundary design. Provides principles and patterns for authentication, authorization, service identity, token propagation, tenant isolation, secret management, and audit logging. Referenced by design-architecture when defining security boundaries."
|
||
|
|
---
|
||
|
|
|
||
|
|
This is a knowledge contract, not a workflow skill. It provides theoretical guidance that the Architect references when designing security boundaries. It does not produce artifacts directly.
|
||
|
|
|
||
|
|
## Core Principles
|
||
|
|
|
||
|
|
### Defense in Depth
|
||
|
|
- Never rely on a single security boundary
|
||
|
|
- Apply security at every layer: network, service, data, application
|
||
|
|
- Assume breach: design so that compromise of one layer doesn't compromise all
|
||
|
|
|
||
|
|
### Least Privilege
|
||
|
|
- Services and users should have the minimum permissions required
|
||
|
|
- Default deny: start with no access, grant explicitly
|
||
|
|
- Rotate and expire credentials regularly
|
||
|
|
|
||
|
|
### Zero Trust
|
||
|
|
- Don't trust internal network traffic by default
|
||
|
|
- Authenticate and authorize every service-to-service call
|
||
|
|
- Encrypt data in transit, even within the internal network
|
||
|
|
|
||
|
|
## Authentication
|
||
|
|
|
||
|
|
### Patterns
|
||
|
|
- **Token-based authentication**: JWT, OAuth2 tokens
|
||
|
|
- **API key authentication**: For service-to-service and public APIs
|
||
|
|
- **Certificate-based authentication**: mTLS for internal service communication
|
||
|
|
- **Session-based authentication**: For web applications with stateful sessions
|
||
|
|
|
||
|
|
### Design Considerations
|
||
|
|
- Define where authentication happens (edge gateway, service level, or both)
|
||
|
|
- Define token format, issuer, audience, and expiration
|
||
|
|
- Define token refresh and revocation strategy
|
||
|
|
- Define credential rotation strategy
|
||
|
|
- Consider token size impact on request headers
|
||
|
|
|
||
|
|
## Authorization
|
||
|
|
|
||
|
|
### Patterns
|
||
|
|
- **RBAC (Role-Based Access Control)**: Assign permissions to roles, assign roles to users
|
||
|
|
- **ABAC (Attribute-Based Access Control)**: Assign permissions based on attributes (user, resource, environment)
|
||
|
|
- **ACL (Access Control List)**: Explicit list of who can access what
|
||
|
|
- **ReBAC (Relationship-Based Access Control)**: Permissions based on relationships between entities
|
||
|
|
|
||
|
|
### Design Considerations
|
||
|
|
- Choose the simplest model that meets PRD requirements
|
||
|
|
- Define permission granularity: coarse-grained (role-level) vs fine-grained (resource-level)
|
||
|
|
- Define where authorization is enforced (gateway, service, or both)
|
||
|
|
- Define how permissions are stored and cached
|
||
|
|
- Consider multi-tenant authorization: can users in one tenant access resources in another?
|
||
|
|
|
||
|
|
## Service Identity
|
||
|
|
|
||
|
|
### Patterns
|
||
|
|
- **Service accounts**: Each service has its own identity with specific permissions
|
||
|
|
- **Workload identity**: Identity tied to the deployment (Kubernetes service accounts, cloud IAM roles)
|
||
|
|
- **Service mesh identity**: Identity managed by the service mesh (Istio, Linkerd)
|
||
|
|
|
||
|
|
### Design Considerations
|
||
|
|
- Each service should have its own identity (no shared credentials)
|
||
|
|
- Service identity should be short-lived and automatically rotated
|
||
|
|
- Service identity should be bound to the deployment environment
|
||
|
|
- Service identity permissions should follow least privilege
|
||
|
|
|
||
|
|
## Token Propagation
|
||
|
|
|
||
|
|
### Patterns
|
||
|
|
- **Pass-through**: Gateway validates token, passes it to downstream services
|
||
|
|
- **Token exchange**: Gateway validates external token, issues internal token
|
||
|
|
- **Token relay**: Each service forwards the token to downstream services
|
||
|
|
- **Impersonation**: Service calls downstream on behalf of the user
|
||
|
|
|
||
|
|
### Design Considerations
|
||
|
|
- Define token format for internal vs external communication
|
||
|
|
- Define token lifecycle: creation, validation, refresh, revocation
|
||
|
|
- Consider token size when propagating through multiple hops
|
||
|
|
- Consider what context to propagate (user identity, tenant, permissions, correlation ID)
|
||
|
|
|
||
|
|
## Tenant Isolation
|
||
|
|
|
||
|
|
### Patterns
|
||
|
|
- **Database-level isolation**: Separate database per tenant
|
||
|
|
- **Schema-level isolation**: Separate schema per tenant, shared database
|
||
|
|
- **Row-level isolation**: Shared schema, tenant_id column with enforcement
|
||
|
|
- **Application-level isolation**: Shared infrastructure, application enforces isolation
|
||
|
|
|
||
|
|
### Design Considerations
|
||
|
|
- Choose isolation level based on PRD requirements (compliance, performance, cost)
|
||
|
|
- Row-level isolation is simplest but requires careful query filtering
|
||
|
|
- Database-level isolation provides strongest isolation but highest cost
|
||
|
|
- Define how tenant context is resolved (subdomain, header, token claim)
|
||
|
|
- Define how tenant isolation is enforced (middleware, query filter, database policy)
|
||
|
|
|
||
|
|
## Secret Management
|
||
|
|
|
||
|
|
### Patterns
|
||
|
|
- **Environment variables**: Simple, but don't support rotation well
|
||
|
|
- **Secret management service**: HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager
|
||
|
|
- **Platform-native secrets**: Kubernetes Secrets, cloud IAM role-based access
|
||
|
|
- **Configuration service**: Centralized configuration with encryption at rest
|
||
|
|
|
||
|
|
### Design Considerations
|
||
|
|
- Secrets must never be stored in code, configuration files in version control, or logs
|
||
|
|
- Define secret rotation strategy for each type of secret
|
||
|
|
- Define how services access secrets (sidecar, SDK, environment injection)
|
||
|
|
- Define audit trail for secret access
|
||
|
|
- Consider secret hierarchies (global, per-environment, per-service)
|
||
|
|
|
||
|
|
## Audit Logging
|
||
|
|
|
||
|
|
### Design Considerations
|
||
|
|
- Log all authentication and authorization events (success and failure)
|
||
|
|
- Log all data modification operations (who, what, when, from where)
|
||
|
|
- Log all administrative actions
|
||
|
|
- Define log retention period based on compliance requirements
|
||
|
|
- Define log format: structured JSON with consistent fields
|
||
|
|
- Log must be tamper-evident or append-only for compliance
|
||
|
|
|
||
|
|
## Anti-Patterns
|
||
|
|
|
||
|
|
- **Shared credentials across services**: Each service must have its own identity
|
||
|
|
- **Hard-coded secrets**: Secrets must be externalized and rotated
|
||
|
|
- **Overly broad permissions**: Grant least privilege, not convenience privilege
|
||
|
|
- **Missing authentication for internal services**: Internal traffic must also be authenticated
|
||
|
|
- **Missing audit logging for sensitive operations**: All auth events and data modifications must be logged
|
||
|
|
- **Trust based on network location**: Don't assume internal network is safe
|