ルールセットをカスタマイズする

各SASTアナライザーは、ルールセット設定ファイルを通じて異なるレベルのカスタマイズをサポートしています。SemgrepベースのSASTアナライザーと高度なSASTアナライザーには、デフォルトのルールセットがあります。

ルールセット用語集

ルール: 特定の脆弱性をスキャンする個別のセキュリティチェックまたは検出パターン。

ルールセット: sast-ruleset.tomlファイルで定義されている、ルールとその設定のコレクション。

パススルー: パススルーとは、ファイル、Gitリポジトリ、URL、またはインライン設定からルールセットのカスタマイズを取得する設定ソースです。複数のパススルーをチェーンに結合でき、それぞれが以前の設定を上書きするか追加できます。

ルールのカスタマイズオプション

SASTルールセットにはデフォルトのルールが含まれていますが、組織ごとにセキュリティ要件が異なります。ルールを無効にしたり、そのメタデータをオーバーライドしたり、ルールを置き換えたり追加したりすることで、これらのルールセットをカスタマイズできます。

下の表は、各アナライザータイプで利用できるカスタマイズオプションを示しています。

デフォルトルールを無効にする

任意のSASTアナライザーのデフォルトルールを無効にできます。たとえば、組織のポリシーに基づいて特定のルールを除外することがあります。

以下の例を参照してください:

• デフォルトの高度なSASTルールを無効にする
• その他のSASTアナライザーのデフォルトルールを無効にする

デフォルトルールのメタデータをオーバーライドする

任意のSASTアナライザーのデフォルトルールの特定の属性をオーバーライドできます。たとえば、組織のポリシーに基づいて脆弱性の重大度をオーバーライドしたり、脆弱性レポートに表示するメッセージを変更したりできます。

例については、デフォルトのルールメタデータをオーバーライドするを参照してください。

デフォルトルールを置き換えるか追加する

SemgrepベースのSASTアナライザーと高度なSASTアナライザーのデフォルトルールを置き換えたり追加したりできます。デフォルトでは、カスタムルールセットを定義すると、デフォルトのルールセットが置き換えられます。デフォルトルールセットに追加するには、ルールセット設定ファイルでkeepdefaultrulesをtrueに設定する必要があります。

以下の例を参照してください:

• 高度なSASTのデフォルトルールを置き換える
• semgrepのデフォルトルールを置き換えるか追加する

ルールセットカスタマイズの影響

以下の表は、SASTルールセットをカスタマイズしたときに発生することを示しています:

設定方法

ルールセットのカスタマイズは、以下の方法で提供できます:

ローカルルールセットファイル: カスタマイズをsast-ruleset.tomlファイルで定義し、リポジトリにコミットします。このアプローチにより、ルールセット設定はバージョン管理下でソースコードとともに管理されます。

リモートルールセットファイル: ルールセットファイルがホストされているリモートの場所（Gitリポジトリ、URL、またはその他のソース）を指定します。このアプローチにより、ルールセットを一元的に管理し、複数のプロジェクトで再利用できます。

パススルー（ルールセットに結合できる設定ソース）を使用してカスタマイズを提供します。

すべてのルールセットのカスタマイズは、SASTルールセットスキーマに準拠する必要があります。

ローカルルールセットファイルを使用する

カスタマイズをソースコードと一緒に保存したい場合は、ローカルルールセットファイルを使用します。ローカルのカスタマイズは個別のプロジェクトにのみ適用されます。

前提条件:

• プロジェクトのメンテナーまたはオーナーのロール。

ローカルルールセットファイルを作成するには:

1. まだ存在しない場合は、プロジェクトのルートに.gitlabディレクトリを作成します。
2. .gitlabディレクトリにsast-ruleset.tomlという名前のファイルを作成します。
3. カスタムルールセットをsast-ruleset.tomlファイルに追加します。
4. ローカルルールセットファイルをリポジトリにコミットします。

ローカルルールセットファイルの例を参照してください。

リモートルールセットファイルを使用する

複数のプロジェクトに同じカスタマイズを適用したい場合は、リモートルールセットファイルを使用します。リモートルールセットファイルは、それを使用するプロジェクトのリポジトリの外部に保存されます。

リモートルールセットファイルを使用するには、以下を行います:

