feat(examples): protect-mcp governed example — Cedar policies + signed receipts

[TJF (tomjwxf)]

Summary

Adds a governed example for the scopeblind-protect-mcp integration merged in #667, following the same pattern as openai-agents-governed, crewai-governed, and smolagents-governed.

What's included

examples/protect-mcp-governed/ — full governed example with 8 scenarios:

Scenario	What it demonstrates
Cedar Policy Evaluation	Tool calls evaluated against Cedar policies
Cedar Deny Is Authoritative	Cedar deny overrides trust scores (even trust=999)
Receipt Tamper Detection	Tampering with a receipt invalidates the signature
Spending Authority	Financial tool calls checked against limits
Receipt Chain Integrity	Hash-linked chain detects insertions/deletions
Trust Tier Mapping	Cedar tiers map to AGT trust score adjustments
Offline Verification	Receipts verified without network, using npx @veritasacta/verify
Full Governed Pipeline	5-tool pipeline with governance at every step

examples/quickstart/protect_mcp_governed.py — 30-line quickstart showing sign + verify + tamper detection.

Design decisions

• Runs standalone with zero dependencies. Inline signing fallback (SHA-256 HMAC) when agent-governance-toolkit and scopeblind-protect-mcp are not installed. Uses full adapter when available.
• 8 scenarios match the pattern from openai-agents-governed (which has 9 scenarios).
• DCO signed. CLA previously signed for feat: ScopeBlind protect-mcp integration — Cedar policy enforcement + verifiable receipts #667.

Testing

python examples/protect-mcp-governed/getting_started.py
# 16 receipts signed, all verified, tamper detected, chain intact

python examples/quickstart/protect_mcp_governed.py
# 3 receipts: allow, tamper detection, deny

Both scripts exit 0 with correct output.

Relationship to #667

PR #667 added the scopeblind-protect-mcp integration package with 5 components and 50+ tests. This PR adds the governed example and quickstart that show developers how to USE it — completing the pattern that every other major integration (OpenAI Agents, CrewAI, smolagents) already has.

Closes #1157.

