{"id":51620177,"url":"https://github.com/aatuh/evydence","last_synced_at":"2026-07-12T18:32:05.160Z","repository":{"id":360972588,"uuid":"1252485654","full_name":"aatuh/evydence","owner":"aatuh","description":"Self-hosted VEX-first release evidence ledger for customer CVE, SBOM, provenance, and release-review questions.","archived":false,"fork":false,"pushed_at":"2026-07-11T13:41:27.000Z","size":2091,"stargazers_count":0,"open_issues_count":12,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-07-12T18:32:02.915Z","etag":null,"topics":["api-first","audit-log","compliance-readiness","evidence-ledger","golang","openapi","release-evidence","sbom","self-hosted","supply-chain-security","vex","vulnerability-management"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aatuh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":"GOVERNANCE.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-28T15:09:02.000Z","updated_at":"2026-07-11T13:41:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aatuh/evydence","commit_stats":null,"previous_names":["aatuh/evydence"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aatuh/evydence","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aatuh%2Fevydence","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aatuh%2Fevydence/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aatuh%2Fevydence/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aatuh%2Fevydence/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aatuh","download_url":"https://codeload.github.com/aatuh/evydence/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aatuh%2Fevydence/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35400292,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-12T02:00:06.386Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-first","audit-log","compliance-readiness","evidence-ledger","golang","openapi","release-evidence","sbom","self-hosted","supply-chain-security","vex","vulnerability-management"],"created_at":"2026-07-12T18:32:04.385Z","updated_at":"2026-07-12T18:32:05.143Z","avatar_url":"https://github.com/aatuh.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Evydence\n\n[![CI](https://github.com/aatuh/evydence/actions/workflows/ci.yml/badge.svg)](https://github.com/aatuh/evydence/actions/workflows/ci.yml)\n[![OpenSSF Scorecard](https://github.com/aatuh/evydence/actions/workflows/scorecard.yml/badge.svg)](https://github.com/aatuh/evydence/actions/workflows/scorecard.yml)\n[![License: AGPL-3.0-only](https://img.shields.io/badge/license-AGPL--3.0--only-blue.svg)](LICENSE)\n![Go Version](https://img.shields.io/badge/go-1.25+-00ADD8.svg)\n![OpenAPI](https://img.shields.io/badge/OpenAPI-186%20precise%20operations-brightgreen.svg)\n![Coverage Gate](https://img.shields.io/badge/production%20coverage-80%25+-brightgreen.svg)\n\nEvydence is a self-hosted, API-first release evidence ledger for product\nsecurity, AppSec, platform, release engineering, and compliance-readiness teams\nthat need to answer customer CVE, SBOM, provenance, and release-review\nquestions with signed, customer-safe release evidence bundles.\n\nWebsite: \u003chttps://evydence.app\u003e\n\nThe core buyer question is: \"This CVE appears in your SBOM for this release.\nAre you affected, why or why not, who approved that decision, and what evidence\ncan we verify?\" Evydence records the SBOM, vulnerability scan, VEX or manual\ndecision, build provenance, artifact digest, exceptions, release bundle, and\ncustomer package that support the answer.\n\n| Start here | Use this when you want to |\n| --- | --- |\n| [Customer CVE review demo](examples/customer-cve-review-demo/README.md) | Inspect the no-external-services buyer proof path. |\n| [Buyer evaluation overview](docs/buyer-overview.md) | Follow the buyer package, demo, release-evidence, and API review path. |\n| [Operator overview](docs/operator-overview.md) | Follow the self-hosted install, runbook, and production-gate path. |\n| [OpenAPI reference](docs/reference/openapi.md) | Review the `/v1` API contract and generated schemas. |\n| [Rendered OpenAPI docs](docs/openapi/index.html) | Browse the generated static operation and schema reference. |\n| [Install and operate](docs/how-to/install-and-operate.md) | Run the self-hosted API/worker path with PostgreSQL and object storage. |\n| [Release evidence index](docs/reference/release-evidence-index.md) | Verify public release artifacts, checksums, production-check evidence, and limitations. |\n\nBefore Evydence, teams often stitch together scanner exports, CI logs, Slack\napprovals, spreadsheets, object-storage folders, and one-off customer answers.\nAfter Evydence, the same release has tenant-scoped API records, append-only\ndecisions, tamper-evident audit entries, signed bundles, reproducible reports,\nand scoped packages that state gaps, assumptions, exceptions, and limitations.\n\nIt does not make legal compliance conclusions, grant certification, prove SBOM\ncompleteness, treat scanner findings as authoritative, or guarantee release\nsecurity.\n\n## Current Status\n\n- Best for: evaluation, pilots, and controlled internal self-hosted use after operator review.\n- Not for: broad HA production, regulated production without review, hosted SaaS, or legal/compliance conclusions.\n- Current public release candidate metadata is tracked in\n  [`release/current.json`](release/current.json); GitHub Releases remains the\n  external source of truth for published tags and assets.\n- Current release evidence links the Release Artifacts workflow, public CI\n  `Production Check` workflow run, CodeQL run, `coverage.out`, and\n  `release-check-summary.txt` from the\n  [Release evidence index](docs/reference/release-evidence-index.md).\n- See [Production readiness](docs/reference/production-readiness.md),\n  [Pilot deployment checklist](docs/how-to/pilot-deployment-checklist.md), and\n  [Release evidence index](docs/reference/release-evidence-index.md) before\n  running beyond local evaluation.\n\n## What Question Does Evydence Answer?\n\nEvydence is designed to make release-risk answers traceable to concrete\nobjects instead of unsupported prose:\n\n| Customer or internal review question | Evydence object that carries the answer |\n| --- | --- |\n| Are we affected by `CVE-X` in release `Y`? | Vulnerability finding plus VEX/manual decision, exception, or remediation record linked to the release. |\n| Which SBOM was used for this answer? | SBOM record linked to the release and artifact, with raw payload hash and object reference. |\n| Which scanner result raised the finding? | Vulnerability scan and normalized finding record with scanner metadata. |\n| Who approved or recorded the decision? | Append-only vulnerability decision, exception, approval, and audit-chain entries with actor context. |\n| What evidence supports \"not affected\" or \"fixed\"? | VEX impact/action statements, linked evidence, artifact digest, build provenance, and verification receipts. |\n| What can be safely shared with a customer? | Redaction profile, customer package, evidence bundle, and package manifest with limitations. |\n| How can the customer verify the package? | Signed release bundle, package manifest hash, OpenAPI-backed API records, audit-chain verification, and offline verifier paths. |\n\n## Current Limitations\n\n- Current status is a controlled self-hosted production candidate for\n  evaluation, pilots, and controlled internal production after operator review.\n- Production API deployments use one API writer replica; workers may scale\n  through PostgreSQL outbox locking.\n- Container publication uses the maintainer-run GHCR workflow and must be\n  verified by immutable digest and cosign evidence; Helm installs should not use\n  floating image tags.\n- Native PKCS#11/HSM module execution, broad provider-side WORM enforcement\n  proof beyond recorded object-lock verification metadata, direct\n  provider-specific management API clients, external group synchronization,\n  regulated production, and hosted SaaS production remain outside the current\n  supported profile unless a deployment review closes those gaps.\n\n## Current Implementation\n\nThis repository contains a Go implementation under module\n`github.com/aatuh/evydence`. The current public release candidate is\n[`v0.1.0-rc.7`](https://github.com/aatuh/evydence/releases/tag/v0.1.0-rc.7),\npublished as a prerelease with signed archives, checksums, OpenAPI and\nmigration checksums, coverage output, production-check summary, SBOM/provenance\nmetadata, release notes, and a signed release manifest.\n\nUse GitHub Releases and the checked release evidence artifacts as the operator\ninstall source for the release-candidate line. Source checkout remains the\ndevelopment path.\n\nContainer images for the release-candidate line are published, when the\nmaintainer image workflow has run for the tag, as\n`ghcr.io/aatuh/evydence:\u003ctag\u003e`. Treat the digest and cosign evidence as the\noperator trust input, not the mutable tag alone. The current public release\ncandidate metadata distinguishes release archive evidence from the last\nverified project-owned image evidence because image publication is a separate\nworkflow.\n\n## Fastest Proof Path\n\nFor a reviewer-first path, follow\n[Evaluate Evydence in 10 minutes](docs/tutorials/evaluate-in-10-minutes.md).\nFor a first local API flow, follow [Getting started](docs/tutorials/getting-started.md).\nFor durable local evaluation, run the production-like Compose rehearsal in\n[Install and operate](docs/how-to/install-and-operate.md).\nFor the release-evidence path to inspect first, use the\n[end-to-end release evidence example](examples/end-to-end-release-evidence/README.md).\nFor a no-external-services buyer proof, run the\n[customer CVE review demo](examples/customer-cve-review-demo/README.md).\nFor the first CI wiring example, start with the\n[GitHub Actions quickstart release evidence workflow](docs/github-actions/quickstart-release-evidence.yml),\nthen move to the scanner-oriented workflow once your runner has pinned scanner\nversions.\nFor concrete JSON outputs to inspect without running a full stack, open the\nsample readiness report,\n[customer-package manifest](examples/end-to-end-release-evidence/sample-customer-package-manifest.json),\n[downloadable customer package](examples/end-to-end-release-evidence/sample-customer-package.zip),\nand audit-chain verification fixtures in that example or load the bundled\npackage in the [local package viewer](docs/how-to/view-packages.md).\n\nRelease-candidate artifacts and their verification commands are indexed in\n[Release evidence index](docs/reference/release-evidence-index.md). Start with\nthe public `v0.1.0-rc.7` release if you want to evaluate release verification\nbefore running the API.\n\nTo verify the public release assets from a clean temporary directory on Linux\namd64, run:\n\n```sh\nmake public-release-verify TAG=v0.1.0-rc.7\n```\n\nThe VEX-first evidence flow to evaluate first is:\n\n1. Create a product, release, and artifact.\n2. Upload SBOM evidence for the artifact.\n3. Upload vulnerability scan evidence for the release.\n4. Record a VEX decision or approved exception for an intentionally blocking finding.\n5. Generate a release-readiness report.\n6. Create a signed release bundle and customer-safe package or evidence bundle.\n7. View the package locally and verify the bundle, package manifest, and audit chain.\n\nFor a visual preview of the customer-package review surface, see the\n[package viewer guide](docs/how-to/view-packages.md). The preview uses\nnon-sensitive bundled sample data, includes desktop and mobile screenshots, and\ndoes not upload files.\n\n## Why Evydence Instead Of Existing Tools?\n\n- Dependency-Track and vulnerability-management tools are strong for SBOM and\n  finding workflows; Evydence focuses on release-level evidence, decisions,\n  bundles, audit chains, controls, customer packages, and review limitations.\n- GUAC-style supply-chain graph tools are strong for relationship exploration;\n  Evydence focuses on release manifests, verification receipts, and\n  reviewer-facing package evidence.\n- OpenVEX-focused tooling is strong for authoring or consuming VEX statements;\n  Evydence stores VEX as evidence and links normalized decisions to releases,\n  scans, SBOM context, exceptions, and customer-safe packages.\n- Vanta, Drata, and similar SaaS GRC tools are broad compliance platforms;\n  Evydence is a self-hosted technical evidence ledger and does not claim legal\n  compliance or certification.\n- Building this in-house with object storage, scripts, spreadsheets, and ad hoc\n  Postgres tables is possible; Evydence provides a versioned API, OpenAPI\n  contract, tenant scoping, idempotency, audit chains, release evidence, and\n  checked non-claim language from the start.\n\n### Core Product Path\n\n- `/v1` API, committed OpenAPI contract, idempotent create/action requests, and\n  tenant-scoped Problem Details responses.\n- Products, releases, artifacts, SBOMs, vulnerability scans, VEX/manual\n  decisions, exceptions, approvals, release bundles, audit-chain verification,\n  and customer-safe packages.\n- Release-readiness, vulnerability-decision, control-coverage, CRA-readiness,\n  security-summary, package, retention, and backup reports with assumptions and\n  limitations.\n- PostgreSQL, object storage, outbox worker, CLI upload/verification helpers,\n  GitHub Actions/GitLab examples, SDK wrappers, Compose, Helm, and air-gapped\n  packaging paths.\n\nFor the full advanced capability inventory, including identity, controls,\nsource/deployment/incident evidence, retention, backup, signing-provider\nprofiles, provider verification, transparency records, and\nimplemented-but-partial areas, see [Capability map](docs/reference/capability-map.md).\n\n## License, Security, Support, And Governance\n\nEvydence is licensed under `AGPL-3.0-only`; see [LICENSE](LICENSE).\nCommercial license exceptions and paid support are described in\n[COMMERCIAL.md](COMMERCIAL.md). Project governance, contribution expectations,\nsecurity reporting, support paths, trademark guidance, release-evidence\nexpectations, and release notes are documented in [GOVERNANCE.md](GOVERNANCE.md),\n[CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md),\n[SUPPORT.md](SUPPORT.md), [TRADEMARKS.md](TRADEMARKS.md),\n[RELEASE_EVIDENCE.md](RELEASE_EVIDENCE.md), and [CHANGELOG.md](CHANGELOG.md).\n\nThese files preserve the same product boundary as the rest of the repository:\nEvydence supports compliance readiness and technical evidence organization, but\ndoes not make legal compliance conclusions, grant certification, prove SBOM\ncompleteness, treat scanner output as authoritative, or guarantee release\nsecurity.\n\n## Local API\n\n```sh\ncp .api.env.example .api.env\nset -a; . ./.api.env; set +a\nEVYDENCE_PRINT_BOOTSTRAP_SECRET=true go run ./cmd/evydence-api\n```\n\nThe API listens on `EVYDENCE_ADDR`, defaulting to `:8080`. Local bootstrap output includes a one-time admin API key secret. Leave `EVYDENCE_DATABASE_URL` unset for in-process local demos, or set it to use PostgreSQL-backed durable state.\n\nUse the secret as:\n\n```http\nAuthorization: Bearer \u003csecret\u003e\nIdempotency-Key: \u003cstable-create-key\u003e\n```\n\nFor a runnable first evidence flow, use [Getting started](docs/tutorials/getting-started.md).\n\n## Validation\n\nThe canonical release validation reference is [docs/reference/release-validation.md](docs/reference/release-validation.md).\nThe self-hosted production-readiness profile is [docs/reference/production-readiness.md](docs/reference/production-readiness.md).\nThe release-candidate checklist is [docs/reference/release-candidate.md](docs/reference/release-candidate.md).\nThe release evidence artifact map is [docs/reference/release-evidence-index.md](docs/reference/release-evidence-index.md).\nThe maintainer review policy for high-risk paths is [docs/reference/maintainer-review-policy.md](docs/reference/maintainer-review-policy.md).\nThe public roadmap and release cadence are [docs/reference/roadmap.md](docs/reference/roadmap.md).\n\nCommon local checks:\n\n```sh\nmake test\nmake openapi-check\nmake fast-check\n```\n\nPostgreSQL checks are opt-in so unit tests stay fast:\n\n```sh\nmake compose-up\nset -a; . ./.test.env; set +a\nmake live-postgres-check\nmake postgres-integration-test\n```\n\n`make finalize` runs the project-owned formatting, unit, OpenAPI, docs, deployment, and SDK gates. `make release-check` extends that with lint, gosec, govulncheck, race tests, and live PostgreSQL gates when `EVYDENCE_TEST_DATABASE_URL` is configured. `make coverage` is the no-database local coverage view; `make coverage-check` is the production coverage gate and requires `EVYDENCE_TEST_DATABASE_URL` so PostgreSQL-backed coverage is included.\n\n`make production-check` is stricter: it requires `EVYDENCE_TEST_DATABASE_URL`, enforces the configured coverage threshold, and runs a release artifact signing smoke test. Passing the gate is required release-candidate evidence, but it does not by itself close the remaining service decomposition, PKCS#11/native HSM custody, direct provider-specific management API/group synchronization, broader object-lock enforcement beyond configured bucket/sample-object checks, HA, and exit-review work. Production API and worker processes default to relational-only PostgreSQL loads and skip compatibility snapshot writes; the compatibility snapshot remains for migration, recovery, and local workflows. Critical runtime mutations for tenants, credential hashes, idempotency, audit-chain entries, release bundles, signatures, verification results, vulnerability decisions, and outbox jobs use focused PostgreSQL write paths when available. Release-ledger and evidence-core mutations for products, projects, releases, artifacts, evidence items, evidence lifecycle events, SBOMs, vulnerability scans, OpenAPI contracts, VEX documents, audit-chain entries, and parser outbox jobs also use focused PostgreSQL write paths when available. Remaining aggregate persistence calls use PostgreSQL relational synchronization without writing the compatibility snapshot when that store is configured. Current self-hosted production guidance still uses a single API writer replica; production API startup rejects unsupported writer modes and declared replica counts above one, then enforces that stance with a PostgreSQL advisory writer lease. Worker replicas may scale through PostgreSQL outbox row locking.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faatuh%2Fevydence","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faatuh%2Fevydence","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faatuh%2Fevydence/lists"}