[PR #4482] feat(evidence): add evidence bundle audit command and MCP tool #6267

Open
opened 2026-10-31 01:13:09 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/4482
Author: @Jackzigen
Created: 10/16/2026
Status: 🔄 Open

Base: main ← Head: evidence-audit-command


📝 Commits (6)

  • 10eb834 feat(evidence): add evidence bundle audit command and MCP tool
  • 3c2892e fix(evidence-audit): tighten leak rules and cover caller-authored fields
  • 9390b5f fix(evidence-audit): restore EvidenceIntegrityError import after rebase
  • 6114ecd fix(evidence-audit): address review — key-side scanning, dedupe, docs
  • b7eb07d fix(evidence): address review findings on bundle audit leaks and paths
  • ecabdca fix(evidence): audit relationship coverage and analysis profile fields

📊 Changes

14 files changed (+1030 additions, -12 deletions)

View changed files

📝 package-lock.json (+0 -12)
📝 src/application/EvidenceBundleCommands.ts (+25 -0)
📝 src/cliCommandNames.ts (+1 -0)
📝 src/cliEvidenceCommands.ts (+16 -0)
📝 src/contracts/sessionToolContracts.ts (+6 -0)
📝 src/contracts/toolContractExamples.ts (+1 -0)
📝 src/contracts/toolEffects.ts (+1 -0)
📝 src/contracts/toolOutputSchemaGroups.ts (+2 -0)
➕ src/domain/evidenceAudit.test.ts (+327 -0)
➕ src/domain/evidenceAudit.ts (+484 -0)
➕ src/server/registerEvidenceAuditTool.ts (+58 -0)
📝 src/server/registerSessionTools.ts (+8 -0)
📝 tests/boundary/cli/cliToolCoverage.test.ts (+1 -0)
➕ tests/boundary/cli/evidenceAuditCommand.test.ts (+100 -0)

📄 Description

Summary

Adds a read-only audit for exported evidence bundles so contributors can check a bundle for credential/privacy leaks before attaching it to a public issue. Fixes #4398.

  • CLI: rea evidence-audit <path> [--json]
  • MCP: audit_evidence_bundle session tool (pure read, no session mutation, records no evidence)
  • Finds credential-shaped values (Bearer tokens, AWS keys, GitHub tokens, Stripe/Slack keys, private key blocks), local home paths, and Authorization header values; object keys are scanned too, and credential-shaped keys are reported at the parent pointer and redacted as <redacted-xxxxxxxx> in pointers
  • Free-form fields (limitations, notes, …) are scanned like any other string
  • Matching values are never printed — findings report length + short hash prefix only; pointers show masked keys
  • Rules are heuristics: false positives are possible and each failure needs human confirmation before acting

Problem and expected behavior

Users export evidence bundles from sessions to attach to public issues. A bundle can embed a credential or a home path, and nothing in main warns the contributor before they publish it. The audit gives a pre-publication check: it must never print the secret itself, must flag both credential values and credential-shaped object keys, and must stay a pure read with no session mutation.

Change and scope

  • New domain module src/domain/evidenceAudit.ts (scan rules, pointer building, sorting) plus evidenceAudit.test.ts
  • CLI wiring in src/cliEvidenceCommands.ts, application command in src/application/EvidenceBundleCommands.ts
  • MCP tool registered via src/server/registerEvidenceAuditTool.ts on the same application command (runDerivedOperation), with an absolute-path input schema matching the sibling compare_bundles tool

Follow the contribution scope: read-only audit within existing boundaries — no target execution, injection, mutation, or protection recovery, so no maintainer scope decision is required (not applicable).

Contract and boundary impact

  • Semantic owner and earliest changed stage: domain (evidence audit rules); CLI + MCP surface added downstream
  • Contribution scope fit and linked maintainer decision: read-only audit of already-exported bundles; no scope decision required — not applicable
  • CLI and MCP/tool-catalog contract: adds rea evidence-audit <path> [--json] and session tool audit_evidence_bundle; no existing command or tool changed
  • Provider, bridge, target-format, or platform compatibility: none — pure string/JSON analysis
  • Evidence, artifact, provenance, or reconstruction contract: no session mutation, no evidence recorded
  • Target selection, authority, upstream behavior, and cleanup details: not applicable
  • Generated metadata (docs/public/product-catalog.json), package, or installation impact: none (CI generates and validates; no generated output committed here)

Expected effects (check known effects; use documentation-only on its own).

  • Read existing files or captured data.
  • Launch or attach to a process.
  • Inject into a process or target.
  • Modify a target or its environment.
  • Send data over a network.
  • Modify this repository or workspace files.
  • none / documentation-only

Compatibility, safety, and release

  • Breaking changes or migration steps: none — purely additive
  • Real Hopper/Ghidra, browser, or OS coverage: not applicable — works on any exported bundle JSON
  • Package or release metadata impact: none
  • Security, privacy, process, or containment review: the tool itself is the security check; matched values are never printed (length + hash prefix only), pointers mask credential-shaped keys, and the report is safe to paste into a public issue. Rules are heuristics and false positives are possible; each failure requires human confirmation.

Author readiness

Human owner: @Jackzigen

  • I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
  • I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
  • I declare this PR ready for initial maintainer review.

Before merge

  • This PR addresses a concrete problem or an agreed enhancement.
  • Related issue is linked: Fixes #4398.
  • The PR has one focused outcome and the title follows type(scope): outcome.
  • Related review threads addressed in d7a5fc91 from the previous rounds have been addressed in d7a5fc91 (absolute path gate, key-side scanning, bearer/AWS regex tightening, runDerivedOperation, unknown dedupe, limitations scanning, heuristic warnings in code and docs).
  • Tests cover changed observable behavior and meaningful failure paths: src/domain/evidenceAudit.test.ts (299 tests across the audit suite); boundary CLI test tests/boundary/cli/evidenceAuditCommand.test.ts green locally.
  • Owning docs, contracts, and generated metadata are updated where needed.
  • User-visible CLI/MCP changes include representative output: rea evidence-audit bundle.json --json outputs findings with rule_id/pointer/length/hash prefix, never the matched value.
  • I checked the final diff for secrets, unrelated cleanup, and unsupported claims. No JWT detection is claimed (JWT rules are intentionally out of scope).

Local validation: npm run check:fast (typecheck + lint + targeted tests) passed; the full audit suite (299 tests) passes locally. Hosted CI runs on push. Note: local run of tests/acceptance/setup/opencodeV2ClientSetup.test.ts fails on this machine for environment reasons (no Ghidra installed, Node version below the required floor) — this is a pre-existing local-environment failure, not caused by this PR, and does not affect the audit code paths.


🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/4482 **Author:** [@Jackzigen](https://github.com/Jackzigen) **Created:** 10/16/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `evidence-audit-command` --- ### 📝 Commits (6) - [`10eb834`](https://github.com/morluto/rea/commit/10eb8340261ccdc9ec28c40d419d1fa4bf770dc3) feat(evidence): add evidence bundle audit command and MCP tool - [`3c2892e`](https://github.com/morluto/rea/commit/3c2892ecede6942144d0c3bc03ae330b0984756e) fix(evidence-audit): tighten leak rules and cover caller-authored fields - [`9390b5f`](https://github.com/morluto/rea/commit/9390b5f75a489e1a6989ffcff64581c1783532f2) fix(evidence-audit): restore EvidenceIntegrityError import after rebase - [`6114ecd`](https://github.com/morluto/rea/commit/6114ecdf2c02e021cd5edd051d4bfcdcc55a1fa6) fix(evidence-audit): address review — key-side scanning, dedupe, docs - [`b7eb07d`](https://github.com/morluto/rea/commit/b7eb07d010bd622f6a6edd3dabce9e8dc7034146) fix(evidence): address review findings on bundle audit leaks and paths - [`ecabdca`](https://github.com/morluto/rea/commit/ecabdcac2661f922f94c87361a5eff47257bed0f) fix(evidence): audit relationship coverage and analysis profile fields ### 📊 Changes **14 files changed** (+1030 additions, -12 deletions) <details> <summary>View changed files</summary> 📝 `package-lock.json` (+0 -12) 📝 `src/application/EvidenceBundleCommands.ts` (+25 -0) 📝 `src/cliCommandNames.ts` (+1 -0) 📝 `src/cliEvidenceCommands.ts` (+16 -0) 📝 `src/contracts/sessionToolContracts.ts` (+6 -0) 📝 `src/contracts/toolContractExamples.ts` (+1 -0) 📝 `src/contracts/toolEffects.ts` (+1 -0) 📝 `src/contracts/toolOutputSchemaGroups.ts` (+2 -0) ➕ `src/domain/evidenceAudit.test.ts` (+327 -0) ➕ `src/domain/evidenceAudit.ts` (+484 -0) ➕ `src/server/registerEvidenceAuditTool.ts` (+58 -0) 📝 `src/server/registerSessionTools.ts` (+8 -0) 📝 `tests/boundary/cli/cliToolCoverage.test.ts` (+1 -0) ➕ `tests/boundary/cli/evidenceAuditCommand.test.ts` (+100 -0) </details> ### 📄 Description ## Summary Adds a read-only audit for exported evidence bundles so contributors can check a bundle for credential/privacy leaks before attaching it to a public issue. Fixes #4398. - CLI: `rea evidence-audit <path> [--json]` - MCP: `audit_evidence_bundle` session tool (pure read, no session mutation, records no evidence) - Finds credential-shaped values (Bearer tokens, AWS keys, GitHub tokens, Stripe/Slack keys, private key blocks), local home paths, and `Authorization` header values; object keys are scanned too, and credential-shaped keys are reported at the parent pointer and redacted as `<redacted-xxxxxxxx>` in pointers - Free-form fields (`limitations`, `notes`, …) are scanned like any other string - Matching values are never printed — findings report length + short hash prefix only; pointers show masked keys - Rules are heuristics: false positives are possible and each failure needs human confirmation before acting ## Problem and expected behavior Users export evidence bundles from sessions to attach to public issues. A bundle can embed a credential or a home path, and nothing in main warns the contributor before they publish it. The audit gives a pre-publication check: it must never print the secret itself, must flag both credential values and credential-shaped object keys, and must stay a pure read with no session mutation. ## Change and scope - New domain module `src/domain/evidenceAudit.ts` (scan rules, pointer building, sorting) plus `evidenceAudit.test.ts` - CLI wiring in `src/cliEvidenceCommands.ts`, application command in `src/application/EvidenceBundleCommands.ts` - MCP tool registered via `src/server/registerEvidenceAuditTool.ts` on the same application command (`runDerivedOperation`), with an absolute-path input schema matching the sibling `compare_bundles` tool Follow the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope): read-only audit within existing boundaries — no target execution, injection, mutation, or protection recovery, so no maintainer scope decision is required (not applicable). ## Contract and boundary impact - Semantic owner and earliest changed stage: domain (evidence audit rules); CLI + MCP surface added downstream - Contribution scope fit and linked maintainer decision: read-only audit of already-exported bundles; no scope decision required — not applicable - CLI and MCP/tool-catalog contract: adds `rea evidence-audit <path> [--json]` and session tool `audit_evidence_bundle`; no existing command or tool changed - Provider, bridge, target-format, or platform compatibility: none — pure string/JSON analysis - Evidence, artifact, provenance, or reconstruction contract: no session mutation, no evidence recorded - Target selection, authority, upstream behavior, and cleanup details: not applicable - Generated metadata (`docs/public/product-catalog.json`), package, or installation impact: none (CI generates and validates; no generated output committed here) Expected effects (check known effects; use documentation-only on its own). - [x] Read existing files or captured data. - [ ] Launch or attach to a process. - [ ] Inject into a process or target. - [ ] Modify a target or its environment. - [ ] Send data over a network. - [ ] Modify this repository or workspace files. - [ ] none / documentation-only ## Compatibility, safety, and release - Breaking changes or migration steps: none — purely additive - Real Hopper/Ghidra, browser, or OS coverage: not applicable — works on any exported bundle JSON - Package or release metadata impact: none - Security, privacy, process, or containment review: the tool itself is the security check; matched values are never printed (length + hash prefix only), pointers mask credential-shaped keys, and the report is safe to paste into a public issue. Rules are heuristics and false positives are possible; each failure requires human confirmation. ## Author readiness Human owner: @Jackzigen - [x] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. ## Before merge - [x] This PR addresses a concrete problem or an agreed enhancement. - [x] Related issue is linked: Fixes #4398. - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related review threads addressed in `d7a5fc91` from the previous rounds have been addressed in `d7a5fc91` (absolute path gate, key-side scanning, bearer/AWS regex tightening, runDerivedOperation, unknown dedupe, limitations scanning, heuristic warnings in code and docs). - [x] Tests cover changed observable behavior and meaningful failure paths: `src/domain/evidenceAudit.test.ts` (299 tests across the audit suite); boundary CLI test `tests/boundary/cli/evidenceAuditCommand.test.ts` green locally. - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output: `rea evidence-audit bundle.json --json` outputs findings with rule_id/pointer/length/hash prefix, never the matched value. - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. No JWT detection is claimed (JWT rules are intentionally out of scope). --- **Local validation**: `npm run check:fast` (typecheck + lint + targeted tests) passed; the full audit suite (299 tests) passes locally. Hosted CI runs on push. Note: local run of `tests/acceptance/setup/opencodeV2ClientSetup.test.ts` fails on this machine for environment reasons (no Ghidra installed, Node version below the required floor) — this is a pre-existing local-environment failure, not caused by this PR, and does not affect the audit code paths. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
morluto/rea#6267
No description provided.