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

*Fonte de evidência → Ingestão → Bancos de dados do caso → Análise → Camada de IA → Relatório*


**Como ler:**

| Etapa | O que importa |
|---|---|
| ① → ② | **Quatro portas independentes para um caso.** Você nunca precisa do coletor próprio do Crow-Eye — uma pasta do Velociraptor, KAPE ou um pacote de EDR passa pelo Importador Offline, e CSV/JSON/SQLite de terceiros passa pelo Importar Evidência. |
| ② → ③ | Tudo converge para um único lugar: **os bancos de dados do caso**. Artefatos analisados vão para `Target_Artifacts/`; evidências importadas de terceiros vão para `Imported_Evidence/` e são descobertas automaticamente. |
| ③ → ④ | **Os três caminhos de análise são independentes entre si.** A Linha do Tempo e a UBA leem os bancos de dados do caso diretamente — nenhuma exige uma execução de correlação. O Mecanismo de Correlação é uma camada *adicional*, não um pré-requisito. |
| ③ → ④ | **A Vinculação Dinâmica fica ao lado da Linha do Tempo e da UBA** — um quarto leitor independente dos bancos de dados do caso (não tem relação com a visualização da Linha do Tempo). Ela reúne mapeamentos de identidade (SID → nome de usuário, MAC → rede, hash/GUID → aplicativo) em um `Crow_Intelligence.db` por caso e, em seguida, sobrepõe esse contexto **inline nas tabelas de dados de artefatos** por meio de `ATTACH` + `LEFT JOIN` não destrutivos. Ela muda como os registros *são lidos*, nunca a evidência. |
| ④ → ⑤ | O Eye consulta os bancos de dados do caso diretamente e pode buscar resultados de correlação **sob demanda**. Ele nunca toca na evidência em si — ele emite chamadas de ferramenta que o Crow-Eye executa e registra. |
| ⑤ → Relatório | O **Relatório Vivo é construído apenas pelo Eye**, por meio de suas ferramentas `report_*`. A Linha do Tempo e a UBA são superfícies de análise — elas não escrevem no relatório. Descobertas em nível de caso ainda podem ser exportadas separadamente via [Pesquisar e Exportar](#-pesquisar-e-exportar). |
| ⑤ ↔ | O **Mapa Narrativo é bidirecional**: o Eye escreve nele, você escreve nele, e seu conteúdo é injetado no prompt do Eye a cada turno. É a memória, e você pode comandá-lo. |
| ⑤ ⟳ | A página de **Conformidade audita o Eye.** Cada chamada de ferramenta feita pelo Eye é ancorada à cadeia de hash **EvidenceSeal**; a página renderiza o status **GEP** por regra em tempo real (10 princípios) verificado a partir dessa cadeia e de `EYE_Logs/`, exportável como `audit_trail.json`. |

**Etapas independentes.** A Linha do Tempo e a UBA leem os bancos de dados de artefatos do caso **diretamente** — nenhuma exige uma execução de correlação, e a Linha do Tempo não depende do Mecanismo de Correlação (ela aplica seu próprio agrupamento temporal leve). A correlação é uma camada de análise adicional cujos resultados o Eye pode consultar.

**Somente leitura por design.** A análise grava no banco de dados do caso; toda etapa posterior (UBA, Linha do Tempo, visualizadores de correlação, Eye) abre esses bancos de dados **somente leitura**. A evidência original nunca é modificada — a [Vinculação Dinâmica](#-modos-de-análise) lê os bancos de dados do caso para construir um `Crow_Intelligence.db` por caso com mapeamentos de identidade e enriquece as tabelas de dados de artefatos inline por meio de consultas `ATTACH` + `LEFT JOIN` não destrutivas, em vez de reescrever linhas.

**Governado por design.** Cada ação que o Eye toma é ancorada à cadeia de hash **EvidenceSeal** à prova de adulteração, e a página de **Conformidade** verifica continuamente o Eye contra o [Protocolo Ghassan Elsman (GEP)](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/docs/GEP_standard.md) — status por regra em tempo real, exportável para `EYE_Logs/audit_trail.json`.

## 📥 Baixar e Instalar

> **Recomendado:** obtenha o build Windows empacotado (**instalador MSI / EXE**) no site oficial — sem configuração de Python, funciona imediatamente.

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

O **build MSI/EXE instalado é a forma recomendada de executar o Crow-Eye**, e é a nossa **maior prioridade para atualizações**:

- 🛡️ **Correções mais rápidas.** Quando um problema é encontrado ou um bug é relatado, lançamos um EXE atualizado **o mais rápido possível** — o build empacotado é onde as correções chegam primeiro.
- 🔄 **Atualização automática integrada.** No aplicativo instalado, abra **Configurações → Atualizações** para **verificar atualizações e instalá-las automaticamente** — sem reinstalação manual.
- 📦 **Zero configuração.** Sem necessidade de instalar Python, Node ou dependências.

> Prefere executar a partir do código-fonte? Veja **[Início Rápido](#-início-rápido)** abaixo. O build a partir do código-fonte é destinado a colaboradores e **não inclui o atualizador automático** — use o MSI/EXE para atualizações automáticas.

## 🚀 Início Rápido

### Opção A — Build instalado (recomendado)
Baixe o **MSI/EXE** em [crow-eye.com/download](https://crow-eye.com/download), instale e inicie o **Crow-Eye** como Administrador. Crie um caso e comece a analisar.

### Opção B — Executar a partir do código-fonte (desenvolvedores)

> Para colaboradores e usuários avançados. Este caminho **não inclui o atualizador automático** — use o MSI/EXE para atualizações automáticas.

**Requisitos** (instalados automaticamente na primeira execução):
- Python 3.12.4
- **Node.js e npm** — necessários para a **Visualização da Linha do Tempo**
- Pacotes principais: 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 de MFT/USN com milhões de registros) |
| **Disco** | 5 GB livres | Espaço livre ≥ 2× o tamanho da evidência sendo analisada |
| **CPU** | 4 núcleos | 8+ núcleos |
| **SO** | Windows 10/11 (completo) · Linux (análise offline e de imagens) | — |

> A correlação faz streaming em memória constante para conjuntos de dados muito grandes, então a RAM raramente é o limite rígido — a taxa de transferência do disco e o espaço livre geralmente são.

**Iniciar** (execute como Administrador para que o Crow-Eye possa acessar artefatos do sistema):```bash
python "Crow Eye.py"

**Formatos de importação suportados:** CSV (qualquer arquivo com cabeçalho), JSON (plano ou aninhado) e SQLite (importação direta). Mapeamento automático de colunas, detecção de tipos de dados, normalização de timestamps para ISO, validação e índices otimizados.```
prefetch.db (Feather)
├── feather_metadata (artifact type, source, record count)
├── prefetch_data (executable_name, path, last_executed, hash)
└── Indexes (timestamp, name, path)

#### 3. ⚙️ Motores (Estratégias de Correlação)

**Finalidade**: Executar a lógica de correlação para encontrar relações entre artefatos. As ligações estruturais vêm **primeiro**; uma pontuação ponderada por camadas é aplicada por cima como *interpretação/classificação*, não como base para uma correspondência.

**Motor de Varredura por Janela de Tempo** — ideal para análises baseadas em tempo e correlação temporal sistemática. Varre o tempo em intervalos fixos, coleta registros de todas as feathers por janela, aplica correspondência de campos semânticos + pontuação ponderada e evita duplicatas por meio do rastreamento de MatchSet. **O(N log N)** (consultas indexadas por timestamp); processamento em lote (~2.567 janelas/segundo).

**Motor de Correlação Baseado em Identidade** — ideal para grandes conjuntos de dados (>1.000 registros) e rastreamento de identidades. Extrai e normaliza identidades, agrupa registros por identidade, constrói âncoras temporais dentro de cada cluster, classifica evidências como primárias/secundárias/de apoio e faz streaming para conjuntos muito grandes (>5.000 âncoras) com memória constante. **O(N log N)**; 40+ padrões de campos de identidade por tipo.

**Seleção do motor:** use o motor de Janela de Tempo para análises baseadas em tempo e o motor Baseado em Identidade para rastreamento de identidades — ambos estão prontos para produção e otimizados para grandes conjuntos de dados com consultas indexadas.

#### 4. 🔄 Pipelines (Orquestração de Fluxos de Trabalho)

**Finalidade**: Automatizar fluxos de trabalho completos de análise, desde a criação de feathers até a geração de resultados. Um pipeline lê sua configuração (tipo de motor, wings, feathers), instancia o motor correto por meio do EngineSelector, executa cada wing, agrega correspondências, salva os resultados (DB + JSON) e os exibe na GUI com filtragem e visualização.```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"
  }
}

### Exemplo de Caso de Uso: Encontrando Prova de Execução

**Cenário**: provar que `malware.exe` foi executado em um sistema.```json
{
  "wing_id": "malware-execution",
  "correlation_rules": { "time_window_minutes": 5, "minimum_matches": 2 },
  "feathers": ["prefetch", "shimcache", "amcache"]
}

## Instalação

### Pré-requisitos

- Python 3.8 ou superior
- pip (gerenciador de pacotes do Python)
- Acesso à internet para baixar dependências

### Passos de instalação

1. Clone o repositório:

```bash
git clone https://github.com/example/repo.git
cd repo

python -m venv venv
source venv/bin/activate  # No Windows: venv\Scripts\activate

pip install -r requirements.txt

python tool.py --version

python tool.py [opções] <alvo>

python tool.py https://exemplo.com

python tool.py -v -o resultados.txt https://exemplo.com

python tool.py -t 50 https://exemplo.com

# Configuração da ferramenta
config:
  user_agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
  timeout: 30
  max_retries: 3
  proxy:
    enabled: false
    url: ""
  headers:
    Accept: "*/*"
    Accept-Language: "en-US,en;q=0.9"

pip install -r requirements.txt

chmod +x tool.py

from correlation_engine.pipeline import PipelineExecutor
executor = PipelineExecutor(pipeline_config)
results = executor.execute()
```
Aqui está a tradução do conteúdo fornecido:

---

## Instalação

### Requisitos

- Python 3.8 ou superior
- pip (gerenciador de pacotes do Python)

### Passos de Instalação

1. Clone o repositório:
   ```bash
   git clone https://github.com/example/tool.git
   cd tool
   ```

2. Instale as dependências:
   ```bash
   pip install -r requirements.txt
   ```

3. Execute a ferramenta:
   ```bash
   python main.py --help
   ```

## Uso

### Exemplos Básicos

Para executar uma varredura básica:

```bash
python main.py scan --target example.com
```

Para gerar um relatório detalhado:

```bash
python main.py report --format pdf
```

### Opções Avançadas

A ferramenta suporta várias opções avançadas para personalizar sua experiência:

- `--verbose`: Ativa a saída detalhada.
- `--output-dir DIR`: Especifica o diretório de saída para os resultados.
- `--config FILE`: Usa um arquivo de configuração personalizado.

## Configuração

O arquivo de configuração padrão é `config.yaml`. Você pode criar um arquivo de configuração personalizado e passá-lo com a opção `--config`.

### Exemplo de `config.yaml`

```yaml
targets:
  - example.com
  - example.org

scan_options:
  ports: [80, 443, 8080]
  timeout: 30

report:
  format: html
  output_dir: ./reports
```

## Solução de Problemas

### Erro: `ModuleNotFoundError`

Se você encontrar um erro de módulo não encontrado, certifique-se de que todas as dependências estão instaladas:

```bash
pip install -r requirements.txt
```

### Erro: `PermissionError`

Se você encontrar um erro de permissão ao executar a ferramenta, tente usar `sudo` (no Linux/macOS) ou execute o terminal como administrador (no Windows).

## Contribuindo

Aceitamos contribuições! Por favor, siga estas etapas:

1. Faça um fork do repositório.
2. Crie um novo branch para sua funcionalidade.
3. Envie um pull request com uma descrição clara das alterações.

## Licença

Este projeto está licenciado sob a Licença MIT. Consulte o arquivo `LICENSE` para obter mais detalhes.

---

**Aviso Legal:** Esta ferramenta é fornecida apenas para fins educacionais e de teste de segurança autorizado. O uso indevido desta ferramenta pode violar leis e regulamentos locais. O autor não se responsabiliza por qualquer uso indevido.```
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
```
### Benchmarks de Desempenho

| Registros | Motor de Janela Temporal | Motor Baseado em Identidade |
|---|---|---|
| 1.000 | 0,5s | 2s |
| 10.000 | 5s | 15s |
| 100.000 | 50s | 2,5 min (streaming) |
| 1.000.000 | — | 25 min (streaming) |

### Introdução ao Motor de Correlação

1. **Iniciar**: `python -m correlation_engine.main`
2. **Criar Feathers**: importe seus artefatos forenses (Prefetch, ShimCache, …).
3. **Criar Wings**: defina regras de correlação para sua investigação.
4. **Criar um Pipeline**: configure quais wings e feathers usar.
5. **Executar**: execute o pipeline e visualize os resultados correlacionados.
6. **Analisar**: use o Visualizador de Resultados para explorar relações temporais.

### 📚 Documentação do Motor de Correlação

- **[Visão Geral do Motor de Correlação](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/CORRELATION_ENGINE_OVERVIEW.md)** — visão geral do sistema com diagramas de arquitetura
- **[Documentação do Motor](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/engine/ENGINE_DOCUMENTATION.md)** — arquitetura de motor duplo, seleção de motor, otimização de desempenho
- **[Arquitetura](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/ARCHITECTURE.md)** — integração de componentes e fluxo de dados
- **[Documentação de Feather](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/feather/FEATHER_DOCUMENTATION.md)** — o sistema de normalização de dados
- **[Documentação de Wings](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/wings/WINGS_DOCUMENTATION.md)** — regras de correlação
- **[Documentação de Pipeline](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/pipeline/PIPELINE_DOCUMENTATION.md)** — orquestração de fluxo de trabalho
- **[Adicionando um Artefato](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/ADDING_AN_ARTIFACT.md)** — o fluxo de trabalho para conectar um novo parser ao motor
- **[Registro de Campos Padrão](https://github.com/ghassan-elsman/crow-eye/blob/main/config/standard_fields)** — sinônimos canônicos de nomes de colunas carregados por ambos os motores e pelo Eye
- **[Guia de Contribuição](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/CONTRIBUTING.md)** — como contribuir com o motor
- Links rápidos: [Seleção de Motor](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/engine/ENGINE_DOCUMENTATION.md#engine-selection-guide) · [Solução de Problemas](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/engine/ENGINE_DOCUMENTATION.md#troubleshooting) · [Otimização de Desempenho](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/engine/ENGINE_DOCUMENTATION.md#performance-and-optimization)

## 👁️ Eye — O Assistente de IA Forense

> **Um assistente poderoso, não um substituto.** O Eye automatiza e *verifica* as hipóteses de um investigador — ele nunca decide por você.

**Eye** é o assistente de IA forense integrado do Crow-Eye: um investigador forense qualificado apoiado por uma base de conhecimento real de artefatos do Windows. Ele oferece uma interface em linguagem natural para consultar, correlacionar e documentar tudo em um caso — Prefetch, MFT, Registry, Event Logs, AmCache, ShimCache, SRUM e muito mais — mantendo um registro auditável e à prova de adulteração de exatamente o que fez. O Eye pode ser executado inteiramente em seu próprio hardware (incluindo **totalmente isolado da rede**), em conformidade com a postura de privacidade do Crow-Eye de **"0 ms de dados enviados para fora do dispositivo"**. Arquitetura completa: [`eye/README.md`](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/README.md).

| Capacidade | O que significa para você |
|---|---|
| **Investigação em linguagem natural** | Pergunte em inglês simples; o Eye escreve o SQL e pesquisa por você. |
| **Integração de múltiplas fontes** | Acesso unificado a todos os artefatos analisados no caso. |
| **Análise aprimorada por RAG** | O Eye recupera conhecimento forense específico de artefatos antes de responder. |
| **Espaço de Trabalho de Relatório Vivo** | Descobertas, tabelas, gráficos e linhas do tempo são documentados em tempo real. |
| **Humano no circuito** | Ações críticas (ex.: exportação de relatório) exigem sua aprovação explícita. |
| **Cadeia de custódia** | Prova criptográfica de exatamente o que o modelo analisou. |

O Eye transforma perguntas conversacionais ("mostre-me o que foi executado a partir de `C:\Temp` após as 22:00") em trabalho forense real: ele planeja uma abordagem, recupera conhecimento relevante de artefatos, executa SQL e buscas entre artefatos em seus bancos de dados de caso e sintetiza uma resposta validada. Cada resposta é produzida **em dois lugares ao mesmo tempo** — uma resposta de chat para você e um bloco estruturado gravado em um **Espaço de Trabalho de Relatório Vivo**, para que o dossiê se construa sozinho à medida que a investigação avança.

### O Protocolo Ghassan Elsman (GEP)

Tudo o que o Eye faz está ancorado no **Protocolo Ghassan Elsman (GEP)** — um padrão **neutro de fornecedor e independente de ferramenta** para *como qualquer IA deve ser usada em forense digital*. São **10 princípios** que um sistema conforme deve sustentar para que as descobertas assistidas por IA permaneçam **verdadeiras, rastreáveis aos registros de origem e respaldadas por uma cadeia auditável e à prova de adulteração**, com o investigador humano no controle:

| # | Princípio | Em uma linha |
|---|---|---|
| **GEP-1** | Primazia da Evidência | Conclusões vêm apenas de artefatos realmente examinados. |
| **GEP-2** | Rastreabilidade | Cada fato está vinculado a um registro de origem específico. |
| **GEP-3** | Especificidade e Cronologia | Carimbos de data/hora UTC exatos, identificadores e caminhos, ordenados no tempo. |
| **GEP-4** | Corroboração Cruzada | Basear-se em múltiplas fontes; relatar concordância, silêncio e conflito. |
| **GEP-5** | Verificação de Premissas | Tratar alegações humanas como hipóteses a provar ou refutar. |
| **GEP-6** | Completude | Nunca descartar ou truncar evidências silenciosamente. |
| **GEP-7** | Integridade e Não Repúdio | Nunca modificar evidências; registrar o que foi visto e feito, de forma à prova de adulteração. |
| **GEP-8** | Transparência e Explicabilidade | Raciocínio, ferramentas usadas e dados vistos são visíveis e auditáveis. |
| **GEP-9** | Autoridade Humana | O investigador decide; ações duráveis são atribuíveis. |
| **GEP-10** | Defensabilidade | A saída é objetiva, precisa e estruturada para revisão independente. |

O Eye do Crow-Eye é a **implementação de referência** do GEP; os comportamentos no produto que o sustentam são **Regras Operacionais**. 📜 Leia o padrão: [`eye/docs/GEP_standard.md`](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/docs/GEP_standard.md).

### Modos de Implantação

O Eye se adapta ao seu modelo de ameaça por meio de três modos de implantação:

| Modo | Melhor para | Backends |
|---|---|---|
| ☁️ **Modelos de IA em Nuvem** | Análise profunda e complexa com máximo poder computacional | OpenAI, Anthropic (Claude), Google Gemini |
| 🔒 **Servidor de IA Offline** (isolado da rede) | Investigações no local, com exposição zero | Ollama, LM Studio |
| ⚡ **Agentes de Terminal CLI** | Reutilizar um agente de terminal de IA que você já possui como modelo | Claude Code, Gemini CLI, ChatGPT CLI, llama.cpp, … |

No **modo agente CLI**, o Crow-Eye aciona um **agente de terminal/linha de comando de IA existente como modelo** — em vez de uma API em nuvem ou um servidor offline local — para que você possa investigar com o agente que já usa.

**O ciclo de investigação:**

1. **Abra ou crie um caso** — o Eye se limita aos bancos de dados de artefatos e ao histórico desse caso.
2. **Faça uma pergunta** em linguagem natural ou inicie uma triagem abrangente com um clique.
3. **O Eye executa seu pipeline** — detectar intenção → recuperar conhecimento → executar ferramentas → sintetizar.
4. **Você obtém uma saída dupla** — uma resposta direta no chat *e* um novo bloco no Relatório Vivo.
5. **Aprove ações bloqueadas** — exportações e outras etapas críticas aguardam sua autorização.

Você pode trocar de modelo em tempo de execução com a ferramenta `switch_model`. A troca é **restrita ao mesmo backend**, para que as evidências nunca sejam enviadas silenciosamente a um provedor diferente daquele que você escolheu.

### Rastreando o Processo de Pensamento do LLM

O Eye foi construído para que você possa ver — e depois provar — *como* ele chegou a uma conclusão. Enquanto o Eye trabalha, ele transmite atualizações estruturadas de `ThinkingStep` para a interface em tempo real; cada uma carrega um `step_id`, `type`, `label` legível por humanos, `status` (`active` → `done`, ou `error`) e `tool`/`params`/`detail` opcionais.

| Tipo de etapa | O que você está vendo |
|---|---|
| `thinking` | Planejamento do Eye — detectando intenção forense, construindo o prompt do sistema, decidindo os próximos passos. |
| `rag` | O Eye recuperando conhecimento de artefatos de sua base de conhecimento para fundamentar a resposta. |
| `tool_call` | O Eye executando uma ferramenta forense (uma consulta SQL, uma busca, uma consulta de correlação). |
| `synthesis` | O Eye validando e montando a resposta final, respaldada por evidências. |

Uma consulta típica se desenrola como `thinking → rag → thinking → tool_call → synthesis`, e todo caso mantém artefatos de rastreamento em disco que você pode inspecionar depois:

| Arquivo | O que registra |
|---|---|
| `<case>/EYE_Logs/eye_payload_seal.jsonl` | Os payloads exatos enviados ao modelo, encadeados por hash. |
| `<case>/EYE_Logs/truncation_audit.log` | O que do contexto foi mantido, resumido, descartado ou fixado — e por quê. |
| `<case>/case_history.json` | O histórico completo da conversa, com contagens de tokens por mensagem. |

### Execução de Ferramentas

O Eye é **orientado por ferramentas**: o modelo nunca toca as evidências diretamente. Ele emite chamadas de ferramenta, e o Eye as executa contra os bancos de dados do caso e retorna os resultados — para que cada ação seja explícita, registrada e reproduzível. As ferramentas são definidas em `configs/llm_config.json` e despachadas por meio de `eye/services/context_manager.py`.

**Ferramentas investigativas** — leem e analisam evidências:

| Ferramenta | Finalidade |
|---|---|
| `query_database` | Executar um `SELECT` contra um banco de dados forense. |
| `search_artifacts` | Busca de texto / regex entre bancos de dados. |
| `semantic_search_artifacts` | Busca semântica em artefatos analisados. |
| `get_schema` | Inspecionar esquemas de tabelas. |
| `query_timeline` | Uma varredura cronológica única em todos os bancos de dados do caso — o que aconteceu e quando. |
| `query_correlation_results` | Consultar a saída do Motor de Correlação por tempo / identidade. |
| `read_imported_evidence` | Ler evidências de terceiros importadas para o caso na íntegra (relatórios, e-mails, saída de ferramentas de navegador). |
| `correlate_imported_evidence` | Correlacionar evidências de terceiros importadas para o caso com artefatos nativos. |
| `analyze_large_dataset` | Análise map-reduce de grandes conjuntos de resultados — **sem truncamento silencioso**. |
| `list_case_files` | Listar arquivos no diretório do caso. |
| `internet_search` / `fetch_web_content` | Pesquisar e buscar contexto externo de ameaças / técnico. |
| `query_living_off_the_land_intel` | Consultas LOLBAS / LOLDrivers. |
| `query_threat_intel` | Consultas VirusTotal / inteligência de ameaças. |
| `switch_model` | Trocar de modelo em tempo de execução (somente mesmo backend). |

**Ferramentas de relatório** constroem o Espaço de Trabalho de Relatório 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` e `export_report` (a exportação exige aprovação humana).

**Ferramentas de autoria** (governadas — veja [Construindo Wings de Correlação e Mapeamentos Semânticos](#building-correlation-wings--semantic-mappings)): `correlation_create_wing`, `correlation_edit_wing`, `correlation_create_semantic_mapping`, `correlation_edit_semantic_mapping`. As chamadas de ferramenta são traduzidas para o que o backend ativo espera — chamada de função nativa para APIs em nuvem e servidores locais, ou um wrapper XML `<tool_call>` para agentes CLI.

### Construindo Wings de Correlação e Mapeamentos Semânticos

O Eye não apenas *consulta* o [Motor de Correlação](#-correlation-engine) — ele pode ajudar a **estendê-lo**. Quando o Eye detecta um padrão recorrente entre artefatos, ele pode propor novos **Wings** (regras de correlação) e **Mapeamentos Semânticos** (traduções técnico-para-humano). Isso é *autoria governada*: o Eye propõe, o analista revisa o artefato salvo, e cada mudança é justificada e respaldada por evidências.

**Um Wing** une feathers dentro de uma janela de tempo e um limite mínimo de correspondências para provar uma alegação:

| Campo | Significado |
|---|---|
| `wing_name` | Nome legível por humanos para a regra. |
| `proves` | A alegação forense que ele sustenta (ex.: *execução de programa*). |
| `feathers[]` | Artefatos a correlacionar — cada um com `artifact_type`, `weight` opcional (0–1) e `tier` (1–4). |
| `time_window_minutes` | Janela de correlação (padrão **180** = 3 horas). |
| `minimum_matches` | Quantos feathers devem corresponder dentro da janela (padrão **1**). |
| `reason` *(obrigatório)* | Justificativa forense para a regra. |
| `related_evidence` *(obrigatório)* | Uma ou mais referências `database:table:rowid` que a motivaram. |

**Um Mapeamento Semântico** traduz um valor técnico bruto em significado legível por humanos (ex.: *EventID 4624 → "Logon Bem-sucedido"*). Ele vem em duas variantes: um `mapping` simples (valor único / regex → valor semântico) ou uma `rule` de múltiplas condições (condições unidas por AND/OR). Ambos suportam `category`, `severity`, `confidence` e `scope`, e ambos exigem `reason` + `related_evidence`.

**Governança — regras do lado de escrita que sustentam o GEP:**
- **Razão Obrigatória** (sustenta **GEP-9** + **GEP-2**): toda criação *e* edição deve incluir uma `reason` forense.
- **Vínculo de Evidência** (sustenta **GEP-2**): toda criação deve citar pelo menos uma referência `database:table:rowid`.
- **Carimbado pelo Eye / somente leitura para outros** (sustenta **GEP-7** + **GEP-9**): o Eye carimba sua autoria + razão + histórico de edições e pode editar **apenas o que o Eye criou** — regras integradas e criadas por humanos permanecem **somente leitura**.

### Contexto Autocurativo

Investigações longas podem exceder a janela de contexto de um modelo — especialmente modelos offline menores. Em vez de travar ou descartar evidências silenciosamente, o Eye **compacta automaticamente seu próprio contexto** antes de cada chamada de modelo (dentro de seu caminho de geração protegido, totalmente auditado).

Antes de cada chamada, o Eye mede o payload completo e reserva espaço para a resposta (**10%** da janela, mínimo de 512 tokens, nunca mais da metade). Se ainda assim não couber, ele se cura em duas passagens ordenadas, nunca tocando mensagens **protegidas** (fixadas, evidências auto-detectadas ou um resultado de ferramenta):

1. **Passagem de resumo** *(uma vez)* — o histórico não protegido é condensado em um único resumo, registrado como `SUMMARIZED`.
2. **Passagem de descarte** — a mensagem **não protegida mais antiga** é removida uma a uma até caber, registrada como `TRUNCATED`.

Se o **núcleo de evidências** irredutível (fixado + resultados de ferramentas + a pergunta atual) *ainda* transbordar, o Eye **se recusa a prosseguir em vez de truncar evidências** (`REFUSED_OVERFLOW`) e pede que você restrinja a consulta ou use `analyze_large_dataset`. O que quer que finalmente vá para o modelo é o payload exato que é selado para a cadeia de custódia.

### 🗺️ Mapa Narrativo — A Memória Persistente do Caso do Eye

O Eye é **sem estado entre turnos** — então o **Mapa Narrativo** é onde "o que sabemos e o que concluímos" vive para um caso. Ele é a **memória de trabalho persistente, auditável e à prova de adulteração** do Eye, e seu conteúdo é **injetado no prompt do Eye a cada turno** (o mapa literalmente *é* a memória).

- 🧭 **Veredito → Narrativa → Evidência.** Uma hierarquia estrita: um **Veredito** de caso, as **Narrativas** abaixo dele (alegações, cada uma com um estado — `proven` · `open` · `negative` · `needs` · `absolute`), e as **Evidências** respaldadas por artefatos abaixo delas.
- 🪟 **Sua própria janela.** Abre pelo botão **"Narrative Map"** na janela de chat do Eye, para que você possa acompanhar o chat, o relatório vivo e a memória do caso lado a lado; ele atualiza ao vivo conforme as coisas mudam.
- ↔️ **Bidirecional — uma memória que você comanda.** Tanto as edições do Eye quanto suas próprias anotações fluem por um único **commit validado pelo GEP** e são seladas em um **log de auditoria encadeado por hash** (`narrative_map_audit.jsonl`). Você pode **adicionar, editar e remover** suas alegações e evidências, moldando diretamente como o Eye entende e interpreta o caso.
- 🚫 **Nunca afirma o não suportado.** Uma narrativa do Eye pode permanecer `open` sem evidências enquanto investiga, mas nunca pode ser `proven` sem evidências; um tema que o Eye verificou mas encontrou vazio converte-se automaticamente para **`negative`** — porque uma ausência documentada é em si uma descoberta.

### Como a Conformidade Funciona

A conformidade não é um recurso adicionado por cima — ela é aplicada no pipeline.

- **🔗 Cadeia de custódia (Selo de Evidência).** Todo payload que o Eye envia a um LLM é selado: o **SHA-256 dos bytes exatos**, a contagem de tokens, o modelo + seu limite de contexto e a proveniência de cada linha de evidência (`database:table:rowid`, além de offsets calculados para registros MFT). Os selos são **somente anexação e encadeados por hash** em `<case>/EYE_Logs/eye_payload_seal.jsonl` — um único registro alterado ou removido quebra a cadeia, então o log prova *matematicamente* quais bytes o modelo analisou.
- **🚫 Sem truncamento silencioso.** Quando o contexto fica apertado, o Eye [se autocura](#self-healing-context) e realoca orçamentos em uma ordem estrita: **Prioridade 1 (Imovível): Evidência Bruta + o Prompt do Sistema** › **Prioridade 2 (Sacrificial): Conversa Casual** › **Prioridade 3 (Flexível): Contexto RAG**. Se o núcleo de evidências ainda não couber, o Eye se recusa em vez de descartar evidências silenciosamente.
- **🧾 Trilha de auditoria de truncamento.** Toda decisão de contexto é registrada em `<case>/EYE_Logs/truncation_audit.log` (`SUMMARIZED`, `TRUNCATED`, `PRESERVED`, `PINNED`, `UNPINNED`, `BUDGET_REDUCED`), cada uma com um hash. Evidências detectadas são fixadas automaticamente acima de um limite de confiança; você também pode fixar mensagens manualmente.
- **📑 Mandato de evidência-para-relatório.** O Eye deve responder no chat **e** persistir as evidências de apoio no relatório; falhar em registrar evidências é sinalizado como violação de protocolo.
- **⚖️ Governança de correlação.** Qualquer Wing ou mapeamento que o Eye criar deve incluir uma `reason` forense e `related_evidence`; regras criadas fora do Eye são somente leitura e não podem ser reescritas silenciosamente.
- **🔐 Privacidade e isolamento de rede.** Em modos offline, o Eye faz **zero chamadas de saída**; chaves de API em nuvem vivem em chaveiros nativos do SO — nunca codificadas, nunca gravadas em logs.

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

## 📖 Eye-Describe — Base de Conhecimento de Artefatos em Nível de Byte

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

Historicamente, os investigadores caíam na armadilha de confiar em suas ferramentas forenses sem entender como os artefatos subjacentes se comportam ou como a ferramenta os analisou. O risco hoje é simplesmente substituir *"a ferramenta"* por *"a IA"*. Uma IA pode analisar um registro com precisão técnica perfeita e ainda assim colocá-lo no contexto errado — mudando todo o significado da evidência.

**Eye-Describe** existe para que nem o humano nem o modelo precisem adivinhar. É uma referência interativa, em nível de byte, das estruturas binárias brutas dos artefatos do Windows, e serve a dois papéis ao mesmo tempo:

| Papel | O que faz |
|---|---|
| 🧑‍🏫 **O projeto para o humano** | Uma referência educacional interativa da anatomia profunda em nível de byte dos artefatos do Windows — o que cada estrutura é, como se comporta, o que pode e o que não pode provar. Gratuito para uso, voltado a estudantes, educadores e profissionais que querem entender a evidência em vez da coluna de saída. |
| ⚖️ **A âncora de conformidade para a IA** | A visibilidade do Eye está vinculada aos comportamentos documentados de artefatos no Eye-Describe. O modelo raciocina contra uma referência codificada do que um artefato *realmente significa*, em vez de inferir semântica por conta própria. |

Ao ancorar a camada de IA ao comportamento documentado de artefatos, o Crow-Eye não está pedindo que você confie em um modelo — está restringindo o modelo a respeitar a forense bruta.

> **Não troque a confiança na ferramenta pela confiança na IA. Entenda os dados.**

## 🧪 Qualidade e Validação

Ferramentas forenses só são úteis se sua saída puder ser defendida. O trabalho de correção do Crow-Eye é deliberadamente visível:- **Suites de regressão.** O Correlation Engine é coberto por uma suite pytest que abrange parsing de timestamps, normalização de identidades, fan-out multi-timestamp, o contrato do writer, autoria Eye (governança GEP no lado de escrita) e o registo de campos padrão. O motor UBA inclui a sua própria suite, incluindo uma execução ponta a ponta contra um caso real.
- **Harness de validação.** Um harness holístico exercita todas as 7 wings padrão contra **ambos** os motores num caso Windows real de ~700K registos.
- **Histórico de defeitos publicado.** Regressões de precisão e o seu impacto medido estão documentados abertamente em [`RELEASE_NOTES.md`](https://github.com/ghassan-elsman/crow-eye/blob/main/RELEASE_NOTES.md) — incluindo casos em que uma correção alterou os registos vistos por ordens de magnitude. Saber o que estava errado, e quando, faz parte do que torna um resultado defensável.
- **Contabilidade de evidências verificável.** Cada registo ou cai numa correspondência ou num bucket de descarte nomeado, e o ledger de descarte por janela torna "sem evidências sobrantes" algo que pode verificar a partir do log em vez de aceitar por fé.
- **Logs à prova de adulteração.** `verify_chain()` re-percorre o log de auditoria do Narrative Map e a cadeia do Evidence Seal para detetar modificações — incluindo de campos legíveis por humanos.

## 🔬 Plataforma de Investigação

Crow-Eye é mais do que software — é uma **plataforma de investigação aberta** que acelera todo o campo da forense Windows. O projeto foca-se em:

- Publicar documentação detalhada sobre estruturas internas de artefactos.
- Partilhar lógica de correlação e metodologias.
- Permitir revisão por pares, transparência e colaboração académica.
- Contribuir para o conhecimento coletivo da comunidade forense.

## 🛠️ Notas Técnicas

- O parsing de registos requer ficheiros de hive de registo completos.
- Alguns artefactos requerem tratamento especial devido aos mecanismos de bloqueio de ficheiros do Windows (ver [Registos personalizados / ficheiros bloqueados](#-artefactos-suportados)).
- O parsing de LNK e Jump Lists é tratado pelo parser dedicado do próprio Crow-Eye.

## 📸 Capturas de Ecrã

Uma seleção da interface e das vistas de análise do Crow-Eye.

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

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

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

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

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

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

🎥 **Vídeo de demonstração:** [![Ver a demonstração](https://assets.kitploit.com/production/public/readmes/9931/01aa6e4b5fb8732512fe81143b1dcd87d908401369284bad8cfaf1b119fcbf41.jpg)](https://youtu.be/hbvNlBhTfdQ)

## 🚧 Roadmap

Trabalho planeado e em curso (ver [`RELEASE_NOTES.md`](https://github.com/ghassan-elsman/crow-eye/blob/main/RELEASE_NOTES.md) para alterações já lançadas):

- 📊 **Vistas GUI e relatórios avançados** — visualização e relatórios mais ricos.
- 🔄 **Diálogo de pesquisa melhorado** — filtragem avançada com suporte a linguagem natural.
- 🎯 **Mapeamento semântico melhorado** — mapeamento abrangente de campos em todos os tipos de artefactos.
- 📈 **Pontuação de correlação avançada** — pontuação de confiança refinada e explicável.
- ⚡ **Correlação paralela** — despacho por process-pool, ativado por padrão para cargas de trabalho grandes.

Tem uma ideia ou quer adicionar um artefacto? [Abra um issue](https://github.com/Ghassan-elsman/Crow-Eye/issues) ou veja [Contribuir](#-contribuir).

## 📚 Documentação

- **[TECHNICAL_DOCUMENTATION.md](https://github.com/ghassan-elsman/crow-eye/blob/main/TECHNICAL_DOCUMENTATION.md)** — arquitetura, componentes e guia de desenvolvimento.
- **[RELEASE_NOTES.md](https://github.com/ghassan-elsman/crow-eye/blob/main/RELEASE_NOTES.md)** — o que há de novo em cada lançamento (UBA, Narrative Map, backends Eye na nuvem, endurecimento de gestão de casos, …).
- **[Documentação do Correlation Engine](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/docs/CORRELATION_ENGINE_OVERVIEW.md)** — visão geral, motor, feathers, wings, pipelines.
- **[Arquitetura da timeline](https://github.com/ghassan-elsman/crow-eye/blob/main/timeline/ARCHITECTURE.md)** — internals do módulo de timeline.
- **[Arquitetura Eye](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/README.md)** e **[padrão GEP](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/docs/GEP_standard.md)** — o assistente de IA e o seu protocolo de governação.

## 🤝 Contribuir

Crow-Eye é construído como uma plataforma de investigação aberta, e contribuições são bem-vindas — novos parsers, regras de correlação, documentação e investigação de artefactos.

- **Contribuições gerais:** [CONTRIBUTING.md](https://github.com/ghassan-elsman/crow-eye/blob/main/CONTRIBUTING.md)
- **Correlation Engine (área prioritária):** [correlation_engine/CONTRIBUTING.md](https://github.com/ghassan-elsman/crow-eye/blob/main/correlation_engine/CONTRIBUTING.md)
- **Contacto:** [[email protected]](mailto:[email protected]) · ou abra um issue / pull request.

## 🌐 Website & Comunidade

- 🌍 **Website oficial:** [crow-eye.com](https://crow-eye.com/) — recursos, documentação e downloads.
- 💬 **Discord:** [Junte-se ao Discord do Crow-Eye](https://discord.gg/2vag2Udf) — ajuda direta, investigação de artefactos e anúncios de lançamentos.

## 📄 Licença

Crow-Eye é lançado sob a **[GNU General Public License v3.0](https://github.com/ghassan-elsman/crow-eye/blob/main/LICENSE)** (GPL-3.0). É livre de usar, estudar, partilhar e modificar sob os termos dessa licença.

## 📝 Citar o Crow-Eye

Se usar o Crow-Eye em trabalho académico, investigação publicada ou um relatório de caso, por favor cite-o:```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: Um Mecanismo de Forense para Windows* (GPL-3.0). https://github.com/Ghassan-elsman/Crow-Eye

Para citações de metodologia, o Protocolo Ghassan Elsman está documentado separadamente em [`eye/docs/GEP_standard.md`](https://github.com/ghassan-elsman/crow-eye/blob/main/eye/docs/GEP_standard.md).

## 💖 Apoio

O Crow-Eye é gratuito e de código aberto, construído e mantido por uma única pessoa. Se ele ajuda no seu trabalho, considere apoiar o projeto — isso financia diretamente novos parsers e pesquisas: **[SPONSORS.md](https://github.com/ghassan-elsman/crow-eye/blob/main/SPONSORS.md)** · **[GitHub Sponsors](https://github.com/sponsors/Ghassan-elsman)**.

## Créditos

Criado e mantido por **Ghassan Elsman**.