diff --git a/10-security-considerations.md b/10-security-considerations.md new file mode 100644 index 0000000..0bf1fc1 --- /dev/null +++ b/10-security-considerations.md @@ -0,0 +1,139 @@ +# ANP Security Considerations + +This document summarizes security guidance that cuts across the ANP +specifications. It does not replace the protocol-specific requirements in the +DID:WBA, Agent Description, Agent Discovery, Meta-Protocol, or Messaging +documents. Instead, it clarifies the security boundary that implementations and +applications should preserve when they compose these mechanisms. + +## 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 the +identity associated with a DID verification method, and message signatures or +digests protect the covered request components 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 the 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. Return an authentication error, such as `401 Unauthorized`, when identity + proof fails; return an authorization error, such as `403 Forbidden`, when the + DID is authenticated but lacks permission. + +When an operation requires user presence or other high-assurance approval, the +application should express that policy in the agent description or runtime +capability contract. A DID document should not be treated as proof that a human +approved a specific action. + +## 3. Credential and Key Lifecycle + +DID:WBA already defines timestamp checks, nonce-based replay protection, DID +document verification, and access-token handling. Implementations should also +make the lifecycle behavior explicit: + +1. Use short and configurable validity windows for signatures, challenges, and + access tokens. +2. Keep replay-cache entries at least as long as the accepted signature or + challenge window. +3. 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. +4. Version or otherwise track key material so that rotation, revocation, and DID + document updates are visible to authorization and audit logic. +5. Prefer sender-constrained access tokens when a compatible profile is + available; otherwise, treat bearer tokens as high-value secrets and limit + their lifetime and scope. + +These items are implementation guidance. They do not require a new wire-format +field unless a future ANP profile chooses to standardize one. + +## 4. Security Event Hooks + +ANP implementations should expose security-relevant events to the application +or runtime layer. The specification does not need to mandate a particular +logging backend, but implementations should make the following events observable +to policy, monitoring, and incident-response code: + +1. DID resolution, DID-document verification, and verification-method mismatch. +2. Signature, digest, timestamp, nonce, replay-cache, and access-token + acceptance or rejection. +3. Protocol negotiation start, accept, reject, failure, and protocol-hash + mismatch. +4. Generated or loaded protocol-handler verification 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, protocol hash, +operation name, decision, timestamp, and error code. Applications can redact or +aggregate these fields according to their privacy requirements. + +## 5. Generated Protocol Code and Negotiated Handlers + +The Meta-Protocol allows agents to negotiate or reuse protocol descriptions. +Implementations should treat generated or dynamically loaded handlers as +untrusted until verified. Recommended safeguards include: + +1. Bind generated handlers to the negotiated protocol identifier and protocol + hash. +2. Verify signatures or provenance for reusable protocol packages when such + metadata is available. +3. Run generated or third-party handler code in a least-privilege sandbox. +4. Deny filesystem, network, credential, tool, and environment access unless + the application explicitly grants it. +5. Keep the handler's allowed capabilities separate from the sender's + authenticated identity; authenticating the sender should not automatically + grant the handler new local 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 +the 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 hash, 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. 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, token scope, and key-rotation behavior. +4. Avoids putting secrets, API keys, or bearer credentials in agent description + documents. +5. Treats generated protocol handlers and third-party handler packages as + untrusted code until verified and sandboxed. +6. Exposes security events to application policy and monitoring code. +7. Preserves source identity and protocol context across bridges, gateways, and + cross-protocol calls. +8. Requires explicit application policy for sensitive operations such as user + approval, file access, tool execution, payment, or external network access. diff --git a/README.md b/README.md index e82f08b..81b2560 100644 --- a/README.md +++ b/README.md @@ -83,6 +83,7 @@ We are developing an open-source implementation of AgentNetworkProtocol, and its - Complete materials are available at [Extended Reading](docs/links.md) - For detailed design, please read the [ANP Technical White Paper](/01-agentnetworkprotocol-technical-white-paper.md) +- For cross-cutting security guidance, see [ANP Security Considerations](/10-security-considerations.md) - Refer to the open-source implementation [AgentConnect Examples](https://github.com/agent-network-protocol/AgentConnect) ## Milestones diff --git a/docs/links.md b/docs/links.md index a5533c8..8da2bbd 100644 --- a/docs/links.md +++ b/docs/links.md @@ -6,6 +6,7 @@ For ease of reference, all ANP-related materials are organized by **Specificatio - [ANP Getting Started Guide](/docs/anp-getting-started-guide.md) - [did:wba Method Specification](/03-did-wba-method-design-specification.md) +- [ANP Security Considerations](/10-security-considerations.md) - [ANP End-to-End Instant Messaging Protocol Overview](/09-ANP-end-to-end-instant-messaging-protocol-specification.md) - [ANP Profile 1: Core Binding](/message/01-core-binding.md) - [ANP Profile 2: Identity and Discovery](/message/02-identity-and-discovery.md)