Version 2.3 以降
Sider Scan の各種設定内容、設定方法について説明いたします。
Sider Scan における設定項目は、.siderscan.json というJSON形式のファイルに記述することで制御可能です。.siderscan.json ファイルは、Sider Scan の解析対象のリポジトリのルートディレクトリに配置します。以下では、各設定項目の内容と、実際にファイルに記載するキーと、取りうる値について説明します。
1. report オブジェクト
- キー名: report
- 値: 複数の子オブジェクト(後述)
report オブジェクトには、Sider Scan の解析結果をどのように通知するかの設定項目を記述します。以下のJSONファイルは、解析結果を指定したメールアドレスに送信するための設定例です。report オブジェクトに、解析結果の送信先のメールアドレスと、メールの送信のためにSider 社が用意したメールサーバーを利用することが記述されています。以下では、report オブジェクトに設定可能な各子オブジェクトについて説明します。
{
"report": {
"mail": {
"to": ["alice@siderlabs.com", "bob@siderlabs.com", "carol@siderlabs.com"],
"useBuiltInProvider": true
}
}
}
1-1. repositoryName オブジェクト
- キー名: repositoryName
- 値: リポジトリの名前(String)
- 既定値: “”(ブランク)
Sider Scan の解析結果のメールのタイトルには、検索性を高めるために、リポジトリの名称を記載することができます。リポジトリの名称は、CIツールによっては環境変数等から取得することが難しい場合もあるため、明示的にリポジトリの名称を指定するために使います。このオブジェクトを使用しない場合、メールのタイトルに記述されるリポジトリ名はブランクになります。
1-2. method オブジェクト
- キー名: method
- 値: mail または file のいずれか
- 既定値: “mail”
Sider Scan の解析結果は、メールで受け取るか(値: mail)、ファイルとして出力するか(値: file)、選択できます。メールの場合は、別途メールの送信設定が必要になります。ファイル出力の場合は、出力された解析結果ファイルをアーティファクトとして保存するなど、CIツール側での設定が必要になります。
1-3. language オブジェクト
- キー名: language
- 値: en または ja のいずれか
- 既定値: “ja”
Sider Scan の解析結果を記述する言語は、日本語(値: ja)か、英語(値: en) を選択できます。
1-4. formats オブジェクト
- キー名: formats
- 値: html または text のいずれか または両方
- 既定値: [“html”, “text”]
Sider Scan の解析結果を記述するフォーマットを指定します
1-5. html オブジェクト
- キー名: html
- 値: includeConfidentiality オブジェクト(後述)
- 既定値: “includeConfidentiality” : true
Sider Scan の解析結果レポートには、確認が必要と思われるコードの前後10行程度を表示させることができます。この機能を使うことによりメールのみで、詳細分析が必要か否か判断できますが、セキュリティポリシーによってはコード断片をメールで送受信できない環境もあります。その際には、こちらのオブジェクトを使用して、メールにコード断片を含めないように設定可能です。このオブジェクトは、formats オブジェクトでhtml を選択している場合にのみ有効です。
1-5-1. includeConfidentiality オブジェクト
- キー名: includeConfidentiality
- 値: true または false のいずれか (boolean)
- 既定値: true
html オブジェクトの子オブジェクトです。解析結果を記述したレポートにコード断片を含めるか否かを設定します。参考までに、解析結果を記述したレポートにコード断片を含めない設定は以下のとおりです。
{
"report": {
"formats" : ["html"],
"html": {
"includeConfidentiality": false
}
}
}
1-6. mail オブジェクト
- キー名: mail
- 値: 複数の子オブジェクト(後述)
- 既定値: “”(ブランク。file 出力をしない場合は、必ず設定下さい)
Sider Scan の解析結果を送信するための、メールの設定を行います。設定可能な項目は、「メールの送信先アドレス」「メールの送信元として表示するアドレス」「メールタイトルに検出結果の概要を記載するか否か」「メールサーバーの設定」です。以下では、mail オブジェクトに記載する各種オブジェクトについて説明します。
1-6-1. to オブジェクト
- キー名: to
- 値: 送信先メールアドレス (string)の配列
- 既定値: “”(ブランク)
Sider Scan の解析結果のメール送信先アドレスを設定します。メールの送信先は、カンマ(,) 区切りで複数設定することができます。例えば以下のようになります。
"to": ["alice@siderlabs.com", "bob@siderlabs.com", "carol@siderlabs.com"]
1-6-2. from オブジェクト
- キー名: from
- 値: メール送信元として表示するメールアドレス (string)
- 既定値: “Sider Scan Report <no-reply@siderlabs.com>”
Sider Scan の解析結果をメールで送る際に、メールの送信元として表示するアドレスを設定します。
1-6-3. subject オブジェクト
- キー名: subject
- 値: showDetectionOutline オブジェクト
- 既定値: “showDetectionOutline”: true
Sider Scan の解析結果をメールで送る際に、 メールタイトルに検出結果の概要を記載する(“showDetectionOutline”: true)か、否か(“showDetectionOutline”: false) を設定します。以下はメールタイトルに検出結果の概要を含めない場合の例です。
{
"report": {
"mail": {
"subject": {
"showDetectionOutline": false
}
}
}
}
1-6-4. useBuiltInProvider オブジェクト
- キー名: useBuiltinProvider
- 値: true または false (boolean)
- 既定値: true
Sider Scan の解析結果をメールで送る際に、Sider 社がSider Scan ユーザーのために用意したメールサーバーを利用するか(true)、否か(false) を設定します。Sider社管理のメールサーバーは、サーバー側で管理可能なメールの経路はすべて暗号化されており、メールの内容をSider社メンバーが閲覧することもできない設定になっていますので、安心してお使い下さい。
1-6-5. provider オブジェクト
- キー名: provider
- 値: 複数の子オブジェクト(type、port、host)
- 既定値: “”(ブランク)
Sider Scan の解析結果をメールで送る際に、ユーザーが固有のメールサーバーを利用するための設定を記述します。provider キーの値として、”type”, “port”, “host” オブジェクトを設定下さい。 type の値は、現在は、SMTPサーバーのみに対応しているため、smpt (String) です。port の値は、ポート番号を記載します(Integer)。host の値は、SMTPサーバーのホスト名を記述します(String)。
以下では、ユーザーが管理しているSMTPサーバー(port 番号2525、ホスト名 smtp.exampleserver.com) を利用するための設定例を示します。
{
"report": {
"mail": {
"to": ["alice@siderlabs.com"],
"provider": {
"type": "smtp",
"port": 2525,
"host": "smtp.exampleserver.com"
}
}
}
}
1-7. File オブジェクト
- キー名: file
- 値: outputDirectory オブジェクト
- 既定値: “outputDirectory”: “scan_result”
Sider Scan の解析結果をメールで通知せず、ファイル形式での出力を選択した場合(method オブジェクトの値がfile) に設定する項目です。outputDirectory オブジェクトで出力先のディレクトリを指定することができます。デフォルトでは、ルートディレクトリにscan_result というディレクトリを作成し、そちらに解析結果のファイルを出力します。
1-8. includeDuplicateCode オブジェクト
- キー名: includeDuplicateCode
- 値: true または false (boolean)
- 既定値: true
Sider Scan の重複コード解析の結果をレポートに含める(値: true)か、含めない(値: false) を選択できます。
1-9. notificationThreshold オブジェクト
- キー名: notificationThreshold
- 値: “high” または “mid” または “low”
- 既定値: “mid”
Sider Scan は、検出された要確認コードを、様々な観点から一つ一つ評価し、総合的に確認すべき「優先度スコア」を算出しています。優先度スコアは高い順にHigh, Mid, Low でランク分けされます。 優先度スコアを閾値として、報告する通知の数を制限することが可能です。取りえる値は、high, mid, low の3種類で、値の意味は、それぞれ
high: 優先度スコアがHigh のもののみ通知
mid: 優先度スコアがMid 以上のものを通知
low: 全ての指摘を通知
となります。以下は、優先度スコアがHigh 以上のもののみ通知するように設定した例です。
{
"report": {
"notificationThreshold": "high",
"mail": {
"to": ["alice@siderlabs.com", "bob@siderlabs.com", "carol@siderlabs.com"],
"useBuiltInProvider": true
}
}
}
2. Scan オブジェクト
- キー名: scan
- 値: 複数の子オブジェクト (history、result)
- 既定値: “”(ブランク)
Sider Scan の解析に関する細かな設定を行うためのオブジェクトです。現在は、過去の解析結果を取得するためのhistory オブジェクトと、解析結果の保存のためのresult オブジェクトを設定可能です。それぞれについて、下記で説明します。
2-1. history オブジェクト
- キー名: history
- 値: filePathオブジェクト
- 既定値: “filePath”: “output.radump”
Sider Scan が解析を行う際に、前回の解析結果を参照します。これにより、前回の解析結果から更新のあったファイルに関する分析のみを行うことができ、解析時間の大幅な短縮が可能です。このオブジェクトでは、前回の解析結果(radump ファイル)が保存されているファイルパスを指定します。通常は、このオブジェクトを改めて設定する必要はありません。
2-2. result オブジェクト
- キー名: result
- 値: 複数の子オブジェクト(outputDirectory、url)
- 既定値: “outputDirectory”: “scan_result”, “url”:””(ブランク)
Sider Scan の解析結果の出力先のパスを明示的に指定します。また、url オブジェクトにより、解析結果の閲覧先URLを設定可能です。以下にscan オブジェクトの設定例を示します。
{
"scan": {
"history": {
"filePath": "results/output.radump"
},
"result": {
"outputDirectory": "results"
}
}
}
3. enableSiderScanTracing オブジェクト
- キー名: enableSiderScanTracing
- 値: 複数の子オブジェクト(onStartup, onComplete, userEmail)
- 既定値: “onStartup”: true, “onComplete”: true, “userEmail”: “”(ブランク)
Sider Scan は、解析時にソースコードやその他のユーザー固有の情報を外部に送信することはありません。しかしながら製品の改善の参考として、利用状況のデータを取得します。具体的には、Sider Scanが解析を開始した際と解析を完了した際に、利用状況のデータをSider 社管理のサーバーに送信します。ユーザーのセキュリティポリシーなどによって、外部サーバーへの情報送信が制限されている場合がございます。その場合、こちらのオブジェクトで、適切な情報の制御をお願いします。以下の例は、解析開始時、完了時、共にデータの送信をしない。また、管理者のE-mail アドレスをbob@siderlabs.com に指定した具体例です。
{
"enableSiderScanTracing": {
"onStartup": false,
"onComplete": false,
"userEmail": "bob@siderlabs.com"
}
}
3-1. onStartupオブジェクト
- キー名: onStartup
- 値: true または false
- 既定値: true
Sider Scan は、解析開始時に、解析が実行された事実をSider 社のサーバーに送信します。これにより、Sider 社は各ユーザーがどのぐらい頻繁にSider Scan を実行しているのかを把握することができます。いわゆる利用率の指標になるため、この指標が改善されるように製品開発を行うことで、ユーザーにとっての価値を還元します。
3-2. onCompleteオブジェクト
- キー名: onComplete
- 値: true または false
- 既定値: true
Sider Scan の解析終了時に、要確認コードや、重要な重複コードに関する指摘がどのぐらいあったか、統計情報をSider 社サーバーに送信します。指摘の数以外のデータは送信しませんので、ご安心下さい。指摘の数に関する統計情報を得ることで、適度な数の指摘がでるように、解析エンジンを調整することが可能になります。ご協力ください。
3-3. userEmailオブジェクト
- キー名: userEmail
- 値: 管理者(代表者)のE-mail アドレス(string)
- 既定値: “”(ブランク)
Sider Scan は、ご利用のユーザーを識別するために、このオブジェクトに記載されたメールアドレスを管理に用います。このメールアドレスは、解析レポートの送付先のメールアドレスとは異なることに注意下さい。特にご指定の無い場合は、IPアドレスや解析対象のリポジトリ名から、一意のユーザー識別ID を自動で生成して、Sider Scan ユーザーの識別に用います。ご了承下さい。
4. exitCode オブジェクト
- キー名: exitCode
- 値: nonZeroIfDetected オブジェクト
- 既定値: “nonZeroIfDetected”: false
Sider Scan の解析の結果、指摘が検出された場合にexitCodeをnon-zeroにするか( “nonZeroIfDetected”: true)、否か( “nonZeroIfDetected”: false) にするかを設定します。例えば、CIツールがJenkins の場合に、要確認コードが検出された場合に、exitCodeを異常としておく(“nonZeroIfDetected”:true) ことで、その後のアクションにつなげることが可能です。