feat(dotnet): match python parity for OSS package

[jackbatzner]

Description

Bring agent-governance-dotnet much closer to Python parity for the OSS SDK surface by expanding identity, registry, JWK/JWKS/DID, and policy features, then aligning tests and public docs with the new contract.

Key updates:

• expand AgentIdentity with canonical did:mesh: normalization, richer metadata, capability/delegation helpers, and compatibility signing cleanup
• expand IdentityRegistry with sponsor lookup, trust checks, optional attestation gating, and cascade revocation
• add richer JWK/JWKS/DID document import/export support
• add JSON policy loading, organization scope support, richer PolicyDecision metadata, and normalized agent_did evaluation context
• refresh .NET tests and docs to reflect the new parity surface and remaining .NET 8 signing limitation

Maintainer review on this branch found no blocking issues.

Type of Change

• New feature (non-breaking change that adds functionality)
• Documentation update
• Maintenance (dependency updates, CI/CD, refactoring)

Package(s) Affected

• agent-governance
• docs / root

Checklist

• I have added tests that prove my fix/feature works
• All new and existing tests pass (pytest)
• I have updated documentation as needed

Attribution & Prior Art

• This contribution does not contain code copied or derived from other projects without attribution
• Any external projects that inspired this design are credited in code comments or documentation
• If this PR implements functionality similar to an existing open-source project, I have listed it below

Prior art / related projects (if any):

• Python packages/agent-mesh SDK in this repository served as the parity reference surface

Related Issues

[github-actions]

🤖 AI Agent: code-reviewer

Pull Request Review: feat(dotnet): match python parity for OSS package

Summary

This PR introduces significant updates to the .NET SDK in the agent-governance-toolkit repository, aiming to align its functionality with the Python SDK. Key areas include identity, registry, JWK/JWKS/DID support, policy engine enhancements, and lifecycle management. The changes also refresh tests and documentation to reflect the new parity surface.

---

🔴 CRITICAL Issues

1. Cryptographic Operations: Missing Ed25519 Support

   • The PR notes that .NET 8 lacks native support for Ed25519 signing, which is critical for secure asymmetric cryptographic operations. While the SDK provides HMAC-SHA256 signing, this is insufficient for zero-trust identity systems that rely on asymmetric cryptography.
   • Impact: Agents may be vulnerable to impersonation attacks or replay attacks due to the lack of asymmetric signing.
   • Action: Implement a workaround using third-party libraries (e.g., NSec.Cryptography) or document this limitation prominently in the README and API docs.

2. Policy Engine: Cascade Revocation

   • The expanded IdentityRegistry includes cascade revocation, but there is no mention of safeguards against accidental or malicious revocation of trusted agents.
   • Impact: A compromised registry entry could revoke trust for multiple agents, leading to denial-of-service scenarios.
   • Action: Add safeguards, such as multi-party approval workflows or audit trails, for cascade revocation operations.

3. Sandbox Escape Vectors

   • The KillSwitch mechanism allows immediate termination of agents, but there is no indication of runtime sandboxing or isolation to prevent terminated agents from persisting rogue processes.
   • Impact: Agents terminated by the kill switch could bypass governance by escaping the sandbox.
   • Action: Ensure that terminated agents are fully sandboxed and cannot persist rogue processes. Add tests to validate sandbox escape prevention.

---

🟡 WARNING: Potential Breaking Changes

1. Public API Changes

   • The addition of sponsor metadata, delegation, and JWK/JWKS export in AgentIdentity changes the shape of the identity object. This could break existing integrations that rely on the previous identity structure.
   • Action: Provide migration guides and version the API appropriately to avoid breaking changes for existing users.

2. Policy File Format

   • The introduction of JSON policy loading alongside YAML may cause compatibility issues if users inadvertently mix formats or rely on YAML-specific features.
   • Action: Clearly document the differences between YAML and JSON policy formats and provide validation tools to ensure compatibility.

---

💡 Suggestions for Improvement

1. Thread Safety

   • The PR mentions thread-safe audit logging but does not explicitly address thread safety in concurrent agent execution. Ensure that all shared resources (e.g., KillSwitch, LifecycleManager) are properly synchronized.
   • Action: Add tests for concurrent execution scenarios to validate thread safety.

