{"id":49046568,"url":"https://github.com/allenfbyrd/controlbridge","last_synced_at":"2026-04-21T19:00:44.405Z","repository":{"id":352450089,"uuid":"1212583206","full_name":"allenfbyrd/controlbridge","owner":"allenfbyrd","description":"Open-source Python GRC tool: gap analysis, AI risk statements, OSCAL-first compliance automation","archived":false,"fork":false,"pushed_at":"2026-04-20T01:38:26.000Z","size":2172,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-20T18:04:30.476Z","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-20T01:38:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/allenfbyrd/controlbridge","commit_stats":null,"previous_names":["allenfbyrd/controlbridge"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/allenfbyrd/controlbridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allenfbyrd%2Fcontrolbridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allenfbyrd%2Fcontrolbridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allenfbyrd%2Fcontrolbridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allenfbyrd%2Fcontrolbridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/allenfbyrd","download_url":"https://codeload.github.com/allenfbyrd/controlbridge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allenfbyrd%2Fcontrolbridge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32105868,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-21T11:25:29.218Z","status":"ssl_error","status_checked_at":"2026-04-21T11:25:28.499Z","response_time":128,"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-19T17:14:43.894Z","updated_at":"2026-04-21T19:00:44.381Z","avatar_url":"https://github.com/allenfbyrd.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ControlBridge\n\n\u003e **Bridge the gap between your controls and your frameworks.**\n\n**ControlBridge** 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/controlbridge/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/allenfbyrd/controlbridge/actions/workflows/test.yml)\n[![PyPI version](https://img.shields.io/pypi/v/controlbridge.svg)](https://pypi.org/project/controlbridge/)\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![Status: Phase 1 MVP](https://img.shields.io/badge/status-Phase%201%20MVP-yellow.svg)\n[![Code of Conduct](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)\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 ControlBridge exists\n\nControlBridge 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 ControlBridge, 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 ControlBridge 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.** ControlBridge 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: 82 frameworks bundled, 501 tests passing\n\n**v0.4.0-alpha.1 (April 2026)** is the **\"Accessible GRC\"** release.\nControlBridge grows beyond the CLI with a FastAPI REST server, a\nReact + shadcn/ui web UI (localhost-only, WCAG 2.1 AA via Radix\nprimitives), an air-gapped mode (`--offline` flag +\n`doctor --check-air-gap` validator), and a new sixth workspace\npackage (`controlbridge-api`).\n\nInstall the UI via the new `[gui]` extra:\n\n```bash\nuv tool install \"controlbridge[gui]\"\n# or\npip install \"controlbridge[gui]\"\n\ncontrolbridge serve   # web UI at http://127.0.0.1:8000\n```\n\nSee [`docs/gui/README.md`](docs/gui/README.md) for the full UI guide and\n[`docs/air-gapped.md`](docs/air-gapped.md) for air-gapped deployments.\nThe alpha.1 ships the read-only web UI (Home / Dashboard / Frameworks /\nSettings); the interactive onboarding wizard, Gap Analyze form, Gap\nDiff picker, and Risk Generate streaming page land in alpha.2.\n\n**v0.3.1 (April 2026)** added three realistic end-to-end example\nscenarios — Meridian Financial (fintech), Acme Healthtech (HIPAA),\nNorthstar Systems (DoD contractor) — with pre-generated gap\nsnapshots and a full walkthrough that exercises every feature\nadded through v0.3.0. The repo dog-foods its own GitHub Action\n(`.github/workflows/controlbridge.yml`) on every PR against the\nMeridian v2 inventory. Start at\n[`examples/WALKTHROUGH.md`](examples/WALKTHROUGH.md). Also fixed one\nlatent bug in `compute_gap_diff` that only affected library-level\n(non-CLI) callers — flagged by the new integration-test regression\nguard.\n\n**v0.3.0 (April 2026)** is the **compliance-as-code release**:\n\n- **`controlbridge gap diff`** — compare two gap-analysis snapshots,\n  classify each gap as opened / closed / severity-changed / unchanged.\n  Pair with `--fail-on-regression` in a GitHub Action to block PRs\n  that make compliance posture worse. No commercial GRC tool does this\n  at the PR level. See [`docs/github-action/README.md`](docs/github-action/README.md)\n  for the drop-in workflow.\n- **`controlbridge explain \u003ccontrol_id\u003e`** — LLM-generated plain-English\n  translation of any framework's control text. Answers the questions\n  engineers actually ask (\"what does this mean, why should I care,\n  what do I do?\") instead of quoting the NIST legal prose verbatim.\n  Cached to disk per (framework, control, model, temperature) so\n  repeat lookups are free.\n\nAlso: the `FrameworkId` enum (deprecated in v0.2.0) is removed; mypy\nCI is now strict (no more `continue-on-error`); +32 new tests.\n\n**v0.2.1 (April 2026)** was the correctness patch that:\n\n- Bundles the full **NIST SP 800-53 Rev 5** catalog (1,196 controls,\n  verbatim from `usnistgov/oscal-content`) plus the four resolved\n  **Low / Moderate / High / Privacy baselines** — so `gap analyze\n  --framework nist-800-53-rev5-moderate` actually runs against the real\n  287-control baseline instead of a 16-control sample.\n- Rewrites the FedRAMP baselines with real NIST text (v0.2.0 shipped them\n  as pointer-only stubs).\n- Replaces the always-LOW gap effort estimator with a keyword-aware\n  hybrid heuristic, so the prioritized roadmap actually surfaces\n  easy-win controls.\n- Wires the `controlbridge.yaml` project config loader that `init` has\n  been generating since v0.1.0 but nothing read. Precedence:\n  **CLI flag \u003e env var \u003e yaml \u003e built-in default**.\n- Persists gap reports to a user-dir store, making `risk generate\n  --gap-id GAP-…` work without re-running `gap analyze`.\n- +221 new tests (131 → 352 passing); all `controlbridge catalog`\n  subcommands now covered; OSCAL profile resolver tested end-to-end.\n\nSee [`CHANGELOG.md`](CHANGELOG.md) for the full v0.2.1 entry and\n[`docs/ROADMAP.md`](docs/ROADMAP.md) for the v0.3.0+ plan.\n\n### What works today\n\n- **Gap analysis against 77 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 `controlbridge 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`, `risk generate`, `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`).\n\n- **392 passing pytest tests** 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, `FrameworkId` deprecation,\n  crosswalk bidirectionality, multi-format inventory parsing, severity\n  calculation, and all four report exporters.\n\n### What Phase 1 explicitly does NOT include\n\nSetting expectations matters. Phase 1 does NOT yet include:\n\n- Evidence collectors for AWS, Azure, GCP, GitHub, or Okta (Phase 2)\n- LLM-based evidence validation (Phase 3)\n- Jira or ServiceNow push integrations (Phase 2)\n- The FastAPI REST server (`controlbridge serve`)\n- A web UI\n- Full-depth NIST 800-53 Rev 5 catalog (~323 controls with 3-level\n  enhancements) — v0.2.0 ships the 16-control Moderate sample plus\n  pointer-style FedRAMP baselines that the OSCAL profile resolver can\n  turn into resolved 149/287/369-control baselines once you supply the\n  full upstream NIST OSCAL catalog via `catalog import --profile`.\n  Direct bundling of the full NIST Rev 5 catalog is planned for v0.2.1\n  via the upstream refresh CI workflow.\n- Authoritative control text for copyrighted frameworks (ISO 27001/27002,\n  SOC 2 TSC, PCI DSS, HITRUST CSF, etc.). These frameworks will ship as\n  **Tier C stubs** in v0.2.0 — public clause numbering only, with a\n  `controlbridge catalog import` command 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 controlbridge\n```\n\nThis installs the `controlbridge` and `cb` CLI commands, plus the four workspace\nsub-packages as transitive dependencies (`controlbridge-core`, `controlbridge-ai`,\n`controlbridge-collectors`, `controlbridge-integrations`).\n\n### Install from source (for contributors)\n\n```bash\ngit clone https://github.com/allenfbyrd/controlbridge.git\ncd controlbridge\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: 22 passed in ~0.3s\n```\n\n### End-to-end walkthrough with sample data\n\nControlBridge 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 controlbridge doctor\n\n# 2. Explore available frameworks\nuv run controlbridge catalog list\n\n# 3. Inspect a specific control\nuv run controlbridge catalog show nist-800-53-mod --control SI-4\n\n# 4. See how one framework maps to another\nuv run controlbridge 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 controlbridge 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### 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 controlbridge 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 controlbridge init\n\n# Creates:\n#   controlbridge.yaml       — config with defaults\n#   my-controls.yaml         — template control inventory\n#   system-context.yaml      — template system context\n#   .controlbridge/          — local storage\n```\n\nEdit `my-controls.yaml` with your real inventory and run `controlbridge gap analyze`.\n\n---\n\n## Architecture\n\nControlBridge is a **uv workspace monorepo** of five composable Python packages:\n\n| Package                      | Role                                                                        |\n| ---------------------------- | --------------------------------------------------------------------------- |\n| `controlbridge-core`         | Pydantic data models, OSCAL catalog loader, crosswalk engine, gap analyzer  |\n| `controlbridge-ai`           | LiteLLM + Instructor client, risk statement generator, evidence validator  |\n| `controlbridge-collectors`   | Evidence collection agents for cloud and SaaS systems *(Phase 2)*          |\n| `controlbridge-integrations` | Jira and ServiceNow push integrations *(Phase 2)*                           |\n| `controlbridge`              | Meta-package: Typer/Rich CLI and FastAPI REST server                        |\n\n### Data flow (Phase 1)\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\n### Phase 1 — MVP (this release)\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      `controlbridge catalog import` for user-licensed Tier-C content;\n      GitHub Actions refresh CI for upstream change detection.\n\n### Phase 2 — Evidence Collection (next)\n- [ ] Base collector architecture with `check_connection()`, `collect()`, `get_supported_controls()`\n- [ ] **AWS collector** — Config rules, Security Hub findings, IAM policies, CloudTrail, Audit Manager\n- [ ] **GitHub collector** — branch protection, required reviews, Actions runners, secret scanning status\n- [ ] **Okta collector** — MFA enforcement, session policies, user lifecycle evidence\n- [ ] **Azure collector** — Policy, Defender for Cloud, Entra ID\n- [ ] **GCP collector** — Security Command Center, Cloud Asset Inventory\n- [ ] **Evidence bundle storage** — local file, SQLite, git-backed\n- [ ] **Scheduled collection** with cron or CI triggers\n- [ ] **Jira / ServiceNow integration** — push gaps as tickets with severity and remediation guidance\n\n### Phase 3 — AI Evidence Validation\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### Phase 4 — Platform\n- [ ] FastAPI REST server (`controlbridge serve`)\n- [ ] Multi-tenant database backend (PostgreSQL)\n- [ ] Web UI for non-technical reviewers\n- [ ] Audit trail with cryptographic evidence hashes\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 [`ControlBridge-Architecture-and-Implementation-Plan.md`](ControlBridge-Architecture-and-Implementation-Plan.md)\nfor the full canonical plan (312 KB, ~8200 lines) including all code sketches, data\nflows, and technology rationales.\n\n---\n\n## Development\n\n### Project layout\n\n```\nControlBridge/\n├── packages/\n│   ├── controlbridge-core/         # Pydantic models, catalogs, gap analyzer\n│   ├── controlbridge-ai/           # LiteLLM client, risk generator\n│   ├── controlbridge-collectors/   # (Phase 2)\n│   ├── controlbridge-integrations/ # (Phase 2)\n│   └── controlbridge/              # CLI + API meta-package\n├── tests/\n│   ├── fixtures/                   # Sample inventories for tests\n│   └── unit/                       # Unit + end-to-end tests\n├── examples/\n│   └── meridian-fintech/           # Realistic walkthrough sample\n├── .github/\n│   ├── workflows/test.yml          # CI: pytest matrix + ruff\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/controlbridge-core/src/controlbridge_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 `controlbridge 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\nPhase 1 is complete and the architecture is stable. High-value contribution\nareas:\n\n- **Production OSCAL catalogs** — drop-in JSON files from upstream sources\n- **Additional crosswalks** — especially ISO 27001 ↔ NIST 800-53 and PCI DSS ↔ SOC 2\n- **Phase 2 collectors** — AWS, GitHub, and Okta are the highest priority\n- **Test coverage** — particularly edge cases in CSV header matching and OSCAL parsing\n\n---\n\n## License\n\n[Apache License 2.0](LICENSE)\n\n---\n\n## Acknowledgments\n\nControlBridge 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%2Fcontrolbridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fallenfbyrd%2Fcontrolbridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fallenfbyrd%2Fcontrolbridge/lists"}