Note: For the official security policy and vulnerability reporting process, please see the Security Policy document.

This document details the security mechanisms, considerations, and best practices... Security is a fundamental aspect of the AgentVault ecosystem, designed to enable trustworthy interactions between agents and protect user/developer credentials. This document details the security mechanisms, considerations, and best practices.

Authentication verifies the identity of the communicating parties. AgentVault employs different mechanisms for client-to-agent and developer-to-registry interactions.

Agents declare how clients should authenticate in their AgentCard (authSchemes). The agentvault library (used by the CLI and custom clients) supports:

• none:
  • Mechanism: No authentication headers are sent.
  • Use Case: Suitable for public agents providing non-sensitive information or actions.
  • Security: Offers no protection against unauthorized access. Use only when the agent's functionality requires no access control.
• apiKey:
  • Mechanism: The client sends a pre-shared secret key in the X-Api-Key HTTP header.
  • Client-Side: The agentvault library's KeyManager retrieves the key associated with the agent's service_identifier from local storage (env, file, or OS keyring).
  • Server-Side: The agent server (implementer) is responsible for receiving the X-Api-Key header and validating the key against its own secure storage (e.g., environment variable, configuration management system, database with hashed keys). Never hardcode keys in agent source code.
  • Security: Relies on the secrecy of the key and secure transport (HTTPS). Simpler to implement but less flexible than OAuth.
• oauth2 (Client Credentials Grant):
  • Mechanism: The client uses its own credentials (Client ID & Secret) to obtain a short-lived Bearer token from the agent's designated Token Endpoint (tokenUrl in Agent Card), then uses that token for subsequent A2A requests.
  • Client-Side: KeyManager retrieves the Client ID/Secret for the agent's service_identifier. AgentVaultClient performs the POST request to the tokenUrl to get the access_token and caches it (in memory). It sends the token in the Authorization: Bearer <token> header.
  • Server-Side: The agent server must provide a /token endpoint compliant with the OAuth 2.0 Client Credentials grant flow. It validates the received Client ID/Secret and issues a signed, potentially short-lived Bearer token (e.g., a JWT). The main /a2a endpoint must then validate incoming Bearer tokens (check signature, expiry, audience, scopes if applicable).
  • Security: More complex but standard-based. Allows for token revocation, scopes, and avoids sending long-lived secrets directly to the agent endpoint after initial token exchange. Requires secure handling of Client ID/Secret on the client and robust token validation on the server.
• bearer:
  • Mechanism: The client sends a pre-existing Bearer token in the Authorization: Bearer <token> header.
  • Client-Side: Assumes the client application has obtained a suitable token through some other means (e.g., user login flow, separate OAuth process). The agentvault library simply passes this token along if configured.
  • Server-Side: The agent server must validate the received Bearer token.
  • Security: Depends entirely on the security of the token issuance and validation process external to the basic A2A interaction.

• Mechanism: Uses an API Key (X-Api-Key header) specific to the developer.
• Key Generation: Keys are generated by registry administrators (currently manual, future portal TBD) using secrets.token_urlsafe and prefixed (avreg_).
• Storage: The hash of the developer's API key is stored in the registry database (Developer.api_key_hash) using passlib with bcrypt. Plain text keys are never stored.
• Verification: The registry API uses passlib.verify(plain_key, stored_hash) to authenticate developers attempting to manage their Agent Cards.
• Security: Relies on the developer keeping their plain-text key secret and secure transport (HTTPS). Hashing prevents exposure of the plain key even if the database is compromised. The current lookup method iterates hashes, which is a scalability concern but not a direct security flaw for moderate numbers of developers.

The agentvault library's KeyManager provides a unified way for clients (like the CLI) to manage credentials needed for agent authentication.

• Secure Storage: Strongly recommends using the OS Keyring (--keyring option in CLI config set) for storing sensitive API keys and OAuth secrets. This leverages platform-specific secure storage mechanisms.
• Alternative Sources: Supports loading from environment variables and .env/.json files for flexibility, but users should be aware of the security implications of storing secrets in these locations (filesystem permissions, environment variable visibility).
• Abstraction: Client code interacts with KeyManager (get_key, get_oauth_client_id, etc.) without needing to know where the credential came from.

• HTTPS is MANDATORY for all communication with the AgentVault Registry API and any A2A agent endpoint not running on localhost.
• Agent Card url and tokenUrl fields should use https://.
• Failure to use HTTPS exposes authentication credentials (API keys, Bearer tokens) and message content to eavesdropping.

• Pydantic: All components heavily utilize Pydantic models for defining data structures (Agent Cards, API request/response bodies, A2A messages). Pydantic performs automatic data validation on input, preventing many types of injection or malformed data errors.
• Registry: Validates submitted card_data against the canonical agentvault.models.AgentCard schema before storing it.
• Server SDK: The create_a2a_router automatically validates incoming JSON-RPC params against the type hints of the corresponding agent handler method.

• Registry: Implements basic IP-based rate limiting using slowapi to mitigate simple denial-of-service and abuse patterns. Production deployments may require more sophisticated limiting.
• Agents: Agent developers are responsible for implementing appropriate rate limiting on their own A2A endpoints if needed.

• Declaration: Agent Cards can declare (capabilities.teeDetails) that an agent runs within a TEE, providing metadata like the TEE type and potentially an attestation endpoint URL.
• Discovery: The registry allows filtering agents based on TEE support.
• Verification (Future Work): Currently, AgentVault clients do not automatically verify TEE attestations. Implementing robust, automated attestation verification and potentially establishing secure channels based on TEE keys is a complex task planned for future development. Users currently rely on the agent's declaration and must perform any verification manually or through out-of-band mechanisms.

• Auditing: The project includes a GitHub Actions workflow (dependency_audit.yml) using pip-audit to automatically scan dependencies listed in poetry.lock files for known vulnerabilities on pushes/PRs to main.
• Updates: Regularly updating dependencies (e.g., via poetry update) is crucial to patch vulnerabilities.

Please report suspected security vulnerabilities privately according to the Security Policy.