feat: add agent lifecycle management - provisioning to decommission

[imran-siddique]

Addresses gap #2: agent lifecycle management (provisioning, credential rotation, orphan detection, decommissioning). 24 tests, tutorial 30, full audit trail.

[github-actions]

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

📝 Documentation Sync Report

Issues Found

• ❌ LifecycleManager and related classes in agentmesh.lifecycle — missing docstrings for public methods and parameters.
• ❌ AgentInventory, ProcessScanner, ConfigScanner, Reconciler, RiskScorer, and other public classes/methods in agent-discovery — missing docstrings for purpose, parameters, return values, and exceptions.
• ⚠️ packages/agent-discovery/README.md — does not fully document the RiskScorer and its scoring factors, which are detailed in the tutorial.
• ⚠️ docs/tutorials/README.md — new tutorials (29 and 30) are added, but the summary sections for "Discovery & Inventory" and "Extending the Toolkit" could be expanded for clarity.
• ⚠️ CHANGELOG.md — no entry for the new agentmesh.lifecycle module or the agentmesh-platform package.

Suggestions

• 💡 Add detailed docstrings for LifecycleManager and its methods, including request_provisioning, approve, activate, heartbeat, rotate_credentials, decommission, and get_audit_trail. Include parameter descriptions, return types, and exceptions raised.
• 💡 Add detailed docstrings for AgentInventory, ProcessScanner, ConfigScanner, Reconciler, RiskScorer, and other public classes/methods in agent-discovery. Ensure type hints are included for all parameters and return values.
• 💡 Update packages/agent-discovery/README.md to include a section on RiskScorer, explaining its purpose, scoring factors, and usage.
• 💡 Expand the "Discovery & Inventory" and "Extending the Toolkit" sections in docs/tutorials/README.md to provide more context about the new tutorials.
• 💡 Add a new entry in CHANGELOG.md for the agentmesh-platform package and its LifecycleManager and related features.

Please address these issues to ensure the documentation is complete and up-to-date. Let me know if you need further clarification or assistance.

[github-actions]

🤖 AI Agent: breaking-change-detector — Summary

🔍 API Compatibility Report

Summary

This pull request introduces new functionality related to agent lifecycle management and discovery. It includes new packages (agent-discovery and agentmesh-platform) and their associated APIs. After analyzing the diff, no breaking changes were identified in existing APIs. The changes are additive, introducing new public APIs and features.

Findings

Severity	Package	Change	Impact
🔵	agent-discovery	New package with public APIs for agent discovery	Additive
🔵	agentmesh-platform	New lifecycle management APIs	Additive

Migration Guide

✅ No migration steps are required as no breaking changes were detected.

Notes

• The new APIs (agent-discovery and agentmesh-platform) should be documented thoroughly to ensure downstream users can adopt them easily.
• Ensure that the new CLI commands and tutorials are included in the official documentation for better usability.

If you have further questions or need additional analysis, feel free to ask!

[github-actions]

🤖 AI Agent: code-reviewer

Pull Request Review: Agent Lifecycle Management and Discovery

This pull request introduces significant new functionality for agent lifecycle management (provisioning to decommissioning) and agent discovery. Below is a detailed review of the changes, focusing on the specified areas of concern.

---

🔴 CRITICAL: Security Issues

1. Credential Rotation and Revocation

   • The CredentialPolicy includes auto_rotate and revoke_on_decommission. However, there is no explicit verification that credentials are securely revoked from all systems where they might have been distributed. If an agent's credentials are cached or not properly invalidated, this could lead to unauthorized access.
     • Actionable Fix: Ensure that credential revocation propagates to all systems where the credentials might be in use. Add tests to verify that revoked credentials cannot be used post-decommission.

2. Orphan Detection

   • The OrphanDetector relies on heartbeats to identify orphaned agents. However, there is no mention of cryptographic verification of these heartbeats. An attacker could spoof heartbeats to prevent an agent from being marked as orphaned.
     • Actionable Fix: Ensure all heartbeats are signed using the agent's private key and verified against its public key (e.g., SPIFFE/SVID). Add tests to validate this behavior.

