.NET: Add security warnings to xml comments for core components (#4527)

* Add security warnings to xml comments for core components * Address build errors. * Fix formatting issue * Fix formatting issue * Supress formatting warning * Supress format issue in ChatHistoryMemoryProvider * Fix remarks paragraphs
2026-06-16 21:04:09 +08:00 · 2026-03-06 19:04:22 +00:00
parent b98880df32
commit 1ca43f9643
10 changed files with 185 additions and 0 deletions
@@ -20,6 +20,19 @@ namespace Microsoft.Agents.AI;
 /// <see cref="AIAgent"/> serves as the foundational class for implementing AI agents that can participate in conversations
 /// and process user requests. An agent instance may participate in multiple concurrent conversations, and each conversation
 /// may involve multiple agents working together.
+/// <para>
+/// <strong>Security considerations:</strong> An <see cref="AIAgent"/> orchestrates data flow across trust boundaries —
+/// messages are sent to external AI services, context providers, chat history stores, and function tools. Agent Framework
+/// passes messages through as-is without validation or sanitization. Developers must be aware that:
+/// <list type="bullet">
+/// <item><description>User-supplied messages may contain prompt injection attempts designed to manipulate LLM behavior.</description></item>
+/// <item><description>LLM responses should be treated as untrusted output — they may contain hallucinations, malicious payloads (e.g., scripts, SQL),
+/// or content influenced by indirect prompt injection. Always validate and sanitize LLM output before rendering in HTML, executing as code,
+/// or using in database queries.</description></item>
+/// <item><description>Messages with different roles carry different trust levels: <c>system</c> messages have the highest trust and must be developer-controlled;
+/// <c>user</c>, <c>assistant</c>, and <c>tool</c> messages should be treated as untrusted.</description></item>
+/// </list>
+/// </para>
 /// </remarks>
 [DebuggerDisplay("{DebuggerDisplay,nq}")]
 public abstract partial class AIAgent
@@ -165,6 +178,11 @@ public abstract partial class AIAgent
    /// This method enables saving conversation sessions to persistent storage,
    /// allowing conversations to resume across application restarts or be migrated between
    /// different agent instances. Use <see cref="DeserializeSessionAsync"/> to restore the session.
+    /// <para>
+    /// <strong>Security consideration:</strong> Serialized sessions may contain conversation content, session identifiers,
+    /// and other potentially sensitive data including PII. Ensure that serialized session data is stored securely with
+    /// appropriate access controls and encryption at rest.
+    /// </para>
    /// </remarks>
    public ValueTask<JsonElement> SerializeSessionAsync(AgentSession session, JsonSerializerOptions? jsonSerializerOptions = null, CancellationToken cancellationToken = default)
        => this.SerializeSessionCoreAsync(session, jsonSerializerOptions, cancellationToken);
@@ -194,6 +212,12 @@ public abstract partial class AIAgent
    /// This method enables restoration of conversation sessions from previously saved state,
    /// allowing conversations to resume across application restarts or be migrated between
    /// different agent instances.
+    /// <para>
+    /// <strong>Security consideration:</strong> Restoring a session from an untrusted source is equivalent to accepting untrusted input.
+    /// Serialized sessions may contain conversation content, session identifiers, and potentially sensitive data. A compromised
+    /// storage backend could alter message roles to escalate trust, or inject adversarial content that influences LLM behavior.
+    /// Treat serialized session data as sensitive and ensure it is stored and transmitted securely.
+    /// </para>
    /// </remarks>
    public ValueTask<AgentSession> DeserializeSessionAsync(JsonElement serializedState, JsonSerializerOptions? jsonSerializerOptions = null, CancellationToken cancellationToken = default)
        => this.DeserializeSessionCoreAsync(serializedState, jsonSerializerOptions, cancellationToken);
@@ -301,6 +325,11 @@ public abstract partial class AIAgent
    /// The messages are processed in the order provided and become part of the conversation history.
    /// The agent's response will also be added to <paramref name="session"/> if one is provided.
    /// </para>
+    /// <para>
+    /// <strong>Security consideration:</strong> Agent Framework does not validate or sanitize message content — it is passed through
+    /// to the underlying AI service as-is. If input messages include untrusted user content, developers should be aware of prompt injection risks.
+    /// System-role messages must be developer-controlled and should never contain end-user input.
+    /// </para>
    /// </remarks>
    public Task<AgentResponse> RunAsync(
        IEnumerable<ChatMessage> messages,
@@ -426,6 +455,11 @@ public abstract partial class AIAgent
    /// Each <see cref="AgentResponseUpdate"/> represents a portion of the complete response, allowing consumers
    /// to display partial results, implement progressive loading, or provide immediate feedback to users.
    /// </para>
+    /// <para>
+    /// <strong>Security consideration:</strong> Agent Framework does not validate or sanitize message content — it is passed through
+    /// to the underlying AI service as-is. If input messages include untrusted user content, developers should be aware of prompt injection risks.
+    /// System-role messages must be developer-controlled and should never contain end-user input.
+    /// </para>
    /// </remarks>
    public async IAsyncEnumerable<AgentResponseUpdate> RunStreamingAsync(
        IEnumerable<ChatMessage> messages,
@@ -28,6 +28,14 @@ namespace Microsoft.Agents.AI;
 /// <see cref="InvokingAsync"/> to provide context, and optionally called at the end of invocation via
 /// <see cref="InvokedAsync"/> to process results.
 /// </para>
+/// <para>
+/// <strong>Security considerations:</strong> Context providers may inject messages with any role, including <c>system</c>, which
+/// has the highest trust level and directly shapes LLM behavior. Developers must ensure that all providers attached to an agent
+/// are trusted. Agent Framework does not validate or filter the data returned by providers — it is accepted as-is and merged into
+/// the request context. If a provider retrieves data from an external source (e.g., a vector database or memory service), be aware
+/// that a compromised data source could introduce adversarial content designed to manipulate LLM behavior via indirect prompt injection.
+/// Implementers should validate and sanitize data retrieved from external sources before returning it.
+/// </para>
 /// </remarks>
 public abstract class AIContextProvider
 {
@@ -96,6 +104,11 @@ public abstract class AIContextProvider
    /// <item><description>Injecting contextual messages from conversation history</description></item>
    /// </list>
    /// </para>
+    /// <para>
+    /// <strong>Security consideration:</strong> Data retrieved from external sources (e.g., vector databases, memory services, or
+    /// knowledge bases) may contain adversarial content designed to influence LLM behavior via indirect prompt injection.
+    /// Implementers should validate data integrity and consider the trustworthiness of the data source.
+    /// </para>
    /// </remarks>
    public ValueTask<AIContext> InvokingAsync(InvokingContext context, CancellationToken cancellationToken = default)
        => this.InvokingCoreAsync(Throw.IfNull(context), cancellationToken);
@@ -195,6 +208,11 @@ public abstract class AIContextProvider
    /// In contrast with <see cref="InvokingCoreAsync"/>, this method only returns additional context to be merged with the input,
    /// while <see cref="InvokingCoreAsync"/> is responsible for returning the full merged <see cref="AIContext"/> for the invocation.
    /// </para>
+    /// <para>
+    /// <strong>Security consideration:</strong> Any messages, tools, or instructions returned by this method will be merged into the
+    /// AI request context. If data is retrieved from external or untrusted sources, implementers should validate and sanitize it
+    /// to prevent indirect prompt injection attacks.
+    /// </para>
    /// </remarks>
    /// <param name="context">Contains the request context including the caller provided messages that will be used by the agent for this invocation.</param>
    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
@@ -299,6 +317,10 @@ public abstract class AIContextProvider
    /// <para>
    /// The default implementation of <see cref="InvokedCoreAsync"/> only calls this method if the invocation succeeded.
    /// </para>
+    /// <para>
+    /// <strong>Security consideration:</strong> Messages being processed/stored may contain PII and sensitive conversation content.
+    /// Implementers should ensure appropriate encryption at rest and access controls for the storage backend.
+    /// </para>
    /// </remarks>
    protected virtual ValueTask StoreAIContextAsync(InvokedContext context, CancellationToken cancellationToken = default) =>
        default;
@@ -42,6 +42,15 @@ namespace Microsoft.Agents.AI;
 /// <see cref="JsonElement"/> and the <see cref="AIAgent.DeserializeSessionAsync(JsonElement, JsonSerializerOptions?, System.Threading.CancellationToken)"/> method
 /// can be used to deserialize the session.
 /// </para>
+/// <para>
+/// <strong>Security considerations:</strong> Serialized sessions may contain conversation content, session identifiers,
+/// and other potentially sensitive data including PII. Developers should:
+/// <list type="bullet">
+/// <item><description>Treat serialized session data as sensitive and store it securely with appropriate access controls and encryption at rest.</description></item>
+/// <item><description>Treat restoring a session from an untrusted source as equivalent to accepting untrusted input. A compromised storage backend
+/// could alter message roles to escalate trust, or inject adversarial content that influences LLM behavior.</description></item>
+/// </list>
+/// </para>
 /// </remarks>
 /// <seealso cref="AIAgent"/>
 /// <seealso cref="AIAgent.CreateSessionAsync(System.Threading.CancellationToken)"/>
@@ -67,6 +76,11 @@ public abstract class AgentSession
    /// <summary>
    /// Gets any arbitrary state associated with this session.
    /// </summary>
+    /// <remarks>
+    /// Data stored in the <see cref="StateBag"/> will be included when the session is serialized.
+    /// Avoid storing secrets, credentials, or highly sensitive data in the state bag without appropriate encryption,
+    /// as this data may be persisted to external storage.
+    /// </remarks>
    [JsonPropertyName("stateBag")]
    public AgentSessionStateBag StateBag { get; protected set; } = new();

@@ -37,6 +37,14 @@ namespace Microsoft.Agents.AI;
 /// A <see cref="ChatHistoryProvider"/> is only relevant for scenarios where the underlying AI service that the agent is using
 /// does not use in-service chat history storage.
 /// </para>
+/// <para>
+/// <strong>Security considerations:</strong> Agent Framework does not validate or filter the messages returned by the provider
+/// during load — they are accepted as-is and treated identically to user-supplied messages. Implementers must ensure that only
+/// trusted data is returned. If the underlying storage is compromised, adversarial content could influence LLM behavior via
+/// indirect prompt injection — for example, injected messages could alter the conversation context or impersonate different roles.
+/// Messages stored in chat history may contain PII and sensitive conversation content; implementers should consider encryption
+/// at rest and appropriate access controls for the storage backend.
+/// </para>
 /// </remarks>
 public abstract class ChatHistoryProvider
 {
@@ -159,6 +167,11 @@ public abstract class ChatHistoryProvider
    /// Messages are returned in chronological order to maintain proper conversation flow and context for the agent.
    /// The oldest messages appear first in the collection, followed by more recent messages.
    /// </para>
+    /// <para>
+    /// <strong>Security consideration:</strong> Messages loaded from storage should be treated with the same caution as user-supplied
+    /// messages. A compromised storage backend could alter message roles to escalate trust (e.g., changing <c>user</c> messages to
+    /// <c>system</c> messages) or inject adversarial content that influences LLM behavior.
+    /// </para>
    /// </remarks>
    /// <param name="context">Contains the request context including the caller provided messages that will be used by the agent for this invocation.</param>
    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
@@ -273,6 +286,10 @@ public abstract class ChatHistoryProvider
    /// <para>
    /// The default implementation of <see cref="InvokedCoreAsync"/> only calls this method if the invocation succeeded.
    /// </para>
+    /// <para>
+    /// <strong>Security consideration:</strong> Messages being stored may contain PII and sensitive conversation content.
+    /// Implementers should ensure appropriate encryption at rest and access controls for the storage backend.
+    /// </para>
    /// </remarks>
    protected virtual ValueTask StoreChatHistoryAsync(InvokedContext context, CancellationToken cancellationToken = default) =>
        default;
@@ -17,6 +17,24 @@ namespace Microsoft.Agents.AI;
 /// <summary>
 /// Provides a Cosmos DB implementation of the <see cref="ChatHistoryProvider"/> abstract class.
 /// </summary>
+/// <remarks>
+/// <para>
+/// <strong>Security considerations:</strong>
+/// <list type="bullet">
+/// <item><description><strong>PII and sensitive data:</strong> Chat history stored in Cosmos DB may contain PII, sensitive conversation
+/// content, and system instructions. Ensure the Cosmos DB account is configured with appropriate access controls, encryption at rest,
+/// and network security (e.g., private endpoints, virtual network rules). The <see cref="MessageTtlSeconds"/> property can be used to
+/// automatically expire messages and limit data retention.</description></item>
+/// <item><description><strong>Compromised store risks:</strong> Agent Framework does not validate or filter messages loaded from the
+/// store — they are accepted as-is. If the Cosmos DB store is compromised, adversarial content could be injected into the conversation
+/// context, potentially influencing LLM behavior via indirect prompt injection. Altered message roles (e.g., changing <c>user</c> to
+/// <c>system</c>) could escalate trust levels.</description></item>
+/// <item><description><strong>Authentication:</strong> Agent Framework does not manage authentication or encryption for the Cosmos DB
+/// connection — these are the responsibility of the <see cref="CosmosClient"/> configuration. Use managed identity
+/// or token-based authentication where possible, and avoid embedding connection strings with keys in source code.</description></item>
+/// </list>
+/// </para>
+/// </remarks>
 [RequiresUnreferencedCode("The CosmosChatHistoryProvider uses JSON serialization which is incompatible with trimming.")]
 [RequiresDynamicCode("The CosmosChatHistoryProvider uses JSON serialization which is incompatible with NativeAOT.")]
 public sealed class CosmosChatHistoryProvider : ChatHistoryProvider, IDisposable
@@ -13,16 +13,38 @@ using Microsoft.Shared.Diagnostics;

 namespace Microsoft.Agents.AI.Mem0;

+#pragma warning disable IDE0001 // Simplify Names - Microsoft.Extensions.Logging.LogLevel.Trace doesn't get found in net472 when removing the namespace.
 /// <summary>
 /// Provides a Mem0 backed <see cref="MessageAIContextProvider"/> that persists conversation messages as memories
 /// and retrieves related memories to augment the agent invocation context.
 /// </summary>
 /// <remarks>
+/// <para>
 /// The provider stores user, assistant and system messages as Mem0 memories and retrieves relevant memories
 /// for new invocations using a semantic search endpoint. Retrieved memories are injected as user messages
 /// to the model, prefixed by a configurable context prompt.
+/// </para>
+/// <para>
+/// <strong>Security considerations:</strong>
+/// <list type="bullet">
+/// <item><description><strong>External service trust:</strong> This provider communicates with an external Mem0 service over HTTP.
+/// Agent Framework does not manage authentication, encryption, or connection details for this service — these are the responsibility
+/// of the <see cref="HttpClient"/> configuration. Ensure the HTTP client is configured with appropriate authentication
+/// and uses HTTPS to protect data in transit.</description></item>
+/// <item><description><strong>PII and sensitive data:</strong> Conversation messages (including user inputs, LLM responses, and system
+/// instructions) are sent to the external Mem0 service for storage. These messages may contain PII or sensitive information.
+/// Ensure the Mem0 service is configured with appropriate data retention policies and access controls.</description></item>
+/// <item><description><strong>Indirect prompt injection:</strong> Memories retrieved from the Mem0 service are injected into the LLM
+/// context as user messages. If the memory store is compromised, adversarial content could influence LLM behavior. The data
+/// returned from the service is accepted as-is without validation or sanitization.</description></item>
+/// <item><description><strong>Trace logging:</strong> When <see cref="Microsoft.Extensions.Logging.LogLevel.Trace"/> is enabled,
+/// full memory content (including search queries and results) may be logged. This data may contain PII and should not be enabled
+/// in production environments.</description></item>
+/// </list>
+/// </para>
 /// </remarks>
 public sealed class Mem0Provider : MessageAIContextProvider
+#pragma warning restore IDE0001 // Simplify Names
 {
    private const string DefaultContextPrompt = "## Memories\nConsider the following memories when answering user questions:";

@@ -17,6 +17,25 @@ namespace Microsoft.Agents.AI;
 /// <summary>
 /// Provides an <see cref="AIAgent"/> that delegates to an <see cref="IChatClient"/> implementation.
 /// </summary>
+/// <remarks>
+/// <para>
+/// <strong>Security considerations:</strong> The <see cref="ChatClientAgent"/> orchestrates data flow across trust boundaries.
+/// The underlying AI service is an external endpoint and LLM responses should be treated as untrusted output. Developers should be aware of:
+/// <list type="bullet">
+/// <item><description><strong>Hallucination:</strong> LLMs may generate plausible-sounding but factually incorrect information.
+/// Do not treat LLM output as authoritative without verification.</description></item>
+/// <item><description><strong>Indirect prompt injection:</strong> Data retrieved by tools, AI context providers, or chat history providers may
+/// contain adversarial content designed to influence LLM behavior or exfiltrate data through tool calls.</description></item>
+/// <item><description><strong>Malicious payloads:</strong> LLM output may contain content that is harmful if rendered or executed without
+/// sanitization — for example, HTML/JavaScript for cross-site scripting, SQL for injection, or shell commands.</description></item>
+/// <item><description><strong>Tool invocation:</strong> By default, all tools provided to the agent are invoked without user approval.
+/// The AI selects which functions to call and with what arguments. Function arguments should be treated as untrusted input.
+/// Developers should require explicit approval for tools with side effects, data sensitivity, or irreversibility.</description></item>
+/// </list>
+/// Developers should validate and sanitize LLM output before rendering it in HTML, executing it as code, using it in database queries,
+/// or passing it to any security-sensitive context. Apply defense-in-depth by combining tool approval requirements with output validation.
+/// </para>
+/// </remarks>
 public sealed partial class ChatClientAgent : AIAgent
 {
    private readonly ChatClientAgentOptions? _agentOptions;
@@ -44,6 +63,9 @@ public sealed partial class ChatClientAgent : AIAgent
    /// Optional collection of tools that the agent can invoke during conversations.
    /// These tools augment any tools that may be provided to the agent via <see cref="ChatOptions.Tools"/> when
    /// the agent is run.
+    /// By default, all provided tools are invoked without user approval. The AI selects which functions to call and chooses
+    /// the arguments — these arguments should be treated as untrusted input. Developers should require explicit approval
+    /// for tools that have side effects, access sensitive data, or perform irreversible operations.
    /// </param>
    /// <param name="loggerFactory">
    /// Optional logger factory for creating loggers used by the agent and its components.
@@ -13,6 +13,7 @@ using Microsoft.Shared.Diagnostics;

 namespace Microsoft.Agents.AI;

+#pragma warning disable IDE0001 // Simplify Names - Microsoft.Extensions.Logging.LogLevel.Trace doesn't get found in net472 when removing the namespace.
 /// <summary>
 /// A context provider that stores all chat history in a vector store and is able to
 /// retrieve related chat history later to augment the current conversation.
@@ -33,8 +34,25 @@ namespace Microsoft.Agents.AI;
 /// exposes a function tool that the model can invoke to retrieve relevant memories on demand instead of
 /// injecting them automatically on each invocation.
 /// </para>
+/// <para>
+/// <strong>Security considerations:</strong>
+/// <list type="bullet">
+/// <item><description><strong>Indirect prompt injection:</strong> Messages retrieved from the vector store via semantic search
+/// are injected into the LLM context. If the vector store is compromised, adversarial content could influence LLM behavior.
+/// The data returned from the store is accepted as-is without validation or sanitization.</description></item>
+/// <item><description><strong>PII and sensitive data:</strong> Conversation messages (including user inputs and LLM responses)
+/// are stored as vectors in the underlying store. These messages may contain PII or sensitive information. Ensure the vector
+/// store is configured with appropriate access controls and encryption at rest.</description></item>
+/// <item><description><strong>On-demand search tool:</strong> When using <see cref="ChatHistoryMemoryProviderOptions.SearchBehavior.OnDemandFunctionCalling"/>,
+/// the AI model controls when and what to search for. The search query is AI-generated and should be treated as untrusted input
+/// by the vector store implementation.</description></item>
+/// <item><description><strong>Trace logging:</strong> When <see cref="Microsoft.Extensions.Logging.LogLevel.Trace"/> is enabled,
+/// full search queries and results may be logged. This data may contain PII.</description></item>
+/// </list>
+/// </para>
 /// </remarks>
 public sealed class ChatHistoryMemoryProvider : MessageAIContextProvider, IDisposable
+#pragma warning restore IDE0001 // Simplify Names
 {
    private const string DefaultContextPrompt = "## Memories\nConsider the following memories when answering user questions:";
    private const int DefaultMaxResults = 3;
@@ -70,6 +70,12 @@ public sealed class OpenTelemetryAgent : DelegatingAIAgent, IDisposable
    /// and outputs, such as message content, function call arguments, and function call results.
    /// The default value can be overridden by setting the <c>OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT</c>
    /// environment variable to "true". Explicitly setting this property will override the environment variable.
+    /// <para>
+    /// <strong>Security consideration:</strong> When sensitive data capture is enabled, the full text of chat messages —
+    /// including user inputs, LLM responses, function call arguments, and function results — is emitted as telemetry.
+    /// This data may contain PII or other sensitive information. Ensure that your telemetry pipeline is configured
+    /// with appropriate access controls and data retention policies.
+    /// </para>
    /// </remarks>
    public bool EnableSensitiveData
    {
@@ -31,6 +31,18 @@ namespace Microsoft.Agents.AI;
 /// to the current request messages when forming the search input. This can improve search relevance by providing
 /// multi-turn context to the retrieval layer without permanently altering the conversation history.
 /// </para>
+/// <para>
+/// <strong>Security considerations:</strong> Search results retrieved from external sources are injected into the LLM context and may
+/// contain adversarial content designed to manipulate LLM behavior via indirect prompt injection. Developers should be aware that:
+/// <list type="bullet">
+/// <item><description>The search query may be constructed from user input or LLM-generated content, both of which are untrusted.
+/// Implementers of the search delegate should validate search inputs and apply appropriate access controls to search results.</description></item>
+/// <item><description>Retrieved documents are formatted and injected as messages in the AI request context. If the external data source
+/// is compromised, adversarial content could influence the LLM's responses.</description></item>
+/// <item><description>When using <see cref="TextSearchProviderOptions.TextSearchBehavior.OnDemandFunctionCalling"/>, the AI model controls
+/// when and what to search for — the search query text is AI-generated and should be treated as untrusted input by the search implementation.</description></item>
+/// </list>
+/// </para>
 /// </remarks>
 public sealed class TextSearchProvider : MessageAIContextProvider
 {