DORSAL ML Training Pipeline

Repositório de treino de modelos do Dorsal em 3 camadas:

1. Camada 1 (attack_*.onnx): classificador supervisionado global de ataques.
2. Camada 2 (gateway): baseline comportamental local por cliente.
3. Camada 3 (global_anomaly_*.onnx): modelo global de anomalia com telemetria agregada.

Este repo entrega pipeline pronto para você rodar quando quiser com dados estáticos, DAST, snapshots de agentes e telemetria.

1) Pré-requisitos

• Linux/macOS com bash, git, python3.11+.
• uv instalado (curl -LsSf https://astral.sh/uv/install.sh | sh).
• Opcional: docker (para Juice Shop e build do gateway).

2) Setup inicial (uma vez)

cd /home/abraham/tools/dorsal-ml
make venv
make install-dev
make bootstrap
STATIC_PROFILE=full make setup-data
make smoke
make test

Isso cria .venv, estrutura de diretórios (data/, models/, reports/, keys/, logs/) e prepara fontes estaticas. STATIC_PROFILE=full inclui a base obrigatoria (UNSW-NB15, CIC-IDS, Juice/DVWA traffic dirs, ModSecurity CRS, NVD snapshot e Common Crawl local).

3) Treino da Camada 1 (ataques conhecidos)

3.0 Ordem recomendada (estatico -> lab -> realworld)

1. Rode bootstrap estatico completo (STATIC_PROFILE=full make setup-data + make layer1).
2. Depois suba o lab e gere trafego legitimo + ataques (LAB_PLAN.md).
3. Por fim rode make layer1-realworld para validacao com distribuicao operacional.

attack-zap-baseline, attack-zap-graphql e attack-ai-simulated nao exigem dataset pre-gerado; exigem apenas lab ativo e labs/.env.lab configurado.

Observacao importante:

• attack-ai-simulated gera artefatos compativeis com Shannon/Strix, mas nao executa os agentes oficiais.
• Shannon/Strix oficiais seguem modo manual-first (voce roda os agentes e salva outputs em data/raw/lab/strix e data/raw/lab/shannon).

3.1 Fluxo rápido (profile classic)

make layer1

Saídas principais:

• data/curated/attack_*.parquet
• models/attack_*.onnx
• models/attack_latest.onnx
• reports/attack_*.benchmark.json

3.1.1 Fluxo estático completo (fontes obrigatórias)

STATIC_PROFILE=full \
TARGET_APP=lab_multi \
LAB_RUN_ID=static_bootstrap \
ATTACK_RATIO=0.20 \
make layer1

Esse fluxo usa as novas fontes estaticas quando os caminhos locais existem:

• data/academic/UNSW-NB15
• data/academic/CIC-IDS
• data/raw/static/juiceshop
• data/raw/static/dvwa
• data/coreruleset
• data/nvd/nvd_api_snapshot.json
• data/commoncrawl

3.2 Fluxo com DAST e agentes (opcional)

Coloque exports/snapshots locais (incluindo runs oficiais de Shannon/Strix, quando usados):

• data/dast/burp_export.xml
• data/dast/zap_report.json
• data/dast/acunetix_export.json
• data/raw/strix/...
• data/raw/shannon/...

Execute:

BURP_FILE=./data/dast/burp_export.xml \
ZAP_FILE=./data/dast/zap_report.json \
ACUNETIX_FILE=./data/dast/acunetix_export.json \
STRIX_RUNS_DIR=./data/raw/strix \
SHANNON_SESSIONS_DIR=./data/raw/shannon \
make layer1

3.3 Fluxo recomendado para cenario real (menos falso positivo)

Use o workflow de duas fases:

• treino com distribuicao 80/20 (ataque/legitimo controlado);
• validacao final com distribuicao proxima da operacao (ex.: 98/2).

make layer1-realworld

Variaveis principais (opcionais):

TRAIN_ATTACK_RATIO=0.20 \
REALWORLD_ATTACK_RATIO=0.02 \
REALWORLD_MAX_FPR=0.01 \
HARD_NEGATIVES_PATH=./data/raw/hard_negatives \
HARD_NEGATIVE_RATIO=0.25 \
SLICE_GATES_CONFIG=./configs/slice_gates.example.json \
make layer1-realworld

Saidas adicionais:

• data/curated/attack_rw_*.train.parquet
• data/curated/attack_rw_*.realworld.parquet
• reports/attack_rw_*.realworld_summary.json
• reports/attack_rw_*.promotion_decision.json

Playbook detalhado:

• docs/layer1_realworld_playbook.md
• LAB_PLAN.md (lab completo com gateway + apps + trafego legitimo + campanhas de ataque)
• labs/docker-compose.layer1-lab.yml (stack de laboratorio para coleta realista)

3.4 Schema v2 de dataset (metadados de campanha e confianca)

O build da Camada 1 agora inclui metadados adicionais no parquet:

• scenario_type
• target_app
• attack_family
• attack_technique
• validation_tier
• lab_run_id
• effect_outcome
• is_replay

