### Configuração do Ambiente

**IMPORTANTE:** Você deve configurar as variáveis de ambiente antes de iniciar a aplicação. A aplicação requer que `NEO4J_PASSWORD` seja definida.

Crie um arquivo `.env` na raiz do projeto:```bash
# Copy the sample file
cp infra/env.sample .env

# Edit .env and set your actual passwords
nano .env

**Nota:** O aplicativo falhará ao iniciar se `NEO4J_PASSWORD` não estiver definida. Consulte [Correção de Variáveis de Ambiente](https://github.com/blevene/bandjacks/blob/HEAD/ENV_VARIABLES_FIX.md) para mais detalhes.

### Iniciando os Serviços```bash
# Start the FastAPI backend server
uv run uvicorn bandjacks.services.api.main:app --reload --port 8000

# In another terminal, start the Next.js frontend
cd ui && npm run dev

# Access the applications
open http://localhost:8000/docs    # API documentation
open http://localhost:3000         # Frontend UI

> **Nota:** A CLI requer que variáveis de ambiente sejam definidas (NEO4J_PASSWORD, etc.). Execute a partir da raiz do projeto onde o `.env` está localizado.

### Comandos de Consulta```bash
# Search for threat intelligence
uv run python -m bandjacks.cli.main query search "ransomware encryption techniques" --top-k 10

# Explore graph relationships
uv run python -m bandjacks.cli.main query graph "attack-pattern--abc123" --depth 2

### Extração de Documentos```bash
# Extract CTI from a document
uv run python -m bandjacks.cli.main extract document ./report.pdf --confidence-threshold 80 --show-evidence

### Comandos de Fluxo de Trabalho```bash
# Process a directory of reports with analytics
uv run python -m bandjacks.cli.main workflow process-reports ./reports/ --workers 3 --analyze --export-dir ./results/

# Bulk export all analytics data
uv run python -m bandjacks.cli.main workflow bulk-export --export-dir ./analytics_export/

## Interface do Frontend

O frontend Next.js fornece uma interface moderna para trabalhar com o sistema.

### Gerenciamento de Relatórios (`/reports`)
- **Lista de Relatórios**: Visualizar todos os relatórios ingeridos com status e contagens de técnicas
- **Novo Relatório** (`/reports/new`): Carregar arquivos PDF/TXT ou colar conteúdo do relatório
- **Detalhe do Relatório** (`/reports/[id]`): Visualizar técnicas, entidades e evidências extraídas
- **Interface de Revisão** (`/reports/[id]/review`): Fluxo de revisão com humano no loop

### Análise de Coocorrência (`/analytics/cooccurrence`)

> **Nota:** Estas páginas requerem dados `AttackEpisode` no Neo4j. Processe os relatórios pelo pipeline de extração primeiro, ou use `POST /v1/flows/build` para gerar episódios a partir de dados de conjuntos de intrusão.

- **Página Central**: Visão geral com contagens de episódios/técnicas/atores
- **Pares Principais** (`/pairs`): Pares de técnicas coocorrentes com métricas NPMI/Lift
- **Condicional** (`/conditional`): Probabilidades condicionais P(B|A)
- **Pacotes** (`/bundles`): Pacotes de técnicas frequentemente coocorrentes
- **Atores** (`/actors`): Padrões de técnicas específicas de atores
- **Pontes** (`/bridging`): Técnicas usadas em múltiplos atores

### Saúde do Sistema (`/health`)
- Status de saúde em tempo real de todos os componentes (Neo4j, OpenSearch, Redis)
- Estatísticas de cache e uso de memória
- Endpoints de saúde compatíveis com Kubernetes

### Iniciando o Frontend```bash
cd ui
npm run dev     # Development mode with hot reload
npm run build   # Production build
npm run start   # Start production server

# Ensure backend is running
# API_URL defaults to http://localhost:8000/v1

### 2. Extraindo Técnicas de Relatórios

