Add evidence bundle manifest

Author: RamazanKara

CHANGELOG.md

@@ -34,6 +34,7 @@
 - Added project readiness status with pipeline summaries, export readiness, next actions, and `--json` output.
 - Added `openexit run` to execute assessment, mapping, full generation, validation, status reporting, and optional evidence bundle export for collected projects.
 - Added `openexit demo` with embedded redacted fixtures for complete release-binary demos across supported assessment paths.
+- Added a machine-readable evidence bundle manifest with build metadata, validation summary, and per-file SHA-256 digests.
 - Updated CI and release workflows to Node.js 24-native GitHub Actions.
 
 ## 0.1.0 - 2026-05-24

README.md

@@ -118,7 +118,7 @@ Included in the current implementation:
 - ArgoCD starter manifest.
 - Typed migration plan manifest and phase-gate Markdown plan.
 - Validation report with embedded JSON Schema checks, Grafana dashboard, Prometheus alert, OpenTelemetry collector, ArgoCD, Forgejo migration, identity realm/client, edge VCL/HAProxy/Coraza, and LiteLLM/vLLM candidate checks, YAML/JSON parsing, evidence ref checks, secret scan, and optional `promtool`/`kubeconform` checks.
-- Evidence bundle export.
+- Evidence bundle export with README, checksums, and a machine-readable manifest.
 - Evidence bundle path-safety checks that reject symlinks in exported project sections.
 - No-op assist provider and explicit opt-in LiteLLM assist.
 - GitHub Enterprise to Forgejo assessment path with fixture import and live repository inventory collection.

docs/cli.md

@@ -29,7 +29,7 @@ The checked-in Datadog example can be refreshed with `make example VERSION=0.1.0
 
 `openexit validate` performs typed consistency checks, embedded JSON Schema validation, Grafana dashboard candidate validation, Prometheus alert-rule candidate validation, OpenTelemetry collector candidate validation, ArgoCD candidate validation, Forgejo migration candidate validation, identity realm/client candidate validation, edge VCL/HAProxy/Coraza candidate validation, LiteLLM/vLLM candidate validation, YAML/JSON parse checks, evidence reference checks, secret scanning, and optional external tool checks when `promtool` or `kubeconform` are installed.
 
-`openexit export` refuses to package symlinks from exported project sections, even with `--force`, so evidence bundles cannot accidentally include files from outside the project tree.
+`openexit export` refuses to package symlinks from exported project sections, even with `--force`, so evidence bundles cannot accidentally include files from outside the project tree. Exported zips include `openexit-evidence/manifest.json` with build metadata, project source/target, validation totals, and per-file SHA-256 digests, plus `checksums.txt` for archive-level verification.
 
 Generate individual artifacts with `openexit generate --artifact <name>`. The primary Datadog path supports `mapping`, `assessment`, `risk-register`, `manual-review`, `cost-drivers`, `target-architecture`, `acceptance-criteria`, `rollback-plan`, `runbook`, `restore-drill-checklist`, `alert-shadowing-plan`, `migration-plan`, `grafana-dashboards`, `prometheus-rules`, `opentelemetry`, and `argocd`. The GitHub Enterprise path also supports `forgejo-migration-candidate`; the identity path also supports `realm-client-candidate`; the edge path also supports `vcl-candidates`, `haproxy-candidates`, and `coraza-rule-candidates`; the AI provider path also supports `litellm-config-candidate`.
 

docs/release.md

@@ -17,7 +17,7 @@ Release-blocking v0.1 requirements:
 - Grafana, Prometheus, OpenTelemetry, and ArgoCD candidate generators.
 - Typed migration plan manifest with assessment, pilot, shadow, and cutover phase gates.
 - Validation engine with embedded JSON Schema checks, Grafana dashboard, Prometheus alert, OpenTelemetry collector, ArgoCD, Forgejo migration, identity realm/client, edge VCL/HAProxy/Coraza, and LiteLLM/vLLM candidate checks, YAML/JSON parsing, evidence refs, secret scan, optional promtool, and optional kubeconform.
-- Evidence bundle export with checksums and OpenExit version metadata.
+- Evidence bundle export with checksums, a machine-readable manifest, and OpenExit version metadata.
 - No-op AI assist and optional external assist behind explicit opt-in.
 - Documentation, examples, CI, release draft workflow, and reproducible release artifacts.
 
@@ -60,6 +60,7 @@ The AI provider path is complete for local fixture assessment workflows and incl
 - [ ] `validation/validation-report.md` includes `litellm-config-candidate: passed` for the OpenAI/Anthropic to vLLM/LiteLLM pipeline.
 - [ ] `CHANGELOG.md` has a `0.1.0` section.
 - [ ] Exported bundle README includes version, commit, build date, bundle timestamp, and candidate warning.
+- [ ] Exported bundle `manifest.json` includes build metadata, project source/target, validation totals, and per-file SHA-256 digests.
 - [ ] Export refuses symlinks in exported project sections, including when `--force` is used.
 - [ ] No credentials, tokens, passwords, or private keys are present in fixtures, generated files, docs, or bundles.
 - [ ] Draft release notes have been reviewed.

docs/security.md

@@ -14,7 +14,7 @@ OpenExit is designed for local-first assessment work.
 - The Anthropic collector records aggregate Messages API usage and server tool metadata only; it never requests or stores raw prompts, responses, or API key values.
 - Raw source evidence is redacted before it is written locally.
 - Validation scans JSON, YAML, Markdown, text, VCL, HAProxy, and Coraza-style generated artifacts for secret-like values.
-- Exported bundles contain local manifests, generated candidates, validation output, checksums, and redacted evidence.
+- Exported bundles contain local manifests, generated candidates, validation output, a machine-readable bundle manifest, checksums, and redacted evidence.
 - Export refuses symlinks in exported project sections so bundle contents cannot follow paths outside the project tree.
 - AI assist is optional, disabled by default, and never part of deterministic validation or export.
 

examples/datadog-to-grafana/README.md

@@ -9,6 +9,7 @@ make example VERSION=0.1.0-dev
 ```
 
 This refreshes `examples/datadog-to-grafana/output/` and writes an ignored bundle to `examples/datadog-to-grafana/openexit-example.zip`.