• リモートルールセットを作成します。
• 各プロジェクトからリモートルールセットを参照します。

リモートルールセットファイルを作成する

複数のプロジェクトの中央ルールセットとしてリモートルールセットファイルを作成します。

前提条件:

• プロジェクトのメンテナーまたはオーナーのロール。

リモートルールセットを作成するには:

• プロジェクトのリポジトリにルールセットを作成します。

  例となるルールセットファイルについては、例を参照してください。

リモートルールセットファイルを参照する

プロジェクトにルールを適用するために、リモートルールセットファイルを参照します。

前提条件:

• プロジェクトのメンテナーまたはオーナーのロール。
• プロジェクトのリモートルールセット。
• リモートルールセットが保存されているプロジェクトへの読み取りアクセス権。たとえば、ジョブトークンまたはグループアクセストークンを使用します。

各プロジェクトでリモートルールセットファイルを参照するには、以下を行います:

• リモートルールセットファイルの場所を指定するために、CI/CD変数SAST_RULESET_GIT_REFERENCE変数を設定します。

  リモートルールセットファイルの参照は、プロジェクトURI、オプションの認証、およびオプションのGit SHAを指定するために、Git URLと同様の形式を使用します。変数は以下の形式を使用します:

  [<AUTH_USER>[:<AUTH_PASSWORD>]@]<PROJECT_PATH>[@<GIT_SHA>]

以下の例は、SASTを有効にし、リモートルールセットファイルを使用します。この例では、ファイルはexample-ruleset-projectのデフォルトブランチのパス.gitlab/sast-ruleset.tomlにコミットされます。

include:
  - template: Jobs/SAST.gitlab-ci.yml

variables:
  SAST_RULESET_GIT_REFERENCE: "gitlab.com/example-group/example-ruleset-project"

高度な例については、プライベートリモート設定の例を指定するを参照してください。

リモート設定ファイルのトラブルシューティング

リモート設定ファイルがカスタマイズを正しく適用していないように見える場合、原因は以下のとおりです:

1. あなたのリポジトリにはローカルの.gitlab/sast-ruleset.tomlファイルがあります。
   • デフォルトでは、リモート設定が変数として設定されていても、ローカルファイルが存在する場合はそれが使用されます。
   • ローカル設定ファイルを無視するには、SECURE_ENABLE_LOCAL_CONFIGURATION CI/CD変数をfalseに設定します。
2. 認証に問題があります。
   • これが問題の原因であるかどうかを確認するには、認証を必要としないリポジトリの場所から設定ファイルを参照してみてください。

スキーマ

ルールセット設定ファイルはTOML構文を使用します。以下のセクションでは、各設定要素の構造と有効な設定について説明します。

トップレベルセクション

トップレベルセクションには、TOMLテーブルとして定義された1つ以上の設定セクションが含まれます。

設定例:

[semgrep]
...

既存のルールを変更する設定セクションを作成したり、カスタムルールセットをビルドしたりすることは避けてください。後者はデフォルトルールを完全に置き換えるためです。

[$analyzer]設定セクション

[$analyzer]セクションでは、アナライザーの動作をカスタマイズできます。有効なプロパティは、作成している設定の種類によって異なります。

interpolate

以下の例は、$GITURL環境変数を使用してプライベートリポジトリにアクセスする設定を示しています。この変数にはユーザー名とトークン（例: https://user:token@url）が含まれているため、それらは設定ファイルに明示的に保存されません。

[semgrep]
  description = "My private Semgrep ruleset"
  interpolate = true

  [[semgrep.passthrough]]
    type  = "git"
    value = "$GITURL"
    ref = "main"

[[$analyzer.ruleset]]セクション

[[$analyzer.ruleset]]セクションは、単一のデフォルトルールを対象とし、変更します。アナライザーごとに最大20個のこれらのセクションを定義できます。

設定例:

[semgrep]
  [[semgrep.ruleset]]
    disable = true
    ...

[$analyzer.ruleset.identifier]セクション

[$analyzer.ruleset.identifier]セクションは、変更したいデフォルトルールの識別子を定義します。

typeとvalueの正しい値は、アナライザーによって生成されるgl-sast-report.jsonを見ることで調べることができます。このファイルは、アナライザーのCIジョブからジョブアーティファクトとしてダウンロードできます。