2. OWASP Agentic AI Top 10 Compliance

   • While the PR claims compliance with OWASP Agentic AI Top 10, there is no evidence of automated testing for these risks.
   • Action: Add automated tests for each OWASP category to ensure compliance.

3. Type Safety and Validation

   • The expanded AgentIdentity and IdentityRegistry functionality should leverage strong type validation (e.g., Pydantic models in Python or equivalent in .NET) to prevent invalid inputs.
   • Action: Add type validation for all public-facing APIs.

4. Backward Compatibility

   • Consider adding feature flags or configuration options to allow users to opt into new functionality without breaking existing workflows.
   • Action: Implement feature flags for new capabilities like JSON policy loading and sponsor metadata.

---

Additional Observations

• Documentation: The updated README is comprehensive but could benefit from a dedicated "Migration Guide" section for users transitioning from older versions.
• Testing: Ensure that test coverage includes edge cases for new features like cascade revocation and JWK/JWKS export.

---

Conclusion

This PR introduces valuable enhancements to the .NET SDK, bringing it closer to parity with the Python SDK. However, critical issues related to cryptographic operations, sandboxing, and cascade revocation must be addressed to ensure security and reliability. Additionally, potential breaking changes should be mitigated through migration guides and feature flags.

Recommended Actions:

• Address 🔴 CRITICAL issues immediately.
• Provide migration guides for 🟡 WARNING changes.
• Implement 💡 Suggestions to improve robustness and usability.

[github-actions]

🤖 AI Agent: security-scanner — Security Review of Pull Request: feat(dotnet): match python parity for OSS package

Security Review of Pull Request: feat(dotnet): match python parity for OSS package

This pull request introduces significant changes to the agent-governance-dotnet library to bring it closer to feature parity with the Python implementation. The changes include updates to the policy engine, identity management, and support for JSON-based policy files. Below is a detailed security analysis based on the specified criteria:

---

1. Prompt Injection Defense Bypass

No direct evidence of prompt injection vulnerabilities was found in this PR. However, the changes introduce JSON-based policy loading (Policy.FromJson and PolicyEngine.LoadJson), which could potentially allow crafted JSON policies to bypass intended policy restrictions if not properly validated.

🔵 LOW

• Attack Vector: If an attacker can inject malicious JSON policies into the system, they could bypass or weaken governance rules.
• Mitigation: Ensure strict validation of JSON policy files, including schema validation and sanitization of inputs. Consider adding unit tests for edge cases and malformed JSON.

---

2. Policy Engine Circumvention

The policy engine now supports JSON-based policies and introduces a new Organization scope. The addition of this scope increases the complexity of policy evaluation, which could introduce subtle logic flaws.

🟠 HIGH

• Attack Vector: If the new Organization scope is not properly prioritized or validated, it could allow policies to be skipped or misapplied. For example, a malicious actor could craft a policy with conflicting rules to exploit weaknesses in the conflict resolution logic.
• Mitigation: Add comprehensive tests to ensure that the new Organization scope is correctly prioritized in the conflict resolution logic. Specifically, verify that the MostSpecificWins strategy handles the new scope as intended. Additionally, ensure that the PolicyScope.ParseScope method properly validates input to prevent unexpected behavior.

---

3. Trust Chain Weaknesses

The changes expand the AgentIdentity class to include features like did:mesh: normalization, delegation, and JWK/JWKS/DID document export. While these features are useful, they introduce potential risks if the trust chain is not properly validated.

🔴 CRITICAL

• Attack Vector: If the AgentIdentity class does not validate the authenticity and integrity of DID documents or JWK/JWKS keys, it could allow attackers to impersonate agents or inject malicious keys.
• Mitigation: Ensure that all DID documents and JWK/JWKS keys are validated against a trusted source (e.g., using cryptographic signatures). Add unit tests to verify that invalid or tampered documents are rejected.

---

4. Credential Exposure

No evidence of credential exposure was found in the changes. The code does not appear to log sensitive information or expose credentials in error messages.

🔵 LOW

• Mitigation: Continue to ensure that sensitive information (e.g., private keys, secrets) is never logged or exposed in error messages.

---

5. Sandbox Escape

No evidence of sandbox escape vulnerabilities was found in this PR. The changes do not introduce any new system calls or external process executions.