3. Shadow Agent Risk Scoring

   • The RiskScorer assigns points for missing identity (e.g., no DID/SPIFFE). However, there is no mechanism to verify the authenticity of the discovered agents' identities. This could lead to false negatives if an attacker spoofs a valid identity.
     • Actionable Fix: Add a mechanism to verify the authenticity of discovered identities, such as checking against a trusted certificate authority or registry.

4. Process Scanner Redaction

   • The ProcessScanner claims to redact sensitive information (e.g., API keys, tokens, JWTs) from command-line arguments. However, there is no evidence of robust testing for edge cases (e.g., obfuscated or encoded secrets).
     • Actionable Fix: Add comprehensive tests to ensure all sensitive information is reliably detected and redacted, including edge cases like base64-encoded secrets.

---

🟡 WARNING: Potential Breaking Changes

1. Lifecycle Manager API

   • The LifecycleManager introduces new methods (request_provisioning, approve, activate, etc.) that may not be backward-compatible with existing agent management workflows.
     • Actionable Fix: Clearly document these changes in the release notes and provide migration guides for users of the previous API.

2. Agent Discovery CLI

   • The new CLI commands (agent-discovery scan, inventory, reconcile) introduce a new interface for users. This could lead to confusion if not properly documented.
     • Actionable Fix: Ensure the CLI commands are thoroughly documented, and consider providing examples for common use cases.

---

💡 Suggestions for Improvement

1. Thread Safety

   • The LifecycleManager and AgentInventory classes appear to use file-based storage for state persistence. If these classes are used in a multi-threaded or multi-process environment, there could be race conditions.
     • Suggestion: Use file locks or a thread-safe database (e.g., SQLite) to ensure consistent state updates.

2. Type Safety

   • The LifecyclePolicy and CredentialPolicy classes use type annotations, but there is no evidence of runtime validation (e.g., Pydantic models).
     • Suggestion: Use Pydantic models for these classes to enforce type safety and validate input at runtime.

3. Audit Trail Immutability

   • The audit trail is described as "immutably recorded," but there is no mention of how immutability is enforced (e.g., append-only logs, cryptographic signatures).
     • Suggestion: Use a tamper-evident mechanism (e.g., Merkle trees or blockchain) to ensure the integrity of the audit trail.

4. Dependency Risk

   • The agent-discovery package introduces new dependencies (e.g., for GitHub scanning). These dependencies could introduce supply chain risks.
     • Suggestion: Perform a security audit of the new dependencies and consider making them optional.

5. Backward Compatibility

   • The addition of new tutorials and CLI commands is a positive step, but it may overwhelm new users.
     • Suggestion: Provide a "Getting Started" guide that focuses on the most common use cases.

---

✅ Positive Aspects

1. Comprehensive Documentation

   • The new tutorials (29 and 30) are well-written and provide clear, step-by-step instructions for using the new features.

2. Test Coverage

   • The pull request mentions 24 new tests, which is a good indicator of quality. However, it would be helpful to see a summary of the test coverage.

3. Modular Design

   • The agent-discovery package uses a plugin architecture for scanners, making it easy to extend.

4. OWASP Agentic Top 10 Compliance

   • The focus on credential rotation, orphan detection, and audit trails aligns well with OWASP's recommendations for secure agent management.

---

Summary of Recommendations

Critical Fixes

• Implement robust credential revocation mechanisms.
• Cryptographically verify heartbeats to prevent spoofing.
• Authenticate discovered agent identities to prevent false negatives.
• Add comprehensive tests for redacting sensitive information in the ProcessScanner.

Warnings

• Document API changes and provide migration guides.
• Ensure CLI commands are well-documented and user-friendly.

Suggestions

• Use thread-safe mechanisms for state persistence.
• Enforce type safety with Pydantic models.
• Implement tamper-evident audit trails.
• Audit new dependencies for supply chain risks.
• Create a "Getting Started" guide for new users.

---

Final Assessment

This pull request introduces valuable features for agent lifecycle management and discovery, addressing critical gaps in the Agent Governance Toolkit. However, several security issues and potential breaking changes need to be addressed before merging. Once these concerns are resolved, the new functionality will significantly enhance the toolkit's capabilities.

[github-actions]

🤖 AI Agent: test-generator — `packages/agent-discovery/src/agent_discovery/__init__.py`

🧪 Test Coverage Analysis