たとえば、以下のスニペットは、3つの識別子を持つsemgrepルールからの検出結果を示しています。JSONオブジェクト内のtypeとvalueキーは、このセクションで指定すべき値に対応しています。

...
  "vulnerabilities": [
    {
      "id": "7331a4b7093875f6eb9f6eb1755b30cc792e9fb3a08c9ce673fb0d2207d7c9c9",
      "category": "sast",
      "message": "Key Exchange without Entity Authentication",
      "description": "Audit the use of ssh.InsecureIgnoreHostKey\n",
      ...
      "identifiers": [
        {
          "type": "semgrep_id",
          "name": "gosec.G106-1",
          "value": "gosec.G106-1"
        },
        {
          "type": "cwe",
          "name": "CWE-322",
          "value": "322",
          "url": "https://cwe.mitre.org/data/definitions/322.html"
        },
        {
          "type": "gosec_rule_id",
          "name": "Gosec Rule ID G106",
          "value": "G106"
        }
      ]
    }
    ...
  ]
...

設定例:

[semgrep]
  [[semgrep.ruleset]]
    [semgrep.ruleset.identifier]
      type = "semgrep_id"
      value = "gosec.G106-1
    ...

[$analyzer.ruleset.override]セクション

[$analyzer.ruleset.override]セクションでは、デフォルトルールの属性をオーバーライドできます。

設定例:

[semgrep]
  [[semgrep.ruleset]]
    [semgrep.ruleset.override]
      severity = "Critical"
      name = "Command injection"
    ...

[[$analyzer.passthrough]]セクション

[[$analyzer.passthrough]]セクションでは、アナライザー用のカスタム設定をビルドできます。アナライザーごとに最大20個のこれらのセクションを定義できます。パススルーは、アナライザーのデフォルトルールを置き換える完全な設定に評価される_パススルーチェーン_に構成されます。

パススルーは順序どおりに評価されます。チェーンで後からリストされるパススルーは、優先順位が高く、以前のパススルーによって生成されたデータを上書きするか追加できます（modeによって異なります）。これは、既存の設定を使用または変更する必要がある場合に便利です。

単一のパススルーによって生成される設定のサイズは10 MBに制限されます。

パススルータイプ

例

以下の例は、一般的なシナリオでのルールセットのカスタマイズ方法を示しています。各例で使用されている設定オプションを理解するには、スキーマセクションを使用してください。

高度なSASTのデフォルトルールを置き換える

以下のカスタムルールセット設定により、高度なSASTアナライザーのデフォルトルールセットは、スキャン対象のリポジトリ内のmy-gitlab-advanced-sast-rules.yamlという名前のファイルに含まれるカスタムルールセットに置き換えられます。

# my-gitlab-advanced-sast-rules.yaml
---
rules:
- id: my-custom-rule
  pattern: print("Hello World")
  message: |
    Unauthorized use of Hello World.
  severity: ERROR
  languages:
  - python

[gitlab-advanced-sast]
  description = "My custom ruleset for Semgrep"

  [[gitlab-advanced-sast.passthrough]]
    type  = "file"
    value = "my-gitlab-advanced-sast-rules.yaml"

デフォルトの高度なSASTルールを無効にする

高度なSASTルールを無効にするか、そのメタデータを編集できます。以下の例は、異なる基準に基づいてルールを無効にします:

• 脆弱性のクラス全体を識別子するCWE識別子。
• 高度なSASTで使用される特定の検出戦略を識別子する高度なSASTルールID。
• 互換性のために高度なSASTの検出結果に含まれる、関連するSemgrepルールID。この追加メタデータにより、両方のアナライザーが同じ場所で類似の検出結果を作成した場合に、検出結果を自動的に移行できます。

これらの識別子は、各脆弱性の脆弱性の詳細に表示されます。また、各識別子とその関連するtypeをダウンロード可能なSASTレポートアーティファクトで確認できます。