🔵 LOW

• Mitigation: Maintain strict isolation between the policy engine and the underlying system. Avoid introducing features that could execute arbitrary code.

---

6. Deserialization Attacks

The addition of JSON deserialization introduces potential risks if untrusted input is processed. While the System.Text.Json library is used, which is generally safer than alternatives like Newtonsoft.Json, there is still a risk of deserialization attacks if the input is not properly sanitized.

🟠 HIGH

• Attack Vector: An attacker could craft malicious JSON input to exploit deserialization vulnerabilities, potentially leading to remote code execution or denial of service.
• Mitigation: Use strict schema validation for JSON input. Avoid deserializing untrusted input directly into complex objects. Add tests to ensure that malformed or malicious JSON is safely handled.

---

7. Race Conditions

The policy engine uses locks (_policyLock and _rateLimitLock) to manage concurrent access to policies and rate limits. While this is a good practice, the implementation of rate limiting introduces a potential time-of-check-to-time-of-use (TOCTOU) vulnerability.

🟠 HIGH

• Attack Vector: An attacker could exploit a race condition in the rate-limiting logic to bypass restrictions. For example, by sending multiple requests in parallel, they might exceed the rate limit before it is enforced.
• Mitigation: Use atomic operations or a thread-safe data structure to manage rate limits. Add tests to simulate concurrent requests and verify that rate limits are enforced correctly.

---

8. Supply Chain

No new dependencies were introduced in this PR, so there is no evidence of dependency confusion or typosquatting risks.

🔵 LOW

• Mitigation: Regularly audit dependencies for vulnerabilities and ensure that all dependencies are sourced from trusted repositories.

---

Summary of Findings

Category	Severity	Description	Mitigation
Prompt Injection Defense	🔵 LOW	Potential for crafted JSON policies to bypass rules.	Add schema validation and edge-case tests for JSON policies.
Policy Engine Circumvention	🟠 HIGH	New Organization scope may introduce logic flaws in conflict resolution.	Add tests for MostSpecificWins strategy and validate PolicyScope inputs.
Trust Chain Weaknesses	🔴 CRITICAL	Potential lack of validation for DID documents and JWK/JWKS keys.	Validate authenticity and integrity of all external documents and keys.
Credential Exposure	🔵 LOW	No evidence of credential exposure.	Ensure sensitive data is not logged or exposed in error messages.
Sandbox Escape	🔵 LOW	No evidence of sandbox escape vulnerabilities.	Maintain strict isolation and avoid arbitrary code execution.
Deserialization Attacks	🟠 HIGH	JSON deserialization introduces potential risks with untrusted input.	Use strict schema validation and avoid deserializing untrusted input.
Race Conditions	🟠 HIGH	Potential TOCTOU vulnerability in rate-limiting logic.	Use atomic operations or thread-safe data structures for rate limit handling.
Supply Chain	🔵 LOW	No new dependencies introduced.	Regularly audit dependencies for vulnerabilities.

---

Recommendations

1. Policy Validation: Implement strict schema validation for both YAML and JSON policy files to ensure that only valid and expected inputs are processed.
2. Conflict Resolution Testing: Add comprehensive tests to verify the behavior of the MostSpecificWins strategy, especially with the new Organization scope.
3. Trust Chain Validation: Ensure that all DID documents and JWK/JWKS keys are validated against a trusted source. Add tests to verify that invalid or tampered documents are rejected.
4. Rate-Limiting Improvements: Replace the _rateLimitLock with a thread-safe data structure or use atomic operations to prevent race conditions.
5. Deserialization Safety: Avoid deserializing untrusted JSON directly into complex objects. Use schema validation to ensure the integrity of the input.

---

Final Assessment

This PR introduces valuable features but also increases the attack surface of the library. The most critical issue is the potential lack of validation for DID documents and JWK/JWKS keys, which could compromise the trust chain. Additionally, the new JSON deserialization and rate-limiting logic require further scrutiny to ensure they are secure. Addressing these issues is essential before merging this PR.

[github-actions]

🤖 AI Agent: code-reviewer

Feedback on Pull Request: feat(dotnet): match python parity for OSS package

---

🔴 CRITICAL: Security Issues

