Share via


YAML configuration options to customize the build tasks

Note

Effective December 31, 2022, the Microsoft Security Code Analysis (MSCA) extension is retired. MSCA is replaced by the Microsoft Security DevOps Azure DevOps extension. Follow the instructions in Configure to install and configure the extension.

This article lists all YAML configuration options available in each of the build tasks. The article starts with the tasks for security code analysis tools. It ends with the post-processing tasks.

Anti-Malware Scanner task

InputType Type Applicable Required Default Value Options (for picklists) Description
InputType pickList always True Basic Basic, Custom
ScanType pickList InputType = Basic True CustomScan CustomScan, FullSystemScan, QuickScan, YourConfiguredScan The scan type to use for the AntiMalware scan.
FileDirPath filePath ScanType = CustomScan True $(Build.StagingDirectory) Indicates the file or directory to be scanned.
DisableRemediation boolean ScanType = CustomScan False true When checked: 1) File exclusions are ignored. 2) Archive files are scanned. 3) Actions are not applied after detection. 4) Event log entries are not written after detection. 5) Detections from the custom scan are not displayed in the user interface. 6) The console output will show the list of detections from the custom scan.
BootSectorScan boolean ScanType = CustomScan False false If checked, it enables boot sector scanning.
Arguments string InputType = Custom True -Scan -ScanType 3 -DisableRemediation -File $(Build.StagingDirectory) The command line arguments, where the argument for -File is an absolute path, or a relative path to the $(Build.StagingDirectory) predefined on your build agent. Note: If you do not provide an argument for -File as the last argument, it defaults to $(Build.StagingDirectory). You can also provide your own arguments allowed by the MpCmdRun.exe tool.

For more details about the command line arguments for this tool, please enter -h or -? in the Arguments field and execute the build task.
EnableServices boolean always True false If checked, it will try enabling the required services for Windows Update in case they are disabled.
NOTE: Please make sure that the group policy does not disable the services and the account this build is running under has admin privileges.
SupportLogOnError boolean always True false If checked, it will collect the support files for diagnosis when an error happened. This may take several minutes.
NOTE: Please make sure that the account this build is running under has admin privileges.
TreatSignatureUpdateFailureAs pickList always True Warning Error, Standard, Warning The log level used if the signature cannot be updated at run-time. When set to Error, a failure to update the signature will fail the build task. Note that it is common for the signature update to fail on hosted build agents, even though the signature may be relatively current (less than 3 hours old).
SignatureFreshness pickList always True UpToDate OneDay, ThreeDays, TwoDays, UpToDate The maximum allowed age for the AntiMalware signature. If the signature cannot be updated and is older than this value, the build task will behave according to the selected value in the Validate Signatures Age As field. Note: If you choose Up-To-Date, the signatures are allowed to be up to 3 hours old.
TreatStaleSignatureAs pickList always True Error Error, Standard, Warning The log level used if the signature age is older than the selected AntiMalware Signature Age. An outdated signature may be treated as a Warning or Informational to continue with the AntiMalware scan, but this is not recommended.

BinSkim task

