Technical Documentation (Documentación técnica)
ACCIÓN REQUERIDA (léelo y ejecútalo inmediatamente)
AHORA: Confirma si la tarea actual corresponde al ámbito de este skillAHORA: Lee../tool-index.mdpara verificar la disponibilidad de herramientas y rutas realesSIGUIENTE: Si falta alguna herramienta, llama a bootstrap; no adivines rutasACTÚA: Ve al primer paso del flujo de trabajo y ejecútalo; no te quedes en modo de confirmación
Para guía sobre estilo de escritura, tono y voz, usa Skill(ce:writer) con la persona The Engineer.
Generación de documentos para tareas de seguridad/reversing
Cuando se complete una tarea de reversing, penetración, CTF o análisis de seguridad, este skill genera un documento técnico formal en el directorio del proyecto del usuario.
Cuándo se activa
- Tarea de reversing completada con conclusiones clave (algoritmo recuperado, firma descifrada, bypass encontrado, etc.)
- Prueba de penetración completada, vulnerabilidad descubierta y verificada
- CTF resuelto, flag obtenido
- El usuario pide explícitamente "un informe/documento/writeup"
Selección de plantilla
| Tipo de tarea | Plantilla a usar |
|---|---|
| Reversing de APK/binario/so | references/security-report-templates.md → Informe de reversing |
| Penetración / Bug bounty | references/security-report-templates.md → Informe de pentest |
| Solución de CTF | references/security-report-templates.md → CTF Writeup |
| Reversing de firma JS/Web | references/security-report-templates.md → Informe de reversing de firma |
| Malware / APT / Análisis de virus | references/security-report-templates.md + references/vendor-report-rules.md |
| Documentación técnica general | references/templates.md → README / Documentación de API |
Estructura de informe de proveedor (Issue #65)
Los informes de seguridad formales DEBEN leer references/vendor-report-rules.md (solo la estructura, no copiar el texto original del proveedor). Solo se elige el flavor del proveedor cuando la evidencia de la tarea o el usuario lo solicite explícitamente; para reversing normal y otras tareas se usa flavor = null.
| Flavor / Overlay | Cuándo usarlo | Esqueleto de referencia principal |
|---|---|---|
malware | Muestras claramente maliciosas, troyanos, white+black, phishing con veneno | Estilo Huorong: Resumen → Flujo → Análisis de muestra → Respuesta a incidentes → IOC |
apt | APT/campañas/grupos/cadena de infección multi-etapa/objetivo sectorial | Estilo Kaspersky Securelist: Resumen → Cadena de infección → Narrativa de investigación → Hallazgos interesantes → Análisis técnico → Detección y mitigación → IOC |
flavor = null | Reversing normal de APK/ELF/PE/Mach-O, análisis de algoritmo/firmware, pentest / CTF / firma JS | Plantilla original de la tarea + elementos base genéricos; no se agregan capítulos específicos de malware/APT |
thin vuln | El usuario solicita explícitamente análisis técnico de vulnerabilidad/parche/CVE | Resumen → Impacto/Reproducción → Análisis del crash y del parche → Recomendaciones de protección (superpuesto sobre null, no es un tercer flavor de texto completo por defecto) |
Principio: menos es más en plantillas — solo 2 flavors de proveedor de texto completo; vuln es solo un overlay opcional, no se crea un tercer conjunto de plantillas completas por defecto.
Cumple simultáneamente con §0 Evidence → Finding → Path; en caso de conflicto, el contrato Evidence tiene prioridad.
Especificaciones de salida
- Ubicación: Directorio actual del proyecto del usuario (no el directorio del paquete del skill)
- Formato del nombre:
YYYY-MM-DD_[tipo]-[abreviatura-objetivo]-report.md - Si el proyecto tiene directorio
docs/: Se coloca preferentemente dentro dedocs/ - Codificación: UTF-8
- Idioma: Sigue el idioma de la conversación del usuario (chino → informe en chino, inglés → informe en inglés)
Requisitos de calidad
- Todos los bloques de código deben ser ejecutables o tener contexto claro
- Sin marcadores de posición ni TODOs
- Los hallazgos clave deben estar respaldados por evidencia
- Los pasos de reproducción deben permitir que un tercero replique el resultado de forma independiente
- La información sensible (tokens reales, contraseñas, URLs internas) debe reemplazarse con marcadores de posición
- DEBE incluir la cadena Evidence → Finding → Path (ver
../ops/evidence-finding-path.mdy la plantilla §0) - DEBE leer
references/vendor-report-rules.md: seleccionarmalware/aptoflavor = null(las tareas de vulnerabilidad pueden superponer thinvuln); sin flavor solo se genera la plantilla original de la tarea y los elementos Base aplicables, sin forzar IOC/ATT&CK - DEBERÍA referenciar el caso
scope.md/timeline.md(../scripts/case-init.ps1)
Integración de diagramas
Al generar el informe, se debe llamar al skill diagram-generator en las secciones adecuadas para crear diagramas visuales:
| Tipo de informe | Diagramas sugeridos | Tipo de diagrama |
|---|---|---|
| Informe de reversing | Diagrama de llamadas a funciones, diagrama de flujo de datos | Mermaid flowchart / sequenceDiagram |
| Informe de pentest | Diagrama de ruta de ataque, topología de red | Mermaid flowchart / Graphviz |
| CTF Writeup | Diagrama de flujo de la solución | Mermaid flowchart |
| Informe de reversing de firma JS | Diagrama de secuencia de solicitud, diagrama de flujo del algoritmo | Mermaid sequenceDiagram / flowchart |
Los diagramas se incrustan en el informe como bloques de código Mermaid, asegurando que se rendericen directamente en GitHub/GitLab.
Principios fundamentales
1. Divulgación progresiva
Revela la información en capas:
| Capa | Contenido | Pregunta del usuario |
|---|---|---|
| 1 | Descripción en una frase | ¿Qué es? |
| 2 | Bloque de código de inicio rápido | ¿Cómo lo uso? |
| 3 | Referencia completa de la API | ¿Qué opciones tengo? |
| 4 | Inmersión en la arquitectura | ¿Cómo funciona? |
Las advertencias, cambios importantes y requisitos previos van al PRINCIPIO.
2. Escritura orientada a tareas
<!-- Mal: Orientado a características -->
## Clase AuthService
La clase AuthService proporciona métodos de autenticación...
<!-- Bien: Orientado a tareas -->
## Autenticación de usuarios
Para autenticar a un usuario, llama a login() con las credenciales:
3. Muestra, no solo digas
Cada concepto necesita un ejemplo concreto.
Estándares de formato
- Encabezados en minúscula: "Getting started" no "Getting Started"
- Máximo 3 niveles de encabezado: Más profundidad significa dividir el documento
- Especifica siempre el idioma en los bloques de código
- Rutas relativas para enlaces internos
- Tablas para datos estructurados con 3+ atributos
Lista de verificación de calidad
- Ejemplos de código probados y ejecutables
- Sin texto de marcador de posición ni TODOs
- Coincide con el comportamiento real del código
- Escaneable sin leer todo
- El lector sabe qué hacer a continuación
Anti-patrones
| Problema | Solución |
|---|---|
| Muro de texto | Divide con encabezados, viñetas, código, tablas |
| Información crítica enterrada | Advertencias/cambios importantes al PRINCIPIO |
| Falta documentación de errores | Documenta siempre lo que puede fallar |
Plantillas
Para plantillas de README, endpoint de API y organización de archivos, consulta references/templates.md.
Skills relacionados
Skill(ce:writer)— Estilo de escritura, tono y voz (carga la persona The Engineer)Skill(ce:visualizing-with-mermaid)— Diagramas de arquitectura y flujo
Autoarranque bajo demanda (On-Demand Bootstrap)
Este skill no depende de herramientas externas, solo genera texto. No necesita bootstrap.
Si es necesario renderizar diagramas para incrustarlos en el informe, se llamará al skill diagram-generator/.
Contexto de enrutamiento
Entrada ascendente: Todos los skills de seguridad/reversing llaman automáticamente a este skill al completar la tarea. Modo de activación:
- Automático: Al finalizar la tarea, como paso 9 de la cadena de comportamiento.
- Manual: El usuario dice "escribe informe", "genera documentación", "writeup".
Módulos relacionados del mismo nivel:
apk-reverse/— Genera informe de reversing tras completar el reversing de APKida-reverse/— Genera informe de reversing tras completar el análisis binarioradare2/— Genera informe de reversing tras completar el análisis CLIjs-reverse/— Genera informe de firma tras completar el reversing de firma JSreverse-engineering/— Genera informe de reversing tras completar el reversing generalfield-journal/— El contenido del informe también sirve como fuente de datos para el registro de evolución
Plantilla de informe de seguridad: references/security-report-templates.md
Reglas de informe de proveedor: references/vendor-report-rules.md (flavor: malware | apt | null; overlay opcional: vuln)
Plantilla de documentación general: references/templates.md
Autocomprobación de finalización de tarea (DEBE pasar antes de declarar finalizada)
- ¿Ejecuté cada paso del flujo de trabajo (no solo lo leí)?
- ¿Usé rutas de herramientas reales basadas en
tool-index? - ¿Generé evidencia reproducible (comandos/scripts/capturas de pantalla/informes)?
- ¿El informe contiene Evidence / Finding / Path (contrato ops)?
- ¿Se completaron y documentaron los elementos de la lista de verificación requeridos por RULES?