writehat

WriteHat は、レポート作成プロセスから Microsoft Word（そして多くの苦痛）を取り除くレポートツールです。Markdown --> HTML --> PDF。ペネトレーションテスターによってペネトレーションテスターのために作られましたが、あらゆる種類のレポートの生成に使用できます。Django (Python 3) で書かれています。

特徴:

• 美しいペンテストレポートを簡単に生成
• その場でドラッグ＆ドロップできるレポートビルダー
• Markdown対応 – コードブロック、テーブルなど
• 画像の切り抜き、注釈、キャプション、アップロード
• カスタマイズ可能なレポートの背景/フッター
• オペレーターの割り当てと個別レポートセクションのステータス追跡
• レポートのクローン作成とテンプレート化機能
• 所見データベース
• 複数のスコアリングタイプに対応 (CVSS 3.1、DREAD)
• 同じ所見セットから複数のレポートを簡単に生成可能
• 拡張可能な設計により、パワーユーザーが高度にカスタマイズされたレポートセクションを作成可能
• LDAP統合

インストール前提条件:

• docker と docker-compose をインストール
  • 通常は apt、pacman、dnf などでインストール可能
  root@kitploit:~

  $ sudo apt install docker.io docker-compose
  

WriteHat のデプロイ (テスト用の簡単な方法):

WriteHat は以下の1コマンドでデプロイできます:

$ git clone https://github.com/blacklanternsecurity/writehat && cd writehat && docker-compose up

https://127.0.0.1 にログイン (デフォルト: admin / PLEASECHANGETHISFORHEAVENSSAKE)

WriteHat のデプロイ (正しい方法):

1. Docker と Docker Compose をインストール

2. WriteHat リポジトリをクローンして /opt に配置

   root@kitploit:~

   $ cd /opt
   $ git clone https://github.com/blacklanternsecurity/writehat
   $ cd writehat
   

3. 安全なパスワードを作成し、writehat/config/writehat.conf に設定:

   • MongoDB（docker-compose.yml にも入力）
   • MySQL（docker-compose.yml にも入力）
   • Django（Cookie の暗号化などに使用）
   • 管理者ユーザー 注意: デフォルト設定を使用する場合、パスワード以外は変更する必要はありません 注意: writehat/config/writehat.conf と docker-compose.yml のパーミッションを忘れずにロックダウンしてください (chown root:root; chmod 600)

4. 希望するホスト名を writehat/config/writehat.conf の allowed_hosts に追加

5. (任意) 自己署名SSL証明書を nginx/ 内の以下のファイルで置き換え:

用語

以下は、WriteHat の用語のうち、わかりにくいかもしれない基本的な説明です。

Engagement
 ├─ Customer
 ├─ Finding Group 1
 │   ├─ Finding
 │   └─ Finding
 ├─ Finding Group 2
 │   ├─ Finding
 │   └─ Finding
 ├─ Report 1
 └─ Report 2
     └─ Page Template

Engagement

Engagement は、顧客向けのコンテンツを作成する場所です。ここで実際の作業（レポートの作成や所見の入力）を行います。

Report

Report は、ドラッグ＆ドロップインターフェースで簡単に更新し、HTML または PDF にレンダリングできる、モジュール化された階層的なComponentの集まりです。1つの Engagement に複数のReportを作成できます。Page Templateを使用して背景やフッターをカスタマイズできます。ReportはReport Templateに変換することもできます。

Report Component

レポートComponentは、レポート作成ツール内でドラッグ＆ドロップで配置できるレポートのセクションまたはモジュールです。例: 「タイトルページ」「Markdown」「所見」など。多くの組み込みコンポーネントがありますが、自分で作成することもできます。（HTML/CSS + Python で構成されているため、簡単です。以下のガイドを参照してください。）

Report Template

Report Template は、Engagement内のReportの開始点として使用できます。ReportをReport Templateに変換することもできます。

Finding Group

Finding Group は、同じ方法（例: CVSS または DREAD）でスコアリングされる所見のコレクションです。Engagement ごとに複数の Finding Group を作成できます（例: 「技術的所見」と「財務的所見」）。所見をReportに挿入するとき（たとえば「所見」Componentを使用）、そのComponentにどのFinding Groupを入力するかを選択する必要があります。

Page Template

Page Template を使用すると、レポートの背景画像とフッターをカスタマイズできます。デフォルトのPage Templateを1つ設定すると、EngagementまたはReportレベルで上書きされない限り、グローバルに適用されます。

カスタムレポートコンポーネントの作成

各レポートコンポーネントは、以下の要素で構成されています:

1. writehat/components/ にある Python ファイル
2. writehat/templates/componentTemplates/ にある HTML テンプレート
3. writehat/static/css/component/ にある CSS ファイル（オプション）

これらのディレクトリ内の既存ファイルを参考にすることをお勧めします。出発点や例として適しています。

簡単なカスタムコンポーネントは次のようになります:

components/CustomComponent.py:

from .base import *

class CustomComponentForm(ComponentForm):

    summary = forms.CharField(label='Component Text', widget=forms.Textarea, max_length=50000, required=False)
    field_order = ['name', 'summary', 'pageBreakBefore', 'showTitle']