packages/agent-discovery/src/agent_discovery/__init__.py

• ✅ Existing coverage: This file primarily serves as an initializer for the agent_discovery package. It likely doesn't contain significant logic that requires testing.
• ❌ Missing coverage: None identified.
• 💡 Suggested test cases: None needed for this file.

---

packages/agent-discovery/src/agent_discovery/cli/__init__.py

• ✅ Existing coverage: This file likely initializes the CLI module and does not contain significant logic.
• ❌ Missing coverage: None identified.
• 💡 Suggested test cases: None needed for this file.

---

packages/agent-discovery/src/agent_discovery/cli/main.py

• ✅ Existing coverage: The CLI commands (scan, inventory, reconcile) are likely covered by existing tests for the CLI functionality.
• ❌ Missing coverage:
  • Edge cases for invalid command-line arguments.
  • Error handling for missing or malformed configuration files.
  • Behavior when required dependencies (e.g., agent-discovery[github]) are not installed.
• 💡 Suggested test cases:
  1. test_cli_invalid_args — Ensure the CLI gracefully handles invalid arguments and provides helpful error messages.
  2. test_cli_missing_dependency — Verify the CLI warns the user if a required dependency is missing (e.g., GitHub scanner).
  3. test_cli_invalid_registry_file — Test behavior when the registry file is missing or malformed during reconciliation.

---

packages/agent-discovery/src/agent_discovery/inventory.py

• ✅ Existing coverage: Basic inventory operations (e.g., adding agents, deduplication) are likely covered.
• ❌ Missing coverage:
  • Edge cases for deduplication logic (e.g., agents with similar but not identical fingerprints).
  • Handling of corrupted or partially written inventory files.
  • Concurrency scenarios where multiple scanners update the inventory simultaneously.
• 💡 Suggested test cases:
  1. test_inventory_deduplication_edge_cases — Test deduplication logic with agents having similar but not identical fingerprints.
  2. test_inventory_corrupted_file — Verify behavior when the inventory file is corrupted or partially written.
  3. test_inventory_concurrent_updates — Simulate multiple scanners updating the inventory concurrently and ensure no data loss or corruption.

---

packages/agent-discovery/src/agent_discovery/models.py

• ✅ Existing coverage: Core models like DiscoveredAgent and Evidence are likely covered.
• ❌ Missing coverage:
  • Validation of model constraints (e.g., required fields, valid confidence scores).
  • Handling of malformed input data when creating models.
• 💡 Suggested test cases:
  1. test_discovered_agent_validation — Ensure DiscoveredAgent enforces required fields and valid confidence scores.
  2. test_evidence_invalid_data — Verify behavior when creating Evidence with malformed or missing data.

---

packages/agent-discovery/src/agent_discovery/reconciler.py

• ✅ Existing coverage: Basic reconciliation logic (e.g., matching discovered agents to the registry) is likely covered.
• ❌ Missing coverage:
  • Edge cases for matching logic (e.g., partial matches, multiple matches).
  • Behavior when the registry contains invalid or incomplete data.
  • Handling of large registries or inventories.
• 💡 Suggested test cases:
  1. test_reconciler_partial_matches — Test behavior when a discovered agent partially matches multiple registry entries.
  2. test_reconciler_invalid_registry_data — Verify behavior when the registry contains invalid or incomplete data.
  3. test_reconciler_large_inventory — Simulate reconciliation with a large inventory and registry to test performance and memory usage.

---

packages/agent-discovery/src/agent_discovery/risk.py

• ✅ Existing coverage: Basic risk scoring logic is likely covered.
• ❌ Missing coverage:
  • Edge cases for risk factor calculations (e.g., agents with no identity, multiple high-risk factors).
  • Behavior when risk factors are missing or misconfigured.
• 💡 Suggested test cases:
  1. test_risk_scorer_no_identity — Verify that agents with no identity receive the correct risk score.
  2. test_risk_scorer_multiple_high_risk_factors — Test risk scoring for agents with multiple high-risk factors.
  3. test_risk_scorer_missing_factors — Ensure the scorer handles missing or misconfigured risk factors gracefully.

---

packages/agent-discovery/src/agent_discovery/scanners/__init__.py