InputType Type Applicable Required Default Value Options (for picklists) Description
InputType pickList always True Basic Basic, CommandLine
arguments string InputType = CommandLine True Standard BinSkim command line arguments to execute. The output path will be removed and replaced.
For more details about the command line arguments for this tool, please enter help in the Arguments field and execute the build task.
Function pickList InputType = Basic True analyze analyze, dump, exportConfig, exportRules
AnalyzeTarget filePath InputType = Basic && Function = analyze True $(Build.ArtifactStagingDirectory)*.dll;
$(Build.ArtifactStagingDirectory)*.exe
One or more specifiers to a file, directory, or filter pattern that resolves to one or more binaries to analyze. (';' separated list)
AnalyzeSymPath string InputType = Basic && Function = analyze False Path to the symbols file for the target.
AnalyzeConfigPath string InputType = Basic && Function = analyze False default Path to a policy file that will be used to configure analysis. Pass value of 'default' to use built-in settings.
AnalyzePluginPath string InputType = Basic && Function = analyze False Path to a plug-in that will be invoked against all targets in the analysis set.
AnalyzeRecurse boolean InputType = Basic && Function = analyze False true Recurse into subdirectories when evaluating file specifier arguments.
AnalyzeVerbose boolean InputType = Basic && Function = analyze False false Emit verbose output. The resulting comprehensive report is designed to provide appropriate evidence for compliance scenarios.
AnalyzeHashes boolean InputType = Basic && Function = analyze False false Output SHA-256 hash of analysis targets when emitting SARIF reports.
AnalyzeStatistics boolean InputType = Basic && Function = analyze False false Generate timing and other statistics for analysis session.
AnalyzeEnvironment boolean InputType = Basic && Function = analyze False false Log machine environment details of run to output file. WARNING: This option records potentially sensitive information (such as all environment variable values) to any emitted log.
ExportRulesOutputType pickList InputType = Basic && Function = exportRules False SARIF SARIF, SonarQube The type of rules descriptor file to output. This will be included in the BinSkim logs folder published by the Publish Security Analysis Logs build task.
DumpTarget filePath InputType = Basic && Function = dump True $(Build.ArtifactStagingDirectory) One or more specifiers to a file, directory, or filter pattern that resolves to one or more binaries to analyze. (';' separated list)
DumpRecurse boolean InputType = Basic && Function = dump False true Recurse into subdirectories when evaluating file specifier arguments.
DumpVerbose boolean InputType = Basic && Function = dump False true Emit verbose output. The resulting comprehensive report is designed to provide appropriate evidence for compliance scenarios.
toolVersion pickList always False Latest 1.5.0, Latest, LatestPreRelease The version of the tool to run.

Credential Scanner task

InputType Type Applicable Required Default Value Options (for picklists) Description
outputFormat pickList always False pre csv, pre, tsv The output format of the Credential Scanner results file.
toolVersion pickList always False Latest 1.27.7, Latest, LatestPreRelease The version of the tool to run.
scanFolder filePath always False $(Build.SourcesDirectory) The folder in your repository to scan for credentials.
searchersFileType pickList always False Default Custom, Default, DefaultAndCustom Options to locate the searchers file used for scanning.
searchersFile filePath searchersFileType == Custom OR searchersFileType == DefaultAndCustom False The Credential Scanner searchers configuration file of checks to execute. Multiple values can be included and used by providing a comma-separated list of paths to Credential Scanner searchers files.
suppressionsFile filePath always False The Credential Scanner suppressions file to use for suppressing issues in the output log.
suppressAsError boolean always False false Suppressed matches will be output to the output file [-O]-matches.[-f] rather than the default suppressed output file [-O]-suppressed.[-f]. (Defaults to 'False')
verboseOutput boolean always False false Output verbose information.
batchSize string always False The number of concurrent threads used to run Credential Scanners in parallel. (Default to 20)
Value must be within the range of 1-2147483647.
regexMatchTimeoutInSeconds string always False The amount of time in seconds to spend attempting a searcher match before abandoning the check.
Adds -Co RegexMatchTimeoutInSeconds=<Value> to the command line.
fileScanReadBufferSize string always False Buffer size while reading content in bytes. (Defaults to 524288)
Adds -Co FileScanReadBufferSize=<Value> to the command line.
maxFileScanReadBytes string always False Maximum number of bytes to read from a given file during content analysis. (Defaults to 104857600)
Adds -Co MaxFileScanReadBytes=<Value> to the command line.

Roslyn Analyzers task

InputType Type Applicable Required Default Value Options (for picklists) Description
userProvideBuildInfo pickList always True auto auto, msBuildInfo Options for a user to provide the MSBuild version, MSBuild architecture, and build commandline for Roslyn analysis. If Auto is selected, this task will retrieve the build info from the previous MSBuild, VSBuild, and/or .NET Core (for build) tasks in the same pipeline.
msBuildVersion pickList userProvideBuildInfo == msBuildInfo True 16.0 15.0, 16.0 The MSBuild version.
msBuildArchitecture pickList userProvideBuildInfo == msBuildInfo True x86 DotNetCore, x64, x86 The MSBuild architecture. Note: If the build commandline calls dotnet.exe build, choose the Via .NET Core option.
msBuildCommandline string userProvideBuildInfo == msBuildInfo True The complete build commandline for compiling your solution or projects.

Notes: The commandline should begin with a full path to MSBuild.exe or dotnet.exe.
The command will run with $(Build.SourcesDirectory) as the working directory.
rulesetName pickList always False Recommended Custom, None, Recommended, Required A named ruleset to use.