Campos novos para trilha de benigno dificil:

• scenario_type=hard_negative
• effect_outcome=benign_confirmed

Tambem e gerado um manifesto JSON de dataset (audit trail):

• default: reports/dataset_manifest_<campaign_id>.json
• override: --manifest-path ou DATASET_MANIFEST_PATH

Exemplo com metadados de campanha:

TARGET_APP=crapi \
LAB_RUN_ID=lab_20260313 \
IS_REPLAY=0 \
make layer1

Exemplo de uso direto:

.venv/bin/python -m training.build_dataset \
  --payloads-dir ./data/PayloadAllTheThings \
  --seclists-dir ./data/SecLists \
  --unsw-nb15-dir ./data/academic/UNSW-NB15 \
  --cic-ids-dir ./data/academic/CIC-IDS \
  --juiceshop-traffic-dir ./data/raw/static/juiceshop \
  --dvwa-traffic-dir ./data/raw/static/dvwa \
  --modsec-crs-dir ./data/coreruleset \
  --nvd-snapshot-file ./data/nvd/nvd_api_snapshot.json \
  --commoncrawl-dir ./data/commoncrawl \
  --require-static-full \
  --campaign-id campaign_crapi_v1 \
  --target-app crapi \
  --lab-run-id lab_20260313 \
  --manifest-path ./reports/campaign_crapi_v1.manifest.json \
  --output ./data/curated/campaign_crapi_v1.parquet

Exemplo com hard negatives e perfil de cenario:

.venv/bin/python -m training.build_dataset \
  --payloads-dir ./data/PayloadAllTheThings \
  --seclists-dir ./data/SecLists \
  --hard-negatives-path ./data/raw/hard_negatives \
  --hard-negative-ratio 0.25 \
  --scenario-profile b2b \
  --campaign-id campaign_crapi_v2 \
  --output ./data/curated/campaign_crapi_v2.parquet

Impacto no gateway nesta fase:

• nenhum ajuste de runtime e necessario;
• o artefato ONNX de inferencia permanece compativel.

Guia detalhado de upgrade:

• docs/p0_schema_upgrade.md
• docs/p1_dataset_governance.md

4) Treino da Camada 3 (global anomaly)

4.1 Com telemetria local de arquivo

TELEMETRY_INPUT=./data/telemetry/telemetry_real.parquet make layer3

4.2 Sem conector pronto (fallback sintético)

make layer3

Saídas:

• data/raw/telemetry_*.parquet
• models/global_anomaly_*.onnx (preferencial)
• models/global_anomaly_*.pkl (fallback se conversão ONNX falhar)
• models/global_anomaly_latest.onnx ou models/global_anomaly_latest.pkl

5) Rodar tudo em sequência

make all

Equivalente a: bootstrap -> Camada 1 -> Camada 3.

6) Bundle seguro para gateway (.onnx protegido)

Gerar chaves de assinatura:

.venv/bin/python -m training.bundle_packager gen-keys \
  --private-key ./keys/model_signing_private.b64 \
  --public-key ./keys/model_signing_public.b64

Rodar layer1 com bundle automático:

export DORSAL_MODEL_SIGNING_PRIVATE_KEY=./keys/model_signing_private.b64
export DORSAL_MODEL_KEK='troque-por-segredo-forte'
make layer1

Bundle gerado em models/bundles/<model_name>/ com:

• model.enc
• manifest.json
• signature.sig
• feature_map.json
• bundle.meta.json

7) Retreino semanal

make weekly

Comportamento:

• prepara workspace;
• atualiza fontes públicas;
• executa Camada 1 e Camada 3;
• opcionalmente build/push de gateway se ENABLE_GATEWAY_BUILD=1.

Logs ficam em logs/weekly_retrain_*.log.

8) Configuração por .env

Use configs/pipeline.env.example:

cp configs/pipeline.env.example .env
set -a; source .env; set +a

Depois rode qualquer target (make layer1, make layer3, make weekly).

9) Comandos diretos dos módulos (sem scripts)

.venv/bin/python -m training.build_dataset --help
.venv/bin/python -m training.train_attack_model --help
.venv/bin/python -m training.validate_model --help
.venv/bin/python -m training.benchmark_inference --help
.venv/bin/python -m training.train_anomaly_model --help
.venv/bin/python -m training.promotion_gate --help
.venv/bin/python scripts/fetch_telemetry.py --help

10) Critérios de aceite recomendados

• Camada 1: precision >= 0.92, recall >= 0.85, fpr <= 0.03.
• Camada 1 (slice gates): aplicar thresholds por scenario_type, validation_tier, target_app e attack_family.
• Benchmark ONNX: validar P50/P95/P99 com lote 1 e 32.
• Camada 3: usar holdout por tenant quando houver labels reais.
• Nunca usar dorsal_score como label de treino.

11) Estrutura de artefatos

data/
  raw/
  intermediate/
  curated/
  dast/
models/
  attack_*.onnx
  global_anomaly_*.onnx
  bundles/
reports/
keys/
logs/