Cómo escribir informes técnicos y no morir en el intento (III)

Consejos de redacción

El corrector ortográfico no cuesta dinero

Tenemos que reconocer que da un poco de vergüenza tener que poner este consejo, pero la cruda realidad obliga: pasar el corrector ortográfico es OBLIGATORIO en todo documento sobre el que tengáis la mínima autoría.

Hay pocas cosas que destruyan más rápidamente un informe que ver un “vamos haber las fases” o un “llendo a las conclusiones”. Pasar un corrector ortográfico cuesta muy poco y te puede salvar de fallos épicos.

Uno de los problemas cuando escribimos informes técnicos reside en que el procesador de texto no reconoce nuestra terminología (ni tampoco los términos en inglés). Un consejo muy interesante es el de ir añadiendo poco a poco estas palabras al diccionario personal de vuestro usuario, de modo que no se vuelvan a mostrar en siguientes ocasiones. De esta forma, cualquier falta de ortografía saltará a la vista y será más fácil de corregir.

Consejo 12: Guarda 10 minutos para pasar el corrector ortográfico. Hazlo SIEMPRE.

Cuidado con las frases largas

Otro de los problemas principales que solemos encontrar en la lectura de informes técnicos es la longitud de las frases. Hemos encontrado en más de una ocasión frases de 8 líneas cuya digestión era peor que la de un cachopo de kilo y medio.

Veamos un ejemplo ficticio (pero muy parecido a la realidad):

Los atacantes emplearon un ataque de spear-phishing contra varios altos cargos de la Organización con un documento malicioso que cuando se abría solicitaba la activación de macros y al aceptarse lanzaba un Powershell que contactaba con el C2 y se descarga la siguiente fase del malware que intentaba robar credenciales, se instalaba como servicio e intentaba escalar privilegios con la vulnerabilidad CVE-2019-001.

La solución mágica en muchos casos es el uso indiscriminado de comas. Una “mejora” del ejemplo anterior:

Los atacantes emplearon un ataque de spear-phishing contra varios altos cargos de la Organización, con un documento malicioso que cuando se abría solicitaba la activación de macros, y al aceptarse lanzaba un Powershell, que contactaba con el C2 y se descarga la siguiente fase del malware, que intentaba robar credenciales, se instalaba como servicio e intentaba escalar privilegios, con la vulnerabilidad CVE-2019-001.

Cada vez que tenemos que corregir alguno de estos, el consejo es el mismo: coge aliento e intenta decir esta frase de un tirón. En cuanto se dan cuenta de que en muchos casos es imposible, se vuelven conscientes del exceso cometido. Mano de santo, oiga.

La solución es muy simple: cualquier frase que no puedas decir sin respirar tiene que ser dividida en dos o más frases (en realidad, tendrías que tener una buena excusa para una frase de más de tres líneas). Veamos el ejemplo inicial dignamente redactado:

Los atacantes emplearon un ataque de spear-phishing contra varios altos cargos de la Organización. El correo contenía un documento malicioso que cuando se abría solicitaba la activación de macros y al aceptarse lanzaba un Powershell que contactaba con el C2. En ese momento se descarga la siguiente fase del malware que intentaba robar credenciales, se instalaba como servicio e intentaba escalar privilegios con la vulnerabilidad CVE-2019-001.

Una frase de 5 líneas ha sido dividida en 3 frases más cortas, incrementando su legibilidad. Con un poco de práctica esta técnica se pone en marcha sola y hará que vuestros informes sean mucho más fáciles de leer y entender.

Consejo 13: Escribe lo que puedas decir sin respirar. Parte en dos las frases largas.

No escatimes con los párrafos

Junto con los dos anteriores, el problema de los párrafos conforma la “Santísima Trinidad” de los principales problemas sobre cómo redactar informes técnicos. Imaginemos un poco más de texto del ejemplo anterior.

