Option Reference Guide

version 2.3 or later

This page explains the various settings of Sider Scan.

Each configuration item in Sider Scan can be controlled by writing it in a JSON format file, .siderscan.json. The .siderscan.json should be placed in the root directory of the repository to be analyzed by Sider Scan. In the following, we will explain the detail of each setting item, the Key to be described in the file, and the possible values.

1. report object

  • Key: report
  • Value: multiple child objects (details are described later)

In the report object, you can describe the settings for how to notify the analysis result of Sider Scan. The following JSON file is an example of the setting to send the analysis result to the specified email address: in the report object, the email address to send the analysis result to and the mail server prepared by Sider are described. In the following, each child object that can be set to the report object will be explained.

{
  "report": {
    "mail": {
      "to": ["alice@siderlabs.com", "bob@siderlabs.com", "carol@siderlabs.com"],
      "useBuiltInProvider": true
    }
  }
}

1-1. repositoryName object

  • Key: repositoryName
  • Value: Repository Name(String)
  • Default Value: “”(blank)

In the title of the email of the analysis result of Sider Scan, you can add the name of the repository to improve the searchability. This object is used to specify the repository name explicitly, since it may be difficult to get it from environment variables of CI tool. If you do not use this object, the repository name in the mail title will be blank.

1-2. method object

  • Key: method
  • Value: “mail” or “file”
  • Default Value: “mail”

You can choose to receive the analysis result of Sider Scan by e-mail (value: mail) or output it as a file (value: file). In the case of “mail”, you may need to configure the mail sending settings. In the case of “file” , the CI tool may need to be configured to save the analysis result file as an artifact.

1-3. language object

  • Key: language
  • Value: “en” or “ja”
  • Default Value: “ja”

You can select either Japanese (value: ja) or English (value: en) as the language to describe the analysis results of Sider Scan.

1-4. formats object

  • Key: formats
  • Value: “html” or “text” or both
  • Default Value: [“html”, “text”]

Specify the format to describe the analysis result of Sider Scan.

1-5. html object

  • Key: html
  • Value: includeConfidentiality object(details are described later)
  • Default Value: “includeConfidentiality” : true

The analysis result report of Sider Scan can display about 10 lines before and after the code having a problem. By using this function, you can easily confirm whether it is an actual issue or not only by e-mail, but code snippet may not be sent or received by e-mail depending on your security policy. This object can be used to prevent code fragments from being included in e-mails. This object is available only when “html” is selected in the formats object.

1-5-1. includeConfidentiality object

  • Key: includeConfidentiality
  • Value: true or false (boolean)
  • Default Value: true

This is a child object of the html object. Set whether or not to include the code fragments in the report describing the analysis results. For your reference, the settings to NOT include the code snippet in the report describing the analysis result are as follows.

{
  "report": {
    "formats" : ["html"],
    "html": {
      "includeConfidentiality": false
    }
  }
}

1-6. mail object

  • Key: mail
  • Value: multiple child objects (details are described later)
  • Default Value: “”(blank. If you don’t use “file” output, be sure to set this option.)

Configure the mail settings to send the analysis result of Sider Scan. The items that can be set are:

  • Destination address of mail
  • Address to be displayed as the source of mail
  • Whether or not to describe the summary of detection result in the mail title
  • Mail server setting

The following sections describe the various objects to be described in the mail object.

1-6-1. to object

  • Key: to
  • Value: the mail address(es) to send the analysis result of Sider Scan (Array of string)
  • Default Value: “”(blank)

Set the mail address to send the analysis result of Sider Scan. You can set multiple mail addresses separated by comma (,). Here is the example:

"to": ["alice@siderlabs.com", "bob@siderlabs.com", "carol@siderlabs.com"]

1-6-2. from object

  • Key: from
  • Value: Sender’s mail address (string)
  • Default Value: “Sider Scan Report <no-reply@siderlabs.com>”

Set the address to be displayed as the sender of the email when sending the analysis result of Sider Scan by email.

1-6-3. subject object

  • Key: subject
  • Value: showDetectionOutline object
  • Default Value: “showDetectionOutline”: true

When sending the analysis result of Sider Scan by e-mail, you can set whether to include the summary of the detection result in the e-mail title (“showDetectionOutline”: true) or not (“showDetectionOutline”: false). The following is an example of NOT including the detection result summary in the mail title.

{
  "report": {
    "mail": {
      "subject": {
         "showDetectionOutline": false
      }
    }
  }
}

1-6-4. useBuiltInProvider object

  • Key: useBuiltinProvider
  • Value: true or false (boolean)
  • Default Value: true

When sending Sider Scan analysis results by e-mail, you can set whether to use the mail server managed by Sider Corporation (true) or not (false). For the mail server managed by Sider, all mail routes are encrypted and the contents of the mail cannot be read even by Sider members. Please feel free to use it.

1-6-5. provider object

  • Key: provider
  • Value: multiple child objects(type, port, host)
  • Default Value: “”(blank)

This object is used to describe the settings for using a user’s own mail server when sending the Sider Scan analysis results by e-mail. The value of “type” is currently smtp (String) only. The value of “port” is the port number (Integer). The value of “host” is the host name of the SMTP server (String).

