git.stella-ops.org/docs/cli/drift-cli.md

Drift CLI Reference

Sprint: SPRINT_3600_0004_0001
Task: UI-024 - Update CLI documentation for drift commands

Overview

The Drift CLI provides commands for detecting and analyzing reachability drift between scan results. Reachability drift occurs when the call paths to vulnerable code change between builds, potentially altering the risk profile of an application.

Commands

stellaops drift

Parent command for reachability drift operations.

stellaops drift <SUBCOMMAND> [OPTIONS]

---

stellaops drift compare

Compare reachability between two scans or graph snapshots.

stellaops drift compare [OPTIONS]

Required Options

Option	Alias	Description
--base <ID>	-b	Base scan/graph ID or commit SHA for comparison

Optional Options

Option	Alias	Description	Default
--head <ID>	-h	Head scan/graph ID or commit SHA	latest
--image <REF>	-i	Container image reference (digest or tag)	-
--repo <REPO>	-r	Repository reference (owner/repo)	-
--output <FMT>	-o	Output format: table, json, sarif	table
--min-severity <SEV>		Minimum severity: critical, high, medium, low, info	medium
--only-increases		Only show sinks with increased reachability	false
--verbose		Enable verbose output	false

Examples

Compare by scan IDs

stellaops drift compare --base abc123 --head def456

Compare by commit SHAs

stellaops drift compare --base HEAD~1 --head HEAD --repo myorg/myapp

Filter to risk increases only

stellaops drift compare --base abc123 --only-increases --min-severity high

Output as JSON

stellaops drift compare --base abc123 --output json > drift.json

Output as SARIF for CI integration

stellaops drift compare --base abc123 --output sarif > drift.sarif

---

stellaops drift show

Display details of a previously computed drift result.

stellaops drift show [OPTIONS]

Required Options

Option	Description
--id <ID>	Drift result ID to display

Optional Options

Option	Alias	Description	Default
--output <FMT>	-o	Output format: table, json, sarif	table
--expand-paths		Show full call paths instead of compressed view	false
--verbose		Enable verbose output	false

Examples

Show drift result

stellaops drift show --id drift-abc123

Show with expanded paths

stellaops drift show --id drift-abc123 --expand-paths

---

Output Formats

Table Format (Default)

Human-readable table output using Spectre.Console:

┌─────────────────────────────────────────────────────────────┐
│ Reachability Drift (abc123)                                 │
├───────────────────────────────┬─────────────────────────────┤
│ Metric                        │ Value                       │
├───────────────────────────────┼─────────────────────────────┤
│ Trend                         │ ↑ Increasing                │
│ Net Risk Delta                │ +3                          │
│ Increased                     │ 4                           │
│ Decreased                     │ 1                           │
│ New Sinks                     │ 2                           │
│ Removed Sinks                 │ 0                           │
└───────────────────────────────┴─────────────────────────────┘

┌──────────────┬──────────────────────┬───────────────┬─────────────────────────┬───────┐
│ Severity     │ Sink                 │ CVE           │ Bucket Change           │ Delta │
├──────────────┼──────────────────────┼───────────────┼─────────────────────────┼───────┤
│ CRITICAL     │ SqlConnection.Open   │ CVE-2024-1234 │ Runtime → Entrypoint    │ +2    │
│ HIGH         │ XmlParser.Parse      │ CVE-2024-5678 │ Unknown → Direct        │ +1    │
└──────────────┴──────────────────────┴───────────────┴─────────────────────────┴───────┘

JSON Format

Structured JSON for programmatic processing:

{
  "id": "abc123",
  "comparedAt": "2025-12-18T10:30:00Z",
  "baseGraphId": "base-graph-id",
  "headGraphId": "head-graph-id",
  "summary": {
    "totalSinks": 42,
    "increasedReachability": 4,
    "decreasedReachability": 1,
    "unchangedReachability": 35,
    "newSinks": 2,
    "removedSinks": 0,
    "riskTrend": "increasing",
    "netRiskDelta": 3
  },
  "driftedSinks": [
    {
      "sinkSymbol": "SqlConnection.Open",
      "cveId": "CVE-2024-1234",
      "severity": "critical",
      "previousBucket": "runtime",
      "currentBucket": "entrypoint",
      "isRiskIncrease": true,
      "riskDelta": 2
    }
  ]
}

SARIF Format

SARIF 2.1.0 output for CI/CD integration:

{
  "version": "2.1.0",
  "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "StellaOps Drift",
          "version": "1.0.0",
          "informationUri": "https://stellaops.io/docs/drift"
        }
      },
      "results": [
        {
          "ruleId": "CVE-2024-1234",
          "level": "error",
          "message": {
            "text": "Reachability changed: runtime → entrypoint"
          }
        }
      ]
    }
  ]
}

---

Exit Codes

Code	Description
0	Success (no risk increases or within threshold)
1	Error during execution
2	Risk increases detected
3	Critical risk increases detected

---

CI/CD Integration

GitHub Actions

- name: Check Reachability Drift
  run: |
    stellaops drift compare \
      --base ${{ github.event.pull_request.base.sha }} \
      --head ${{ github.sha }} \
      --repo ${{ github.repository }} \
      --output sarif > drift.sarif
  continue-on-error: true

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v2
  with:
    sarif_file: drift.sarif

GitLab CI

drift-check:
  script:
    - stellaops drift compare --base $CI_MERGE_REQUEST_DIFF_BASE_SHA --head $CI_COMMIT_SHA --output sarif > drift.sarif
  artifacts:
    reports:
      sast: drift.sarif

---

Related Documentation

• Reachability Analysis
• Smart-Diff CLI
• VEX Decisioning