Skip to content

docs: refresh all proposals — update status, add 5 new proposals#348

Merged
imran-siddique merged 15 commits intomicrosoft:mainfrom
imran-siddique:docs/proposal-refresh
Mar 23, 2026
Merged

docs: refresh all proposals — update status, add 5 new proposals#348
imran-siddique merged 15 commits intomicrosoft:mainfrom
imran-siddique:docs/proposal-refresh

Conversation

@imran-siddique
Copy link
Copy Markdown
Member

Full refresh of proposals directory. Updated 8 existing proposal status fields (Dify->Shipped, MAF->Implemented, CSA-ATF->Active, etc). Created 5 new proposals for shipped/active engagements: Haystack, Oracle Agent Spec, Stripe MPP, Nexus Trust Exchange, A2A Trust Extensions. Updated README index with new Agent Infrastructure section. 14 files changed, 224 insertions — all documentation.

imran-siddique and others added 15 commits March 20, 2026 10:56
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add EU AI Act, Colorado AI Act, and GPAI obligations timeline with
AGT coverage mapping. Reference Microsoft Purview DSPM for AI as
complementary data governance layer.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The Scorecard API rejects workflows with write permissions at the
workflow level. id-token: write and security-events: write must be
scoped to the job level only. Restores permissions: read-all at
workflow level while keeping job-level write permissions intact.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…ft#324)

Add Google-style docstrings with Args, Returns, Raises, Attributes,
and Example sections to MCPMessageType, MCPAdapter, and MCPServer
classes. Also enhances docstrings for key methods including
handle_message, _handle_tools_call, _handle_resources_read, and
_map_tool_to_action.

