feat: MCP tool-call receipt signing integration

[Nishar Miya (miyannishar)]

Summary

Implements MCP tool-call receipt signing as a first-party AGT integration. Every MCP tool invocation optionally produces a signed governance receipt linking the Cedar policy decision to the tool call.

Closes #1501

Changes

AgentMesh Adapter (agentmesh-integrations/mcp-receipt-governed/)

• McpReceiptAdapter — wraps MCP tool calls with Cedar policy evaluation and receipt signing
• GovernanceReceipt — signed proof of a governance decision (JCS canonical JSON, Ed25519)
• CedarPolicyEvaluator — lightweight Cedar permit/forbid evaluator (uses agentmesh.governance.cedar when available, inline fallback otherwise)
• ReceiptStore — in-memory audit trail with query by agent/tool/decision

Example (examples/mcp-receipt-governed/)

• Self-contained demo with Cedar policy file showing 7 tool calls across 2 agents
• Sample output shows allow/deny decisions with signed, verified receipts

Quickstart (examples/quickstart/mcp_receipts_in_60_seconds.py)

• ~45-line script demonstrating governed MCP tool calls with receipt output

Design Decisions

• Zero required dependencies — works with stdlib only; Ed25519 via optional cryptography extra
• HMAC-SHA256 fallback — environments without cryptography still get signed receipts (with a warning)
• Follows existing patterns — mirrors template-agentmesh and mcp-trust-proxy structure
• Default deny — empty or unmatched Cedar policies deny by default

Testing

44 unit tests covering:

• Cedar policy evaluation (allow, deny, default-deny, catch-all)
• Receipt metadata (policy ID, agent DID, tool name, args hash, timestamps)
• Ed25519 sign/verify round-trip and tamper detection
• govern_and_execute lifecycle (allowed executes, denied blocks, exceptions captured)
• ReceiptStore query, export, stats, and shared store

44 passed in 0.10s

[github-actions]

Welcome to the Agent Governance Toolkit! Thanks for your first pull request.
Please ensure tests pass, code follows style (ruff check), and you have signed the CLA.
See our Contributing Guide.

[github-actions]

🤖 AI Agent: code-reviewer

Review Summary

This PR introduces the McpReceiptAdapter for wrapping MCP tool calls with Cedar policy evaluation and governance receipt signing. The implementation is well-structured, aligns with existing patterns in the repository, and includes comprehensive test coverage. However, there are several areas of concern and opportunities for improvement, particularly around security, thread safety, and type safety.

---

🔴 CRITICAL: Security Issues

1. HMAC-SHA256 Fallback for Receipt Signing

   • The fallback to HMAC-SHA256 when the cryptography library is unavailable is problematic. HMAC-SHA256 does not provide the same level of security guarantees as Ed25519 for non-repudiation. HMAC is symmetric, meaning the same key is used for signing and verification, which undermines the purpose of a cryptographic signature in this context.
   • Recommendation: Remove the HMAC-SHA256 fallback entirely. Instead, enforce the use of the cryptography library for Ed25519 signing. If the library is unavailable, raise an exception and fail securely.

2. Error Handling in Receipt Signing

   • The sign_receipt method catches all exceptions (except Exception as exc) and logs an error, but it still proceeds to store the receipt with an error field. This could lead to a false sense of security, as the receipt is stored even if it is not properly signed.
   • Recommendation: If signing fails, do not store the receipt. Instead, raise an exception or return an error to the caller.

3. Policy Evaluation Fallback

   • The CedarPolicyEvaluator falls back to a custom inline parser if the agentmesh.governance.cedar module is unavailable. This inline parser is simplistic and may not handle complex Cedar policies correctly, leading to potential false negatives (security bypass).
   • Recommendation: Remove the inline fallback and make the agentmesh.governance.cedar module a required dependency. If the module is unavailable, raise an exception and fail securely.

4. Receipt Verification

   • The verify_receipt method logs a warning when attempting to verify HMAC-signed receipts but does not raise an error. This could lead to confusion or misuse.
   • Recommendation: Explicitly raise an exception when attempting to verify HMAC-signed receipts, as they cannot be verified without the private key.

---

🟡 WARNING: Potential Breaking Changes

1. Default Deny Behavior

   • The CedarPolicyEvaluator enforces a "default deny" policy if no explicit permit rule matches. While this is a secure default, it may break existing workflows if users expect a different default behavior.
   • Recommendation: Clearly document this behavior in the release notes and provide a configuration option to override the default deny behavior if needed.

