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.