Getting started with Credential Scanner (CredScan)

Credential Scanner (aka CredScan) is a tool developed and maintained by Microsoft to identify credential leaks such as those in source code and configuration files. Some of the commonly found types of credentials are default passwords, SQL connection strings and Certificates with private keys.

The CredScan build task is included in the Microsoft Security Code Analysis Extension. This page has the steps needed to configure & run the build task as part of your build definition.

Prerequisites:

1. You are using the Azure DevOps Build system.
2. The Microsoft Security Code Analysis Extension installed in your account.

Setup:

1. Open your team project from your Azure DevOps Account.
2. Navigate to the Build tab under Build and Release
3. Select the Build Definition into which you wish to add the CredScan build task.
  • New - Click New and follow the steps detailed to create a new Build Definition.
  • Edit - Select the Build Definition. On the subsequent page, click Edit to begin editing the Build Definition.
4. Click + to navigate to the Add Tasks pane.
5. Find the CredScan build task either from the list or using the search box and then click Add.

6. The Run CredScan build task should now be a part of the Build Definition.

Customizing the CredScan Build Task:

1. Click the task Run CredScan to see the different options available within.

2. Available options include
  • Output Format – TSV/ CSV/ SARIF/ PREfast
  • Tool Version (Recommended: Latest)
  • Scan Folder – The folder in your repository to scan
  • Searchers File Type - Options to locate the searchers file used for scanning.
  • Suppressions File – A JSON file can be used for suppressing issues in the output log (more details in the Resources section).
  • (New) Verbose Output - self explanatory
  • Batch Size - The number of concurrent threads used to run Credential Scanners in parallel. Defaults to 20 (Value must be in the range of 1 to 2147483647).
  • (New) Match Timeout - The amount of time to spend attempting a searcher match before abandoning the check.
  • (New) File Scan Read Buffer Size - Buffer size while reading content in bytes. (Defaults to 524288)
  • (New) Maximum File Scan Read Bytes - Maximum number of bytes to read from a given file during content analysis. (Defaults to 104857600)
  • Run this task (under Control Options) - Specifies when the task should run. Choose "Custom conditions" to specify more complex conditions.

    • *Version - Build task version within Azure DevOps. Not frequently used.

Resources

Two of the most common suppression scenarios are detailed below:

1. Suppress all occurrences of a given secret within the specified path

The hash key of the secret from the CredScan output file is required as shown in the sample below

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

Warning: The hash key is generated by a portion of the matching value or file content. Any source code revision could change the hash key and disable the suppression rule.
2. To suppress all secrets in a specified file (or to suppress the secrets file itself)

The file expression could be a file name or any postfix portion of the full file path/name. Wildcards are not supported.

Example
File to be suppressed: [InputPath]\src\JS\lib\angular.js
Valid Suppression Rules:

  • [InputPath]\src\JS\lib\angular.js -- suppress the file in the specified path
  • \src\JS\lib\angular.js
  • \JS\lib\angular.js
  • \lib\angular.js
  • angular.js -- suppress 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" } ] }

Warning: All future secrets added to the file will also get suppressed automatically.

While detecting hard coded secrets in a timely manner and mitigating the risks is helpful, it is even better if one could prevent secrets from getting checked in altogether. In this regard, Microsoft has released CredScan Code Analyzer as part of Microsoft DevLabs extension for Visual Studio. While in early preview, it provides developers an inline experience for detecting potential secrets in their code, giving them the opportunity to fix those issues in real-time. For more information, please refer to this blog on Managing Secrets Securely in the Cloud.
Below are few additional resources to help you manage secrets and access sensitive information from within your applications in a secure manner:

CredScan relies on a set of content searchers commonly defined in the buildsearchers.xml file. The file contains an array of XML serialized objects that represent a ContentSearcher object. The program is distributed with a set of searchers that have been well tested but it does allow you to implement your own custom searchers too.

A content searcher is defined as follows:

  • Name – The descriptive searcher name to be used in CredScan output file. It is recommended to use camel case naming convention for searcher names.
  • RuleId – The stable opaque id of the searcher.
    • CredScan default searchers are assigned with RuleIds like CSCAN0010, CSCAN0020, CSCAN0030, etc. The last digit is reserved for potential searcher regex group merging or division.
    • RuleId for customized searchers should have its own namespace in the format of: CSCAN-{Namespace}0010, CSCAN-{Namespace}0020, CSCAN-{Namespace}0030, etc.
    • The fully qualified searcher name is the combination of the RuleId and the searcher name, e.g. CSCAN0010.KeyStoreFiles, CSCAN0020.Base64EncodedCertificate, etc.
  • ResourceMatchPattern – Regex of file extensions to check against searcher
  • ContentSearchPatterns – Array of strings containing Regex statements to match. If no search patterns are defined, all files matching the resource match pattern will be returned.
  • ContentSearchFilters – Array of strings containing Regex statements to filter searcher specific false positives.
  • Matchdetails – A descriptive message and/or mitigation instructions to be added for each match of the searcher.
  • Recommendation – Provides the suggestions field content for a match using PREfast report format.
  • Severity – An integer to reflect the severity of the issue (Highest = 1).

Microsoft Corporation 2017