New JsonPatch documentation page for System.Text.Json-based JsonPatch implementation

[mkArtakMSFT]

As I'm wrapping up work on dotnet/aspnetcore#24333, I've just went through a threat-model review for the new implementation, where some security-threats were discussed, which actually apply to both existing and the new JsonPatch implementations.

This issue tracks two asks:

1. Create a new documentation page for JsonPatch, that is based on System.Text.Json serialization (this is my new work, that I'm trying to get merged in preview 4).
2. Add security-focused content to both existing and new pages to educate customers about the risks so that they can take necessary measures to protect their apps as necessary.

System.Text.Json-serialization based JsonPatch

The design document for the new implementation can be found here: https://gist.github.com/mkArtakMSFT/346cf9d5c6eeb73406185751e28bd8fa.

But if I would try to summarize the differences below:

1. The new serializer doesn't use Newtonsoft.Json. It uses System.Text.Json serialization instead
2. The new implementation doesn't support dynamic types (like ExpandoObject).
3. The new implementation will ship as a new package - Microsoft.AspNetCore.JsonPatch.SystemTextJson

Security-focused content

When using the .JsonPatch[.SystemTextJson] package, it is critical to understand and mitigate potential security risks. Below are the identified threats along with their corresponding mitigations to ensure secure usage of the package.

Denial of Service (DoS) via Memory Amplification

• Scenario: A malicious client submits a copy operation that duplicates large object graphs multiple times, leading to excessive memory consumption.
• Impact: Potential Out-Of-Memory (OOM) conditions, causing service disruptions.
• Mitigation:
  • Validate incoming JSON Patch documents for size and structure before applying the document before calling ApplyTo method.
  • The validation will need to be application specific, of course, but an example validation can look something like the following:

public void Action(JsonPatchDocument<T> patch){
    if (patch.Operations.Where(op=>op.OperationType == OperationType.Copy).Count() > MaxCopyOperationsCount)
    {
        throw new InvalidOperationException(); // this is just an example, and it's up to the developer to make sure that this case is handled properly, based on the application needs.
    }
}

Business Logic Subversion

• Scenario: Patch operations manipulate fields with implicit invariants (e.g., internal flags, IDs, or computed fields), violating business constraints.
• Impact: Data integrity issues and unintended application behavior.
• Mitigation:
  • Use POCO objects with explicitly defined properties that are safe to modify.
  • Avoid exposing sensitive or security-critical properties in the target object.
  • If no POCO object is used, validate the patched object after applying operations to ensure business rules and invariants are not violated.

Important

One difference in behavior in with the System.Text.Json-serializer is that JsonPatch library relies on the runtime type information during patching. This means, that when applying a patch to (for example) a list of Employee objects, and there are items which are of type derieved from the Employee type, a patch request can target these specific type properties and modify them as needed.

Authentication and Authorization

• Scenario: Unauthenticated or unauthorized clients send malicious JSON Patch requests.
• Impact: Unauthorized access to modify sensitive data or disrupt application behavior.
• Mitigation:
  • Protect endpoints accepting JSON Patch requests with proper authentication and authorization mechanisms.
  • Restrict access to trusted clients or users with appropriate permissions.

---

Important

This is not an exhaustive list of threats. Application developers must conduct their own threat model reviews to determine an application-specific comprehensive list and come up with appropriate mitigations as needed. For example, applications which expose collections to patch operations should consider the potential for algorithmic complexity attacks if those operations insert or remove elements at the beginning of the collection.

---

By running comprehensive threat models for their own applications and addressing identified threats while following the recommended mitigations above, consumers of these packages can safely integrate JSON Patch functionality into their applications while minimizing security risks.

---

Document Details

⚠ Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.

• ID: 593f528c-61b9-7021-335d-c1c0ec1814d1
• Version Independent ID: 6a88d237-1a03-b865-e3c5-20ceedef2a1f
• Platform ID: 54f6475a-b72c-2ccc-3ab8-5326d9d05c50
• Content: JsonPatch in ASP.NET Core web API
• Content Source: aspnetcore/web-api/jsonpatch.md
• Service: aspnet-core
• Sub-service: web-api
• GitHub Login: @Rick-Anderson
• Microsoft Alias: riande

---

Associated WorkItem - 439108

[mkArtakMSFT]

@Rick-Anderson the content here is now finalized, as I've incorporated the final touches made to the threat-model.