fix(security): complete dependency confusion fix — all pip install agent-os replaced

[imran-siddique]

Completes the fix from PR #325. Replaces all 25+ instances of bare \pip install agent-os\ (unregistered on PyPI) with \pip install agent-os-kernel\ across 23 files. 75 CLI tests pass.

[github-actions]

🤖 AI Agent: breaking-change-detector

🔍 API Compatibility Report

Summary

This pull request primarily replaces references to the agent-os package with agent-os-kernel across multiple files. No breaking changes to the public API of the microsoft/agent-governance-toolkit repository were identified. The changes involve documentation updates, examples, and CI/CD configurations, with no modifications to function signatures, exception types, or exported modules.

Findings

Severity	Package	Change	Impact
✅	agent-os-kernel	Replacement of agent-os with agent-os-kernel	No breaking changes to the public API
🔵	agent-os	Added detailed docstrings for MCPMessageType and MCPAdapter	Improves documentation, no breaking changes

Migration Guide

No migration steps are necessary as no breaking changes were introduced. Users should update their dependencies to use agent-os-kernel instead of agent-os as per the updated documentation.

Additional Notes

• The detailed docstrings added to MCPMessageType and MCPAdapter improve clarity and usability for developers, but they do not alter the functionality or introduce breaking changes.
• The replacement of agent-os with agent-os-kernel appears to be a continuation of a previous change (referenced as PR fix: remove unregistered PyPI packages from notebooks and requirements (dependency confusion) #325). This change ensures consistency across the repository and aligns with the new package naming convention.

✅ No breaking changes detected.

[github-actions]

🤖 AI Agent: docs-sync-checker

📝 Documentation Sync Report

Issues Found

• ❌ handle_message() in packages/agent-os/modules/control-plane/src/agent_control_plane/mcp_adapter.py — missing complete docstring for parameters, return values, and exceptions.
• ❌ _handle_tools_list() in packages/agent-os/modules/control-plane/src/agent_control_plane/mcp_adapter.py — missing docstring.
• ❌ _handle_resources_list() in packages/agent-os/modules/control-plane/src/agent_control_plane/mcp_adapter.py — missing docstring.
• ❌ _handle_prompts_get() in packages/agent-os/modules/control-plane/src/agent_control_plane/mcp_adapter.py — missing docstring.
• ⚠️ README.md — new pip install agent-os-kernel command is not reflected in all relevant sections.
• ⚠️ CHANGELOG.md — no entry for the replacement of pip install agent-os with pip install agent-os-kernel.
• ⚠️ examples/ — several example scripts and requirements.txt files were updated, but the changes are not reflected in the corresponding documentation or comments.

Suggestions

• 💡 Add a complete docstring for handle_message(message: Dict[str, Any]) -> Dict[str, Any] in mcp_adapter.py. Include details about parameters, return values, and exceptions.
• 💡 Add docstrings for _handle_tools_list(params: Dict) -> Dict, _handle_resources_list(params: Dict) -> Dict, and _handle_prompts_get(params: Dict) -> Dict in mcp_adapter.py.
• 💡 Update README.md to replace all instances of pip install agent-os with pip install agent-os-kernel.
• 💡 Add an entry to CHANGELOG.md documenting the replacement of pip install agent-os with pip install agent-os-kernel across the repository.
• 💡 Review and update example scripts and associated documentation in examples/ to ensure consistency with the new agent-os-kernel package name.

Additional Notes

• The changes to the MCPAdapter class include improvements to the docstrings for some methods, but a few methods still lack complete documentation. Ensure all public methods have comprehensive docstrings.
• The README.md has been partially updated to reflect the new pip install agent-os-kernel command, but some sections may still reference the old agent-os package. A thorough review is recommended.
• The CHANGELOG.md should include a clear entry for this change, as it impacts the installation process and is a significant update.
• Example scripts and requirements.txt files in examples/ were updated, but their corresponding documentation and comments need to be reviewed for consistency.

Action Items

1. Add missing docstrings to the identified methods in mcp_adapter.py.
2. Update all relevant sections of README.md to reflect the new pip install agent-os-kernel command.
3. Add a detailed entry to CHANGELOG.md about the replacement of pip install agent-os with pip install agent-os-kernel.
4. Review and update all example scripts and their documentation in examples/ to ensure they align with the new package name and installation instructions.

Let me know if you need further assistance!

[github-actions]

🤖 AI Agent: test-generator

🧪 Test Coverage Analysis

packages/agent-os/src/agent_os/cli/__init__.py

• ✅ Existing coverage: The existing tests likely cover basic command-line interface (CLI) functionality, including command execution and argument parsing.
• ❌ Missing coverage: There may be insufficient coverage for edge cases related to policy evaluation, trust scoring, and input validation. Specifically, scenarios involving conflicting policies, malformed inputs, and edge cases in trust scoring (e.g., handling of edge scores like 0.0 and 1.0) may not be adequately tested.
• 💡 Suggested test cases:
  1. test_policy_conflict_handling — Verify that the CLI correctly identifies and handles conflicting policies when multiple policies are applied.
  2. test_trust_score_edge_cases — Test the behavior of the CLI when trust scores are at the extreme ends (0.0 and 1.0) to ensure proper handling and responses.
  3. test_malformed_input_handling — Ensure that the CLI gracefully handles malformed inputs, such as invalid command options or unexpected argument types, without crashing.
  4. test_policy_bypass_attempts — Simulate attempts to bypass defined policies through CLI commands and verify that the system correctly denies such attempts.
  5. test_timeout_handling — Test the CLI's response to timeout scenarios during command execution, ensuring it handles partial failures gracefully.

[github-actions]

🤖 AI Agent: code-reviewer

Review Summary

This pull request addresses a critical security issue by replacing all instances of pip install agent-os with pip install agent-os-kernel, ensuring that the project no longer references a potentially malicious or unregistered package on PyPI. The PR also includes updates to documentation, examples, and CI/CD workflows to reflect this change. Additionally, there are some updates to the MCPAdapter class, including improved docstrings and governance checks.

---

🔴 CRITICAL

1. Dependency Confusion Risk Mitigation

   • The replacement of pip install agent-os with pip install agent-os-kernel is a critical fix to mitigate dependency confusion attacks. However, ensure that the agent-os-kernel package is properly registered and secured on PyPI or a private package index. If it is hosted on a private index, ensure that the index is secure and access is restricted to authorized users only.

2. Governance Checks in MCPAdapter

   • The MCPAdapter class has been updated with improved docstrings and governance checks. However, the handle_message method does not seem to sanitize or validate the message input thoroughly before processing. This could lead to potential injection or deserialization vulnerabilities. Add validation for the message structure and its fields to ensure they conform to the expected JSON-RPC 2.0 format.

---

🟡 WARNING

1. Breaking Change

   • Replacing pip install agent-os with pip install agent-os-kernel is a breaking change for users who rely on the previous package name. While this change is necessary for security, it should be clearly communicated in the release notes and documentation. Consider adding a migration guide for users to transition to the new package name.

2. Backward Compatibility

   • If agent-os-kernel introduces any API changes compared to agent-os, ensure that these changes are documented and that the new package is backward-compatible with the previous one. If not, provide clear guidance on how users can adapt their code.

---

💡 SUGGESTIONS

1. Documentation Updates

   • The documentation updates are comprehensive, but consider adding a section explicitly explaining why the package name was changed (e.g., to mitigate dependency confusion risks). This will help users understand the rationale behind the change and build trust in the new package.

2. Testing

   • While the PR mentions that 75 CLI tests pass, ensure that there is adequate test coverage for the agent-os-kernel package, especially for critical governance and security features. Consider adding tests to validate the new governance checks in the MCPAdapter class.

3. CI/CD Enhancements

   • The addition of the link-check.yml workflow is a good step toward improving documentation quality. However, consider adding a badge to the README.md to display the status of the link-check workflow.

4. Code Comments

   • The updated docstrings in the MCPAdapter class are detailed and helpful. However, consider adding inline comments for complex logic within methods like _handle_tools_call and _handle_resources_read to improve code readability.

5. Error Handling

   • The handle_message method raises a PermissionError for governance violations, which is then converted to a JSON-RPC error response. While this is acceptable, consider creating a custom exception class (e.g., GovernanceError) to make the intent clearer and to allow for more granular error handling in the future.

6. Performance Testing

   • Since the MCPAdapter class is central to the governance functionality, consider conducting performance tests to ensure that the additional governance checks do not introduce significant latency, especially under high concurrency.

7. OWASP Agentic Top 10 Compliance

   • The PR does not explicitly address OWASP Agentic Top 10 compliance. Ensure that the changes align with the relevant OWASP recommendations, particularly around dependency management, input validation, and secure defaults.

---

Final Recommendation

• Approve with Changes: The PR addresses a critical security issue and makes necessary updates to the codebase. However, the changes introduce a breaking change and require additional validation and documentation updates. Address the critical and warning issues before merging.

[github-actions]

🤖 AI Agent: security-scanner

Security Analysis of Pull Request

This pull request addresses a critical issue related to dependency confusion by replacing all instances of pip install agent-os with pip install agent-os-kernel. The changes span across multiple files, including documentation, CI/CD workflows, and code. Below is a detailed security analysis of the changes:

---

1. Dependency Confusion Mitigation

• Risk: The original agent-os package was unregistered on PyPI, which made it vulnerable to dependency confusion attacks. An attacker could have registered a malicious package with the same name on PyPI, potentially compromising the security of downstream users.
• Change: The PR replaces all instances of pip install agent-os with pip install agent-os-kernel, which is presumably a registered and verified package on PyPI.
• Assessment: This change addresses the dependency confusion vulnerability by ensuring that the package being installed is the intended one (agent-os-kernel) and not a malicious package.
• Rating: 🔴 CRITICAL
• Recommendation: Ensure that agent-os-kernel is properly registered, verified, and maintained on PyPI. Additionally, consider implementing dependency pinning (e.g., pip install agent-os-kernel==<specific_version>) to prevent supply chain attacks via malicious updates.

---

2. Supply Chain Risks in Dependencies

• Risk: The PR highlights several dependencies in requirements.txt files that are not available on PyPI (zendesk-sdk, freshdesk-sdk, hashlib-compat). These could be potential sources of supply chain attacks if malicious actors register packages with these names on PyPI.
• Change: The PR replaces zendesk-sdk and freshdesk-sdk with their correct PyPI equivalents (zenpy and freshdesk) and removes the invalid hashlib-compat dependency.
• Assessment: This is a critical fix as it eliminates the risk of dependency confusion for these packages.
• Rating: 🔴 CRITICAL
• Recommendation: Ensure that all dependencies are verified and sourced from trusted repositories. Regularly audit dependencies for vulnerabilities using tools like pip-audit or safety.

---

3. Policy Engine Circumvention

• Risk: The MCPAdapter class is responsible for enforcing governance rules on MCP protocol messages. If there are flaws in its implementation, it could allow malicious actors to bypass policy checks.
• Change: The PR adds detailed docstrings to the MCPAdapter class and its methods, clarifying their purpose and behavior. However, no functional changes to the governance logic are made.
• Assessment: While the added documentation improves code clarity, it does not address potential vulnerabilities in the governance logic. The _handle_tools_call and _handle_resources_read methods rely on the control_plane.check_action method for governance checks. If there are any issues in control_plane.check_action, it could lead to policy circumvention.
• Rating: 🟠 HIGH
• Recommendation: Conduct a thorough review of the control_plane.check_action method to ensure it correctly enforces all governance policies. Add unit tests to verify that unauthorized actions are consistently blocked.

---

4. Credential Exposure

• Risk: Secrets or sensitive information could be exposed in logs, error messages, or debug output.
• Change: The PR includes logging statements in the MCPAdapter class, such as self.logger.info(f"Resource read request: {uri}").
• Assessment: Logging the uri in _handle_resources_read could potentially expose sensitive information, such as file paths or resource identifiers, in logs.
• Rating: 🟠 HIGH
• Recommendation: Sanitize sensitive information before logging. For example, avoid logging full URIs if they may contain sensitive data. Use a logging library that supports redaction or implement custom sanitization logic.

---

5. Prompt Injection Defense Bypass

• Risk: If the MCPAdapter or related components process user-provided input without proper sanitization, it could be vulnerable to prompt injection attacks.
• Change: No changes in this PR directly address prompt injection vulnerabilities.
• Assessment: The MCPAdapter class processes user-provided JSON-RPC messages, including prompt-related methods like _handle_prompts_get. If these methods do not properly validate or sanitize input, they could be exploited for prompt injection.
• Rating: 🟠 HIGH
• Recommendation: Review all methods in MCPAdapter that process user input, especially _handle_prompts_get. Ensure that input is validated and sanitized to prevent injection attacks. Add tests to simulate potential injection scenarios.

---

6. Trust Chain Weaknesses

• Risk: Weaknesses in SPIFFE/SVID validation or certificate pinning could compromise the trust chain.
• Change: No changes in this PR directly address trust chain validation.
• Assessment: The PR does not introduce new trust chain weaknesses. However, the MCPAdapter class interacts with the control plane and may rely on SPIFFE/SVID for identity and trust. Any issues in this area could have critical security implications.
• Rating: 🟡 MEDIUM
• Recommendation: Review the implementation of SPIFFE/SVID validation and certificate pinning in the control plane and related components. Ensure that all trust decisions are based on verified identities.

---

7. Sandbox Escape

• Risk: If the MCPAdapter or related components allow untrusted code execution, it could lead to a sandbox escape.
• Change: No changes in this PR directly address sandboxing.
• Assessment: The MCPAdapter class includes methods like _handle_tools_call, which execute tools based on user-provided input. If these tools are not properly sandboxed, they could execute arbitrary code.
• Rating: 🟠 HIGH
• Recommendation: Ensure that all tools executed via _handle_tools_call are sandboxed. Consider using technologies like containerization or restricted execution environments to isolate untrusted code.

---

8. Deserialization Attacks

• Risk: Unsafe deserialization of user-provided data could lead to remote code execution or other attacks.
• Change: The MCPAdapter class processes JSON-RPC messages, which involves deserialization of JSON data.
• Assessment: JSON is generally safer than formats like pickle or YAML, but it is still important to validate the structure and content of deserialized data. The PR does not introduce new deserialization vulnerabilities, but the existing code should be reviewed for potential issues.
• Rating: 🟡 MEDIUM
• Recommendation: Ensure that all deserialized JSON data is validated against a schema or expected structure. Use libraries like jsonschema to enforce validation.

---

9. Race Conditions

• Risk: Time-of-check-to-time-of-use (TOCTOU) vulnerabilities in policy checks or trust evaluation could allow attackers to bypass governance.
• Change: No changes in this PR directly address race conditions.
• Assessment: The MCPAdapter class performs governance checks via the control plane. If these checks are not atomic or if there are delays between the check and the action, race conditions could occur.
• Rating: 🟡 MEDIUM
• Recommendation: Ensure that governance checks and the corresponding actions are performed atomically. Use locks or other synchronization mechanisms if necessary.

---

Summary of Findings

Finding	Rating	Recommendation
Dependency confusion mitigation	🔴 CRITICAL	Verify agent-os-kernel package and implement dependency pinning.
Supply chain risks in dependencies	🔴 CRITICAL	Audit all dependencies and ensure they are sourced from trusted repositories.
Policy engine circumvention	🟠 HIGH	Review control_plane.check_action for robustness and add tests for edge cases.
Credential exposure in logs	🟠 HIGH	Sanitize sensitive information before logging.
Prompt injection defense bypass	🟠 HIGH	Validate and sanitize all user-provided input to prevent injection attacks.
Trust chain weaknesses	🟡 MEDIUM	Review SPIFFE/SVID validation and certificate pinning.
Sandbox escape	🟠 HIGH	Ensure tools executed via _handle_tools_call are sandboxed.
Deserialization attacks	🟡 MEDIUM	Validate all deserialized JSON data against a schema.
Race conditions in policy checks	🟡 MEDIUM	Ensure atomicity of governance checks and actions.

Final Recommendation

The PR addresses a critical dependency confusion vulnerability, which is a significant improvement. However, there are several areas in the codebase that require further review and testing to ensure robust security, particularly around governance checks, logging, and input validation. These issues should be addressed in subsequent PRs to strengthen the security posture of the library.