Evidence Packs

Evidence packs capture the security posture of a sovereign TramAI deployment as a deterministic, safe-for-auditors JSON artifact. They contain no secrets, tokens, prompts, stack traces, or filesystem paths — every identifier is sanitized through EvidenceSafeString before being written.

Module: tramai-sovereign — SovereignEvidencePackV1 DTO, SovereignEvidencePackWriter, and SovereignEvidencePackGenerator.

What

An evidence pack is a SovereignEvidencePackV1 DTO that summarizes:

• Deployment identity — deployment mode (STANDARD or OFFLINE), allowed models (sorted), allowed providers (sorted), trust zone mappings
• Artifact verification — settings snapshot, per-artifact receipts (manifest digest, artifact count, total size)
• Zero-egress evidence — optional subsection from offline deployment testing (loopback invocations, TCP/DNS probes)
• Audit chain — optional validation of the hash-chained audit event integrity
• Supply chain — optional SBOM linkage (CycloneDX format with SHA-256 digest)
• Release bundle — optional build artifact evidence with Maven coordinates and digests for every JAR
• CI/CD attestation — optional build provenance from a CI pipeline (GitHub Actions)

Deterministic JSON

The SovereignEvidencePackWriter produces JSON with:

• Stable field ordering matching the data class declaration order
• Full JSON control-character escaping (all chars < 0x20 as \uXXXX)
• No external JSON library dependency
• Parent directory auto-creation

Same input produces identical output every time — suitable for hashing, signing, or comparing in CI.

Safety Guarantees

All string values are validated through EvidenceSafeString.sanitize():

• Rejects identifiers containing path prefixes (/tmp/, /home/, /Users/)
• Rejects identifiers containing secrets-adjacent terms (token, secret, password, prompt, rawRequest, rawResponse, stacktrace)
• Rejects control characters
• Rejects Windows drive paths

SHA-256 digest values (sha256:<hex>) bypass string sanitization and are validated with strict regex instead.

When to Use

Use evidence packs when:

• You need audit-grade documentation of your TramAI deployment's security posture
• You need CI attestation — generate and upload evidence packs as CI artifacts with provenance
• You need enterprise security review artifacts that auditors can inspect without access to the runtime
• You need air-gap validation evidence — prove that an offline deployment has zero egress
• You need a verifiable deployment snapshot — hash the pack and sign it

Do not use evidence packs for runtime monitoring or live debugging — they are static snapshots.

Quickstart

Basic Generation

// 1. Build your sovereign runtime
val tramai = SovereignTramai.builder()
    .profile(profile)
    .modelRegistry(registry)
    .auditStore(auditStore)
    .provider(ollamaProvider, name = "ollama", default = true)
    .model("llama3.2", "ollama")
    .modelArtifactVerifier(verifier)
    .modelArtifactVerificationSettings(ModelArtifactVerificationSettings(enabled = true))
    .build()

// 2. Generate an evidence pack
val pack = tramai.evidencePack()

// 3. Write to file
SovereignEvidencePackWriter.write(pack, Paths.get("evidence/sovereign-evidence.json"))

With All Optional Sub-Sections

val pack = tramai.evidencePack(
    zeroEgress = ZeroEgressEvidenceV1(
        deploymentMode = "OFFLINE",
        runtimeBuildSucceeded = true,
        loopbackProviderInvocationSucceeded = true,
        loopbackProviderInvocationCount = 3,
        externalTcpProbeBlocked = true,
        externalDnsProbeBlocked = true,
    ),
    auditChain = AuditChainEvidenceV1(
        isValid = true,
        totalEvents = 42,
    ),
    supplyChain = SupplyChainEvidenceV1(
        schemaVersion = 1,
        sbomFormat = "CycloneDX",
        sbomSpecVersion = "1.6",
        sbomFileName = "bom.json",
        sbomSha256 = "sha256:abc123def456abc123def456abc123def456abc123def456abc123def456abcd",
        generatedBy = "CycloneDX Gradle Plugin 3.2.4",
    ),
    releaseBundle = ReleaseBundleEvidenceV1(
        schemaVersion = 1,
        buildTool = "Gradle",
        javaVersion = "21",
        gradleVersion = "8.12",
        artifacts = listOf(
            ReleaseArtifactEvidenceV1(
                groupId = "dev.tramai",
                artifactId = "tramai-core",
                version = "0.3.0",
                classifier = null,
                extension = "jar",
                fileName = "tramai-core-0.3.0.jar",
                sha256 = "sha256:abc123def456abc123def456abc123def456abc123def456abc123def456abcd",
                sizeBytes = 245760,
            ),
        ),
    ),
    attestation = AttestationEvidenceV1(
        schemaVersion = 1,
        provider = "GitHub Artifact Attestations",
        workflowName = "deploy",
        workflowRunId = "1234567890",
        repository = "my-org/my-repo",
        commitSha = "abc123def456abc123def456abc123def456abc1",
        attestedSubjects = listOf(
            AttestedSubjectV1(
                fileName = "sovereign-evidence.json",
                sha256 = "sha256:abc123def456abc123def456abc123def456abc123def456abc123def456abcd",
                attestationType = "build-provenance",
            ),
        ),
    ),
)

