blacklanternsecurity/writehatUna herramienta de informes de pentest escrita en Python. Libérate de Microsoft Word.
**WriteHat** es una herramienta de informes que elimina Microsoft Word (y muchas horas de sufrimiento) del proceso de generación de informes. **Markdown** --> **HTML** --> **PDF**. Creada por probadores de penetración, para probadores de penetración, pero puede usarse para generar cualquier tipo de informe. Escrito en Django (Python 3).
## Características:
- **Genere sin esfuerzo informes de pentest hermosos**
- **Constructor de informes de arrastrar y soltar sobre la marcha**
- **Soporte de Markdown - incluidos bloques de código, tablas, etc.**
- **Recortar, anotar, subtitular y subir imágenes**
- **Fondo / pie de página personalizable del informe**
- **Asignar operadores y realizar un seguimiento de los estados de secciones individuales del informe**
- **Capacidad de clonar y usar plantillas de informes**
- **Base de datos de hallazgos**
- **Soporta múltiples tipos de puntuación (CVSS 3.1, DREAD)**
- **Puede generar fácilmente múltiples informes a partir del mismo conjunto de hallazgos**
- **El diseño extensible permite a los usuarios avanzados crear secciones de informe altamente personalizadas**
- **Integración LDAP**
## Requisitos previos de instalación:
- Instalar `docker` y `docker-compose`
- Normalmente se pueden instalar usando `apt`, `pacman`, `dnf`, etc.
~~~
$ sudo apt install docker.io docker-compose
~~~
## Desplegar WriteHat (La forma rápida y sencilla, para pruebas):
WriteHat se puede desplegar con un solo comando:
~~~
$ git clone https://github.com/blacklanternsecurity/writehat && cd writehat && docker-compose up
~~~
Inicie sesión en **https://127.0.0.1** (por defecto: **`admin`** / **`PLEASECHANGETHISFORHEAVENSSAKE`**)
## Desplegar WriteHat (La forma correcta):
1. **Instalar Docker y Docker Compose**
1. **Clonar el repositorio de WriteHat** en `/opt`
~~~
$ cd /opt
$ git clone https://github.com/blacklanternsecurity/writehat
$ cd writehat
~~~
1. **Crear contraseñas seguras** en `writehat/config/writehat.conf` para:
- MongoDB (también ingrese en `docker-compose.yml`)
- MySQL (también ingrese en `docker-compose.yml`)
- Django (usado para cifrar cookies, etc.)
- Usuario administrador
Nota: No es necesario modificar nada más aparte de las contraseñas si está usando la configuración predeterminada
Nota: No olvide restringir los permisos en `writehat/config/writehat.conf` y `docker-compose.yml`: (`chown root:root; chmod 600`)
1. **Agregue su nombre de host deseado** a `allowed_hosts` en `writehat/config/writehat.conf`
1. (Opcional) **Reemplace los certificados SSL autofirmados** en `nginx/`:
- `writehat.crt`
- `writehat.key`
1. **Pruebe que todo funcione**:
~~~
$ docker-compose up --build
~~~
Nota: Si está usando una VPN, debe desconectarse de la VPN la primera vez que ejecute los servicios con `docker-compose`. Esto es para que docker pueda crear con éxito la red virtual.
1. **Instale y active el servicio systemd**:
Esto iniciará WriteHat automáticamente al arrancar
~~~
$ sudo cp writehat/config/writehat.service /etc/systemd/system/
$ sudo systemctl enable writehat --now
~~~
1. **Supervise los registros del servicio**:
~~~
$ sudo journalctl -xefu writehat.service
~~~
1. **Cree usuarios**
Navegue a https://127.0.0.1/admin después de iniciar sesión con el usuario administrador especificado en `writehat/config/writehat.conf`
Nota: Hay algunas acciones que solo un administrador puede realizar (por ejemplo, copias de seguridad de la base de datos). Se crea automáticamente un usuario administrador a partir del nombre de usuario y la contraseña en `writehat/config/writehat.conf`, pero también puede promocionar a un usuario LDAP a administrador:
~~~
# Enter the app container
$ docker-compose exec writehat bash
# Promote the user and exit
$ ./manage.py ldap_promote <ldap_username>
$ exit
~~~
## Terminología
Aquí hay explicaciones básicas para algunos términos de **WriteHat** que pueden no ser obvios.
~~~
Engagement
├─ Customer
├─ Finding Group 1
│ ├─ Finding
│ └─ Finding
├─ Finding Group 2
│ ├─ Finding
│ └─ Finding
├─ Report 1
└─ Report 2
└─ Page Template
~~~
### Engagement
Un **Engagement** es donde se crea contenido para el cliente. Aquí es donde ocurre el trabajo: crear informes e ingresar hallazgos.
### Report
Un **Report** es un arreglo modular y jerárquico de **Componentes** que se puede actualizar fácilmente mediante una interfaz de arrastrar y soltar, y luego convertirse en HTML o PDF. Un engagement puede tener múltiples **Reports**. Se puede usar una **Page Template** para personalizar el fondo y el pie de página. Un **Report** también se puede convertir en un **Report Template**.
### Report Component
Un **Componente** de informe es una sección o módulo del informe que se puede arrastrar/soltar en su lugar dentro del creador de informes. Los ejemplos incluyen "Página de título", "Markdown", "Hallazgos", etc. Hay muchos componentes integrados, pero también puede crear los suyos propios. (Son solo HTML/CSS + Python, así que es bastante fácil. Vea la guía a continuación)
### Report Template
Un **Report Template** se puede usar como punto de partida para un **Report** (en un **Engagement**). Los **Reports** también se pueden convertir en **Report Templates**.
### Finding Group
Un **Finding Group** es una colección de hallazgos que se puntúan de la misma manera (por ejemplo, CVSS o DREAD). Puede crear múltiples grupos de hallazgos por engagement (por ejemplo, "Hallazgos Técnicos" y "Hallazgos de Tesorería"). Al insertar los hallazgos en el **Report** (a través del **Componente** "Hallazgos", por ejemplo), debe seleccionar qué **Finding Group** desea poblar ese **Componente**.
### Page Template
Una **Page Template** le permite personalizar las imágenes de fondo y los pies de página del informe. Puede establecer una **Page Template** como predeterminada, y se aplicará globalmente a menos que se anule a nivel de **Engagement** o **Report**.
## Escribir Componentes de Informe Personalizados
Cada componente de informe está compuesto por lo siguiente:
1. Un archivo Python en `writehat/components/`
2. Una plantilla HTML en `writehat/templates/componentTemplates/`
3. Un archivo CSS en `writehat/static/css/component/` (opcional)
Recomendamos consultar los archivos existentes en estos directorios; funcionan bien como puntos de partida / ejemplos.
Un componente personalizado simple se vería así:
### `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
~~~
Tenga en cuenta que los campos *deben* compartir el mismo nombre tanto en la clase del componente como en su formulario. Todos los componentes deben heredar de `BaseComponent` o de otro componente. Además, cada componente tiene campos integrados para `name`, `pageBreakBefore` (si comenzar en una nueva página) y `showTitle` (si mostrar o no el campo `name` como encabezado). Por lo tanto, no es necesario agregarlos.
### `componentTemplates/CustomComponent.html`:
Los campos del módulo Python se agregan automáticamente al contexto de la plantilla. En este ejemplo, queremos renderizar el campo `summary` como markdown, por lo que agregamos la etiqueta `markdown` delante de él. Tenga en cuenta que también puede acceder a variables de nivel de engagement e informe, como `report.name`, `report.findings`, `engagement.customer.name`, etc.
~~~
{% 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` (opcional):
El nombre del archivo debe coincidir con el del archivo Python (pero con extensión `.css` en lugar de `.py`). Se carga automáticamente cuando se renderiza el informe.
~~~
div.custom-component-summary {
font-weight: bold;
}
~~~
Una vez creados los archivos anteriores, simplemente reinicie la aplicación web y el nuevo componente se poblará automáticamente.
~~~
$ docker-compose restart writehat
~~~
## Actualización/Migración Manual de la BD
Si se envía una actualización que cambia el esquema de la base de datos, las migraciones de la base de datos de Django se ejecutan automáticamente cuando se reinicia el contenedor. Sin embargo, a veces puede ser necesaria la interacción del usuario.
Para aplicar migraciones de Django manualmente:
1. Detenga WriteHat (`systemctl stop writehat`)
2. Cambie al directorio de WriteHat (`/opt/writehat`)
3. Inicie el contenedor docker
~~~
$ docker-compose run writehat bash
~~~
4. Una vez en el contenedor, aplique las migraciones como de costumbre:
~~~
$ ./manage.py makemigrations
$ ./manage.py migrate
$ exit
~~~
5. Detenga los contenedores docker y reinicie el servicio
~~~
$ docker-compose down
$ systemctl start writehat
~~~
## Copia de seguridad/Restauración Manual de la BD
Tenga en cuenta que ya hay funcionalidad dentro de la aplicación para esto en la página `/admin` de la aplicación web. Puede usar este método si desea realizar un trabajo de copia de seguridad a nivel de archivos mediante `cron`, etc.
1. En el sistema de destino:
- Siga los pasos normales de instalación
- Detenga WriteHat (`systemctl stop writehat`)
2. En el sistema de origen:
- Detenga WriteHat (`systemctl stop writehat`)
3. Empaquete en TAR los directorios `mysql`, `mongo` y `writehat/migrations` y copie el archivo al sistema de destino (misma ubicación):
~~~
# MUST RUN AS ROOT
$ sudo tar --same-owner -cvzpf db_backup.tar.gz mongo mysql writehat/migrations
~~~
4. En el sistema de destino, haga una copia de seguridad del directorio `migrations`
~~~
$ mv writehat/migrations writehat/migrations.bak
~~~
5. Extraiga el archivo TAR en el destino
~~~
$ sudo tar --same-owner -xvpzf db_backup.tar.gz
~~~
6. Inicie WriteHat en el nuevo sistema
~~~
$ systemctl start writehat
~~~
## Hoja de ruta / *Posibles* desarrollos futuros:
- Seguimiento de cambios y revisiones
- Funcionalidad de revisión/retroalimentación más detallada
- Edición colaborativa multiusuario similar a Google Docs
- Función de exportación JSON
- Generación de diapositivas de presentación
- Creador de tablas más avanzado con función de carga CSV
- Permisos/ACL más granulares (más allá de solo roles de usuario y administrador)
## Errores conocidos / Limitaciones:
- Chrome o Chromium es el navegador recomendado. Otros no han sido probados y pueden experimentar errores.
- El campo "Asignado" en los componentes del informe solo funciona con usuarios LDAP, no con locales.
- Las anotaciones en imágenes a veces saltan ligeramente cuando se aplican. Es un error conocido que estamos rastreando con la librería JS: https://github.com/ailon/markerjs/issues/40
- Aparecen errores visuales ocasionalmente en los saltos de página. Estos se pueden solucionar insertando manualmente un salto de página en el markdown afectado (hay un botón para ello en el editor).