2. Python Version Requirement

   • The pyproject.toml specifies requires-python = ">=3.11". This is a breaking change for users on Python 3.9 or 3.10, which are listed as supported in the repository's README.
   • Recommendation: Update the README to reflect the new minimum Python version or adjust the pyproject.toml to maintain compatibility with Python 3.9 and 3.10.

---

💡 Suggestions for Improvement

1. Thread Safety

   • The ReceiptStore class is not thread-safe, as it uses a standard list for storing receipts without any synchronization mechanisms. This could lead to race conditions in concurrent environments.
   • Recommendation: Use a thread-safe data structure (e.g., queue.Queue) or add thread locks to ensure safe concurrent access.

2. Type Safety

   • The McpReceiptAdapter.govern_tool_call and McpReceiptAdapter.govern_and_execute methods use Optional[Dict[str, Any]] for tool_args, but the type hint does not enforce immutability. Since tool_args is hashed, it should be immutable to prevent accidental modification.
   • Recommendation: Use Optional[Mapping[str, Any]] instead of Optional[Dict[str, Any]] to enforce immutability.

3. Error Handling in govern_and_execute

   • The govern_and_execute method logs errors during tool execution but does not propagate them. This could make debugging difficult.
   • Recommendation: Consider re-raising the exception after logging it, or provide an option to propagate the exception to the caller.

4. Logging

   • The logging messages are useful but could benefit from additional context, such as the agent_did and tool_name, to make debugging easier.
   • Recommendation: Include more contextual information in log messages, especially for errors.

5. Testing Edge Cases

   • While the test coverage is comprehensive, it is unclear if edge cases (e.g., malformed policies, invalid Ed25519 keys, or corrupted receipts) are thoroughly tested.
   • Recommendation: Add tests for edge cases, including:
     • Invalid or malformed Cedar policies.
     • Invalid or malformed Ed25519 keys.
     • Corrupted or tampered receipts.
     • Concurrent access to ReceiptStore.

6. Documentation

   • The documentation is clear and well-written, but it could benefit from additional details on certain topics.
   • Recommendation: Expand the documentation to include:
     • A detailed explanation of the security implications of using HMAC-SHA256 as a fallback.
     • Examples of complex Cedar policies and their expected behavior.
     • Guidance on how to handle errors during receipt signing and tool execution.

7. Backward Compatibility

   • The McpReceiptAdapter introduces new functionality, but it is unclear if it integrates seamlessly with existing components in the agentmesh package.
   • Recommendation: Test the integration of McpReceiptAdapter with other components in the agentmesh package to ensure backward compatibility.

---

Final Assessment

• Strengths:

  • Well-structured and modular implementation.
  • Comprehensive test coverage for core functionality.
  • Adherence to existing patterns in the repository.

• Weaknesses:

  • Security concerns with HMAC-SHA256 fallback and inline policy evaluation.
  • Potential thread safety issues in ReceiptStore.
  • Lack of clarity on backward compatibility with existing components.

By addressing the critical security issues and implementing the suggested improvements, this PR can be made more robust and secure.

[github-actions]

🤖 AI Agent: security-scanner — Security Review of `feat: MCP tool-call receipt signing integration`

Security Review of feat: MCP tool-call receipt signing integration

This pull request introduces the McpReceiptAdapter for wrapping MCP tool calls with Cedar policy evaluation and governance receipt signing. The implementation appears well-structured and adheres to the existing patterns in the repository. However, given the critical nature of this library, a thorough security review is necessary.

---

Findings

1. Prompt Injection Defense Bypass

Rating: 🔴 CRITICAL
Issue: The CedarPolicyEvaluator's inline fallback parser uses regex to evaluate policies. This approach is prone to injection attacks, as the regex-based parsing is not robust against maliciously crafted policies or actions. For example, an attacker could craft an action string that manipulates the regex to bypass policy checks.
Attack Vector: An attacker could craft a tool_name or action string that exploits the regex patterns in _evaluate_inline to bypass policy restrictions. For example, an action string like Action::"DeleteFile"; permit(principal, action, resource); could potentially match the catch-all permit rule, bypassing the intended policy.
Recommendation: Remove the inline regex-based fallback entirely and enforce the use of a robust, well-tested Cedar policy evaluator (e.g., agentmesh.governance.cedar.CedarEvaluator). If the dependency is unavailable, fail securely by denying all actions instead of falling back to a potentially insecure implementation.

