feat: add quantum-safe ML-DSA-65 signing alongside Ed25519

[imran-siddique]

Addresses gap #4: post-quantum crypto. ML-DSA-65 (FIPS 204, NIST Level 3) via dilithium-py alongside existing Ed25519. SigningProvider ABC, create_signer() factory, dual-signing support, SignatureBundle with audit metadata. 24 tests passing. Optional dependency - Ed25519 unchanged.

[github-actions]

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

📝 Documentation Sync Report

Issues Found

1. ❌ cli() in packages/agent-compliance/src/agent_compliance/cli/agt.py — missing docstring.
2. ❌ verify() in packages/agent-compliance/src/agent_compliance/cli/agt.py — missing docstring.
3. ❌ integrity() in packages/agent-compliance/src/agent_compliance/cli/agt.py — missing docstring.
4. ❌ lint_policy() in packages/agent-compliance/src/agent_compliance/cli/agt.py — missing docstring.
5. ❌ doctor() in packages/agent-compliance/src/agent_compliance/cli/agt.py — missing docstring.
6. ⚠️ packages/agent-compliance/README.md — no mention of the new agt CLI or its commands.
7. ⚠️ CHANGELOG.md — no entry for the addition of the agt CLI and its commands.
8. ⚠️ examples/quickstart.py — outdated usage instructions; the agt CLI should be mentioned.

Suggestions

• 💡 Add docstrings for the following functions in packages/agent-compliance/src/agent_compliance/cli/agt.py:

  • cli(output_json: bool, verbose: bool, quiet: bool, no_color: bool) -> None
  • verify(ctx_obj: AgtContext, badge: bool) -> None
  • integrity(ctx_obj: AgtContext, manifest: Optional[str], generate: Optional[str]) -> None
  • lint_policy(ctx_obj: AgtContext, path: str, strict: bool) -> None
  • doctor(ctx_obj: AgtContext) -> None
    Each docstring should explain the purpose, parameters, return values, and exceptions.

• 💡 Update packages/agent-compliance/README.md to include a new section describing the agt CLI, its purpose, and usage examples for commands like verify, integrity, lint-policy, and doctor.

• 💡 Add an entry to CHANGELOG.md summarizing the addition of the agt CLI, its commands, and any new functionality introduced.

• 💡 Update examples/quickstart.py to reference the agt CLI instead of the previous command-line usage.

• 💡 Ensure all new public APIs in packages/agent-compliance/src/agent_compliance/cli/agt.py have complete type annotations (already present).

Additional Notes

• The agt CLI is a significant addition to the project, and its documentation should reflect its importance and functionality.
• The added click commands are well-structured but lack docstrings, which are essential for maintainability and clarity.
• The optional dependency on click should also be mentioned in the README.md under installation instructions.

Please address the issues and suggestions above to ensure the documentation is fully in sync with the new changes. Let me know if you need further assistance!

[github-actions]

🤖 AI Agent: breaking-change-detector — Summary

🔍 API Compatibility Report

Summary

This pull request introduces quantum-safe ML-DSA-65 signing alongside Ed25519, adds a new CLI entry point (agt), and includes several new features and dependencies. No breaking changes were detected in the existing public API. The changes are primarily additive.

Findings

Severity	Package	Change	Impact
🔵	agent-compliance	Added new CLI entry point agt	New functionality, not breaking
🔵	agent-compliance	Added click as a dependency	New dependency, not breaking
🔵	agent-compliance	Added agt.commands plugin discovery	New extensibility, not breaking
🔵	agent-compliance	Added GovernanceVerifier class	New API, not breaking
🔵	agent-compliance	Added IntegrityVerifier class	New API, not breaking
🔵	agent-compliance	Added lint_path function	New API, not breaking

Migration Guide

No migration steps are necessary as no breaking changes were identified. Downstream users can adopt the new features without modifying existing code.

Additional Notes

• The new CLI entry point (agt) and its subcommands (verify, integrity, lint-policy, doctor) should be documented for users.
• The optional dependency on click should be clearly communicated to users, especially for those who may need to install it separately.
• The added support for ML-DSA-65 signing is a significant feature and should be highlighted in the release notes.

✅ No breaking changes detected.

[github-actions]

🤖 AI Agent: test-generator — `packages/agent-compliance/src/agent_compliance/cli/agt.py`

🧪 Test Coverage Analysis

packages/agent-compliance/src/agent_compliance/cli/agt.py

• ✅ Existing coverage:
  • Basic CLI command registration and execution.
  • Verification of verify, integrity, and lint-policy commands.
  • Error handling for known exceptions.
  • Plugin discovery mechanism.
