Customize Add-In Tools

This section lets you customize tools that you previously registered on the Admin page. Software Risk Manager shows your list of registered tools on the left, and you can select a tool to enable/disable it, assign one or more project secrets, or adjust tool behavior by changing any custom TOML configuration data the tool can read.



What you can customize will vary by tool. For example, the default Security Code Scan tool has no project-specific TOML configuration, and it does not read project secrets, but the Enabled/Disabled toggle lets you customize whether its available for your project.

Alternatively, the ZAP tool lets you use project secrets to make authenticated requests during scanning. The interpretation of project secret data is tool dependent - ZAP, for example, will ignore any secrets with missing username or password fields.



The Config box shows any project-specific TOML configuration for the tool you selected. You can see in the above ZAP example how it includes authentication settings and a target field that determines where ZAP begins scanning.

You should avoid using the Default enabled feature available on the Admin page for tools with project-specific TOML configuration unless you have a process for specifying project configuration before a tool runs. Tools with insufficient configuration details typically fail when run.

You must click Save to persist any changes, and you must save any changes you want to keep before selecting another tool.

Customize Checkmarx Add-In Tool

The Software Risk Manager Checkmarx Add-In has the following project-specific configuration.
[checkmarx]
baseUrl = ""
projectId = 0

[scan]
checkScanStatusDelay = 60
Use the Customize Add-In Tools feature to specify values for the above configuration before enabling the tool. Refer to the following table for an explanation of the configuration parameters.
Table 1.
Parameter Description Example
baseUrl the base URL endpoint for the Checkmarx scanner (default="") "https://cxprivatecloud.checkmarx.net"
projectId the Checkmarx-assigned ID of a project created by the Checkmarx software at the base URL (default=0) any integer value greater than 0
checkScanStatusDelay the delay in seconds between requests to fetch scan status (default=60) 60

Note that you may have constant values for both checkScanStatusDelay and baseUrl, so you can use the Admin page to specify values that will not vary by project.

You must also provide an account credential that authorizes use of the Checkmarx software at the base URL. The Checkmarx Add-In Tool expects to find a project secret named checkmarx-project-credential that includes both a username and a password field. The credential must grant permission to start a new scan in the configured Checkmarx project and to generate a Checkmarx report with scan findings.

Customize ZAP Add-In Tool

The ZAP Add-In has the following project-specific configuration.


[context]
target = ""
                    
[scanOptions]
runActiveScan = false
                    
[reportOptions]
minRiskThreshold = 0
minConfThreshold = 0
                    
[authentication]
type = "none"
loginIndicatorRegex = ""
                    
[formAuthentication]
formURL = ""
formUsernameFieldName = ""
formPasswordFieldName = ""
formAntiCrossSiteRequestForgeryFieldName = ""
formExtraPostData = ""
                    
[scriptAuthentication]
authenticationScriptContent = ""

Use the Customize Add-In Tools feature to specify values for the above configuration before enabling the tool. Refer to the following table for an explanation of the configuration parameters.

Table 2.
Parameter Description Example
target the URL where the scan starts (default="") the ZEST script for script authentication (default="")
runActiveScan the decision to run an active scan (default=false) true
minRiskThreshold the minimum risk code for ZAP report findings (default=0) 1
minConfThreshold the minimum confidence for ZAP report findings (default=0) 1
type the authentication type: none, formAuthentication, or scriptAuthentication (default=none) formAuthentication
loginIndicatorRegex the regex to to indicate a successful login request (default="") '\QSet-Cookie: .AspNetCore.Identity.Application=\E'
formURL the URL of the login form for forms authentication (default="") "http://host.docker.internal/contosou/account/login"
formUsernameFieldName the login form's username field name (default="") "Email"
formPasswordFieldName the login form's password field name (default="") "Password"
formAntiCrossSiteRequestForgeryFieldName the anti-XSRF token field name (default="") "__RequestVerificationToken"
formExtraPostData the extra data to include with login request (default="") "RememberMe=false"
authenticationScriptContent the ZEST script for script authentication (default="") See ZAP documentation

When you have ZAP authentication configured, you can provide account credentials by creating project secrets that include both a username and a password field. The ZAP scanner will send authenticated requests using each credential it finds. Be sure to specify the correct username and password with each credential so that ZAP can log on successfully.

Customize Burp Suite Add-In Tool

The Burp Suite Add-In must be specialized before use by adding your licensed, activated copy of Burp Suite to the base Docker image that Software Risk Manager provides. Note that your use of the Burp Suite Add-In Tool must comply with your Burp Suite license agreement. Take the following steps to specialize the Burp Suite Add-In.
  1. Copy your Burp Suite JAR file to a new directory named burp-suite.
  2. Build a Docker image that derives from what's provided by Software Risk Manager.
  3. Activate Burp Suite and save your changes in a new Docker image.