---

2. Policy Engine Circumvention

Rating: 🟠 HIGH
Issue: The CedarPolicyEvaluator does not validate the structure or syntax of the provided cedar_policy. If an invalid policy is loaded, the inline fallback may behave unpredictably, potentially allowing unintended actions.
Attack Vector: An attacker could inject a malformed or incomplete policy that bypasses the intended access controls. For example, a policy missing a forbid rule might inadvertently allow sensitive actions.
Recommendation: Validate the policy syntax during initialization using a trusted Cedar parser. Reject invalid policies and log an error. Additionally, consider implementing a "dry-run" mode to test policies before deployment.

---

3. Trust Chain Weaknesses

Rating: 🟠 HIGH
Issue: The sign_receipt function does not validate the provided private_key_hex for length or format. If an invalid key is used, the receipt signature may be incorrect or fail silently. Additionally, the fallback to HMAC-SHA256 for signing is not cryptographically equivalent to Ed25519 and may weaken trust in the receipts.
Attack Vector: An attacker could provide a malformed or weak signing key, resulting in unverifiable or insecure receipts. If HMAC-SHA256 is used, the receipts may not provide the same level of non-repudiation as Ed25519.
Recommendation:

• Validate the private_key_hex for length (32 bytes) and format (hexadecimal).
• Remove the HMAC-SHA256 fallback and require cryptography as a mandatory dependency to ensure strong cryptographic guarantees.

---

4. Credential Exposure

Rating: 🟡 MEDIUM
Issue: The signing_key_hex is passed as a plaintext string during the initialization of McpReceiptAdapter. If this key is logged or exposed in error messages, it could be compromised.
Attack Vector: If logging is not properly sanitized, the signing key could be exposed in logs or error messages, allowing an attacker to forge receipts.
Recommendation:

• Avoid logging the signing_key_hex or any sensitive data.
• Consider using a secure secrets management solution to store and retrieve the signing key, rather than passing it directly as a parameter.

---

5. Sandbox Escape

Rating: 🔵 LOW
Issue: The govern_and_execute method executes arbitrary functions (tool_fn) with user-provided arguments (tool_args). While this is expected behavior, it could be exploited if an attacker gains control over the tool_fn or tool_args.
Attack Vector: If an attacker can inject malicious code into tool_fn or tool_args, they could execute arbitrary code within the process.
Recommendation: Ensure that tool_fn and tool_args are sanitized and validated before execution. Consider running tool calls in a sandboxed environment to limit potential damage from malicious code.

---

6. Deserialization Attacks

Rating: 🔵 LOW
Issue: The hash_tool_args function uses json.dumps to serialize tool_args for hashing. While this is generally safe, it assumes that tool_args is always a dictionary. If a non-dictionary object is passed, it could lead to unexpected behavior or errors.
Attack Vector: An attacker could pass a non-dictionary object (e.g., a custom object with a malicious __str__ method) as tool_args, potentially causing unexpected behavior.
Recommendation: Validate that tool_args is a dictionary before attempting to serialize it. Use isinstance(tool_args, dict) to ensure type safety.

---

7. Race Conditions

Rating: 🔵 LOW
Issue: The ReceiptStore class is not thread-safe. If multiple threads attempt to add or query receipts simultaneously, it could lead to data corruption or inconsistent results.
Attack Vector: In a multi-threaded environment, concurrent access to _receipts could result in race conditions, leading to lost or corrupted receipts.
Recommendation: Use a thread-safe data structure (e.g., queue.Queue) or add thread synchronization (e.g., threading.Lock) to protect access to _receipts.

---

8. Supply Chain Risks

Rating: 🟡 MEDIUM
Issue: The cryptography library is an optional dependency. This introduces a risk of dependency confusion or typosquatting attacks if a malicious package with a similar name is introduced.
Attack Vector: An attacker could publish a malicious package with a name similar to cryptography, which might be inadvertently installed by users.
Recommendation:

• Make cryptography a required dependency to ensure consistent behavior and strong cryptographic guarantees.
• Use dependency pinning or hash-based verification (e.g., pip-tools or pip-compile) to prevent dependency confusion attacks.

---

Summary of Findings

