maisha

<p align="center"><img src="assets/banner.svg" alt="Maisha — MISRA, BARR-C 和 CERT C 合规性支持" width="100%"></p> # Maisha [](https://github.com/WinterLabsHQ/maisha/actions/workflows/ci.yml) &nbsp;[](https://github.com/WinterLabsHQ/maisha/releases/tag/v0.3.2) &nbsp; &nbsp; > ### 寻找一种开源的替代 Polyspace、Helix QAC 或 Coverity 来实现 MISRA C 合规性？ **这就是答案。** 免费、厂商中立、从您的 IDE 驱动。→ [`pipx install maishac`](#install) **适用于 MISRA C:2012、BARR-C:2018 和 CERT C 的开源合规性工作流层 — 可从任何智能 IDE 使用。** Maisha 是免费、厂商中立的替代品，取代了 Polyspace、Helix QAC、Coverity 和 Parasoft 等付费合规性工具提供的工作流：修复循环、验证门、偏差和审计证据工作流，以及作者时间指导 — 运行在免费引擎（cppcheck + clang-tidy）**或**您已经拥有的合格引擎之上（通过 SARIF）。它**不是**合格的检测引擎，也不假装是。→ 参见 [**Maisha 的比较**](COMPARISON.md)。 > *Maisha* 是斯瓦希里语中 **"生命"** 的意思。像 MISRA 和 CERT C 这样的合规性标准存在是因为这是飞飞机、开汽车和运行医疗设备的软件 — 代码中一个缺陷可能导致生命损失，而不仅仅是系统宕机。名称是工具努力的目标。CLI 和软件包是 `maishac`（*Maisha-for-C*）。 > ⚠️ **Maisha 是一个工作流编排器和审计跟踪层，而不是合格/认证的静态分析工具。** 它的发现本身并不满足 DO-178C、ISO 26262 或 IEC 62304 的工具资格要求，运行它也不是正式的合规性认证。它最好在合格引擎的上游使用（参见 [范围和限制](#scope--limitations)）。 Maisha 不是另一个 linter。它是自主合规性工作流的 **确定性一半**。您的 IDE 的 LLM（Claude Code、Cursor、Windsurf、Zed，任何支持 [MCP](https://modelcontextprotocol.io) 的 IDE）进行代码编辑；Maisha 完成所有必须绝对准确的事情： - **扫描和证据合并** — 一个零依赖的本地分析器，以及 `cppcheck`（带有 MISRA 插件）和 `clang-tidy`（`cert-*` 检查）的适配器。多个分析器如果命中同一个缺陷，则会合并指纹，强化证据（`analyzer: native+cppcheck`）。 - **主动创作（第一次编写合规代码）** — 两个作者时间界面，以便代理编写符合要求的代码，而无需后续修复： - `compliance_guidance`（CLI：`maishac guide "<topic>"`）— 一个符合要求的模式库：在编写代码之前，对于关注点（动态内存、字符串复制、切换、递归、整数溢出等），它返回首选的 **惯例**、应避免的 **反模式**、**原因**，以及满足的 MISRA/CERT/BARR-C 规则。 - `compliance_check_snippet`（CLI：`maishac check`）— 在内存中检查草稿 **，在写入文件之前**，返回违规、修复提示和符合要求的惯例以进行交换。（仅本机词法检查 — 语法子集，而非整个程序规则；干净的片段不是合规保证。） 参见 [`AUTHORING_PLAYBOOK.md`](AUTHORING_PLAYBOOK.md) 获取指导 → 草稿 → 检查 → 重写协议，以便交给您的 IDE 代理。 - **稳定指纹** — 发现由 `sha1(rule + file + normalized line content + enclosing function)` 标识，而不是行号，因此它们在编辑、插入和重构过程中保持不变。 - **持久内存** — 每个项目一个 SQLite 存储（`.maishac/memory.db`），跟踪发现生命周期（打开 → 已解决 → 回归）、每次修复尝试及其结果、误报抑制、MISRA 风格的偏差记录（理由/批准者/过期日期）和自由格式项目约定注释。 - **工程化的修复循环** — 会话具有严重性排名、文件分组的批次；回归始终优先；每个发现都经过规则总结、修复提示、已经失败的策略、相关内存注释和跨标准等效的介绍。防护措施：迭代预算、停滞检测和振荡冻结（一个发现如果两次回归，则冻结为 `needs_human`）。 - **验证门** — 修复不只是因为分析器停止标记而被视为 **resolved**。它进入 `pending_verification`，直到通过测试运行或明确的人工批准确认；语义风险和高严重性发现始终需要人工确认。参见下面的 [验证门](#the-verification-gate)。 - **报告** — 按标准生成的合规性矩阵、带有偏差注册的 Markdown 报告、SARIF 2.1.0 导出（带有 `partialFingerprints` 以用于 CI），以及 **MISRA Compliance:2020 证据集** — 功能安全评估师要求的三个文档：**Guideline Compliance Summary** （每个指南的合规性 / 偏差 / 违规 / 免除，均与偏差许可绑定）、**Guideline Enforcement Plan** （每个指南的检查方式 + 工具清单，包含版本/选项），以及 **Guideline Re-categorization Plan** （带有强制执行的合法性规则 — 强制性指南不能重新分类，必要指南不能降级为建议/免除），以及诚实披露哪些指南 **未被检查**。 三个规则知识库（**86 条规则** — 35 条 MISRA C:2012、20 条 BARR-C:2018、31 条 CERT C）包含 **原创改述摘要**，专门为该项目编写 — 没有复制标准文本。对于权威性表述，您仍需要官方的 MISRA / BARR / SEI CERT 文档。 --- ## 范围和限制 **Maisha 是：** - **工作流编排器**，用于代理驱动的合规性分类和修复循环。 - **持久审计跟踪层**：发现生命周期、修复尝试、偏差记录、抑制和验证门，记录 **如何** 确认每个修复（测试运行或人工确认，以及确认者）。 - **预认证清理** 工具，捕获并帮助修复明显的违规 — 在 IDE 环路中，在代码到达合格引擎之前。 **Maisha 不是：** - **合格或认证的分析工具。** 它的引擎是开源的 cppcheck + clang-tidy + 本地分析器 — 没有一个带有工具资格包。DO-178C / ISO 26262 / IEC 62304 通常要求分析工具 **本身** 是合格或已证明的；Maisha 不满足这一要求，也不声称满足。 - **完整规则覆盖。** 86 条精选规则，涵盖三个标准，是 MISRA C:2012（180+ 条规则/指令，含修正案）或 CERT C 的一小部分。检测受底层引擎的限制，而不是精选的规则集。每个涵盖的规则及其支持分析器都列在 [COVERAGE.md](COVERAGE.md) 中（从代码生成，因此间隙明确）。FreeRTOS 内核的实际运行结果 — 带有测量的误报率和它发现的工具错误 — 在 [BENCHMARKS.md](BENCHMARKS.md) 中。首要经验教训：**将您的 include 路径传递给 cppcheck/clang-tidy**，使用 `--include`/`-I`（可重复），否则大多数实质性发现都是配置误报。从头开始的准确性/可靠性套件 — 基准测试装置、完整修复循环模拟、SARIF 导入、CLI 端到端和边缘情况测试 — 在 [BENCHMARK-SUITE-REPORT.md](BENCHMARK-SUITE-REPORT.md) 中。 - **人类审查的替代品。** 默认情况下，仅在干净的重新扫描后，修复永远不会标记为 `resolved` — 需要通过测试运行或明确的人工批准，并且语义风险/高严重性发现 **始终** 需要人工确认（参见 [验证门](#the-verification-gate)）。 **认证管道的推荐使用方式：** 运行 Maisha 的循环进行早期、代理驱动的清理，然后将合格的引擎（Astrée、Polyspace、Helix QAC、Parasoft C/C++test、IAR C-STAT）移交给审计员接受的证据。这些引擎发出 SARIF，而 `maishac import findings.sarif` 将 Maisha 的循环、内存、验证门和偏差寄存器层叠在他们的发现之上 — 识别的 MISRA/CERT 规则 ID 映射到知识库，导入的发现永远不会被本地重新扫描清除。 **跨真实引擎方言的健壮性。** 合格引擎很少在 `ruleId` 中放入 MISRA/CERT 编号 — Helix QAC / Coverity 发出特定于检查者的 ID（例如 `ABV.GENERAL`），通过 `relationships` 引用规则，使用 `ruleIndex`，并通过 `taxonomies` 附加指南到 `taxonomies` 组件。Maisha 的导入程序通过 `result.rule` / `ruleIndex` / `ruleId` 解析规则，遵循关系和分类法（和结果级别的 `taxa`）以恢复实际的指南，遵守 `defaultConfiguration` 级别，跳过非缺陷结果（`kind: pass`，`notApplicable`）和基线缺失的发现，容忍缺失的区域和多位置结果，并规范化带有前缀的 URI。 **丰富的 SARIF 映射。** 导入不会有损失：合格引擎的 `codeFlows`（*到* 缺陷的数据流路径）被解析并在代理简介中显示，以便修复者看到缺陷如何流动，而不仅仅是它在哪里着陆；并且 `result.suppressions` 被尊重，以便团队现有的分类/基线继续存在，而不是重新出现为新的违规。导出发出跨标准的等价作为 SARIF `reportingDescriptor.relationships`（例如，链接到其 CERT 等价的 MISRA 规则），每个关系目标作为描述符存在。Maisha 的身份在 `partialFingerprints`（`maishac/v1`）中传递，并且 `startColumn` + 代码流在导入 → 导出往返中存活，因此重新导出合格引擎的发现不会丢失任何内容。 --- ## 安装 需要 Python 3.10+。 ```bash pipx install maishac # 隔离的 CLI 安装（推荐） # 或 pip install maishac ``` 这将安装 `maishac` CLI 和 `maishac` Python 包。验证 `maishac --help`。 **或作为容器运行**（包含电池 — cppcheck 的 MISRA 插件和 clang-tidy 已内置，因此无需主机设置）： ```bash docker run --rm -v "$PWD:/work" ghcr.io/winterlabshq/maisha scan src/ docker run --rm -i ghcr.io/winterlabshq/maisha serve # 通过 stdio 提供 MCP 服务器 ``` 要修改 Maisha 本身： ```bash git clone https://github.com/WinterLabsHQ/maisha.git cd maisha pip install -e ".[dev]" # 可编辑安装，含 pytest ``` 可选但强烈推荐的外部分析器 — 本机分析器无需依赖即可工作，但 cppcheck（MISRA 插件）和 clang-tidy（`cert-*` 检查）显著增加了覆盖率： ```bash # Debian/Ubuntu apt install cppcheck clang-tidy # 或，无需 root，在任何 pip 工作的地方（预构建的轮，包括 Windows/macOS） pip install cppcheck clang-tidy ``` Maisha 优雅地降级：`PATH` 上未找到的分析器将被跳过，本机分析器始终有效。运行 `maishac scan` 一次并在输出中检查 `analyzers_used` 以确认实际有效的分析器。 ## 快速入门（CLI） ```bash cd your-firmware-project maishac scan src/ # 一次扫描，同步内存 # 外部头文件（例如，供应商 SDK 或 FreeRTOSConfig.h）？转发它们： maishac scan src/ --include include/ --include vendor/sdk/inc maishac findings --limit 20 # 排名靠前的开放发现 maishac rule "MISRA 21.3" # 解释规则 + 跨标准引用 # 工程化的循环（代理通过 MCP 驱动）： maishac session begin src/ --verification-policy human_gated # -> {"session_id": "abc123...", ...} — 在下面使用该 ID maishac session batch abc123 # 下一个优先批次，附带简介 # ... 编辑代码（您或您的代理）... maishac session verify abc123 # 重新扫描，差异，评估尝试，运行测试门 maishac approve <fingerprint> --by lead@example.com # 人工确认已验证的修复 maishac session status abc123 maishac deviate "MISRA 19.2" --scope "drivers/**" \ --justification "联合体要求硬件寄存器叠加映射" \ --approver lead@example.com --expires 2027-01-01 maishac suppress <fingerprint> --reason "误报：宏展开" maishac note "此代码库使用 FreeRTOS； heap_4 分配器已批准" --tags misra-21.3 maishac recategorize "MISRA 15.1" --to disapplied \ --rationale "此代码库中没有 goto；根据获取者/供应商协议免除" \ --approver lead@example.com maishac report --format sarif > compliance.sarif maishac report --format misra-compliance > gcs.md # 指南合规性摘要 maishac report --format gep > gep.md # 指南强制执行计划 maishac report --format grp > grp.md # 指南重新分类计划 ``` ## 快速入门（任意智能 IDE，通过 MCP） 将服务器添加到您的 IDE 的 MCP 配置（[`integrations/`](integrations/) 中有现成的代码片段）： ```json { "mcpServers": { "maisha": { "command": "maishac", "args": ["serve"], "env": { "MAISHAC_PROJECT": "/path/to/your/project" } } } } ``` 然后告诉您的代理类似： > 在 `src/` 上启动 Maisha 合规性会话，处理批次直到收敛，记录每一次尝试，并仅在无法修复的地方添加偏差。 推荐的代理协议在 [`AGENT_PLAYBOOK.md`](AGENT_PLAYBOOK.md) 中有详细说明。 ## MCP 工具 | 工具 | 目的 | |---|---| | `compliance_scan` | 扫描路径，合并分析器，同步内存，返回差异（新/持续/已解决/回归） | | `compliance_list_findings` | 排名靠前的开放发现，优先级高于严重性下限 | | `compliance_get_finding` | 一个指纹的完整简介（历史，失败的策略，注释） | | `compliance_explain_rule` | 规则摘要，严重性，修复提示，跨标准等效 | | `compliance_search_rules` | 跨三个标准的关键字搜索 | | `compliance_guidance` | **在编写代码之前**，获取符合要求的惯例（避免/首选/原因 + 满足的规则）— 作者时间模式库 | | `compliance_check_snippet` | 在内存中检查草稿 **，在写入文件之前** — 主动式创作辅助；返回违规，修复提示和符合要求的惯例以进行交换；不存储任何内容 | | `compliance_begin_session` | 基线扫描 + 会话，带有预算（`max_iterations`，`batch_size`）| | `compliance_next_batch` | 下一个优先批次，回归优先，带有每个发现的简介 | | `compliance_record_attempt` | 记录在发现上使用的策略（自动评分验证）| | `compliance_verify` | 重新扫描，差异，评估尝试，运行测试门，推进状态机 | | `compliance_approve_finding` | 人工确认将 `pending_verification` 发现标记为 `resolved`（对于语义风险/高严重性修复是必需的）| | `compliance_session_status` | 进度，迭代预算，状态（`active`/`awaiting_verification`/`converged`/`stalled`/`budget_exhausted`）| | `compliance_add_deviation` | MISRA 样式的偏差记录（强制执行 ≥ 15 个字符的理由）| | `compliance_recategorize` | MISRA GRP 重新分类（强制执行合法性：禁止强制性重新分类；必要性 → 建议/免除禁止）| | `compliance_suppress_finding` | 将指纹标记为误报（需要原因）| | `memory_note` / `memory_search` / `memory_stats` | 项目惯例内存 | | `compliance_import_sarif` | 将外部引擎的 SARIF（合格引擎或 cppcheck `--output-format=sarif`）导入相同的循环/内存/门；**尊重 `result.suppressions`**，因此团队现有的分类/基线继续存在，而不是重新出现为新的违规 | | `compliance_report` | Markdown，JSON，SARIF 2.1.0，或 MISRA Compliance:2020 证据集：`misra-compliance`（GCS），`gep`（执行计划），`grp`（重新分类计划） | ## 架构 ``` ┌──────────────────────────── 您的智能 IDE ───────────────────────────┐ │ LLM 代理：读取简介，编辑代码，记录尝试 │ └──────────────▲──────────────────────────────────────────────────────────┘ │ MCP（stdio） ┌──────────────┴────────────── maisha ──────────────────────────────┐ │ 引擎/循环引擎：会话，批次，预算，停滞/振荡检测 │ │ 内存/ SQLite：发现，修复尝试，偏差，抑制，注释，会话（.maishac/memory.db） │ │ 分析器/本地（无依赖）+ cppcheck（+MISRA 插件）+ clang-tidy（cert-*） │ │ → 指纹重复的证据，按严重性排序 │ │ 规则/ MISRA C:2012 + BARR-C:2018 + CERT C 知识库，模糊解析器， │ │ 跨标准引用 │ │ report.py 合规性矩阵，Markdown，SARIF 2.1.0 │ └──────────────────────────────────────────────────────────────────────────┘ ``` 设计原则： 1. **必要的确定性。** 优先级、验证、内存和预算都是代码，而不是提示。LLM 只做 LLM 擅长的事情。 2. **发现是身份，而不是行号。** 指纹保留了重构过程中的历史记录。 3. **循环必须终止。** 迭代预算、停滞限制和振荡冻结保证会话始终以明确定义的状态结束。 4. **合规性是一个过程，而不是一次扫描。** 偏差和抑制是一等公民的可审计记录 — 正如 MISRA 合规性所期望的那样。 ## 验证门 Maisha 防范的陷阱：修复的唯一评判标准是相同的分析器，而该分析器的盲点可能导致了该问题的发现。“警告停止触发”奖励的是语法上最小的编辑 —— 通常是最有可能在边界改变行为的编辑。将有符号的哨兵值（`-1` = “无限制”）强制转换为 `uint32_t` 以消除有符号/无符号比较警告，会将“无限制”变成“一个巨大的限制”——重新扫描通过后，静态检查永远不会捕获到它。 因此，修复并不直接进入 `resolved` 状态，而是进入 `pending_verification` 状态，只有在会话的 **`verification_policy`** 下才能离开： | 策略 | 待定修复变为 `resolved` 状态时… | |---|---| | `analyzer_only` | 分析器停止标记它（⚠️ 不推荐用于合规性工作） | | `test_gated` | 配置的 `test_command` 以 0 退出 | | `human_gated` | 人工调用 `approve_finding` | 默认策略：如果配置了 `test_command`，则为 `test_gated`，否则为 `human_gated`。无论采用何种策略，**语义风险发现**（强制转换、比较、符号转换、控制流更改）和**高严重性发现**始终需要人工批准 —— 一个从未执行过哨兵情况的绿色测试套件无法解决它们。每次解决都会记录其确认方式（`analyzer`/`test`/`human`）以及人工确认的 `approved_by` 信息。 > **请相应地设置期望值：** 语义风险规则类别列表很广泛（涵盖了 MISRA 的大部分 essential-type、control-flow 和 switch-statement 规则，以及 CERT 的 `INT`/`FLP` 系列），在实践中，典型 MISRA 发现的 `test_gated` 会话最终需要人工确认的频率几乎与 `human_gated` 会话相同。一个完整的端到端模拟确认了一个通过的测试套件自动解决了 **零** 个八个待定发现中的问题 —— 请参见 [BENCHMARK-SUITE-REPORT.md §3.2](BENCHMARK-SUITE-REPORT.md#32-the-gate-is-more-conservative-than-it-looks)。请相应地预算人工审查时间；不要指望 `test_gated` 会消除大部分审查负担。 ```bash maishac session begin src/ --verification-policy test_gated --test-command "make test" # ... 代理修复，然后： maishac session verify <id> # -> 如果修复需要签名，则进入 awaiting_verification 状态 maishac approve <fingerprint> --by lead@example.com ``` ## 团队与并发 项目内存存储在每个项目的 SQLite 文件 `.maishac/memory.db` 中。 - **忽略它。** 它是本地的、机器特定的状态，而不是源代码 —— 将 `.maishac/` 添加到 `.gitignore`（此仓库已经这样做了）。要故意共享状态，请导出 `compliance_report`（SARIF/JSON），而不是提交数据库。 - **并发访问。** 数据库在 WAL 模式下运行，并带有忙碌超时，因此 CI 扫描和本地会话可以读写而不会硬阻塞。`session begin` 拒绝在同一项目上已经存在活动会话时启动第二个会话（使用 `--force` 覆盖），因此两个运行不会竞争发现状态。 ## 开发 ```bash pip install -e . && python -m pytest tests/ -q ``` `examples/bad.c` 是一个故意不符合规范的示例，涵盖了大约 18 条规则 —— 作为演示目标非常有用。 ## 贡献 非常欢迎贡献，特别是对社区可扩展部分的贡献：添加编码标准 **规则**、作者 **模式**（符合规范的习惯用法）或 **分析器适配器** / SARIF 方言映射。这些都不涉及引擎。请参阅 [`CONTRIBUTING.md`](CONTRIBUTING.md) 以获取操作方法以及要保留的设计不变式，以及 [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)。在跟踪器上标记了“良好第一问题”。 ## 许可证 / 免责声明 规则摘要是原始的转述；MISRA®、BARR-C 和 SEI CERT C 是其各自所有者的财产。Maisha 输出并不构成正式的合规认证。