CA2327:請勿使用不安全的 JsonSerializerSettings

原因

當 Newtonsoft.Json.JsonSerializerSettings 實例符合下列兩個條件時，就會引發此規則：

• TypeNameHandling 屬性是 以外的None值。
• SerializationBinder 屬性為 null。

JsonSerializerSettings 實例必須以下列其中一種方式使用：

• 初始化為類別欄位或屬性。
• 方法傳回。
• 傳遞至 JsonSerializer.Create 或 JsonSerializer.CreateDefault。
• 傳遞至具有 JsonSerializerSettings 參數的 JsonConvert 方法。

根據預設，此規則會分析整個程式代碼基底，但這是可設定的。

檔案描述

還原序列化未受信任資料時，不安全的還原序列化程式會易受攻擊。 攻擊者可以修改序列化的資料，以包含非預期的型別，以插入具有惡意副作用的物件。 例如，對不安全還原串行化程式的攻擊可能會在基礎操作系統上執行命令、透過網路通訊或刪除檔案。

此規則會尋找設定為從輸入還原串行化型別的 Newtonsoft.Json.JsonSerializerSettings 實例，但未設定為使用 Newtonsoft.Json.Serialization.ISerializationBinder 來限制還原串行化類型。 如果您想要完全禁止從輸入完全還原串行化指定的類型，請停用規則 CA2327、CA2328、CA2329 和 CA2330，並改為啟用規則 CA2326。

如何修正違規

• 可能的話，請使用 TypeNameHandlingNone 的值。
• 讓串行化的數據防竄改。 串行化之後，以密碼編譯方式簽署串行化的數據。 還原串行化之前，請先驗證密碼編譯簽章。 保護密碼編譯金鑰，避免洩漏金鑰，並設計金鑰輪替。
• 限制還原串行化類型。 實作自定義 的 Newtonsoft.Json.Serialization.ISerializationBinder。 使用 Json.NET 還原串行化之前，請確定您已在 Newtonsoft.Json.JsonSerializerSettings.SerializationBinder 屬性中指定自定義 ISerializationBinder。 在覆寫的 Newtonsoft.Json.Serialization.ISerializationBinder.BindToType 方法中，如果類型非預期，則傳回或擲回 null 例外狀況以停止還原串行化。

隱藏警告的時機

如果下列狀況，可以放心地隱藏此規則的警告：

• 您知道輸入是受信任的。 請考慮應用程式的信任界限和數據流可能會隨著時間而變更。
• 您已在如何修正違規中採取其中一項預防措施。

隱藏警告

如果您只想要隱藏單一違規，請將預處理器指示詞新增至原始程式檔以停用，然後重新啟用規則。

#pragma warning disable CA2327
// The code that's violating the rule is on this line.
#pragma warning restore CA2327

若要停用檔案、資料夾或項目的規則，請在組態檔中將其嚴重性設定為 。none

[*.{cs,vb}]
dotnet_diagnostic.CA2327.severity = none

如需詳細資訊，請參閱 如何隱藏程式代碼分析警告。

設定程式代碼以分析

使用下列選項來設定程式代碼基底要執行此規則的部分。

• 排除特定符號
• 排除特定類型及其衍生類型

您可以只針對此規則、它套用的所有規則，或針對套用至此類別的所有規則（安全性）設定這些選項。 如需詳細資訊，請參閱 程式代碼品質規則組態選項。

排除特定符號

您可以從分析中排除特定符號，例如類型和方法。 例如，若要指定規則不應該在名為 MyType的任何程式代碼上執行，請將下列機碼/值組新增至 專案中的 .editorconfig 檔案：

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

選項值中允許的符號名稱格式（以 |分隔）：

• 只包含符號名稱（包含名稱的所有符號，不論包含類型或命名空間為何）。
• 符號 檔案識別碼格式的完整名稱。 每個符號名稱都需要符號種類前置詞，例如 M: 方法、 T: 類型和 N: 命名空間。
• .ctor 用於建構函式和 .cctor 靜態建構函式。

範例：

排除特定類型及其衍生類型

您可以從分析中排除特定類型及其衍生類型。 例如，若要指定規則不應該在具名 MyType 類型及其衍生型別內的任何方法上執行，請將下列機碼/值組新增至 專案中的 .editorconfig 檔案：

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

選項值中允許的符號名稱格式（以 |分隔）：

• 僅限類型名稱（包含名稱的所有類型，不論包含類型或命名空間為何）。
• 符號 文件識別碼格式的完整名稱，具有選擇性 T: 前置詞。

範例：

虛擬程式代碼範例

違規

using Newtonsoft.Json;

public class BookRecord
{
    public string Title { get; set; }
    public object Location { get; set; }
}

public abstract class Location
{
    public string StoreId { get; set; }
}

public class AisleLocation : Location
{
    public char Aisle { get; set; }
    public byte Shelf { get; set; }
}