• ✅ Existing coverage: This file likely initializes the scanners module and does not contain significant logic.
• ❌ Missing coverage: None identified.
• 💡 Suggested test cases: None needed for this file.

---

packages/agent-discovery/src/agent_discovery/scanners/base.py

• ✅ Existing coverage: Basic functionality of the BaseScanner abstract class is likely covered.
• ❌ Missing coverage:
  • Validation of scanner registration in the registry.
  • Behavior when a custom scanner does not implement required methods.
• 💡 Suggested test cases:
  1. test_base_scanner_registration — Verify that custom scanners are correctly registered in the registry.
  2. test_base_scanner_missing_methods — Ensure the system raises appropriate errors when a custom scanner does not implement required methods.

---

packages/agent-discovery/src/agent_discovery/scanners/config.py

• ✅ Existing coverage: Basic functionality of the ConfigScanner is likely covered.
• ❌ Missing coverage:
  • Edge cases for deeply nested directories or circular symlinks.
  • Handling of unsupported or malformed configuration files.
• 💡 Suggested test cases:
  1. test_config_scanner_deeply_nested — Test behavior when scanning deeply nested directories.
  2. test_config_scanner_circular_symlinks — Verify the scanner handles circular symlinks gracefully.
  3. test_config_scanner_malformed_files — Ensure the scanner skips unsupported or malformed configuration files without crashing.

---

packages/agent-discovery/src/agent_discovery/scanners/github.py

• ✅ Existing coverage: Basic functionality of the GitHubScanner is likely covered.
• ❌ Missing coverage:
  • Handling of rate limits or API errors from GitHub.
  • Behavior when scanning large organizations with many repositories.
• 💡 Suggested test cases:
  1. test_github_scanner_rate_limiting — Simulate GitHub API rate limits and verify the scanner retries or fails gracefully.
  2. test_github_scanner_large_org — Test performance and memory usage when scanning a large organization with many repositories.
  3. test_github_scanner_invalid_credentials — Verify behavior when invalid GitHub credentials are provided.

---

packages/agent-discovery/src/agent_discovery/scanners/process.py

• ✅ Existing coverage: Basic functionality of the ProcessScanner is likely covered.
• ❌ Missing coverage:
  • Edge cases for processes with obfuscated or incomplete command-line arguments.
  • Handling of processes with restricted permissions.
• 💡 Suggested test cases:
  1. test_process_scanner_obfuscated_args — Test detection of agents with obfuscated or incomplete command-line arguments.
  2. test_process_scanner_restricted_permissions — Verify behavior when the scanner encounters processes with restricted permissions.

---

packages/agent-marketplace/src/agent_marketplace/installer.py

• ✅ Existing coverage: Basic installation logic is likely covered.
• ❌ Missing coverage:
  • Handling of installation failures (e.g., network issues, unsupported platforms).
  • Validation of downloaded packages (e.g., checksum verification).
• 💡 Suggested test cases:
  1. test_installer_network_failure — Simulate network issues during installation and verify graceful handling.
  2. test_installer_checksum_verification — Ensure the installer validates package checksums to prevent tampering.

---

packages/agent-mesh/src/agentmesh/lifecycle/__init__.py

• ✅ Existing coverage: This file likely initializes the lifecycle module and does not contain significant logic.
• ❌ Missing coverage: None identified.
• 💡 Suggested test cases: None needed for this file.

---

packages/agent-mesh/src/agentmesh/lifecycle/credentials.py

• ✅ Existing coverage: Basic credential management functionality is likely covered.
• ❌ Missing coverage:
  • Edge cases for credential expiration and revocation.
  • Handling of invalid or corrupted credential data.
• 💡 Suggested test cases:
  1. test_credentials_expiration — Verify behavior when credentials expire.
  2. test_credentials_revocation — Ensure credentials are properly revoked during decommissioning.
  3. test_credentials_invalid_data — Test handling of invalid or corrupted credential data.

---

packages/agent-mesh/src/agentmesh/lifecycle/manager.py

• ✅ Existing coverage: Basic lifecycle management functionality (e.g., provisioning, activation) is likely covered.
• ❌ Missing coverage:
  • Edge cases for orphan detection and reclaiming.
  • Handling of invalid state transitions (e.g., activating a decommissioned agent).
