writehat

WriteHat è uno strumento di reporting che elimina Microsoft Word (e molte ore di sofferenza) dal processo di redazione dei report. Markdown --> HTML --> PDF. Creato da penetration tester, per penetration tester - ma può essere utilizzato per generare qualsiasi tipo di report. Scritto in Django (Python 3).

Caratteristiche:

• Genera senza sforzo splendidi report di penetration test
• Costruttore di report drag-and-drop in tempo reale
• Supporto Markdown - inclusi blocchi di codice, tabelle, ecc.
• Ritaglia, annota, didascalia e carica immagini
• Sfondo / piè di pagina personalizzabile
• Assegna operatori e monitora lo stato delle singole sezioni del report
• Possibilità di clonare e creare modelli di report
• Database dei risultati
• Supporta più tipi di punteggio (CVSS 3.1, DREAD)
• Può generare facilmente più report dallo stesso insieme di risultati
• Il design estensibile consente agli utenti esperti di creare sezioni di report altamente personalizzate
• Integrazione LDAP

Prerequisiti di installazione:

• Installa docker e docker-compose
  • Di solito possono essere installati usando apt, pacman, dnf, ecc.
  root@kitploit:~

  $ sudo apt install docker.io docker-compose
  

Distribuzione di WriteHat (Il modo rapido e semplice, per test):

WriteHat può essere distribuito con un singolo comando:

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

Accedi su https://127.0.0.1 (predefinito: admin / PLEASECHANGETHISFORHEAVENSSAKE)

Distribuzione di WriteHat (Il modo corretto):

1. Installa Docker e Docker Compose

2. Clona il repository WriteHat in /opt

   root@kitploit:~

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

3. Crea password sicure in writehat/config/writehat.conf per:

   • MongoDB (inserisci anche in docker-compose.yml)
   • MySQL (inserisci anche in docker-compose.yml)
   • Django (usato per crittografare i cookie, ecc.)
   • Utente amministratore Nota: Nient'altro oltre alle password deve essere modificato se si utilizza la configurazione predefinita Nota: Non dimenticare di impostare i permessi su writehat/config/writehat.conf e docker-compose.yml: (chown root:root; chmod 600)

4. Aggiungi il nome host desiderato a allowed_hosts in writehat/config/writehat.conf

Terminologia

Ecco le spiegazioni di base per alcuni termini di WriteHat che potrebbero non essere ovvi.

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

Engagement

Un Engagement è il luogo in cui viene creato il contenuto per il cliente. Qui avviene il lavoro: creazione di report e inserimento dei risultati.

Report

Un Report è una disposizione modulare e gerarchica di Componenti che può essere facilmente aggiornata tramite un'interfaccia drag-and-drop, per poi essere renderizzata in HTML o PDF. Un engagement può avere più Report. Un Page Template può essere utilizzato per personalizzare lo sfondo e il piè di pagina. Un Report può anche essere convertito in un Report Template.

Componente del Report

Un Componente del report è una sezione o un modulo del report che può essere trascinato/rilasciato all'interno del creatore di report. Esempi includono "Pagina del titolo", "Markdown", "Risultati", ecc. Ci sono molti componenti predefiniti, ma puoi crearne di tuoi. (Sono solo HTML/CSS + Python, quindi è abbastanza facile. Vedi la guida qui sotto)

Report Template

Un Report Template può essere utilizzato come punto di partenza per un Report (in un Engagement). I Report possono anche essere convertiti in Report Template.

Finding Group

Un Finding Group è una raccolta di risultati che vengono valutati allo stesso modo (ad esempio CVSS o DREAD). Puoi creare più gruppi di risultati per engagement (ad esempio "Risultati tecnici" e "Risultati finanziari"). Quando inserisci i risultati nel Report (tramite il Componente "Risultati", ad esempio), devi selezionare quale Finding Group vuoi popolare in quel Componente.

Page Template

Un Page Template ti permette di personalizzare le immagini di sfondo e i piè di pagina del report. Puoi impostare un Page Template come predefinito e verrà applicato globalmente a meno che non venga sovrascritto a livello di Engagement o Report.

Scrittura di componenti di report personalizzati

Ogni componente del report è composto da:

1. Un file Python in writehat/components/
2. Un template HTML in writehat/templates/componentTemplates/
3. Un file CSS in writehat/static/css/component/ (opzionale)

Consigliamo di fare riferimento ai file esistenti in queste directory; funzionano bene come punti di partenza / esempi.

