REPLAY["DIRTY-HIVE REPLAY<br/>transaction logs applied to a working copy"]
PARSERS["ARTIFACT PARSERS<br/>18 artifact types · live and offline"]

OUT["LIVING REPORT<br/>CSV · JSON · HTML"]

I1 --> PARSERS
I2 --> PARSERS
I3 --> PARSERS

PARSERS -- "every registry hive,<br/>evidence never written to" --> REPLAY
REPLAY -- "the state Windows<br/>had not finished writing" --> PARSERS

PARSERS -- "parsed artifacts" --> CASE
I4 -- "verbatim copy or<br/>converted to feather" --> CASE

CASE -- "read-only" --> TL
CASE -- "read-only" --> UB
CASE -- "read-only" --> CE
CASE -- "read-only" --> DL
CE --> RES
DL --> INTEL

CASE -- "read-only queries" --> EYE
RES -. "queried on demand" .-> EYE
EYE <== "verdict · narrative · evidence" ==> NM

EYE -- "audited by" --> COMP

EYE -- "report_* tools" --> OUT

class S1,S2,S3,S4 src
class I1,I2,I3,I4,PARSERS ing
class CASE,RES,INTEL store
class TL,UB,CE,DL ana
class EYE,NM,COMP ai
class OUT out

linkStyle default stroke-width:2px

*Fuente de evidencia → Ingesta → Bases de datos del caso → Análisis → Capa de IA → Informe*


**Cómo leerlo:**

