writehat

WriteHat هي أداة إعداد تقارير تزيل Microsoft Word (وساعات طويلة من المعاناة) من عملية إعداد التقارير. ماركداون --> HTML --> PDF. صُممت بواسطة مختبرين اختراق، ومن أجل مختبرين اختراق - ولكن يمكن استخدامها لإنشاء أي نوع من التقارير. كُتبت باستخدام Django (Python 3).

الميزات:

• إنشاء تقارير اختراق جميلة بسهولة
• منشئ تقارير بالسحب والإفلات في الوقت الفعلي
• دعم ماركداون - بما في ذلك كتل الأكواد والجداول إلخ.
• قص الصور وإضافة التعليقات التوضيحية والتسميات ورفعها
• خلفية/تذييل قابل للتخصيص للتقارير
• تعيين مشغلين وتتبع حالة الأقسام الفردية للتقرير
• إمكانية استنساخ التقارير وتحويلها إلى قوالب
• قاعدة بيانات النتائج
• يدعم أنواع تسجيل متعددة (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 (يستخدم لتشفير ملفات تعريف الارتباط إلخ.)
   • المستخدم المسؤول ملاحظة: لا يلزم تعديل أي شيء آخر بخلاف كلمات المرور إذا كنت تستخدم التكوين الافتراضي ملاحظة: لا تنسَ تقييد صلاحيات writehat/config/writehat.conf و docker-compose.yml: (chown root:root; chmod 600)

4. إضافة اسم المضيف المطلوب إلى allowed_hosts في writehat/config/writehat.conf

5. (اختياري) في :

المصطلحات

فيما يلي شروحات أساسية لبعض مصطلحات WriteHat التي قد لا تكون واضحة.

مهمة
 ├─ العميل
 ├─ مجموعة نتائج 1
 │   ├─ نتيجة
 │   └─ نتيجة
 ├─ مجموعة نتائج 2
 │   ├─ نتيجة
 │   └─ نتيجة
 ├─ تقرير 1
 └─ تقرير 2
     └─ قالب صفحة

المهمة

المهمة هي المكان الذي يتم فيه إنشاء المحتوى للعميل. هذا هو مكان العمل - إنشاء التقارير وإدخال النتائج.

التقرير

التقرير هو ترتيب هرمي معياري من المكونات يمكن تحديثه بسهولة عبر واجهة السحب والإفلات، ثم تحويله إلى HTML أو PDF. يمكن أن تحتوي المهمة على تقارير متعددة. يمكن استخدام قالب الصفحة لتخصيص الخلفية والتذييل. يمكن أيضًا تحويل التقرير إلى قالب تقرير.

مكون التقرير

مكون التقرير هو قسم أو وحدة من التقرير يمكن سحبها/إفلاتها في مكانها داخل منشئ التقارير. تشمل الأمثلة "صفحة العنوان" و"ماركداون" و"النتائج" إلخ. هناك العديد من المكونات المدمجة، ولكن يمكنك أيضًا إنشاء مكوناتك الخاصة. (هي مجرد HTML/CSS + Python، لذا فهي سهلة جدًا. انظر الدليل أدناه)

قالب التقرير

يمكن استخدام قالب التقرير كنقطة بداية لـ تقرير (في المهمة). يمكن أيضًا تحويل التقارير إلى قوالب تقارير.

مجموعة النتائج

مجموعة النتائج هي مجموعة من النتائج التي يتم تسجيلها بنفس الطريقة (مثل CVSS أو DREAD). يمكنك إنشاء مجموعات نتائج متعددة لكل مهمة (مثل "النتائج الفنية" و"نتائج الخزانة"). عند إدراج النتائج في التقرير (عبر مكون "النتائج" على سبيل المثال)، تحتاج إلى تحديد مجموعة النتائج التي تريد ملء ذلك المكون بها.

قالب الصفحة

يتيح لك قالب الصفحة تخصيص صور الخلفية والتذييلات للتقارير. يمكنك تعيين قالب صفحة واحد كافتراضي، وسيتم تطبيقه بشكل عام ما لم يتم تجاوزه على مستوى المهمة أو التقرير.

كتابة مكونات تقارير مخصصة

يتكون كل مكون تقرير من العناصر التالية:

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 أمامه. لاحظ أنه يمكنك أيضًا الوصول إلى المتغيرات على مستوى التقرير والمهمة، مثل 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. قم بضغط mysql و mongo و writehat/migrations في أرشيف TAR وانسخ الأرشيف إلى النظام الوجهة (نفس الموقع):

# يجب التشغيل كجذر
$ 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
• صلاحيات / قوائم تحكم وصول أكثر تفصيلاً (تتجاوز مجرد دوري المستخدم والمسؤول)

الأخطاء / القيود المعروفة:

• Chrome أو Chromium هو المتصفح الموصى به. المتصفحات الأخرى لم يتم اختبارها وقد تواجه أخطاء.
• حقل "المسؤول" على مكونات التقرير يعمل فقط مع مستخدمي LDAP، وليس المحليين.
• أحيانًا تقفز التعليقات التوضيحية على الصور قليلاً عند تطبيقها. إنه خطأ معروف نتابعه مع مكتبة JS: https://github.com/ailon/markerjs/issues/40
• تظهر أخطاء بصرية أحيانًا عند فواصل الصفحات. يمكن إصلاح ذلك بإدراج فاصل صفحة يدويًا في الماركداون المتأثر (يوجد زر لذلك في المحرر).