The following is an example of the configuration for using a user-managed SMTP server (port number is 2525, host name is smtp.exampleserver.com).

{
  "report": {
    "mail": {
      "to": ["alice@siderlabs.com"],
      "provider": {
        "type": "smtp",
        "port": 2525,
        "host": "smtp.exampleserver.com"
      }
    }
  }
}

1-7. File object

  • Key: file
  • Value: outputDirectory object
  • Default Value: “outputDirectory”: “scan_result”

The output directory can be specified with the outputDirectory object if you do not want to be notified of the analysis results by e-mail and you choose to output them in file format. By default, a directory named scan_result will be created in the root directory, and the analysis result files will be output there.

1-8. includeDuplicateCode object

  • Key: includeDuplicateCode
  • Value: true or false (boolean)
  • Default Value: true

You can select the results of duplicate codes should be included (value: true) or not (value: false) in the reports.

1-9. notificationThreshold object

  • Key: notificationThreshold
  • Value: “high” or “mid” or “low”
  • Default: “mid”

It is possible to reduce the number of notifications, using the priority score as a threshold. The meaning of the values are:

high: Notify the code with a High priority score only
mid: Notify the code with Mid and High priority score
low: Notify all

The following JSON code is an example of setting up notification only for a high priority score.

{
  "report": {
    "notificationThreshold": "high",
    "mail": {
      "to": ["alice@siderlabs.com", "bob@siderlabs.com", "carol@siderlabs.com"],
      "useBuiltInProvider": true
    }
  }
}

2. Scan object

  • Key: scan
  • Value: Multiple child objects (history, result)
  • Default Value: “”(blank)

This object is used to configure detailed settings for analysis. Currently, the history object to get the past analysis results and the result object to save the analysis results can be configurable.

2-1. history object

  • Key: history
  • Value: filePath object
  • Default Value: “filePath”: “output.radump”

When Sider Scan performs an analysis, it refers to the previous analysis results. This allows Sider Scan to perform analysis only on files that have been updated since the last analysis result, which can significantly reduce the analysis time. This object specifies the file path where the previous analysis result (radump file) is saved. Normally, you don’t need to change this object.

2-2. result object

  • Key: result
  • Value: Multiple child objects(outputDirectory, url)
  • Default Value: “outputDirectory”: “scan_result”, “url”: “”(blank)

Explicitly specify the output path of the Sider Scan analysis results. The url object can also be used to set the URL to view the analysis results. An example of the scan object configuration is shown below.

{
  "scan": {
    "history": {
      "filePath": "results/output.radump"
    },
    "result": {
      "outputDirectory": "results"
    }
  }
}

3. enableSiderScanTracing object

  • Key: enableSiderScanTracing
  • Value: Multiple child objects(onStartup, onComplete, userEmail)
  • Default Value: “onStartup”: true, “onComplete”: true, “userEmail”: “”(blank)

Sider Scan does not transmit source code or other user-specific information to the outside world during analysis. However, it does collect usage data to help improve the product. Specifically, Sider Scan will send usage data to Sider’s servers when it starts and completes the analysis. Depending on the user’s security policy, sending information to an external server may be restricted. In that case, please use this object to control the information. The following example does not send any data both at the start and completion of the analysis.

{
  "enableSiderScanTracing": {
    "onStartup": false,
    "onComplete": false,
    "userEmail": "bob@siderlabs.com"
  }
}

3-1. onStartup object

  • Key: onStartup
  • Value: true or false
  • Default Value: true

At the start of the analysis, Sider Scan sends the fact that the analysis has been performed to the Sider server. This allows Sider to understand how often each user is running Sider Scan. We keep improving our products in such a way that this metric will improve, thus returning value to our users.

3-2. onComplete object

  • Key: onComplete
  • Value: true or false
  • Default Value: true

At the end of analysis, Sider Scan will send statistics to Sider’s server on how many codes were detected that need to be checked and how many important duplicate codes were found. Please be assured that no data other than the number of suggestions will be sent. By getting the statistics on the number of suggestions, we will be able to adjust the analysis engine to get the right number of suggestions. Thank you for your cooperation.

3-3. userEmail object

  • Key: userEmail
  • Value: Repository Manager’s E-mail address (string)
  • Default Value: “”(blank)

Sider Scan will use the email address listed in this object to identify each user. Please note that this email address is different from the email address to which the analysis report is sent. If you do not specify this, Sider Scan will automatically generate a unique user identification ID from the IP address and the repository name to be analyzed.

4. exitCode object

  • Key: exitCode
  • Value: nonZeroIfDetected object
  • Default Value: “nonZeroIfDetected”: false

Set whether to set exitCode to non-zero (“nonZeroIfDetected”: true) or not (“nonZeroIfDetected”: false) when the result of Sider Scan analysis shows that the code needs to be checked. For example, if your CI tool is Jenkins, you can set the exitCode to be abnormal (“non-ZeroIfDetected”:true) when a code that needs to be verified is detected, so that you can trigger further actions.