Los atacantes emplearon un ataque de spear-phishing contra varios altos cargos de la Organización. El correo contenía un documento malicioso que cuando se abría solicitaba la activación de macros y al aceptarse lanzaba un Powershell que contactaba con el C2. En ese momento se descarga la siguiente fase del malware que intentaba robar credenciales, se instalaba como servicio e intentaba escalar privilegios con la vulnerabilidad CVE-2019-001. A lo largo de dos meses los atacantes lograron infectar 12 equipos de la red de la Organización, logrando acceder al servidor de bases de datos MENGANITA y descargando los contenidos de las tablas X, Y y Z. El ataque fue detectado cuando un administrador de sistemas vio una sesión iniciada por un usuario que en este momento estaba de vacaciones, alertando al equipo de seguridad. Los analistas de seguridad verificaron que se trataba de un incidente de seguridad y recabaron información volátil del servidor, procediendo a su análisis.

Aquí tenéis lo que denominamos cariñosamente un “ladrillito”. Tener tantas líneas en un solo bloque de texto dificulta la legibilidad y hace muy fácil perderse, haciendo la lectura del mismo farragosa (algo que en textos online se hace incluso más gravoso).

La solución es partir cada idea en un párrafo (o incluso una misma idea en varios párrafos). Una guía podría ser no tener párrafos de más de 6-8 líneas. Veamos una versión nueva del ejemplo:

Los atacantes emplearon un ataque de spear-phishing contra varios altos cargos de la Organización. El correo contenía un documento malicioso que cuando se abría solicitaba la activación de macros y al aceptarse lanzaba un Powershell que contactaba con el C2.

En ese momento se descarga la siguiente fase del malware que intentaba robar credenciales, se instalaba como servicio e intentaba escalar privilegios con la vulnerabilidad CVE-2019-001.

A lo largo de dos meses los atacantes lograron infectar 12 equipos de la red de la Organización, logrando acceder al servidor de bases de datos MENGANITA y descargando los contenidos de las tablas X, Y y Z.

El ataque fue detectado cuando un administrador de sistemas vio una sesión iniciada por un usuario que en este momento estaba de vacaciones, alertando al equipo de seguridad. Los analistas de seguridad verificaron que se trataba de un incidente de seguridad y recabaron información volátil del servidor, procediendo a su análisis.

Si os dais cuenta, el texto se ha dividido en cuatro párrafos, cada uno con un concepto (intrusión, acciones de los atacantes y detección), y es claramente de mejor lectura.

Consejo 14: Divide los bloques de texto con párrafos para que no ocupen más de 6-8 líneas.

Elige usar voz pasiva o activa

Este consejo tiene un poco de controversia, ya que existen dos (por así decirlo) corrientes: los defensores de la voz pasiva y los de la voz activa. No quedamos para pegarnos ni estigmatizamos a los contrarios, así que siéntete libre de usar la que te parezca más cómoda.

Para que veas cómo queda vamos a poner tres ejemplos:

Yo revisé los logs del servidor MENGANITA y encontré una serie de accesos inapropiados. Yo realicé un análisis de los accesos y determiné que el primero de ellos se había realizado el 13 de enero a las 15:25h. Yo busqué un listado completo de los accesos y comprobé que se habían realizado 5 accesos entre el 13 y el 15 de enero.

Este primer ejemplo es muy “yo, yo, yo” … lo cual nunca queda bien en un informe. Vamos a volver a redactarlo en tercera persona:

El analista revisó los logs del servidor MENGANITA y encontró una serie de accesos inapropiados. El analista realizó un análisis de los accesos y determinó que el primero de ellos se había realizado el 13 de enero a las 15:25h. El analista buscó un listado completo de los accesos y comprobó que se habían realizado 5 accesos entre el 13 y el 15 de enero.

Un poco mejor, ¿verdad? Vamos a ver ahora si cambiamos a voz pasiva:

Se revisaron los logs del servidor MENGANITA se encontraron una serie de accesos inapropiados. Se realizó un análisis de los accesos y se determinó que el primero de ellos se había realizado el 13 de enero a las 15:25h. Se buscó un listado completo de los accesos y se pudo comprobar que se habían realizado 5 accesos entre el 13 y el 15 de enero.

La tercera opción es la que queda más profesional (todo es cuestión de gustos, ojo), pero la segunda también me parece válida. Lo que sí que es obligatorio es mantener la consistencia: elige la que mejor te parezca, pero mantenla a lo largo del documento.