• ❌ Missing coverage:
  • Edge cases for --json, --verbose, --quiet, and --no-color options.
  • Error handling for unknown exceptions.
  • Plugin discovery failures.
  • doctor command functionality, including:
    • Missing or invalid configuration files.
    • Missing or incompatible plugins.
    • Partial installation of required packages.
  • Interaction between commands and the AgtContext object.
• 💡 Suggested test cases:
  1. test_agt_verify_json_output — Ensure verify command outputs correct JSON when --json is used.
  2. test_agt_integrity_generate_manifest — Test the integrity command with --generate and validate the generated manifest.
  3. test_agt_integrity_missing_manifest — Test the integrity command with a missing manifest file.
  4. test_agt_lint_policy_strict_mode — Verify that lint-policy fails when --strict is used and warnings are present.
  5. test_agt_doctor_partial_installation — Simulate a scenario where some required packages are missing and verify the output.
  6. test_agt_doctor_plugin_discovery_failure — Simulate a failure in plugin discovery and verify the error handling.
  7. test_agt_error_handling_unknown_exception — Simulate an unknown exception and verify the error message.

---

packages/agent-compliance/src/agent_compliance/cli/main.py

• ✅ Existing coverage:
  • Basic CLI entry point functionality.
• ❌ Missing coverage:
  • None (file primarily serves as an entry point).
• 💡 Suggested test cases:
  • No additional tests needed for this file.

---

packages/agent-compliance/src/agent_compliance/governance/__init__.py

• ✅ Existing coverage:
  • Module import and initialization.
• ❌ Missing coverage:
  • None (file primarily serves as a module initializer).
• 💡 Suggested test cases:
  • No additional tests needed for this file.

---

packages/agent-compliance/src/agent_compliance/governance/attestation_validator.py

• ✅ Existing coverage:
  • Validation of governance attestation checklists.
• ❌ Missing coverage:
  • Edge cases for invalid or malformed attestation checklists.
  • Handling of missing or incomplete checklist items.
  • Validation of conflicting checklist items.
• 💡 Suggested test cases:
  1. test_attestation_validator_invalid_checklist — Validate behavior with an invalid checklist format.
  2. test_attestation_validator_missing_items — Test validation with missing required checklist items.
  3. test_attestation_validator_conflicting_items — Test validation with conflicting checklist items.

---

packages/agent-compliance/src/agent_compliance/security/__init__.py

• ✅ Existing coverage:
  • Module import and initialization.
• ❌ Missing coverage:
  • None (file primarily serves as a module initializer).
• 💡 Suggested test cases:
  • No additional tests needed for this file.

---

packages/agent-compliance/src/agent_compliance/security/scanner.py

• ✅ Existing coverage:
  • Basic scanning functionality.
• ❌ Missing coverage:
  • Edge cases for malformed inputs or unsupported file formats.
  • Handling of oversized payloads.
  • Scanning performance under high concurrency.
• 💡 Suggested test cases:
  1. test_scanner_malformed_input — Test behavior with malformed input files.
  2. test_scanner_unsupported_format — Validate handling of unsupported file formats.
  3. test_scanner_oversized_payload — Test scanning of oversized payloads.
  4. test_scanner_concurrent_execution — Simulate high concurrency and verify correct behavior.

---

Other Files

For the remaining files, the changes primarily involve documentation updates, dependency updates, or minor code adjustments. These do not introduce new functionality or significant changes that require additional test cases. However, ensure that existing tests for related functionality are passing.

If any of the files contain new or modified logic that isn't explicitly covered here, please provide more details for further analysis.

[github-actions]

🤖 AI Agent: code-reviewer

Pull Request Review for feat: add quantum-safe ML-DSA-65 signing alongside Ed25519

---

🔴 CRITICAL: Security Issues

1. Lack of Cryptographic Validation for ML-DSA-65 Implementation:

   • There is no evidence in the provided diff that the ML-DSA-65 implementation has been rigorously validated against the FIPS 204 or NIST Level 3 standards. Without proper validation, the implementation may be vulnerable to cryptographic attacks.
   • Action: Ensure that the ML-DSA-65 implementation is tested against known test vectors and adheres to the standard. Add unit tests to verify the correctness of the cryptographic operations.

2. Dual-Signing Mechanism:

   • The introduction of dual-signing (Ed25519 + ML-DSA-65) increases the attack surface. If either signature scheme is compromised, the overall security of the system is at risk.
   • Action: Clearly document the security implications of dual-signing. Consider adding a configuration option to allow users to disable dual-signing if not required.

3. Dependency on dilithium-py:

   • The dilithium-py library is used for ML-DSA-65, but there is no information about its security audits or compliance with NIST standards.
   • Action: Verify the security of the dilithium-py library. Ensure it is actively maintained, has undergone third-party audits, and is not vulnerable to known attacks.