Extraia técnicas do MITRE ATT&CK de relatórios de inteligência de ameaças:```python
import httpx
import time

# For small reports (<5KB) - synchronous processing
response = httpx.post(
    "http://localhost:8000/v1/reports/ingest",
    json={
        "content": "APT29 used spearphishing emails with malicious attachments...",
        "title": "APT29 Campaign Analysis",
        "config": {
            "use_optimized_extractor": True,
            "span_score_threshold": 0.7,
            "top_k": 5
        }
    }
)

result = response.json()
print(f"Extracted {len(result['extraction']['techniques'])} techniques")

# For large reports (>5KB) - asynchronous processing
response = httpx.post(
    "http://localhost:8000/v1/reports/ingest_async",
    json={
        "content": large_report_text,
        "title": "Large Report Analysis"
    }
)

job_id = response.json()["job_id"]

# Check job status
status = httpx.get(f"http://localhost:8000/v1/reports/jobs/{job_id}/status")
while status.json()["status"] == "processing":
    time.sleep(2)
    status = httpx.get(f"http://localhost:8000/v1/reports/jobs/{job_id}/status")

# Get results from completed job
result = status.json()["result"]
print(f"Extracted {result['techniques_count']} techniques in {result['elapsed_time']} seconds")

## Arquitetura do Pipeline de Extração

O pipeline de extração do Bandjacks utiliza uma arquitetura multiagente para extrair inteligência de ameaças estruturada:

### Componentes do Pipeline

O pipeline de extração usa 9 agentes especializados em sequência:

#### 1. **EntityExtractionAgent** - Reconhecimento de Entidades
- Extrai atores de ameaças, malwares, ferramentas e campanhas
- Executa primeiro para fornecer contexto para a extração de técnicas
- Usa few-shot prompting com validação de esquema JSON
- Lida com documentos divididos em blocos com extração progressiva em janela

#### 2. **SpanFinderAgent** - Detecção de Texto Comportamental
- Detecta trechos de texto contendo comportamentos de ameaça usando 14 padrões de regex específicos por tática
- Identifica IDs de técnica explícitos (T1566.001) e padrões comportamentais
- Pontua trechos por confiança com indexação de palavras-chave
- Sem chamadas de LLM — pura correspondência de padrões para velocidade

#### 3. **BatchRetrieverAgent** - Recuperação de Candidatos
- Usa busca vetorial KNN do OpenSearch para encontrar técnicas candidatas por trecho
- Desduplica textos de trechos idênticos antes da codificação para evitar embeddings redundantes
- Retorna top-k candidatos com pontuações de similaridade para cada trecho

#### 4. **Pre-filter** - Redução de Trechos
- Limita trechos a `max_spans_per_technique` (padrão 2) por técnica candidata
- Mantém os trechos com maior pontuação por candidato para preservar a qualidade da evidência
- Reduz chamadas de LLM do mapeador em ~46% com perda mínima de técnicas

#### 5. **DiscoveryAgent** - Descoberta por LLM (condicional)
- Acionado quando a confiança do recuperador é baixa (<0,7 média)
- Usa LLM para descobrir técnicas que a busca vetorial não encontrou
- Única chamada em lote para todos os trechos de baixa confiança

#### 6. **BatchMapperAgent** - Mapeamento de Técnicas (LLM)
- Processa trechos em lotes de até 10 (`MAX_MAPPER_BATCH_SIZE`, padrão reduzido de 25 em 2026-05 para limitar truncamento em LLMs em nuvem)
- Extrai TODAS as técnicas relevantes por trecho com pontuações de confiança
- Usa validação de esquema JSON para saída estruturada

#### 7. **EvidenceVerifierAgent** - Validação de Evidências
- Verificação baseada em padrões de citações e referências de linhas
- Pontua a qualidade da evidência em uma escala de 40 a 100 pontos
- Sem chamadas de LLM — regex e correspondência de texto

#### 8. **ConsolidatorAgent** - Consolidação de Evidências
- Mescla técnicas duplicadas encontradas em vários trechos
- Agrega evidências usando similaridade de Jaccard (limiar >85%)
- Produz lista final de técnicas com pontuações de confiança consolidadas

#### 9. **AttackFlowSynthesizer** - Geração de Sequência (LLM)
- Analisa marcadores temporais ("primeiro", "depois", "então")
- Infere relações causais a partir da narrativa
- Cria objetos STIX Attack Flow com arestas probabilísticas
- Recorre a modelagem de co-ocorrência quando a sequência não é clara

### Otimizações de Desempenho

- **Blocos Inteligentes**: Documentos divididos em blocos de 2KB com sobreposição
- **Processamento em Lote**: Mapeador processa até 25 trechos por chamada de LLM
- **Processamento Paralelo**: Blocos processados simultaneamente em threads de trabalho
- **Cache de Respostas**: Respostas de LLM armazenadas em cache para evitar chamadas duplicadas
- **Término Antecipado**: Extrações de alta confiança pulam verificação
- **TechniqueCache**: Todas as técnicas ATT&CK carregadas na inicialização para consultas O(1)
- **Pre-filter**: Limita trechos por técnica candidata antes do mapeador LLM (46% menos chamadas)
- **Embedding em Lote**: Embeddings de técnicas gerados em lotes (2-5x mais rápido)
- **Pool de Conexões**: Conexões Neo4j/OpenSearch compartilhadas entre requisições
- **Lotes UNWIND**: Escritas Neo4j agrupadas via UNWIND (30-40 consultas → 6-7)
- **Pré-aquecimento do Modelo**: Modelo de embedding carregado na inicialização para evitar latência de cold-start

### Tempos de Processamento

| Tamanho do Documento | Tempo de Processamento | Técnicas Extraídas |
|----------------------|------------------------|---------------------|
| Pequeno (<5KB)       | 10-20 segundos         | 5-10 técnicas       |
| Médio (5-15KB)       | 20-40 segundos         | 10-15 técnicas      |
| Grande (>15KB)       | 30-60 segundos         | 15-25 técnicas      |

## Análise de Co-ocorrência

Bandjacks fornece análises para entender relacionamentos entre técnicas. 

> **Nota:** As análises requerem dados de `AttackEpisode` e `AttackAction` no Neo4j. Estes são criados quando:
> - Relatórios são processados pelo pipeline de extração
> - Fluxos de ataque são construídos via `/v1/flows/build`
> - Pacotes STIX com episódios de ataque são ingeridos
>
> Se nenhum episódio existir, as análises retornarão resultados vazios.

### Co-ocorrência Global

Calcular quais técnicas frequentemente aparecem juntas em todos os episódios de ataque:```python
# Via API
response = httpx.post(
    "http://localhost:8000/v1/analytics/cooccurrence/global",
    json={"min_support": 2, "min_episodes_per_pair": 2, "limit": 50}
)