+The bundle includes `openexit-evidence/manifest.json` for machine-readable audit metadata and per-file digests.
 
 For a release-binary smoke test that does not depend on repository-local fixtures, run:
 

internal/app/e2e_test.go

@@ -1125,6 +1125,7 @@ func expectedProjectFiles() []string {
 func expectedBundleFiles() []string {
 	files := []string{
 		"openexit-evidence/README.md",
+		"openexit-evidence/manifest.json",
 		"openexit-evidence/checksums.txt",
 	}
 	for _, rel := range expectedProjectFiles() {
@@ -1167,9 +1168,78 @@ func assertBundle(bundlePath string, expected []string) error {
 			return &checksumError{message: "bundle README missing marker " + string(marker)}
 		}
 	}
+	if err := verifyBundleManifest(files); err != nil {
+		return err
+	}
 	return verifyChecksums(files)
 }
 
+func verifyBundleManifest(files map[string][]byte) error {
+	data, ok := files["openexit-evidence/manifest.json"]
+	if !ok {
+		return &missingBundleFileError{name: "openexit-evidence/manifest.json"}
+	}
+	var manifest struct {
+		APIVersion string `json:"apiVersion"`
+		Kind       string `json:"kind"`
+		Build      struct {
+			Version string `json:"version"`
+			Commit  string `json:"commit"`
+			Date    string `json:"date"`
+		} `json:"build"`
+		Project struct {
+			Name   string `json:"name"`
+			Source string `json:"source"`
+			Target string `json:"target"`
+		} `json:"project"`
+		Validation struct {
+			Status   string `json:"status"`
+			Checks   int    `json:"checks"`
+			Passed   int    `json:"passed"`
+			Failed   int    `json:"failed"`
+			Warnings int    `json:"warnings"`
+		} `json:"validation"`
+		Files []struct {
+			Path   string `json:"path"`
+			Size   int64  `json:"size"`
+			SHA256 string `json:"sha256"`
+		} `json:"files"`
+	}
+	if err := json.Unmarshal(data, &manifest); err != nil {
+		return err
+	}
+	if manifest.APIVersion != "openexit.dev/v1alpha1" || manifest.Kind != "EvidenceBundle" {
+		return &checksumError{message: "unexpected bundle manifest identity"}
+	}
+	if manifest.Project.Source != "datadog" || manifest.Project.Target != "grafana-lgtm" {
+		return &checksumError{message: "bundle manifest has wrong source/target"}
+	}
+	if manifest.Validation.Status != "passed" || manifest.Validation.Checks == 0 || manifest.Validation.Failed != 0 {
+		return &checksumError{message: "bundle manifest has wrong validation summary"}
+	}
+	if manifest.Build.Version == "" || manifest.Build.Commit == "" || manifest.Build.Date == "" {
+		return &checksumError{message: "bundle manifest missing build metadata"}
+	}
+	seen := map[string]bool{}
+	for _, entry := range manifest.Files {
+		data, ok := files["openexit-evidence/"+entry.Path]
+		if !ok {
+			return &missingBundleFileError{name: "openexit-evidence/" + entry.Path}
+		}
+		sum := sha256.Sum256(data)
+		if hex.EncodeToString(sum[:]) != entry.SHA256 || int64(len(data)) != entry.Size {
+			return &checksumError{message: "bundle manifest digest mismatch for " + entry.Path}
+		}
+		seen[entry.Path] = true
+	}
+	for _, rel := range []string{"openexit.yaml", "validation/openexit.validation.yaml", "generated-config/prometheus/rules/datadog-monitor-candidates.yaml"} {
+		if !seen[rel] {
+			return &missingBundleFileError{name: "bundle manifest entry " + rel}
+		}
+	}
+	return nil
+}
+
 func verifyChecksums(files map[string][]byte) error {
 	checksumData, ok := files["openexit-evidence/checksums.txt"]
 	if !ok {

internal/export/bundle.go

@@ -5,6 +5,7 @@ import (
 	"bytes"
 	"crypto/sha256"
 	"encoding/hex"
+	"encoding/json"
 	"fmt"
 	"io"
 	"os"
@@ -15,6 +16,7 @@ import (
 
 	"github.com/RamazanKara/openexit/internal/validate"
 	"github.com/RamazanKara/openexit/internal/version"
+	"gopkg.in/yaml.v3"
 )
 
 type Options struct {
@@ -42,7 +44,43 @@ func Bundle(opts Options) error {
 	if err != nil {
 		return err
 	}
-	return writeZip(opts.ProjectDir, opts.Out, files)
+	return writeZip(opts.ProjectDir, opts.Out, files, report)
+}
+
+type BundleManifest struct {
+	APIVersion  string               `json:"apiVersion"`
+	Kind        string               `json:"kind"`
+	GeneratedAt string               `json:"generatedAt"`
+	Build       BundleBuild          `json:"build"`
+	Project     BundleProject        `json:"project"`
+	Validation  BundleValidation     `json:"validation"`
+	Files       []BundleManifestFile `json:"files"`
+}
+
+type BundleBuild struct {
+	Version string `json:"version"`
+	Commit  string `json:"commit"`
+	Date    string `json:"date"`
+}
+
+type BundleProject struct {
+	Name   string `json:"name"`
+	Source string `json:"source,omitempty"`
+	Target string `json:"target,omitempty"`
+}
+
+type BundleValidation struct {
+	Status   string `json:"status"`
+	Checks   int    `json:"checks"`
+	Passed   int    `json:"passed"`
+	Failed   int    `json:"failed"`
+	Warnings int    `json:"warnings"`
+}
+
+type BundleManifestFile struct {
+	Path   string `json:"path"`
+	Size   int64  `json:"size"`
+	SHA256 string `json:"sha256"`
 }
 
 func bundleFiles(projectDir string) ([]string, error) {
@@ -84,7 +122,7 @@ func bundleFiles(projectDir string) ([]string, error) {
 	return files, err
 }
 
-func writeZip(projectDir, out string, files []string) (err error) {
+func writeZip(projectDir, out string, files []string, report *validate.Report) (err error) {
 	if err := os.MkdirAll(filepath.Dir(out), 0o755); err != nil && filepath.Dir(out) != "." {
 		return err
 	}
@@ -104,6 +142,7 @@ func writeZip(projectDir, out string, files []string) (err error) {
 		}
 	}()
 	checksums := map[string]string{}
+	var manifestFiles []BundleManifestFile
 	prefix := "openexit-evidence"
 	fixedTime := time.Date(2026, 5, 24, 0, 0, 0, 0, time.UTC)
 	generatedAt := time.Now().UTC().Format(time.RFC3339)
@@ -118,20 +157,25 @@ func writeZip(projectDir, out string, files []string) (err error) {
 			return err
 		}
 		sum := sha256.Sum256(data)
-		checksums[filepath.ToSlash(rel)] = hex.EncodeToString(sum[:])
+		digest := hex.EncodeToString(sum[:])
+		relName := filepath.ToSlash(rel)
+		checksums[relName] = digest
+		manifestFiles = append(manifestFiles, BundleManifestFile{
+			Path:   relName,
+			Size:   int64(len(data)),
+			SHA256: digest,
+		})
 	}
-	var checks bytes.Buffer
-	keys := make([]string, 0, len(checksums))
-	for path := range checksums {
-		keys = append(keys, path)
-	}
-	sort.Strings(keys)
-	for _, path := range keys {
-		_, _ = fmt.Fprintf(&checks, "%s  %s\n", checksums[path], path)
+
+	manifestData, err := json.MarshalIndent(buildManifest(projectDir, generatedAt, report, manifestFiles), "", "  ")
+	if err != nil {
+		return err
 	}
-	if err := addZipFile(zw, prefix+"/checksums.txt", fixedTime, checks.Bytes()); err != nil {
+	manifestData = append(manifestData, '\n')
+	if err := addSyntheticZipFile(zw, prefix, "manifest.json", fixedTime, manifestData, checksums); err != nil {
 		return err
 	}
+
 	readme := fmt.Sprintf(`# OpenExit Evidence Bundle
 
 Generated by OpenExit.
@@ -142,8 +186,94 @@ Generated by OpenExit.
 - Bundle generated at: %s
 
 This bundle contains local inventory, assessment, generated candidates, validation, and redacted evidence. Candidate configs are not production-ready until reviewed.
+The machine-readable bundle manifest is available at manifest.json.
 `, version.Version, version.Commit, version.Date, generatedAt)
-	return addZipFile(zw, prefix+"/README.md", fixedTime, []byte(readme))
+	if err := addSyntheticZipFile(zw, prefix, "README.md", fixedTime, []byte(readme), checksums); err != nil {
+		return err
+	}
+
+	var checks bytes.Buffer
+	keys := make([]string, 0, len(checksums))
+	for path := range checksums {
+		keys = append(keys, path)
+	}
+	sort.Strings(keys)
+	for _, path := range keys {
+		_, _ = fmt.Fprintf(&checks, "%s  %s\n", checksums[path], path)
+	}
+	return addZipFile(zw, prefix+"/checksums.txt", fixedTime, checks.Bytes())
+}
+
+func buildManifest(projectDir, generatedAt string, report *validate.Report, files []BundleManifestFile) BundleManifest {
+	return BundleManifest{
+		APIVersion:  "openexit.dev/v1alpha1",
+		Kind:        "EvidenceBundle",
+		GeneratedAt: generatedAt,
+		Build: BundleBuild{
+			Version: version.Version,
+			Commit:  version.Commit,
+			Date:    version.Date,
+		},
+		Project:    readBundleProject(projectDir),
+		Validation: validationSummary(report),
+		Files:      files,
+	}
+}
+
+func readBundleProject(projectDir string) BundleProject {
+	project := BundleProject{Name: filepath.Base(projectDir)}
+	data, err := os.ReadFile(filepath.Join(projectDir, "openexit.yaml"))
+	if err != nil {
+		return project
+	}
+	var manifest struct {
+		Metadata struct {
+			Name string `yaml:"name"`
+		} `yaml:"metadata"`
+		Source struct {
+			Type string `yaml:"type"`
+		} `yaml:"source"`
+		Target struct {
+			Type string `yaml:"type"`
+		} `yaml:"target"`
+	}
+	if err := yaml.Unmarshal(data, &manifest); err != nil {
+		return project
+	}
+	if strings.TrimSpace(manifest.Metadata.Name) != "" {
+		project.Name = manifest.Metadata.Name
+	}
+	project.Source = manifest.Source.Type
+	project.Target = manifest.Target.Type
+	return project
+}
+
+func validationSummary(report *validate.Report) BundleValidation {
+	summary := BundleValidation{Status: reportStatus(report)}
+	if report == nil {
+		return summary
+	}
+	summary.Checks = len(report.Checks)
+	for _, check := range report.Checks {
+		switch check.Status {
+		case "passed":
+			summary.Passed++
+		case "failed":
+			summary.Failed++
+		case "warning":
+			summary.Warnings++
+		}
+	}
+	return summary
+}
+
+func addSyntheticZipFile(zw *zip.Writer, prefix, rel string, modTime time.Time, data []byte, checksums map[string]string) error {
+	if err := addZipFile(zw, prefix+"/"+rel, modTime, data); err != nil {
+		return err
+	}
+	sum := sha256.Sum256(data)
+	checksums[rel] = hex.EncodeToString(sum[:])
+	return nil
 }
 
 func addZipFile(zw *zip.Writer, name string, modTime time.Time, data []byte) error {