Automação, integrações e ferramentas para desenvolvedores

Plexicus Automation: gatilhos, etapas e o modelo de fluxo

O Plexicus Automation funciona ao lado do ciclo Validar → Entender → Remediar do Proof-Driven AppSec. Ele aplica as decisões recorrentes da sua equipe (“corrija isto agora”, “abra um ticket para aquilo”, “pergunte antes ao líder de AppSec”) a cada achado correspondente. Abra-o na barra lateral esquerda principal; a página se chama Automations, e os caminhos deste módulo começam nela, como Automations New automation .

Imagine uma injeção de SQL com severidade Critical no handler de login da sua API de faturamento. Um fluxo pode solicitar um pull request de remediação, aguardar a aprovação do seu líder de AppSec, abrir uma issue no Jira e publicar uma notificação no app. Nenhum merge acontece sozinho; a sua equipe revisa o pull request.

Gatilho → Decisão → Ação → Registro

Todo fluxo tem quatro partes:

1. Gatilho. Um evento inicia uma execução. Cada fluxo tem exatamente um gatilho.
2. Decisão. Etapas de condição encaminham a execução por severidade, tipo de achado, repositório ou dados do webhook. Cada etapa também tem um caminho de sucesso e um caminho de erro.
3. Ação. Etapas de ação solicitam uma remediação, abrem um ticket, notificam pessoas ou chamam um sistema conectado.
4. Registro. As execuções ficam armazenadas com logs por etapa, as alterações nos fluxos vão para o registro de auditoria (módulo 10) e os tickets ficam vinculados na linha do tempo do achado.

Gatilhos

Gatilho	Uma execução começa quando	Observações
New finding	O Plexicus cria um achado	Filtros opcionais: Severity, Finding type, Repository ID
Finding enriched	O Plexicus adiciona contexto a um achado existente	Os mesmos filtros opcionais
Finding reopened	Um scan detecta de novo um achado depois que ele foi resolvido	É executado a cada reabertura, depois que a execução anterior termina
Webhook	Uma requisição assinada chega à Ingress URL do fluxo	Abordado na aula 3
Schedule	Um agendamento cron é disparado	Cron de 5 campos mais um fuso horário (UTC por padrão)
Manual	Alguém inicia a execução com Run now	Aparece como “Manual only” na lista

Para definir o gatilho, selecione o nó Trigger no canvas e edite o painel dele; os gatilhos não são arrastados da paleta. Depois de salvar, reabra o painel do gatilho para conferir se os seus filtros ou o agendamento foram mantidos, e faça um dry run do fluxo antes que um administrador o ative.

Duas regras definem os fluxos de eventos de achado. Primeiro, um fluxo é executado automaticamente no máximo uma vez por achado. A exceção é um fluxo cujo gatilho é Finding reopened: ele é executado a cada reabertura, desde que a execução anterior dele para aquele achado tenha terminado. Um fluxo New finding ou Finding enriched não é executado de novo em uma reabertura; por isso, crie um fluxo Finding reopened separado para agir sobre achados reabertos. Segundo, Deduplicate by fingerprint agrupa os achados que compartilham o mesmo fingerprint de segredo na execução que já está em andamento, de modo que uma chave de API vazada leve a uma única rotação, e não a cinco.

Etapas

Etapa	O que faz	Configurações obrigatórias
Remediation	Solicita uma remediação por IA, como um pull request para revisão (módulo 7)	Tipo de remediação
Ticket	Abre um ticket em um provedor como o Jira	Provedor de ticket (chave do projeto opcional)
Notify	Cria uma notificação no app	Canal de notificação, usado como título; mensagem opcional
Wait for approval	Pausa a execução até que alguém aprove ou rejeite	Função de aprovador e tempo limite opcionais, definidos em segundos
Condition (if)	Segue a aresta “yes” quando a condição é verdadeira; caso contrário, segue a aresta “no”	Condição
Condition (switch)	Segue o primeiro caso correspondente, ou a aresta de erro se nenhum corresponder	Casos
Connector	Chama uma capacidade de uma integração registrada	Tipo de conector, capacidade, nome do conector

Cinco etapas de rotação de segredos alimentam o template Secret rotation. O Notify gera apenas notificações no app. Para chegar a outro sistema, use uma etapa Ticket ou uma etapa Connector que chame uma integração HTTP API.

As condições usam JSON logic restrito. A condição abaixo foi pensada para corresponder a achados Critical:

{ "==": [{ "var": "finding.severity" }, "Critical"] }

Operadores permitidos: ==, !=, >, <, >=, <=, and, or, not, in e var. Você pode testar campos do achado, como severity, type, status e repository_id, e dados do webhook como trigger.payload.FIELD. Os valores são comparados de forma exata, diferenciando maiúsculas de minúsculas. Prefira o construtor visual de condições e faça um dry run com um achado que você sabe que é Critical antes de confiar em uma condição escrita à mão.

Como criar fluxos com segurança

O Plexicus coloca várias salvaguardas entre uma ideia e um fluxo ativo: rascunhos desativados, dry runs, ativação apenas por administradores, versões e histórico de execuções.

Três formas de começar

Templates. Automations Start from a template oferece fluxos prontos:

• Auto-remediate + ticket: em um novo achado, solicita uma remediação por IA, abre um ticket no Jira e envia uma notificação no app se alguma etapa falhar.
• Conditional remediation: achados High e Critical seguem para a remediação automatizada com um pull request, e todo o resto vira um ticket no Jira para triagem.
• Secret rotation: rotaciona um segredo vazado, armazena-o no HashiCorp Vault, abre um PR em rascunho que substitui o valor fixo no código por uma variável de ambiente, verifica o novo valor lendo-o de volta, aguarda a aprovação de um administrador e então promove o PR. Qualquer falha abre um ticket no Jira.

Do prompt ao fluxo. Automations New from prompt transforma uma descrição em inglês simples, de até 4.000 caracteres, em um rascunho, usando o modelo de IA configurado para a sua organização. Por exemplo: “When a critical finding is created, wait for admin approval, then open a Jira ticket.” O rascunho lista todos os sistemas externos que ele vai acessar em This flow will contact:, e nada é salvo até você clicar em Confirm and save draft.

Editor visual. Automations New automation abre três painéis: a paleta de etapas à esquerda (Triggers, Logic, Actions e Integrations), o canvas no meio e o inspetor à direita, com as abas Config, Last run I/O e Notes. Arraste uma etapa para o canvas ou clique duas vezes para adicionar uma. O inspetor marca cada etapa como Configured ou Incomplete. A versão atual adiciona desfazer e refazer e um construtor de agendamento com uma prévia da próxima execução.

Seja qual for a forma de começar, você obtém um rascunho desativado, que não faz nada até um administrador ativá-lo. O Plexicus valida o fluxo quando você salva, e problemas como duas arestas que saem do mesmo ramo para destinos diferentes aparecem em This flow has validation errors.

Dry runs (execuções simuladas)

Um dry run percorre o fluxo inteiro e simula cada etapa que tocaria um sistema externo. Cada etapa registra o que teria feito, por exemplo “Would create jira ticket in project SEC”, e os parâmetros que parecem segredos são mascarados. Os dry runs funcionam em rascunhos, não contam para os limites de execução e aparecem no histórico de execuções com o selo Dry run. Informe um Finding ID na barra superior do editor e clique em Dry run. Na versão atual, você também pode testar fluxos de agendamento e de webhook sem um finding ID.

Ativação e versões

Somente os administradores da organização podem criar, editar, ativar ou excluir fluxos; os demais usuários têm acesso somente leitura e ainda podem consultar o histórico de execuções.

A ativação verifica de novo cada conexão que o fluxo usa, incluindo as etapas Connector e o provedor da etapa Ticket. Se um teste falhar, você vê Activation failed com o conector que falhou. Dependendo do seu plano, o número de fluxos ativos e de execuções manuais pode ser limitado.

Editar um fluxo ativo e clicar em Save new version cria a próxima versão. As execuções em andamento continuam na versão com que começaram, e as versões anteriores são mantidas. Depois de salvar, confira a coluna Status e ative a nova versão se ela aparecer como Inactive.

Histórico de execuções, status e aprovações

Abra Automations Edit Runs para ver Automation, Finding, Status e Started de cada execução. Expanda uma linha para ver os logs por etapa ou use Replay para percorrer uma execução passo a passo, com a entrada e a saída de cada etapa.

Status	Significado
Running	As etapas estão em execução
Waiting	Pausada em uma etapa Wait for approval
Completed	O fluxo chegou ao fim, por um caminho de sucesso ou por um caminho de falha
Failed	A execução parou com um erro ou durou mais do que o máximo de 30 dias
Cancelled	A execução foi interrompida antes de terminar

As execuções em Waiting mostram Approve, Reject e Cancel. Approve continua pelo caminho de sucesso. Reject e um timeout seguem o caminho de erro. Cancel se comporta como Reject: a execução continua pelo caminho de erro. O timeout é definido em segundos, e o padrão é de 7 dias (604.800 segundos). Se a etapa indicar uma função de aprovador, somente os usuários com essa função podem aprovar ou rejeitar.

Ticketing e integrações de saída

O Plexicus se conecta a outros sistemas em dois lugares: Settings Integrations reúne os conectores de ticketing por trás do botão Create Ticket dos achados, e a página de integrações do Automation reúne os sistemas que os seus fluxos usam.

Conectar o Jira e o ServiceNow

Abra Settings Integrations Ticket Management , que lista Jira, ServiceNow e Webhook.

O Jira tem quatro abas: Credentials, Stage Configuration, Test Connection e Create Ticket. A aba Credentials pede um Email Address, um API Token e a Server URL da sua instância do Jira Cloud, como company.atlassian.net.

O ServiceNow pede um OAuth Token e a sua Instance URL, como https://dev12345.service-now.com. O Plexicus abre incidentes no estado New com a categoria Security. Os conectores que você pode habilitar dependem do seu plano.

Os dois conectores têm dois estágios, que você ativa ou desativa em Stage Configuration:

• Create Issue cobre os tickets criados a partir de achados.
• Pull Request se aplica quando o Plexicus abre um pull request de remediação. Um ticket vinculado recebe um comentário com o link do PR e é marcado como em andamento. Se ainda não houver um ticket vinculado, o Plexicus cria um.

Cada estágio tem um Priority Mapping (por padrão, o Jira mapeia Critical para Highest, e o ServiceNow mapeia Critical para “1 - Critical”) e um Field Mapping opcional, que preenche campos do ticket com dados do achado usando placeholders como %Finding.title%. O estágio também oferece opções de filtro; teste-as em um achado de exemplo antes de confiar nelas. Execute Test Connection depois de salvar as credenciais.

Criar um ticket a partir de um achado

Na página de detalhes de um achado, o menu suspenso Create Ticket lista cada provedor configurado. O Jira abre um formulário com Service, Issue Type (Bug, Task, Story, Epic), Project Key e um Priority Override opcional. O ServiceNow abre o incidente na hora, usando os mapeamentos do estágio. O Webhook envia o achado para o endpoint que você configurou.

O Plexicus vincula o ID, a URL e o status do ticket ao achado e adiciona uma entrada “ticket created” à linha do tempo dele. Não presuma que o ticket será fechado sozinho quando o achado for resolvido; feche-o pelo fluxo de trabalho normal da sua ferramenta de tickets.

Webhooks de saída e integrações do Automation

O conector Webhook envia achados para um endpoint HTTP que você controla. O assistente dele tem quatro passos: Settings (Webhook Name, Webhook URL, HTTP Method POST ou PUT, Data Format), Authentication (None, Basic ou Bearer Token), Headers e Preview, onde você confere o payload e envia um teste.

A página de integrações do Automation lista os sistemas externos conectados que as suas automações podem usar: HashiCorp Vault, Kubernetes Secrets, Jira, ServiceNow, Source control, HTTP API e Outgoing webhook. O campo Credentials reference guarda uma referência a credenciais armazenadas, nunca o segredo em si. Cada card mostra Unverified, Healthy ou Unhealthy, e Save and test verifica uma nova integração na hora. Não é possível excluir uma integração que um fluxo ainda usa.

Webhooks de entrada assinados

Um fluxo com gatilho Webhook recebe a sua própria Ingress URL. No painel do gatilho, clique em Generate new secret e copie o segredo imediatamente, porque ele é mostrado uma única vez. Gerar um novo segredo substitui o anterior na hora; por isso, atualize todos os chamadores ao mesmo tempo. O chamador assina o corpo bruto da requisição com HMAC-SHA256 usando esse segredo e envia o digest hexadecimal no header X-Plexicus-Signature, no formato sha256=HEX_DIGEST. O painel inclui uma requisição de exemplo pronta. Em um shell, a assinatura fica assim:

BODY='{"service":"billing-api","event":"deploy"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $NF}')
curl -X POST "$INGRESS_URL" \
  -H "Content-Type: application/json" \
  -H "X-Plexicus-Signature: sha256=$SIG" \
  --data "$BODY"

Assine exatamente os bytes que você envia. Se o chamador serializar o JSON de novo depois de assinar, a assinatura deixa de corresponder.

Resposta HTTP	Rótulo em Recent deliveries	Significado
202	Accepted	Uma nova execução começa para cada entrega aceita
401	Invalid signature	A assinatura está ausente ou não corresponde ao corpo e ao segredo atual, ou ainda não foi gerado nenhum segredo
409	Inactive	O fluxo está inativo ou não usa um gatilho Webhook
400	Invalid JSON	O corpo não é um JSON válido
413	Payload too large	O corpo excede o limite de tamanho
429	Rate limited	Entregas demais para a organização

Acesso para desenvolvedores: tokens de API e a API REST

Scripts, pipelines de CI e agentes de IDE acessam o Plexicus por meio de tokens. Escolher o token certo mantém o acesso rastreável e fácil de revogar.

Tokens de API pessoais

Acesse Settings API Tokens . Informe um Token name, escolha uma Expiration (30 days, 90 days ou No expiration) e clique em Generate token. O valor aparece uma única vez, em “Save your token now”. Copie-o e clique em I’ve saved it. A tabela Active tokens lista Name, Created, Expires e Type, com Revoke em cada linha.

Um token pessoal não tem escopos próprios. Ele age como você, com a sua função e as suas permissões na organização. Um token criado por um desenvolvedor pode fazer o que esse desenvolvedor pode fazer no console, e nada além disso. A revogação de um token tem efeito imediato, e qualquer chamada posterior com ele retorna 401. A criação de tokens fica gravada no registro de auditoria.

Boas práticas:

• Crie um token por ferramenta (um script de relatórios, a sua IDE, um job de CI), para poder revogar um sem quebrar os outros.
• Prefira uma validade de 30 ou 90 dias. Se escolher No expiration, confira a coluna Expires, porque um prazo padrão longo ainda pode ser aplicado.

O token do Plexalyzer da organização

O token do Plexalyzer, também chamado de token do scanner de CI/CD, pertence à organização, e não a uma pessoa. Ele autentica o scanner Plexalyzer nos seus pipelines. Os administradores o criam, com uma data de expiração opcional, em Settings Plexalyzer Token . Em algumas versões, o mesmo token aparece na seção do token do scanner de CI/CD em Settings API Tokens . O módulo 3 mostra como armazená-lo como o segredo de CI PLEXALYZER_TOKEN e como configurar os pipelines.

O Plexicus não tem um token de nível organizacional para chamadas gerais à API. Mesmo um script que deve durar mais do que o acesso de uma pessoa precisa de um token de API pessoal; por isso, escolha o dono dele de forma deliberada, dê ao token um nome próprio e revogue-o quando ele não for mais necessário.

Token	Pertence a	Use para
Token de API pessoal	Você, com a sua função	Scripts, integrações, o MCP server
Token da CLI	Você, com a sua função	O Plexicus TUI, criado por plexicus login
Token do Plexalyzer	A organização	Apenas o scanner Plexalyzer no CI/CD

Fundamentos da API REST

Toda requisição envia Authorization: Bearer seguido do seu token e Accept: application/json, além de Content-Type: application/json em POST, PUT e PATCH. A URL base do SaaS está no guia da API em docs.plexicus.ai; uma implantação auto-hospedada usa a sua própria URL. Os caminhos dos recursos ficam no plural, como /repositories, /findings, /remediations, /repository-scans e /automations.

curl -H "Authorization: Bearer $PLEXICUS_API_TOKEN" \
     -H "Accept: application/json" \
     "$PLEXICUS_API_URL/findings?filters%5Bseverity%5D=critical,high&limit=25"

As listas usam paginação por cursor. Uma resposta contém items, total e um link next; passe o cursor dele para obter a próxima página. A maioria dos endpoints retorna 25 itens por página por padrão, e limit altera esse valor.

As ações de longa duração retornam 202 e continuam em segundo plano. POST /repository-scans com um repository_id e um scan_type igual a app ou sbom inicia um scan. POST /remediations com um finding_id solicita uma correção por IA; consulte GET /remediations?finding_id=... periodicamente até que ele retorne o diff e as orientações (404 significa que ainda não está pronto). As ações de IA consomem a sua cota de uso de IA, exibida em Settings Billing e no menu do seu perfil (módulos 7 e 10). Você também pode iniciar um fluxo pelo endpoint de execuções de /automations, para até 100 achados por chamada e, opcionalmente, como dry run.

Os erros usam o formato Problem Details da RFC 7807. Um 401 significa que o token é inválido, expirou ou foi revogado. Um 403 significa que o token funciona, mas a sua função ou o seu plano não permite a ação. Um 429 significa que você atingiu um limite de taxa; tente de novo com backoff exponencial.

Como trabalhar no terminal e na IDE

Duas ferramentas para desenvolvedores levam os achados para onde você já trabalha: o Plexicus TUI, no seu terminal, e o Plexicus MCP server, na sua IDE.

O Plexicus TUI

Baixe o binário para macOS Apple Silicon, macOS Intel ou Linux x86-64 na página GitHub Releases de github.com/plexicus/tui. Depois:

plexicus --version   # confirma a instalação
plexicus login       # entra pelo navegador
plexicus             # navega pelos achados e pelos repositórios conectados

Na primeira execução, um assistente de configuração pede a URL do seu servidor Plexicus.

Tecla	Ação
F	Abrir os filtros
/	Buscar
Enter	Abrir os detalhes do achado
r	Solicitar uma remediação por IA
p	Criar um pull request

Pressione r, revise o diff e só então pressione p. O pull request passa pela sua revisão normal, e a sua equipe mantém o controle do merge.

O que o plexicus login faz

plexicus login abre o navegador na página de autorização do Plexicus. Entre, se necessário, inclusive com 2FA, se estiver ativado. A página mostra “Authorizing Plexicus CLI…” e depois “CLI authorized”. Nos bastidores, o Plexicus cria um token de API pessoal chamado CLI - YYYY-MM-DD, válido por 365 dias, e o seu navegador o entrega à CLI em um endereço local 127.0.0.1. A CLI o armazena em ~/.config/plexicus.

Como é um token pessoal comum, ele aparece em Settings API Tokens , onde você o revoga. plexicus logout apenas exclui a cópia local. Em uma máquina headless, sem navegador, gere em vez disso um token pessoal e exporte-o como PLEXICUS_API_TOKEN.

O Plexicus MCP server

O Plexicus MCP server (pacote plexicus-mcp) roda localmente na sua máquina e dá a um agente de IDE compatível com MCP acesso à API REST do Plexicus com o seu token pessoal. Os clientes documentados incluem Cursor, VS Code, Windsurf e um agente de programação de linha de comando. A configuração tem três passos:

1. Escolha um cliente.
2. Escolha um método de inicialização: uvx plexicus-mcp (recomendado), pipx run plexicus-mcp ou pip install plexicus-mcp.
3. Configure o seu token e conecte. Depois que você gera um token, a seção Use with your IDE (MCP) da página API Tokens mostra trechos já preenchidos: um comando de uma linha para clientes de linha de comando e uma configuração JSON para Cursor, VS Code e Windsurf.

{
  "mcpServers": {
    "plexicus": {
      "command": "uvx",
      "args": ["plexicus-mcp"],
      "env": {
        "PLEXICUS_API_TOKEN": "YOUR_TOKEN",
        "PLEXICUS_API_URL": "YOUR_API_URL"
      }
    }
  }
}

PLEXICUS_API_TOKEN é obrigatório. PLEXICUS_API_URL é opcional; o padrão é a API do SaaS, e ele é definido em implantações auto-hospedadas. Com um token inválido, as ferramentas retornam “Authentication failed — the API token is invalid, expired or revoked.”

O servidor expõe 10 ferramentas. Somente request_scan e generate_remediation alteram alguma coisa; as demais são somente leitura.

Ferramenta	Finalidade
get_current_repository	Associar o git remote do seu workspace a um repositório do Plexicus
list_repositories, get_repository	Navegar pelos repositórios, pelas contagens por severidade e pelo estado dos scans
list_findings, get_finding	Filtrar por severidade, status, CWE ou título e depois ler os detalhes
request_scan, get_scan_status	Iniciar um scan de app ou de SBOM e acompanhá-lo
generate_remediation, get_remediation	Solicitar uma correção por IA e obter o diff e as orientações
get_security_posture	Totais de toda a conta e os repositórios de maior risco

Ele também traz três prompts guiados (fix_finding, triage_findings, security_review) e dois recursos: plexicus://repositories e um recurso de achados por repositório. Toda ferramenta retorna um resumo legível, além dos dados brutos da API.

Principais pontos

• Todo fluxo tem um gatilho, etapas com caminhos de sucesso e de erro e uma execução registrada. Um fluxo é executado uma vez por achado; só um fluxo com gatilho Finding reopened volta a ser executado, a cada reabertura.
• Os fluxos começam como rascunhos desativados. Faça um dry run, peça a um administrador que os ative (a ativação testa as conexões de novo) e leia os logs por etapa, porque Completed pode incluir uma etapa que falhou.
• Jira, ServiceNow e webhooks de saída ficam em Settings Integrations Ticket Management . Os webhooks de entrada precisam ser assinados com HMAC-SHA256 usando o segredo atual do fluxo.
• Os tokens de API pessoais agem com a sua própria função; o token do Plexalyzer da organização serve apenas para o scanner. Use um token por ferramenta e revogue os que você não usa.
• plexicus login cria um token pessoal revogável para o Plexicus TUI. O MCP server dá aos agentes de IDE 10 ferramentas, e as correções sugeridas nunca viram pull requests sem você.