audit work, fixed StellaOps.sln warnings/errors, fixed tests, sprints work, new advisories
This commit is contained in:
master
267
docs/modules/cli/guides/commands/facet-drift.md
Normal file
267
docs/modules/cli/guides/commands/facet-drift.md
Normal file
@@ -0,0 +1,267 @@
|
||||
# stella drift (Facet Analysis) - Command Guide
|
||||
|
||||
**Sprint:** SPRINT_20260105_002_004_CLI
|
||||
**Task:** CLI-016 - Facet drift command documentation
|
||||
|
||||
## Overview
|
||||
|
||||
The `stella drift` command analyzes facet drift between a baseline seal and the current state of a container image. Unlike reachability drift (which tracks call paths to vulnerable code), facet drift tracks file-level changes within categorized image layers.
|
||||
|
||||
## Commands
|
||||
|
||||
### stella drift
|
||||
|
||||
Analyze facet drift for an image against a baseline seal.
|
||||
|
||||
```bash
|
||||
stella drift <IMAGE> [OPTIONS]
|
||||
```
|
||||
|
||||
#### Arguments
|
||||
|
||||
| Argument | Description |
|
||||
|----------|-------------|
|
||||
| `IMAGE` | Image reference or digest to analyze (required) |
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Alias | Description | Default |
|
||||
|--------|-------|-------------|---------|
|
||||
| `--baseline <ID>` | `-b` | Baseline seal ID for comparison | latest seal |
|
||||
| `--format <FMT>` | `-f` | Output format: `table`, `json`, `yaml` | `table` |
|
||||
| `--verbose` | `-v` | Show detailed file changes | `false` |
|
||||
| `--fail-on-breach` | | Exit with error code if quota breached | `false` |
|
||||
|
||||
#### Examples
|
||||
|
||||
##### Basic drift analysis
|
||||
|
||||
```bash
|
||||
stella drift sha256:abc123def456...
|
||||
```
|
||||
|
||||
##### With specific baseline
|
||||
|
||||
```bash
|
||||
stella drift myregistry.io/app:v2.0 --baseline seal-xyz789
|
||||
```
|
||||
|
||||
##### JSON output for CI integration
|
||||
|
||||
```bash
|
||||
stella drift sha256:abc123 --format json > drift-report.json
|
||||
```
|
||||
|
||||
##### Fail build on quota breach
|
||||
|
||||
```bash
|
||||
stella drift sha256:abc123 --fail-on-breach
|
||||
```
|
||||
|
||||
##### Verbose output with file details
|
||||
|
||||
```bash
|
||||
stella drift sha256:abc123 --verbose
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output Formats
|
||||
|
||||
### Table Format (Default)
|
||||
|
||||
```
|
||||
Overall Verdict: Warning
|
||||
Total Changed Files: 15
|
||||
|
||||
+----------+-------+---------+----------+---------+-----------+
|
||||
| Facet | Added | Removed | Modified | Churn % | Verdict |
|
||||
+----------+-------+---------+----------+---------+-----------+
|
||||
| runtime | 2 | 1 | 3 | 12.5% | Warning |
|
||||
| config | 5 | 0 | 2 | 8.2% | Ok |
|
||||
| static | 0 | 2 | 0 | 3.1% | Ok |
|
||||
+----------+-------+---------+----------+---------+-----------+
|
||||
```
|
||||
|
||||
With `--verbose`:
|
||||
|
||||
```
|
||||
File Changes:
|
||||
|
||||
runtime
|
||||
+ /usr/lib/libcrypto.so.3.0.1
|
||||
+ /usr/lib/libssl.so.3.0.1
|
||||
- /usr/lib/libcrypto.so.3.0.0
|
||||
~ /usr/bin/app (sha256:old -> sha256:new)
|
||||
~ /etc/app/config.yaml
|
||||
~ /var/lib/app/data.db
|
||||
```
|
||||
|
||||
### JSON Format
|
||||
|
||||
```json
|
||||
{
|
||||
"imageDigest": "sha256:abc123...",
|
||||
"baselineSealId": "seal-xyz789",
|
||||
"analyzedAt": "2026-01-05T10:30:00Z",
|
||||
"overallVerdict": "warning",
|
||||
"totalChangedFiles": 15,
|
||||
"facetDrifts": [
|
||||
{
|
||||
"facetId": "runtime",
|
||||
"baselineFileCount": 48,
|
||||
"added": [
|
||||
{
|
||||
"path": "/usr/lib/libcrypto.so.3.0.1",
|
||||
"digest": "sha256:new...",
|
||||
"sizeBytes": 3145728,
|
||||
"modifiedAt": null
|
||||
}
|
||||
],
|
||||
"removed": [
|
||||
{
|
||||
"path": "/usr/lib/libcrypto.so.3.0.0",
|
||||
"digest": "sha256:old...",
|
||||
"sizeBytes": 3145600,
|
||||
"modifiedAt": null
|
||||
}
|
||||
],
|
||||
"modified": [
|
||||
{
|
||||
"path": "/usr/bin/app",
|
||||
"previousDigest": "sha256:prev...",
|
||||
"currentDigest": "sha256:curr...",
|
||||
"previousSizeBytes": 15728640,
|
||||
"currentSizeBytes": 15730000
|
||||
}
|
||||
],
|
||||
"driftScore": 25.5,
|
||||
"churnPercent": 12.5,
|
||||
"quotaVerdict": "warning"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### YAML Format
|
||||
|
||||
```yaml
|
||||
imageDigest: sha256:abc123...
|
||||
baselineSealId: seal-xyz789
|
||||
overallVerdict: warning
|
||||
totalChangedFiles: 15
|
||||
facetDrifts:
|
||||
- facetId: runtime
|
||||
added: 2
|
||||
removed: 1
|
||||
modified: 3
|
||||
churnPercent: 12.50
|
||||
verdict: warning
|
||||
- facetId: config
|
||||
added: 5
|
||||
removed: 0
|
||||
modified: 2
|
||||
churnPercent: 8.20
|
||||
verdict: ok
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quota Verdicts
|
||||
|
||||
| Verdict | Description | Exit Code |
|
||||
|---------|-------------|-----------|
|
||||
| `Ok` | Drift within acceptable limits | 0 |
|
||||
| `Warning` | Approaching quota limits | 0 |
|
||||
| `Blocked` | Quota exceeded, deployment should be blocked | 2 |
|
||||
| `RequiresVex` | Significant drift, requires VEX authorization | 2 |
|
||||
|
||||
## Exit Codes
|
||||
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| `0` | Success (no breach, or breach without `--fail-on-breach`) |
|
||||
| `1` | Error (no baseline seal, image not found, etc.) |
|
||||
| `2` | Quota breached (with `--fail-on-breach`) |
|
||||
|
||||
---
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
```yaml
|
||||
- name: Check Facet Drift
|
||||
run: |
|
||||
stella drift ${{ env.IMAGE_DIGEST }} \
|
||||
--format json \
|
||||
--fail-on-breach > drift.json
|
||||
continue-on-error: true
|
||||
id: drift-check
|
||||
|
||||
- name: Upload Drift Report
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: facet-drift-report
|
||||
path: drift.json
|
||||
|
||||
- name: Generate VEX if needed
|
||||
if: failure() && steps.drift-check.outcome == 'failure'
|
||||
run: |
|
||||
stella vex gen --from-drift \
|
||||
--image ${{ env.IMAGE_DIGEST }} \
|
||||
--output vex-request.json
|
||||
```
|
||||
|
||||
### GitLab CI
|
||||
|
||||
```yaml
|
||||
facet-drift-check:
|
||||
script:
|
||||
- stella drift $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA --fail-on-breach --format json > drift.json
|
||||
artifacts:
|
||||
paths:
|
||||
- drift.json
|
||||
reports:
|
||||
codequality: drift.json
|
||||
allow_failure: true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workflow: Handling Drift Breaches
|
||||
|
||||
When drift exceeds quotas:
|
||||
|
||||
1. **Review the drift report**
|
||||
```bash
|
||||
stella drift sha256:abc123 --verbose
|
||||
```
|
||||
|
||||
2. **Determine if changes are intentional**
|
||||
- Legitimate updates: Generate VEX authorization
|
||||
- Unexpected changes: Investigate and remediate
|
||||
|
||||
3. **For intentional changes, generate VEX**
|
||||
```bash
|
||||
stella vex gen --from-drift --image sha256:abc123 --output vex.json
|
||||
```
|
||||
|
||||
4. **Review and sign the VEX**
|
||||
```bash
|
||||
stella vex sign --input vex.json --key /path/to/key
|
||||
```
|
||||
|
||||
5. **Or re-seal to establish new baseline**
|
||||
```bash
|
||||
stella seal sha256:abc123 --store
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Facet Seal Command](./seal.md)
|
||||
- [VEX Generation from Drift](./vex.md#stella-vex-gen---from-drift)
|
||||
- [Reachability Drift (different concept)](./drift.md)
|
||||
- [Admission Webhook Configuration](../admin/admission-webhook.md)
|
||||
Reference in New Issue
Block a user