feat(go): add MCP security, execution rings, and lifecycle management to Go SDK

[imran-siddique]

Summary

Adds three new modules to the Go SDK:

MCP Security Scanner (mcp.go)

• Detects tool poisoning (prompt injection in descriptions)
• Typosquatting detection via Levenshtein distance
• Hidden instruction detection (zero-width chars, homoglyphs)
• Rug pull detection (oversized descriptions with malicious patterns)
• Risk scoring (0-100)

Execution Rings (rings.go)

• Four privilege levels: Admin (0), Standard (1), Restricted (2), Sandboxed (3)
• Default-deny access control
• Wildcard permission support

Lifecycle Management (lifecycle.go)

• Eight-state lifecycle model matching other SDKs
• Validated state transitions
• Event history tracking
• Convenience methods (Activate, Suspend, Quarantine, Decommission)

Tests

• mcp_test.go: All 4 threat types, safe tools, Levenshtein, risk score capping
• rings_test.go: Assign, access checks, default deny, wildcard, reassignment
• lifecycle_test.go: Valid/invalid transitions, terminal states, event recording

All tests pass. go vet ./... clean.

[github-actions]

🤖 AI Agent: security-scanner — Security Analysis of Pull Request

Security Analysis of Pull Request

This pull request introduces three new modules to the Go SDK: MCP Security Scanner (mcp.go), Execution Rings (rings.go), and Lifecycle Management (lifecycle.go). Below is a detailed security analysis of the changes, focusing on the critical areas outlined in the task.

---

1. Prompt Injection Defense Bypass

Finding: 🔴 CRITICAL

The detectToolPoisoning function in mcp.go attempts to identify prompt injection patterns by matching specific substrings in the tool description. However, this approach is vulnerable to obfuscation techniques, such as:

• Using synonyms or rephrased instructions (e.g., "forget prior commands" instead of "ignore previous instructions").
• Adding spaces, punctuation, or other characters between words (e.g., "ignore...previous").
• Using base64 encoding or other encoding methods to hide malicious instructions.

Attack Vector:
An attacker could craft a tool description that bypasses these substring checks by using obfuscation techniques, leading to prompt injection vulnerabilities.

Suggested Fix:

• Implement a more robust NLP-based approach to detect semantic intent rather than relying on substring matching.
• Use a pre-trained model or embedding-based similarity scoring to flag suspicious descriptions.
• Regularly update the list of patterns and integrate community feedback to improve detection.

---

2. Policy Engine Circumvention

Finding: 🟠 HIGH

The rings.go module implements execution rings with privilege levels and access control. However:

• The SetRingPermissions method allows wildcard permissions, which could inadvertently grant overly broad access if misconfigured.
• The CheckAccess method does not validate the action against the agent's assigned ring permissions in a robust manner. If an attacker can manipulate the action string (e.g., via injection), they may bypass access controls.

Attack Vector:
An attacker could exploit wildcard permissions or manipulate the action string to gain unauthorized access to restricted actions.

Suggested Fix:

• Remove support for wildcard permissions or implement strict validation to ensure they are not overly permissive.
• Sanitize and validate the action string before checking permissions.
• Add unit tests to simulate edge cases and ensure the access control logic is robust.

---

3. Trust Chain Weaknesses

Finding: 🔵 LOW

No SPIFFE/SVID validation or certificate pinning mechanisms were introduced in this pull request. However, this is not directly relevant to the changes made in this PR. Future iterations of the SDK should ensure that any identity or trust-related mechanisms are robust and secure.

Suggested Fix:

• Ensure SPIFFE/SVID validation is implemented in future updates.
• Add certificate pinning for any TLS connections used by the SDK.

---

4. Credential Exposure

Finding: 🔵 LOW

No credentials or secrets were exposed in logs, error messages, or debug output. The modules appear to handle sensitive information securely.

Suggested Fix:

• Continue to avoid logging sensitive information.
• Implement a mechanism to redact sensitive data from error messages.

---

5. Sandbox Escape

Finding: 🟡 MEDIUM

The sandbox-policy.yaml file was updated to use regex-based conditions (matches) instead of prefix-based conditions (starts_with). While regex provides more flexibility, it also introduces the risk of overly permissive or incorrect patterns that could allow sandbox escapes.