for pair in response.json()["pairs"]:
    print(f"{pair['name_a']} + {pair['name_b']}: NPMI={pair['npmi']:.3f}")

### Pacotes de Técnicas

Identifique pacotes de técnicas que co-ocorrem frequentemente (3-5 técnicas):```python
response = httpx.post(
    "http://localhost:8000/v1/analytics/cooccurrence/bundles",
    json={"min_support": 3, "min_size": 3, "max_size": 5}
)

## Sistema de Revisão Humano-no-Loop

O Bandjacks inclui um sistema abrangente de revisão para validar a inteligência extraída:

### Interface de Revisão Unificada

O sistema de revisão apresenta todos os itens extraídos em uma única interface:```typescript
// Review workflow
1. Upload/ingest report → Extraction pipeline runs
2. Navigate to /reports/{id}/review
3. Review extracted items across three tabs:
   - Entities (threat actors, malware, tools)
   - Techniques (ATT&CK mappings with evidence)
   - Attack Flow (sequenced steps)
4. Take actions on each item:
   - Approve: Accept as correct
   - Reject: Mark as incorrect
   - Edit: Modify details (name, confidence, etc.)
5. Submit all decisions atomically

### 4. Procurando por Técnicas

Procure por técnicas ATT&CK usando linguagem natural:```python
# Vector search for similar techniques
response = httpx.post(
    "http://localhost:8000/v1/search/ttx",
    json={
        "query": "ransomware that encrypts files and demands payment",
        "top_k": 5
    }
)

techniques = response.json()["results"]
for tech in techniques:
    print(f"{tech['external_id']}: {tech['name']} (score: {tech['score']:.2f})")

### 6. Gerando Modelos de AttackFlow

Crie modelos de co-ocorrência que mostram como agentes de ameaças utilizam técnicas em conjunto:```python
# Generate flow for a specific intrusion set (e.g., APT29)
response = httpx.post(
    "http://localhost:8000/v1/flows/build",
    json={
        "intrusion_set_id": "intrusion-set--899ce53f-13a0-479b-a0e4-67d46e241542"
    }
)

flow = response.json()
print(f"Generated flow '{flow['name']}' with {len(flow['steps'])} techniques")
print(f"Co-occurrence edges: {len(flow['edges'])}")

AttackFlow models utilizam **co-ocorrência** em vez de ordenação sequencial, já que conjuntos de intrusão não possuem informações de sequência inerentes. As técnicas são conectadas por:
- **Arestas intra-tática**: Entre técnicas na mesma tática da kill chain
- **Arestas entre táticas**: Entre técnicas através de táticas adjacentes
- **Padrões hub-and-spoke**: Para grandes conjuntos de técnicas, evitando explosão de arestas