| Etapa | Qué importa |
|---|---|
| ① → ② | **Cuatro puertas independientes hacia un caso.** Nunca necesitas el recolector propio de Crow-Eye — una carpeta de Velociraptor, KAPE o un paquete de EDR pasa por el Importador Offline, y CSV/JSON/SQLite de terceros pasa por Importar Evidencia. |
| ② → ③ | Todo converge en un solo lugar: **las bases de datos del caso**. Los artefactos analizados se guardan en `Target_Artifacts/`; la evidencia importada de terceros se guarda en `Imported_Evidence/` y se descubre automáticamente. |
| ③ → ④ | **Las tres rutas de análisis son independientes entre sí.** La Línea de Tiempo y el UBA leen las bases de datos del caso directamente — ninguna requiere una ejecución de correlación. El Motor de Correlación es una capa *adicional*, no un requisito previo. |
| ③ → ④ | **El Enlace Dinámico se sitúa junto a la Línea de Tiempo y el UBA** — un cuarto lector independiente de las bases de datos del caso (no tiene nada que ver con la visualización de la Línea de Tiempo). Reúne mapeos de identidad (SID → nombre de usuario, MAC → red, hash/GUID → aplicación) en una `Crow_Intelligence.db` por caso, y luego superpone ese contexto **en línea en las tablas de datos de artefactos** mediante `ATTACH` + `LEFT JOIN` no destructivos. Cambia cómo *se leen* los registros, nunca la evidencia. |
| ④ → ⑤ | El Eye consulta las bases de datos del caso directamente y puede extraer resultados de correlación **bajo demanda**. Nunca toca la evidencia en sí — emite llamadas a herramientas que Crow-Eye ejecuta y registra. |
| ⑤ → Informe | El **Informe Vivo lo construye únicamente el Eye**, a través de sus herramientas `report_*`. La Línea de Tiempo y el UBA son superficies de análisis — no escriben en el informe. Los hallazgos a nivel de caso aún pueden exportarse por separado mediante [Buscar y Exportar](#-buscar--exportar). |
| ⑤ ↔ | El **Mapa Narrativo es bidireccional**: el Eye escribe en él, tú escribes en él, y su contenido se inyecta en el prompt del Eye en cada turno. Es la memoria, y puedes comandarlo. |
| ⑤ ⟳ | La **página de Cumplimiento audita al Eye.** Cada llamada a herramienta que hace el Eye está anclada a la cadena de hash **EvidenceSeal**; la página muestra el estado **GEP** en vivo por regla (10 principios) verificado desde esa cadena y `EYE_Logs/`, exportable como `audit_trail.json`. |

**Etapas independientes.** La Línea de Tiempo y el UBA leen las bases de datos de artefactos del caso **directamente** — ninguna requiere una ejecución de correlación, y la Línea de Tiempo no depende del Motor de Correlación (aplica su propio agrupamiento temporal ligero). La correlación es una capa de análisis adicional cuyos resultados el Eye puede consultar.

**Solo lectura por diseño.** El análisis escribe en la base de datos del caso; cada etapa posterior (UBA, la Línea de Tiempo, los visores de correlación, el Eye) abre esas bases de datos **en modo solo lectura**. La evidencia original nunca se modifica — el [Enlace Dinámico](#-modos-de-análisis) lee las bases de datos del caso para construir una `Crow_Intelligence.db` por caso con mapeos de identidad y enriquece las tablas de datos de artefactos en línea mediante consultas `ATTACH` + `LEFT JOIN` no destructivas en lugar de reescribir filas.

**Gobernado por diseño.** Cada acción que toma el Eye está anclada a la cadena de hash **EvidenceSeal** a prueba de manipulación, y la página de **Cumplimiento** verifica continuamente al Eye contra el [Protocolo Ghassan Elsman (GEP)](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/docs/GEP_standard.md) — estado en vivo por regla, exportable a `EYE_Logs/audit_trail.json`.

## 📥 Descargar e Instalar

> **Recomendado:** obtén la compilación de Windows empaquetada (**instalador MSI / EXE**) desde el sitio web oficial — sin configuración de Python, funciona directamente.

### ▶️ [Descargar Crow-Eye para Windows → crow-eye.com/download](https://crow-eye.com/download)

La **compilación MSI/EXE instalada es la forma recomendada de ejecutar Crow-Eye**, y es nuestra **máxima prioridad para actualizaciones**:

- 🛡️ **Correcciones más rápidas.** Cuando se encuentra un problema o se reporta un error, publicamos un EXE actualizado **lo antes posible** — la compilación empaquetada es donde llegan primero las correcciones.
- 🔄 **Actualización automática integrada.** En la aplicación instalada, abre **Configuración → Actualizaciones** para **buscar actualizaciones e instalarlas automáticamente** — sin reinstalación manual.
- 📦 **Cero configuración.** No se requiere instalación de Python, Node ni dependencias.

> ¿Prefieres ejecutar desde el código fuente? Consulta **[Inicio Rápido](#-inicio-rápido)** más abajo. La compilación desde el código fuente está pensada para colaboradores y **no incluye el actualizador automático** — usa el MSI/EXE para actualizaciones automáticas.

## 🚀 Inicio Rápido

### Opción A — Compilación instalada (recomendada)
Descarga el **MSI/EXE** desde [crow-eye.com/download](https://crow-eye.com/download), instálalo e inicia **Crow-Eye** como Administrador. Crea un caso y comienza a analizar.

### Opción B — Ejecutar desde el código fuente (desarrolladores)

> Para colaboradores y usuarios avanzados. Esta ruta **no incluye el actualizador automático** — usa el MSI/EXE para actualizaciones automáticas.

**Requisitos** (se instalan automáticamente en el primer inicio):
- Python 3.12.4
- **Node.js y npm** — necesarios para la **Visualización de la Línea de Tiempo**
- Paquetes clave: PyQt5, python-registry, pywin32, pandas, streamlit, altair, olefile, windowsprefetch, sqlite3, colorama, setuptools

**Hardware recomendado**

| | Mínimo | Recomendado para casos grandes |
|---|---|---|
| **RAM** | 8 GB | 16 GB+ (conjuntos MFT/USN de millones de registros) |
| **Disco** | 5 GB libres | Espacio libre ≥ 2× el tamaño de la evidencia que se analiza |
| **CPU** | 4 núcleos | 8+ núcleos |
| **SO** | Windows 10/11 (completo) · Linux (análisis offline y de imágenes) | — |

> La correlación se transmite en memoria constante para conjuntos de datos muy grandes, por lo que la RAM rara vez es el límite estricto — el rendimiento del disco y el espacio libre suelen serlo.

**Inicio** (ejecuta como Administrador para que Crow-Eye pueda acceder a los artefactos del sistema):```bash
python "Crow Eye.py"

**Formatos de importación compatibles:** CSV (cualquier archivo con encabezados), JSON (plano o anidado) y SQLite (importación directa). Mapeo automático de columnas, detección de tipos de datos, normalización de marcas de tiempo a ISO, validación e índices optimizados.```
prefetch.db (Feather)
├── feather_metadata (artifact type, source, record count)
├── prefetch_data (executable_name, path, last_executed, hash)
└── Indexes (timestamp, name, path)

#### 3. ⚙️ Motores (Estrategias de Correlación)

**Propósito**: Ejecutar la lógica de correlación para encontrar relaciones entre artefactos. Los vínculos estructurales vienen **primero**; una puntuación ponderada por niveles se superpone como *interpretación/clasificación*, no como base para una coincidencia.

**Motor de Escaneo por Ventana de Tiempo** — ideal para análisis basado en tiempo y correlación temporal sistemática. Escanea a través del tiempo en intervalos fijos, recopila registros de todas las plumas por ventana, aplica coincidencia de campos semánticos + puntuación ponderada y evita duplicados mediante el seguimiento de MatchSet. **O(N log N)** (consultas de marcas de tiempo indexadas); procesamiento por lotes (~2,567 ventanas/segundo).

**Motor de Correlación Basado en Identidad** — ideal para conjuntos de datos grandes (>1,000 registros) y seguimiento de identidades. Extrae y normaliza identidades, agrupa registros por identidad, construye anclas temporales dentro de cada clúster, clasifica la evidencia como primaria/secundaria/de apoyo y transmite conjuntos muy grandes (>5,000 anclas) con memoria constante. **O(N log N)**; más de 40 patrones de campos de identidad por tipo.

**Selección del motor:** use el motor de Ventana de Tiempo para análisis basado en tiempo y el motor Basado en Identidad para seguimiento de identidades — ambos están listos para producción y optimizados para conjuntos de datos grandes con consultas indexadas.

#### 4. 🔄 Pipelines (Orquestación de Flujos de Trabajo)

**Propósito**: Automatizar flujos de trabajo de análisis completos desde la creación de plumas hasta la generación de resultados. Un pipeline lee su configuración (tipo de motor, alas, plumas), instancia el motor correcto mediante el EngineSelector, ejecuta cada ala, agrega coincidencias, guarda resultados (BD + JSON) y los muestra en la GUI con filtrado y visualización.```json
{
  "pipeline_name": "Investigation Pipeline",
  "engine_type": "identity_based",
  "wings": [{"wing_id": "execution-proof"}, {"wing_id": "file-access"}],
  "feathers": [
    {"feather_id": "prefetch", "database_path": "data/prefetch.db"},
    {"feather_id": "srum", "database_path": "data/srum.db"},
    {"feather_id": "eventlogs", "database_path": "data/eventlogs.db"}
  ],
  "filters": {
    "time_period_start": "2024-01-01T00:00:00",
    "time_period_end": "2024-12-31T23:59:59"
  }
}

### Ejemplo de caso de uso: Encontrar prueba de ejecución

**Escenario**: demostrar que `malware.exe` fue ejecutado en un sistema.```json
{
  "wing_id": "malware-execution",
  "correlation_rules": { "time_window_minutes": 5, "minimum_matches": 2 },
  "feathers": ["prefetch", "shimcache", "amcache"]
}

## Instalación

### Requisitos previos

- Python 3.8 o superior
- pip (gestor de paquetes de Python)
- Acceso a Internet para descargar dependencias

### Instalación desde PyPI

La forma más sencilla de instalar la herramienta es mediante pip:

```bash
pip install kitploit-tool

git clone https://github.com/example/kitploit-tool.git
cd kitploit-tool
pip install -r requirements.txt
python setup.py install

kitploit-tool --version

Kitploit Tool v1.2.3

kitploit-tool -t https://example.com

kitploit-tool -t https://example.com,https://example.org

kitploit-tool -l objetivos.txt

kitploit-tool -t https://example.com -o resultados.json
kitploit-tool -t https://example.com -o resultados.html
kitploit-tool -t https://example.com -o resultados.txt

kitploit-tool -t https://example.com -v

kitploit-tool -t https://example.com -vv

# Configuración de Kitploit Tool
timeout: 30
user_agent: "Kitploit-Tool/1.0"
proxy:
  http: "http://proxy.example.com:8080"
  https: "https://proxy.example.com:8080"

export KITPLOIT_TIMEOUT=30
export KITPLOIT_USER_AGENT="Kitploit-Tool/1.0"
export KITPLOIT_PROXY="http://proxy.example.com:8080"

from correlation_engine.pipeline import PipelineExecutor
executor = PipelineExecutor(pipeline_config)
results = executor.execute()
```
I need the actual content of chunk 20 to translate it. Please provide the Markdown text you want translated.```
Identity: malware.exe
  Anchor 1 (2024-01-15 10:30:00):
    ✓ Prefetch: malware.exe executed at 10:30:00
    ✓ ShimCache: malware.exe modified at 10:30:15
    ✓ AmCache:  malware.exe installed at 10:29:45

  Conclusion: Execution proven with 3 corroborating artifacts
```
### Puntos de Referencia de Rendimiento

| Registros | Motor de Ventana Temporal | Motor Basado en Identidad |
|---|---|---|
| 1.000 | 0,5 s | 2 s |
| 10.000 | 5 s | 15 s |
| 100.000 | 50 s | 2,5 min (streaming) |
| 1.000.000 | — | 25 min (streaming) |

### Primeros Pasos con el Motor de Correlación

1. **Inicio**: `python -m correlation_engine.main`
2. **Crear Feathers**: importa tus artefactos forenses (Prefetch, ShimCache, …).
3. **Crear Wings**: define reglas de correlación para tu investigación.
4. **Crear un Pipeline**: configura qué wings y feathers usar.
5. **Ejecutar**: ejecuta el pipeline y visualiza los resultados correlacionados.
6. **Analizar**: usa el Visor de Resultados para explorar relaciones temporales.

### 📚 Documentación del Motor de Correlación

- **[Descripción General del Motor de Correlación](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/CORRELATION_ENGINE_OVERVIEW.md)** — descripción general del sistema con diagramas de arquitectura
- **[Documentación del Motor](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/engine/ENGINE_DOCUMENTATION.md)** — arquitectura de doble motor, selección de motor, optimización de rendimiento
- **[Arquitectura](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/ARCHITECTURE.md)** — integración de componentes y flujo de datos
- **[Documentación de Feather](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/feather/FEATHER_DOCUMENTATION.md)** — el sistema de normalización de datos
- **[Documentación de Wings](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/wings/WINGS_DOCUMENTATION.md)** — reglas de correlación
- **[Documentación del Pipeline](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/pipeline/PIPELINE_DOCUMENTATION.md)** — orquestación del flujo de trabajo
- **[Añadir un Artefacto](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/ADDING_AN_ARTIFACT.md)** — el flujo de trabajo para conectar un nuevo analizador al motor
- **[Registro de Campos Estándar](https://github.com/ghassan-elsman/crow-eye/blob/main/config/standard_fields)** — sinónimos canónicos de nombres de columnas cargados por ambos motores y el Eye
- **[Guía de Contribución](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/CONTRIBUTING.md)** — cómo contribuir al motor
- Enlaces rápidos: [Selección de Motor](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/engine/ENGINE_DOCUMENTATION.md#engine-selection-guide) · [Solución de Problemas](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/engine/ENGINE_DOCUMENTATION.md#troubleshooting) · [Optimización de Rendimiento](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/engine/ENGINE_DOCUMENTATION.md#performance-and-optimization)

## 👁️ Eye — El Asistente de IA Forense

> **Un asistente potente, no un sustituto.** Eye automatiza y *verifica* las hipótesis de un investigador — nunca toma la decisión por ti.

**Eye** es el asistente de IA forense integrado de Crow-Eye: un investigador forense experto respaldado por una base de conocimiento real de artefactos de Windows. Te ofrece una interfaz de lenguaje natural para consultar, correlacionar y documentar todo en un caso — Prefetch, MFT, Registro, Registros de Eventos, AmCache, ShimCache, SRUM y más — manteniendo un registro auditable y a prueba de manipulaciones de exactamente lo que hizo. Eye puede ejecutarse completamente en tu propio hardware (incluido **totalmente aislado de la red**), en línea con la postura de privacidad de Crow-Eye de **"0 ms de datos enviados fuera del dispositivo"**. Arquitectura completa: [`eye/README.md`](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/README.md).

| Capacidad | Qué significa para ti |
|---|---|
| **Investigación en lenguaje natural** | Pregunta en inglés sencillo; Eye escribe el SQL y busca por ti. |
| **Integración multi-fuente** | Acceso unificado a todos los artefactos analizados del caso. |
| **Análisis mejorado con RAG** | Eye recupera conocimiento forense específico de artefactos antes de responder. |
| **Espacio de Trabajo de Informe Vivo** | Hallazgos, tablas, gráficos y líneas de tiempo se documentan en tiempo real. |
| **Humano en el circuito** | Las acciones críticas (p. ej., exportación de informes) requieren tu aprobación explícita. |
| **Cadena de custodia** | Prueba criptográfica de exactamente qué analizó el modelo. |

Eye convierte preguntas conversacionales ("muéstrame qué se ejecutó desde `C:\Temp` después de las 22:00") en trabajo forense real: planifica un enfoque, recupera conocimiento relevante de artefactos, ejecuta SQL y búsquedas entre artefactos contra las bases de datos de tu caso, y sintetiza una respuesta validada. Cada respuesta se produce **en dos lugares a la vez** — una respuesta de chat para ti y un bloque estructurado escrito en un **Espacio de Trabajo de Informe Vivo** para que el expediente se construya solo a medida que avanza la investigación.

### El Protocolo Ghassan Elsman (GEP)

Todo lo que hace Eye está anclado al **Protocolo Ghassan Elsman (GEP)** — un estándar **neutral respecto al proveedor e independiente de la herramienta** sobre *cómo debe usarse cualquier IA en la informática forense*. Son **10 principios** que un sistema conforme debe mantener para que los hallazgos asistidos por IA sigan siendo **veraces, trazables hasta los registros fuente y respaldados por una cadena auditable y a prueba de manipulaciones**, con el investigador humano al control:

| # | Principio | En una línea |
|---|---|---|
| **GEP-1** | Primacía de la Evidencia | Las conclusiones provienen solo de artefactos realmente examinados. |
| **GEP-2** | Trazabilidad | Cada hecho se vincula a un registro fuente específico. |
| **GEP-3** | Especificidad y Cronología | Marcas de tiempo UTC exactas, identificadores y rutas, ordenados en el tiempo. |
| **GEP-4** | Corroboración Cruzada | Basarse en múltiples fuentes; informar acuerdos, silencios y conflictos. |
| **GEP-5** | Verificación de Premisas | Tratar las afirmaciones humanas como hipótesis a probar o refutar. |
| **GEP-6** | Integridad | Nunca descartar o truncar evidencia en silencio. |
| **GEP-7** | Integridad y No Repudio | Nunca modificar evidencia; registrar lo visto y hecho, de forma a prueba de manipulaciones. |
| **GEP-8** | Transparencia y Explicabilidad | El razonamiento, las herramientas usadas y los datos vistos son visibles y auditables. |
| **GEP-9** | Autoridad Humana | El investigador decide; las acciones duraderas son atribuibles. |
| **GEP-10** | Defendibilidad | La salida es objetiva, precisa y estructurada para revisión independiente. |

El Eye de Crow-Eye es la **implementación de referencia** del GEP; los comportamientos dentro del producto que lo sostienen son **Reglas Operativas**. 📜 Lee el estándar: [`eye/docs/GEP_standard.md`](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/docs/GEP_standard.md).

### Modos de Despliegue

Eye se adapta a tu modelo de amenazas mediante tres modos de despliegue:

| Modo | Ideal para | Backends |
|---|---|---|
| ☁️ **Modelos de IA en la Nube** | Análisis profundo y complejo con máximo cómputo | OpenAI, Anthropic (Claude), Google Gemini |
| 🔒 **Servidor de IA Offline** (aislado de la red) | Investigaciones con exposición cero, on-premise | Ollama, LM Studio |
| ⚡ **Agentes de Terminal CLI** | Reutilizar un agente de IA de terminal que ya tengas como modelo | Claude Code, Gemini CLI, ChatGPT CLI, llama.cpp, … |

En **modo agente CLI**, Crow-Eye impulsa un **agente de IA de terminal/línea de comandos existente como modelo** — en lugar de una API en la nube o un servidor local offline — para que puedas investigar con el agente que ya usas.

**El bucle de investigación:**

1. **Abrir o crear un caso** — Eye se limita a las bases de datos de artefactos y el historial de ese caso.
2. **Hacer una pregunta** en lenguaje natural, o lanzar un triaje integral con un clic.
3. **Eye ejecuta su pipeline** — detectar intención → recuperar conocimiento → ejecutar herramientas → sintetizar.
4. **Obtienes una salida dual** — una respuesta directa de chat *y* un nuevo bloque en el Informe Vivo.
5. **Aprobar acciones restringidas** — las exportaciones y otros pasos críticos esperan tu visto bueno.

Puedes cambiar de modelo en tiempo de ejecución con la herramienta `switch_model`. El cambio está **restringido al mismo backend**, de modo que la evidencia nunca se envía silenciosamente a un proveedor distinto del que elegiste.

### Rastreo del Proceso de Pensamiento del LLM

Eye está construido para que puedas ver — y luego probar — *cómo* llegó a una conclusión. Mientras Eye trabaja, transmite actualizaciones estructuradas de `ThinkingStep` a la interfaz en tiempo real; cada una lleva un `step_id`, `type`, `label` legible por humanos, `status` (`active` → `done`, o `error`) y `tool`/`params`/`detail` opcionales.

| Tipo de paso | Lo que estás viendo |
|---|---|
| `thinking` | Planificación de Eye — detectar intención forense, construir el prompt del sistema, decidir los siguientes movimientos. |
| `rag` | Eye recuperando conocimiento de artefactos de su base de conocimiento para fundamentar la respuesta. |
| `tool_call` | Eye ejecutando una herramienta forense (una consulta SQL, una búsqueda, una consulta de correlación). |
| `synthesis` | Eye validando y ensamblando la respuesta final respaldada por evidencia. |

Una consulta típica se desarrolla como `thinking → rag → thinking → tool_call → synthesis`, y cada caso conserva artefactos de rastreo en disco que puedes inspeccionar después:

| Archivo | Qué registra |
|---|---|
| `<case>/EYE_Logs/eye_payload_seal.jsonl` | Las cargas útiles exactas enviadas al modelo, encadenadas por hash. |
| `<case>/EYE_Logs/truncation_audit.log` | Qué contexto se mantuvo, resumió, descartó o fijó — y por qué. |
| `<case>/case_history.json` | El historial completo de la conversación, con recuentos de tokens por mensaje. |

### Ejecución de Herramientas

Eye está **impulsado por herramientas**: el modelo nunca toca la evidencia directamente. Emite llamadas a herramientas, y Eye las ejecuta contra las bases de datos del caso y devuelve los resultados — de modo que cada acción es explícita, registrada y reproducible. Las herramientas se definen en `configs/llm_config.json` y se despachan a través de `eye/services/context_manager.py`.

**Herramientas de investigación** — leer y analizar evidencia:

| Herramienta | Propósito |
|---|---|
| `query_database` | Ejecutar un `SELECT` contra una base de datos forense. |
| `search_artifacts` | Búsqueda de texto / regex entre bases de datos. |
| `semantic_search_artifacts` | Búsqueda semántica entre artefactos analizados. |
| `get_schema` | Inspeccionar esquemas de tablas. |
| `query_timeline` | Un barrido cronológico único a través de cada base de datos del caso — qué ocurrió y cuándo. |
| `query_correlation_results` | Consultar la salida del Motor de Correlación por tiempo / identidad. |
| `read_imported_evidence` | Leer evidencia de terceros importada al caso de forma textual (informes, correos, salida de herramientas de navegador). |
| `correlate_imported_evidence` | Correlacionar evidencia de terceros importada al caso contra artefactos nativos. |
| `analyze_large_dataset` | Análisis map-reduce de grandes conjuntos de resultados — **sin truncamiento silencioso**. |
| `list_case_files` | Listar archivos en el directorio del caso. |
| `internet_search` / `fetch_web_content` | Buscar y obtener contexto externo de amenazas / técnico. |
| `query_living_off_the_land_intel` | Consultas LOLBAS / LOLDrivers. |
| `query_threat_intel` | Consultas VirusTotal / inteligencia de amenazas. |
| `switch_model` | Cambiar de modelo en tiempo de ejecución (solo mismo backend). |

**Herramientas de informes** construyen el Espacio de Trabajo de Informe Vivo: `report_append_section`, `report_add_data_table`, `report_add_chart`, `report_add_timeline`, `report_add_heatmap`, `report_add_chain_of_custody`, `report_add_chat_transcript`, `report_add_image`, `report_edit_section`, `report_delete_section`, `chat_add_table` y `export_report` (la exportación requiere aprobación humana).

**Herramientas de autoría** (gobernadas — ver [Construcción de Wings de Correlación y Mapeos Semánticos](#building-correlation-wings--semantic-mappings)): `correlation_create_wing`, `correlation_edit_wing`, `correlation_create_semantic_mapping`, `correlation_edit_semantic_mapping`. Las llamadas a herramientas se traducen a lo que el backend activo espera — llamadas a funciones nativas para APIs en la nube y servidores locales, o un envoltorio XML `<tool_call>` para agentes CLI.

### Construcción de Wings de Correlación y Mapeos Semánticos

Eye no solo *consulta* el [Motor de Correlación](#-correlation-engine) — puede ayudar a **extenderlo**. Cuando Eye detecta un patrón recurrente entre artefactos, puede proponer nuevos **Wings** (reglas de correlación) y **Mapeos Semánticos** (traducciones técnico-a-humano). Esto es *autoría gobernada*: Eye propone, el analista revisa el artefacto guardado, y cada cambio está justificado y respaldado por evidencia.

**Un Wing** une feathers dentro de una ventana temporal y un umbral mínimo de coincidencias para probar una afirmación:

| Campo | Significado |
|---|---|
| `wing_name` | Nombre legible por humanos para la regla. |
| `proves` | La afirmación forense que respalda (p. ej., *ejecución de programas*). |
| `feathers[]` | Artefactos a correlacionar — cada uno con `artifact_type`, `weight` opcional (0–1) y `tier` (1–4). |
| `time_window_minutes` | Ventana de correlación (por defecto **180** = 3 horas). |
| `minimum_matches` | Cuántos feathers deben coincidir dentro de la ventana (por defecto **1**). |
| `reason` *(obligatorio)* | Justificación forense de la regla. |
| `related_evidence` *(obligatorio)* | Una o más referencias `database:table:rowid` que la motivaron. |

**Un Mapeo Semántico** traduce un valor técnico bruto a un significado legible por humanos (p. ej., *EventID 4624 → "Inicio de Sesión Exitoso"*). Viene en dos variantes: un `mapping` simple (valor único / regex → valor semántico) o una `rule` de múltiples condiciones (condiciones unidas por AND/OR). Ambos admiten `category`, `severity`, `confidence` y `scope`, y ambos requieren `reason` + `related_evidence`.

**Gobernanza — reglas del lado de escritura que sostienen el GEP:**
- **Razón Obligatoria** (sostiene **GEP-9** + **GEP-2**): cada creación *y* edición debe incluir una `reason` forense.
- **Vínculo de Evidencia** (sostiene **GEP-2**): cada creación debe citar al menos una referencia `database:table:rowid`.
- **Sellado por Eye / solo lectura para otros** (sostiene **GEP-7** + **GEP-9**): Eye sella su autoría + razón + historial de ediciones y puede editar **solo lo que Eye creó** — las reglas integradas y las creadas por humanos permanecen en **solo lectura**.

### Contexto Autocurativo

Las investigaciones largas pueden superar la ventana de contexto de un modelo — especialmente los modelos offline más pequeños. En lugar de fallar o descartar evidencia en silencio, Eye **compacta automáticamente su propio contexto** antes de cada llamada al modelo (dentro de su ruta de generación protegida, totalmente auditada).

Antes de cada llamada, Eye mide la carga útil completa y reserva espacio para la respuesta (**10%** de la ventana, mínimo 512 tokens, nunca más de la mitad). Si aún no cabe, se cura en dos pasadas ordenadas, sin tocar nunca los mensajes **protegidos** (fijados, evidencia auto-detectada o un resultado de herramienta):

1. **Pasada de resumen** *(una vez)* — el historial no protegido se colapsa en un único resumen, registrado como `SUMMARIZED`.
2. **Pasada de descarte** — el mensaje **no protegido más antiguo** se elimina de uno en uno hasta que quepa, registrado como `TRUNCATED`.

Si el **núcleo de evidencia** irreducible (fijado + resultados de herramientas + la pregunta actual) *aún* se desborda, Eye **se niega a continuar en lugar de truncar evidencia** (`REFUSED_OVERFLOW`) y te pide que acotes la consulta o uses `analyze_large_dataset`. Lo que finalmente llega al modelo es la carga útil exacta que se sella para la cadena de custodia.

### 🗺️ Mapa Narrativo — La Memoria Persistente del Caso del Eye

El Eye es **sin estado entre turnos** — por eso el **Mapa Narrativo** es donde "lo que sabemos y lo que hemos concluido" vive para un caso. Es la **memoria de trabajo persistente, auditable y a prueba de manipulaciones** del Eye, y su contenido se **inyecta en el prompt del Eye en cada turno** (el mapa literalmente *es* la memoria).

- 🧭 **Veredicto → Narrativa → Evidencia.** Una jerarquía estricta: un **Veredicto** de caso, las **Narrativas** debajo de él (afirmaciones, cada una con un estado — `proven` · `open` · `negative` · `needs` · `absolute`), y la **Evidencia** respaldada por artefactos debajo de esas.
- 🪟 **Su propia ventana.** Se abre desde el botón **"Narrative Map"** en la ventana de chat del Eye, para que puedas ver el chat, el informe vivo y la memoria del caso lado a lado; se actualiza en vivo a medida que las cosas cambian.
- ↔️ **Bidireccional — una memoria que controlas.** Tanto las ediciones del Eye como tus propias notas fluyen a través de un único **commit validado por GEP** y se sellan en un **registro de auditoría encadenado por hash** (`narrative_map_audit.jsonl`). Puedes **añadir, editar y eliminar** sus afirmaciones y evidencia, dando forma directamente a cómo el Eye entiende e interpreta el caso.
- 🚫 **Nunca afirma lo no respaldado.** Una narrativa del Eye puede permanecer `open` sin evidencia mientras investiga, pero nunca puede estar `proven` sin evidencia; un tema que el Eye verificó pero encontró vacío se auto-convierte en **`negative`** — porque una ausencia documentada es en sí misma un hallazgo.

### Cómo Funciona el Cumplimiento

El cumplimiento no es una función añadida encima — se aplica en el pipeline.

- **🔗 Cadena de custodia (Sello de Evidencia).** Cada carga útil que Eye envía a un LLM se sella: el **SHA-256 de los bytes exactos**, el recuento de tokens, el modelo + su límite de contexto, y la procedencia de cada fila de evidencia (`database:table:rowid`, más desplazamientos calculados para registros MFT). Los sellos son **de solo añadido y encadenados por hash** en `<case>/EYE_Logs/eye_payload_seal.jsonl` — un único registro alterado o eliminado rompe la cadena, de modo que el registro prueba *matemáticamente* qué bytes analizó el modelo.
- **🚫 Sin truncamiento silencioso.** Cuando el contexto se ajusta, Eye se [autocura](#self-healing-context) y reasigna presupuestos en un orden estricto: **Prioridad 1 (Inamovible): Evidencia Bruta + el Prompt del Sistema** › **Prioridad 2 (Sacrificable): Conversación Casual** › **Prioridad 3 (Flexible): Contexto RAG**. Si el núcleo de evidencia aún no cabe, Eye se niega en lugar de descartar evidencia en silencio.
- **🧾 Rastro de auditoría de truncamiento.** Cada decisión de contexto se registra en `<case>/EYE_Logs/truncation_audit.log` (`SUMMARIZED`, `TRUNCATED`, `PRESERVED`, `PINNED`, `UNPINNED`, `BUDGET_REDUCED`), cada una con un hash. La evidencia detectada se fija automáticamente por encima de un umbral de confianza; también puedes fijar mensajes manualmente.
- **📑 Mandato de evidencia-a-informe.** Eye debe responder en el chat **y** persistir la evidencia de respaldo en el informe; no registrar evidencia se marca como una violación del protocolo.
- **⚖️ Gobernanza de correlación.** Cualquier Wing o mapeo que Eye cree debe incluir una `reason` forense y `related_evidence`; las reglas creadas fuera de Eye son de solo lectura y no pueden reescribirse en silencio.
- **🔐 Privacidad y aislamiento de red.** En modos offline, Eye realiza **cero llamadas salientes**; las claves de API en la nube viven en llaveros nativos del sistema operativo — nunca codificadas, nunca escritas en registros.

📖 **Arquitectura completa del Eye:** [`eye/README.md`](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/README.md).

## 📖 Eye-Describe — Base de Conocimiento de Artefactos a Nivel de Byte

> 🔗 **[Explora Eye-Describe → crow-eye.com/eye-describe](https://crow-eye.com/eye-describe)**

Históricamente, los investigadores caían en la trampa de confiar en sus herramientas forenses sin entender cómo se comportan los artefactos subyacentes o cómo los analizó la herramienta. El riesgo hoy es simplemente reemplazar *"la herramienta"* por *"la IA"*. Una IA puede analizar un registro con precisión técnica perfecta y aun así colocarlo en el contexto equivocado — cambiando el significado completo de la evidencia.

**Eye-Describe** existe para que ni el humano ni el modelo tengan que adivinar. Es una referencia interactiva a nivel de byte de las estructuras binarias brutas de los artefactos de Windows, y cumple dos roles a la vez:

| Rol | Qué hace |
|---|---|
| 🧑‍🏫 **El plano para el humano** | Una referencia educativa interactiva de la anatomía profunda a nivel de byte de los artefactos de Windows — qué es cada estructura, cómo se comporta, qué puede y qué no puede probar. Gratuita, dirigida a estudiantes, educadores y profesionales que quieren entender la evidencia en lugar de la columna de salida. |
| ⚖️ **El ancla de cumplimiento para la IA** | La visibilidad del Eye está vinculada a los comportamientos documentados de artefactos en Eye-Describe. El modelo razona contra una referencia codificada de lo que un artefacto *realmente significa*, en lugar de inferir semántica por su cuenta. |

Al anclar la capa de IA al comportamiento documentado de los artefactos, Crow-Eye no te pide que confíes en un modelo — está restringiendo al modelo para que respete la forensia bruta.

> **No reemplaces la confianza en la herramienta por confianza en la IA. Entiende los datos.**

## 🧪 Calidad y Validación

Las herramientas forenses solo son útiles si su salida puede defenderse. El trabajo de corrección de Crow-Eye es deliberadamente visible:- **Suites de regresión.** El Correlation Engine está cubierto por una suite de pytest que abarca el análisis de marcas de tiempo, la normalización de identidades, la expansión multi-marca de tiempo, el contrato del escritor, la autoría de Eyes (gobernanza GEP del lado de escritura) y el registro de campos estándar. El motor UBA incluye su propia suite, incluida una ejecución de extremo a extremo contra un caso real.
- **Banco de validación.** Un banco holístico ejercita las 7 alas predeterminadas contra **ambos** motores en un caso real de Windows de ~700K registros.
- **Historial de defectos publicado.** Las regresiones de precisión y su impacto medido están documentados abiertamente en [`RELEASE_NOTES.md`](https://github.com/ghassan-elsman/crow-eye/blob/main/RELEASE_NOTES.md), incluidos los casos en los que una corrección cambió los registros vistos en órdenes de magnitud. Saber qué estuvo mal y cuándo es parte de lo que hace que un resultado sea defendible.
- **Contabilidad de evidencia verificable.** Cada registro termina en una coincidencia o en un depósito de descarte con nombre, y el libro de descartes por ventana hace que "no quede evidencia sobrante" sea algo que puedas comprobar desde el registro en lugar de aceptar por fe.
- **Registros a prueba de manipulación.** `verify_chain()` vuelve a recorrer el registro de auditoría del Narrative Map y la cadena del Evidence Seal para detectar modificaciones, incluidas las de campos legibles por humanos.

## 🔬 Plataforma de investigación

Crow-Eye es más que software: es una **plataforma de investigación abierta** que acelera todo el campo de la informática forense de Windows. El proyecto se centra en:

- Publicar documentación detallada sobre las estructuras internas de los artefactos.
- Compartir lógica de correlación y metodologías.
- Habilitar la revisión por pares, la transparencia y la colaboración académica.
- Contribuir al conocimiento colectivo de la comunidad forense.

## 🛠️ Notas técnicas

- El análisis del registro requiere archivos de hive de registro completos.
- Algunos artefactos requieren un manejo especial debido a los mecanismos de bloqueo de archivos de Windows (consulta [Registro personalizado / archivos bloqueados](#-artefactos-soportados)).
- El análisis de LNK y Jump Lists lo maneja el propio analizador dedicado de Crow-Eye.

## 📸 Capturas de pantalla

Una selección de las vistas de interfaz y análisis de Crow-Eye.

![Captura de pantalla de Crow-Eye](https://assets.kitploit.com/production/public/readmes/9931/d631f2359d186d47eab815cc199d2c08c7c098cb8c64509d7c43185b6413d537.png)

![Captura de pantalla de Crow-Eye](https://assets.kitploit.com/production/public/readmes/9931/140bd5b574f8b2d239f45be6b9d238a592da1cf3b7e6a0cf0a7450a653a75b88.png)

![Captura de pantalla de Crow-Eye](https://assets.kitploit.com/production/public/readmes/9931/b7593c596ea437f84cdf476c147fc363a9a87fd821023b2c93559cdc56ceebee.png)

![Captura de pantalla de Crow-Eye](https://assets.kitploit.com/production/public/readmes/9931/b67e55fc8c3bc87a5357add66c97e2b5d75310fe7ea5c1f571f5e8938c0a25ae.png)

![Captura de pantalla de Crow-Eye](https://assets.kitploit.com/production/public/readmes/9931/8f10355f7d0f9f31e2e270ecf43fa70e94a6eda3b84b792d28479e0552eec000.png)

![Captura de pantalla de Crow-Eye](https://assets.kitploit.com/production/public/readmes/9931/7bbf1b790d445d33a392b023cc14877e8ee0c72ed2aeec1aba1663da7d0419a2.png)

🎥 **Vídeo de demostración:** [![Ver la demo](https://assets.kitploit.com/production/public/readmes/9931/01aa6e4b5fb8732512fe81143b1dcd87d908401369284bad8cfaf1b119fcbf41.jpg)](https://youtu.be/hbvNlBhTfdQ)

## 🚧 Hoja de ruta

Trabajo planificado y en curso (consulta [`RELEASE_NOTES.md`](https://github.com/ghassan-elsman/crow-eye/blob/main/RELEASE_NOTES.md) para ver los cambios publicados):

- 📊 **Vistas e informes GUI avanzados** — visualización e informes más ricos.
- 🔄 **Diálogo de búsqueda mejorado** — filtrado avanzado con soporte de lenguaje natural.
- 🎯 **Mapeo semántico mejorado** — mapeo integral de campos en todos los tipos de artefactos.
- 📈 **Puntuación de correlación avanzada** — puntuación de confianza refinada y explicable.
- ⚡ **Correlación paralela** — despacho por pool de procesos, habilitado por defecto para cargas de trabajo grandes.

¿Tienes una idea o quieres añadir un artefacto? [Abre un issue](https://github.com/Ghassan-elsman/Crow-Eye/issues) o consulta [Contribuciones](#-contribuciones).

## 📚 Documentación

- **[TECHNICAL_DOCUMENTATION.md](https://github.com/ghassan-elsman/crow-eye/blob/main/TECHNICAL_DOCUMENTATION.md)** — arquitectura, componentes y guía de desarrollo.
- **[RELEASE_NOTES.md](https://github.com/ghassan-elsman/crow-eye/blob/main/RELEASE_NOTES.md)** — novedades de cada versión (UBA, Narrative Map, backends Eye en la nube, endurecimiento de gestión de casos, …).
- **[Documentación del Correlation Engine](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/CORRELATION_ENGINE_OVERVIEW.md)** — descripción general, motor, feathers, wings, pipelines.
- **[Arquitectura de la línea de tiempo](https://github.com/ghassan-elsman/crow-eye/blob/main/timeline/ARCHITECTURE.md)** — internals del módulo de línea de tiempo.
- **[Arquitectura de Eye](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/README.md)** y **[estándar GEP](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/docs/GEP_standard.md)** — el asistente de IA y su protocolo rector.

## 🤝 Contribuciones

Crow-Eye está construido como una plataforma de investigación abierta, y las contribuciones son bienvenidas: nuevos analizadores, reglas de correlación, documentación e investigación de artefactos.

- **Contribuciones generales:** [CONTRIBUTING.md](https://github.com/ghassan-elsman/crow-eye/blob/main/CONTRIBUTING.md)
- **Correlation Engine (área prioritaria):** [correlation_engine/CONTRIBUTING.md](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/CONTRIBUTING.md)
- **Contacto:** [[email protected]](mailto:[email protected]) · o abre un issue / pull request.

## 🌐 Sitio web y comunidad

- 🌍 **Sitio web oficial:** [crow-eye.com](https://crow-eye.com/) — recursos, documentación y descargas.
- 💬 **Discord:** [Únete al Discord de Crow-Eye](https://discord.gg/2vag2Udf) — ayuda directa, investigación de artefactos y anuncios de versiones.

## 📄 Licencia

Crow-Eye se publica bajo la **[GNU General Public License v3.0](https://github.com/ghassan-elsman/crow-eye/blob/main/LICENSE)** (GPL-3.0). Es libre de usar, estudiar, compartir y modificar bajo los términos de esa licencia.

## 📝 Cómo citar Crow-Eye

Si usas Crow-Eye en trabajos académicos, investigaciones publicadas o un informe de caso, cítalo:```bibtex
@software{elsman_crow_eye,
  author  = {Elsman, Ghassan},
  title   = {Crow-Eye: A Windows Forensics Engine},
  url     = {https://github.com/Ghassan-elsman/Crow-Eye},
  license = {GPL-3.0},
  year    = {2026}
}
```
Elsman, G. *Crow-Eye: Un Motor de Informática Forense para Windows* (GPL-3.0). https://github.com/Ghassan-elsman/Crow-Eye

Para las citas metodológicas, el Protocolo Ghassan Elsman está documentado por separado en [`eye/docs/GEP_standard.md`](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/docs/GEP_standard.md).

## 💖 Apoyo

Crow-Eye es gratuito y de código abierto, creado y mantenido por una sola persona. Si te resulta útil en tu trabajo, considera patrocinarlo: financia directamente nuevos analizadores e investigación: **[SPONSORS.md](https://github.com/ghassan-elsman/crow-eye/blob/main/SPONSORS.md)** · **[GitHub Sponsors](https://github.com/sponsors/Ghassan-elsman)**.

## Créditos

Creado y mantenido por **Ghassan Elsman**.