Evidence Pack Schema (V1)

SovereignEvidencePackV1

ArtifactEvidenceV1

ZeroEgressEvidenceV1

AuditChainEvidenceV1

SupplyChainEvidenceV1

AttestationEvidenceV1

AttestedSubjectV1

ReleaseBundleEvidenceV1

ReleaseArtifactEvidenceV1

Writer

The SovereignEvidencePackWriter produces deterministic JSON output:

SovereignEvidencePackWriter.write(pack, Paths.get("evidence/pack.json"))

Output format:

{
    "schemaVersion": 1,
    "deploymentMode": "OFFLINE",
    "allowedModels": [
        "llama3.2"
    ],
    "allowedProviders": [
        "ollama"
    ],
    "providerZones": {
        "ollama": "LOCAL"
    },
    "artifactVerificationSettings": {
        "enabled": true,
        "requireDigestForLocalModels": true
    },
    "artifacts": [
        {
            "registryEntryId": "ollama-llama3.2",
            "manifestDigest": "sha256:abc123def456abc123def456abc123def456abc123def456abc123def456abcd",
            "modelName": "llama3.2",
            "verifiedAt": "2025-06-14T12:00:00Z",
            "artifactCount": 3,
            "totalSizeBytes": 1234567890
        }
    ],
    "zeroEgress": null,
    "auditChain": null,
    "supplyChain": null,
    "releaseBundle": null,
    "attestation": null,
    "generatedAt": "2025-06-14T12:00:00Z"
}

Generator Validation

The SovereignEvidencePackGenerator.generate() method performs validation and sanitization:

1. EvidenceSafeString sanitization — all model names, provider names, zone keys, registry entry IDs, and workflow names are sanitized (rejects paths, secrets-adjacent terms, control characters)
2. Supply chain validation — sbomSha256 must match ^sha256:[a-fA-F0-9]{64}$, schemaVersion must be 1, sbomFileName must not contain path separators
3. Attestation validation — workflowRunId must be numeric, repository must match owner/repo, commitSha must be 40 hex chars, attestedSubjects must not be empty, attestationType must be "build-provenance" or "sbom"
4. Release bundle validation — sha256 for each artifact must match ^sha256:[a-fA-F0-9]{64}$, sizeBytes must be >= 0, artifacts list must not be empty
5. Deterministic sorting — allowedModels and allowedProviders are sorted; providerZones keys are sorted alphabetically in the writer

All validation failures use fixed safe-code error messages:

• "evidence-unsafe-identifier"
• "evidence-unsafe-digest-format"
• "evidence-unsafe-control-character"
• "evidence-unsupported-supply-chain-schema-version"
• "evidence-unsupported-attestation-schema-version"
• "evidence-unsafe-attestation-workflow-run-id"
• "evidence-unsafe-attestation-commit-sha"
• "evidence-unsafe-attestation-repository"
• "evidence-unsafe-attestation-subjects"
• "evidence-unsupported-attestation-type"
• "evidence-unsupported-release-bundle-schema-version"
• "evidence-unsafe-release-artifacts"
• "evidence-unsafe-artifact-size"

CI Workflow Integration

Evidence packs are designed for CI artifact upload with attestation:

# .github/workflows/deploy.yml
steps:
  - name: Generate evidence pack
    run: ./gradlew sovereignEvidencePack

  - name: Sign the evidence pack
    run: |
      openssl dgst -sha256 -sign private-key.pem \
        -out build/evidence/sovereign-evidence.json.sig \
        build/evidence/sovereign-evidence.json

  - name: Upload evidence
    uses: actions/upload-artifact@v4
    with:
      name: sovereign-evidence
      path: build/evidence/

Extension Pattern

To add a new evidence sub-section:

1. Define the DTO — a new data class like ZeroEgressEvidenceV1 with documented properties and @param KDoc
2. Add to SovereignEvidencePackV1 — add an optional field (val newSection: NewSectionV1? = null)
3. Update the writer — add a serializeNewSection() method and wire it into serialize() matching the data class declaration order
4. Update the generator — add sanitization and validation in SovereignEvidencePackGenerator.generate()

Limitations

• Snapshot-only — evidence packs capture a point-in-time view; they are not updated automatically
• No secrets — by design, evidence packs cannot contain secrets, tokens, or credentials (EvidenceSafeString actively rejects them)
• No runtime data — no prompts, responses, or model outputs are included
• Manual sub-sections — zeroEgress, auditChain, supplyChain, releaseBundle, and attestation must be constructed manually and passed to evidencePack()
• Schema version 1 — the current schema is v1; breaking changes will increment schemaVersion

Next Steps

• Offline Deployment — generate zero-egress evidence for air-gapped deployments
• Artifact Verification — verification receipts feed into evidence packs
• Sovereign Mode — understanding the sovereign runtime