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 можно развернуть одной командой:

$ 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 (используется для шифрования куки и т.д.)
   • Пользователя admin Примечание: Ничего, кроме паролей, менять не нужно, если вы используете конфигурацию по умолчанию. Примечание: Не забудьте ограничить права доступа к writehat/config/writehat.conf и docker-compose.yml: (chown root:root; chmod 600)

4. Добавьте желаемое имя хоста в allowed_hosts в writehat/config/writehat.conf

Терминология

Вот основные пояснения некоторых терминов WriteHat, которые могут быть неочевидны.

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

Вовлечение (Engagement)

Вовлечение — это место, где создаётся контент для заказчика. Здесь происходит основная работа — создание отчётов и ввод находок.

Отчёт (Report)

Отчёт — это модульное иерархическое расположение компонентов, которое можно легко обновлять с помощью интерфейса перетаскивания, а затем преобразовывать в HTML или PDF. В рамках одного вовлечения может быть несколько отчётов. Шаблон страницы можно использовать для настройки фона и нижнего колонтитула. Отчёт также можно преобразовать в шаблон отчёта.

Компонент отчёта (Report Component)

Компонент отчёта — это раздел или модуль отчёта, который можно перетаскивать в нужное место в редакторе отчётов. Примеры: «Титульная страница», «Markdown», «Находки» и т.д. Существует множество встроенных компонентов, но вы можете создавать и свои собственные. (Они представляют собой просто HTML/CSS + Python, так что это довольно просто. Смотрите руководство ниже.)

Шаблон отчёта (Report Template)

Шаблон отчёта можно использовать в качестве отправной точки для отчёта (в рамках вовлечения). Отчёты также можно преобразовывать в шаблоны отчётов.

Группа находок (Finding Group)

Группа находок — это набор находок, которые оцениваются одинаковым способом (например, CVSS или DREAD). Вы можете создать несколько групп находок на одно вовлечение (например, «Технические находки» и «Финансовые находки»). При вставке находок в отчёт (например, через компонент «Находки») необходимо выбрать, какая группа находок будет заполнять этот компонент.

Шаблон страницы (Page Template)

Шаблон страницы позволяет настроить фоновые изображения и нижние колонтитулы отчёта. Вы можете установить один шаблон страницы по умолчанию, и он будет применяться глобально, если не будет переопределён на уровне вовлечения или отчёта.

Написание пользовательских компонентов отчёта

Каждый компонент отчёта состоит из следующего:

1. Файл Python в writehat/components/
2. HTML-шаблон в writehat/templates/componentTemplates/
3. CSS-файл в writehat/static/css/component/ (опционально)

Мы рекомендуем обратиться к существующим файлам в этих каталогах; они хорошо подходят в качестве отправных точек/примеров.

Простой пользовательский компонент будет выглядеть так:

components/CustomComponent.py:

from .base import *

class CustomComponentForm(ComponentForm):

    summary = forms.CharField(label='Текст компонента', widget=forms.Textarea, max_length=50000, required=False)
    field_order = ['name', 'summary', 'pageBreakBefore', 'showTitle']


class Component(BaseComponent):

    default_name = 'Пользовательский компонент отчёта'
    formClass = CustomComponentForm

    # атрибут "templatable" определяет, будет ли это поле
    # сохранено, если отчёт когда-либо будет преобразован в шаблон
    fieldList = {
        'summary': StringField(markdown=True, templatable=True),
    }

    # обязательно укажите HTML-шаблон
    htmlTemplate = 'componentTemplates/CustomComponent.html'

    # тип и цвет иконки Font Awesome (HTML/CSS)
    # Это просто визуальное оформление в веб-приложении
    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 и т.д.

{% 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 (но с расширением .css вместо .py). Он загружается автоматически при рендеринге отчёта.

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

После создания указанных выше файлов просто перезапустите веб-приложение, и новый компонент появится автоматически.

$ docker-compose restart writehat

Ручное обновление/миграция БД

Если вышло обновление, изменяющее схему базы данных, миграции 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

Ручное резервное копирование/восстановление БД

Обратите внимание, что в приложении уже есть функциональность для этого на странице /admin. Вы можете использовать этот метод, если хотите выполнять резервное копирование на уровне файлов через cron и т.д.

1. На целевой системе:
   • Выполните стандартные шаги установки
   • Остановите WriteHat (systemctl stop writehat)
2. На исходной системе:
   • Остановите WriteHat (systemctl stop writehat)
3. Упакуйте в TAR каталоги mysql, mongo и writehat/migrations и скопируйте архив на целевую систему (в то же место):

# ДОЛЖНО ВЫПОЛНЯТЬСЯ ОТ 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. Другие не тестировались и могут содержать ошибки.
• Поле «Ответственный» (Assignee) в компонентах отчёта работает только с пользователями LDAP, а не с локальными.
• Аннотации на изображениях иногда немного смещаются при применении. Это известная ошибка, которую мы отслеживаем в JS-библиотеке: https://github.com/ailon/markerjs/issues/40
• Визуальные ошибки иногда возникают на разрывах страниц. Их можно исправить, вручную вставив разрыв страницы в соответствующем Markdown (в редакторе есть соответствующая кнопка).