class Component(BaseComponent):

    default_name = 'Custom Report Component'
    formClass = CustomComponentForm

    # "templatable" 属性は、レポートがテンプレートに変換されたときにそのフィールドを保存するかどうかを決定します
    fieldList = {
        'summary': StringField(markdown=True, templatable=True),
    }

    # HTML テンプレートを必ず指定してください
    htmlTemplate = 'componentTemplates/CustomComponent.html'

    # Font Awesome アイコンの種類と色 (HTML/CSS)
    # これは Web アプリ内で視覚的な飾りとして使用されます
    iconType = 'fas fa-stream'
    iconColor = 'var(--blue)'

    # "preprocess" 関数はレポートがレンダリングされるときに実行されます
    # これを使用して、データに対して最後の操作を実行します
    def preprocess(self, context):

        # 例: "summary" フィールド全体を大文字にする:
        #   context['summary'] = context['summary'].upper()
        return context

フィールドは、コンポーネントクラスとそのフォームの両方で同じ名前を持つ必要があります。すべてのコンポーネントは BaseComponent または別のコンポーネントを継承する必要があります。また、各コンポーネントには name、pageBreakBefore（新しいページで開始するかどうか）、showTitle（name フィールドを見出しとして表示するかどうか）の組み込みフィールドがあります。そのため、これらを追加する必要はありません。

componentTemplates/CustomComponent.html:

Python モジュールのフィールドは、自動的にテンプレートコンテキストに追加されます。この例では、summary フィールドを Markdown としてレンダリングしたいので、その前に markdown タグを追加します。また、report.name、report.findings、engagement.customer.name などの Engagement および Report レベルの変数にもアクセスできます。

{% load custom_tags %}
<section class="l{{ level }} component{% if pageBreakBefore %} page-break{% endif %}" id="container_{{ id }}">
  {% include 'componentTemplates/Heading.html' %}
  <div class='markdown-align-justify custom-component-summary'>
    <p>
      {% markdown summary %}
    </p>
  </div>
</section>

componentTemplates/CustomComponent.css（オプション）:

ファイル名は Python ファイルと同じでなければなりません（拡張子は .py ではなく .css）。レポートがレンダリングされるときに自動的に読み込まれます。

div.custom-component-summary {
    font-weight: bold;
}

上記のファイルを作成したら、Web アプリを再起動するだけで、新しいコンポーネントが自動的に反映されます。

$ docker-compose restart writehat

手動 DB 更新/マイグレーション

データベーススキーマを変更するアップデートがプッシュされた場合、Django のデータベースマイグレーションはコンテナの再起動時に自動的に実行されます。ただし、ユーザーの操作が必要になる場合があります。 Django マイグレーションを手動で適用するには:

1. WriteHat を停止 (systemctl stop writehat)
2. WriteHat ディレクトリに移動 (/opt/writehat)
3. Docker コンテナを起動

$ docker-compose run writehat bash

4. コンテナ内で、通常通りマイグレーションを適用:

$ ./manage.py makemigrations
$ ./manage.py migrate
$ exit

5. Docker コンテナを停止し、サービスを再起動

$ docker-compose down
$ systemctl start writehat

手動 DB バックアップ/リストア

注意: Web アプリの /admin ページにはすでにアプリ内機能があります。cron などを使用してファイルレベルのバックアップジョブを作成したい場合にこの方法を使用できます。

1. 移行先システムで:
   • 通常のインストール手順に従う
   • WriteHat を停止 (systemctl stop writehat)
2. 移行元システムで:
   • WriteHat を停止 (systemctl stop writehat)
3. mysql、mongo、writehat/migrations ディレクトリを TAR でアーカイブし、移行先システムの同じ場所にコピー:

# 必ず root で実行
$ sudo tar --same-owner -cvzpf db_backup.tar.gz mongo mysql writehat/migrations

4. 移行先システムで、migrations ディレクトリのバックアップを作成

$ mv writehat/migrations writehat/migrations.bak

5. 移行先システムで TAR アーカイブを展開

$ sudo tar --same-owner -xvpzf db_backup.tar.gz

6. 新しいシステムで WriteHat を起動

$ systemctl start writehat

ロードマップ / 可能性のある 将来の開発:

• 変更追跡とリビジョン
• より詳細なレビュー/フィードバック機能
• Google Docs のような共同編集機能
• JSON エクスポート機能
• プレゼンテーションスライドの生成
• CSV アップロード機能を備えたより高度なテーブル作成ツール
• より細かい権限 / ACL（ユーザーと管理者以外のロールを超えて）

既知のバグ / 制限:

• Chrome または Chromium が推奨ブラウザです。その他は未テストで、バグが発生する可能性があります。
• レポートコンポーネントの「担当者」フィールドは、ローカルユーザーではなく LDAP ユーザーでのみ動作します。
• 画像への注釈は適用時にわずかに位置がずれることがあります。これは JS ライブラリで追跡中の既知のバグです: https://github.com/ailon/markerjs/issues/40
• 改ページ時に視覚的なバグが発生することがあります。影響を受ける Markdown に手動で改ページを挿入することで修正できます（エディターにボタンがあります）。