• 💡 Suggested test cases:
  1. test_lifecycle_orphan_detection — Verify orphan detection logic for agents with missing heartbeats.
  2. test_lifecycle_invalid_state_transition — Ensure invalid state transitions (e.g., activating a decommissioned agent) are rejected.

---

packages/agent-mesh/src/agentmesh/lifecycle/models.py

• ✅ Existing coverage: Core lifecycle models (e.g., Agent, LifecycleEvent) are likely covered.
• ❌ Missing coverage:
  • Validation of model constraints (e.g., valid state transitions).
  • Handling of malformed input data.
• 💡 Suggested test cases:
  1. test_lifecycle_event_validation — Ensure LifecycleEvent enforces valid state transitions.
  2. test_agent_invalid_data — Verify behavior when creating an Agent with malformed or missing data.

---

packages/agent-mesh/src/agentmesh/lifecycle/orphan_detector.py

• ✅ Existing coverage: Basic orphan detection functionality is likely covered.
• ❌ Missing coverage:
  • Edge cases for agents with intermittent heartbeats.
  • Handling of large fleets with many orphaned agents.
• 💡 Suggested test cases:
  1. test_orphan_detector_intermittent_heartbeats — Test behavior for agents with intermittent heartbeats.
  2. test_orphan_detector_large_fleet — Verify performance and memory usage when scanning a large fleet.

---

packages/agent-mesh/src/agentmesh/marketplace/_marketplace_impl.py

• ✅ Existing coverage: Basic marketplace functionality is likely covered.
• ❌ Missing coverage:
  • Handling of invalid marketplace configurations.
  • Edge cases for marketplace interactions (e.g., unavailable services).
• 💡 Suggested test cases:
  1. test_marketplace_invalid_config — Verify behavior with invalid marketplace configurations.
  2. test_marketplace_service_unavailable — Test handling of unavailable services during marketplace interactions.

---

packages/agent-mesh/src/agentmesh/trust/handshake.py

• ✅ Existing coverage: Basic trust handshake functionality is likely covered.
• ❌ Missing coverage:
  • Edge cases for expired or revoked certificates.
  • Handling of mismatched trust scores during handshake.
• 💡 Suggested test cases:
  1. test_handshake_expired_certificate — Verify behavior when an expired certificate is used during a handshake.
  2. test_handshake_mismatched_trust_score — Ensure the handshake fails gracefully when trust scores do not match.

[github-actions]

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

Security Analysis of the Pull Request

This pull request introduces agent lifecycle management and shadow AI discovery functionalities to the Agent Governance Toolkit (AGT). While these features are critical for enhancing the governance of AI agents, they also introduce potential security risks. Below is a detailed analysis of the changes, categorized by the security concerns outlined in the prompt.

---

1. Prompt Injection Defense Bypass

No evidence of prompt injection vulnerabilities was identified in the changes. The new features focus on agent lifecycle management and discovery, which do not directly involve user-supplied prompts or natural language processing.

Rating: 🔵 LOW

---

2. Policy Engine Circumvention

The lifecycle management system introduces a policy engine for agent provisioning, approval, and decommissioning. However, there are potential risks:

Finding 1: Lack of validation for actor in provisioning and approval

The actor field in the request_provisioning and approve methods is not validated to ensure that the actor is authorized to perform these actions. This could allow unauthorized users to provision or approve agents.

Attack Vector: An attacker could impersonate an admin by providing a fake actor email address, bypassing the approval process and provisioning unauthorized agents.

Recommendation:

• Implement strict validation of the actor field against a list of authorized users or roles.
• Use a secure authentication mechanism (e.g., OAuth, SAML) to verify the identity of the actor.

Rating: 🔴 CRITICAL

---

3. Trust Chain Weaknesses

The lifecycle management system relies on short-lived credentials and cryptographic identities (DIDs/SPIFFE). However, there are gaps in the implementation:

Finding 2: Lack of SPIFFE/SVID validation in agent activation

The activate method issues credentials to agents but does not validate their SPIFFE/SVID identities. This could allow malicious agents to obtain valid credentials.

Attack Vector: A malicious agent could request activation without a valid SPIFFE/SVID, gaining access to the system.

Recommendation:

• Enforce SPIFFE/SVID validation during the activation process.
• Reject activation requests from agents without valid cryptographic identities.