public class WarehouseLocation : Location
{
    public string Bay { get; set; }
    public byte Shelf { get; set; }
}

public class ExampleClass
{
    public BookRecord DeserializeBookRecord(string s)
    {
        JsonSerializerSettings settings = new JsonSerializerSettings();
        settings.TypeNameHandling = TypeNameHandling.Auto;
        return JsonConvert.DeserializeObject<BookRecord>(s, settings);    // CA2327 violation
    }
}

Imports Newtonsoft.Json

Public Class BookRecord
    Public Property Title As String
    Public Property Location As Location
End Class

Public MustInherit Class Location
    Public Property StoreId As String
End Class

Public Class AisleLocation
    Inherits Location

    Public Property Aisle As Char
    Public Property Shelf As Byte
End Class

Public Class WarehouseLocation
    Inherits Location

    Public Property Bay As String
    Public Property Shelf As Byte
End Class

Public Class ExampleClass
    Public Function DeserializeBookRecord(s As String) As BookRecord
        Dim settings As JsonSerializerSettings = New JsonSerializerSettings()
        settings.TypeNameHandling = TypeNameHandling.Auto
        Return JsonConvert.DeserializeObject(Of BookRecord)(s, settings)    ' CA2327 violation
    End Function
End Class

解決方案

using System;
using Newtonsoft.Json;
using Newtonsoft.Json.Serialization;

public class BookRecordSerializationBinder : ISerializationBinder
{
    // To maintain backwards compatibility with serialized data before using an ISerializationBinder.
    private static readonly DefaultSerializationBinder Binder = new DefaultSerializationBinder();

    public void BindToName(Type serializedType, out string assemblyName, out string typeName)
    {
        Binder.BindToName(serializedType, out assemblyName, out typeName);
    }

    public Type BindToType(string assemblyName, string typeName)
    {
        // If the type isn't expected, then stop deserialization.
        if (typeName != "BookRecord" && typeName != "AisleLocation" && typeName != "WarehouseLocation")
        {
            return null;
        }

        return Binder.BindToType(assemblyName, typeName);
    }
}

public class BookRecord
{
    public string Title { get; set; }
    public object Location { get; set; }
}

public abstract class Location
{
    public string StoreId { get; set; }
}

public class AisleLocation : Location
{
    public char Aisle { get; set; }
    public byte Shelf { get; set; }
}

public class WarehouseLocation : Location
{
    public string Bay { get; set; }
    public byte Shelf { get; set; }
}

public class ExampleClass
{
    public BookRecord DeserializeBookRecord(string s)
    {
        JsonSerializerSettings settings = new JsonSerializerSettings();
        settings.TypeNameHandling = TypeNameHandling.Auto;
        settings.SerializationBinder = new BookRecordSerializationBinder();
        return JsonConvert.DeserializeObject<BookRecord>(s, settings);
    }
}

Imports System
Imports Newtonsoft.Json
Imports Newtonsoft.Json.Serialization

Public Class BookRecordSerializationBinder
    Implements ISerializationBinder

    ' To maintain backwards compatibility with serialized data before using an ISerializationBinder.
    Private Shared ReadOnly Property Binder As New DefaultSerializationBinder()

    Public Sub BindToName(serializedType As Type, ByRef assemblyName As String, ByRef typeName As String) Implements ISerializationBinder.BindToName
        Binder.BindToName(serializedType, assemblyName, typeName)
    End Sub

    Public Function BindToType(assemblyName As String, typeName As String) As Type Implements ISerializationBinder.BindToType
        ' If the type isn't expected, then stop deserialization.
        If typeName <> "BookRecord" AndAlso typeName <> "AisleLocation" AndAlso typeName <> "WarehouseLocation" Then
            Return Nothing
        End If

        Return Binder.BindToType(assemblyName, typeName)
    End Function
End Class

Public Class BookRecord
    Public Property Title As String
    Public Property Location As Location
End Class

Public MustInherit Class Location
    Public Property StoreId As String
End Class

Public Class AisleLocation
    Inherits Location

    Public Property Aisle As Char
    Public Property Shelf As Byte
End Class

Public Class WarehouseLocation
    Inherits Location

    Public Property Bay As String
    Public Property Shelf As Byte
End Class

Public Class ExampleClass
    Public Function DeserializeBookRecord(s As String) As BookRecord
        Dim settings As JsonSerializerSettings = New JsonSerializerSettings()
        settings.TypeNameHandling = TypeNameHandling.Auto
        settings.SerializationBinder = New BookRecordSerializationBinder()
        Return JsonConvert.DeserializeObject(Of BookRecord)(s, settings)
    End Function
End Class

相關規則

CA2326:請勿使用「無」以外的 TypeNameHandling 值

CA2328:確定 JsonSerializerSettings 安全

CA2329:請勿使用不安全的組態來還原序列化 JsonSerializer

CA2330:在還原序列化時，請確認 JsonSerializer 有安全的組態