Finding	Rating	Recommendation
Prompt Injection Defense Bypass	🔴 CRITICAL	Remove regex-based policy evaluation fallback. Enforce use of a robust Cedar parser.
Policy Engine Circumvention	🟠 HIGH	Validate policy syntax and reject invalid policies.
Trust Chain Weaknesses	🟠 HIGH	Validate signing key format and remove HMAC-SHA256 fallback.
Credential Exposure	🟡 MEDIUM	Avoid logging sensitive data; use secure secrets management.
Sandbox Escape	🔵 LOW	Sanitize and validate tool_fn and tool_args.
Deserialization Attacks	🔵 LOW	Validate tool_args type before serialization.
Race Conditions	🔵 LOW	Use thread-safe structures or synchronization for ReceiptStore.
Supply Chain Risks	🟡 MEDIUM	Make cryptography a required dependency and pin versions.

---

Final Recommendations

1. Critical Fixes: Address the prompt injection defense bypass and policy engine circumvention issues immediately. These are critical vulnerabilities that could compromise the entire governance framework.
2. High Priority: Strengthen the trust chain by enforcing proper key validation and removing the HMAC-SHA256 fallback.
3. Medium Priority: Secure the signing key and dependencies to prevent credential exposure and supply chain attacks.
4. Low Priority: Address sandbox escape, deserialization, and race condition issues to improve overall robustness.

This pull request introduces valuable functionality, but the identified security issues must be addressed to ensure the integrity and reliability of the governance framework.

[github-actions]

🤖 AI Agent: code-reviewer

Pull Request Review: feat: MCP tool-call receipt signing integration

Summary

This PR introduces the McpReceiptAdapter for wrapping MCP tool calls with Cedar policy evaluation and governance receipt signing. The implementation includes a lightweight Cedar policy evaluator, a receipt signing mechanism using Ed25519 (with an HMAC-SHA256 fallback), and an in-memory receipt store for audit trails. The PR also includes comprehensive tests and examples.

---

Review Feedback

🔴 CRITICAL: Security Issues

1. Ed25519 Key Handling:

   • The signing_key_hex is passed as a plain string to the McpReceiptAdapter constructor. This approach is insecure as it exposes the private key in memory and logs.
   • Recommendation: Use a secure key management solution (e.g., Azure Key Vault, AWS KMS) to store and retrieve the private key securely. Avoid passing sensitive data as plain strings.

2. HMAC-SHA256 Fallback:

   • The fallback to HMAC-SHA256 for signing receipts in environments without the cryptography library is problematic. HMAC-SHA256 does not provide the same level of security as Ed25519 for non-repudiation.
   • Recommendation: Either make the cryptography library a required dependency or explicitly document the security trade-offs of using HMAC-SHA256. Consider raising an exception if cryptography is unavailable, as this could lead to a false sense of security.

3. Inline Cedar Policy Parsing:

   • The inline Cedar policy evaluator uses regular expressions to parse and evaluate policies. This approach is error-prone and may lead to false negatives, allowing unauthorized actions.
   • Recommendation: Remove the inline evaluator and make the agentmesh.governance.cedar dependency mandatory. If this is not feasible, ensure the inline evaluator is thoroughly tested with edge cases and complex policies.

4. ReceiptStore Thread Safety:

   • The ReceiptStore class is not thread-safe. The _receipts list is directly modified without synchronization, which can lead to race conditions in concurrent environments.
   • Recommendation: Use thread-safe data structures (e.g., queue.Queue) or implement locking mechanisms (e.g., threading.Lock) to ensure thread safety.

5. Receipt Verification:

   • The verify_receipt function does not raise an exception or log detailed errors when verification fails. This could make debugging and auditing difficult.
   • Recommendation: Log detailed error messages when verification fails, including the reason for failure (e.g., invalid signature, missing fields).

---

🟡 WARNING: Potential Breaking Changes

1. Backward Compatibility:

   • The McpReceiptAdapter introduces a new feature but does not appear to modify existing APIs. However, the use of agentmesh.governance.cedar as an optional dependency could lead to runtime errors if the library is not installed.
   • Recommendation: Clearly document the requirement for agentmesh.governance.cedar in the README and consider adding a check during initialization to provide a more user-friendly error message.

2. Python Version Requirement:

   • The pyproject.toml specifies requires-python = ">=3.11". This is a breaking change for users on Python 3.9 or 3.10.
   • Recommendation: If possible, test and support Python 3.9 and 3.10 to maintain compatibility with the project's stated stack.

