# Fluxos visuais com .catflow

> Monte análises em grafo com etapas, parsers, condições e reuniões; aprovações por revisão, artefatos rastreáveis, checkpoints e limites.

- Idioma: pt-BR
- URL canônica: https://netcattest.com/catsuite/docs/fluxos
- Seção: Fluxos visuais
- Atualizado: 2026-10-05
- Outro idioma (en): https://netcattest.com/catsuite/en/docs/workflows

Fluxos visuais transformam rotinas de análise em grafos reproduzíveis. Cada bloco recebe artefatos tipados, produz novos artefatos e registra duração, entradas, saídas, hashes e versões.

## Começar

1. Abra **Configurações → Extensões → Fluxos**.
2. Instale os modelos do laboratório e abra um fluxo.
3. Revise a aprovação e execute a fixture.
4. Toque na saída de uma etapa e depois na entrada da seguinte; apenas tipos compatíveis são aceitos.

A condição oferece rotas `true` e `false`, e a reunião espera as entradas selecionadas. Arraste, amplie, organize ou duplique blocos. O painel de propriedades fica na lateral em telas maiores e embaixo no celular.

## Tipos de bloco

| Bloco | Função |
|---|---|
| `capture` | entrada de tráfego capturado |
| `filter` | seleciona artefatos |
| `condition` | divide o fluxo em `true` e `false` |
| `join` | reúne ramos |
| `parser` | interpreta conteúdo por tipo MIME |
| `request` | envia requests aprovadas |
| `crawler` | percorre páginas com GET e HEAD |
| `storage` | persiste resultados |
| `report` | consolida relatório |
| `connector` | executa uma capacidade do [CatBridge](https://netcattest.com/catsuite/docs/catbridge) |
| `extension` | executa uma etapa registrada por extensão |

## Artefatos

| Tipo | Conteúdo típico |
|---|---|
| `http` | mensagem HTTP completa |
| `endpoint` | URL observada, com origem |
| `jwt` | claims decodificadas, sem verificação de assinatura |
| `secret` | candidato a segredo, mascarado |
| `analysis` | análise estruturada |
| `finding` | achado com severidade e confiança |
| `record` | registro genérico |
| `javascript` | fonte JavaScript estática |
| `openapi` | especificação OpenAPI |

O host gera identidade, SHA-256, origem, versões, fontes e proteção de cada artefato. Copiar uma entrada cria uma nova evidência ligada à anterior, e metadados fornecidos pelo script não substituem os do host.

## Registrar etapas e parsers

```js
cat.pipeline.registerStep({
  id: 'lab.inspecionar',
  title: {'pt-BR': 'Inspecionar', en: 'Inspect'},
  inputs: ['http'],
  outputs: ['http', 'analysis']
}, async ctx => {
  for (const entrada of ctx.inputs) {
    if (ctx.signal.aborted) return;
    ctx.emit('http', entrada.data);
    ctx.emit('analysis', {url: entrada.data.url, confidence: 'observed'});
  }
  ctx.progress(1);
});

cat.parsers.register({
  id: 'lab.json',
  title: {'pt-BR': 'Ler JSON', en: 'Parse JSON'},
  inputs: ['http'],
  outputs: ['record'],
  mimeTypes: ['application/json']
}, ctx => {
  for (const entrada of ctx.inputs) {
    if (!entrada.data.body.complete) throw new Error('E_BODY');
    ctx.emit('record', JSON.parse(cat.bytes.toText(entrada.data.body.bytes)));
  }
});
```

Declare `pipeline.step` ou `parsers` no manifesto e, para receber HTTP, também `traffic.read`. Apenas tipos declarados podem ser emitidos.

## Contexto da etapa

| Campo | Descrição |
|---|---|
| `ctx.inputs` | artefatos de entrada |
| `ctx.config` | configuração própria da etapa |
| `ctx.runId`, `ctx.nodeId` | identidade da execução e do bloco |
| `ctx.revisionId` | revisão aprovada em execução |
| `ctx.protection` | `PUBLIC`, `PROTECTED` ou `SECRET` |
| `ctx.restored` | estado do último checkpoint |
| `ctx.checkpoint(estado)` | grava até 32 KiB de JSON |
| `ctx.emit(tipo, dados)` | emite um artefato |
| `ctx.progress(valor)` | progresso de 0 a 1 |
| `ctx.signal.aborted` | indica cancelamento |

## Checkpoints e retomada

```js
cat.pipeline.registerStep({
  id: 'lab.retomar',
  title: {'pt-BR': 'Retomar', en: 'Resume'},
  inputs: ['record'],
  outputs: ['record']
}, async ctx => {
  let feitos = ctx.restored?.feitos || 0;
  for (; feitos < ctx.inputs.length; feitos++) {
    if (ctx.signal.aborted) return;
    ctx.emit('record', ctx.inputs[feitos].data);
    await ctx.checkpoint({feitos: feitos + 1});
  }
});
```

Resultados, operações e checkpoints são gravados de forma incremental. A retomada reutiliza etapas concluídas. Uma operação de resultado desconhecido nunca é reenviada automaticamente; repeti-la exige autorização explícita depois de revisar possíveis efeitos duplicados. Checkpoints não tornam transações externas idempotentes por si só.

## Aprovação e revisões

O Flow ID é permanente. A revisão é o SHA-256 da definição executável, das dependências e da política efetiva; nome e posição visual não entram nesse hash. Salvar ou exportar sem mudanças executáveis preserva a ativação. Alterar código, configurações, escopo, métodos, proteção, capacidades ou limites exige nova aprovação, e revisões anteriores ficam arquivadas.

Envios precisam de `network=true`, execução com envios, destino permitido e capacidade própria. O tráfego gerado tem `source=workflow`, `flowOrigin` e `pluginOrigin`, e não reinicia o fluxo.

## Falhas e histórico

- Uma falha bloqueia seus dependentes; ramificações independentes podem terminar.
- Um ramo não escolhido fica ignorado.
- O histórico mostra duração, progresso, entradas, saídas, erros, hashes e versões.
- A comparação identifica resultados adicionados ou removidos e mudanças de versões.
- Reproduzir cria uma execução nova, inicialmente sem rede.

## Limites

| Recurso | Padrão | Teto |
|---|---|---|
| Fluxos simultâneos | 2 | 4 |
| Blocos por fluxo | 32 | 128 |
| Conexões | 64 | 256 |
| Fila | 128 | 512 |
| Artefatos por execução | 1.000 | 5.000 |

Análises usam dois ambientes de 32 MiB, separados dos quatro ambientes do proxy. Uma execução tem até 15 minutos e tarefas de conector até 10 minutos. Saturação é registrada e não suspende o encaminhamento do proxy.

## Modelos incluídos

| Modelo | Etapas |
|---|---|
| Auditoria de identidade | Captura → JWT → Segredos → Autorização → Relatório |
| Mapa de API | Crawler → JavaScript → Endpoints → OpenAPI → Relatório |
| Ramificações | Condição sobre Authorization, ramos de JWT e segredos, reunião e relatório |
| Auditoria de API | Captura → httpx → Katana → reunião → comparação OpenAPI → Schemathesis → relatório |

> [!NOTA]
> Os modelos começam no modo laboratório, sem envios. Identificadores numéricos encontrados pela auditoria de identidade são hipóteses de IDOR/BOLA e não demonstram acesso indevido.