1. Policy Engine Default Action

   • The policy engine defaults to "allow" when no policies are loaded or no rules match. This behavior can lead to unintended security risks, as it allows actions to proceed without explicit approval. Consider changing the default behavior to "deny" to align with the principle of least privilege.
   • Recommendation: Update the default behavior to deny access when no policies are loaded or no rules match.

2. Rate Limiting Implementation

   • The _rateLimits dictionary in PolicyEngine is protected by a lock (_rateLimitLock), but the implementation does not show how concurrent access to this dictionary is handled during evaluation. This could lead to race conditions or inconsistent state in rate-limiting logic.
   • Recommendation: Use a thread-safe collection, such as ConcurrentDictionary, instead of manually managing locks.

3. Agent DID Normalization

   • The Evaluate method normalizes the agentDid using AgentIdentity.NormalizeDid. However, the implementation of NormalizeDid is not provided in the diff. If this normalization function is flawed, it could lead to incorrect evaluation contexts, potentially allowing security bypasses.
   • Recommendation: Review the implementation of NormalizeDid to ensure it correctly handles edge cases, such as malformed or maliciously crafted DIDs.

4. Policy Document Parsing

   • The Policy.FromJson and Policy.FromYaml methods allow trailing commas and ignore unmatched properties. While this increases flexibility, it could lead to security issues if malformed or unexpected input is silently accepted.
   • Recommendation: Add stricter validation for policy documents, ensuring that only explicitly defined fields are accepted and that malformed input is rejected.

---

🟡 WARNING: Potential Breaking Changes

1. Conflict Resolution Scope Update

   • The addition of the Organization scope and the change in scope hierarchy (Agent > Organization > Tenant > Global) may alter the behavior of existing policies that rely on the previous hierarchy.
   • Recommendation: Clearly document this change in the release notes and provide migration guidance for users to update their policies accordingly.

2. PolicyDecision API Changes

   • The PolicyDecision class now includes additional fields (PolicyName, RateLimitReset, Metadata, etc.) and changes to method signatures (e.g., AllowDefault and DenyDefault now require DateTime evaluatedAt). These changes may break existing integrations that rely on the previous API.
   • Recommendation: Ensure backward compatibility by providing overloads for the modified methods or clearly document the changes in the API contract.

---

💡 Suggestions for Improvement

1. Thread Safety

   • While the PolicyEngine class uses locks for thread safety, consider using ReaderWriterLockSlim for better performance when handling multiple concurrent read operations.

2. Logging and Auditing

   • Add detailed logging for policy evaluation, including the input context, matched rules, and final decisions. This will aid in debugging and auditing policy decisions.

3. Unit Test Coverage

   • Ensure that the new features (e.g., JSON policy loading, organization scope, rate-limiting enhancements) are thoroughly tested. Specifically, test edge cases such as malformed JSON/YAML inputs, invalid DIDs, and complex conflict resolution scenarios.

4. Documentation

   • Update the documentation to include examples of the new features, such as JSON policy loading, organization scope, and rate-limiting enhancements. Highlight the differences between the Python and .NET implementations.

5. Error Handling

   • Improve error messages for policy parsing failures to include more details about the specific issues (e.g., missing required fields, invalid values).

6. Performance Optimization

   • Consider profiling the Evaluate method to identify potential bottlenecks, especially in scenarios with a large number of policies and rules.

7. Backward Compatibility

   • For the PolicyDecision class, consider marking the old methods as [Obsolete] and provide a clear migration path for users.

---

Summary

This pull request introduces significant improvements to the .NET implementation of the agent-governance package, bringing it closer to parity with the Python SDK. However, there are critical security concerns related to default policy actions, rate-limiting implementation, and policy document parsing that need to be addressed. Additionally, some changes may break existing integrations, and these should be documented with migration guidance. Finally, there are opportunities to improve thread safety, logging, testing, and documentation.

Action Items:

1. Address the critical security issues outlined above.
2. Review and mitigate potential breaking changes.
3. Implement the suggested improvements to enhance the robustness and usability of the library.

[github-actions]

🤖 AI Agent: code-reviewer

Pull Request Review: feat(dotnet): match python parity for OSS package

---

🔴 CRITICAL: Security Concerns