If Ruleset Configured In Your Visual Studio Project File(s) is chosen, the ruleset preconfigured in your VS project file(s) will be used. If Custom is chosen, a custom ruleset path option can be set.
rulesetVersion pickList rulesetName == Required OR rulesetName == Recommended False Latest 8.0, 8.1, 8.2, Latest, LatestPreRelease The version of the chosen SDL ruleset.
customRuleset string rulesetName = Custom False An accessible path to a ruleset to use. Relative paths will be normalized to the root of the source repository ($(Build.SourcesDirectory)).

If the ruleset specifies Rules with Actions set to Error, the build task will fail. To use a ruleset that does this, please check Continue on error in the build task's Control Options.
microsoftAnalyzersVersion pickList always False Latest 2.9.3, 2.9.4, 2.9.6, Latest, LatestPreRelease The version of the Microsoft.CodeAnalysis.FxCopAnalyzers package to run.
suppressionFileForCompilerWarnings filePath always False A suppressions file to suppress C# and VB compiler warnings.

A plain-text file with each warning ID listed one a separate line.
For compiler warnings, specify only the numeric part of the warning identifier. For example 1018 will suppress CS1018, and CA1501 will suppress CA1501.

A relative file path will be appended to the root of the source repository ($(Build.SourcesDirectory)).

TSLint task

InputType Type Applicable Required Default Value Options (for picklists) Description
RuleLibrary pickList always True tslint custom, microsoft, tslint All results include the rules shipped with the selected version of TSLint (Base Only).

Base Only - Only the rules shipped with TSLint.

Include Microsoft Rules - Downloads tslint-microsoft-contrib and includes its rules to be available for use in the TSLint run. Choosing this option hides the Type Checking checkbox, as it is required by Microsoft's rules and will automatically be used. It also unhides the Microsoft Contribution Version field, allowing a version of the tslint-microsoft-contrib from npm to be selected.

Include Custom Rules - Unhides the Rules Directory field, which accepts an accessible path to a directory of TSLint rules to be available for use in the TSLint run.

Note: The default value has changed to tslint, as many users have experienced issues configuring the Microsoft ruleset. For specific version configuration, please see tslint-microsoft-contrib on GitHub.
RulesDirectory string RuleLibrary == custom True An accessible directory containing additional TSLint rules to be available for use in the TSLint run.
Ruleset pickList RuleLibrary != microsoft True tsrecommended custom, tslatest, tsrecommended Defines the rules to run against TypeScript files.

tslint:latest - Extends tslint:recommended and is continuously updated to include configuration for the latest rules in every TSLint release. Using this config may introduce breaking changes across minor releases as new rules are enabled which cause lint failures in your code. When TSLint reaches a major version bump, tslint:recommended will be updated to be identical to tslint:latest.

tslint:recommended - A stable, somewhat opinionated set of rules which TSLint encourages for general TypeScript programming. This configuration follows semver, so it will not have breaking changes across minor or patch releases.
RulesetMicrosoft pickList RuleLibrary == microsoft True mssdlrequired custom, msrecommended, mssdlrecommended, mssdlrequired, tslatest, tsrecommended Defines the rules to run against TypeScript files.

microsoft:sdl-required - Run all of the available checks provided by tslint and the tslint-microsoft-contrib rules that satisfy the required Security Development Lifecycle (SDL) policies.

microsoft:sdl-recommended - Run all of the available checks provided by tslint and the tslint-microsoft-contrib rules that satisfy the required and recommended Security Development Lifecycle (SDL) policies.

microsoft:recommended All checks that are recommended by the creators of the tslint-microsoft-contrib rules. This includes security and non-security checks.

tslint:latest - Extends tslint:recommended and is continuously updated to include configuration for the latest rules in every TSLint release. Using this config may introduce breaking changes across minor releases as a new rules are enabled which cause lint failures in your code. When TSLint reaches a major version bump, tslint:recommended will be updated to be identical to tslint:latest.

tslint:recommended - A stable, somewhat opinionated set of rules which TSLint encourages for general TypeScript programming. This configuration follows semver, so it will not have breaking changes across minor or patch releases.
RulesetFile string Ruleset == custom OR RulesetMicrosoft == custom True A configuration file specifying which rules to run.

The path to the config will be added as the path for custom rules.
FileSelectionType pickList always True fileGlob fileGlob, projectFile
Files string FileSelectionType == fileGlob True ***.ts A file glob that determines which file(s) to process. Paths are relative to the Build.SourcesDirectory value.

