{"id":49172363,"url":"https://github.com/allenfbyrd/evidentia","last_synced_at":"2026-05-15T23:05:38.963Z","repository":{"id":352450089,"uuid":"1212583206","full_name":"allenfbyrd/evidentia","owner":"allenfbyrd","description":"Previously: ControlBridge. Open-source Python GRC tool: gap analysis, AI risk statements, OSCAL-first compliance automation","archived":false,"fork":false,"pushed_at":"2026-04-22T17:56:06.000Z","size":2655,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-22T19:29:53.083Z","etag":null,"topics":["compliance","gap-analysis","grc","nist","oscal","pydantic","python","risk-management","soc2"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/allenfbyrd.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-16T14:21:00.000Z","updated_at":"2026-04-22T17:56:10.000Z","dependencies_parsed_at":null,"dependency_job_id":"9b8ddd56-2b40-4415-8f37-169afcfd1a03","html_url":"https://github.com/allenfbyrd/evidentia","commit_stats":null,"previous_names":["allenfbyrd/controlbridge","allenfbyrd/evidentia"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/allenfbyrd/evidentia","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allenfbyrd%2Fevidentia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allenfbyrd%2Fevidentia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allenfbyrd%2Fevidentia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allenfbyrd%2Fevidentia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/allenfbyrd","download_url":"https://codeload.github.com/allenfbyrd/evidentia/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allenfbyrd%2Fevidentia/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32152607,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T17:06:48.269Z","status":"ssl_error","status_checked_at":"2026-04-22T17:06:19.037Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["compliance","gap-analysis","grc","nist","oscal","pydantic","python","risk-management","soc2"],"created_at":"2026-04-22T20:00:27.771Z","updated_at":"2026-05-15T23:05:38.948Z","avatar_url":"https://github.com/allenfbyrd.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Evidentia\n\n\u003e **Bridge the gap between your controls and your frameworks.**\n\n**Evidentia** is an open-source, Python-first Governance, Risk, and Compliance\n(GRC) platform that turns compliance from a spreadsheet problem into a software\nproblem. It provides composable building blocks for control gap analysis,\nAI-generated risk statements, automated evidence collection, and compliance\nreporting — all usable from a Python library, a CLI, or a REST API.\n\n[![tests](https://github.com/allenfbyrd/evidentia/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/allenfbyrd/evidentia/actions/workflows/test.yml)\n[![codecov](https://codecov.io/gh/allenfbyrd/evidentia/branch/main/graph/badge.svg)](https://codecov.io/gh/allenfbyrd/evidentia)\n[![PyPI version](https://img.shields.io/pypi/v/evidentia.svg)](https://pypi.org/project/evidentia/)\n![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)\n![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-green.svg)\n[![Code of Conduct](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)\n[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/12724/badge?v=silver)](https://www.bestpractices.dev/projects/12724)\n\n---\n\n## Why Evidentia is different\n\nGRC tooling has been waiting for its **Terraform moment**. Vanta and Drata\nare the AWS Consoles of compliance — polished SaaS dashboards charging\n$30K–$80K/year per framework. Evidentia is the **library-first compliance\ninfrastructure layer underneath**: composable, embeddable, and built on the\nopen standards (OSCAL) that the entire federal compliance stack is moving\ntoward in 2026.\n\nIt's the only OSS tool today that combines **all** of the following in one package:\n\n- **OSCAL-native end-to-end** — ingests NIST OSCAL catalogs, emits OSCAL\n  Assessment Results. Ready for the **September 2026 federal mandate**\n  (OMB M-24-15 + FedRAMP RFC-0024). Vanta, Drata, AuditBoard, OneTrust,\n  ServiceNow IRM, MetricStream all ship **zero OSCAL output** today.\n- **Cryptographically signed evidence** — Sigstore/Rekor keyless signing\n  of every Assessment Results document, PEP 740 attestations on every\n  released wheel + sdist, and a CycloneDX SBOM attached to every GitHub\n  Release. **No other OSS GRC tool puts cryptographic provenance on the\n  evidence itself.**\n- **89 framework catalogs bundled** — NIST 800-53 Rev 5 (full 1,196\n  controls + Low/Moderate/High/Privacy baselines), CSF 2.0, FedRAMP,\n  CMMC 2.0, EU AI Act, DORA, NIS2, GDPR, all 15 comprehensive US state\n  privacy laws, the full FFIEC IT Examination Handbook stack (5\n  booklets: Information Security / Audit / Management / Operations\n  / Outsourcing), FFIEC Cybersecurity Assessment Tool, OCC Bulletin\n  2026-13a / FRB SR 26-02 (Model Risk Management), plus 20 Tier-C\n  licensed-stub frameworks with `evidentia catalog import` for your\n  licensed copies. More than any commercial vendor (Vanta: 35+,\n  Drata: 20+, RegScale: 60+).\n- **Apache 2.0 license** — embeddable in commercial products without\n  AGPL friction. The OSS GRC alternatives (CISO Assistant, Eramba,\n  Comp AI) are AGPL with paid commercial tiers.\n- **Library-first, CLI-second, API-third** — `pip install evidentia-core;\n  from evidentia_core import GapAnalyzer`. The closest peers\n  (`compliance-trestle`, RegScale OSCAL Hub) are workflow / CLI tools, not\n  embeddable libraries.\n- **Air-gap capable** — `--offline` flag refuses network egress; signs\n  evidence with GPG when Sigstore can't reach Fulcio. Built for FedRAMP\n  High, CMMC Level 2, and EU sovereign-cloud deployments where SaaS GRC\n  is a non-starter.\n- **AI-optional, not AI-mandatory** — risk-statement generation and\n  control explanation use LLMs via LiteLLM (any provider — OpenAI,\n  Anthropic, Google, Azure, Bedrock, Ollama, vLLM). Everything else is\n  deterministic. No leakage of sensitive evidence to third-party AI APIs\n  unless you explicitly opt in.\n- **CI-native via composite GitHub Action** — drop in\n  `uses: allenfbyrd/evidentia/.github/actions/gap-analysis@v0` and every\n  PR runs gap analysis, posts a sticky compliance comment, and blocks\n  merge on regression. No commercial GRC tool does this at the PR level.\n\nFor the full competitive analysis, market tailwinds, intellectual\nancestry, and 12-month direction, see\n[`docs/positioning-and-value.md`](docs/positioning-and-value.md) — a\n12,000-word synthesis from 7 parallel research streams.\n\n---\n\n## The problem\n\nModern GRC is stuck in 2005. The typical compliance program runs on:\n\n- **Spreadsheets** that get copy-pasted between auditors, engineers, and exec staff\n- **Vendor GRC suites** that cost $50K-500K per year, lock you in, and still require\n  weeks of manual work to map one framework to another\n- **Point solutions** that handle one piece (a vulnerability scanner, a policy\n  tracker, a questionnaire manager) but can't talk to each other\n- **Consultants** who re-learn your environment from scratch every audit cycle\n\nMeanwhile, the compliance workload keeps growing. A single fintech or healthcare\nSaaS company today might simultaneously be in scope for **SOC 2, PCI DSS 4.0,\nHIPAA, GDPR, CCPA, ISO 27001, and NYDFS Part 500** — seven frameworks with\nsubstantial overlap, each demanding its own evidence, gap analysis, and risk\ndocumentation.\n\nThe same control (say, \"MFA on all privileged accounts\") satisfies requirements\nin all seven. But because each framework uses different vocabulary, numbering,\nand organization, compliance teams end up documenting the same control seven\ndifferent ways — and audit season becomes a months-long exercise in cross-referencing.\n\n**This is a software problem.** It should be solved the way software problems\nget solved: with composable libraries, structured data, version control, and\nautomation.\n\n## Why Evidentia exists\n\nEvidentia is built on four principles:\n\n1. **Open standards, not vendor lock-in.** Inputs and outputs use\n   [OSCAL](https://pages.nist.gov/OSCAL/) — NIST's open standard for control\n   catalogs and assessment results. If you outgrow Evidentia, your data\n   travels with you.\n\n2. **Library-first, CLI-second, API-third.** The Python library is the\n   canonical interface. The CLI is a thin wrapper. The REST API is a thin\n   wrapper. Everything Evidentia can do via the CLI, it can do from a\n   Python script — which means you can embed it in CI pipelines, compliance\n   portals, or custom integrations.\n\n3. **AI where it helps, not where it hurts.** Evidentia uses LLMs for\n   tasks where language understanding is the bottleneck (writing NIST SP 800-30\n   risk statements from a gap, validating whether a policy PDF actually\n   covers a control). It uses deterministic code for tasks where correctness\n   matters (OSCAL parsing, gap arithmetic, cross-framework mapping).\n\n4. **Provider-agnostic LLM access.** All AI features route through\n   [LiteLLM](https://docs.litellm.ai/) + [Instructor](https://python.useinstructor.com/),\n   giving you structured Pydantic output from any model — OpenAI, Anthropic,\n   Google, Azure, Ollama, vLLM, or any OpenAI-compatible endpoint. No vendor\n   lock-in on the AI layer either.\n\n## Who it's for\n\n- **Security engineers** at startups and mid-size companies who need to\n  hit SOC 2 Type II without hiring a full compliance team\n- **GRC consultants** who want to stop rebuilding the same spreadsheets\n  for every engagement\n- **Platform teams** who want to embed gap analysis into their CI pipelines\n  and catch drift before the auditor does\n- **CISO offices** that want a real audit trail on risk decisions, backed\n  by versioned structured data instead of Slack threads\n- **Anyone** who has ever said \"I know this NIST control is the same as\n  this SOC 2 criterion, but I don't want to re-document it for the fifth time\"\n\n---\n\n## Current status: 89 frameworks bundled, full suite passing\n\n### Recent releases\n\n**v0.9.0 (May 2026)** — *Federal compliance — POA\u0026M lifecycle +\nCONMON cycle calendar + walk-through-as-validation*. First minor\nof the v0.9.x line. Opens the federal-compliance theme reserved\nat v0.8.7 cycle-close. Lands operator-facing surfaces auditors\nexpect in any regulated-industry GRC tool: Plan-of-Action-and-\nMilestones tracking + Continuous Monitoring cycle calendar.\n**Phase 1** — POA\u0026M data layer: `POAMState` 5-state enum\n(planned / in_progress / overdue / completed / verified)\naligned to FedRAMP POA\u0026M Template Completion Guide v3.0 + NIST\nSP 800-53A Rev 5 Appendix F; forward-only state transitions;\n`Milestone` Pydantic record; `ControlGap.poam_milestones`\noptional list (default-empty for v0.7.x + v0.8.x backward-compat);\nnew `evidentia_core.poam` sub-package (state.py + milestone.py);\nnew `evidentia_core.poam_store` JSON file-store mirroring\nv0.7.9 vendor_store; 6 new EventActions.\n**Phase 2** — `evidentia poam` CLI (7 verbs: create from gap\nreport / list / show / update / milestone add|update / delete /\ncalendar); `/api/poam/*` FastAPI router (8 endpoints);\n`evidentia_core.oscal.poam_exporter.gap_report_to_oscal_poam()`\nemitting OSCAL 1.1.2 plan-of-action-and-milestones JSON with\nSHA-256 back-matter integrity (mirrors v0.7.0 finding-resource\nembedding). Default severity-filter is CRITICAL + HIGH per FedRAMP\n§3.1 auditor-default; `--all` opts into the full set.\n**Phase 3** — `evidentia_core.conmon` pure-function library\nwith 7 bundled cadences (NIST 800-53 CA-7 monthly + FedRAMP\nConMon × 3 + CMMC L2 triennial + DoD RMF annual + OCC 2026-13a\nmodel-risk annual); `evidentia conmon` CLI (list / next /\ncheck); 2 new EventActions. No daemon — operators poll.\n**Plus** new operator runbooks (`docs/poam-runbook.md` +\n`docs/conmon-runbook.md`); 14-item Step 5.A refinement batch\n(UUID canonicalization in poam_store + vendor_store via\n`str(UUID(id))` preventing duplicate-records-per-alias +\nnon-conformant OSCAL UUID emit; `_enum_value` extracted to\n`evidentia_core.models.common`; stale-doc refreshes across\ngovernance + config + generation_context references).\n**15th consecutive PROCEED-CLEAN** of v0.7.x → v0.8.x → v0.9.x\nline. **2583 tests passing / 17 skipped across 227 source files;\nmypy strict 0/0; ruff clean.** Phase 4 walk-through deferred to\nv0.9.1 per §31.A POA\u0026M-first / walk-through-as-validation\nposture.\n\n**v0.8.7 (May 2026)** — *Final v0.8.x wrap-up*. Single focused\nsession closing the v0.8.6 P3 CLI deferral + backfilling\nv0.8.6 cycle-close artifacts deferred during single-session\ncompression. **NEW** `--faithfulness-threshold-mode\n{framework-aware,fixed}` flag on `evidentia eval risk-\ndeterminism` (default `framework-aware`) closes the v0.8.6\nP3 deferral; `--faithfulness-threshold` default changed from\n`0.3` → `None` sentinel for backward-compatible framework-\naware default resolution. Resolution precedence: explicit\nvalue wins → framework-aware mode (extracts framework from\nprompt_id; looks up via `resolve_threshold(framework, method)`)\n→ fixed mode (0.30 framework-agnostic). 6 v0.8.6 cycle-close\nartifacts backfilled (`docs/security-review-v0.8.6.md` +\n`docs/v0.8.6-plan.md` + threat-model v0.8.6 delta +\ncapability-matrix v0.8.6 snapshot + README v0.8.6 entry +\nROADMAP v0.8.6 PLANNED → SHIPPED transition). 14th\nconsecutive PROCEED-CLEAN of v0.7.x → v0.8.x line. **2386\ntests passing across 217 source files; mypy strict 0/0; ruff\nclean.** **FINAL v0.8.x patch** — v0.9.0 opens with the\nfederal-compliance theme per the 2026-04-28 §10 Q4 lock-in.\n\n**v0.8.6 (May 2026)** — *CIMD scope enforcement at MCP-\nprotocol level + Cohen's Kappa rater agreement + per-claim\nconfidence + framework-aware threshold defaults + v0.7.x\nretrospective + v1.0 transition narrative DRAFT*. Aggressive\n~2-3 week comprehensive scope (single-session compression\nmatching v0.8.3 + v0.8.4 + v0.8.5 cadence). Closes ALL 3\nv0.8.5 carry-overs + 3 cycle-additions. **MCP CIMD scope\nenforcement at MCP-protocol level**: NEW `evidentia_mcp.scope`\nmodule monkey-binds `FastMCP.call_tool` (mcp Python SDK 1.27\nhas no public middleware hook); `--default-client-id \u003cslug\u003e`\nCLI flag; pass-through preserves v0.8.5 default no-gating\nbehavior; per-call `AI_MCP_TOOL_AUTHORIZED` /\n`AI_MCP_TOOL_DENIED` audit events; deny paths raise\n`McpError` code -32602. **Cohen's Kappa rater agreement\nscript** (`scripts/compute_inter_rater_kappa.py`): two-rater\nfile mode + rule-based-rater mode; CI-gateable exit codes;\nempirical κ = 0.4848 (moderate) at jaccard threshold 0.85\nships as \"single-rater + κ probe inconclusive\" per the\ndocumented R3 mitigation. **Per-claim bootstrap-resampled\nconfidence**: `FaithfulnessResult.confidence` field\n(default-off cost-aware ~100ms/claim; opt-in via\n`compute_confidence=True`); **framework-aware threshold\ndefaults**: `DEFAULT_THRESHOLDS_BY_FRAMEWORK_JACCARD` map\n(NIST 0.60 / FFIEC 0.35 / ISO27001 0.30) +\n`resolve_threshold(framework, method)` helper +\n`FaithfulnessResult.framework` field. **`docs/v0.7.x-\nretrospective.md`** publishes the 18-release v0.7.x cycle\nnarrative; **`docs/v1.0-transition.md` DRAFT** captures v1.0\ntheme candidates + acceptance gates + open questions for\nv0.9.0 cycle-open. Thirteenth consecutive PROCEED-CLEAN of\nthe v0.7.x → v0.8.x line. **2383 tests passing across 217\nsource files; mypy strict 0/0; ruff clean.** v0.8.7 wrap-up\nrelease closes the v0.8.6 P3 CLI deferral.\n\n**v0.8.5 (May 2026)** — *DFAH CLI flags + corpus expansion +\nreal-LLM integration tests + MCP CIMD richness*. Aggressive\n~2-3 week comprehensive scope (single-session compression\nmatching v0.8.3 + v0.8.4 cadence). Closes ALL 4 v0.8.4\ncarry-overs in one focused session per Allen's explicit\n\"implement CIMD now\" directive — ending the 5-cycle CIMD\ndeferral pattern. **DFAH faithfulness CLI flags**:\n`evidentia eval risk-determinism --check-faithfulness\n--faithfulness-threshold N --faithfulness-method\n{jaccard,semantic} --source-clauses-file \u003cyaml\u003e`. Closes the\nv0.8.4 P1.2 CLI-surface deferral; pre-condition validation\nrejects malformed inputs BEFORE any LLM call fires. **DFAH\ncorpus expansion** to 123 entries with per-framework subsets\n(NIST 24 / FFIEC 24 / ISO 27001 24). `tune_faithfulness_threshold.py\n--corpus-pattern \u003cglob\u003e` for per-framework sweep; empirical\nper-framework recommended thresholds documented. **Real-LLM\nintegration tests** at `tests/integration/test_eval/` opt-in\nvia `EVIDENTIA_LLM_INTEGRATION=1`. **MCP CIMD richness**:\nnew `evidentia_mcp.cimd` module ships `CIMDDocument` (per\nRFC 7591 + MCP conventions) + `CIMDRegistry` (JSON-file-\nbacked, version-tagged). `evidentia mcp serve --cimd-registry\n\u003cpath\u003e` flag wires it through stdio + SSE + HTTP transports.\nTwelfth consecutive PROCEED-CLEAN of v0.7.x → v0.8.x line.\n**2338 tests passing across 216 source files; mypy strict\n0/0; ruff clean.** v0.8.6 reservations: per-tool scope\nenforcement at MCP-protocol level + multi-rater corpus pass\n+ per-claim confidence scoring.\n\n**v0.8.4 (May 2026)** — *G4 Path 2 + DFAHarness wiring*.\nAggressive ~2-3 week focused scope (single-session compression\nmatching v0.8.3 cadence). Closes the v0.8.3 ship-failure root\ncause via **G4 Path 2** (post-PyPI regeneration in\n`release.yml` — sidesteps cross-platform reproducibility\nentirely). New regeneration step BETWEEN Wait-for-PyPI + docker\nbuild runs `pip-compile --generate-hashes --no-emit-find-links`\nagainst PyPI's just-published wheels → ephemeral\n`docker/requirements.txt` overwrite → docker build picks it\nup. Hashes match because pip-compile downloads from PyPI's\nbytes in the Linux CI runner — same source as the container\nbuild's pip install. Built-in 3-attempt retry loop with 30s\nsleeps absorbs PyPI propagation lag. **DFAHarness\n`check_faithfulness=True` wiring** closes the v0.8.3 P1.2\ndeferral: `EvalSample.source_clauses` field +\n`EvalResult.faithfulness_results` list +\n`DFAHarness.run(check_faithfulness=, faithfulness_threshold=,\nfaithfulness_method=, claim_extraction_fn=,\nfaithfulness_score_fn=)` kwargs.\n`EventAction.AI_EVAL_FAITHFULNESS_CHECKED` +\n`AI_EVAL_FAITHFULNESS_VIOLATION` (reserved-but-inactive in\nv0.8.0) ACTIVATED. Mock-callable injection points keep harness\ntests cost-zero while exercising real production code paths.\n14 new unit tests across 5 test classes. Eleventh consecutive\nPROCEED-CLEAN of the v0.7.x → v0.8.x line. **2313 tests passing\nacross 220+ source files; mypy strict 0/0; ruff clean.** MCP\nCIMD richness deferred to v0.8.5 (5th cycle-deferral; v0.8.5\nre-evaluates with potential formal retirement) + CLI flags +\ncalibration corpus expansion + real-LLM integration tests\ndeferred to v0.8.5.\n\n**v0.8.3 + v0.8.3.1 hot-fix (May 2026)** — *Supply-chain G4\nattempt + AI-quality completion*. Aggressive ~3-week cycle\nexecuted in a single focused session. Closes 5 of 8 v0.8.2\ncarry-overs (G4 attempt failed first-fire + reverted in\nsame-day hot-fix). **G4 Path 1 ATTEMPTED**: Dockerfile flipped\nfrom exact-version pinning to\n`pip install --require-hashes -r /tmp/requirements.txt` against\nhash-pinned `docker/requirements.txt`; `release.yml` exported\n`SOURCE_DATE_EPOCH` for SOURCE_DATE_EPOCH-driven `uv build`\nreproducibility. **First-fire revealed `uv build` is NOT\nbyte-identical between Windows local + Linux CI runner** even\nwith same SOURCE_DATE_EPOCH (file-ordering / timestamp-precision\ndrift). PyPI publish succeeded but container build's\n`pip install --require-hashes` failed: local-computed hashes ≠\nLinux-CI-built wheel hashes. **v0.8.3.1 hot-fix REVERTED** the\nDockerfile to exact-version pinning (same v0.8.2 surface; no\nregression); container ship recovered same-day. Recurring\nScorecard PinnedDependencies false-positive cycle continued\n(alerts dismissed per the runbook). G4 closure deferred to\nv0.8.4 with Path 2 (post-PyPI regeneration; sidesteps cross-\nplatform reproducibility entirely). **F-V82-S1**:\n`bump_version.py --regenerate-requirements` auto-detects host\nplatform; on non-Linux hosts auto-invokes pip-compile inside\nLinux base image. **F-V82-S2**: `evidentia eval verify` CLI\nreplaces broad `except Exception` with specific `SigstoreError`\nsubclass catches mapped to distinct exit codes. **DFAH\nsentence-transformers path (P1.1)**: opt-in\n`[eval-faithfulness]` extra; default model `all-MiniLM-L6-v2`\n(~90 MB); catches paraphrases that the v0.8.2 Jaccard baseline\nmisses. **LLM atomic-claim extraction (P1.2)**: new\n`extract_claims()` function decomposes AI-generated artifacts\ninto atomic verifiable claims for faithfulness scoring.\n**Calibration corpus (P1.3)**: 50-entry corpus + threshold-\ntuning script empirically guide operators on per-corpus\nthreshold selection. Tenth consecutive PROCEED-CLEAN of the\nv0.7.x → v0.8.x line. **2299 tests passing across 220+ source\nfiles; mypy strict 0/0; ruff clean.** MCP CIMD richness\ndeferred to v0.8.4 (4th cycle-deferral; gated on empirical\noperator demand) + DFAHarness `check_faithfulness=True` wiring\ndeferred to v0.8.4 polish.\n\n**v0.8.2 (May 2026)** — *Review-deferral closure + supply-chain\nhardening + test-quality + DFAH faithfulness*. Aggressive ~3-week\ncycle executed in a single focused session. Closes 8 reservations\ncarried out of v0.8.1. **F-V81-S1**: `evidentia mcp serve\n--allow-root \u003cpath\u003e` gates file-path tool inputs via\n`validate_within`. **F-V81-S2**: AuthProvider construction moved\nfrom import-time module-level → FastAPI `lifespan` event;\nimports are side-effect-free. **G4 Dockerfile foundation**:\n`docker/requirements.txt` regenerated against the v0.8.2 dep\ntree with SHA256 hashes per transitive (activation deferred to\nv0.8.3 per §25.6 R1 build-determinism). **G1 mutmut + G2\nhypothesis**: mutation-testing baseline + 8 property-based\ntests on normalizer + crosswalk. **DFAH faithfulness scoring**:\nsecond arXiv 2601.15322 metric via stdlib Jaccard token-overlap\n(threshold 0.3 default). **First-class Sigstore signing for\n`evidentia eval`**: `--sign / --no-sign` flag + `evidentia\neval verify` subcommand. Ninth consecutive PROCEED-CLEAN of\nthe v0.7.x → v0.8.x line. **2277 tests passing across ~215\nsource files; mypy strict 0/0; ruff clean.** CIMD richness +\nsentence-transformers faithfulness + DFAH calibration corpus\ndeferred to v0.8.3.\n\n**v0.8.1 (May 2026)** — *Review-deferral close-out + LLM richness\n+ network surfaces*. Aggressive ~4-week cycle compressed to a\nsingle focused session. Closes ALL 12 v0.8.0-bucketed review\nfindings (2 HIGH + 4 MEDIUM + 6 LOW polish + 2 INFO). Ships the\nLLM-driven richness for the v0.8.0 P0 surfaces:\n``evidentia eval risk-determinism --context X --gaps Y`` runs\nthe DFAHarness against the live RiskStatementGenerator;\nPRT LLM-driven per-claim decomposition replaces the v0.8.0\nstub (``trace_kind=v0.8.1-llm`` vs ``=v0.8.0-stub`` audit-log\ndiscriminator). Network surfaces: ``evidentia mcp serve\n--transport sse|http`` + FastAPI AuthProvider middleware\n(``evidentia serve --auth-token-file \u003cpath\u003e``). Closes the\nv0.8.0 F-V08-S3 ``/api/metrics`` auth gate. Eighth consecutive\nPROCEED-CLEAN of the v0.7.x → v0.8.x line. Three Phase 4 infra\nprimitives (G4 Dockerfile ``--require-hashes``, G1 mutmut, G2\nhypothesis) deferred to v0.8.2 per §24.6 R6. **2240 tests\npassing across 211 source files; mypy strict 0/0; ruff clean.**\n\n**v0.8.0 (May 2026)** — *The OSS-native AI moat*. First minor\nafter the v0.7.x cycle close. Lands four AI-quality features\nthat distinguish a Vanta-class dashboard from a compliance-\nengineering tool: **DFAH determinism harness** (`evidentia eval\nstub-smoke` — auditor-defensible numerical proof that AI\nartifact generation is reproducible per arXiv 2601.15322),\n**Policy Reasoning Traces** (`evidentia risk generate\n--emit-trace` — decomposes risk statements into ordered claims\nwith policy clause citations per arXiv 2509.23291), **MCP\nserver** (`evidentia mcp serve` — exposes Evidentia to MCP-\naware AI clients over stdio with 4 read-only tools), and\n**plugin contract scaffolding** (`evidentia_core.plugins` —\n4 ABCs + 3 reference implementations + entry-point discovery\nfor community catalog providers + SI-partner extensions).\nM-4 collector base-class refactor consolidates ~60% of the\nHTTP scaffolding across the 4 vendor-risk collectors. New\n`/api/metrics` Prometheus endpoint + `docs/evidence-integrity.md`\noperator deployment guidance. Pre-release-review v4 Pre-tag\nPROCEED-CLEAN with 5 inline-fixes from the parallel security\n+ code-quality reviews; 12 findings bucketed to v0.8.1 with\ndocumented rationale. **2227 tests passing across 210 source\nfiles; mypy strict 0/0; ruff clean.**\n\n**v0.7.16 (May 2026)** — *Final v0.7.x cycle release.*\nCloses the v0.7.x cycle (18 patches + 2 hot-fixes over ~12\ndays; 6 consecutive PROCEED-CLEAN). python-dotenv CVE bump\n+ commit-msg hook variant of standing-rule sweep + post-\nship release.yml hardening validation. v0.8.0 design phase\nopens immediately post-ship.\n\n**v0.7.15 (May 2026)** — *Tailwind 4 + SettingsPage refactor +\nstanding-rule pre-commit hook*. Final v0.7.x cycle release before\nv0.8.0 design opens. Tailwind 3→4 migration (full shadcn/ui\npreset rewrite to CSS-first `@theme {}`; PostCSS chain replaced\nwith `@tailwindcss/vite` plugin; `tailwindcss-animate` v3-era →\n`tw-animate-css` v4-compatible). SettingsPage.tsx refactored to\nkey-based remount of `\u003cSettingsForm/\u003e` sub-component; lint rule\n`react-hooks/set-state-in-effect` promoted from `warn` to\n`error`. New `scripts/standing_rule_sweep.sh` + pre-commit hook\nruns the canonical 21-pattern guard at commit-time. Fifth\nconsecutive PROCEED-CLEAN /security-review. Post-ship hardening\n(commit `fd36e78`) extends `release.yml` publish-container Wait\nstep to all 6 packages — closes the LAST PyPI propagation race\nsurface. 2120 tests passing across 188 source files.\n\n**v0.7.14 (May 2026)** — *frontend modernization + Codecov\nP2.1 RESOLVED + final v0.7.x hygiene + v0.8.0 G4 foundation*.\n7 of 8 PR #21 frontend major bumps (TypeScript 5→6, ESLint\n9→10 flat-config, plugin-react-hooks 5→7, jsdom + minors;\ntailwind 3→4 deferred to v0.7.15). 3 deferred v0.7.8 LOWs\nclosed (Tableau Windows tempfile via TemporaryDirectory,\nDatabricks LTS env-var, test-coverage gaps). Codecov dashboard\nfixed (was 0% since v0.7.10; now 82.14% via removing the\n`flag_management.individual_flags[].paths` glob that filtered\nall files out). container-build Wait extended to all 6 packages.\nHash-pinned `docker/requirements.txt` preview lands as v0.8.0\nG4 reproducible-build foundation. Fourth consecutive PROCEED-\nCLEAN /security-review. 2120 tests passing across 188 source\nfiles.\n\n**v0.7.13 (May 2026)** — *dependency modernization + Codecov fix\n+ P3 carry-over closures + release-notes hygiene*. Wrap-up of\nthe v0.7.x cycle. No new public surfaces. Codecov coverage\nupload fixed (switched to `source_pkgs` so Cobertura XML emits\nfull repo-relative paths). `release.yml` now auto-populates the\nGitHub Release body from `CHANGELOG.md` via a new\n`extract_changelog_block.py` step + `body_path` arg — closes\nthe v0.7.5–v0.7.12 stub-body gap structurally; future releases\nauto-populate. P3 carry-overs closed: M-9 OSCAL UUID\nconformance + L-2 Vanta/Drata high-risk extended fields +\nL-4 SIG BYO sparse-row debug logging + 5 of 9 v0.7.8 LOWs.\nThird consecutive PROCEED-CLEAN /security-review. Plus 10\nhistorical release-body backfills landed retroactively. 2100\ntests passing across 188 source files.\n\n**v0.7.12 (May 2026)** — *concrete cloud-WORM backends + FAIR\nMonte Carlo + GDPR purge-flow + alert-zero*. Adds the three cloud\nbackends to the `WORMBackend` ABC introduced in v0.7.11:\n`S3ObjectLockWORM`, `AzureImmutableBlobWORM`, `GCSBucketLockWORM`\n(installed via `evidentia[worm-s3]` / `[worm-azure]` /\n`[worm-gcs]` extras). Adds FAIR Monte Carlo simulation\n(`risk quantify --method fair-mc`) using stdlib-only Beta-PERT\nsampling. Adds GDPR Article 17 purge-flow (`purge_immediately` +\n`force_gdpr_purge` operator override). Plus 3 cloud-WORM operator\nrunbooks, alert-zero closure (CodeQL custom sanitizer pack\nregisters `validate_within` as a path-injection sanitizer),\n`bump_version.py` inter-package pin tightening, and\nrelease-checklist Steps 5.5 + 9.5 doc-consistency + release-notes\npractices. Second consecutive PROCEED-CLEAN /security-review.\n2075 tests passing across 188 source files.\n\n**v0.7.11 (May 2026)** — *audit chain-of-custody + governance trio\n+ Open FAIR + 6-store harmony*. Adds the `evidentia retention`\nCLI (set / list / show / extend / transition / delete / report)\nwith 10-regime classification (SEC 17a-4 / FINRA 3110 / IRS / SOX\n/ HIPAA / GLBA / PCI / SR 11-7 / GDPR / generic) and a\n`WORMBackend` ABC with a `LocalFilesystemWORM` reference impl.\nAdds KRI/KPI/KGI metrics overlay (P1.5 G3), Open FAIR risk\nquantification (P1.5 G4 deterministic PERT-mean), and\nprocess-as-code governance workflows (P1.5 G5). Closes 9 of 17\nv0.7.10 P3 deferrals including F-V10-S2 (`$EDITOR` allowlist).\n**First v0.7.x PROCEED-CLEAN** /security-review (0 findings).\n1929 tests passing across 184 source files.\n\n**v0.7.9 + v0.7.10 (May 2026)** — *industry overlay (financial\nservices TPRM + model risk + governance primitives) + federal-\ncompliance carry-overs*. v0.7.9 ships `evidentia tprm` (vendor\ninventory + DD-questionnaire generator with 5 output formats\nincluding SIG BYO + caiq-full + concentration-report) + 4\nvendor-risk SaaS collectors (Vanta / Drata / BitSight /\nSecurityScorecard) + OSCAL TPRM emit. v0.7.10 adds the model-\nrisk overlay (SR 11-7 / OCC 2011-12 model inventory + validation\nreport templates) + 7 new bundled catalogs (5 FFIEC IT Handbook\nbooklets + OCC 2011-12 / FRB SR 11-7 + FFIEC CAT). Bundled\ncatalog count: 82 → 89.\n\n**v0.7.8 (May 2026)** — *cloud data-warehouse collectors + BI\nintegrations*. Adds two read-only evidence collectors for cloud\ndata warehouses (Databricks workspace API + Snowflake\n`account_usage` views; mapped to NIST 800-53 controls AC-2 / AC-3\n/ AC-6 / AC-7 / AU-2 / AU-3 / IA-2 / IA-5 / SC-7 / SC-12 / SI-2)\nplus the first **output integrations to enterprise BI platforms**\n(Tableau Server / Cloud + Power BI). Three published datasets per\nBI platform: gap inventory, NIST SP 800-30 risk register with AI-\nprovenance fields, and CollectionContext audit trail. Ships\nwalkthrough docs (`docs/cloud-dw-collectors.md`,\n`docs/bi-integrations.md`) and an end-to-end Meridian-with-BI\ndemo.\n\n**v0.7.7 (May 2026)** — *SQL family evidence collectors*. Five\nread-only relational-DB adapters (`[sql-postgres]`, `[sql-mysql]`,\n`[sql-sqlite]`, `[sql-mssql]`, `[sql-oracle]`) mapping DB-resident\ncompliance evidence to NIST 800-53 controls. Plus ServiceNow\noutput integration carry-forward.\n\nSee [`CHANGELOG.md`](CHANGELOG.md) for the full version history\n(v0.1.0 through v0.7.15). For forward direction, see\n[`docs/v0.8.0-plan.md`](docs/v0.8.0-plan.md) (the OSS-native AI\nmoat — DFAH + PRT + MCP + plugin contracts) and\n[`docs/ROADMAP.md`](docs/ROADMAP.md) (everything else).\n\n### What works today\n\n- **Gap analysis against 89 bundled frameworks** across four redistribution\n  tiers:\n\n  - **Tier A — US federal (25 frameworks, verbatim public domain):**\n    NIST 800-53 Moderate sample, 800-171 Rev 2/Rev 3, 800-172, CSF 2.0,\n    AI RMF 1.0, Privacy Framework 1.0, SSDF 800-218; FedRAMP Rev 5\n    Low/Moderate/High/LI-SaaS baselines; CMMC 2.0 Levels 1/2/3; HIPAA\n    Security/Privacy/Breach Notification Rules; GLBA Safeguards, NY DFS\n    500, NERC CIP v7, FDA 21 CFR Part 11, IRS 1075, CMS ARS, FBI CJIS v6,\n    CISA Cross-Sector CPGs.\n\n  - **Tier A — International (6 frameworks):** UK NCSC CAF 3.2, UK Cyber\n    Essentials, Australian Essential Eight, Australian ISM, Canada\n    ITSG-33, New Zealand NZISM.\n\n  - **Tier D — Statutory obligations (21 frameworks, government edicts,\n    uncopyrightable):** EU GDPR, EU AI Act, EU NIS2, EU DORA, UK DPA 2018,\n    Canada PIPEDA, plus all 15 comprehensive US state privacy laws (CA\n    CCPA/CPRA, VA, CO, CT, UT, TX, OR, DE, MT, IA, FL, TN, NH, MD, MN).\n\n  - **Tier C — Licensed stubs (20 frameworks):** ISO/IEC 27001:2022,\n    27002:2022, 27017, 27018, 27701, 42001 (AI), 22301 (BC); PCI DSS\n    v4.0.1; HITRUST CSF v11; COBIT 2019; SWIFT CSCF 2024; CIS Controls\n    v8.1 plus 5 CIS Benchmarks (AWS, Azure, GCP, Kubernetes, RHEL 9);\n    Secure Controls Framework 2024; IEC 62443; SOC 2 TSC. Copyrighted\n    authoritative text isn't bundled — ships with public clause numbering\n    plus a `evidentia catalog import` hook for your licensed copy.\n\n  - **Tier B — Threat and vulnerability catalogs (4 frameworks):** MITRE\n    ATT\u0026CK Enterprise (41 techniques), MITRE CWE Top 25 (2024), MITRE\n    CAPEC sample, CISA KEV sample (Log4Shell, MOVEit, EternalBlue, etc).\n\n- **Six bundled crosswalks:** NIST CSF 2.0 → 800-53, FedRAMP Moderate →\n  CMMC L2, NIST 800-53 → HIPAA Security, ISO 27001 → NIST 800-53, VCDPA →\n  CCPA/CPRA, NIST 800-53 → SOC 2 TSC.\n\n- **Multi-format inventory parsing.** Load your controls from YAML, CSV, JSON\n  (including OSCAL component-definition), or any format with fuzzy-matched\n  column headers. Status normalization handles \"implemented\", \"partial\",\n  \"planned\", \"in progress\", \"missing\", etc.\n\n- **Cross-framework crosswalk engine.** Bidirectional mapping index: ask\n  \"what NIST 800-53 controls satisfy my SOC 2 criterion?\" or \"what CMMC\n  Level 2 controls match my FedRAMP Moderate posture?\". v0.2.0 ships six\n  bundled crosswalks (118 mappings total). Custom crosswalks are\n  drop-in JSON files in `catalogs/data/mappings/`.\n\n- **Prioritized gap reports.** Severity by implementation state, effort-weighted\n  priority scores, efficiency opportunities (controls that close gaps in 2+\n  frameworks simultaneously), and a prioritized remediation roadmap.\n\n- **Four output formats:** JSON (canonical), CSV (flat), Markdown (human\n  review), and OSCAL Assessment Results (for audit handoff and tool interop).\n\n- **AI risk statement generator.** NIST SP 800-30 Rev 1 compliant risk\n  statements from gaps + system context. Uses Instructor to enforce the\n  `RiskStatement` Pydantic schema on LLM output, with automatic retries on\n  validation failure. Works with any LiteLLM-supported model.\n\n- **Typer + Rich CLI** with `init`, `catalog list/show/crosswalk/import/\n  where/license-info/remove`, `gap analyze`, `gap diff`, `risk generate`,\n  `explain control`, `collect aws`, `collect github`, `integrations jira`,\n  `oscal verify` (v0.7.0 — verifies SHA-256 digests + GPG `.asc` and/or\n  Sigstore `.sigstore.json` signatures), `serve` (web UI), `doctor`,\n  and `version` commands. `catalog list` supports `--tier` and `--category`\n  filters; `catalog import` accepts direct JSON or an OSCAL profile (via\n  `--profile \u003cprofile.json\u003e --catalog \u003csource.json\u003e`). Global flags:\n  `--offline` (air-gap mode), `--json-logs` (ECS 8.11 structured output\n  for SIEM ingestion), `--config \u003cpath\u003e`, `--verbose`, `--quiet`.\n\n- **965 tests passing + 8 environmental skips** (Windows-local; full\n  suite of 973 passes on Linux CI per the v0.7.0 baseline) covering models, catalog loading (with a\n  parametric smoke test per bundled framework), recursive enhancement\n  flattener for NIST Rev 5 3-level IDs, tier invariants, OSCAL profile\n  resolution, user-import directory precedence, crosswalk bidirectionality,\n  multi-format inventory parsing, severity calculation, all four report\n  exporters, Jira integration push/sync, AWS Config + Security Hub +\n  IAM Access Analyzer + GitHub branch protection + CODEOWNERS +\n  Dependabot evidence collection, FastAPI `/api/*` endpoints, air-gap\n  mode, OSCAL AR digest + GPG + Sigstore round-trip verification, and\n  3 trestle conformance tests against the NIST OSCAL reference impl.\n\n### What's not yet included (as of v0.7.2)\n\nSetting expectations matters. v0.7.0 shipped a substantial enterprise\nhardening pass, v0.7.1 closed the AI features carry-over (typed\n`EvidentiaAIError` hierarchy, `GenerationContext` metadata, bounded\nretry, ECS structured logging across `risk_statements/` + `explain/`),\nand v0.7.2 added supply-chain visibility via OpenSSF Scorecard +\ncontributor-experience IDE config + a catalog-drift detector fix.\nSee [`CHANGELOG.md`](CHANGELOG.md) for the full v0.7.0 + v0.7.1 +\nv0.7.2 deltas. The following are still on the roadmap but not yet\nshipped:\n\n- **Composite action hardening** (v0.7.3) — SHA-pin third-party\n  actions in `.github/actions/gap-analysis/action.yml`, composite\n  action E2E smoke test, SLSA L3 build provenance via\n  `actions/attest-build-provenance@v2`. See\n  [`docs/v0.7.3-plan.md`](docs/v0.7.3-plan.md) for the full plan;\n  2-4 week ship target.\n- **LLM-based evidence validation** (Phase 3 / v0.8+) — \"is this\n  screenshot actually proof of MFA?\" scoring, freshness detection,\n  multi-modal validation via Document Screenshot Embedding (DSE).\n  Currently academic-only; tracked in\n  [`docs/positioning-and-value.md`](docs/positioning-and-value.md) §13.\n- **Additional collectors / integrations** — Okta (MFA, inactive users,\n  privileged-account counts), ServiceNow (`sn_compliance_task` push),\n  Vanta + Drata (push test results via their public APIs), Azure + GCP\n  evidence collectors. Carried forward to v0.7.3 as\n  optional/community-driven items per\n  [`docs/v0.7.3-plan.md`](docs/v0.7.3-plan.md) §\"P2 — Optional /\n  community-driven\".\n- **Multi-user auth / RBAC** — the web UI is localhost-only today;\n  network-deployment token auth is queued for v0.7.x+.\n- **Authoritative control text for copyrighted frameworks** (ISO\n  27001/27002, SOC 2 TSC, PCI DSS, HITRUST CSF, etc.) — ship as\n  **Tier-C stubs** with public clause numbering only. Use\n  `evidentia catalog import` to load your own licensed copy.\n\n---\n\n## Quick start\n\n### Prerequisites\n\n- Python 3.12+\n- [uv](https://docs.astral.sh/uv/) 0.4+ (recommended) or pip\n\n### Install from PyPI\n\n```bash\npip install evidentia\n```\n\nThis installs the `evidentia` and `cb` CLI commands, plus the five workspace\nsub-packages as transitive dependencies (`evidentia-core`, `evidentia-ai`,\n`evidentia-collectors`, `evidentia-integrations`, `evidentia-api`).\n\n### Install from source (for contributors)\n\n```bash\ngit clone https://github.com/allenfbyrd/evidentia.git\ncd evidentia\nuv sync --all-packages\n```\n\nThis downloads Python 3.12 (if needed), creates a `.venv`, and installs all\nfive workspace packages in editable mode.\n\n### Run the smoke test\n\n```bash\nuv run pytest tests/ -q\n# Expected: full suite passes in ~10s on a warm checkout\n```\n\n\u003e Hit a snag? See [`docs/troubleshooting.md`](docs/troubleshooting.md)\n\u003e for common first-run issues — wrong Python version, missing SPA\n\u003e bundle, Sigstore TUF metadata fetch failures, Docker bind-mount\n\u003e permissions.\n\u003e\n\u003e Want the absolute shortest path? See [`docs/quickstart.md`](docs/quickstart.md)\n\u003e — five commands from `pip install` to a verified OSCAL Assessment\n\u003e Results document.\n\n### Web UI flows (v0.7.6 alpha.2)\n\n`evidentia serve` brings up a FastAPI + React SPA on\n`http://127.0.0.1:8000`. Five interactive surfaces ship today,\nmirroring the CLI 1:1:\n\n| Page | What it does |\n|---|---|\n| [Home](docs/gui/screenshots/home.png) | Three-path onboarding (sample data / upload / wizard) |\n| [Frameworks](docs/gui/screenshots/frameworks.png) | Browse all 89 bundled catalogs with tier + category filters |\n| [Gap Analyze](docs/gui/screenshots/gap-analyze.png) | Form + framework picker → TanStack Table results |\n| [Gap Diff](docs/gui/screenshots/gap-diff.png) | Two-report classification + PR-comment markdown export |\n| [Risk Generate](docs/gui/screenshots/risk-generate.png) | Streamed AI risk statements per gap |\n\nSee [`docs/gui/README.md`](docs/gui/README.md) for a per-page\nwalkthrough + accessibility notes + troubleshooting.\n\n### End-to-end walkthrough with sample data\n\nEvidentia ships with a realistic fictional fintech scenario in\n[`examples/meridian-fintech/`](examples/meridian-fintech/). Walk through it in five steps:\n\n```bash\n# 1. Verify installation\nuv run evidentia doctor\n\n# 2. Explore available frameworks\nuv run evidentia catalog list\n\n# 3. Inspect a specific control\nuv run evidentia catalog show nist-800-53-mod --control SI-4\n\n# 4. See how one framework maps to another\nuv run evidentia catalog crosswalk \\\n  --source nist-800-53-mod --target soc2-tsc --control AC-2\n\n# 5. Run gap analysis on the Meridian Financial sample inventory\ncd examples/meridian-fintech\nuv --project ../.. run evidentia gap analyze \\\n  --inventory my-controls.yaml \\\n  --frameworks nist-800-53-mod,soc2-tsc \\\n  --output report.md --format markdown \\\n  --min-efficiency-frameworks 2\n```\n\nExpected output: a 17-gap report against 28 required controls, 39.3% coverage,\n11 critical / 5 high / 1 medium severities, with the top of the priority queue\ndominated by monitoring/detection gaps (CC7.1, CC7.2, SI-4, AU-6).\n\n### Use as a GitHub Action\n\nv0.7.0 ships a composite GitHub Action that turns every PR into a\ncompliance check. It runs `evidentia gap analyze`, diffs against the\nmain-branch baseline, posts a sticky PR comment with the diff, and gates\nmerge on regressions.\n\n```yaml\n# .github/workflows/compliance.yml\nname: Compliance check\non:\n  pull_request:\n    branches: [main]\n  push:\n    branches: [main]\n\npermissions:\n  contents: read\n  pull-requests: write\n\njobs:\n  compliance:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v5\n        with: { fetch-depth: 2 }\n\n      - uses: allenfbyrd/evidentia/.github/actions/gap-analysis@v0\n        with:\n          inventory: inventory.yaml\n          frameworks: nist-800-53-rev5-moderate,soc2-tsc\n          github-token: ${{ secrets.GITHUB_TOKEN }}\n```\n\nSee [`.github/actions/gap-analysis/README.md`](.github/actions/gap-analysis/README.md)\nfor the full input/output surface, OSCAL AR + Sigstore signing options,\nSHA-pinned variants for audit pipelines, and the migration guide from\nthe legacy standalone `allenfbyrd/evidentia-action@v1` (now archived).\n\n### Generate AI risk statements\n\nRequires an LLM API key. Any LiteLLM-supported provider works:\n\n```bash\nexport OPENAI_API_KEY=sk-...            # or ANTHROPIC_API_KEY, etc.\n\nuv --project ../.. run evidentia risk generate \\\n  --context system-context.yaml \\\n  --gaps report.json \\\n  --model gpt-4o \\\n  --output risks.json \\\n  --limit 5\n```\n\nThis produces five validated `RiskStatement` objects (NIST SP 800-30 structure)\nfor the five highest-priority gaps.\n\n### Starting your own project\n\n```bash\n# From an empty directory\nuv run evidentia init\n\n# Creates:\n#   evidentia.yaml       — config with defaults\n#   my-controls.yaml         — template control inventory\n#   system-context.yaml      — template system context\n#   .evidentia/          — local storage\n```\n\nEdit `my-controls.yaml` with your real inventory and run `evidentia gap analyze`.\n\n---\n\n## Architecture\n\nEvidentia is a **uv workspace monorepo** of six composable Python packages\nplus a React/Vite frontend workspace:\n\n| Package                      | Role                                                                        |\n| ---------------------------- | --------------------------------------------------------------------------- |\n| `evidentia-core`         | Pydantic data models, OSCAL catalog loader, crosswalk engine, gap analyzer  |\n| `evidentia-ai`           | LiteLLM + Instructor client, risk statement generator, control explainer  |\n| `evidentia-collectors`   | Evidence collection agents — AWS (Config + Security Hub), GitHub (branch protection + CODEOWNERS), Okta (SSO + MFA), Databricks (Unity Catalog + clusters), Snowflake (LOGIN_HISTORY + grants + masking), 5 SQL adapters (Postgres / MySQL / SQLite / MSSQL / Oracle), 4 vendor-risk APIs (Vanta / Drata / BitSight / SecurityScorecard) |\n| `evidentia-integrations` | Jira push + bidirectional status sync, ServiceNow ticket sync, Tableau + Power BI publish |\n| `evidentia-api`          | FastAPI server (26 REST routes across 12 router modules) that bundles the React SPA for `evidentia serve` |\n| `evidentia`              | CLI meta-package: Typer/Rich entry points (`evidentia` + `cb` alias)        |\n| `evidentia-ui` *(non-Python)* | Vite + React 18 + shadcn/ui frontend; built bundle is copied into `evidentia-api` at wheel time |\n\nThe 6 v0.5.1 `controlbridge-*` deprecation shims published in v0.6.0\nwere removed at v0.7.0 per the public migration contract. Existing\nv0.5.1 installs continue to work; future releases no longer produce\nshim wheels.\n\n### Data flow\n\n```\n┌─────────────────┐   ┌─────────────────┐   ┌────────────────────┐\n│ my-controls.yaml│   │  OSCAL catalogs │   │ framework mappings │\n│       .csv      │   │  (77 bundled;   │   │    (crosswalks)    │\n│       .json     │   │  manifest-driven) │   └──────────┬───────┘\n└────────┬────────┘   └────────┬────────┘              │\n         │                     ▼                       ▼\n         │           ┌──────────────────────────────────────┐\n         └──────────▶│         GapAnalyzer                  │\n                     │  normalize → match → score → rank    │\n                     └──────────────────┬───────────────────┘\n                                        │\n                     ┌──────────────────┴───────────────────┐\n                     │                                      │\n                     ▼                                      ▼\n         ┌──────────────────────┐              ┌──────────────────────┐\n         │  GapAnalysisReport   │              │   RiskStatementGen   │\n         │  (JSON/CSV/MD/OSCAL) │              │   (NIST SP 800-30)   │\n         └──────────────────────┘              └──────────┬───────────┘\n                                                          │\n                                                          ▼\n                                              ┌──────────────────────┐\n                                              │  LiteLLM+Instructor  │\n                                              │  (any LLM provider)  │\n                                              └──────────────────────┘\n```\n\n### Key design decisions\n\n- **Pydantic v2 everywhere** with `ConfigDict(use_enum_values=True, extra=\"forbid\", str_strip_whitespace=True)`. Structured data, strict validation, JSON-roundtripping for free.\n- **OSCAL as the lingua franca.** Inputs parse OSCAL catalogs and component-definitions. Outputs include OSCAL Assessment Results. Your data is portable.\n- **Instructor for AI structured output.** LLMs return raw text; Instructor enforces a Pydantic schema and automatically retries on validation failure. No regex parsing of LLM output.\n- **Hatchling build backend** with `[tool.hatch.build.targets.wheel] packages = [\"src/...\"]` and `[dependency-groups] dev = [...]` (the modern uv spec, not the deprecated `[tool.uv] dev-dependencies`).\n\n---\n\n## Roadmap\n\nSee [`docs/ROADMAP.md`](docs/ROADMAP.md) for the detailed version-level plan.\nSummary below.\n\n### Phase 1 — MVP (v0.1.0 – v0.2.1) — SHIPPED\n- [x] Core data models\n- [x] OSCAL catalog loader + crosswalk engine\n- [x] Multi-format inventory parser\n- [x] Gap analyzer with priority scoring\n- [x] Report exporters (JSON/CSV/Markdown/OSCAL-AR)\n- [x] AI risk statement generator\n- [x] CLI (init, catalog, gap, risk, doctor)\n- [x] Sample data + end-to-end walkthrough\n- [x] **Phase 1.5 (v0.2.0 big-bang):** exhaustive framework expansion\n      — full upstream NIST 800-53 Rev 5 OSCAL (~1189 controls + Low/Mod/High/Privacy baselines),\n      NIST 800-171 r2/r3, 800-172, CSF 2.0, AI RMF, SSDF, Privacy Framework;\n      FedRAMP Rev 5 baselines; CMMC 2.0 L1/L2/L3; CJIS, CISA CPGs, HIPAA,\n      GLBA, NY DFS 500, NERC CIP, FDA 21 CFR Pt 11, IRS 1075, CMS ARS;\n      EU GDPR/AI Act/NIS2/DORA, UK NCSC CAF, Essential Eight, ACSC ISM,\n      Canada ITSG-33/PIPEDA, NZISM; 15 US state privacy laws; Tier-C stubs\n      for ISO 27001/27002/27017/27018/27701/42001/22301/9001, SOC 2 TSC,\n      PCI DSS 4.0, HITRUST, COBIT, SWIFT CSCF, CIS Controls + Benchmarks,\n      SCF, IEC 62443; MITRE ATT\u0026CK, CWE, CAPEC, CISA KEV;\n      `evidentia catalog import` for user-licensed Tier-C content;\n      GitHub Actions refresh CI for upstream change detection.\n\n### Compliance-as-code (v0.3.x) — SHIPPED\n- [x] `evidentia gap diff` — classify gaps opened / closed / severity-changed / unchanged\n- [x] `--fail-on-regression` for CI integration\n- [x] `evidentia explain \u003ccontrol_id\u003e` — LLM-generated plain-English control translations\n- [x] Three realistic example scenarios (Meridian fintech, Acme Healthtech, Northstar DoD)\n\n### Accessible GRC (v0.4.x) — SHIPPED\n- [x] FastAPI REST server (`evidentia serve`) — 26 `/api/*` routes across 12 router modules\n- [x] React + Vite + shadcn/ui web UI (WCAG 2.1 AA via Radix primitives)\n- [x] Air-gapped mode (`--offline` flag + `doctor --check-air-gap` validator)\n- [x] Reusable GitHub Action (`allenfbyrd/evidentia-action@v1`)\n\n### Phase 2 — Evidence Collection (v0.5.0) — SHIPPED\n- [x] Base collector architecture with `check_connection()`, `collect()`, `get_supported_controls()`\n- [x] **AWS collector** — Config rules + Security Hub (FSBP / CIS)\n- [x] **GitHub collector** — branch protection, CODEOWNERS, visibility\n- [x] **Jira integration** — push gaps as issues + bidirectional status sync\n\n### Rename release (v0.6.0) — SHIPPED\n- [x] ControlBridge → Evidentia across code, PyPI, GitHub, docs\n- [x] v0.5.1 deprecation shims for the six old PyPI names\n\n### Enterprise-grade release (v0.7.0) — SHIPPED\n- [x] SHA-256 digest per evidence item in OSCAL AR exports\n- [x] Optional GPG signing of the AR document (air-gap path)\n- [x] Sigstore/Rekor signing of the AR (online path, OIDC-based)\n- [x] CycloneDX SBOM on every release\n- [x] PyPI Trusted Publisher (OIDC) + PEP 740 attestations\n- [x] OSCAL conformance via `compliance-trestle` round-trip in CI\n- [x] AWS IAM Access Analyzer + GitHub Dependabot collectors\n- [x] ECS-8.11 / NIST-AU-3 / OpenTelemetry structured logs\n- [x] Consolidated GitHub Action at `.github/actions/gap-analysis/`\n- [x] Tamper-evident audit trail for external-auditor review\n\n### AI features hardening (v0.7.1) — SHIPPED\n- [x] `GenerationContext` metadata on every AI-generated artifact (sibling of `CollectionContext`)\n- [x] 9 new `evidentia.ai.*` `EventAction` entries for ECS-structured AI audit events\n- [x] Typed exception hierarchy in `evidentia_ai.exceptions` — closes BLOCKER B3 for `risk_statements/` + `explain/`\n- [x] Bounded retry via `with_retry_async` + `build_retrying`/`build_async_retrying` against shared `LLM_TRANSIENT_EXCEPTIONS` set\n- [x] `run_id`-correlated audit trails across AI generated/failed/retry/cache_hit/batch_completed events\n- [x] Best-effort operator identity via `evidentia_ai.client.get_operator_identity()` — closes NIST AU-3 \"Identity\" gap for AI artifacts\n- [x] 116+ net new tests across `test_ai/`, `test_audit/`, `test_models/`\n\n### Supply-chain polish + documentation refresh (v0.7.2) — SHIPPED\n- [x] OpenSSF Scorecard weekly workflow (`.github/workflows/scorecard.yml`) publishing to `securityscorecards.dev`\n- [x] Cursor + VS Code workspace config (`.vscode/{4 files}` + `.cursorrules` + `.editorconfig`) for testing/validation inline\n- [x] `docs/ide-setup.md` walkthrough — pytest discovery, mypy strict, ruff format-on-save, coverage gutters, 7 debug configs, 16 pre-canned tasks\n- [x] Catalog-drift detector fix — pinned `yaml.safe_dump(width=200)` for byte-stable manifest emit + `--ignore-all-space` workflow guard (closes issues #1-#4)\n- [x] Pre-release-review refinements — 4 MEDIUM doc/config polish fixes (DORA past-tense, doc stamp date, Windows venv path, regen stderr warning)\n\n### Later — quality signals + more integrations (v0.7.x+)\n- [ ] Risk-statement quality validator (NIST SP 800-30 / IR 8286 scoring + auto-regeneration)\n- [ ] Additional collectors — IAM Access Analyzer, Dependabot, Okta, Azure, GCP\n- [ ] Additional integrations — ServiceNow, Vanta, Drata\n- [ ] Compliance ROI scoring (\"close N gaps across M frameworks with one remediation\")\n- [ ] Auto-generated TypeScript types from FastAPI OpenAPI schema\n- [ ] Tauri desktop packaging for offline-first users\n\n### Phase 3 — AI Evidence Validation (later)\n- [ ] Evidence-to-control relevance scoring (is this screenshot actually proof of MFA?)\n- [ ] Freshness / staleness detection per framework (SOC 2 = 90 days, NIST = 365)\n- [ ] Multi-modal validation (PDFs, screenshots, log exports, JSON)\n- [ ] Coverage heatmaps\n\n### Platform — network deployment (later)\n- [ ] Multi-user auth / RBAC for network deployments (localhost-only today)\n- [ ] Multi-tenant database backend (PostgreSQL)\n- [ ] Cost analytics (LLM spend per control / per framework)\n\n### Phase 5 — Ecosystem\n- [ ] Plugin system for custom collectors\n- [ ] OSCAL catalog marketplace / community contributions\n- [ ] Integration with policy-as-code tools (OPA, Cedar)\n- [ ] Terraform provider for compliance-as-code\n\nSee [`Evidentia-Architecture-and-Implementation-Plan.md`](Evidentia-Architecture-and-Implementation-Plan.md)\nfor the full canonical plan (~318 KB) including all code sketches, data\nflows, and technology rationales.\n\n---\n\n## Development\n\n### Project layout\n\n```\nEvidentia/\n├── packages/\n│   ├── evidentia-core/         # Pydantic models, catalogs, gap analyzer\n│   ├── evidentia-ai/           # LiteLLM client, risk generator, explain\n│   ├── evidentia-collectors/   # AWS (Config + Security Hub), GitHub\n│   ├── evidentia-integrations/ # Jira (push + sync)\n│   ├── evidentia-api/          # FastAPI REST server + bundled SPA\n│   ├── evidentia/              # CLI meta-package (Typer entry points)\n│   └── evidentia-ui/           # Vite + React + shadcn/ui frontend\n├── tests/\n│   ├── fixtures/                   # Sample inventories + recorded fixtures\n│   ├── unit/                       # Unit tests (per-package subtrees)\n│   └── integration/                # CLI + examples smoke tests\n├── examples/\n│   ├── meridian-fintech/           # Realistic fintech walkthrough\n│   ├── acme-healthtech/            # HIPAA-focused scenario\n│   └── northstar-systems/          # DoD / CMMC scenario\n├── docs/\n│   ├── ROADMAP.md                  # Version-level plan\n│   ├── air-gapped.md               # `--offline` mode guide\n│   ├── architecture/               # Deep-dive docs\n│   ├── github-action/              # Reusable action docs\n│   └── gui/                        # Web UI guide\n├── .github/\n│   ├── workflows/test.yml          # CI: pytest matrix + ruff + mypy\n│   ├── workflows/release.yml       # Auto-release on main-branch deploys\n│   └── ISSUE_TEMPLATE/             # Bug report / feature request\n└── pyproject.toml                  # uv workspace root\n```\n\n### Run tests\n\n```bash\nuv run pytest tests/ -q                       # All tests\nuv run pytest tests/unit/ -v                  # Unit tests with verbose output\nuv run pytest tests/unit/test_gap_analyzer/   # One subpackage\n```\n\n### Add a new framework catalog\n\n1. Drop an OSCAL catalog JSON file in `packages/evidentia-core/src/evidentia_core/catalogs/data/\u003cframework-id\u003e.json`.\n2. Register its metadata in `catalogs/registry.py` under `FRAMEWORK_METADATA`.\n3. Optionally add crosswalks in `catalogs/data/mappings/`.\n4. Run `evidentia catalog list` — your framework should appear.\n\n### Code style\n\n- Python 3.12+ syntax: `str | None`, `list[str]`, `from datetime import UTC`\n- `from __future__ import annotations` at the top of every module\n- Ruff + mypy (configured in `pyproject.toml`)\n\n---\n\n## Contributing\n\nPhases 1, 1.5, 2 (Jira + AWS + GitHub), and Accessible GRC (v0.4.x web UI\n+ air-gap mode) are shipped. High-value contribution areas:\n\n- **Additional crosswalks** — especially ISO 27001 ↔ NIST 800-53 and PCI DSS ↔ SOC 2\n- **Queued collectors** — IAM Access Analyzer, Dependabot, Okta, Azure, GCP\n- **Queued integrations** — ServiceNow, Vanta, Drata\n- **Evidence chain of custody (v0.7.0)** — SHA-256 digests + GPG signing of OSCAL AR exports\n- **Risk-statement quality validation** — NIST SP 800-30 / IR 8286 scoring of AI output\n- **Production OSCAL catalogs** — drop-in JSON files from upstream sources\n- **Test coverage** — edge cases in CSV header matching, OSCAL parsing, and air-gap guard\n\n---\n\n## Security\n\nPlease **do not open a public GitHub issue** for security concerns.\nSee [`SECURITY.md`](SECURITY.md) for the disclosure process —\nGitHub Private Vulnerability Reporting is the preferred channel;\nemail is documented as a backup. The policy also covers the\nsupported-version table, scope, disclosure timeline, and\nsupply-chain provenance verification.\n\nEvery release ships with cryptographic provenance: PEP 740\nattestations on every wheel + sdist (Sigstore + Rekor), CycloneDX\n1.6 SBOM attached to each [GitHub\nRelease](https://github.com/allenfbyrd/evidentia/releases).\nVerification command in [`SECURITY.md`](SECURITY.md).\n\n---\n\n## License\n\n[Apache License 2.0](LICENSE)\n\n---\n\n## Acknowledgments\n\nEvidentia stands on the shoulders of excellent open-source projects:\n\n- **[NIST OSCAL](https://pages.nist.gov/OSCAL/)** — the structured data standard that makes framework interop possible\n- **[Pydantic](https://docs.pydantic.dev/)** — type-safe data models without the boilerplate\n- **[LiteLLM](https://docs.litellm.ai/)** — unified LLM access across every provider\n- **[Instructor](https://python.useinstructor.com/)** — structured output extraction from LLMs\n- **[Typer](https://typer.tiangolo.com/)** and **[Rich](https://rich.readthedocs.io/)** — the CLI is only as good as the framework\n- **[uv](https://docs.astral.sh/uv/)** — Python packaging that finally feels modern\n\n## AI assistance\n\nThis project was developed alongside AI platforms.\n\nModels used: Claude Opus 4.6, Claude Opus 4.7, Sonar Deep Research\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fallenfbyrd%2Fevidentia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fallenfbyrd%2Fevidentia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fallenfbyrd%2Fevidentia/lists"}