You can accomplish the above steps for Burp Suite Professional by first creating a new burp-suite directory.
C:\>mkdir burp-suite && cd burp-suite
Download your Burp Suite JAR file into the burp-suite directory. In this example, the JAR file is named burpsuite_pro_v2.1.03.jar.
C:\burp-suite>dir
  Directory of C:\burp-suite

09/19/2019  11:12    <DIR>          .
09/19/2019  11:12    <DIR>          ..
08/13/2019  11:28       301,048,274 burpsuite_pro_v2.1.03.jar
Here's a Dockerfile you can use to build a Docker image derived from what Software Risk Manager provides. 
FROM codedx-burpsuiterunnerbase:v1.0
COPY burpsuite_pro_v2.1.03.jar /opt/codedx/burpsuite/bin/burpsuite_pro_v2.1.03.jar
Use the above Dockerfile contents to create a file named "Dockerfile" in the burp-suite directory.
C:\burp-suite>dir
  Directory of C:\burp-suite

09/19/2019  14:00    <DIR>          .
09/19/2019  14:00    <DIR>          ..
08/13/2019  11:28       301,048,274 burpsuite_pro_v2.1.03.jar
09/19/2019  14:00               189 Dockerfile
Create the Docker image by running the following command from the burp-suite directory. 
C:\burp-suite>docker build -t codedx-burpsuiterunner-unactivated:v1.0 .
Sending build context to Docker daemon  301.1MB
Step 1/2 : FROM codedx-burpsuiterunnerbase:v1.0
 ---> 03be80c2bc9f
Step 2/2 : COPY burpsuite_pro_v2.1.03.jar /opt/codedx/burpsuite/bin/burpsuite_pro_v2.1.03.jar
 ---> e3d6aa0106b0
Successfully built e3d6aa0106b0
Successfully tagged codedx-burpsuiterunner-unactivated:v1.0
Next, you must use your new Docker image to start a container where you can run Burp Suite. Follow the instructions to activate your license. Do not shut down the container.
C:\burp-suite>docker run -it --name burpsuite codedx-burpsuiterunner-unactivated:v1.0 sh
$ java -jar burpsuite_pro_v2.1.03.jar

When you have installed and activated your license, run a separate command to create a snapshot with the license activated.C:\burp-suite>docker commit burpsuite codedx-burpsuiterunner-licensed:v1.0

Add your new codedx-burpsuiterunner-licensed Docker image to a private Docker registry that Software Risk Manager can access. Now you can shut down and remove the burpsuite container you created.
C:\burp-suite>docker stop burpsuite -t 0 && docker rm burpsuite
burpsuite
burpsuite

The last step is using the Admin page to edit the Burp Suite TOML config by finding the request.imageName parameter and replacing the codedx-burpsuiterunnerbase:v1.0 value with <private-registry-name>/<repository-name>/codedx-burpsuiterunner-licensed:v1.0, a value based on the above example where you would replace <private-registry-name> and <repository-name> with appropriate values.

The Software Risk Manager Burp Suite Add-In has the following project-specific configuration.
[scan]
name = ""
urls = [""]
includeSimpleScope = []
excludeSimpleScope = []
namedConfigurations = ["Never stop audit due to application errors"]
apiPort = 2727
Use the Customize Add-In Tools feature to specify values for the above configuration before enabling the tool. Refer to the following table for an explanation of the configuration parameters.
Table 3.
Parameter Description Example
name the name associated with your scan (default="") must be the empty string for Burp Suite Professional
urls the URL(s) to scan, use a command to separate multiple URLs (default=empty list) "https://host.docker.internal/contosou"
includeSimpleScope the list of items to include in the scan's scope (default=empty list) "https://host.docker.internal/"
excludeSimpleScope the list of items to exclude from the scan's scope (default=empty list) "https://host.docker.internal/contosou/department"
namedConfigurations the Burp Suite named configurations to use with the scan (default="Never stop audit due to application errors") any configuration name that Burp Suite recognizes
apiPort the port number where the Burp Suite API will be made available (default=2727) any unused, valid port number
Note: You can use the Admin page to specify values for parameters, like apiPort, that will not vary by project.
You must also provide an API key and a hashed API key value that authorizes use of Burp Suite's REST API. The Burp Suite Add-In Tool expects to find a project secret named burp-suite-api-key that includes both a key and a hashed-key field. You can create an API key and its related hashed key value by using the Burp Suite application (see API Keys under User Options, Misc, REST API). Create an API key and then save your user options to a file (Burp menu, User options, Save user options) so that you can find the "hashed_key" value for the key you created. Here's an example of a hashed_key for the API key named 'key': 

{
    "user_options":{
        "misc":{
           "api":{
                "address":"",
                "enabled":true,
                "insecure_mode":false,
                "keys":[
                   {
                      "created":1564773138343,
                      "enabled":true,
-->                   "hashed_key":"F/mmTIwXcY/YkZm4SYyyFgglu82zBDeesm8LD7IQNtM=",
                      "name":"key"
                   }
                ],
                "listen_mode":"loopback_only",
                "port":2727
            }
        }
    }
}