[gitlab-advanced-sast]
  [[gitlab-advanced-sast.ruleset]]
    disable = true
    [gitlab-advanced-sast.ruleset.identifier]
      type = "cwe"
      value = "89"

  [[gitlab-advanced-sast.ruleset]]
    disable = true
    [gitlab-advanced-sast.ruleset.identifier]
      type = "gitlab-advanced-sast_id"
      value = "java-spring-csrf-unrestricted-requestmapping-atomic"

  [[gitlab-advanced-sast.ruleset]]
    disable = true
    [gitlab-advanced-sast.ruleset.identifier]
      type = "semgrep_id"
      value = "java_cookie_rule-CookieHTTPOnly"

その他のSASTアナライザーのデフォルトルールを無効にする

以下のカスタムルールセット設定により、以下のルールはレポートから省略されます:

• gosec.G106-1のsemgrep_idまたは322のcweを持つsemgrepルール。
• sql_injectionのsobelow_rule_idを持つsobelowルール。
• memcpyのflawfinder_func_nameを持つflawfinderルール。

[semgrep]
  [[semgrep.ruleset]]
    disable = true
    [semgrep.ruleset.identifier]
      type = "semgrep_id"
      value = "gosec.G106-1"

  [[semgrep.ruleset]]
    disable = true
    [semgrep.ruleset.identifier]
      type = "cwe"
      value = "322"

[sobelow]
  [[sobelow.ruleset]]
    disable = true
    [sobelow.ruleset.identifier]
      type = "sobelow_rule_id"
      value = "sql_injection"

[flawfinder]
  [[flawfinder.ruleset]]
    disable = true
    [flawfinder.ruleset.identifier]
      type = "flawfinder_func_name"
      value = "memcpy"

デフォルトルールのメタデータをオーバーライドする

以下のカスタムルールセット設定により、semgrepで検出されたタイプCWE、値322の脆弱性の重大度はCriticalにオーバーライドされます。

[semgrep]
  [[semgrep.ruleset]]
    [semgrep.ruleset.identifier]
      type = "cwe"
      value = "322"
    [semgrep.ruleset.override]
      severity = "Critical"

semgrepのデフォルトルールを置き換えるか追加する

以下のカスタムルールセット設定により、semgrepアナライザーのデフォルトルールセットは、スキャン対象のリポジトリ内のmy-semgrep-rules.yamlという名前のファイルに含まれるカスタムルールセットに置き換えられます。

# my-semgrep-rules.yml
---
rules:
- id: my-custom-rule
  pattern: print("Hello World")
  message: |
    Unauthorized use of Hello World.
  severity: ERROR
  languages:
  - python

[semgrep]
  description = "My custom ruleset for Semgrep"

  [[semgrep.passthrough]]
    type  = "file"
    value = "my-semgrep-rules.yml"

semgrep用のパススルーチェーンを使用したカスタム設定をビルドする

以下のカスタムルールセット設定により、semgrepアナライザーのデフォルトルールセットは、4つのパススルーのチェーンを評価することによって生成されたカスタムルールセットに置き換えられます。各パススルーは、コンテナ内の/sgrulesディレクトリに書き込まれるファイルを生成します。Gitリモートが応答しない場合に備えて、60秒のtimeoutが設定されます。

この例では、異なるパススルータイプが示されています:

• 2つのgitパススルーで、1つ目はmyrulesGitリポジトリからdevelopブランチをプルし、2つ目はsast-rulesリポジトリからリビジョン97f7686をプルし、goサブディレクトリ内のファイルのみを考慮します。
  • sast-rulesエントリは、設定の後の方に表示されるため、優先順位が高くなります。
  • 2つのチェックアウト間でファイル名が衝突する場合、sast-rulesリポジトリのファイルがmyrulesリポジトリのファイルを上書きするします。
• rawパススルーは、そのvalueを/sgrules/insecure.ymlに書き込みます。
• urlパススルーは、URLでホストされている設定をフェッチし、/sgrules/gosec.ymlに書き込みます。

その後、/sgrulesの下にある最終的な設定でSemgrepが実行するされます。

