CA2311：未先設定 NetDataContractSerializer.Binder 之前，請勿還原序列化

發行項
02/15/2024

屬性	值
規則識別碼	CA2311
職稱	未先設定 NetDataContractSerializer.Binder 之前，請勿還原序列化
類別	安全性
修正程式是中斷或非中斷	不中斷
預設在 .NET 9 中啟用	No

原因

System.Runtime.Serialization.NetDataContractSerializer已呼叫或參考還原串行化方法，Binder但未設定屬性。

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

警告

使用 SerializationBinder 限制類型無法防止所有攻擊。如需詳細資訊，請參閱 BinaryFormatter 安全性指南。

檔案描述

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

當未Binder設定還原串行化方法時NetDataContractSerializer，此規則會System.Runtime.Serialization.NetDataContractSerializer尋找還原串行化方法呼叫或參考。如果您想要不允許不論 Binder 屬性為何，都不允許任何還原串行化NetDataContractSerializer，請停用此規則和 CA2312，並啟用規則 CA2310。

如何修正違規

請改用安全的串行化程式，而且 不允許攻擊者指定要還原串行化的任意類型。如需詳細資訊，請參閱慣用的替代方案。
讓串行化的數據防竄改。串行化之後，以密碼編譯方式簽署串行化的數據。還原串行化之前，請先驗證密碼編譯簽章。保護密碼編譯金鑰，避免洩漏金鑰，並設計金鑰輪替。
此選項可讓程式代碼容易受到阻斷服務攻擊，以及未來可能的遠端程式代碼執行攻擊。如需詳細資訊，請參閱 BinaryFormatter 安全性指南。限制還原串行化類型。實作自訂 System.Runtime.Serialization.SerializationBinder。還原串行化之前，請將 Binder 屬性設定為所有程式代碼路徑中自定義 SerializationBinder 的實例。在覆寫 BindToType 的方法中，如果類型非預期，則擲回例外狀況以停止還原串行化。

隱藏警告的時機

NetDataContractSerializer 不安全且無法確保安全。

設定程式代碼以分析

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

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

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

排除特定符號

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

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

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

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

範例：

選項值	摘要
`dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType`	符合所有名為 `MyType`的符號。
`dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1\|MyType2`	比對名為 `MyType1` 或 `MyType2`的所有符號。
`dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType)`	比對特定方法 `MyMethod` 與指定的完整簽章。
`dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)\|M:NS2.MyType2.MyMethod2(ParamType)`	比對特定方法和`MyMethod1MyMethod2`個別的完整簽章。

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

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

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

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

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

範例：

選項值	摘要
`dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType`	比對所有具名 `MyType` 的類型及其所有衍生型別。
`dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1\|MyType2`	比對所有名為 `MyType1` 或 `MyType2` 的型別，以及其所有衍生型別。
`dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType`	比對具有指定完整名稱的特定型 `MyType` 別及其所有衍生型別。
`dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1\|M:NS2.MyType2`	比對特定類型和`MyType1MyType2`個別的完整名稱，以及其所有衍生型別。

虛擬程式代碼範例

違規

using System;
using System.IO;
using System.Runtime.Serialization;

[DataContract]
public class BookRecord
{
    [DataMember]
    public string Title { get; set; }

    [DataMember]
    public AisleLocation Location { get; set; }
}

[DataContract]
public class AisleLocation
{
    [DataMember]
    public char Aisle { get; set; }

    [DataMember]
    public byte Shelf { get; set; }
}

public class ExampleClass
{
    public BookRecord DeserializeBookRecord(byte[] bytes)
    {
        NetDataContractSerializer serializer = new NetDataContractSerializer();
        using (MemoryStream ms = new MemoryStream(bytes))
        {
            return (BookRecord) serializer.Deserialize(ms);    // CA2311 violation
        }
    }
}

Imports System
Imports System.IO
Imports System.Runtime.Serialization

<DataContract()>
Public Class BookRecord
    <DataMember()>
    Public Property Title As String

    <DataMember()>
    Public Property Location As AisleLocation
End Class