Attack Vector:
An attacker could exploit a poorly written regex pattern to bypass sandbox restrictions, enabling unauthorized file writes or shell access.

Suggested Fix:

• Perform rigorous testing of all regex patterns to ensure they are not overly permissive.
• Use a whitelist approach for file paths and actions instead of regex where possible.
• Add automated tests to validate the behavior of sandbox policies.

---

6. Deserialization Attacks

Finding: 🔵 LOW

No deserialization mechanisms (e.g., JSON, YAML, or pickle loading) were introduced in this PR. The mcp.go module uses JSON for data structures, but there is no evidence of unsafe deserialization.

Suggested Fix:

• Ensure that any future deserialization mechanisms validate input data and sanitize it to prevent code execution or injection attacks.

---

7. Race Conditions

Finding: 🟡 MEDIUM

The lifecycle.go module uses a sync.RWMutex to manage state transitions. While this prevents concurrent writes, there is a potential Time-of-Check-to-Time-of-Use (TOCTOU) vulnerability in the CanTransition method:

• The method checks if a transition is valid (canTransitionLocked) but does not lock the state during the actual transition (Transition).

Attack Vector:
An attacker could exploit a race condition by invoking CanTransition and Transition concurrently, potentially bypassing lifecycle validation.

Suggested Fix:

• Combine the CanTransition and Transition logic into a single atomic operation to eliminate the possibility of TOCTOU vulnerabilities.
• Use the sync.Mutex instead of sync.RWMutex for stricter locking during state transitions.

---

8. Supply Chain

Finding: 🔵 LOW

No new external dependencies were introduced in this pull request. The existing dependencies appear to be legitimate and free from typosquatting risks.

Suggested Fix:

• Regularly audit dependencies for vulnerabilities and typosquatting risks.
• Use tools like go mod verify and snyk to ensure dependency integrity.

---

Summary of Findings

Finding	Severity	Description	Suggested Fix
Prompt injection defense bypass	🔴 CRITICAL	Substring matching is insufficient to detect obfuscated prompt injection patterns.	Use NLP-based semantic analysis and update detection patterns regularly.
Policy engine circumvention	🟠 HIGH	Wildcard permissions and unvalidated action strings could allow unauthorized access.	Remove wildcard permissions or validate them strictly; sanitize action strings.
Trust chain weaknesses	🔵 LOW	No SPIFFE/SVID validation or cert pinning issues in this PR.	Implement SPIFFE/SVID validation and certificate pinning in future updates.
Credential exposure	🔵 LOW	No credentials or sensitive data exposed in logs or errors.	Maintain current practices; add redaction for sensitive data in error messages.
Sandbox escape	🟡 MEDIUM	Regex-based sandbox policies could be overly permissive or incorrect.	Test regex patterns rigorously; prefer whitelist-based policies where possible.
Deserialization attacks	🔵 LOW	No unsafe deserialization mechanisms detected.	Validate and sanitize input data during deserialization in future updates.
Race conditions	🟡 MEDIUM	Potential TOCTOU vulnerability in lifecycle state transitions.	Combine CanTransition and Transition logic into a single atomic operation.
Supply chain	🔵 LOW	No new dependencies or typosquatting risks detected.	Regularly audit dependencies for vulnerabilities and typosquatting risks.

---

Final Recommendation

Address the CRITICAL and HIGH findings immediately, as they pose significant risks to the security of the toolkit. The MEDIUM findings should also be prioritized to ensure robust sandboxing and lifecycle management. The LOW findings can be addressed in future iterations but should not be ignored.

[github-actions]

🤖 AI Agent: code-reviewer

Review Summary

This pull request introduces three major modules to the Go SDK: MCP Security Scanner, Execution Rings, and Lifecycle Management. While the implementation is generally well-structured and adheres to good coding practices, there are several areas that require attention to ensure security, correctness, and backward compatibility. Below is a detailed review of each module and the associated code.

---

MCP Security Scanner (mcp.go)

🔴 CRITICAL: Homoglyph Detection Incompleteness

The looksLikeLatinHomoglyph function only checks a limited set of homoglyphs. This creates a false sense of security, as attackers can use other Unicode characters to bypass detection. For example, Latin Extended-A characters (ā, ē, etc.) or visually similar characters from other scripts are not covered.