4. Error Handling in CLI:

   • The _handle_error function does not log stack traces for unexpected exceptions unless the AGENTOS_DEBUG environment variable is set. This could lead to missed debugging opportunities for critical issues.
   • Action: Log stack traces for unexpected exceptions by default, or provide an explicit flag to enable detailed error logging.

---

🟡 WARNING: Potential Breaking Changes

1. New CLI Entry Point (agt):

   • The addition of a new CLI entry point (agt) may conflict with existing workflows or scripts that rely on the old entry points (agent-governance-toolkit, agent-governance, agent-compliance).
   • Action: Clearly document the new CLI entry point and provide a deprecation notice for the old entry points if they are intended to be removed in the future.

2. Optional Dependency on click:

   • Adding click as a dependency for the CLI introduces a new requirement for users. While click is a widely used library, this change could break environments that do not have click installed.
   • Action: Ensure that the dependency on click is clearly documented, and provide instructions for installing it if not included in the default installation.

---

💡 Suggestions for Improvement

1. Thread Safety in Cryptographic Operations:

   • The code does not provide any guarantees about thread safety when using the new ML-DSA-65 signing mechanism.
   • Suggestion: Document whether the dilithium-py library is thread-safe. If not, implement appropriate locking mechanisms to ensure thread safety during cryptographic operations.

2. Type Annotations:

   • The new code lacks type annotations in several places, such as the _discover_plugins and _get_package_version functions.
   • Suggestion: Add type annotations to improve code readability and catch potential type-related bugs during development.

3. Pydantic Model Validation:

   • There is no evidence of Pydantic model validation for the new SignatureBundle or other related data structures.
   • Suggestion: Use Pydantic models to validate the structure and types of data used in the new signing mechanism.

4. Test Coverage:

   • While the PR mentions 24 passing tests, there is no evidence of tests specifically targeting edge cases for the ML-DSA-65 implementation or the dual-signing mechanism.
   • Suggestion: Add comprehensive tests for the following scenarios:
     • Invalid keys for ML-DSA-65.
     • Corrupted or tampered signatures.
     • Performance benchmarks for dual-signing.
     • Compatibility tests for different Python versions (3.9–3.12).

5. Backward Compatibility:

   • The new CLI (agt) introduces a unified interface, but it is unclear if existing users will be affected by this change.
   • Suggestion: Provide backward compatibility for existing CLI commands or offer a migration guide for users.

6. Documentation:

   • The documentation updates are minimal and do not provide sufficient details about the new features.
   • Suggestion: Update the documentation to include:
     • Detailed usage examples for the new CLI commands.
     • Security considerations for dual-signing.
     • Information about the ML-DSA-65 implementation and its compliance with standards.

7. Code Quality:

   • The _handle_error function could be refactored to reduce code duplication. The error handling logic for JSON and non-JSON outputs is repeated multiple times.
   • Suggestion: Extract the common error-handling logic into a separate function to improve maintainability.

---

Summary of Recommendations

• 🔴 Critical: Validate the ML-DSA-65 implementation against standards and ensure the security of the dilithium-py library.
• 🟡 Warning: Document the new CLI entry point and ensure backward compatibility.
• 💡 Suggestions: Improve thread safety, add type annotations, enhance test coverage, and update documentation.

Let me know if you need further clarification or assistance!

[github-actions]

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

Security Analysis of the Pull Request

This pull request introduces quantum-safe ML-DSA-65 signing alongside the existing Ed25519 signing mechanism. It also includes a new CLI (agt.py) for managing the Agent Governance Toolkit. Below is an analysis of the changes based on the specified security concerns:

---

1. Prompt Injection Defense Bypass

No issues identified.

• The changes in this PR do not directly interact with user-provided prompts or natural language inputs. The CLI commands and their parameters are well-defined and do not involve free-form text inputs that could be exploited for prompt injection.

---

2. Policy Engine Circumvention

🔴 CRITICAL
Issue: The PR introduces a new signing mechanism (ML-DSA-65) but does not enforce strict validation of the signing algorithm used in critical policy decisions. If a malicious actor can downgrade or bypass the quantum-safe signing mechanism, they could compromise the integrity of the governance policies.
Attack Vector: An attacker could craft a policy or signature bundle that uses a weaker or unsupported signing algorithm, potentially bypassing the intended quantum-safe guarantees.
Recommendation:

• Implement strict validation to ensure that only approved signing algorithms (e.g., ML-DSA-65 and Ed25519) are accepted.
• Add a fallback mechanism to reject any unrecognized or unsupported algorithms.
• Include unit tests to verify that unsupported algorithms are rejected.