Un semplice componente personalizzato sarebbe simile a questo:

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

    # the "templatable" attribute decides whether or not that field
    # gets saved if the report is ever converted into a template
    fieldList = {
        'summary': StringField(markdown=True, templatable=True),
    }

    # make sure to specify the HTML template
    htmlTemplate = 'componentTemplates/CustomComponent.html'

    # Font Awesome icon type + color (HTML/CSS)
    # This is just eye candy in the web app
    iconType = 'fas fa-stream'
    iconColor = 'var(--blue)'

    # the "preprocess" function is executed when the report is rendered
    # use this to perform any last-minute operations on its data
    def preprocess(self, context):

        # for example, to uppercase the entire "summary" field:
        #   context['summary'] = context['summary'].upper()
        return context

Nota che i campi devono condividere lo stesso nome sia nella classe del componente che nel suo form. Tutti i componenti devono ereditare da BaseComponent o da un altro componente. Inoltre, ogni componente ha campi predefiniti per name, pageBreakBefore (se iniziare una nuova pagina) e showTitle (se visualizzare il campo name come intestazione). Quindi non è necessario aggiungerli.

componentTemplates/CustomComponent.html:

I campi del modulo Python vengono automaticamente aggiunti al contesto del template. In questo esempio, vogliamo renderizzare il campo summary come markdown, quindi aggiungiamo il tag markdown davanti ad esso. Nota che puoi anche accedere a variabili a livello di engagement e report, come report.name, report.findings, engagement.customer.name, ecc.

{% 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 (opzionale):

Il nome del file deve corrispondere a quello del file Python (ma con estensione .css invece di .py). Viene caricato automaticamente quando il report viene renderizzato.

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

Una volta creati i file sopra, riavvia semplicemente l'app web e il nuovo componente verrà popolato automaticamente.

$ docker-compose restart writehat

Aggiornamento/Migrazione manuale del database

Se viene pubblicato un aggiornamento che modifica lo schema del database, le migrazioni del database Django vengono eseguite automaticamente al riavvio del container. Tuttavia, a volte potrebbe essere richiesta l'interazione dell'utente. Per applicare le migrazioni Django manualmente:

1. Ferma WriteHat (systemctl stop writehat)
2. Entra nella directory di WriteHat (/opt/writehat)
3. Avvia il container docker

$ docker-compose run writehat bash

4. Una volta nel container, applica le migrazioni come di consueto:

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

5. Ferma i container docker e riavvia il servizio

$ docker-compose down
$ systemctl start writehat

Backup/Ripristino manuale del database

Nota che esiste già una funzionalità integrata nell'app per questo nella pagina /admin dell'app web. Puoi usare questo metodo se vuoi creare un backup a livello di file tramite cron, ecc.

1. Sul sistema di destinazione:
   • Segui i normali passaggi di installazione
   • Ferma WriteHat (systemctl stop writehat)
2. Sul sistema di origine:
   • Ferma WriteHat (systemctl stop writehat)
3. Crea un archivio TAR delle directory mysql, mongo e writehat/migrations e copia l'archivio sul sistema di destinazione (stessa posizione):

# DEVE ESSERE ESEGUITO COME ROOT
$ sudo tar --same-owner -cvzpf db_backup.tar.gz mongo mysql writehat/migrations

4. Sul sistema di destinazione, crea un backup della directory migrations

$ mv writehat/migrations writehat/migrations.bak

5. Estrai l'archivio TAR sul sistema di destinazione

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

6. Avvia WriteHat sul nuovo sistema

$ systemctl start writehat

Roadmap / Potenziali sviluppi futuri:

• Tracciamento delle modifiche e revisioni
• Funzionalità di revisione/feedback più approfondita
• Modifica collaborativa multi-utente simile a Google Docs
• Funzionalità di esportazione JSON
• Generazione di diapositive per presentazioni
• Creatore di tabelle più avanzato con funzionalità di caricamento CSV
• Permessi / ACL più granulari (oltre ai soli ruoli utente e amministratore)

Bug noti / Limitazioni:

• Chrome o Chromium è il browser consigliato. Gli altri non sono testati e potrebbero presentare bug.
• Il campo "Assegnatario" sui componenti del report funziona solo con utenti LDAP, non con quelli locali.
• Le annotazioni sulle immagini a volte si spostano leggermente quando vengono applicate. È un bug noto che stiamo monitorando con la libreria JS: https://github.com/ailon/markerjs/issues/40
• Bug visivi compaiono occasionalmente sulle interruzioni di pagina. Questi possono essere risolti inserendo manualmente un'interruzione di pagina nel markdown interessato (c'è un pulsante per questo nell'editor).