[semgrep]
  description = "My custom ruleset for Semgrep"
  targetdir = "/sgrules"
  timeout = 60

  [[semgrep.passthrough]]
    type  = "git"
    value = "https://gitlab.com/user/myrules.git"
    ref = "develop"

  [[semgrep.passthrough]]
    type  = "git"
    value = "https://gitlab.com/gitlab-org/secure/gsoc-sast-vulnerability-rules/playground/sast-rules.git"
    ref = "97f7686db058e2141c0806a477c1e04835c4f395"
    subdir = "go"

  [[semgrep.passthrough]]
    type  = "raw"
    target = "insecure.yml"
    value = """
rules:
- id: "insecure"
  patterns:
    - pattern: "func insecure() {...}"
  message: |
    Insecure function insecure detected
  metadata:
    cwe: "CWE-200: Exposure of Sensitive Information to an Unauthorized Actor"
  severity: "ERROR"
  languages:
    - "go"
"""

  [[semgrep.passthrough]]
    type  = "url"
    value = "https://semgrep.dev/c/p/gosec"
    target = "gosec.yml"

チェーン内のパススルーのモードを設定する

チェーン内のパススルー間で発生するファイル名の競合をどのように処理するかを選択できます。デフォルトの動作は、既存の同じ名前のファイルを上書きすることですが、代わりにmode = appendを選択して、後のファイルのコンテンツを以前のファイルに追加することもできます。

appendモードは、file、url、およびrawパススルータイプでのみ使用できます。

以下のカスタムルールセット設定では、2つのrawパススルーが/sgrules/my-rules.ymlファイルを繰り返し組み立てるために使用され、そのファイルがSemgrepにルールセットとして提供されます。各パススルーは、単一のルールをルールセットに追加します。最初のパススルーは、Semgrepルール構文に従って、トップレベルのrulesオブジェクトを初期化する役割を担います。

[semgrep]
  description = "My custom ruleset for Semgrep"
  targetdir = "/sgrules"
  validate = true

  [[semgrep.passthrough]]
    type  = "raw"
    target = "my-rules.yml"
    value = """
rules:
- id: "insecure"
  patterns:
    - pattern: "func insecure() {...}"
  message: |
    Insecure function 'insecure' detected
  metadata:
    cwe: "..."
  severity: "ERROR"
  languages:
    - "go"
"""

  [[semgrep.passthrough]]
    type  = "raw"
    mode  = "append"
    target = "my-rules.yml"
    value = """
- id: "secret"
  patterns:
    - pattern-either:
        - pattern: '$MASK = "..."'
    - metavariable-regex:
        metavariable: "$MASK"
        regex: "(password|pass|passwd|pwd|secret|token)"
  message: |
    Use of hard-coded password
  metadata:
    cwe: "..."
  severity: "ERROR"
  languages:
    - "go"
"""

# /sgrules/my-rules.yml
rules:
- id: "insecure"
  patterns:
    - pattern: "func insecure() {...}"
  message: |
    Insecure function 'insecure' detected
  metadata:
    cwe: "..."
  severity: "ERROR"
  languages:
    - "go"
- id: "secret"
  patterns:
    - pattern-either:
        - pattern: '$MASK = "..."'
    - metavariable-regex:
        metavariable: "$MASK"
        regex: "(password|pass|passwd|pwd|secret|token)"
  message: |
    Use of hard-coded password
  metadata:
    cwe: "..."
  severity: "ERROR"
  languages:
    - "go"

プライベートリモート設定を指定する

以下の例は、SASTを有効にし、共有ルールセットカスタマイズファイルを使用します:

• このファイルは、認証を必要とするプライベートプロジェクトからダウンロードされます。この例では、CI/CD変数に安全に保存されているグループアクセストークンを使用します。
• このファイルは、デフォルトブランチではなく、特定のGitコミットSHAでチェックアウトされます。

include:
  - template: Jobs/SAST.gitlab-ci.yml

variables:
  SAST_RULESET_GIT_REFERENCE: "oauth2:$GROUP_ACCESS_TOKEN@gitlab.com/example-group/example-ruleset-project@c8ea7e3ff126987fb4819cc35f2310755511c2ab"

デモンストレーションプロジェクト

これらのいくつかの設定オプションを示すデモンストレーションプロジェクトを参照してください。

これらのプロジェクトの多くは、リモートルールセットを使用してルールをオーバーライドまたは無効にする方法を示しており、対象となるアナライザーごとにグループ化されています。

リモートルールセットの設定に関するビデオデモンストレーションも視聴できます:

• リモートルールセットを使用したIaCアナライザー