---

3. Trust Chain Weaknesses

🟠 HIGH
Issue: The PR does not include sufficient details about how the trust chain for ML-DSA-65 is established and verified. Specifically, there is no mention of certificate pinning or SPIFFE/SVID validation for the new signing mechanism.
Attack Vector: An attacker could exploit weaknesses in the trust chain to inject a malicious certificate or compromise the signing process.
Recommendation:

• Clearly document and implement the trust chain validation process for ML-DSA-65.
• Ensure that SPIFFE/SVID validation is performed for all certificates used in the signing process.
• Add certificate pinning to prevent man-in-the-middle attacks.

---

4. Credential Exposure

🔵 LOW
Issue: No sensitive credentials or secrets are exposed in the code changes.
Recommendation:

• Continue to ensure that no secrets are logged or exposed in error messages or debug output.

---

5. Sandbox Escape

🟡 MEDIUM
Issue: The CLI (agt.py) introduces commands that interact with the filesystem (e.g., --manifest, --generate, lint-policy). There is no explicit mention of sandboxing or isolation for these operations.
Attack Vector: A malicious user could exploit these commands to access or modify unauthorized files on the host system.
Recommendation:

• Implement sandboxing or file access restrictions for CLI commands that interact with the filesystem.
• Validate all file paths to ensure they do not traverse outside allowed directories (e.g., prevent ../../ path traversal).
• Add unit tests to verify that unauthorized file access is blocked.

---

6. Deserialization Attacks

🟠 HIGH
Issue: The CLI and other components use YAML and JSON parsing (e.g., lint-policy, integrity). If these inputs are not sanitized, they could be exploited for deserialization attacks.
Attack Vector: An attacker could craft a malicious YAML or JSON file to execute arbitrary code or cause denial-of-service.
Recommendation:

• Use safe YAML loaders (e.g., yaml.safe_load instead of yaml.load).
• Validate the structure and content of parsed data before processing.
• Add tests with malicious payloads to ensure the parser is secure.

---

7. Race Conditions

🟡 MEDIUM
Issue: The CLI commands that interact with the filesystem (e.g., --manifest, --generate) could be vulnerable to time-of-check-to-time-of-use (TOCTOU) race conditions.
Attack Vector: An attacker could replace a file or directory after it has been checked but before it is used, potentially leading to unauthorized access or execution.
Recommendation:

• Use atomic file operations to prevent TOCTOU vulnerabilities.
• Avoid relying on file existence checks before performing operations. Instead, use secure file handling techniques, such as opening files with exclusive access.

---

8. Supply Chain

🟠 HIGH
Issue: The PR introduces a new dependency, click, but does not specify a strict version range. This increases the risk of dependency confusion or typosquatting attacks.
Attack Vector: An attacker could publish a malicious package with a similar name or exploit a vulnerability in an unpinned version of click.
Recommendation:

• Pin the click dependency to a specific version or range (e.g., click>=8.0,<8.2).
• Use a dependency scanner to verify the integrity of all dependencies.
• Add a supply chain security check to the CI/CD pipeline (e.g., pip-audit or safety).

---

Summary of Findings

Category	Severity	Description
Prompt Injection Defense	🔵 LOW	No issues identified.
Policy Engine Circumvention	🔴 CRITICAL	Lack of strict validation for signing algorithms.
Trust Chain Weaknesses	🟠 HIGH	Insufficient details on trust chain validation for ML-DSA-65.
Credential Exposure	🔵 LOW	No sensitive credentials exposed.
Sandbox Escape	🟡 MEDIUM	CLI commands lack sandboxing or file access restrictions.
Deserialization Attacks	🟠 HIGH	Potential for unsafe YAML/JSON deserialization.
Race Conditions	🟡 MEDIUM	Possible TOCTOU vulnerabilities in file operations.
Supply Chain	🟠 HIGH	Dependency (click) not pinned to a specific version or range.

---

Recommended Actions

1. Policy Engine Validation: Enforce strict validation of signing algorithms and reject unsupported ones.
2. Trust Chain: Implement SPIFFE/SVID validation and certificate pinning for ML-DSA-65.
3. Sandboxing: Restrict file access for CLI commands and validate file paths.
4. Deserialization: Use safe loaders and validate parsed data.
5. Race Conditions: Use atomic file operations to prevent TOCTOU vulnerabilities.
6. Dependency Management: Pin the click dependency and implement supply chain security checks.

These changes are critical to ensure the security and integrity of the Agent Governance Toolkit, which serves as a foundational security layer for downstream users.

[imran-siddique]

Shipped in v3.1.0! 🔒 ML-DSA-65 is our first step toward post-quantum readiness. Next: ML-KEM for key exchange.