1. Policy Engine Thread Safety

   • The PolicyEngine class is described as thread-safe, but the implementation raises concerns:
     • While _policies is protected by _policyLock, the _rateLimits dictionary is only protected by _rateLimitLock. This separation could lead to race conditions if _rateLimits is accessed concurrently in methods not shown in the diff. Ensure all access to shared state is properly synchronized.
     • The RateLimitWindow logic (not shown in the diff) should be reviewed for thread safety, especially if it involves mutable state.

   Action: Audit all methods interacting with _rateLimits and _policies to ensure proper locking mechanisms are in place. Consider using ConcurrentDictionary for _rateLimits if appropriate.

2. Policy Parsing and Validation

   • The addition of JSON policy parsing (Policy.FromJson) introduces a potential attack vector for malicious payloads. While JsonSerializerOptions includes JsonCommentHandling.Skip and AllowTrailingCommas, there is no validation of the structure or content of the JSON beyond the schema version check.
   • Similarly, YAML parsing (Policy.FromYaml) relies on YamlDotNet but does not validate the structure or enforce strict schema checks.

   Action: Implement stricter validation for both JSON and YAML inputs. Consider using a schema validation library (e.g., jsonschema for JSON) to ensure the input conforms to expected formats and does not contain unexpected fields or malicious payloads.

3. Cryptographic Operations

   • The .NET 8 compatibility signing feature in AgentIdentity is mentioned but not shown in the diff. Ensure that cryptographic operations (e.g., signing, verification) are implemented using secure libraries and algorithms. Avoid custom cryptographic implementations unless absolutely necessary.

   Action: Verify that cryptographic operations use industry-standard libraries and algorithms (e.g., System.Security.Cryptography for .NET). Ensure that private keys are securely stored and not exposed in logs or error messages.

---

🟡 WARNING: Potential Breaking Changes

1. Policy Scope Changes

   • The addition of the Organization scope and the renumbering of PolicyScope enum values (e.g., Agent changed from 2 to 3) could break existing integrations that rely on the previous numeric values.

   Action: Document this change clearly in the release notes and consider providing a migration guide for users who may be affected.

2. PolicyDecision API Changes

   • The PolicyDecision class has been expanded with new properties (PolicyName, RateLimitReset, EvaluatedAt, Metadata). While these additions are backward-compatible, they may affect consumers who rely on the exact structure of this class.

   Action: Highlight these changes in the release notes and ensure that downstream consumers are aware of the new properties.

---

💡 Suggestions for Improvement

1. Error Handling

   • The Policy.FromYaml and Policy.FromJson methods throw ArgumentException for invalid input. Consider introducing custom exception types (e.g., PolicyParseException) to make error handling more specific and meaningful.

2. Logging

   • Add logging to critical methods in PolicyEngine (e.g., LoadPolicy, Evaluate) to provide better observability into policy loading and evaluation processes. This is especially important for debugging and auditing in production environments.

3. Conflict Resolution Strategy

   • The ConflictResolutionStrategy property in PolicyEngine is currently public and mutable. Consider making it immutable after initialization or providing a thread-safe mechanism for updating it.

4. Testing

   • Ensure that the expanded functionality (e.g., JSON policy parsing, organization scope, richer PolicyDecision metadata) is thoroughly tested. Include tests for edge cases, such as malformed JSON/YAML inputs, unsupported schema versions, and concurrent policy evaluations.

5. Documentation

   • Update documentation to reflect the new features, including examples of JSON policy files, the Organization scope, and the expanded PolicyDecision metadata. Highlight any limitations, such as the lack of native Ed25519 support in .NET 8.

---

Summary

The pull request introduces significant improvements to the .NET SDK, bringing it closer to parity with the Python implementation. However, there are critical security concerns related to thread safety and input validation that must be addressed before merging. Additionally, potential breaking changes in the PolicyScope enum and PolicyDecision class should be documented and mitigated. Finally, enhanced testing, logging, and documentation are recommended to ensure robustness and maintainability.

Action Items:

1. Address thread safety concerns in PolicyEngine.
2. Implement stricter validation for JSON and YAML policy inputs.
3. Audit cryptographic operations for security best practices.
4. Document breaking changes and provide migration guidance.
5. Expand test coverage for new features and edge cases.
6. Improve logging and documentation for observability and usability.