Consejo 15: Elige el estilo que te parezca mejor, y mantenlo a lo largo del documento.

Usa los tipos de letra con sabiduría

Puedes usar cualquier tipo de letra a la hora de redactar tu informe (excepto Comic Sans, por razones obvias), siempre y cuando tenga una buena legibilidad y ayude a que el texto quede limpio. Eso sí, una vez te decidas por un tipo de letra haz uso del mismo en todo el documento: el tener varios tipos de letra en un mismo texto le dan aspecto de “pastiche”, de copia/pega que hace que quede poco profesional.

En Windows un tipo de letra muy recomendable es Open Sans Light, pero Calibri (la que usa por defecto las versiones nuevas de Office) es bastante limpia. En Linux Liberation Sans/Serif siempre dan buenos resultados, aunque al final es cuestión de gustos :D

Otra cosa a tener en cuenta es que los tipos de letra te pueden ayudar a hacer tu texto más fácil de leer a través de un uso juicioso de las negritas y las cursivas. Una técnica frecuente es emplear las negritas para dar énfasis a palabras clave dentro de un párrafo, y las cursivas para todo lo que sean evidencias.

Ejemplo:

Los atacantes lanzaron un ataque de spear-phishing contra varios altos cargos de la Organización. El correo contenía un documento malicioso que cuando se abría solicitaba la activación de macros y al aceptarse lanzaba un Powershell que contactaba con el C2. En ese momento se descarga la siguiente fase del malware que intentaba robar credenciales, se instalaba como servicio e intentaba escalar privilegios con la vulnerabilidad CVE-2019-001.

A lo largo de dos meses los atacantes lograron infectar 12 equipos de la red de la Organización, logrando acceder al servidor de bases de datos MENGANITA y descargando los contenidos de las tablas X, Y y Z.

Logs de acceso de los atacantes a la base de datos:

Jan 13 15:24 Session started for user pepito1
Jan 13 15:25 Database X dump command started
Jan 13 15:37 Database X dump command finished
Jan 13 15:44 Dump command transferred to computer PC1
Jan 13 15:45 Session closed for user pepito1

El ataque fue detectado cuando un administrador de sistemas observó una sesión iniciada por un usuario que en este momento estaba de vacaciones, alertando al equipo de seguridad. Los analistas de seguridad verificaron que se trataba de un incidente de seguridad y recabaron información volátil del servidor, procediendo a su análisis.

Si os fijáis con cuidado, los ojos parecen fijarse con más detalle en las palabras en negrita, que actúan como “anclas” y hacen de resumen del texto, incrementando la comprensión del mismo. De la misma forma, las cursivas “restan” importancia al texto, haciendo que nos fijemos menos (para así solo hacerlo si estamos interesados).

Consejo 16: Usa un solo tipo de letra. Emplea negritas y cursivas para dar y quitar énfasis.

Usa las sangrías para que tu informe se lea mejor

Las sangrías (de texto, no de vino) son una forma excelente de ayudar a que tu texto se lea mejor, ya que permiten crear pequeñas estructuras de texto. Ya sea mediante el apoyo de listas (que siempre suelen tener una pequeña sangría por defecto), o creando tu propia sangría puedes diferenciar distintos tipos de texto para “romper la monotonía” y mejorar la atención de los lectores.

Si te has ido fijando en el documento, estamos usando la sangría junto con la cursiva con los ejemplos. De esta forma se diferencia claramente un texto de otro, y (creemos) que se mejora la legibilidad.

Consejo 17: Usa siempre las sangrías de las listas, y crea las que necesites (sin excesos).

Usa la terminología adecuada

Como ya has hecho un buen trabajo e identificado la audiencia, ya sabes a quién te estás dirigiendo (o deberías). Aun así, el uso de ATL (Acrónimos de Tres Letras, algo que nos encanta a los que trabajamos en TIC) y de terminología muy técnica tiene que ser usado en su justa medida.

Todo se explica mejor con ejemplos:

El atacante usó un XMAS nmap para detectar el puerto de SIP, empleando a continuación un exploit RCE sobre el Asterisk que le permitió desplegar un listener de Cobalt Strike con comunicación a través de un C2 maleable que se inyectó en el svchost.exe.

Si los lectores tienen un perfil de ciberseguridad es posible que capten todo el mensaje, pero lo más probable es que muchos destinatarios finales tengan dificultades para entenderlo correctamente. No decimos que el informe completo tenga que ser entendido por niños de 6 años, pero es tu trabajo trasmitir el mensaje de la forma más clara posible.

Veamos una versión mejorada:


El atacante realizó un port scanning contra el servidor haciendo uso de la herramienta nmap (con la opción avanzada de XMAS), y detectó que el puerto 5060 estaba abierto (señal de que el servidor podía ofrecer servicios de centralita de VoIP a través del protocolo SIP). A continuación, el atacante ejecutó un exploit RCE (ejecución remota de comandos) contra la centralita Asterisk, logrando desplegar una conexión remota con la herramienta de ataque Cobalt Strike.

Dicha herramienta es capaz de establecer comunicación con su C2 (Command & Control) de forma que ésta sea personalizable (intentando por ejemplo hacerse pasar por un servicio como Dropbox o Spotify). Adicionalmente, se ha detectado que el malware se inyectó dentro del proceso de sistema svchost.exe, posiblemente para pasar desapercibido.

En esta versión estamos siendo bastante explicativos para que veas la diferencia entre una y otra. Encuentra un punto intermedio en el que te encuentres cómodo y te asegures de que no tienes que explicar diez veces tu informe a todo el mundo.

Consejo 18: Usa una terminología adecuada a la audiencia. No abuses de los ATL.

Los gráficos cuestan, pero merecen la pena

Hacer gráficas es algo que a pocos gusta. ¡Es trabajo de diseñadores gráficos! ¡Yo soy programador de Python/Go/Rust/C++++, no de Excel! ¡Eso es para consultores! Estas son frases que solemos escuchar cuando le decimos a alguien “esto mejor explícalo con una gráfica”.

Las gráficas tienen su coste (sobre todo para que queden apañadas), pero tienen un poder innegable para transmitir información. Todavía seguimos enamorados de la gráfica de 7 dimensiones del genio de la visualización Hans Rosling, una maravilla de la condensación de la información conjugado con una claridad absoluta.

Como muestra, dos ejemplos del poder de las gráficas:

  • A la hora de presentar los resultados de una auditoria de seguridad (da igual que sea un análisis de vulnerabilidades o un pentesting), haz un listado de los sistemas y de las vulnerabilidades encontradas clasificadas por gravedad. Presenta esta información en un gráfico X/Y (un eje para los sistemas y otro para las vulnerabilidades) marcando en rojo/amarillo/verde las vulnerabilidades.
    Este gráfico permite a cualquiera que lo vea ver el estado de seguridad de sus sistemas de un solo vistazo (cuánto rojo hay, dónde está concentrado, etc…) y funciona de maravilla.
  • Hace tiempo, en un incidente de seguridad teníamos múltiples accesos sospechosos a varios sistemas. Para ayudarnos a entender a los atacantes hicimos un recuento de las horas a las que se habían conectado (independientemente del sistema afectado), y lo mostramos en una gráfica de barras donde X era la hora de conexión e Y el número de conexiones. Quedó clarísimo que los atacantes se conectaban en un rango horario fijo, lo que fue de gran ayuda a la hora de responder al incidente.

Consejo 19: Las gráficas son poderosas. Úsalas cuando puedas para transmitir tu mensaje.

[Advanced+] Hazte con un libro de estilo

Si ya sabes redactar correctamente un informe, y quieres pasar al siguiente nivel, tienes dos opciones: hazte con un compañero/a de curro talibán ortográfico que te ayude a base de correcciones a mejorar tu forma de escribir (Hola, M.) … o consigue un libro de estilo. Podemos recomendar sin problemas estos dos:

Consejo 20: Hazte con un libro de estilo para mejorar tu técnica de escritura.

Speak Your Mind

*