[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

Code Review for feat(examples): protect-mcp governed example — Cedar policies + signed receipts

---

🔴 CRITICAL: Security Issues

1. Inline Fallback Using SHA-256 HMAC for Receipt Signing

   • The fallback implementation in the absence of scopeblind-protect-mcp uses SHA-256 HMAC for signing receipts. While this is acceptable for demonstration purposes, it is not cryptographically equivalent to Ed25519. This fallback could lead to developers mistakenly deploying insecure configurations in production.
   • Actionable Fix: Add explicit warnings in the code and documentation that the fallback is for demonstration purposes only and should never be used in production. Consider raising a runtime exception if the fallback is used in non-development environments.

   if not HAS_SCOPEBLIND:
       print("⚠  scopeblind-protect-mcp not installed — using inline fallback")
       if os.getenv("ENV") != "development":
           raise RuntimeError("Inline fallback is insecure and should not be used in production.")

2. Receipt Replay Protection

   • The current implementation does not include a mechanism to prevent replay attacks. While receipts are hash-chained, there is no explicit nonce or timestamp validation to ensure that a receipt cannot be reused maliciously.
   • Actionable Fix: Introduce a nonce or timestamp validation mechanism to detect and reject replayed receipts. This can be implemented in the ReceiptVerifier class or as part of the AuditLog integrity checks.

3. Receipt Chain Integrity

   • The receipt chain integrity check relies on the parent_receipt_hash field but does not validate the entire chain against tampering. If an attacker modifies multiple receipts in the chain, the current implementation may fail to detect it.
   • Actionable Fix: Implement a Merkle tree-based integrity check for the receipt chain to ensure that tampering with any part of the chain is detectable.

4. Thread Safety in Receipt Chain

   • The receipt_chain is a global list that is not thread-safe. Concurrent access to this list could lead to race conditions, especially in multi-threaded environments.
   • Actionable Fix: Use a thread-safe data structure like queue.Queue or protect access to receipt_chain with a threading lock.

---

🟡 WARNING: Potential Breaking Changes

1. Backward Compatibility with Existing Examples

   • The new example introduces a dependency on scopeblind-protect-mcp, which may not be installed in environments where previous examples were used. This could break existing workflows.
   • Actionable Fix: Clearly document the new dependency and provide installation instructions. Alternatively, provide a flag to disable the new functionality for users who do not wish to install the dependency.

2. Cedar Policy Compatibility

   • The example assumes a specific structure for Cedar policies. If users have existing policies that do not conform to this structure, they may encounter errors.
   • Actionable Fix: Provide a migration guide or validation tool to help users adapt their existing policies to the new structure.

---

💡 Suggestions for Improvement

1. Documentation Enhancements

   • The documentation is comprehensive but could benefit from a clear distinction between production-grade features and demonstration-only features. For example, explicitly label the inline fallback as "DEMO ONLY."
   • Include a section on best practices for securing the signing key (e.g., using a hardware security module or secure key management service).

2. Error Handling

   • The code currently prints warnings when dependencies are missing but does not provide actionable guidance on how to resolve these issues.
   • Suggestion: Use logging instead of print statements and include detailed error messages with links to installation instructions.

3. Type Annotations

   • While the code includes some type annotations, they are not comprehensive. For example, the scopeblind_context function and the ReceiptVerifier methods lack type hints.
   • Actionable Fix: Add type annotations to all functions and methods to improve code readability and maintainability.

4. Unit Tests

   • While the example includes scenarios for testing, these are not integrated into the pytest framework used in the repository.
   • Actionable Fix: Convert the scenarios into formal unit tests using pytest. This will ensure that the examples are automatically tested as part of the CI/CD pipeline.

5. Policy Evaluation Logging

   • The example does not include logging for policy evaluation results. This could make it difficult to debug issues in production.
   • Actionable Fix: Add logging statements to capture the results of policy evaluations, including the policy ID, decision, and any conditions that were evaluated.

6. Offline Verification CLI

   • The example mentions the npx @veritasacta/verify CLI for offline verification but does not provide a Python-based alternative.
   • Suggestion: Include a Python script or function for offline verification to avoid requiring Node.js in Python-only environments.

---

Summary of Recommendations

• Critical Fixes:

  • Warn against using the SHA-256 HMAC fallback in production.
  • Add replay protection for receipts.
  • Enhance receipt chain integrity checks.
  • Ensure thread safety for the receipt_chain.

• Warnings:

  • Document potential breaking changes due to new dependencies and policy structures.

• Suggestions:

  • Improve documentation and error handling.
  • Add comprehensive type annotations.
  • Convert scenarios into pytest tests.
  • Include logging for policy evaluations.
  • Provide a Python-based offline verification tool.

By addressing these issues, the example will be more secure, robust, and user-friendly, aligning with the repository's focus on security and governance.

[github-actions]

🤖 AI Agent: security-scanner — Security Review of PR: `feat(examples): protect-mcp governed example — Cedar policies + signed receipts`

Security Review of PR: feat(examples): protect-mcp governed example — Cedar policies + signed receipts

This PR introduces a governed example for the scopeblind-protect-mcp integration, showcasing the use of Cedar policies, signed receipts, and governance layers. Below is a detailed security analysis based on the critical criteria provided.

---

Findings

1. Prompt Injection Defense Bypass

• Risk: No direct prompt injection vulnerabilities were identified in this PR. However, the example policies (mcp-tool-access.yaml) and the inline fallback implementation rely on trust tiers and predefined rules. If an attacker can manipulate the context.trust_tier or bypass policy evaluation, they could potentially execute unauthorized actions.
• Rating: 🔵 LOW
• Attack Vector: An attacker could craft input that misrepresents the trust_tier or exploits gaps in policy enforcement to bypass restrictions.
• Recommendation: Ensure robust validation of context.trust_tier and other inputs before policy evaluation. Consider adding unit tests to simulate edge cases where trust tiers are manipulated.

---

2. Policy Engine Circumvention

• Risk: The Cedar policy engine is authoritative, but the fallback implementation uses SHA-256 HMAC for receipt signing instead of Ed25519. This fallback is less secure and could be exploited to forge receipts or bypass policy enforcement.
• Rating: 🟠 HIGH
• Attack Vector: An attacker could exploit the weaker fallback signature mechanism to forge receipts and bypass governance checks.
• Recommendation: Remove or restrict the fallback implementation to non-production environments. Ensure Ed25519 signing is mandatory for production use.

---

3. Trust Chain Weaknesses

• Risk: The receipt chain integrity mechanism relies on hash-linking receipts. While this provides tamper detection, the fallback implementation does not use cryptographic Merkle trees or SPIFFE/SVID for identity validation, which could weaken trust guarantees.
• Rating: 🟠 HIGH
• Attack Vector: An attacker could inject fake receipts into the chain or manipulate the hash-linking mechanism to compromise integrity.
• Recommendation: Use cryptographic Merkle trees for receipt chain integrity. Integrate SPIFFE/SVID for agent identity validation and trust establishment.

---

4. Credential Exposure

• Risk: The demo signing key (DEMO_KEY) is hardcoded in the example (getting_started.py). While this is acceptable for demonstration purposes, it could lead to accidental exposure in production if not properly isolated.
• Rating: 🔴 CRITICAL
• Attack Vector: If the hardcoded key is accidentally used in production, it could allow attackers to forge receipts and bypass governance.
• Recommendation: Replace the hardcoded key with a secure key management solution (e.g., AWS KMS, Azure Key Vault). Ensure keys are never hardcoded in source code.

---

5. Sandbox Escape

• Risk: No sandboxing mechanisms were explicitly mentioned in the PR. If the governed tools (e.g., shell_exec) are executed without proper isolation, they could lead to sandbox escapes.
• Rating: 🟠 HIGH
• Attack Vector: An attacker could exploit tools like shell_exec to execute arbitrary code outside the intended sandbox.
• Recommendation: Ensure all tool calls are executed in isolated environments (e.g., containers, VMs). Add explicit sandboxing mechanisms to the governance layer.

---

6. Deserialization Attacks

• Risk: The receipt canonicalization and signing process involves JSON serialization. While no unsafe deserialization was identified, improper handling of JSON inputs could lead to vulnerabilities.
• Rating: 🟡 MEDIUM
• Attack Vector: Maliciously crafted JSON inputs could exploit weaknesses in the receipt verification process.
• Recommendation: Use strict JSON schema validation for all inputs and outputs. Ensure canonicalization is robust and resistant to manipulation.

---

7. Race Conditions

• Risk: The governance pipeline involves concurrent evaluations (e.g., SpendingGate, CedarPolicyBridge). If these components are not thread-safe, race conditions could occur.
• Rating: 🟡 MEDIUM
• Attack Vector: An attacker could exploit timing issues to bypass spending limits or policy checks.
• Recommendation: Ensure all governance components are thread-safe. Add tests for concurrent access scenarios.

---

8. Supply Chain

• Risk: The PR relies on external dependencies (scopeblind_protect_mcp, agent-governance-toolkit, @veritasacta/verify). If these dependencies are compromised (e.g., via dependency confusion or typosquatting), the entire governance layer could be bypassed.
• Rating: 🔴 CRITICAL
• Attack Vector: An attacker could publish a malicious package with a similar name to one of the dependencies, leading to supply chain compromise.
• Recommendation: Pin dependency versions and verify their integrity using checksums. Use a package registry with strict security controls (e.g., GitHub Packages).

---

Summary of Findings

Category	Rating	Recommendation
Prompt Injection Defense	🔵 LOW	Validate context.trust_tier and add tests for edge cases.
Policy Engine Circumvention	🟠 HIGH	Remove fallback signing or restrict it to non-production environments.
Trust Chain Weaknesses	🟠 HIGH	Use Merkle trees and SPIFFE/SVID for stronger trust guarantees.
Credential Exposure	🔴 CRITICAL	Replace hardcoded keys with secure key management solutions.
Sandbox Escape	🟠 HIGH	Add explicit sandboxing mechanisms for tool calls.
Deserialization Attacks	🟡 MEDIUM	Use strict JSON schema validation for all inputs and outputs.
Race Conditions	🟡 MEDIUM	Ensure thread safety and test for concurrent access scenarios.
Supply Chain	🔴 CRITICAL	Pin dependency versions and verify their integrity using checksums.

---

Actionable Recommendations

1. Mandatory Ed25519 Signing: Remove the SHA-256 HMAC fallback or restrict it to non-production environments.
2. Secure Key Management: Replace hardcoded keys with a secure key management solution.
3. Trust Chain Hardening: Use Merkle trees and SPIFFE/SVID for stronger trust guarantees.
4. Dependency Security: Pin dependency versions and verify their integrity using checksums.
5. Sandboxing: Ensure all tool calls are executed in isolated environments.
6. Thread Safety: Audit governance components for thread safety and add tests for concurrent scenarios.
7. JSON Validation: Use strict JSON schema validation for all inputs and outputs.

---

Final Rating: 🟠 HIGH

While the PR introduces valuable governance features, several critical issues (e.g., credential exposure, supply chain risks) must be addressed to ensure robust security.

[github-actions]

🤖 AI Agent: code-reviewer

Review Summary

This pull request introduces a governed example for the scopeblind-protect-mcp integration, showcasing the use of Cedar policies, Ed25519-signed receipts, and other governance mechanisms. The example is well-structured, with clear documentation, a quickstart script, and a comprehensive set of scenarios that demonstrate the integration's capabilities. However, there are several areas where improvements can be made, particularly in terms of security, type safety, and thread safety.

---

🔴 CRITICAL: Security Issues

1. Inline Fallback Uses Weak Cryptography

   • The fallback implementation of Receipt.sign and Receipt.verify uses SHA-256 HMAC instead of Ed25519 for signing and verification. While this is acceptable for demonstration purposes, it is critical to ensure that this fallback is not used in production.
   • Recommendation: Add a clear warning in the documentation and code comments that the fallback implementation is for demonstration purposes only and should not be used in production. Consider adding a runtime check to explicitly prevent the fallback from being used in production environments.

2. Receipt Chain Integrity Validation

   • The receipt chain integrity check in scenario_5_receipt_chain_integrity only validates the hash linkage between receipts but does not ensure the chronological order of timestamps. This could allow an attacker to reorder receipts in the chain without detection.
   • Recommendation: Add a check to ensure that the timestamps of receipts in the chain are strictly increasing.

3. Replay Protection

   • The example does not include a mechanism for detecting replay attacks, where a valid receipt is reused maliciously.
   • Recommendation: Implement a nonce or timestamp-based mechanism to detect and reject replayed receipts.

4. Key Management

   • The demo signing key (DEMO_KEY) is hardcoded in the example. While this is acceptable for demonstration purposes, it sets a bad precedent for developers who might copy this code into production.
   • Recommendation: Add a clear warning in the documentation and code comments that the demo key is for demonstration purposes only. Provide guidance on securely generating and managing keys in production.

---

🟡 WARNING: Potential Breaking Changes

1. Backward Compatibility with Existing Examples
   • This PR introduces a new governed example that follows the pattern of existing examples (openai-agents-governed, crewai-governed, etc.). However, the inline fallback implementation may lead to inconsistencies if developers expect the same behavior across all examples.
   • Recommendation: Ensure that all governed examples use consistent patterns and implementations. If the inline fallback is unique to this example, document this clearly to avoid confusion.

---

💡 Suggestions for Improvement

1. Type Annotations

   • The Receipt class and several functions lack complete type annotations, which can lead to runtime errors and make the code harder to understand.
   • Recommendation: Add type annotations to all functions and class methods. For example:

     def make_receipt(tool: str, decision: str, policy: str, tier: str) -> Receipt:

2. Thread Safety

   • The receipt_chain list is a global variable that is modified by multiple scenarios. This could lead to race conditions in a multithreaded environment.
   • Recommendation: Use thread-safe data structures (e.g., queue.Queue) or synchronization primitives (e.g., threading.Lock) to ensure thread safety.

3. Error Handling

   • The code lacks robust error handling, especially in critical sections like receipt signing and verification.
   • Recommendation: Add error handling for scenarios such as invalid input, failed signature verification, and chain integrity failures. For example:

     try:
         receipt.verify(DEMO_KEY)
     except Exception as e:
         print(f"Error verifying receipt: {e}")

4. Test Coverage

   • While the example includes 8 scenarios, it is unclear if these are integrated into the CI/CD pipeline for automated testing.
   • Recommendation: Add automated tests for the example scenarios using pytest to ensure they work as expected and do not break in future updates.

5. Documentation

   • The documentation is comprehensive but could benefit from additional clarity on the following points:
     • The distinction between the inline fallback and the production implementation.
     • The security implications of using the demo key and fallback implementation.
     • How to set up and use the npx @veritasacta/verify tool for offline verification.
   • Recommendation: Add a "Security Considerations" section to the README to address these points.

6. Code Duplication

   • The inline fallback implementation duplicates functionality that is already provided by the scopeblind-protect-mcp adapter.
   • Recommendation: Consider refactoring the code to minimize duplication. For example, you could create a common utility module for receipt handling that can be used across different examples.

---

Final Assessment

• The PR is well-structured and provides a valuable addition to the repository.
• However, the use of weak cryptography in the fallback implementation and the lack of replay protection are critical security issues that must be addressed before merging.
• Additionally, improvements in type safety, thread safety, and documentation will enhance the overall quality and maintainability of the code.

Let me know if you need further clarification or assistance!

[github-actions]

🤖 AI Agent: code-reviewer

Review Summary

This pull request introduces a comprehensive governed example for the scopeblind-protect-mcp integration, including 8 scenarios that demonstrate Cedar policy evaluation, signed receipts, and offline verification. The implementation is well-documented, and the examples are thorough and align with the existing patterns in the repository. However, there are a few areas that require attention to ensure security, correctness, and maintainability.

---

🔴 CRITICAL: Security Issues

1. Fallback to SHA-256 HMAC for Signing in Standalone Mode

   • The fallback to SHA-256 HMAC for signing receipts in standalone mode (Receipt.sign method) is not cryptographically secure for this use case. HMAC is not suitable for digital signatures because it does not provide non-repudiation. An attacker with access to the signing key could forge receipts.
   • Actionable Fix:
     • Replace the fallback with a more secure signing mechanism, such as Ed25519 or RSA, even in standalone mode. If cryptographic libraries are unavailable, explicitly document the limitations of the fallback mechanism and warn users not to use it in production.

2. Hardcoded Signing Key

   • The demo signing key (DEMO_KEY) is hardcoded as "a" * 64. This is a security risk, as it encourages poor key management practices.
   • Actionable Fix:
     • Use a securely generated key for the demo, and provide instructions for generating a new key. For example, use os.urandom(32).hex() to generate a random key.

3. Receipt Replay Attack Mitigation

   • There is no explicit mechanism to prevent receipt replay attacks in the fallback implementation. While the ReceiptVerifier in the full implementation may address this, the fallback mode is vulnerable.
   • Actionable Fix:
     • Add a nonce or timestamp validation mechanism to detect and reject replayed receipts in the fallback implementation.

---

🟡 WARNING: Potential Breaking Changes

1. Backward Compatibility of Policy Evaluation
   • The introduction of Cedar policies and the CedarPolicyBridge may change the behavior of policy evaluation, especially if Cedar deny decisions override AGT trust scores.
   • Actionable Fix:
     • Clearly document the precedence rules between Cedar policies and AGT trust scores in the public API. Ensure that existing users are aware of these changes and provide a migration guide if necessary.

---

💡 Suggestions for Improvement

1. Thread Safety

   • The ReceiptVerifier and AuditLog components are described as thread-safe, but this is not explicitly tested in the examples. Concurrent access safety is critical for real-world usage.
   • Actionable Suggestion:
     • Add unit tests or examples that demonstrate and validate thread safety under concurrent access.

2. Type Annotations

   • While the code includes some type annotations, they are inconsistent. For example, Receipt.parent_receipt_hash is annotated as str | None, which is not compatible with Python 3.9.
   • Actionable Suggestion:
     • Use Optional[str] instead of str | None for compatibility with Python 3.9.

3. Error Handling

   • The fallback implementation lacks robust error handling. For example, if the signing key is invalid or the receipt chain is corrupted, the program may fail silently or with unclear error messages.
   • Actionable Suggestion:
     • Add explicit error handling and logging for key operations, such as signing, verification, and chain integrity checks.

4. Policy Example Validation

   • The provided Cedar policy examples are clear but lack validation against the actual Cedar schema.
   • Actionable Suggestion:
     • Include a script or test that validates the Cedar policies against the schema to ensure correctness.

5. Documentation

   • The documentation is thorough but could benefit from a dedicated section on security best practices, especially for key management and receipt verification.
   • Actionable Suggestion:
     • Add a "Security Best Practices" section to the README, emphasizing the importance of secure key storage and avoiding the fallback mode in production.

6. Test Coverage

   • While the examples are comprehensive, they are not integrated into the automated test suite.
   • Actionable Suggestion:
     • Convert key scenarios into pytest-based tests to ensure they are automatically executed during CI/CD.

---

Final Assessment

This pull request is a valuable addition to the repository, providing a well-documented and comprehensive example of governed MCP integration. However, the fallback implementation introduces critical security risks that must be addressed before merging. Additionally, improvements in thread safety validation, type annotations, and error handling will enhance the robustness and maintainability of the code.

• Merge Recommendation: Do not merge until the 🔴 CRITICAL issues are resolved. Address the 🟡 WARNING and 💡 SUGGESTION items to improve the overall quality and reliability of the implementation.

[Imran Siddique (imran-siddique)]

Nice governed example with Cedar policies.