Actionable Fix: Use a comprehensive Unicode homoglyph detection library or expand the list to include more characters. Consider leveraging external libraries like unicode-matcher for broader coverage.

---

🔴 CRITICAL: Risk Scoring Weakness

The computeRiskScore function aggregates threat severity scores but does not cap the maximum risk score. This could lead to inconsistent scoring if multiple threats are detected. Additionally, the scoring logic does not account for the cumulative impact of multiple "critical" threats.

Actionable Fix: Introduce a risk score cap (e.g., 100) and refine the scoring algorithm to account for the compounding effect of multiple high-severity threats.

---

💡 SUGGESTION: Known Tools Registry

The knownTools list is populated dynamically during scanning, which could lead to false positives for typosquatting detection if the list contains tools with similar names. This approach may also be vulnerable to poisoning attacks.

Recommendation: Use a predefined list of trusted tool names and allow dynamic updates only from authenticated sources.

---

Execution Rings (rings.go)

🔴 CRITICAL: Default-Deny Implementation

The default-deny access control mechanism is critical for security. However, the implementation does not explicitly verify that all actions are denied unless explicitly allowed. This could lead to unintended privilege escalation if the SetRingPermissions function is misused.

Actionable Fix: Add explicit checks to ensure that actions not listed in SetRingPermissions are denied by default.

---

💡 SUGGESTION: Wildcard Permission Handling

The wildcard permission support is useful but could lead to overly permissive configurations if not carefully managed. For example, * could inadvertently allow sensitive actions.

Recommendation: Introduce a mechanism to restrict wildcard usage to specific namespaces (e.g., data.*).

---

Lifecycle Management (lifecycle.go)

🔴 CRITICAL: Thread Safety

The LifecycleManager uses a sync.RWMutex for thread safety, but the Transition method appends to the events slice without bounds checking. This could lead to memory exhaustion in high-concurrency scenarios.

Actionable Fix: Add a configurable limit to the number of recorded events and implement eviction for older events.

---

💡 SUGGESTION: State Transition Validation

The validTransitions map ensures that state transitions are validated, but the error messages returned by Transition are generic. This makes debugging difficult.

Recommendation: Enhance error messages to include the agent ID and current state for better traceability.

---

Tests

💡 SUGGESTION: Coverage for Edge Cases

While the tests cover common scenarios, edge cases such as invalid tool definitions (e.g., empty names or descriptions) and high-concurrency lifecycle transitions are not tested.

Recommendation: Add tests for edge cases and concurrency scenarios to ensure robustness.

---

Documentation

💡 SUGGESTION: Expand Examples

The examples provided in the README.md are helpful but lack real-world use cases, such as integrating the MCP Security Scanner with the Execution Rings and Lifecycle Management modules.

Recommendation: Add a comprehensive example demonstrating how these modules work together in a governance pipeline.

---

Backward Compatibility

🟡 WARNING: Public API Changes

The addition of new modules expands the public API of the Go SDK. While this is not inherently breaking, downstream consumers may need to update their code to leverage the new functionality.

Actionable Fix: Clearly document the changes in the release notes and provide migration guidance for existing users.

---

General Observations

💡 SUGGESTION: OWASP Agentic Top 10 Compliance

The modules address several OWASP Agentic Top 10 concerns, such as prompt injection and privilege escalation. However, additional measures like rate limiting and monitoring for anomalous behavior could further enhance security.

Recommendation: Consider adding rate limiting and anomaly detection features in future iterations.

---

Final Assessment

• Security: 🔴 Critical issues in homoglyph detection, risk scoring, and thread safety need immediate attention.
• Correctness: The modules are generally well-implemented but require edge case handling and enhanced error messages.
• Backward Compatibility: 🟡 Changes to the public API should be documented to avoid confusion for downstream users.
• Documentation: Examples and usage scenarios need expansion for better developer adoption.

---

Action Items

1. 🔴 Fix homoglyph detection and risk scoring vulnerabilities in mcp.go.
2. 🔴 Ensure thread safety and add event limits in lifecycle.go.
3. 🟡 Document public API changes and provide migration guidance.
4. 💡 Expand examples and test coverage for edge cases and concurrency.
5. 💡 Enhance error messages and restrict wildcard permissions.

Let me know if you need further clarification or assistance!

[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.