diff --git a/README.md b/README.md index 4c4e189..323264c 100644 --- a/README.md +++ b/README.md @@ -116,6 +116,7 @@ AgentConnect focuses on practical SDK support for `did:wba`, authentication, age - [Extended Reading](docs/links.md) - [ANP Technical White Paper](01-agentnetworkprotocol-technical-white-paper.md) +- [ANP Security Considerations](docs/security-considerations.md) - [AgentConnect Examples](https://github.com/agent-network-protocol/AgentConnect) ## Milestones diff --git a/docs/links.md b/docs/links.md index 3683c00..141ba40 100644 --- a/docs/links.md +++ b/docs/links.md @@ -1,6 +1,6 @@ # Further Reading -For ease of reference, all ANP-related materials are organized by **Specifications / Whitepaper / Blogs / Ecosystem**. +For ease of reference, all ANP-related materials are organized by **Specifications / Implementation Guidance / Whitepaper / Blogs / Ecosystem**. ## Specifications @@ -20,6 +20,10 @@ For ease of reference, all ANP-related materials are organized by **Specificatio - [Agent Description Protocol Specification](/07-anp-agent-description-protocol-specification.md) - [Agent Discovery Protocol Specification](/08-anp-agent-discovery-protocol-specification.md) +## Implementation Guidance + +- [ANP Security Considerations](/docs/security-considerations.md) + ## Whitepaper - [AgentNetworkProtocol Technical White Paper](/01-agentnetworkprotocol-technical-white-paper.md) diff --git a/docs/security-considerations.md b/docs/security-considerations.md new file mode 100644 index 0000000..9a94951 --- /dev/null +++ b/docs/security-considerations.md @@ -0,0 +1,240 @@ +# ANP Security Considerations + +- Status: Informational implementation guidance +- Scope: Non-normative. This document does not define new protocol + requirements. Normative requirements remain in the individual ANP + specifications and Profiles. + +This document summarizes security guidance that cuts across the ANP +specifications. It does not replace protocol-specific requirements in the +did:wba, Agent Description, Agent Discovery, Meta-Protocol, Messaging, or +application protocol documents. Instead, it clarifies the security boundaries +that implementations and applications should preserve when composing these +mechanisms. If this guidance conflicts with an applicable ANP specification or +Profile, the specification or Profile takes precedence. + +## 1. Security Goals and Non-Goals + +ANP provides protocol mechanisms for agent identity, authenticated requests, +message integrity, secure service discovery, protocol negotiation, and optional +end-to-end encryption Profiles. In particular, did:wba authentication proves +control of a verification method associated with a DID, while signatures and +digests protect the request components they cover from tampering. + +Successful ANP authentication is not the same as application authorization. A +server or receiving agent still needs to decide whether the authenticated DID is +allowed to access a resource, invoke an operation, or act for a user. Similarly, +ANP does not by itself guarantee task correctness, prompt-injection resistance, +business-rule enforcement, or prevention of information loss in multi-agent +workflows. Those decisions belong to the application, agent runtime, or +deployment policy. ANP implementations should preserve enough authenticated +context for those layers to make and audit each decision. + +## 2. Authentication and Authorization Boundary + +Implementations should keep identity proof separate from resource authorization: + +1. Verify the DID document, verification method, signature coverage, timestamp, + nonce, and message digest according to the relevant ANP Profile. +2. Treat successful verification as authentication of the sender or service + identity, not as permission to perform the requested action. +3. Apply local authorization policy to the authenticated DID, requested + resource, protocol Profile, and operation. +4. Preserve the distinction between authentication failure and authorization + failure in responses and security events. + +When an operation requires user presence or other high-assurance approval, the +application should enforce that policy through the applicable application +protocol or runtime capability contract. A DID document should not be treated as +proof that a human approved a specific action. + +### 2.1 Transport Bindings + +In HTTP bindings, an authentication failure generally maps to `401 Unauthorized`, +while an authenticated identity that lacks permission generally maps to +`403 Forbidden`. Other transports should use the error model defined by their +corresponding Profile while preserving the distinction between authentication +failure and authorization failure. Implementations should not assume that HTTP +status codes are available or meaningful in every ANP transport binding. + +## 3. Credential and Key Lifecycle + +The did:wba specification defines timestamp checks, nonce-based replay +protection, DID document verification, and access-token handling. Implementations +should also make their lifecycle behavior explicit: + +1. Use short, configurable validity windows for signatures, challenges, and + access tokens. +2. Fail closed when a DID document cannot be resolved, a verification method is + removed, a key no longer satisfies the required verification relationship, or + an access token has expired. +3. Track key and authorization-state versions so that rotation, revocation, and + DID document updates are visible to validation and audit logic. +4. Prefer sender-constrained access tokens when a compatible Profile is + available. Otherwise, treat bearer tokens as high-value secrets and limit + their lifetime, audience, and scope. + +These practices do not require a new wire-format field unless a future ANP +Profile standardizes one. + +### 3.1 Access Token Revocation Semantics + +Token expiration and token revocation are different events. Expiration bounds +how long a token can be accepted without an explicit revocation mechanism; it +does not make revocation take effect before the expiration time. + +Short-lived, narrowly scoped tokens are the recommended baseline. Token +lifetimes should decrease as the impact of misuse, breadth of scope, bearer-token +exposure, or expected revocation delay increases. A longer lifetime may be +appropriate only when compensating controls, such as sender constraint and an +online status check, justify it. + +Deployments should document whether they provide: + +1. Expiration-only invalidation, where a valid token remains usable until it + expires. +2. Best-effort early revocation, such as a distributed denylist keyed by token + identifier or authorization-state version. +3. Online validation, such as token introspection or an equivalent state lookup + for each protected request. + +Immediate revocation requires every resource server to consult sufficiently +current shared state before accepting the token. Replication delay, validation +caches, partitions, and failover can weaken that guarantee. Implementations +should therefore define the maximum propagation or cache delay and whether a +revocation-state outage fails closed or temporarily relies on token expiration. +A best-effort denylist improves incident response but should not be described as +immediate revocation unless those distributed-state conditions are met. + +### 3.2 Replay Protection Assumptions + +Timestamp validation narrows the replay window but does not replace nonce or +message-state validation. Replay protection should perform an atomic +check-and-record operation for `(keyid, nonce)`, `(keyid, jti)`, or the equivalent +Profile-specific replay key. + +In a multi-instance deployment, the replay store should either be shared by all +instances or partitioned so that every request with the same replay key is +guaranteed to reach the same owner. Routing, resharding, and failover must not +allow a duplicate to reach an instance that cannot observe the earlier +acceptance. A local in-memory cache on each independently routed instance is not +sufficient. + +After a service restart, an implementation should use one of these approaches: + +1. Restore a durable replay store before accepting requests. +2. Fail closed until every request accepted before the restart is outside the + timestamp acceptance window. +3. Reject requests using client-generated nonces and require a fresh, + server-issued, single-use challenge whose state was created after the + restart. + +For a request with an explicit expiration time, retain its replay entry until at +least that expiration time plus the permitted clock skew. If expiration is +derived from a creation time and maximum age, retain the entry through the end of +that derived acceptance window plus clock skew. Challenge nonces should remain +recorded for at least their full validity window. Rate limits and storage bounds +should not evict live replay entries in a way that makes an otherwise valid +duplicate acceptable. + +## 4. Security Event Hooks + +ANP implementations should expose security-relevant events to the application +or runtime layer. The guidance does not prescribe a logging backend, but the +following events should be observable to policy, monitoring, and +incident-response code: + +1. DID resolution, DID document verification, and verification-method mismatch. +2. Signature, digest, timestamp, nonce, replay-state, and access-token acceptance + or rejection. +3. Protocol negotiation start, accept, reject, failure, and negotiation or + artifact digest mismatch. +4. External artifact validation and local protocol-handler isolation failures. +5. Authorization decisions made after successful authentication. +6. Cross-domain or cross-protocol handoff events. + +Useful event fields include the source DID, destination DID, service DID if +applicable, session or negotiation identifier, protocol Profile, artifact or +negotiation digest, operation name, decision, timestamp, and error code. +Applications can redact or aggregate these fields according to their privacy +requirements. + +## 5. Negotiated Protocol Artifacts and Local Handlers + +ANP-06 defines semantic negotiation through `MetaProtocolInterface`, +`anp.get_capabilities`, and `anp.negotiate`. A negotiation result selects an +interface, Profile, security Profile, schema, content type, and execution mode. +It may reference an external protocol artifact, but ANP-06 does not require +remote code exchange or execution. Artifact publication, signing, review, and +governance remain outside the current ANP-06 interoperability requirements. + +Implementations should treat external artifacts and any locally generated or +loaded code as untrusted input. Recommended safeguards include: + +1. Confirm that the selected interface and Profiles remain consistent with the + target Agent Description, runtime capabilities, and local policy. +2. Bind an artifact to the digest obtained from an authenticated negotiation or + another trusted metadata channel. A digest supplied alongside untrusted + content does not establish authenticity. +3. Verify an artifact signature only against an authorized publisher key and an + explicit trust policy. Signature validity alone does not make the publisher + trusted. +4. Validate artifact schema, version, dependencies, content type, and size before + caching or processing it. +5. Treat natural-language instructions and executable content inside an + artifact as data unless local policy explicitly permits further processing. +6. Run locally generated or third-party handler code in a least-privilege + sandbox. Deny filesystem, network, credential, tool, and environment access + unless the application explicitly grants it. +7. Keep handler capabilities separate from the sender's authenticated identity. + Authenticating the sender should not grant locally loaded code additional + privileges. + +## 6. Cross-Protocol and Bridge Deployments + +ANP deployments may interact with other agent protocols, tool runtimes, or +application gateways. In these settings, the bridge component should preserve +security context instead of converting it into implicit authority. + +For example, when an ANP message leads to a call into another protocol or tool +system, the bridge should carry forward the relevant source DID, destination +DID, service DID, protocol Profile, session or negotiation identifier, and +authorization context. The receiving runtime should still apply its own policy +before reading files, invoking tools, sending network requests, or acting on +behalf of a user. + +This boundary is important because each protocol may verify only its local +message format and identity proof. A composed deployment can still create an +unsafe path if authenticated content from one side silently authorizes actions +on the other side. + +## 7. Payment Scenarios + +Payment-related scenarios require additional controls beyond this general +guidance. Implementations should follow the +[ANP Agent Payment Protocol](../application/10-anp-agent-payment-protocol-specification.md) +and pay particular attention to authorization scope, transaction integrity, +replay protection, and explicit user confirmation. A payment mandate or user +signature should be bound to the intended transaction details, and an +authenticated agent identity should not be treated as standing approval for a +payment. + +## 8. Implementation Checklist + +Implementers should verify that their deployment: + +1. Separates authentication from authorization. +2. Checks signature coverage, message digest, timestamp, nonce, and replay state + before accepting requests. +3. Defines token lifetime, scope, revocation guarantee, and outage behavior. +4. Coordinates replay state across instances, failover, and service restarts. +5. Defines key-rotation and DID document update behavior. +6. Avoids putting secrets, API keys, or bearer credentials in Agent Description + documents. +7. Treats external artifacts and local protocol-handler code as untrusted until + verified and isolated according to local policy. +8. Exposes security events to application policy and monitoring code. +9. Preserves source identity and protocol context across bridges, gateways, and + cross-protocol calls. +10. Requires explicit application policy for sensitive operations such as user + approval, file access, tool execution, payment, or external network access.