Consulte o [Guia de Geração de AttackFlow](https://github.com/blevene/bandjacks/blob/HEAD/docs/ATTACKFLOW_GENERATION.md) para uso detalhado.

## Formatos de Entrada Suportados

O pipeline de extração suporta múltiplos formatos de entrada:

- **Texto Simples** - Conteúdo textual direto
- **Markdown** - Documentos markdown formatados
- **PDF** - Via extração com pdfplumber
- **HTML** - Via análise com BeautifulSoup
- **JSON** - Extração de dados estruturados

### Extrair de Texto Simples```python
# Direct text extraction
plaintext_report = """
The threat actors used spearphishing emails with malicious attachments.
After gaining access, they deployed Mimikatz to harvest credentials and
used RDP for lateral movement across the network.
"""

result = asyncio.run(run_agentic_v2_async(plaintext_report, {
    "cache_llm_responses": True,
    "single_pass_threshold": 500
}))

### Extrato do PDF```python
import pdfplumber
from bandjacks.llm.extraction_pipeline import run_extraction_pipeline

# Read PDF with pdfplumber (recommended)
with pdfplumber.open("threat_report.pdf") as pdf:
    text = ""
    for page in pdf.pages:
        page_text = page.extract_text()
        if page_text:
            text += page_text + "\n"

# Extract techniques using extraction pipeline
result = run_extraction_pipeline(text, {
    "use_optimized_extractor": True,
    "span_score_threshold": 0.7,
    "chunk_size": 2000
}, source_id="threat_report")

print(f"Found {len(result['techniques'])} techniques")

results.append({
    "file": pdf_file.name,
    "techniques": list(result["techniques"].keys()),
    "count": len(result["techniques"])
})

### Construindo Fluxos de Ataque```python
# Generate attack flow from extracted techniques
response = httpx.post(
    "http://localhost:8000/v1/flows/build",
    json={
        "source_id": "report-123",
        "technique_ids": ["T1566.001", "T1059.001", "T1003.001"]
    }
)

flow = response.json()
print(f"Generated flow with {len(flow['steps'])} steps")

## Endpoints da API

### Endpoints Principais

- `POST /v1/stix/load/attack` - Carregar dados MITRE ATT&CK
- `POST /v1/reports/ingest` - Ingestão síncrona de relatórios (<5KB)
- `POST /v1/reports/ingest_async` - Ingestão assíncrona de relatórios (>5KB)
- `POST /v1/reports/ingest/upload` - Enviar arquivos PDF/TXT
- `GET /v1/reports/jobs/{id}/status` - Verificar status do job
- `POST /v1/reports/{id}/unified-review` - Enviar decisões de revisão
- `POST /v1/search/ttx` - Pesquisar por técnicas
- `GET /v1/graph/technique/{id}` - Obter detalhes da técnica

### Fluxos de Ataque

- `POST /v1/flows/build` - Gerar modelos de coocorrência AttackFlow
- `GET /v1/flows/{flow_id}` - Recuperar detalhes específicos do AttackFlow
- `POST /v1/flows/search` - Pesquisar por fluxos de ataque semelhantes
- `GET /v1/flows/dump` - Exportar fluxos em massa com paginação e filtragem

### Análises

- `GET /v1/analytics/cooccurrence/global` - Métricas globais de coocorrência
- `GET /v1/analytics/cooccurrence/conditional` - Probabilidades condicionais
- `GET /v1/analytics/cooccurrence/bundles` - Pacotes de técnicas
- `GET /v1/analytics/cooccurrence/actor` - Padrões específicos de atores
- `GET /v1/coverage/gaps` - Lacunas de cobertura de técnicas

### Defesa e Detecção

- `GET /v1/defense/technique/{id}` - Obter recomendações defensivas
- `GET /v1/detections/technique/{id}` - Estratégias de detecção
- `POST /v1/sigma/validate` - Validar regras Sigma

### Monitoramento

- `GET /health` - Verificação básica de saúde
- `GET /health/live` - Sonda de vivacidade Kubernetes
- `GET /health/ready` - Sonda de prontidão Kubernetes
- `GET /health/components/{component}` - Saúde de componente individual
- `GET /v1/costs/stats` - Rastreamento de custos LLM (agregado diário por modelo)
- `GET /v1/cache/stats` - Obter estatísticas de cache LLM
- `POST /v1/cache/clear` - Limpar cache LLM
- `GET /v1/compliance/report` - Métricas de conformidade
- `GET /v1/drift/status` - Status de detecção de deriva
- `GET /v1/ml-metrics/performance` - Métricas do modelo ML

### Atores e Procedência

- `GET /v1/actors` - Listar atores de ameaça
- `GET /v1/actors/{id}` - Obter detalhes do ator
- `GET /v1/provenance/{object_id}` - Procedência do objeto
- `GET /v1/provenance/{object_id}/lineage` - Cadeia de linhagem completa
- `GET /v1/provenance/{object_id}/evidence` - Trechos de evidência

### Recursos Apenas da API (Sem UI/CLI)

Estes endpoints são totalmente funcionais, mas são acessados apenas via REST API (sem páginas frontend ou comandos CLI):

#### Simulação de Caminhos de Ataque
- `POST /v1/simulation/paths` - Simular caminhos de ataque a partir de técnica/grupo inicial
- `POST /v1/simulation/predict` - Prever técnicas prováveis seguintes dado o estado atual
- `POST /v1/simulation/whatif` - Análise de cenário hipotético para situações defensivas
- `POST /v1/simulation/scenario` - Simular a partir de conjuntos de grupos/software/técnicas
- `GET /v1/simulation/statistics/{technique_id}` - Estatísticas de uso da técnica
- `GET /v1/simulation/groups/{group_id}/patterns` - Padrões de ataque do grupo
- `POST /v1/simulation/compare` - Comparar múltiplos caminhos de ataque

#### Política MDP e Implantação
- `POST /v1/simulate/rollout` - Simulação de implantação PTG
- `POST /v1/simulate/mdp` - Calcular política de defesa ótima MDP
- `GET /v1/simulate/models` - Listar modelos PTG disponíveis

#### Detecção e Monitoramento de Deriva
- `GET /v1/drift/status` - Status atual de deriva em todas as métricas
- `POST /v1/drift/analyze` - Executar análise de deriva com limites personalizados
- `GET /v1/drift/alerts` - Obter alertas de deriva ativos
- `POST /v1/drift/alerts/{alert_id}/acknowledge` - Reconhecer alerta
- `GET /v1/drift/metrics/{metric_name}` - Obter métrica de deriva específica

#### Rastreamento de Métricas ML
- `POST /v1/ml-metrics/prediction` - Registrar previsão do modelo para rastreamento
- `POST /v1/ml-metrics/review` - Registrar métricas de decisão de revisão
- `POST /v1/ml-metrics/coverage-gap` - Registrar lacuna de cobertura
- `GET /v1/ml-metrics/performance` - Obter métricas de desempenho do modelo
- `GET /v1/ml-metrics/dashboard` - Exportar métricas do painel

#### Notificações
- `GET /v1/notifications/history` - Obter histórico de notificações
- `POST /v1/notifications/clear-history` - Limpar histórico de notificações
- `GET /v1/notifications/config` - Obter configuração de notificações
- `POST /v1/notifications/test` - Enviar notificação de teste

#### Gerenciamento de Atualização de Vetores
- `GET /v1/vectors/status` - Status do sistema de atualização de vetores
- `GET /v1/vectors/metrics` - Métricas detalhadas de atualização de vetores
- `POST /v1/vectors/update` - Acionar manualmente atualização de vetores
- `POST /v1/vectors/process-batch` - Forçar processamento em lote
- `DELETE /v1/vectors/queue` - Limpar fila de atualização pendente
- `GET /v1/vectors/health` - Verificação de saúde do sistema de vetores

#### Lista de Ignorar Entidades
- `GET /v1/ignorelist` - Obter status atual da lista de ignorar
- `POST /v1/ignorelist/add` - Adicionar entidade à lista de ignorar
- `DELETE /v1/ignorelist/remove` - Remover entidade da lista de ignorar
- `POST /v1/ignorelist/reload` - Recarregar lista de ignorar do disco

#### Revisão de Padrões Candidatos
- `GET /v1/review/candidates` - Listar padrões de ataque candidatos
- `POST /v1/review/candidates` - Criar padrão candidato
- `GET /v1/review/candidates/{id}` - Obter detalhes do candidato
- `POST /v1/review/candidates/{id}/approve` - Aprovar candidato
- `POST /v1/review/candidates/{id}/reject` - Rejeitar candidato
- `GET /v1/review/candidates/{id}/similar` - Encontrar padrões semelhantes
- `GET /v1/review/candidates/stats/summary` - Estatísticas de candidatos

### Documentação Completa da API

Acesse a documentação completa da API em:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
- OpenAPI JSON: http://localhost:8000/openapi.json

## Arquitetura

### Estrutura do Projeto```
bandjacks/
├── bandjacks/
│   ├── analysis/         # Graph analysis & interdiction
│   │   ├── graph_analyzer.py
│   │   └── interdiction.py
│   ├── analytics/        # Co-occurrence & clustering
│   │   ├── clustering.py
│   │   ├── cooccurrence.py
│   │   └── detection_bundles.py
│   ├── cli/              # Command-line interface
│   │   ├── main.py       # CLI entry point
│   │   ├── batch_extract.py
│   │   ├── formatters.py
│   │   └── workflows.py
│   ├── config/           # Configuration files
│   │   └── entity_ignorelist.yaml
│   ├── core/             # Core utilities
│   │   ├── cache.py      # Redis caching
│   │   ├── connection_pool.py
│   │   └── query_optimizer.py
│   ├── llm/              # Extraction pipeline
│   │   ├── extraction_pipeline.py
│   │   ├── agents_v2.py  # Core extraction agents
│   │   ├── chunked_extractor.py
│   │   ├── optimized_chunked_extractor.py
│   │   ├── entity_extractor.py
│   │   ├── flow_builder.py
│   │   ├── cache.py      # LLM response caching
│   │   └── experimental/ # Experimental features
│   ├── loaders/          # Data loading & indexing
│   │   ├── attack_catalog.py
│   │   ├── attack_upsert.py
│   │   ├── opensearch_index.py
│   │   ├── hybrid_search.py
│   │   └── sigma_loader.py
│   ├── monitoring/       # Metrics & monitoring
│   │   ├── compliance_metrics.py
│   │   ├── defense_metrics.py
│   │   ├── drift_detector.py
│   │   └── ml_metrics.py
│   ├── services/         # API & services
│   │   ├── api/          # FastAPI application
│   │   │   ├── main.py
│   │   │   ├── routes/   # API route handlers
│   │   │   └── middleware/
│   │   ├── technique_cache.py
│   │   └── actor_cache.py
│   ├── simulation/       # Attack simulation
│   │   ├── attack_simulator.py
│   │   ├── mdp_solver.py
│   │   └── ptg_rollout.py
│   └── store/            # Data stores
│       ├── report_store.py
│       ├── candidate_store.py
│       └── review_store.py
├── ui/                   # Next.js frontend
│   ├── app/              # App Router pages
│   │   ├── reports/      # Report management
│   │   ├── analytics/    # Analytics dashboards
│   │   └── health/       # Health monitoring
│   ├── components/       # React components
│   └── hooks/            # Custom React hooks
├── tests/                # Test suite
├── samples/              # Sample reports
├── scripts/              # Utility scripts
└── docs/                 # Documentation

**Prioridade do provedor:** API Local > Gemini > OpenAI > Proxy LiteLLM.
Quando um servidor local está configurado, provedores em nuvem são automaticamente adicionados como alternativas de fallback.

#### Exemplos comuns de servidores locais

| Servidor | `LOCAL_LLM_API_BASE` | `LOCAL_LLM_MODEL` |
|--------|---------------------|-------------------|
| vLLM | `http://host:8000/v1` | `mistralai/Mistral-Nemo-Instruct-2407` |
| llama.cpp | `http://host:8080/v1` | `mistral-nemo` |
| Ollama | `http://host:11434/v1` | `mistral-nemo` |
| LM Studio | `http://host:1234/v1` | `mistral-nemo` |
| LocalAI | `http://host:8080/v1` | `mistral-nemo` |

### Configuração de Extração

O sistema utiliza um único pipeline assíncrono de alto desempenho com opções configuráveis:```python
{
    "cache_llm_responses": True,         # Enable LLM caching (default: True)
    "single_pass_threshold": 500,        # Max words for single-pass (default: 500)
    "early_termination_confidence": 90,  # Skip verification above this (default: 90)
    "disable_discovery": False,          # Disable LLM discovery agent
    "max_spans": 20,                     # Maximum spans to process
    "span_score_threshold": 0.7,         # Minimum span quality
    "top_k": 5,                          # Candidates per span

    # Cost optimization options
    "max_spans_per_technique": 2,        # Pre-filter: max spans per candidate technique (0=disable, default=2)
    "enable_span_dedup": False,          # Text-based span dedup before mapping (default=False)
}

### Limiares de Confiança

Controle a qualidade da extração:```python
{
    "confidence_threshold": 50.0,  # Minimum confidence (0-100)
    "auto_ingest": True            # Auto-add high-confidence results
}

### Exemplo de Resposta de Saúde```json
{
  "status": "healthy",
  "timestamp": "2025-01-28T17:43:30.184036Z",
  "version": "1.0.0",
  "components": {
    "neo4j": {
      "status": "healthy",
      "latency_ms": 5
    },
    "opensearch": {
      "status": "degraded",
      "cluster_status": "yellow",
      "indices": {
        "attack_nodes": false,
        "bandjacks_reports": true
      }
    },
    "redis": {
      "status": "healthy",
      "latency_ms": 2,
      "memory_mb": 1.69
    },
    "caches": {
      "status": "healthy",
      "technique_cache": {
        "count": 993,
        "loaded": true
      },
      "actor_cache": {
        "count": 145,
        "loaded": true
      }
    },
    "system": {
      "status": "healthy",
      "memory": {
        "available_gb": 8.84,
        "percent_used": 72.4
      },
      "disk": {
        "available_gb": 353.11,
        "percent_used": 2.9
      },
      "cpu": {
        "percent_used": 7.7
      }
    }
  }
}

## Otimização de Desempenho

### Cache

O sistema inclui cache automático de respostas LLM para melhor desempenho:```python
# Check cache statistics
response = httpx.get("http://localhost:8000/v1/cache/stats")
stats = response.json()
print(f"Cache hit rate: {stats['hit_rate']}")

# Clear cache if needed
httpx.post("http://localhost:8000/v1/cache/clear")

## Segurança

### Validação de Entrada

- **Prevenção de Injeção Cypher**: Todos os endpoints de consulta a grafos validam os parâmetros `relationship_types` fornecidos pelo usuário contra uma lista de permissões de tipos de relacionamento conhecidos (USES, MITIGATES, HAS_TACTIC, etc.) mais um padrão regex estrito (`^[A-Z][A-Z0-9_]*$`). Entrada inválida retorna 400 antes da construção da consulta.
- **Validação de Esquema JSON**: Respostas do LLM validadas contra esquemas JSON para impedir que dados malformados entrem no pipeline.
- **Validação ADM**: Todo conteúdo STIX deve passar pela validação do Modelo de Dados ATT&CK antes da ingestão.

### Autenticação & Autorização

- **Autenticação JWT**: Middleware opcional para autenticação de API (`JWTAuthMiddleware`)
- **Limitação de Taxa**: Limitação de taxa por endpoint com limites configuráveis
- **CORS**: Compartilhamento de recursos de origem cruzada configurável

## Funcionalidades Avançadas

### Rastreamento de Proveniência

Cada entidade extraída inclui proveniência completa:```python
# Get provenance for an object
response = httpx.get(
    "http://localhost:8000/v1/provenance/attack-pattern--abc123"
)

### Análise de Cobertura

Analise sua cobertura de inteligência de ameaças:```python
# Get coverage analysis
response = httpx.get("http://localhost:8000/v1/analytics/coverage")
coverage = response.json()

print(f"Summary: {coverage['summary']}")
for tactic in coverage['tactics']:
    print(f"  {tactic['tactic']}: {tactic['coverage_percentage']}%")

## Status das Funcionalidades

Esta secção fornece transparência sobre o estado de implementação de várias funcionalidades:

### Totalmente Funcional ✅
- **Pipeline de Extração de Relatórios** - A extração de técnicas baseada em LLM funciona de ponta a ponta
- **Carregamento MITRE ATT&CK** - Carregar dados ATT&CK empresariais/móveis/ICS no Neo4j
- **Pesquisa Vetorial** - Pesquisa semântica baseada em OpenSearch para técnicas
- **Sistema de Revisão** - Fluxo de trabalho de revisão com intervenção humana via API e UI
- **Monitorização de Saúde** - Verificações de saúde dos componentes e sondas Kubernetes
- **Comandos CLI de Consulta/Administração** - Pesquisa, travessia de grafos, gestão de cache
- **Geração de Fluxos de Ataque** - Construção de fluxos baseada em co-ocorrência para conjuntos de intrusão
- **Simulação de Ataque** - Simulação de caminhos baseada em MDP via `/simulation/*` e `/simulate/*`
- **Relatórios de Cobertura** - Relatórios JSON para perspetivas executiva, técnica, tática, operacional

### Funcional com Dependências de Dados ⚠️
- **Análise de Co-ocorrência** - Requer nós `AttackEpisode` do processamento de relatórios
- **Análise de Atores** - Requer episódios atribuídos a conjuntos de intrusão
- **Pacotes de Técnicas** - Requer dados suficientes de episódios para mineração de padrões
- **Comandos CLI de Análise** - Funcionam mas retornam vazios se não existirem episódios

### Apenas API (Sem UI/CLI) 🔌
Estas são funcionalidades totalmente implementadas acessíveis apenas via REST API:
- **Simulação de Caminhos de Ataque** - Rotas `/simulation/*` para previsão de caminhos e análise "what-if"
- **Resolvedor de Políticas MDP** - `/simulate/mdp` para cálculo de política de defesa ótima
- **Detecção de Deriva** - Rotas `/drift/*` para monitorização de deriva na qualidade dos dados
- **Métricas ML** - `/ml-metrics/*` para acompanhamento do desempenho do modelo ao longo do tempo
- **Gestão de Vetores** - `/vectors/*` para gestão de embeddings vetoriais
- **Lista de Ignorar Entidades** - `/ignorelist/*` para filtrar entidades de falsos positivos
- **Padrões Candidatos** - `/review/candidates/*` para candidatos a novas técnicas
- **Notificações** - `/notifications/*` para configuração e histórico de alertas
- **Proveniência** - `/provenance/*` para rastreamento de linhagem de extração
- **Conformidade** - `/compliance/*` para relatórios de métricas de conformidade

### Experimental (em `llm/experimental/`) 🧪
- **PTG (Grafo de Ameaças Probabilístico)** - Lógica central implementada, testes limitados
- **Integração Judge** - Validação de sequências baseada em LLM
- **Simulador de Fluxo de Ataque** - Motor de simulação baseado em fluxos
- **Extrator de Sequências** - Extrair sequências de fluxos

### Removido/Limpo 🗑️
As seguintes funcionalidades fictícias foram removidas da API:
- ~~Análise de Cobertura de Plataforma~~ - Retornava dados fictícios fixos
- ~~Análise de Tendências~~ - Retornava dados sintéticos aleatórios
- ~~Exportação de Relatórios CSV/PDF~~ - Retornava 501; agora apenas JSON
- ~~Inferência de Sequências Gemini~~ - Era um stub 501; use `/sequence/propose` em vez disso

### Matriz de Conectividade

| Área de Funcionalidade | UI Frontend | CLI | REST API |
|------------------------|-------------|-----|----------|
| Gestão de Relatórios | ✅ | ✅ | ✅ |
| Fluxo de Revisão | ✅ | ✅ | ✅ |
| Pesquisa (TTX) | ✅ | ✅ | ✅ |
| Análise de Co-ocorrência | ✅ | ✅ | ✅ |
| Análise de Cobertura | ✅ | - | ✅ |
| Monitorização de Saúde | ✅ | - | ✅ |
| Deteções/Sigma | ✅ | - | ✅ |
| Fluxos de Ataque | ✅ | - | ✅ |
| Sobreposição de Defesa | ✅ | - | ✅ |
| Sequências/PTG | ✅ | - | ✅ |
| Atores | ✅ | - | ✅ |
| Simulação de Ataque | - | - | ✅ |
| Deteção de Deriva | - | - | ✅ |
| Métricas ML | - | - | ✅ |
| Gestão de Vetores | - | - | ✅ |
| Lista de Ignorar Entidades | - | - | ✅ |
| Padrões Candidatos | - | - | ✅ |
| Notificações | - | - | ✅ |
| Proveniência | - | - | ✅ |
| Conformidade | - | - | ✅ |

### Páginas do Frontend
| Página | Estado | Notas |
|--------|--------|-------|
| `/reports` | ✅ A funcionar | Listar, criar, ver relatórios |
| `/reports/[id]/review` | ✅ A funcionar | Fluxo de revisão completo |
| `/analytics/cooccurrence` | ⚠️ Dependente de dados | Mostra KPIs se existirem episódios |
| `/analytics/cooccurrence/pairs` | ⚠️ Dependente de dados | Chama API real |
| `/analytics/cooccurrence/bundles` | ⚠️ Dependente de dados | Chama API real |
| `/analytics/cooccurrence/actors` | ⚠️ Dependente de dados | Chama API real |
| `/health` | ✅ A funcionar | Estado de saúde em tempo real |

## Resolução de Problemas

### Problemas Comuns

1. **Falha na conexão com OpenSearch**
   - Certifique-se de que o OpenSearch está em execução: `curl http://localhost:9200`
   - Verifique se o índice existe: `curl http://localhost:9200/bandjacks_attack_nodes-v1`

2. **Falha na conexão com Neo4j**
   - Verifique se o Neo4j está em execução: `neo4j status`
   - Certifique-se de que `NEO4J_PASSWORD` está definido no ficheiro `.env`
   - Garanta que a palavra-passe corresponde à sua instância Neo4j
   - Se vir "NEO4J_PASSWORD environment variable is required", precisa defini-la no seu ficheiro `.env`

3. **Baixa precisão de extração**
   - Certifique-se de que está a usar o método `agentic_v2`
   - Verifique se a chave da API LLM é válida
   - Confirme que o nome do modelo está correto (gemini-flash-latest)

4. **Erros de timeout**
   - Aumente as definições de timeout para documentos grandes
   - Considere dividir relatórios muito grandes

5. **Frontend não está a conectar à API**
   - Certifique-se de que a API está em execução na porta 8000
   - Verifique as definições de CORS na configuração da API

### Modo de Depuração

Ativar registo detalhado:```python
import logging
logging.basicConfig(level=logging.DEBUG)

# Run extraction with debug output
result = run_agentic_v2(text, config)

### Contribuindo

1. Faça um fork do repositório
2. Crie uma branch de funcionalidade
3. Faça suas alterações
4. Execute os testes: `uv run pytest`
5. Execute a verificação de lint: `uv run ruff check`
6. Envie um pull request

### Qualidade do Código```bash
# Format code
uv run ruff format

# Check linting
uv run ruff check

# Type checking
uv run mypy bandjacks