transilience-report-style

Transilience レポートのスタイル

構造化された所見 JSON を、ブランドに合わせた A4 PDF に変換します（デフォルトはライトテーマ（モダン／ミニマル）。--theme dark でダークテーマに切り替え可能。ブランドグラデーションの罫線、枠付きコード／サンプル、フレーム付きスクリーンショット、重大度と CVSS スコアの色分け、所見カード、重大度メトリクスを含みます）。標準的な Transilience の納品物です。ジェネレーターはデータ駆動型で、JSON を 1 つ用意して、コマンドを 1 つ実行するだけです。デザインシステムについては、formats/transilience-report-style/SKILL.md §0（テーマ／パレット）を参照してください。

使用するタイミング

• ペネトレーションテスト／脆弱性評価／ネットワークスキャン／コンプライアンス対応が完了し、検証も済んでおり、PDF の納品物が必要な場合。
• 所見（できれば検証済み）があり、重大度、CVSS、証拠、修復方法がそろっている場合。

使用方法（3 ステップ）

1. reference/report-data-schema.json に沿って report_data.json を作成します。必須なのは engagement と findings のみです。それ以外のキー（executive_summary、metrics、sections、cve_register、coverage_table、attack_pattern_coverage、ruled_out、tools_used、roadmap、disclaimer）はすべて省略可能なセクションで、省略すると出力されません。最小限の動作するファイルについては、reference/example-report-data.json を参照してください。

   • 内部専用セクション： "internal": true を指定した sections[] の項目は report_data.json に保持されます（内部記録として維持されます）が、クライアント向け PDF には出力されません。ブラインド検証／独立再現の判定表など、内部 QA ログに使用してください。これらをクライアント向け PDF に含めてはいけません。

2. ジェネレーターを実行します：

   python3 reference/generate_report.py <report_data.json> -o reports/My-Report.pdf
   

   フォントとロゴは formats/transilience-report-style/ から自動検出されます。リポジトリ外で実行する場合は、--assets <dir> で場所を指定してください。reportlab が必要です（pip install reportlab）。

3. 検証として、ページをレンダリングし（pdftoppm -png -r 100 -f 1 -l 1 out.pdf /tmp/p）、納品前に内容を確認します。

同じデータから作成できる別版

• エグゼクティブ版 — generate_report.py <data.json> --exec-only を実行すると、表紙＋KPI ボックス＋説明文＋ロードマップがレンダリングされます。所見の詳細や技術レジスターは含まれないため、セキュリティチーム以外への共有に適しています。KPI の件数は、引き続きエンゲージメント全体を示します。
• 機械可読形式へのエクスポート — python3 ../../tools/report_export.py <data.json> --format csv|xml -o findings.csv を実行すると、脆弱性管理へのインポート用に所見レジスターを出力します。PDF レジスターおよび xlsx と同じ行を使用します。1 つのデータを 3 つの形式で表示します。

出力内容

表紙（ロゴ、タイトル行、サブタイトル、メタデータ）→ エグゼクティブサマリー（重大度の件数から自動生成される KPI メトリクスボックス＋説明文＋主なリスク＋肯定的な所見）→ 自由形式の sections（スコープ／方法論）→ 重大度の高い順（Critical→Info）にまとめた所見カード（重大度バー、CVSS＋ベクトル、CWE／OWASP、ステータス、影響対象、説明、影響、任意のPoC ブロック（各ステップは説明文＋コード形式のコマンド＋埋め込みスクリーンショットで構成）、任意の重大度調整情報、所見ごとの任意の CVE 表、修復方法）→ 任意の CVE レジスター、カバレッジ表、攻撃パターンのカバレッジ（サーフェス単位×攻撃クラスの決定論的マトリックス。ステータスを色分け）、除外項目の付録、使用したツールと手法、修復ロードマップ、免責事項。セクション番号は自動的に付与されます。

Finding オブジェクト（重要なフィールド）

id, title, severity (Critical|High|Medium|Low|Info), cvss_score, cvss_vector, cwe, owasp, affected[], description, impact, recommendation ＋任意の poc[], calibration, needs_live_confirmation, cves[], attack[]。attack[] には MITRE の手法 ID が含まれます。ATT&CK（T1190、T1059.001）、または ATT&CK の手法がない AI／LLM の Finding では ATLAS（AML.T0051）です。CWE／OWASP と並んで表示され、すべてのエクスポートに含まれます。poc は手順 {description, command, image_url} の順序付きリストです（従来の evidence／poc_request／screenshot フィールドを統合したもの）。各項目は番号付きの説明文、任意のコード形式のコマンド、任意の埋め込み画像として表示されます。PAN／Aadhaar／カードに類する値は表示時に防御的にマスキングされますが、元のテキストに含まれる実際の秘密情報／PII も必ず編集して削除してください。

規約

• 重大度は CVSS の範囲で設定します（≥9 は Critical、≥7 は High、≥4 は Medium、>0 は Low、0 は Info）。環境に応じて意図的に調整した場合は、calibration フィールドに調整内容を記載します（formats/transilience-report-style/pentest-report.md §7 を参照）。
• 絵文字は使用しません。重大度はテキストラベルのみを使用します。Finding のメタデータは文章ではなくフィールドに記載します。
• 1 件の Finding につき、検証済みの問題を 1 つ記載します。ほぼ重複する項目を繰り返すのではなく、システム全体に及ぶ事例はまとめてください。

参考資料

• ビジュアルデザインシステム全体（カラーパレット、タイポグラフィ、コンポーネント）：formats/transilience-report-style/SKILL.md
• ペンテストレポートの構成＋Finding の品質基準＋重大度の調整＋コンプライアンスマッピング：formats/transilience-report-style/pentest-report.md
• コンプライアンス版：formats/transilience-report-style/compliance-report.md
• ジェネレーター：reference/generate_report.py · スキーマ：reference/report-data-schema.json · 例：reference/example-report-data.json
• 事前 lint（スキーマのハードフェイル＋RAW フィールドのエスケープ／タグ許可リストによるレンダリング前チェック）：../../tools/report_data_lint.py — generate_report.py の前に実行してください。この lint（およびジェネレーター独自の report_data_shape ガード）により、文字列形式のナラティブ、無効な重大度、または安全でない <img>／<a href> がクライアント向け PDF に含まれるのを防ぎます。
• インプレース改訂（追加／置換／--rescore <disposition.csv>／--scope <allowlist> による範囲制限＋再採番／フィード間統合。KPI は常に再計算し、ナラティブ中の Finding 件数も削除します）：../../tools/report_data_revise.py — merge-reports による N→1 の統合とは異なる、段階的改訂のエントリーポイントです。
• 完成済み／外部レポート（PDF／xlsx／DOCX／Markdown／ネイティブ JSON）を標準 Finding スキーマに取り込みます：../../tools/report_ingest.py — 既に作成済みの成果物から merge／再テスト／CERT-In を開始でき、手作業で再入力する必要はありません。