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

```bash
# 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

```bash
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:
   ```bash
   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

```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:

```bash
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:**
```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.

```json
{
  "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:

```json
{
  "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:

```json
{
  "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

```bash
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)_