<DataContract()>
Public Class AisleLocation
    <DataMember()>
    Public Property Aisle As Char

    <DataMember()>
    Public Property Shelf As Byte
End Class

Public Class ExampleClass
    Public Function DeserializeBookRecord(bytes As Byte()) As BookRecord
        Dim serializer As NetDataContractSerializer = New NetDataContractSerializer()
        Using ms As MemoryStream = New MemoryStream(bytes)
            Return CType(serializer.Deserialize(ms), BookRecord)    ' CA2311 violation
        End Using
    End Function
End Class

解決方案

using System;
using System.IO;
using System.Runtime.Serialization;

public class BookRecordSerializationBinder : SerializationBinder
{
    public override Type BindToType(string assemblyName, string typeName)
    {
        // One way to discover expected types is through testing deserialization
        // of **valid** data and logging the types used.

        ////Console.WriteLine($"BindToType('{assemblyName}', '{typeName}')");

        if (typeName == "BookRecord")
        {
            return typeof(BookRecord);
        }
        else if (typeName == "AisleLocation")
        {
            return typeof(AisleLocation);
        }
        else
        {
            throw new ArgumentException("Unexpected type", nameof(typeName));
        }
    }
}

[DataContract]
public class BookRecord
{
    [DataMember]
    public string Title { get; set; }

    [DataMember]
    public AisleLocation Location { get; set; }
}

[DataContract]
public class AisleLocation
{
    [DataMember]
    public char Aisle { get; set; }

    [DataMember]
    public byte Shelf { get; set; }
}

public class ExampleClass
{
    public BookRecord DeserializeBookRecord(byte[] bytes)
    {
        NetDataContractSerializer serializer = new NetDataContractSerializer();
        serializer.Binder = new BookRecordSerializationBinder();
        using (MemoryStream ms = new MemoryStream(bytes))
        {
            return (BookRecord) serializer.Deserialize(ms);
        }
    }
}

Imports System
Imports System.IO
Imports System.Runtime.Serialization

Public Class BookRecordSerializationBinder
    Inherits SerializationBinder

    Public Overrides Function BindToType(assemblyName As String, typeName As String) As Type
        ' One way to discover expected types is through testing deserialization
        ' of **valid** data and logging the types used.

        'Console.WriteLine($"BindToType('{assemblyName}', '{typeName}')")

        If typeName = "BinaryFormatterVB.BookRecord" Then
            Return GetType(BookRecord)
        Else If typeName = "BinaryFormatterVB.AisleLocation" Then
            Return GetType(AisleLocation)
        Else
            Throw New ArgumentException("Unexpected type", NameOf(typeName))
        End If
    End Function
End Class

<DataContract()>
Public Class BookRecord
    <DataMember()>
    Public Property Title As String

    <DataMember()>
    Public Property Location As AisleLocation
End Class

<DataContract()>
Public Class AisleLocation
    <DataMember()>
    Public Property Aisle As Char

    <DataMember()>
    Public Property Shelf As Byte
End Class

Public Class ExampleClass
    Public Function DeserializeBookRecord(bytes As Byte()) As BookRecord
        Dim serializer As NetDataContractSerializer = New NetDataContractSerializer()
        serializer.Binder = New BookRecordSerializationBinder()
        Using ms As MemoryStream = New MemoryStream(bytes)
            Return CType(serializer.Deserialize(ms), BookRecord)
        End Using
    End Function
End Class

CA2310：請勿使用不安全的還原序列化程式 NetDataContractSerializer

CA2312：還原序列化之前，請務必先設定 NetDataContractSerializer.Binder

共用方式為

CA2311：未先設定 NetDataContractSerializer.Binder 之前，請勿還原序列化

原因

檔案描述

如何修正違規

隱藏警告的時機

設定程式代碼以分析

排除特定符號

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

虛擬程式代碼範例

違規

解決方案

其他資源

共用方式為

CA2311：未先設定 NetDataContractSerializer.Binder 之前，請勿還原序列化

原因

檔案描述

如何修正違規

隱藏警告的時機

設定程式代碼以分析

排除特定符號

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

虛擬程式代碼範例

違規

解決方案

相關規則

其他資源