常见问题Frequently asked questions

遇到问题?Got questions? 请查看以下常见问题解答来了解详细信息。Check out the following FAQ for more information.

常见问题解答General FAQ

是否必须对生成运行 Microsoft 安全代码分析?Do I have to run Microsoft Security Code Analysis with my build?

也许。Maybe. 这取决于分析工具的类型。It depends on the type of analysis tool. 源代码可能是唯一必需的东西,生成输出也可能是必需的。The source code might be the only thing that's required, or the build output might be required.

例如,凭据扫描程序 (CredScan) 会分析代码存储库的文件夹结构中的文件。For example, Credential Scanner (CredScan) analyzes files within the folder structure of the code repository. 由于此分析,你可以运行 CredScan 并在独立的生成中发布安全分析日志生成任务来获取结果。Because of this analysis, you can run the CredScan and Publish Security Analysis Logs build tasks in a standalone build to get results.

对于 BinSkim 之类的用来分析生成后项目的其他工具,首先需要的是生成。For other tools like BinSkim that analyze post-build artifacts, the build is required first.

在找到结果时是否可以中断生成?Can I break my build when results are found?

是的。Yes. 当有任何工具在其日志文件中报告了问题时,你都可以引入生成中断。You can introduce a build break when any tool reports an issue or problem in its log file. 只需添加分析后生成任务,并选中要中断生成的任何工具对应的复选框。Just add the Post-Analysis build task, and select the checkbox for any tool for which you want to break the build.

在分析后任务的 UI 中,你可以选择在以下两种情况下中断生成:一是工具仅报告错误,二是工具既报告错误又报告警告。In the UI of the Post-Analysis task, you can choose to break the build when any tool reports either errors only or both errors and warnings.

未创建我指定的输出文件,或者找不到我指定的输出文件The output file I specified isn't being created, or I can’t find the output file I specified

生成任务会筛选某些用户输入。The build tasks filter some user input. 具体对于此问题而言,它们将生成的输出文件的位置更新为生成代理上的一个通用位置。For this question specifically, they update the location of the generated output file to be a common location on the build agent. 有关此位置的详细信息,请参阅以下问题。For more information on this location, see the following questions.

工具生成的输出文件保存在何处?Where are the output files generated by the tools saved?

生成任务会自动将输出路径添加到生成代理上的此已知位置:$(Agent.BuildDirectory)_sdt\logs。The build tasks automatically add output paths to this well-known location on the build agent: $(Agent.BuildDirectory)_sdt\logs. 由于我们对此位置进行了标准化,因此所有生成或使用代码分析日志的团队都可以访问此输出。Because we standardize on this location, all teams that produce or consume code-analysis logs have access to the output.

是否可以对生成进行排队以便在托管的生成代理上运行这些任务?Can I queue a build to run these tasks on a hosted build agent?

是的。Yes. 此扩展中的所有任务和工具都可以在托管的生成代理上执行。All tasks and tools in the extension can be executed on a hosted build agent.

备注

反恶意软件扫描程序生成任务需要启用了 Windows Defender 的生成代理。The Anti-Malware Scanner build task requires a build agent with Windows Defender enabled. 托管的 Visual Studio 2017 和更高版本提供了这样的代理。Hosted Visual Studio 2017 and later provide such an agent. 生成任务不会在 Visual Studio 2015 托管代理上运行。The build task won't run on the Visual Studio 2015 hosted agent.

尽管不能在这些代理上更新特征,但特征的使用期限应始终小于三个小时。Although signatures can't be updated on these agents, signatures should always be less than three hours old.

安装此扩展是否会修改现有 Azure Pipelines?Does installing the extension modify my existing Azure Pipelines?

否。No. 安装此扩展会使安全生成任务可供添加到管道中。Installing the extension makes the security build tasks available for addition to your pipelines. 你仍需要添加或更新生成定义,以便这些工具可用于你的生成过程。You're still required to add or update build definitions, so that the tools can work with your build process.

特定于任务的常见问题解答Task-specific FAQ

本部分列出了特定于生成任务的问题。Questions specific to build tasks are listed in this section.

凭据扫描程序Credential Scanner

常见的抑制方案和示例有哪些?What are common suppression scenarios and examples?

下面是两个最常见的抑制方案的详细信息。Here are details of two of the most common suppression scenarios.

抑制指定路径中给定机密的所有实例To suppress all occurrences of a given secret within the specified path

CredScan 输出文件中机密的哈希键是必需的,如以下示例所示。The hash key of the secret from the CredScan output file is required as shown in the following sample.

    {
        "tool": "Credential Scanner",
        "suppressions": [
        {
            "hash": "CLgYxl2FcQE8XZgha9/UbKLTkJkUh3Vakkxh2CAdhtY=",
            "_justification": "Secret used by MSDN sample, it is fake."
        }
      ]
    }

警告

哈希键由匹配值或文件内容的一部分生成。The hash key is generated by a portion of the matching value or file content. 任何源代码修订都可以更改哈希键并禁用抑制规则。Any source-code revision can change the hash key and disable the suppression rule.

