Ruleforge Guide

Briefing para CTO / líder técnico: comece por Posicionamento-e-metricas e o Home. Esteira: Esteira-de-aprendizado-de-regras.

Ruleforge Guide (hero-ruleforge)

Motor de busca evolutiva determinístico (sem chamada de LLM no loop de scoring) que valida e evolui o catálogo de regras contra um corpus rotulado. Ver a explicação conceitual completa em docs/ARCHITECTURE.md § hero-ruleforge.

Comandos

# precisão/recall/F1 de cada regra contra o corpus golden
node packages/ruleforge/src/cli.ts evaluate

# roda a busca evolutiva numa regra específica
node packages/ruleforge/src/cli.ts evolve HERO-SEC-0327-weak-hash

# roda em todas as regras que têm mutações registradas
node packages/ruleforge/src/cli.ts evolve-all

evaluate mostra TP/FP/FN/TN e lista cada caso que a regra atual erra (com o motivo, quando anotado no corpus). evolve/evolve-all rodam a busca genética (seed fixa = reprodutível) e terminam com uma decisão: PROMOTED (a regra deveria ser atualizada em packages/contracts/src/rules.ts) ou REJECTED (com o motivo — sem ganho de F1, precisão abaixo do mínimo, ou regressão detectada).

Estrutura do corpus (packages/ruleforge/corpus/golden.json)

{
  "id": "hash-02",
  "ruleId": "HERO-SEC-0327-weak-hash",
  "expected": "match",
  "code": "h = hashlib.new('md5')",
  "note": "opcional — por que este caso existe"
}

expected é "match" (a regra deve disparar) ou "no_match" (não deve — inclua traps de falso-positivo aqui, não só casos óbvios).

Adicionando uma mutação (proposta de melhoria de regra)

Edite packages/ruleforge/src/mutations.ts:

"HERO-SEC-XXXX": [
  {
    id: "nome-da-mutacao",
    description: "o que essa mutação muda e por quê",
    apply: (pattern) => ({ ...pattern, regex: `${pattern.regex}|novo_padrao_alternativo` }),
  },
],

Depois rode evolve <ruleId> — a mutação só é promovida se melhorar o F1 sem regredir nenhum caso que a regra atual já acerta, com precisão ≥ 0.85. Uma mutação proposta não vira regra automaticamente — esse é o ponto central do design (ver o caso real da regra de SQL injection em JS, onde uma mutação foi proposta e corretamente rejeitada).

Fechando o ciclo: quando uma mutação é PROMOTED

1. Aplique manualmente a mudança de regex/unless em packages/contracts/src/rules.ts (copie o padrão resultante do output do evolve).
2. Remova a mutação já promovida de mutations.ts (evita reaplicá-la sobre si mesma numa próxima rodada) — deixe um comentário com a data e o ganho de F1.
3. Rebuild: npm run build:contracts.
4. Rode evaluate de novo para confirmar F1 = 1.00 (ou o valor esperado) na regra atualizada.
5. Rode o scanner nos exemplos relevantes para confirmar que o comportamento em produção não regrediu.

Adicionando uma regra nova do zero

1. Adicione a entrada em RULES (packages/contracts/src/rules.ts): id, languages, severity, type, cwe/owasp, pattern.regex.
2. Adicione um sddTemplateId — se for um template novo, defina-o em SDD_TEMPLATES (packages/contracts/src/sdd.ts).
3. Adicione pelo menos 2 casos ao corpus golden: um match (positivo real) e um no_match (trap de falso-positivo plausível).
4. npm run build:contracts && node packages/ruleforge/src/cli.ts evaluate — confirme F1 = 1.00 antes de considerar a regra pronta.