Microsoft's Contribution library requires the use of a project file. If you are using Microsoft's Contribution library with the File Glob Pattern option, a project file will be generated for you.
ECMAScriptVersion pickList FileSelectionType == fileGlob && RuleLibrary == microsoft True ES3 ES2015, ES2016, ES2017, ES3, ES5, ES6, ESNext The target version of ECMAScript configured with your TypeScript compiler. When using a project file, this is the compilerOptions.target field of your TypeScript tsconfig.json file.
Project string FileSelectionType == projectFile True Path to a tsconfig.json file that specifies TypeScript files to run TSLint on. Paths are relative to the Build.SourcesDirectory value.
TypeCheck boolean RuleLibrary != microsoft && FileSelectionType == projectFile False true Enables the type checker when running linting rules.
ExcludeFiles string always False A glob which indicates files to exclude from linting. Paths are relative to the Build.SourcesDirectory value. Multiple values can be specified separated by semicolon.
OutputFormat pickList always True json checkstyle, codeFrame, filesList, json, msbuild, pmd, prose, stylish, verbose, vso The formatter to use to generate output. Note that the JSON format is compatible with Post Analysis.
NodeMemory string always False An explicit amount of memory in MBs to allocate to node for running TSLint. Example: 8000

Maps to the --max_old_space=<value> CLI option for node, which is a v8 option.
ToolVersion pickList RuleLibrary != microsoft True latest 4.0.0, 4.0.1, 4.0.2, 4.1.0, 4.1.1, 4.2.0, 4.3.0, 4.3.1, 4.4.0, 4.4.1, 4.4.2, 4.5.0, 4.5.1, 5.0.0, 5.1.0, 5.2.0, 5.3.0, 5.3.2, 5.4.0, 5.4.1, 5.4.2, 5.4.3, 5.5.0, latest The version of TSLint to download and run.
TypeScriptVersion pickList always True latest 0.8.0, 0.8.1, 0.8.2, 0.8.3, 0.9.0, 0.9.1, 0.9.5, 0.9.7, 1.0.0, 1.0.1, 1.3.0, 1.4.1, 1.5.3, 1.6.2, 1.7.3, 1.7.5, 1.8.0, 1.8.10, 1.8.2, 1.8.5, 1.8.6, 1.8.7, 1.8.9, 1.9.0, 2.0.0, 2.0.10, 2.0.2, 2.0.3, 2.0.6, 2.0.7, 2.0.8, 2.0.9, 2.1.1, 2.1.4, 2.1.5, 2.1.6, 2.2.0, 2.2.1, custom, latest The version of TypeScript to download and use.
Note: This needs to be the same version of TypeScript as is used to compile your code.
TypeScriptVersionCustom string TypeScriptVersion == custom True latest The version of TypeScript to download and use.
Note: This needs to be the same version of TypeScript as is used to compile your code.
MicrosoftContribVersion pickList RuleLibrary == microsoft latest 4.0.0, 4.0.1, 5.0.0, 5.0.1, latest The version of tslint-microsoft-contrib (SDL Rules) to download and use.
Note: The version of tslint will be chosen that is compatible with the version chosen for tslint-microsoft-contrib. Updates to tslint-microsoft-contrib will be gated by this build task, until a period of testing can occur.

Publish Security Analysis Logs task

InputType Type Applicable Required Default Value Options (for picklists) Description
ArtifactName string always True CodeAnalysisLogs The name of the artifact to create.
ArtifactType pickList always True Container Container, FilePath The type of the artifact to create.
TargetPath string ArtifactType = FilePath False \my\share$(Build.DefinitionName)
$(Build.BuildNumber)
The file share to which to copy the files
AllTools boolean always True true Publish results generated by all Secure Development Tools build tasks.
AntiMalware boolean AllTools = false True true Publish results generated by AntiMalware build tasks.
BinSkim boolean AllTools = false True true Publish results generated by BinSkim build tasks.
CredScan boolean AllTools = false True true Publish results generated by Credential Scanner build tasks.
RoslynAnalyzers boolean AllTools = false True false Publish results generated by Roslyn Analyzers build tasks.
TSLint boolean AllTools = false True true Publish results generated by TSLint build tasks. Note that only TSLint logs in the JSON format are supported for reports. If you have chosen a different format, please update your TSLint build task accordingly.
ToolLogsNotFoundAction picklist always True Standard Error, None, Standard, Warning The action to take when logs for a selected tool (or any tool if All Tools is checked) are not found, implying the tool was not run.

