debug-rule

スキル：ルールのデバッグ

モデル上でルールまたは近似が予期しない動作をする理由を、汚染がどこで失われるかをたどって診断し、修正の担当がルール、欠落しているライブラリモデル、エンジンのどれかを判断します。

入力

呼び出し元から提供されます。省略された場合はデフォルト値を使用します。必須の入力が欠けており、妥当なデフォルト値もない場合にのみ確認してください。

• project-root（任意）— 対象プロジェクトのルート。Opentaint はすべての解析成果物を固定された <project-root>/.opentaint/ ディレクトリ内に保持するため、以下のすべての .opentaint/... パスはそこを基準に解決されます。デフォルト：現在のディレクトリ
• rule（必須）— テスト対象のコードを通るように汚染を誘導するサンプルまたはフローを持つ、対象のルール。形式は <ruleSetRelativePath>.yaml:<shortId> です。近似の場合は、近似対象のメソッドを通るようにサンプルが汚染を誘導するルール
• model（必須）— 動作が発生するプロジェクトモデル

ワークフロー

1. 再現して汚染が失われる箇所を特定する

問題が発生した実行とまったく同じ条件（同じ model、ルールセット、適用された近似ディレクトリ）で再現し、ファクト到達可能性の実行によって汚染がどこで失われるかを追跡します。フォアグラウンドのブロッキングコマンドとして直接実行し、終了するまで待ちます。バックグラウンド実行や Monitor の使用は避けてください。

opentaint test rule reachability <rule> \
  --project-model <model> \
  -o <results-dir>/report.sarif \
  --ruleset builtin --ruleset .opentaint/rules \
  --passthrough-approximations .opentaint/pass-through \
  --dataflow-approximations .opentaint/dataflow

<results-dir> は、テストモデルでは .opentaint/test-results/<name>、メインのスキャンでは .opentaint/results です。命令ごとのファクトは -o ファイルではなく、同じディレクトリにある <results-dir>/debug-ifds-fact-reachability.sarif にあります。-o の SARIF にはルールが発火したかどうかだけが表示されます。汚染が失われた箇所を見つけるには、同じディレクトリにあるファイルを読みます。

• 検出漏れ（陽性になるはずなのに通らない場合、またはスキャンにフローがない場合）— ソースにファクトが存在することを確認します。存在しない場合、問題はフローではなく pattern-sources にあります。それ以外の場合はファクトをたどり、最後にファクトを保持している命令と、ファクトがなくなる最初の命令を見つけます。その間が汚染の消失箇所です。
• 誤検出（陰性になるはずなのに発火する場合）— 逆に、汚染された入力が到達していないのにファクトが現れる箇所を見つけます。

問題が発生した実行を正確に追跡してください。別の model やルールセットでは、別のものが追跡されます。近似された呼び出しで汚染が失われる場合、その近似は伝播を行っていません。フローが検出されず、エントリーメソッドが解析されていない可能性がある場合は、--entry-points "<method-fqn>" を指定して再実行してください。その場合にのみ検出結果が現れるなら、データフローではなくエントリーポイントの検出に問題があります。Spring では、このフラグは追加で適用されます。自動検出されたエンドポイントはそのまま維持され、指定したメソッドが追加されます。そのため、解析が開始されないエンドポイントを強制的に含めるために使用し、1 つのメソッドに絞り込むためには使用しないでください。

2. 原因を分類する

修正の担当は、汚染を失わせた命令によって決まります。エンジンのバグである可能性は圧倒的に低いため、ほかの 2 つを除外できた場合に限り、最後に検討してください。ほとんどの場合、汚染を失わせる原因は、欠落または誤ったライブラリモデル、あるいはルールの欠陥です。どちらも除外には手間がかかりますが、その手間を理由に「エンジン」の問題と判断しないでください。結果は次の 3 つです。

• 外部ライブラリのメソッドで汚染が失われる → モデルの問題です。その実行の dropped-external-methods.yaml を確認してください（ファイルがない場合は、--track-external-methods を指定したスキャンで再生成されます）。そこに記載されている場合、そのメソッドはモデル化されていません。これが原因であり、近似の段階でモデル化する必要があります。記載されていないものの、組み込みモデルがそのメソッドをモデル化しているはずなのに、ここで汚染が失われる場合、そのモデルはこのケースに対して誤っています。passThrough のオーバーライドはルールレベルで適用されるため、そのメソッドにはそちらを優先してください。dataflow のオーバーライドは読み込み時に組み込みモデルと競合するため、passThrough を使用するか、伝播の表現に dataflow の形式が必須である場合はエンジンの問題と判断してください。
• ルールがマッチするはずの箇所で汚染が失われる → サニタイザーが誤作動している、またはシンクやソースのバリアントにマッチしていません。ルールの欠陥であり、ルール作成者が修正します。
• エンジンが伝播させるべき通常の命令（代入、キャスト、フィールド読み取り、すでにモデル化された呼び出し）で汚染が失われ、ルールが正しく、モデルも完全である → エンジンの問題です。

3. 診断を報告する

このスキルは診断を行い、修正先を振り分けます。ルールや近似を作成したり、パイプラインを再実行したりはしません。「出力」に従って診断を報告してください。

出力

成果物

• debug-ifds-fact-reachability.sarif — CLI が -o SARIF の隣に出力する、命令ごとのファクト到達可能性トレース

概要

• 診断内容：汚染が失われた（または誤って導入された）file:line と命令、および3つの原因のうち修正を担当するもの
• エンジンが原因の場合：最後に到達可能なファクトまでのファクト到達可能性トレース（エンジン問題のレポートで使用）、実行した正確なデバッグコマンド、およびそれらの実行対象となったモデル