git.stella-ops.org/docs/operations/guides/auditor-guide.md

Auditor Guide

Sprint: SPRINT_20260117_027_CLI_audit_bundle_command
Task: AUD-007 - Documentation

This guide is for external auditors reviewing Stella Ops release evidence.

Overview

Stella Ops generates comprehensive, tamper-evident audit bundles that contain all evidence required to verify release decisions. This guide explains how to interpret and verify these bundles.

Receiving an Audit Bundle

Audit bundles may be delivered as:

• Directory: A folder containing all evidence files
• Archive: A .tar.gz or .zip file

Extracting Archives

# tar.gz
tar -xzf audit-bundle-sha256-abc123.tar.gz

# zip
unzip audit-bundle-sha256-abc123.zip

Bundle Structure

audit-bundle-<digest>-<timestamp>/
├── manifest.json              # Integrity manifest
├── README.md                  # Quick reference
├── verdict/                   # Release decision
├── evidence/                  # Supporting evidence
├── policy/                    # Policy configuration
└── replay/                    # Verification instructions

Step 1: Verify Bundle Integrity

Before reviewing contents, verify the bundle has not been tampered with.

Using Stella CLI

stella audit verify ./audit-bundle-sha256-abc123/

Expected output:

✓ Verified 15/15 files
✓ Integrity hash verified
✓ Bundle integrity verified

Manual Verification

1. Open manifest.json
2. For each file listed, compute SHA-256 and compare:

   sha256sum verdict/verdict.json
   

3. Verify the integrityHash by hashing all file hashes

Step 2: Review the Verdict

The verdict is the official release decision.

verdict/verdict.json

{
  "artifactDigest": "sha256:abc123...",
  "decision": "PASS",
  "timestamp": "2026-01-17T10:25:00Z",
  "gates": [
    {
      "gateId": "sbom-required",
      "status": "PASS",
      "reason": "Valid CycloneDX SBOM present"
    },
    {
      "gateId": "vex-trust",
      "status": "PASS", 
      "reason": "Trust score 0.85 >= 0.70 threshold"
    }
  ]
}

Decision Values

Decision	Meaning
PASS	All gates passed, artifact approved for deployment
BLOCKED	One or more gates failed, artifact not approved
PENDING	Evaluation incomplete, awaiting additional evidence

verdict/verdict.dsse.json

This file contains the cryptographically signed verdict envelope (DSSE format). Verify signatures using:

stella audit verify ./bundle/ --check-signatures

Step 3: Review Evidence

evidence/sbom.json

Software Bill of Materials (SBOM) listing all components in the artifact.

Key fields:

• components[] - List of all software components
• dependencies[] - Dependency relationships
• metadata.timestamp - When SBOM was generated

evidence/vex-statements/

Vulnerability Exploitability eXchange (VEX) statements that justify vulnerability assessments.

index.json:

{
  "statementCount": 3,
  "statements": [
    {"fileName": "vex-001.json", "source": "vendor-security"},
    {"fileName": "vex-002.json", "source": "internal-analysis"}
  ]
}

Each VEX statement explains why a vulnerability does or does not affect this artifact.

evidence/reachability/analysis.json

Reachability analysis showing which vulnerabilities are actually reachable in the code.

{
  "components": [
    {
      "purl": "pkg:npm/lodash@4.17.21",
      "vulnerabilities": [
        {
          "id": "CVE-2021-23337",
          "reachable": false,
          "reason": "Vulnerable function not in call graph"
        }
      ]
    }
  ]
}

Step 4: Review Policy

policy/policy-snapshot.json

The policy configuration used for evaluation:

{
  "policyVersion": "v2.3.1",
  "gates": ["sbom-required", "vex-trust", "cve-threshold"],
  "thresholds": {
    "vexTrustScore": 0.70,
    "maxCriticalCves": 0,
    "maxHighCves": 5
  }
}

policy/gate-decision.json

Detailed breakdown of each gate evaluation:

{
  "gates": [
    {
      "gateId": "vex-trust",
      "decision": "PASS",
      "inputs": {
        "vexStatements": 3,
        "trustScore": 0.85,
        "threshold": 0.70
      }
    }
  ]
}

Step 5: Replay Verification (Optional)

For maximum assurance, you can replay the verdict evaluation.

Using Stella CLI

cd audit-bundle-sha256-abc123/
stella replay snapshot --manifest replay/knowledge-snapshot.json

This re-evaluates the policy using the frozen inputs and should produce an identical verdict.

Manual Replay Steps

See replay/replay-instructions.md for detailed steps.

Compliance Mapping

Compliance Framework	Relevant Bundle Components
SOC 2 (CC7.1)	verdict/, policy/
ISO 27001 (A.12.6)	evidence/sbom.json
FedRAMP	All components
SLSA Level 3	evidence/provenance/

Common Questions

Q: Why was this artifact blocked?

Review policy/gate-decision.json for the specific gate that failed and its reason.

Q: How do I verify the SBOM is accurate?

The SBOM digest is included in the manifest. Compare against the organization's SBOM generation process.

Q: What if replay produces a different result?

This may indicate:

1. Policy version mismatch
2. Missing evidence files
3. Time-dependent policy rules

Contact the organization's security team for clarification.

Q: How long should audit bundles be retained?

Stella Ops recommends:

• Production releases: 5 years minimum
• Security-critical systems: 7 years
• Regulated industries: Per compliance requirements

Support

For questions about this audit bundle:

1. Contact the organization's Stella Ops administrator
2. Reference the Bundle ID from manifest.json
3. Include the artifact digest

---

Last updated: 2026-01-17 (UTC)