Rating: 🔴 CRITICAL

---

4. Credential Exposure

The agent-discovery package includes a process scanner that redacts sensitive information (e.g., API keys, tokens) from command-line arguments. However, there are potential risks:

Finding 3: Insufficient redaction of sensitive data

The redaction mechanism in the process scanner is not explicitly tested for edge cases, such as obfuscated or encoded secrets.

Attack Vector: Sensitive credentials could be exposed if they are not properly redacted from command-line arguments.

Recommendation:

• Add comprehensive tests to ensure that all sensitive data formats (e.g., base64-encoded strings) are redacted.
• Use a library specifically designed for sensitive data redaction.

Rating: 🟠 HIGH

---

5. Sandbox Escape

No evidence of sandboxing or container isolation mechanisms was identified in the changes. However, the agent-discovery package scans local processes and files, which could be exploited by malicious agents to execute arbitrary code.

Attack Vector: A malicious agent could inject code into a process or configuration file, exploiting the scanner's lack of isolation.

Recommendation:

• Run the agent-discovery scanner in a sandboxed environment (e.g., Docker container) with restricted permissions.
• Validate and sanitize all inputs before processing.

Rating: 🟠 HIGH

---

6. Deserialization Attacks

The agent-discovery package uses JSON for inventory storage and reconciliation. There is no evidence of unsafe deserialization in the provided code.

Rating: 🔵 LOW

---

7. Race Conditions

The lifecycle management system includes credential rotation and orphan detection mechanisms, which could be vulnerable to race conditions:

Finding 4: Potential TOCTOU in credential rotation

The check_and_rotate method does not lock credentials during the rotation process, creating a potential time-of-check-to-time-of-use (TOCTOU) vulnerability.

Attack Vector: An attacker could exploit the gap between checking and rotating credentials to use expired credentials.

Recommendation:

• Implement locking mechanisms to prevent concurrent access to credentials during rotation.
• Use atomic operations for credential updates.

Rating: 🟠 HIGH

---

8. Supply Chain

The new agent-discovery package introduces dependencies, including optional ones for GitHub integration. While no malicious dependencies were identified, the use of optional dependencies increases the attack surface.

Attack Vector: Dependency confusion or typosquatting attacks could compromise the system.

Recommendation:

• Use dependency pinning to specific, verified versions.
• Regularly audit dependencies for vulnerabilities using tools like pip-audit or safety.

Rating: 🟡 MEDIUM

---

Summary of Findings

Finding	Rating	Attack Vector	Recommendation
Lack of validation for actor in provisioning and approval	🔴 CRITICAL	Unauthorized users could provision or approve agents by impersonating an admin.	Validate actor against authorized users and use secure authentication mechanisms.
Lack of SPIFFE/SVID validation in activation	🔴 CRITICAL	Malicious agents could obtain credentials without valid cryptographic identities.	Enforce SPIFFE/SVID validation during activation.
Insufficient redaction of sensitive data	🟠 HIGH	Sensitive credentials could be exposed if not properly redacted from command-line arguments.	Add comprehensive redaction tests and use a dedicated redaction library.
Potential TOCTOU in credential rotation	🟠 HIGH	Attackers could exploit gaps in the credential rotation process to use expired credentials.	Implement locking mechanisms and atomic operations for credential updates.
Lack of sandboxing in agent-discovery	🟠 HIGH	Malicious agents could inject code into processes or files, exploiting the scanner's lack of isolation.	Run the scanner in a sandboxed environment with restricted permissions.
Dependency management risks	🟡 MEDIUM	Dependency confusion or typosquatting attacks could compromise the system.	Use dependency pinning and regularly audit dependencies for vulnerabilities.

---

Final Recommendation

The pull request introduces valuable features but contains critical security risks that must be addressed before merging. Specifically:

1. Implement validation for actor fields in provisioning and approval workflows.
2. Enforce SPIFFE/SVID validation during agent activation.
3. Address redaction, TOCTOU, and sandboxing issues to mitigate potential vulnerabilities.

After addressing these issues, the pull request can be re-evaluated for security compliance.

[imran-siddique]

Shipped in v3.1.0! ✅ This is already getting great feedback from the CPG pilot team who needed credential rotation + orphan detection for their supply chain agents.