Skip to content

Commit a3fc29d

Browse files
westey-meoindoherty1Copilot
authored
.NET/Python: Add more content types to purview handling (#8370)
* Add more content types to purview handling * Address PR comments * Split Purview content processing requests Create one processContent request per content entry in both .NET and Python while preserving the Graph contentEntries array contract. Co-authored-by: Copilot <[email protected]> * Skip empty Purview content Avoid sending empty text or binary data to Graph processContent APIs in both .NET and Python. Co-authored-by: Copilot <[email protected]> * Address PR comments --------- Co-authored-by: Eoin Doherty <[email protected]> Co-authored-by: Copilot <[email protected]>
1 parent 52e03cb commit a3fc29d

11 files changed

Lines changed: 1396 additions & 87 deletions

File tree

‎dotnet/src/Microsoft.Agents.AI.Purview/Models/Common/ContentToProcess.cs‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,19 +14,19 @@ internal sealed class ContentToProcess
1414
/// <summary>
1515
/// Creates a new instance of ContentToProcess.
1616
/// </summary>
17-
/// <param name="contentEntries">The content to send and its associated ids.</param>
17+
/// <param name="contentEntry">The content to send and its associated id.</param>
1818
/// <param name="activityMetadata">Metadata about the activity performed with the content.</param>
1919
/// <param name="deviceMetadata">Metadata about the device that produced the content.</param>
2020
/// <param name="integratedAppMetadata">Metadata about the application integrating with Purview.</param>
2121
/// <param name="protectedAppMetadata">Metadata about the application being protected by Purview.</param>
2222
public ContentToProcess(
23-
List<ProcessContentMetadataBase> contentEntries,
23+
ProcessContentMetadataBase contentEntry,
2424
ActivityMetadata activityMetadata,
2525
DeviceMetadata deviceMetadata,
2626
IntegratedAppMetadata integratedAppMetadata,
2727
ProtectedAppMetadata protectedAppMetadata)
2828
{
29-
this.ContentEntries = contentEntries;
29+
this.ContentEntries = [contentEntry];
3030
this.ActivityMetadata = activityMetadata;
3131
this.DeviceMetadata = deviceMetadata;
3232
this.IntegratedAppMetadata = integratedAppMetadata;

‎dotnet/src/Microsoft.Agents.AI.Purview/README.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -273,3 +273,39 @@ catch (PurviewException e)
273273
this._logger.LogError(e, "Purview middleware threw an exception.")
274274
}
275275
```
276+
277+
## Security Considerations
278+
279+
### Identity is a trusted input
280+
281+
Purview evaluates DLP policy **for a specific user**. The identity this integration resolves therefore
282+
decides *which* policy is applied, and it is resolved in this order:
283+
284+
1. The user id from the configured `TokenCredential`'s token, when the credential resolves to a user.
285+
2. The `userId` argument passed to the processor.
286+
3. `ChatMessage.AdditionalProperties["userId"]`.
287+
4. `ChatMessage.AuthorName`, when it is a GUID.
288+
289+
Only source 1 is verified. Sources 2-4 are supplied by the hosting application, so **a host must not
290+
populate them from data that has crossed a trust boundary**. If an end user, an upstream service or a
291+
model response can influence `AdditionalProperties["userId"]` or `AuthorName`, that party can select a
292+
different user's DLP policy - typically one with weaker rules - and evade enforcement. Where identity
293+
must come from a request, derive it from a validated token on the server, never from the request body.
294+
Prefer a user-delegated credential (source 1) whenever possible.
295+
296+
`PurviewAppLocation` in `PurviewSettings` is trusted in the same way: it selects which policy locations
297+
apply and must be configured by the host, not by the caller.
298+
299+
### Fail-closed behaviour
300+
301+
Policy evaluation fails closed. If no user id can be resolved, or the tenant or app location cannot be
302+
determined, `PurviewRequestException` is thrown rather than letting content through unevaluated. Use
303+
`IgnoreExceptions` if you deliberately want availability over enforcement - but understand that it
304+
disables enforcement for every error, not just transient ones.
305+
306+
### What is evaluated
307+
308+
Every content item on a message is submitted for evaluation, not just its text: `DataContent` is sent
309+
as Purview binary content, and `FunctionCallContent`, `FunctionResultContent` and other structured
310+
content are serialized to text. Only `UsageContent` is skipped, because it carries token counts rather
311+
than user data.

‎dotnet/src/Microsoft.Agents.AI.Purview/ScopedContentProcessor.cs‎

Lines changed: 211 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
using System;
44
using System.Collections.Generic;
55
using System.Linq;
6+
using System.Text.Json;
67
using System.Threading;
78
using System.Threading.Tasks;
89
using Microsoft.Agents.AI.Purview.Models.Common;
@@ -22,6 +23,11 @@ internal sealed class ScopedContentProcessor : IScopedContentProcessor
2223
private readonly ICacheProvider _cacheProvider;
2324
private readonly IChannelHandler _channelHandler;
2425

26+
/// <summary>
27+
/// The characters that terminate the authority of a URL, being the start of the path, query or fragment.
28+
/// </summary>
29+
private static readonly char[] s_authorityDelimiters = ['/', '?', '#'];
30+
2531
/// <summary>
2632
/// Create a new instance of <see cref="ScopedContentProcessor"/>.
2733
/// </summary>
@@ -52,12 +58,7 @@ public ScopedContentProcessor(IPurviewClient purviewClient, ICacheProvider cache
5258
foreach (DlpActionInfo policyAction in processContentResponse.PolicyActions)
5359
{
5460
// We need to process all data before blocking, so set the flag and return it outside of this loop.
55-
if (policyAction.Action == DlpAction.BlockAccess)
56-
{
57-
shouldBlock = true;
58-
}
59-
60-
if (policyAction.RestrictionAction == RestrictionAction.Block)
61+
if (IsBlockingAction(policyAction))
6162
{
6263
shouldBlock = true;
6364
}
@@ -68,6 +69,85 @@ public ScopedContentProcessor(IPurviewClient purviewClient, ICacheProvider cache
6869
return (shouldBlock, resolvedUserId);
6970
}
7071

72+
/// <summary>
73+
/// Whether a policy action means the content must not be released.
74+
/// </summary>
75+
/// <remarks>
76+
/// <see cref="DlpAction.RestrictAccess"/> is not blocking on its own: it carries a separate
77+
/// <see cref="RestrictionAction"/> that selects the enforcement mode, which may be
78+
/// <see cref="RestrictionAction.Audit"/>, <see cref="RestrictionAction.Warn"/> or
79+
/// <see cref="RestrictionAction.Allow"/> as well as <see cref="RestrictionAction.Block"/>. Only an
80+
/// explicit <see cref="RestrictionAction.Block"/> mode withholds the content.
81+
/// </remarks>
82+
/// <param name="actionInfo">The policy action to inspect.</param>
83+
/// <returns><see langword="true"/> when the action blocks the content.</returns>
84+
private static bool IsBlockingAction(DlpActionInfo actionInfo)
85+
=> actionInfo.Action == DlpAction.BlockAccess
86+
|| actionInfo.RestrictionAction == RestrictionAction.Block;
87+
88+
/// <summary>
89+
/// Filter policy actions down to the ones that block.
90+
/// </summary>
91+
/// <param name="actionInfos">The policy actions to filter.</param>
92+
/// <returns>The blocking subset of <paramref name="actionInfos"/>.</returns>
93+
private static List<DlpActionInfo> GetBlockingActions(List<DlpActionInfo> actionInfos)
94+
{
95+
List<DlpActionInfo> blockingActions = [];
96+
97+
foreach (DlpActionInfo actionInfo in actionInfos)
98+
{
99+
if (IsBlockingAction(actionInfo))
100+
{
101+
blockingActions.Add(actionInfo);
102+
}
103+
}
104+
105+
return blockingActions;
106+
}
107+
108+
/// <summary>
109+
/// Normalize a policy location value for comparison, according to its location type.
110+
/// </summary>
111+
/// <remarks>
112+
/// Application ids (GUIDs) and domain names are case-insensitive, so those fold whole. URL values
113+
/// are not. Only the scheme and the host are case-insensitive; the userinfo, path, query and
114+
/// fragment are all case-sensitive, so folding a URL whole would let a scope for
115+
/// <c>contoso.com/public</c> match a request for <c>contoso.com/Public</c>. Location types that are
116+
/// not recognized fold whole, which matches more scopes rather than fewer.
117+
/// </remarks>
118+
/// <param name="locationType">The location type segment, for example <c>policyLocationUrl</c>.</param>
119+
/// <param name="value">The location value to normalize.</param>
120+
/// <returns>The value in its comparable form.</returns>
121+
private static string NormalizeLocationValue(string locationType, string value)
122+
{
123+
if (!locationType.EndsWith("url", StringComparison.OrdinalIgnoreCase))
124+
{
125+
return value.ToUpperInvariant();
126+
}
127+
128+
int schemeEnd = value.IndexOf("://", StringComparison.Ordinal);
129+
int authorityStart = schemeEnd >= 0 ? schemeEnd + 3 : 0;
130+
131+
// The authority ends at the first path, query or fragment delimiter, whichever comes first.
132+
int authorityEnd = value.IndexOfAny(s_authorityDelimiters, authorityStart);
133+
if (authorityEnd < 0)
134+
{
135+
authorityEnd = value.Length;
136+
}
137+
138+
// Credentials are case-sensitive, so only the host half of the authority folds.
139+
string authority = value.Substring(authorityStart, authorityEnd - authorityStart);
140+
int userInfoEnd = authority.LastIndexOf('@');
141+
string userInfo = userInfoEnd >= 0 ? authority.Substring(0, userInfoEnd + 1) : string.Empty;
142+
string host = userInfoEnd >= 0 ? authority.Substring(userInfoEnd + 1) : authority;
143+
144+
return string.Concat(
145+
value.Substring(0, authorityStart).ToUpperInvariant(),
146+
userInfo,
147+
host.ToUpperInvariant(),
148+
value.Substring(authorityEnd));
149+
}
150+
71151
private static bool TryGetUserIdFromPayload(IEnumerable<ChatMessage> messages, out string? userId)
72152
{
73153
userId = null;
@@ -115,12 +195,9 @@ private async Task<List<ProcessContentRequest>> MapMessageToPCRequestsAsync(IEnu
115195
foreach (ChatMessage message in messages)
116196
{
117197
string messageId = message.MessageId ?? Guid.NewGuid().ToString();
118-
ContentBase content = new PurviewTextContent(message.Text);
119198
string correlationId = (sessionId ?? Guid.NewGuid().ToString()) + "@AF";
120-
ProcessConversationMetadata conversationMetadata = new(content, messageId, false, $"Agent Framework Message {messageId}", correlationId)
121-
{
122-
SequenceNumber = DateTime.UtcNow.Ticks,
123-
};
199+
long baseSequenceNumber = DateTime.UtcNow.Ticks;
200+
List<ContentBase> mappedContents = MapMessageContents(message);
124201
ActivityMetadata activityMetadata = new(activity);
125202
PolicyLocation policyLocation;
126203

@@ -158,20 +235,127 @@ private async Task<List<ProcessContentRequest>> MapMessageToPCRequestsAsync(IEnu
158235
OperatingSystemVersion = "Unknown"
159236
}
160237
};
161-
ContentToProcess contentToProcess = new([conversationMetadata], activityMetadata, deviceMetadata, integratedAppMetadata, protectedAppMetadata);
162238

163239
if (string.IsNullOrEmpty(resolvedUserId))
164240
{
165241
throw new PurviewRequestException("No user id provided or inferred for Purview request. Please provide an Entra user id in each message, pass a user id to the processor, or configure the TokenCredential to authenticate to an Entra user.");
166242
}
167243

168-
ProcessContentRequest pcRequest = new(contentToProcess, resolvedUserId, tenantId);
169-
pcRequests.Add(pcRequest);
244+
for (int entryIndex = 0; entryIndex < mappedContents.Count; entryIndex++)
245+
{
246+
string identifier = entryIndex == 0 ? messageId : $"{messageId}-{entryIndex}";
247+
ProcessConversationMetadata contentEntry = new(mappedContents[entryIndex], identifier, false, $"Agent Framework Message {messageId}", correlationId)
248+
{
249+
SequenceNumber = baseSequenceNumber + entryIndex,
250+
};
251+
ContentToProcess contentToProcess = new(contentEntry, activityMetadata, deviceMetadata, integratedAppMetadata, protectedAppMetadata);
252+
ProcessContentRequest pcRequest = new(contentToProcess, resolvedUserId, tenantId);
253+
pcRequests.Add(pcRequest);
254+
}
170255
}
171256

172257
return pcRequests;
173258
}
174259

260+
/// <summary>
261+
/// Map every content item of a message onto the Purview content type that fits it.
262+
/// </summary>
263+
/// <param name="message">The message whose contents should be evaluated.</param>
264+
/// <returns>One content item per evaluable <see cref="AIContent"/>.</returns>
265+
/// <remarks>
266+
/// <see cref="UsageContent"/> and content with no data are skipped because they carry no user
267+
/// data. Everything else is mapped to a real content item: submitting a message with part of
268+
/// its payload unevaluated is a policy bypass.
269+
/// </remarks>
270+
private static List<ContentBase> MapMessageContents(ChatMessage message)
271+
{
272+
List<ContentBase> mapped = [];
273+
274+
foreach (AIContent content in message.Contents)
275+
{
276+
ContentBase? purviewContent = MapContent(content);
277+
if (purviewContent != null)
278+
{
279+
mapped.Add(purviewContent);
280+
}
281+
}
282+
283+
return mapped;
284+
}
285+
286+
/// <summary>
287+
/// Map a single <see cref="AIContent"/> onto a Purview content item.
288+
/// </summary>
289+
/// <param name="content">The content item to map.</param>
290+
/// <returns>The Purview content item, or <see langword="null"/> when the content carries no user data.</returns>
291+
private static ContentBase? MapContent(AIContent content)
292+
{
293+
switch (content)
294+
{
295+
case UsageContent:
296+
// Telemetry only; there is nothing for DLP to classify.
297+
return null;
298+
299+
case TextContent { Text: null or "" }:
300+
case TextReasoningContent { Text: null or "" }:
301+
case DataContent { Data.IsEmpty: true }:
302+
// Empty data is skipped because the Graph APIs do not support it. A request with
303+
// empty data cannot violate content policies because it contains no content.
304+
return null;
305+
306+
case TextContent textContent:
307+
return new PurviewTextContent(textContent.Text);
308+
309+
case TextReasoningContent reasoningContent:
310+
return new PurviewTextContent(reasoningContent.Text);
311+
312+
case DataContent dataContent:
313+
return new PurviewBinaryContent(dataContent.Data.ToArray());
314+
315+
case UriContent uriContent:
316+
return new PurviewTextContent($"{uriContent.MediaType} {uriContent.Uri}");
317+
318+
case FunctionCallContent functionCallContent:
319+
return new PurviewTextContent(SerializeForEvaluation(functionCallContent));
320+
321+
case FunctionResultContent functionResultContent:
322+
return new PurviewTextContent(SerializeForEvaluation(functionResultContent));
323+
324+
case ErrorContent errorContent:
325+
return new PurviewTextContent(errorContent.Message ?? string.Empty);
326+
327+
default:
328+
// Catch-all for every remaining content type, including ones added after this code
329+
// was written. Serializing is always safe; skipping would be a policy bypass.
330+
return new PurviewTextContent(SerializeForEvaluation(content));
331+
}
332+
}
333+
334+
/// <summary>
335+
/// Render a content item as text so Purview can classify everything it carries.
336+
/// </summary>
337+
/// <param name="content">The content item to render.</param>
338+
/// <returns>The text representation of <paramref name="content"/>.</returns>
339+
/// <exception cref="PurviewRequestException">The content could not be rendered for evaluation.</exception>
340+
/// <remarks>
341+
/// The type info is resolved from the concrete runtime type rather than <see cref="AIContent"/>.
342+
/// Polymorphic serialization through the base type throws for any subclass the abstractions do not
343+
/// declare, which would push third-party and future content types onto the failure path.
344+
/// </remarks>
345+
private static string SerializeForEvaluation(AIContent content)
346+
{
347+
try
348+
{
349+
return JsonSerializer.Serialize(content, AIJsonUtilities.DefaultOptions.GetTypeInfo(content.GetType()));
350+
}
351+
catch (Exception ex) when (ex is NotSupportedException or InvalidOperationException or JsonException)
352+
{
353+
// Fail closed. Falling back to ToString() would submit a bare type name in place of the
354+
// payload, so the content would clear policy without ever having been evaluated.
355+
throw new PurviewRequestException($"Unable to serialize content of type '{content.GetType()}' for Purview policy evaluation. Content cannot be evaluated and will not be released.", ex);
356+
}
357+
}
358+
175359
/// <summary>
176360
/// Orchestrates process content and protection scopes calls.
177361
/// </summary>
@@ -228,12 +412,18 @@ private async Task<ProcessContentResponse> ProcessWithCachedScopesAsync(
228412

229413
if (shouldProcess)
230414
{
231-
pcRequest.ProcessInline = executionMode == ExecutionMode.EvaluateInline;
415+
pcRequest.ProcessInline = executionMode != ExecutionMode.EvaluateOffline;
232416

233417
if (executionMode == ExecutionMode.EvaluateOffline)
234418
{
235419
this._channelHandler.QueueJob(new ProcessContentJob(pcRequest));
236-
return new ProcessContentResponse();
420+
421+
// Offline evaluation is asynchronous, but an explicit block action already known
422+
// from the cached scopes must still be enforced rather than discarded.
423+
List<DlpActionInfo> blockingActions = GetBlockingActions(dlpActions);
424+
return blockingActions.Count > 0
425+
? new ProcessContentResponse { PolicyActions = blockingActions }
426+
: new ProcessContentResponse();
237427
}
238428

239429
return await this.CallProcessContentAsync(pcRequest, cacheKey, dlpActions, cancellationToken).ConfigureAwait(false);
@@ -327,7 +517,8 @@ internal static (bool shouldProcess, List<DlpActionInfo> dlpActions, ExecutionMo
327517

328518
foreach (var location in scope.Locations ?? Array.Empty<PolicyLocation>())
329519
{
330-
if (location.DataType.EndsWith(locationType, StringComparison.OrdinalIgnoreCase) && location.Value.Equals(locationValue, StringComparison.OrdinalIgnoreCase))
520+
if (location.DataType.EndsWith(locationType, StringComparison.OrdinalIgnoreCase)
521+
&& NormalizeLocationValue(locationType, location.Value).Equals(NormalizeLocationValue(locationType, locationValue), StringComparison.Ordinal))
331522
{
332523
locationMatch = true;
333524
break;
@@ -338,7 +529,9 @@ internal static (bool shouldProcess, List<DlpActionInfo> dlpActions, ExecutionMo
338529
{
339530
shouldProcess = true;
340531

341-
if (scope.ExecutionMode == ExecutionMode.EvaluateInline)
532+
// Only an explicitly offline scope may skip inline evaluation. ExecutionMode is an
533+
// evolvable enum, so any unrecognised value is upgraded to inline (fail closed).
534+
if (scope.ExecutionMode != ExecutionMode.EvaluateOffline)
342535
{
343536
executionMode = ExecutionMode.EvaluateInline;
344537
}

‎dotnet/tests/Microsoft.Agents.AI.Purview.UnitTests/PurviewClientTests.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -519,7 +519,7 @@ private static ContentToProcess CreateValidContentToProcess()
519519
};
520520

521521
return new ContentToProcess(
522-
[metadata],
522+
metadata,
523523
activityMetadata,
524524
deviceMetadata,
525525
integratedAppMetadata,

0 commit comments

Comments
 (0)