feat(rust): add execution rings and lifecycle management to Rust SDK

[imran-siddique]

Summary

Add two new modules to the agentmesh Rust crate:

• rings.rs - Four-level execution privilege ring model (Admin/Standard/Restricted/Sandboxed) with per-agent assignment and per-ring action permissions, ported from the Python hypervisor enforcer.
• lifecycle.rs - Eight-state agent lifecycle manager (Provisioning through Decommissioned) with validated state transitions and event history.

Both modules include comprehensive unit tests (#[cfg(test)]) and are re-exported from the crate root. README updated with API tables and usage examples.

cargo check and cargo check --tests pass successfully.

[github-actions]

🤖 AI Agent: docs-sync-checker — Issues Found

📝 Documentation Sync Report

Issues Found

• ✅ All public APIs in KillSwitch.cs and LifecycleManager.cs have comprehensive docstrings.
• ✅ The README.md for the agent-governance-dotnet package has been updated to include new sections for "Kill Switch" and "Lifecycle Management," reflecting the new functionality.
• ✅ The CHANGELOG.md file has been updated with an entry for the new features added in this PR.
• ✅ Example code in the README.md for the agent-governance-dotnet package is up-to-date and includes usage examples for the new APIs.
• ✅ All new public APIs in KillSwitch.cs and LifecycleManager.cs have complete type annotations.

Suggestions

• None.

✅ Documentation is in sync.

[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: security-scanner — Security Analysis of Pull Request

Security Analysis of Pull Request

This pull request introduces two new modules to the Rust SDK (rings.rs and lifecycle.rs) and corresponding functionality in the .NET SDK (KillSwitch.cs and LifecycleManager.cs). These modules are critical for enforcing agent governance policies, managing agent lifecycle states, and controlling execution privileges. Below is a detailed security analysis based on the specified criteria.

---

1. Prompt Injection Defense Bypass

Finding: 🔵 LOW
The KillSwitch and LifecycleManager modules do not directly interact with user-provided input or natural language prompts. However, the KillSwitch allows human-readable detail messages to be logged, which could theoretically include malicious content if improperly sanitized. This is a minor concern since these logs are internal and not exposed externally.

Attack Vector: If an attacker injects malicious content into the detail field, it could potentially lead to log poisoning or confusion during debugging.

Recommendation: Ensure that all loggable fields are sanitized to prevent injection attacks. For example, escape special characters and validate input length.

---

2. Policy Engine Circumvention

Finding: 🟠 HIGH
The LifecycleManager allows state transitions based on a predefined set of valid transitions. However, the Transition method relies on the CanTransition function, which is implemented correctly but could be bypassed if the State property is directly modified (e.g., via reflection or unsafe code).

Attack Vector: An attacker could bypass the lifecycle state validation by directly modifying the State property, allowing unauthorized transitions (e.g., skipping quarantine).

Recommendation:

• Make the State property private and expose it only via controlled methods.
• Use Rust-like immutability principles in the .NET implementation to prevent direct state modification.
• Add runtime checks to ensure transitions always go through the Transition method.

---

3. Trust Chain Weaknesses

Finding: 🔴 CRITICAL
The KillSwitch and LifecycleManager modules lack mechanisms to verify the authenticity of the agentId field (e.g., using SPIFFE/SVID or certificate-based validation). This could allow attackers to spoof agent identities and manipulate governance actions.

Attack Vector: An attacker could spoof agentId values to impersonate legitimate agents, bypassing governance policies or triggering unauthorized actions.

Recommendation:

• Integrate SPIFFE/SVID or similar identity verification mechanisms to validate agentId values.
• Ensure that agentId is cryptographically signed and verified before processing any governance actions.
• Reject invalid or unverified agentId values.

---

4. Credential Exposure

Finding: 🔵 LOW
No sensitive credentials are exposed in logs, error messages, or debug output. The modules appear to handle sensitive data (e.g., agentId) securely.

Recommendation: Continue to avoid logging sensitive information like cryptographic keys or agent credentials.

---

5. Sandbox Escape

Finding: 🟡 MEDIUM
The rings.rs module introduces a four-level privilege model, but the enforcement of sandboxed actions (Ring::Sandboxed) relies on the check_access method. If this method is improperly implemented or bypassed, agents assigned to the Sandboxed ring could escape their restricted environment.

Attack Vector: An attacker could exploit a logic flaw in check_access to perform unauthorized actions despite being assigned to the Sandboxed ring.

Recommendation:

• Add comprehensive tests to ensure check_access correctly denies all actions for Sandboxed agents.
• Use a deny-by-default approach for sandboxed agents, ensuring no actions are permitted unless explicitly allowed.
• Consider integrating hardware-based sandboxing mechanisms (e.g., Intel SGX or ARM TrustZone) for additional isolation.

---

6. Deserialization Attacks

Finding: 🔵 LOW
No unsafe deserialization mechanisms (e.g., JSON, YAML, or pickle) are present in the code. The modules use strongly typed data structures, which mitigate deserialization risks.

Recommendation: Continue using strongly typed data structures and avoid unsafe deserialization libraries.

---

7. Race Conditions

Finding: 🟠 HIGH
Both KillSwitch and LifecycleManager use locks (_lock) to synchronize access to shared state. However, the use of locks introduces potential race conditions if the locking mechanism is not properly implemented or if the lock is bypassed.

Attack Vector: An attacker could exploit race conditions to perform unauthorized state transitions or manipulate kill event history.

Recommendation:

• Use language-specific concurrency primitives (e.g., std::sync::Mutex in Rust or lock in C#) to ensure thread-safe access to shared state.
• Add tests to simulate concurrent access and verify that race conditions do not occur.

---

8. Supply Chain

Finding: 🔴 CRITICAL
The pull request does not explicitly address dependency management for the Rust SDK. If dependencies are not properly vetted, the project could be vulnerable to dependency confusion or typosquatting attacks.

Attack Vector: An attacker could introduce malicious dependencies into the Rust SDK via typosquatting or dependency confusion.

Recommendation:

• Use tools like cargo-audit to scan for vulnerable dependencies in the Rust SDK.
• Pin dependency versions to avoid unintentional upgrades to malicious packages.
• Verify the authenticity of all dependencies before including them in the project.

---

Summary of Findings

Finding	Severity	Recommendation
Prompt Injection Defense Bypass	🔵 LOW	Sanitize loggable fields to prevent injection attacks.
Policy Engine Circumvention	🟠 HIGH	Make State private and enforce transitions via controlled methods.
Trust Chain Weaknesses	🔴 CRITICAL	Integrate SPIFFE/SVID for agentId validation.
Credential Exposure	🔵 LOW	Avoid logging sensitive information.
Sandbox Escape	🟡 MEDIUM	Add tests for check_access and enforce deny-by-default for sandboxed agents.
Deserialization Attacks	🔵 LOW	Continue using strongly typed data structures.
Race Conditions	🟠 HIGH	Use concurrency primitives and test for race conditions.
Supply Chain	🔴 CRITICAL	Audit dependencies, pin versions, and verify authenticity.

---

Final Recommendations

1. Address critical findings immediately, especially trust chain weaknesses and supply chain risks.
2. Harden the policy engine and sandbox enforcement mechanisms to prevent circumvention.
3. Perform a full dependency audit for the Rust SDK and integrate automated tools for ongoing monitoring.
4. Add additional tests to simulate edge cases and concurrency scenarios.

This pull request introduces valuable functionality but requires further security hardening to ensure robust governance and protection against potential attacks.

[github-actions]

🤖 AI Agent: breaking-change-detector — Summary

🔍 API Compatibility Report

Summary

This pull request introduces new functionality to the Rust SDK (agentmesh crate) and the .NET SDK (agent-governance-dotnet) with no breaking changes detected. The changes are additive and include new modules, classes, methods, and enums. These additions expand the functionality of the SDKs without altering existing APIs.

Findings

Severity	Package	Change	Impact
🔵	agentmesh (Rust SDK)	Added rings.rs module	New functionality for execution rings management. No breaking changes.
🔵	agentmesh (Rust SDK)	Added lifecycle.rs module	New functionality for agent lifecycle management. No breaking changes.
🔵	agent-governance-dotnet	Added KillSwitch class	New functionality for agent termination. No breaking changes.
🔵	agent-governance-dotnet	Added LifecycleManager class	New functionality for agent lifecycle management. No breaking changes.
🔵	agent-governance-dotnet	Added KillReason enum	New enum for kill reasons. No breaking changes.
🔵	agent-governance-dotnet	Added LifecycleState enum	New enum for lifecycle states. No breaking changes.

Migration Guide

No migration steps are necessary as this pull request does not introduce any breaking changes. Downstream users can adopt the new functionality without modifying existing code.

Recommendations

1. Documentation: Ensure that the new APIs (rings.rs, lifecycle.rs, KillSwitch, LifecycleManager, etc.) are thoroughly documented, including usage examples and expected behavior.
2. Versioning: Increment the minor version of the affected packages to reflect the addition of new features.
3. Communication: Notify users of the new features in release notes, highlighting the added functionality and providing links to updated documentation.

✅ No breaking changes detected.

[github-actions]

🤖 AI Agent: code-reviewer

Review Summary

This pull request introduces two new modules to the Rust SDK (agentmesh crate): rings.rs for execution privilege rings and lifecycle.rs for agent lifecycle management. Both modules are well-documented, include comprehensive unit tests, and adhere to Rust's idiomatic practices. However, there are several areas requiring attention to ensure security, correctness, and backward compatibility.

---

🔴 CRITICAL: Security Issues

1. Privilege Escalation in rings.rs:

   • The RingEnforcer does not validate whether an agent can escalate its own privileges. For example, an agent assigned to a lower privilege ring (e.g., Sandboxed) could potentially escalate itself to Admin if it has access to the assign method.
   • Recommendation: Implement checks to ensure that only authorized entities (e.g., system administrators or governance policies) can modify an agent's ring assignment.

2. Lifecycle State Transition Validation:

   • The LifecycleManager allows state transitions based on predefined rules, but there is no cryptographic verification or authentication of the initiatedBy actor. This could allow unauthorized entities to manipulate the lifecycle state.
   • Recommendation: Add cryptographic signatures or authentication mechanisms to verify the identity of the actor initiating the transition.

3. Concurrency Risks in KillSwitch and LifecycleManager:

   • Both classes use lock for thread safety, but the locking mechanism does not prevent deadlocks or race conditions if multiple threads attempt to modify the state simultaneously.
   • Recommendation: Use std::sync::RwLock or tokio::sync::RwLock for better concurrency handling in Rust.

4. Sandbox Escape Vectors in rings.rs:

   • The Sandboxed ring denies all actions, but there is no explicit mechanism to enforce sandboxing at the system level (e.g., syscall filtering or containerization).
   • Recommendation: Integrate system-level sandboxing mechanisms (e.g., seccomp, AppArmor, or SELinux) to enforce sandbox restrictions.

---

🟡 WARNING: Potential Breaking Changes

1. Public API Changes in rings.rs:

   • The addition of RingEnforcer and its methods (assign, get_ring, check_access, etc.) modifies the public API of the agentmesh crate. This could break existing integrations if users rely on the previous API structure.
   • Recommendation: Clearly document these changes in the release notes and consider versioning the crate to signal breaking changes.

2. Lifecycle State Transition Rules:

   • The introduction of strict state transition rules in LifecycleManager could break existing workflows if they rely on transitions that are no longer valid.
   • Recommendation: Provide a migration guide for users to adapt their workflows to the new lifecycle model.

---

💡 Suggestions for Improvement

1. Unit Test Coverage:

   • While the unit tests are comprehensive, consider adding tests for edge cases, such as:
     • Attempting to assign an agent to an invalid ring.
     • Transitioning to a state not listed in ValidTransitions.
     • Concurrent access to KillSwitch and LifecycleManager.

2. Error Messages:

   • Improve error messages for invalid operations (e.g., "Cannot transition from X to Y" could include the list of valid transitions for better debugging).

3. Documentation Enhancements:

   • Add examples of real-world use cases for RingEnforcer and LifecycleManager in the README to help users understand their practical applications.

4. Type Safety:

   • Consider using enums with associated data for KillReason and LifecycleState to enforce stricter type safety and reduce the risk of invalid inputs.

5. Backward Compatibility:

   • Introduce feature flags or configuration options to allow users to opt into the new functionality without breaking existing workflows.

---

Conclusion

While the new modules provide valuable functionality for agent governance, addressing the identified security issues is critical before merging this pull request. Additionally, documenting breaking changes and providing migration guides will help ensure a smooth transition for existing users.