抑制指定文件中的所有机密,或抑制机密文件本身To suppress all secrets in a specified file or to suppress the secrets file itself

文件表达式可以是文件名。The file expression can be a file name. 它还可以是完整文件路径或文件名的基名称部分。It can also be the basename part of a full file path or a file name. 不支持通配符。Wildcards are not supported.

下面的示例展示了如何抑制 <InputPath>\src\JS\lib\angular.js 文件The following examples show how to suppress the file <InputPath>\src\JS\lib\angular.js

有效抑制规则的示例:Examples of valid suppression rules:

  • <InputPath>\src\JS\lib\angular.js - 抑制指定路径中的文件<InputPath>\src\JS\lib\angular.js - suppresses the file in the specified path

  • \src\JS\lib\angular.js\src\JS\lib\angular.js

  • \JS\lib\angular.js\JS\lib\angular.js

  • \lib\angular.js\lib\angular.js

  • angular.js - 抑制具有相同名称的任何文件angular.js - suppresses any file with the same name

      {
          "tool": "Credential Scanner",
          "suppressions": [
          {
              "file": "\\files\\AdditonalSearcher.xml", 
              "_justification": "Additional CredScan searcher specific to my team"
          },
          {
              "file": "\\files\\unittest.pfx", 
              "_justification": "Legitimate UT certificate file with private key"
          }
        ]
      }      
    

警告

将来添加到此文件中的任何机密也将被自动抑制。All future secrets added to the file will also be suppressed automatically.

以下资源可帮助你安全地管理机密以及从应用程序中访问敏感信息:The following resources help you securely manage secrets and access sensitive information from within your applications:

有关详细信息,请参阅博客文章:Managing Secrets Securely in the Cloud(在云中安全地管理机密)。For more information, see the blog post Managing Secrets Securely in the Cloud.

我是否可以编写自己的自定义搜索器?Can I write my own custom searchers?

凭据扫描程序依赖于通常在 buildsearchers.xml 文件中定义的一组内容搜索器。Credential Scanner relies on a set of content searchers that are commonly defined in the buildsearchers.xml file. 该文件包含一个 XML 序列化对象数组,代表 ContentSearcher 对象。The file contains an array of XML serialized objects that represent a ContentSearcher object. 该程序在分发时附带了一组经过充分测试的搜索器。The program is distributed with a set of well-tested searchers. 但你也可以实现自己的自定义搜索器。But you can implement your own custom searchers too.

内容搜索器定义如下:A content searcher is defined as follows:

  • 名称:要在凭据扫描程序输出文件中使用的描述性搜索器名称。Name: The descriptive searcher name to be used in Credential Scanner output files. 建议为搜索器名称使用驼峰式大小写命名约定。We recommended you use the camel-case naming convention for searcher names.

  • RuleId:搜索器的稳定不透明 ID:RuleId: The stable opaque ID of the searcher:

    • 将为凭据扫描程序默认搜索器分配一个 RuleId 值,例如 CSCAN0010、CSCAN0020 或 CSCAN0030。A Credential Scanner default searcher is assigned a RuleId value like CSCAN0010, CSCAN0020, or CSCAN0030. 最后一个数字保留用于可能会通过正则表达式 (regex) 对搜索器组进行的合并或划分。The last digit is reserved for potentially merging or dividing searcher groups via regular expressions (regex).
    • 自定义的搜索器的 RuleId 值应当具有其自己的命名空间。The RuleId value for a customized searcher should have its own namespace. 例如,CSCAN-<Namespace>0010、CSCAN-<Namespace>0020 和 CSCAN-<Namespace>0030。Examples include CSCAN-<Namespace>0010, CSCAN-<Namespace>0020, and CSCAN-<Namespace>0030.
    • 完全限定的搜索器名称是 RuleId 值和搜索器名称的组合。A fully qualified searcher name is the combination of a RuleId value and a searcher name. 例如,CSCAN0010.KeyStoreFiles 和 CSCAN0020.Base64EncodedCertificate。Examples include CSCAN0010.KeyStoreFiles and CSCAN0020.Base64EncodedCertificate.
  • ResourceMatchPattern:用于针对搜索器进行检查的文件扩展名的正则表达式。ResourceMatchPattern: Regex of file extensions to check against the searcher.

  • ContentSearchPatterns:一个字符串数组,其中包含要匹配的正则表达式语句。ContentSearchPatterns: An array of strings containing regex statements to match. 如果未定义搜索模式,则返回与 ResourceMatchPattern 值匹配的所有文件。If no search patterns are defined, all files matching the ResourceMatchPattern value are returned.

  • ContentSearchFilters:一个包含 regex 语句的字符串数组,用于筛选特定于搜索器的误报。ContentSearchFilters: An array of strings containing regex statements to filter searcher-specific false positives.

  • MatchDetails:要为搜索器的每个匹配项添加的描述性消息和/或缓解说明。MatchDetails: A descriptive message, mitigation instructions, or both to be added for each match of the searcher.

  • 建议:针对匹配项的建议字段内容,使用 PREfast 报告格式。Recommendation: The suggestions-field content for a match using the PREfast report format.

  • 严重性:一个整数,反映问题的严重性级别。Severity: An integer that reflects the severity level of an issue. 最高严重性级别的值为 1。The highest severity level has the value 1.

    显示了凭据扫描程序设置的 XML