Options:
None: Message is written to the verbose output stream accessible only by setting the VSTS variable system.debug to true.
Standard: (Default) Writes a standard output message that no logs were found for the tool.
Warning: Writes a yellow warning message that no logs were found for the tool, which shows up on the build summary page as a warning.
Error: Writes a red error message and throws an exception, breaking the build. Use this option to ensure with individual tool choices to ensure which tools ran.

Security Report task

InputType Type Applicable Required Default Value Options (for picklists) Description
VstsConsole boolean always False true Write results to the Pipeline Console.
TsvFile boolean always False true Generate a tsv file (tab separated values) with one line per found result and tabs separating info for the result.
HtmlFile boolean always False true Generate an html report file.
AllTools boolean always True false Report results generated by all Secure Development Tools build tasks.
BinSkim boolean AllTools = false True false Report results generated by BinSkim build tasks.
BinSkimBreakOn pickList AllTools = true OR BinSkim = true True Error Error, WarningAbove The level of results to report.
CredScan boolean AllTools = false True false Report results generated by Credential Scanner build tasks.
RoslynAnalyzers boolean AllTools = false True false Report results generated by Roslyn Analyzer build tasks.
RoslynAnalyzersBreakOn pickList AllTools = true OR RoslynAnalyzers = true True Error Error, WarningAbove The level of results to report.
TSLint boolean AllTools = false True false Report results generated by TSLint build tasks. Note that only TSLint logs in the JSON format are supported for reports. If you have chosen a different format, please update your TSLint build task accordingly.
TSLintBreakOn pickList AllTools = true OR TSLint = true True Error Error, WarningAbove The level of results to report.
ToolLogsNotFoundAction picklist always True Standard Error, None, Standard, Warning The action to take when logs for a selected tool (or any tool if All Tools is checked) are not found, implying the tool was not run.

Options:
None: Message is written to the verbose output stream accessible only by setting the VSTS variable system.debug to true.
Standard: (Default) Writes a standard output message that no logs were found for the tool.
Warning: Writes a yellow warning message that no logs were found for the tool, which shows up on the build summary page as a warning.
Error: Writes a red error message and throws an exception, breaking the build. Use this option to ensure with individual tool choices to ensure which tools ran.
CustomLogsFolder string always False The base folder where analysis tool logs are located; the individual log files will be in subfolders named after each tool, under this path.

Post-Analysis task

InputType Type Applicable Required Default Value Options (for picklists) Description
AllTools boolean always True false Break the build if any issues are found by any Microsoft Security Code Analysis build task.
BinSkim boolean AllTools = false True false Break the build if any BinSkim issues are found, according to the Break On option you selected.
BinSkimBreakOn pickList AllTools = true OR BinSkim = true True Error Error, WarningAbove The level of issues to break the build.
CredScan boolean AllTools = false True false Break the build if any Credential Scanner issues are found.
RoslynAnalyzers boolean AllTools = false True false Break the build if any Roslyn Analyzers issues are found.
RoslynAnalyzersBreakOn pickList AllTools = true OR RoslynAnalyzers = true True Error Error, WarningAbove The level of issues to break the build.
TSLint boolean AllTools = false True false Break the build if any TSLint issues are found. Note that only TSLint logs in the JSON format are supported for post analysis. If you have chosen a different format, please update your TSLint build task accordingly.
TSLintBreakOn pickList AllTools = true OR TSLint = true True Error Error, WarningAbove The level of issues to break the build.
VstsConsole boolean always False true Write results to the Pipeline Console.
ToolLogsNotFoundAction picklist always True Standard Error, None, Standard, Warning The action to take when logs for a selected tool (or any tool if All Tools is checked) are not found, implying the tool was not run.

Options:
None: Message is written to the verbose output stream accessible only by setting the VSTS variable system.debug to true.
Standard: (Default) Writes a standard output message that no logs were found for the tool.
Warning: Writes a yellow warning message that no logs were found for the tool, which shows up on the build summary page as a warning.
Error: Writes a red error message and throws an exception, breaking the build. Use this option to ensure with individual tool choices to ensure which tools ran.

Next steps

If you have further questions about the Security Code Analysis extension and the tools offered, check out our FAQ page.