audit work, fixed StellaOps.sln warnings/errors, fixed tests, sprints work, new advisories
This commit is contained in:
master
266
docs/operations/facet-quota-configuration.md
Normal file
266
docs/operations/facet-quota-configuration.md
Normal file
@@ -0,0 +1,266 @@
|
||||
# Facet Quota Configuration Guide
|
||||
|
||||
> **Version**: 1.0.0
|
||||
> **Sprint**: SPRINT_20260105_002_003_FACET
|
||||
> **Last Updated**: 2026-01-07
|
||||
|
||||
This guide covers configuration and operation of per-facet drift quotas in StellaOps.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Facet quotas control how much change is acceptable in different parts of a container image between builds. When drift exceeds a quota, StellaOps can:
|
||||
|
||||
- **Warn**: Log and report the drift, continue processing
|
||||
- **Block**: Fail the policy gate, prevent deployment
|
||||
- **Auto-VEX**: Generate a VEX draft for human review
|
||||
|
||||
### What are Facets?
|
||||
|
||||
Facets are logical groupings of files in a container image:
|
||||
|
||||
| Facet | Description | Typical Files |
|
||||
|-------|-------------|---------------|
|
||||
| `binaries` | Executables and libraries | `*.so`, `*.dll`, ELF files |
|
||||
| `lang-deps` | Language package dependencies | `node_modules/`, `site-packages/`, `.m2/` |
|
||||
| `os-packages` | OS-level packages | RPM, DEB, APK metadata |
|
||||
| `configs` | Configuration files | `*.conf`, `*.yaml`, `*.json` |
|
||||
| `data` | Static data files | Images, fonts, templates |
|
||||
|
||||
### Why Per-Facet Quotas?
|
||||
|
||||
Different file types have different risk profiles:
|
||||
|
||||
- A single binary change might be intentional (rebuild) or might indicate compromise
|
||||
- 100 new npm packages might be a normal dependency update
|
||||
- Removing OS security packages is always suspicious
|
||||
|
||||
Per-facet quotas let you apply appropriate controls to each category.
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### File Location
|
||||
|
||||
```
|
||||
/etc/stellaops/facet-quotas.yaml
|
||||
```
|
||||
|
||||
Or via environment variable:
|
||||
```bash
|
||||
STELLAOPS_FACET_QUOTAS_PATH=/path/to/facet-quotas.yaml
|
||||
```
|
||||
|
||||
### Basic Structure
|
||||
|
||||
```yaml
|
||||
# Default quota for all facets
|
||||
defaults:
|
||||
maxChurnPercent: 30 # Max % of files that can change
|
||||
maxChangedFiles: 100 # Max absolute changed files
|
||||
maxAddedFiles: 50 # Max new files
|
||||
maxRemovedFiles: 50 # Max removed files
|
||||
action: warn # warn | block | auto-vex
|
||||
|
||||
# Per-facet overrides
|
||||
facets:
|
||||
binaries:
|
||||
maxChurnPercent: 10
|
||||
action: block
|
||||
lang-deps:
|
||||
maxChurnPercent: 40
|
||||
action: auto-vex
|
||||
```
|
||||
|
||||
### Quota Parameters
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `maxChurnPercent` | decimal | Maximum percentage of files in the facet that can change |
|
||||
| `maxChangedFiles` | int | Maximum absolute number of changed files |
|
||||
| `maxAddedFiles` | int | Maximum number of new files (optional) |
|
||||
| `maxRemovedFiles` | int | Maximum number of removed files (optional) |
|
||||
| `action` | string | Action when quota exceeded: `warn`, `block`, `auto-vex` |
|
||||
| `allowlist` | list | Glob patterns to exclude from quota calculation |
|
||||
|
||||
### Using Profiles
|
||||
|
||||
StellaOps includes predefined quota profiles:
|
||||
|
||||
```yaml
|
||||
# Use a predefined profile
|
||||
profile: moderate # strict | moderate | permissive
|
||||
|
||||
# Optionally override specific facets
|
||||
facets:
|
||||
binaries:
|
||||
action: block # Override from profile
|
||||
```
|
||||
|
||||
| Profile | Description | Use Case |
|
||||
|---------|-------------|----------|
|
||||
| `strict` | Minimal tolerance, blocks most drift | Production, regulated |
|
||||
| `moderate` | Balanced, auto-VEX for review | Staging, pre-prod |
|
||||
| `permissive` | Relaxed, warnings only | Development |
|
||||
|
||||
---
|
||||
|
||||
## Policy Integration
|
||||
|
||||
### Enabling Quota Gates
|
||||
|
||||
In your policy configuration:
|
||||
|
||||
```yaml
|
||||
# policy-gates.yaml
|
||||
gates:
|
||||
- name: facet-quota
|
||||
enabled: true
|
||||
options:
|
||||
configPath: /etc/stellaops/facet-quotas.yaml
|
||||
failOnMissingSeal: true # Fail if no baseline seal exists
|
||||
```
|
||||
|
||||
### Seal Management
|
||||
|
||||
Quotas compare current state against a "sealed" baseline:
|
||||
|
||||
```bash
|
||||
# Seal current image as baseline
|
||||
stella facet seal --image myapp:v1.2.3 --tenant production
|
||||
|
||||
# List seals
|
||||
stella facet seals list --tenant production
|
||||
|
||||
# Compare against seal
|
||||
stella facet drift --image myapp:v1.2.4 --baseline v1.2.3
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Auto-VEX Workflow
|
||||
|
||||
When quota action is `auto-vex`, StellaOps:
|
||||
|
||||
1. Generates a VEX draft with drift justification
|
||||
2. Queues the draft for human review
|
||||
3. Sends notifications to configured channels
|
||||
|
||||
### VEX Draft Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"statements": [{
|
||||
"vulnerability": "FACET-DRIFT-2026-001234",
|
||||
"status": "under_investigation",
|
||||
"justification": "facet_drift_detected",
|
||||
"impact_statement": "Drift in 'binaries' facet: 15% churn (quota: 10%), 12 files changed"
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
### Approving VEX Drafts
|
||||
|
||||
```bash
|
||||
# List pending drafts
|
||||
stella vex drafts list --status pending
|
||||
|
||||
# Approve a draft
|
||||
stella vex draft approve --id <draft-id> --reason "Expected rebuild"
|
||||
|
||||
# Reject a draft
|
||||
stella vex draft reject --id <draft-id> --reason "Unexpected changes"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Metrics
|
||||
|
||||
| Metric | Description |
|
||||
|--------|-------------|
|
||||
| `facet_drift_evaluations_total` | Total drift evaluations |
|
||||
| `facet_quota_exceeded_total` | Quota breaches by facet and action |
|
||||
| `facet_vex_drafts_created_total` | Auto-VEX drafts generated |
|
||||
| `facet_seal_operations_total` | Seal create/update operations |
|
||||
|
||||
### Grafana Dashboard
|
||||
|
||||
Import the facet quota dashboard:
|
||||
```
|
||||
devops/observability/grafana/facet-quota-metrics.json
|
||||
```
|
||||
|
||||
### Alerts
|
||||
|
||||
Key alerts to configure:
|
||||
|
||||
- `FacetQuotaBlockRate`: High rate of blocked builds
|
||||
- `FacetDriftAnomalous`: Unusual drift patterns
|
||||
- `FacetVexDraftBacklog`: Growing VEX draft queue
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Quota Unexpectedly Blocking
|
||||
|
||||
1. Check current quota configuration:
|
||||
```bash
|
||||
stella facet quota show --facet binaries
|
||||
```
|
||||
|
||||
2. Review drift details:
|
||||
```bash
|
||||
stella facet drift --image myapp:latest --verbose
|
||||
```
|
||||
|
||||
3. Check allowlist patterns:
|
||||
```bash
|
||||
stella facet quota test-allowlist --pattern "**/__pycache__/**"
|
||||
```
|
||||
|
||||
### Missing Baseline Seal
|
||||
|
||||
```bash
|
||||
# Create initial seal
|
||||
stella facet seal --image myapp:v1.0.0 --tenant production
|
||||
|
||||
# Or skip quota check for first build
|
||||
stella scan --image myapp:v1.0.0 --skip-facet-quota
|
||||
```
|
||||
|
||||
### VEX Draft Not Generated
|
||||
|
||||
1. Verify action is `auto-vex` not `warn`:
|
||||
```yaml
|
||||
facets:
|
||||
binaries:
|
||||
action: auto-vex # Not 'warn'
|
||||
```
|
||||
|
||||
2. Check VEX emitter is enabled:
|
||||
```bash
|
||||
stella config get excititor.vex.facetDriftEnabled
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Start with `moderate` profile** in staging, tune based on observations
|
||||
2. **Use `strict` for production** with explicit allowlists
|
||||
3. **Review auto-VEX drafts daily** to prevent backlog
|
||||
4. **Seal after each release** to establish new baseline
|
||||
5. **Monitor quota metrics** to detect configuration drift
|
||||
|
||||
---
|
||||
|
||||
## Revision History
|
||||
|
||||
| Version | Date | Author | Changes |
|
||||
|---------|------|--------|---------|
|
||||
| 1.0.0 | 2026-01-07 | Agent | Initial release |
|
||||
Reference in New Issue
Block a user