Roslyn 分析器Roslyn Analyzers

使用 Roslyn 分析器任务时的常见错误有哪些?What are common errors when using the Roslyn Analyzers task?

使用错误的 Microsoft.NETCore.App 版本还原了项目The project was restored using a wrong Microsoft.NETCore.App version

完整错误消息:The full error message:

“错误:该项目是使用 Microsoft.NETCore.App 版本 x.x.x 还原的,但使用当前设置时,将改用版本 y.y.y。"Error: The project was restored using Microsoft.NETCore.App version x.x.x, but with current settings, version y.y.y would be used instead. 若要解决此问题,请确保使用相同的设置执行还原和后续操作,例如生成或发布。To resolve this issue, make sure the same settings are used for restore and for subsequent operations such as build or publish. 通常,如果在生成或发布过程中设置了 RuntimeIdentifier 属性,但在还原过程中未设置此属性,则会出现此问题。”Typically this issue can occur if the RuntimeIdentifier property is set during build or publish but not during restore."

因为 Roslyn 分析器任务作为编译过程的一部分运行,因此生成计算机上的源树需要处于可生成状态。Because Roslyn Analyzers tasks run as part of compilation, the source tree on the build machine needs to be in a buildable state.

介于主生成与 Roslyn 分析器步骤之间的一个步骤可能会将源树置于会阻止生成的状态。A step between your main build and Roslyn Analyzers steps might have put the source tree into a state that prevents building. 这一额外步骤可能是 dotnet.exe 发布This extra step is probably dotnet.exe publish. 在即将执行 Roslyn 分析器步骤之前,请尝试重复将执行 NuGet 还原的步骤。Try duplicating the step that does a NuGet restoration just before the Roslyn Analyzers step. 此重复的步骤可以将源树重新置于可生成状态。This duplicated step might put the source tree back in a buildable state.

csc.exe 无法创建分析器实例csc.exe can't create an analyzer instance

完整错误消息:The full error message:

“'csc.exe' 已退出并显示了错误代码 1 -- 无法通过 C:\BBBB.dll 创建分析器 AAAA 的实例:无法加载文件或程序集 'Microsoft.CodeAnalysis, Version=X.X.X.X, Culture=neutral, PublicKeyToken=31bf3856ad364e35' 或它的某一个依赖项。"'csc.exe' exited with error code 1 -- An instance of analyzer AAAA cannot be created from C:\BBBB.dll : Could not load file or assembly 'Microsoft.CodeAnalysis, Version=X.X.X.X, Culture=neutral, PublicKeyToken=31bf3856ad364e35' or one of its dependencies. 系统找不到指定的文件。”The system cannot find the file specified."

请确保你的编译器支持 Roslyn 分析器。Ensure your compiler supports Roslyn Analyzers. 运行 csc.exe /version 命令应当报告版本值 2.6 或更高值。Running the command csc.exe /version should report a version value of 2.6 or later.

有时,.csproj 文件可通过引用 Microsoft.Net.Compilers 中的包来替代生成计算机的 Visual Studio 安装。Sometimes a .csproj file can override the build machine's Visual Studio installation by referencing a package from Microsoft.Net.Compilers. 如果不打算使用编译器的某个特定版本,请删除对 Microsoft.Net.Compilers 的引用。If you don't intend to use a specific version of the compiler, remove references to Microsoft.Net.Compilers. 否则,请确保所引用的包的版本也是 2.6 或更高。Otherwise, make sure the version of the referenced package is also 2.6 or later.

请尝试获取错误日志路径,该路径在 csc.exe /errorlog 选项中指定。Try to get the error-log path, which is specified in the csc.exe /errorlog option. 此选项和路径显示在 Roslyn 分析器生成任务的日志中。The option and path appear in the log for the Roslyn Analyzers build task. 它们可能类似于 /errorlog:F:\ts-services-123_work\456\s\Some\Project\Code\Code.csproj.sarifThey might look something like /errorlog:F:\ts-services-123_work\456\s\Some\Project\Code\Code.csproj.sarif

C# 编译器版本不够新The C# compiler version isn't recent enough

若要获取最新版本的 C# 编译器,请转到 Microsoft.Net.CompilersTo get the latest versions of the C# compiler, go to Microsoft.Net.Compilers. 若要获取已安装的版本,请在命令提示符下运行 csc.exe /versionTo get your installed version, run csc.exe /version at a command prompt. 确保引用 2.6 版或更高版本的 Microsoft.Net.Compilers NuGet 包。Ensure that you reference a Microsoft.Net.Compilers NuGet package that is version 2.6 or later.

后续步骤Next steps

如果你需要更多帮助,可以在周一到周五的太平洋标准时间上午 9:00 到下午 5:00 联系 Microsoft 安全代码分析支持人员。If you need additional assistance, Microsoft Security Code Analysis Support is available Monday to Friday from 9:00 AM to 5:00 PM Pacific Standard Time.