feat(audit): add arguments_hash, approver_did, policy_version to AuditEntry (#2449) by sunilp · Pull Request #2473 · microsoft/agent-governance-toolkit

sunilp · 2026-05-22T02:33:05Z

Description

Adds three optional verifiability fields to the Agent Mesh AuditEntry
schema (spec §4.3), surfaces them through AuditLog.log() and the
CloudEvents serializer:

arguments_hash — hex SHA-256 of action arguments (mutation defense)
approver_did — DID of the approving principal (approval-chain identity)
policy_version — version id of the policy bundle (downgrade defense)

Driven by the conformance review in #2449 where these three fields were
acknowledged as legitimate gaps. This PR is intentionally additive — the
§4.4 canonical hash field set is not changed, so previously-persisted
audit entries continue to verify unchanged. A new spec subsection §4.3.1
documents the v1.0 caveat (fields recorded but not yet hash-covered) and
flags a planned v1.1 extension to MerkleAuditChain under an explicit
schema-version selector.

This is the first of two PRs from the #2449 conformance review:

This PR — additive schema fields, no hash change
PR Adding Microsoft SECURITY.MD #2 (to follow) — issued_at / completed_at dual timestamps and
environment parity into the Agent OS schema

A separate tracking issue will cover the v1.1 hash-coverage extension.

Type of Change

Bug fix (non-breaking change that fixes an issue)
New feature (non-breaking change that adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update
Maintenance (dependency updates, CI/CD, refactoring)
Security fix

Package(s) Affected

Checklist

My code follows the project style guidelines (ruff check)
I have added tests that prove my fix/feature works
All new and existing tests pass (pytest)
I have updated documentation as needed
I have signed the Microsoft CLA

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:

AgentBoundary v0.1 receipt spec (Apache-2.0) —
the field set added here was derived from AgentBoundary's tamper-evidence
taxonomy applied against AGT's conformance evaluation in
adapters/microsoft-agt/.
Field naming was deliberately aligned with AGT's existing did: /
agent_did conventions rather than copying AgentBoundary's subject /
actor naming.

AI Assistance

I can explain every meaningful change in this PR: what it does, why, and what tradeoffs were considered
I have run tests and verification appropriate for this change
No part of this PR was autonomously submitted by an AI agent without my review
I have not used AI to generate review comments on others' PRs

AI tools materially shaped this change: a Claude (Anthropic) coding assistant
drafted the schema additions, spec edits, and test cases. Every change was
reviewed, edited, and signed off by me; the design tradeoffs (additive-only
vs. schema-version + hash extension) were decided by me before drafting. The
v1.1 hash-coverage path was explicitly chosen as a follow-up PR per the
"smallest correct surface" guidance in CONTRIBUTING.md.

IP, Patents, and Licensing

This contribution does not implement patent-pending or patent-encumbered techniques
This contribution does not require an NDA or licensing agreement to understand or use
Any AI tools used have terms compatible with the MIT License

Related Issues

Refs #2449

…tEntry Add three optional verifiability fields to the Agent Mesh AuditEntry schema (spec §4.3) and surface them via AuditLog.log() and CloudEvents serialization: - arguments_hash — hex SHA-256 of action arguments (mutation defense) - approver_did — DID of the approving principal (approval-chain identity) - policy_version — version id of the policy bundle (downgrade defense) Scope is intentionally additive. The §4.4 canonical hash field set is NOT changed in this PR, so previously-persisted entries continue to verify unchanged. A new spec section §4.3.1 documents that v1.0 does not include these fields in the integrity hash; spec v1.1 will extend MerkleAuditChain coverage under an explicit schema-version selector. Driven by external conformance review against the AgentBoundary v0.1 receipt spec (microsoft#2449) where these three fields were acknowledged as legitimate gaps. Five of nine TestAuditEntryExtensions tests cover the API surface, one asserts compute_hash() is unchanged for v1.0 backward compat, two cover CloudEvents serialization, one verifies chain integrity with the new fields populated. Prior art / related projects: - AgentBoundary v0.1 receipt spec (jamjet-labs/agentboundary). Field naming aligned with AGT's existing did: / agent_did conventions. Refs: microsoft#2449 Signed-off-by: sdev <sunil@sunilprakash.com>

The new fields added in the previous commit used `Optional[str]` to match the surrounding pre-existing style. agent-mesh/pyproject.toml configures ruff with `select = [..., "UP"]`, so UP045 fires on the new annotations. Convert only the three new field annotations and the AuditLog.log() kwargs to `str | None`; existing `Optional[str]` usages in this file are left as-is to keep the PR surface minimal. Signed-off-by: sdev <sunil@sunilprakash.com>

github-actions · 2026-05-22T02:35:28Z

🤖 AI Agent: breaking-change-detector — API Compatibility

API Compatibility

No breaking changes detected.

github-actions · 2026-05-22T02:35:28Z

🤖 AI Agent: security-scanner — View details

No security issues found.

github-actions · 2026-05-22T02:35:29Z

🤖 AI Agent: docs-sync-checker — Docs Sync

Docs Sync

Documentation is in sync.

github-actions · 2026-05-22T02:35:30Z

🤖 AI Agent: test-generator — `agentmesh/governance/audit.py`

`agentmesh/governance/audit.py`

test_audit_log_log_handles_missing_new_fields -- Verify AuditLog.log() handles cases where arguments_hash, approver_did, or policy_version are not provided.
test_audit_entry_invalid_arguments_hash -- Test that AuditEntry raises validation errors for invalid arguments_hash values (e.g., non-hex strings or incorrect lengths).
test_audit_entry_invalid_policy_version -- Validate that AuditEntry rejects invalid policy_version formats.
test_audit_entry_invalid_approver_did -- Ensure AuditEntry raises errors for invalid approver_did formats.

`test_governance.py`

test_audit_log_export_with_new_fields -- Confirm that AuditLog.export() includes arguments_hash, approver_did, and policy_version when set.
test_audit_log_integrity_with_invalid_new_fields -- Test AuditLog.verify_integrity() behavior when new fields contain invalid data.

github-actions · 2026-05-22T02:35:30Z

🔴 Contributor Check: HIGH

Check	Result
Profile	HIGH
Credential	NONE
Overall	HIGH

Automated check by AGT Contributor Check.

github-actions · 2026-05-22T02:35:32Z

🤖 AI Agent: contributor-guide — View details

Hi @first-time-contributor, welcome to the project and thank you for your detailed and thoughtful contribution! 🎉

Your PR does a great job of maintaining backward compatibility while introducing new schema fields.

Before merging:

Please ensure the new tests cover edge cases for arguments_hash, approver_did, and policy_version.
Verify that the documentation updates in AUDIT-COMPLIANCE-1.0.md align with the latest project guidelines in CONTRIBUTING.md.

Let us know if you need any help! 🚀

github-actions · 2026-05-22T02:35:32Z

🤖 AI Agent: code-reviewer — Action Items:

TL;DR: 0 blockers, 1 warning. The PR is well-implemented and adheres to the project's standards, but one issue could be addressed in a follow-up PR.

#	Sev	Issue	Where
1	Warn	`arguments_hash` lacks validation to ensure it is a valid SHA-256 hex	`agentmesh/governance/audit.py`

Action Items:

None.

Warnings:

#	Issue	Where	Follow-up
1	Add validation for `arguments_hash` to ensure it is a valid SHA-256 hex string	`agentmesh/governance/audit.py`	Fine as follow-up PR.

sunilp · 2026-05-22T02:37:01Z

@microsoft-github-policy-service agree

github-actions · 2026-05-22T02:39:10Z

PR Review Summary

Check	Status	Details
🔍 Code Review	⚠️ Warning	See details
🛡️ Security Scan	✅ Passed	No issues found
🔄 Breaking Changes	✅ Passed	No issues found
📝 Docs Sync	✅ Passed	No issues found
🧪 Test Coverage	✅ Completed	Analysis complete

Verdict: ⚠️ Ready for human review

imran-siddique

LGTM. Backward-compatible audit fields with chain integrity preserved.

…tEntry (microsoft#2449) (microsoft#2473) * feat(audit): add arguments_hash, approver_did, policy_version to AuditEntry Add three optional verifiability fields to the Agent Mesh AuditEntry schema (spec §4.3) and surface them via AuditLog.log() and CloudEvents serialization: - arguments_hash — hex SHA-256 of action arguments (mutation defense) - approver_did — DID of the approving principal (approval-chain identity) - policy_version — version id of the policy bundle (downgrade defense) Scope is intentionally additive. The §4.4 canonical hash field set is NOT changed in this PR, so previously-persisted entries continue to verify unchanged. A new spec section §4.3.1 documents that v1.0 does not include these fields in the integrity hash; spec v1.1 will extend MerkleAuditChain coverage under an explicit schema-version selector. Driven by external conformance review against the AgentBoundary v0.1 receipt spec (microsoft#2449) where these three fields were acknowledged as legitimate gaps. Five of nine TestAuditEntryExtensions tests cover the API surface, one asserts compute_hash() is unchanged for v1.0 backward compat, two cover CloudEvents serialization, one verifies chain integrity with the new fields populated. Prior art / related projects: - AgentBoundary v0.1 receipt spec (jamjet-labs/agentboundary). Field naming aligned with AGT's existing did: / agent_did conventions. Refs: microsoft#2449 Signed-off-by: sdev <sunil@sunilprakash.com> * style(audit): use str | None for new fields per agent-mesh ruff (UP045) The new fields added in the previous commit used `Optional[str]` to match the surrounding pre-existing style. agent-mesh/pyproject.toml configures ruff with `select = [..., "UP"]`, so UP045 fires on the new annotations. Convert only the three new field annotations and the AuditLog.log() kwargs to `str | None`; existing `Optional[str]` usages in this file are left as-is to keep the PR surface minimal. Signed-off-by: sdev <sunil@sunilprakash.com> --------- Signed-off-by: sdev <sunil@sunilprakash.com>

sunilp added 2 commits May 22, 2026 07:46

sunilp mentioned this pull request May 22, 2026

bug(audit): AuditEntry has duplicate field declarations; container_runtime vs compute_driver name mismatch #2474

Closed

github-actions Bot added documentation Improvements or additions to documentation tests agent-mesh agent-mesh package size/L Large PR (< 500 lines) labels May 22, 2026

github-actions Bot added the needs-review:HIGH Contributor reputation check flagged HIGH risk label May 22, 2026

imran-siddique approved these changes May 22, 2026

View reviewed changes

imran-siddique merged commit f176919 into microsoft:main May 22, 2026
14 of 15 checks passed

This was referenced May 23, 2026

feat(audit): add issued_at, completed_at to AuditEntry (#2449) #2532

Merged

AgentBoundary v0.1 conformance evaluation of AGT — pre-publication review #2449

Closed

Conversation

sunilp commented May 22, 2026

Description

Type of Change

Package(s) Affected

Checklist

Attribution & Prior Art

AI Assistance

IP, Patents, and Licensing

Related Issues

Uh oh!

github-actions Bot commented May 22, 2026

API Compatibility

Uh oh!

github-actions Bot commented May 22, 2026

Uh oh!

github-actions Bot commented May 22, 2026

Docs Sync

Uh oh!

github-actions Bot commented May 22, 2026

agentmesh/governance/audit.py

test_governance.py

Uh oh!

github-actions Bot commented May 22, 2026

Uh oh!

github-actions Bot commented May 22, 2026

Uh oh!

github-actions Bot commented May 22, 2026

Action Items:

Warnings:

Uh oh!

sunilp commented May 22, 2026

Uh oh!

github-actions Bot commented May 22, 2026

PR Review Summary

Uh oh!

imran-siddique left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

`agentmesh/governance/audit.py`

`test_governance.py`