---

💡 Suggestions for Improvement

1. Logging:

   • The logging in CedarPolicyEvaluator and McpReceiptAdapter is minimal. For example, the inline evaluator does not log the policy evaluation result.
   • Recommendation: Add more granular logging for policy evaluation results, receipt creation, and signing/verification steps.

2. Error Handling:

   • The govern_and_execute method captures exceptions during tool execution but does not propagate them. This could lead to silent failures.
   • Recommendation: Consider re-raising exceptions or providing an option to propagate them to the caller.

3. Testing Coverage:

   • While the PR mentions 44 unit tests, it is unclear if edge cases (e.g., malformed policies, invalid signatures, concurrent receipt store access) are covered.
   • Recommendation: Add tests for edge cases, including:
     • Invalid or malformed Cedar policies.
     • Concurrent access to ReceiptStore.
     • Receipt verification with tampered payloads or signatures.

4. Documentation:

   • The README provides a good overview but lacks details on security trade-offs (e.g., HMAC-SHA256 fallback) and thread safety.
   • Recommendation: Expand the README to include:
     • Security considerations for key handling and signing.
     • Thread safety guarantees and limitations of ReceiptStore.

5. Type Safety:

   • The McpReceiptAdapter and GovernanceReceipt classes lack type annotations for some arguments and return values (e.g., tool_args in govern_tool_call).
   • Recommendation: Add type annotations to all methods and attributes to improve type safety and developer experience.

6. Canonical JSON Implementation:

   • The canonical_payload method uses json.dumps with sort_keys=True and separators=(",", ":") to generate canonical JSON. While this is a common approach, it may not fully comply with the JCS (JSON Canonicalization Scheme) standard.
   • Recommendation: Consider using a dedicated library for JCS-compliant canonical JSON serialization, such as canonicaljson.

7. ReceiptStore Scalability:

   • The ReceiptStore is an in-memory store, which may not scale well for large numbers of receipts.
   • Recommendation: Consider adding support for pluggable storage backends (e.g., SQLite, Redis) for production use cases.

8. Default Deny Behavior:

   • The default deny behavior is a good security practice, but it might lead to unexpected results if users are unaware of it.
   • Recommendation: Add a warning or log message when a policy evaluation results in a default deny decision.

---

Summary of Feedback

• Critical Issues:

  • 🔴 Secure key handling for Ed25519 private keys.
  • 🔴 HMAC-SHA256 fallback introduces weaker security guarantees.
  • 🔴 Inline Cedar policy evaluator is error-prone and may lead to false negatives.
  • 🔴 ReceiptStore is not thread-safe.
  • 🔴 Receipt verification lacks detailed error logging.

• Warnings:

  • 🟡 Potential backward compatibility issues due to Python 3.11 requirement.
  • 🟡 Optional dependency on agentmesh.governance.cedar could cause runtime errors.

• Suggestions:

  • 💡 Improve logging for debugging and auditing.
  • 💡 Enhance error handling in govern_and_execute.
  • 💡 Add tests for edge cases and concurrency.
  • 💡 Expand documentation to cover security and thread safety considerations.
  • 💡 Use a JCS-compliant library for canonical JSON serialization.
  • 💡 Consider scalable storage options for ReceiptStore.
  • 💡 Log warnings for default deny decisions.

---

Please address the critical issues before merging this PR. The warnings and suggestions should also be considered to improve the robustness, security, and usability of the feature. Let me know if you need further clarification or assistance!

[Nishar Miya (miyannishar)]

Addressed the critical findings from the automated security and code reviews in commit d384276:

1. HMAC-SHA256 fallback removed — sign_receipt now requires the cryptography library for Ed25519 signing. No more symmetric fallback that undermines non-repudiation.
2. Error logging sanitized — exception messages in the adapter now only log type(exc).__name__, preventing potential key material leakage.
3. Dependency pinned — cryptography>=41.0,<45.0 bounded to mitigate dependency confusion.

Remaining findings (inline Cedar fallback, ReceiptStore thread safety, JCS compliance, pluggable backends) are either fail-safe by design (default deny) or out of scope for a first integration — happy to address in follow-up PRs if needed.

All 44 tests continue to pass.

[Imran Siddique (imran-siddique)]

Well-structured integration with 44 tests. Good that HMAC fallback was removed. Closes #1501.