Fixes microsoft#316
Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
…s (dependency confusion) (microsoft#325)

- Replace !pip install agent-os with !pip install -e ../.. in all 6 notebooks;
  agent-os is not on PyPI and installing it from PyPI is a dependency confusion vector
- Replace zendesk-sdk/freshdesk-sdk with zenpy/freshdesk (the real published SDKs)
  in customer-service/requirements.txt
- Remove hashlib-compat from healthcare-hipaa/requirements.txt; hashlib is stdlib
  and hashlib-compat is not a real PyPI package
…stall agent-os with agent-os-kernel

Replace all remaining instances of `pip install agent-os` (unregistered
on PyPI) with `pip install agent-os-kernel` (the actual package) across
docs, examples, TypeScript extensions, CLI source, tests, and SVG assets.

Also fixes `pip install emk` references to point to `agent-os-kernel[full]`
since emk is a submodule, not a standalone PyPI package.

Completes the fix started in PR microsoft#325 which only covered notebooks.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Dify 65K→133K, AutoGen 42K→55K, CrewAI 28K→46K, Semantic Kernel
24K→27K, LangGraph 24K→27K, Haystack 22K→24K, Agent Framework
7.6K→8K. Added star counts for OpenAI Agents SDK (20K) and
Google ADK (18K). Sorted by stars descending.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Update Status fields across all 8 proposal documents:
- DIFY: Shipped (PR #2060, live on Marketplace)
- GITHUB-COPILOT: Shipped (all 3 PRs merged)
- MAF: Implemented Level 1 (18 tests, awaiting MAF team)
- MCP: Partially Shipped (npm + Glama, registry pending)
- OPENLIT: Implemented (PR #1062 under review)
- CSA-ATF: Active (ATF author engaged, conformance spec published)
- AAIF: Paused (re-submit after public release)
- GOOGLE-ADK: Implemented (GovernanceAdapter shipped)

Added Progress section to CSA-ATF-PROPOSAL.md with timeline.
New proposals for shipped/active engagements:
- HAYSTACK-INTEGRATION-PROPOSAL.md (shipped)
- ORACLE-AGENTSPEC-PROPOSAL.md (active engagement)
- STRIPE-MPP-PROPOSAL.md (planned)
- NEXUS-TRUST-EXCHANGE-PROPOSAL.md (pre-alpha)
- A2A-TRUST-EXTENSIONS-PROPOSAL.md (adapter shipped)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@github-actions github-actions bot added documentation Improvements or additions to documentation size/L Large PR (< 500 lines) labels Mar 23, 2026
@github-actions
Copy link
Copy Markdown

🤖 AI Agent: security-scanner — Security Review Summary

Security Review Summary

This pull request primarily involves documentation updates and new proposals. While the changes are not directly related to the codebase, the proposals describe new integrations and features that could have security implications. Below is an analysis of potential risks and recommendations based on the provided diff.


Findings

1. Trust Chain Weaknesses in Nexus Trust Exchange

  • Risk: The Nexus Trust Exchange proposal mentions a placeholder cryptographic implementation using XOR for Ed25519. XOR is not a secure cryptographic algorithm and is highly susceptible to attacks. This creates a significant risk of trust chain compromise, as the cryptographic foundation is not secure.
  • Rating: 🔴 CRITICAL
  • Attack Vector: An attacker could exploit the weak cryptographic implementation to forge trust signatures, manipulate reputation scores, or bypass escrow mechanisms, undermining the entire trust exchange system.
  • Recommendation: Replace the placeholder XOR implementation with a robust cryptographic library, such as the Ed25519 implementation provided by libsodium or OpenSSL. Additionally, prioritize integrating with a secure key management solution like Azure Key Vault as mentioned in the proposal.

2. Policy Engine Circumvention in Haystack Integration

  • Risk: The GovernancePolicyChecker component in the Haystack integration proposal mentions enforcing governance policies, including tool allowlist/blocklist, content pattern filtering, and rate limiting. However, the proposal does not specify how these policies are configured, updated, or protected from tampering.
  • Rating: 🟠 HIGH
  • Attack Vector: If the policy configuration is not securely managed, an attacker could modify or bypass the policies, allowing unauthorized actions or bypassing restrictions.
  • Recommendation: Ensure that policy configurations are stored securely, preferably in an immutable or append-only format. Implement strong authentication and authorization for any updates to the policy configuration. Additionally, consider adding cryptographic signatures to validate the integrity of the policies.

3. Credential Exposure in Stripe MPP Integration

  • Risk: The Stripe MPP integration proposal involves handling sensitive payment credentials and delegation chains. However, there is no mention of secure storage or transmission of these credentials.
  • Rating: 🟠 HIGH
  • Attack Vector: If payment credentials or delegation chains are exposed in logs, error messages, or insecure storage, attackers could misuse them to perform unauthorized transactions.
  • Recommendation: Use secure storage mechanisms (e.g., Azure Key Vault or AWS Secrets Manager) for sensitive credentials. Ensure that logs and error messages do not expose sensitive information. Use secure communication protocols (e.g., HTTPS) for transmitting payment data.

4. Deserialization Risks in Nexus Trust Exchange

  • Risk: The Nexus Trust Exchange proposal mentions JSONL export for audit logs. If these logs are later deserialized without proper validation, it could lead to deserialization attacks.
  • Rating: 🟡 MEDIUM
  • Attack Vector: An attacker could craft malicious JSONL data to exploit vulnerabilities in the deserialization process, potentially leading to remote code execution or data corruption.
  • Recommendation: Use a secure JSON parsing library that prevents code execution during deserialization. Validate all input data before processing it.

5. Potential Supply Chain Risks

  • Risk: The proposals mention dependencies on third-party libraries and SDKs, such as the Stripe MPP SDK and Haystack. There is no mention of a strategy to mitigate supply chain risks.
  • Rating: 🟡 MEDIUM
  • Attack Vector: If a malicious or compromised dependency is introduced, it could lead to unauthorized access, data exfiltration, or other security breaches.
  • Recommendation: Implement a robust supply chain security strategy, including dependency scanning, version pinning, and verifying the integrity of third-party libraries using checksums or signatures.

General Recommendations

  1. Threat Modeling: Conduct a thorough threat modeling exercise for each proposed integration to identify potential attack vectors and mitigate risks.
  2. Security Reviews: Ensure that all new code and integrations undergo rigorous security reviews before implementation.
  3. Testing: Implement automated security testing for new components, including tests for common vulnerabilities such as injection attacks, deserialization issues, and race conditions.
  4. Documentation: Update the proposals to include detailed security considerations and mitigation strategies for the identified risks.

Conclusion

While this pull request primarily involves documentation updates, the proposed integrations introduce potential security risks that must be addressed during implementation. The most critical issue is the use of an insecure cryptographic placeholder in the Nexus Trust Exchange. This should be prioritized for immediate remediation. Other risks, such as policy engine circumvention and credential exposure, should also be carefully managed during development.

Copy link
Copy Markdown

@github-actions github-actions bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 AI Agent: code-reviewer

Review Summary

This pull request focuses on updating the documentation for proposals, including status updates for existing proposals and the addition of five new proposals. While the changes are documentation-only, they touch on critical areas of the project, such as trust, cryptographic operations, and agent governance. Below is a detailed review of the changes.


🔴 CRITICAL Issues

  1. Nexus Trust Exchange - Placeholder Cryptography

    • The Nexus Trust Exchange proposal mentions that cryptographic operations (Ed25519) are currently implemented using a placeholder XOR-based mechanism. This is a severe security risk as XOR is not cryptographically secure and can be trivially broken.
    • Action Required: Replace the placeholder cryptography with a secure implementation, such as Ed25519 using a trusted library (e.g., PyNaCl or cryptography). If hardware-backed security is required, integrate with Azure Key Vault HSM as planned.
  2. Audit Logger - Tamper-Evident Logging

    • The Haystack integration proposal describes an audit logger with a SHA-256 hash chain for tamper-evident logging. However, there is no mention of how the hash chain is persisted or protected from tampering.
    • Action Required: Ensure the hash chain is stored in a secure, append-only medium (e.g., a write-once database or blockchain). Document the persistence mechanism to ensure audit integrity.

🟡 WARNING Issues

  1. Breaking Changes in Agent Infrastructure

    • The Nexus Trust Exchange and A2A Trust Extensions proposals introduce new components and protocols (e.g., IATP Trust Handshake, VADP delegation chains). These may introduce breaking changes to existing agent interactions if not backward-compatible.
    • Action Required: Clearly document backward compatibility guarantees or provide migration paths for existing agents.
  2. Stripe MPP Integration - Dependency on External SDK

    • The Stripe MPP proposal depends on an external SDK that was launched in March 2026. This introduces a risk of breaking changes or API instability in the dependency.
    • Action Required: Use version pinning for the Stripe MPP SDK and implement fallback mechanisms for unsupported features.

💡 Suggestions for Improvement

  1. Agent Trust Scoring

    • The Haystack integration and Nexus Trust Exchange both implement trust scoring mechanisms. It would be beneficial to standardize the trust scoring model across components to avoid inconsistencies.
    • Suggestion: Define a central trust scoring API or module that can be reused across integrations.
  2. Graceful Fallback Logic

    • The Haystack integration includes fallback logic for when the haystack library is not installed. While this ensures compatibility, the fallback logic is not covered by tests (# pragma: no cover).
    • Suggestion: Add test cases for the fallback logic to ensure it behaves as expected.
  3. Proposal Status Updates

    • The proposal status updates are clear, but some statuses (e.g., "Pre-Alpha," "Planned") lack detailed timelines or next steps.
    • Suggestion: Add a "Next Steps" section to all proposals to provide clarity on future milestones.
  4. Documentation Consistency

    • The README index now includes an "Agent Infrastructure & Protocols" section, but the formatting and categorization could be improved for better readability.
    • Suggestion: Use consistent formatting for all sections and consider grouping proposals by their maturity (e.g., "Shipped," "Active," "Planned").
  5. OWASP Agentic Top 10 Compliance

    • While the proposals touch on critical areas like trust, cryptography, and auditability, there is no explicit mention of compliance with the OWASP Agentic Top 10.
    • Suggestion: Add a compliance mapping section to each proposal to ensure alignment with OWASP Agentic Top 10 guidelines.

Final Recommendation

  • Merge Blocker: Address the 🔴 CRITICAL issues related to placeholder cryptography and audit logging before merging.
  • Post-Merge Actions: Plan for addressing 🟡 WARNING issues and implement the 💡 suggestions in future updates.

By resolving these issues, the documentation will better support the project's goals of secure and trustworthy agent governance.

@imran-siddique imran-siddique merged commit 6897217 into microsoft:main Mar 23, 2026
53 checks passed
@imran-siddique imran-siddique deleted the docs/proposal-refresh branch March 28, 2026 16:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation size/L Large PR (< 500 lines)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants