Automatización, integraciones y herramientas para desarrolladores

Plexicus Automation: disparadores, pasos y el modelo de flujos

Plexicus Automation funciona junto al ciclo Validar → Entender → Remediar de Proof-Driven AppSec. Aplica las decisiones recurrentes de tu equipo (“corrige esto ya”, “abre un ticket para eso”, “consulta antes al responsable de AppSec”) a cada hallazgo que encaje. Ábrelo desde la barra lateral izquierda principal; la página se titula Automatizaciones, y las rutas de este módulo empiezan ahí, como Automatizaciones Nueva automatización .

Imagina una inyección SQL crítica en el handler de login de tu API de facturación. Un flujo puede solicitar un pull request de remediación, esperar a que tu responsable de AppSec lo apruebe, abrir una incidencia en Jira y publicar una notificación en la aplicación. Nada se fusiona por sí solo; tu equipo revisa el pull request.

Disparador → Decisión → Acción → Registro

Todo flujo tiene cuatro partes:

1. Disparador. Un evento inicia una ejecución. Cada flujo tiene exactamente un disparador.
2. Decisión. Los pasos de condición enrutan la ejecución según la severidad, el tipo de hallazgo, el repositorio o los datos del webhook. Además, cada paso tiene una ruta de éxito y una ruta de error.
3. Acción. Los pasos de acción solicitan una remediación, abren un ticket, notifican a personas o llaman a un sistema conectado.
4. Registro. Las ejecuciones se guardan con logs por paso, los cambios en los flujos van al registro de auditoría (módulo 10) y los tickets quedan vinculados en la línea de tiempo del hallazgo.

Disparadores

Disparador	Una ejecución empieza cuando	Notas
Nuevo hallazgo	Plexicus crea un hallazgo	Filtros opcionales: Severidad, Tipo de hallazgo, ID del repositorio
Hallazgo enriquecido	Plexicus añade contexto a un hallazgo existente	Los mismos filtros opcionales
Hallazgo reabierto	Un escaneo vuelve a detectar un hallazgo después de que se resolviera	Se ejecuta en cada reapertura, cuando la ejecución anterior ha terminado
Webhook	Una petición firmada llega a la URL de entrada del flujo	Se explica en la lección 3
Programación	Se dispara una programación cron	Cron de 5 campos más una zona horaria (UTC por defecto)
Manual	Alguien inicia la ejecución con Ejecutar ahora	Aparece como “Solo manual” en la lista

Para configurar el disparador, selecciona el nodo Disparador en el lienzo y edita su panel; los disparadores no se arrastran desde la paleta. Después de guardar, vuelve a abrir el panel del disparador para comprobar que se han conservado tus filtros o tu programación, y lanza una simulación del flujo antes de que un administrador lo active.

Dos reglas determinan cómo funcionan los flujos basados en eventos de hallazgos. Primera: un flujo se ejecuta automáticamente como máximo una vez por hallazgo. La excepción es un flujo cuyo disparador es Hallazgo reabierto: se ejecuta en cada reapertura, siempre que su ejecución anterior para ese hallazgo haya terminado. Un flujo Nuevo hallazgo o Hallazgo enriquecido no vuelve a ejecutarse cuando el hallazgo se reabre, así que crea un flujo Hallazgo reabierto aparte para actuar sobre los hallazgos reabiertos. Segunda: Deduplicar por huella agrupa en la ejecución ya en curso los hallazgos que comparten la huella de un secreto, de modo que una clave de API filtrada da lugar a una sola rotación en lugar de cinco.

Pasos

Paso	Qué hace	Ajustes obligatorios
Remediación	Solicita una remediación con IA, como un pull request para revisar (módulo 7)	Tipo de remediación
Ticket	Abre un ticket con un proveedor como Jira	Proveedor de tickets (clave de proyecto opcional)
Notificar	Crea una notificación en la aplicación	Canal de notificación, que se usa como título; mensaje opcional
Esperar aprobación	Pausa la ejecución hasta que alguien la aprueba o la rechaza	Rol aprobador y tiempo de espera opcionales, este último en segundos
Condición (if)	Sigue la conexión “yes” si la condición se cumple y, si no, la conexión “no”	Condición
Condición (switch)	Toma el primer caso que coincide, o la conexión de error si no coincide ninguno	Casos
Conector	Llama a una capacidad de una integración registrada	Tipo de conector, capacidad, nombre del conector

Cinco pasos de rotación de secretos hacen funcionar la plantilla Secret rotation. Notificar solo envía notificaciones dentro de la aplicación. Para llegar a otro sistema, usa un paso Ticket o un paso Conector que llame a una integración API HTTP.

Las condiciones usan una versión restringida de JSON Logic. Esta está pensada para seleccionar los hallazgos críticos:

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

Operadores permitidos: ==, !=, >, <, >=, <=, and, or, not, in y var. Puedes evaluar campos del hallazgo como severity, type, status y repository_id, y los datos del webhook como trigger.payload.FIELD. Los valores se comparan de forma exacta, incluidas mayúsculas y minúsculas. Usa preferentemente el constructor visual de condiciones, y lanza una simulación con un hallazgo que sepas que es crítico antes de fiarte de una condición escrita a mano.

Crear flujos de forma segura

Plexicus pone varias salvaguardas entre una idea y un flujo activo: borradores desactivados, simulaciones, activación reservada a administradores, versiones e historial de ejecuciones.

Tres formas de empezar

Plantillas. Automatizaciones Empezar desde una plantilla ofrece flujos listos para usar:

• Auto-remediate + ticket: ante un nuevo hallazgo, solicita una remediación con IA, abre un ticket en Jira y envía una notificación en la aplicación si falla algún paso.
• Conditional remediation: los hallazgos de severidad alta y crítica pasan a remediación automatizada con un pull request, y todo lo demás se convierte en un ticket de Jira para el triage.
• Secret rotation: rota un secreto filtrado, lo guarda en HashiCorp Vault, abre un PR en borrador que sustituye el valor incrustado en el código por una variable de entorno, verifica el nuevo valor volviendo a leerlo, espera la aprobación de un administrador y, después, promociona el PR. Cualquier fallo abre un ticket en Jira.

De prompt a flujo. Automatizaciones Nueva desde un prompt convierte una descripción en lenguaje natural de hasta 4.000 caracteres en un borrador, usando el modelo de IA configurado para tu organización. Por ejemplo: “Cuando se cree un hallazgo crítico, espera la aprobación de un administrador y luego abre un ticket en Jira”. El borrador enumera en Este flujo contactará con: todos los sistemas externos a los que llegará, y no se guarda nada hasta que haces clic en Confirmar y guardar borrador.

Editor visual. Automatizaciones Nueva automatización abre tres paneles: la paleta de pasos a la izquierda (Disparadores, Lógica, Acciones e Integraciones), el lienzo en el centro y el inspector a la derecha, con las pestañas Configuración, E/S de la última ejecución y Notas. Arrastra un paso al lienzo o haz doble clic para añadirlo. El inspector marca cada paso como Configurado o Incompleto. La versión actual añade deshacer y rehacer, y un generador de programaciones con vista previa de la próxima ejecución.

Empieces como empieces, obtienes un borrador desactivado que no hace nada hasta que un administrador lo activa. Plexicus valida el flujo al guardarlo, y los problemas, como dos conexiones que salen de una misma rama hacia destinos distintos, aparecen en Este flujo tiene errores de validación.

Simulaciones

Una simulación recorre todo el flujo e imita cada paso que tocaría un sistema externo. Cada paso registra lo que habría hecho, por ejemplo “Would create jira ticket in project SEC”, y los parámetros que parecen secretos se enmascaran. Las simulaciones funcionan con borradores, no cuentan para los límites de ejecución y aparecen en el historial de ejecuciones con la insignia Simulación. Introduce un ID de hallazgo en la barra superior del editor y haz clic en Simulación. En la versión actual también puedes probar flujos de programación y de webhook sin ID de hallazgo.

Activación y versiones

Solo los administradores de la organización pueden crear, editar, activar o eliminar flujos; el resto de usuarios tiene acceso de solo lectura y aun así puede consultar el historial de ejecuciones.

La activación vuelve a comprobar cada conexión que usa el flujo, incluidos los pasos Conector y el proveedor del paso Ticket. Si una prueba falla, verás Fallo al activar junto con el conector que ha fallado. Según tu plan, el número de flujos activos y de ejecuciones manuales puede estar limitado.

Al editar un flujo activo y hacer clic en Guardar nueva versión se crea la siguiente versión. Las ejecuciones en curso siguen con la versión con la que empezaron, y las versiones anteriores se conservan. Después de guardar, revisa la columna Estado y activa la nueva versión si aparece como Inactiva.

Historial de ejecuciones, estados y aprobaciones

Abre Automatizaciones Editar Ejecuciones para ver, de cada ejecución, la Automatización, el Hallazgo, el Estado y la hora de inicio (Iniciado). Despliega una fila para ver los logs por paso, o usa Repetir para recorrer una ejecución paso a paso con la entrada y la salida de cada paso.

Estado	Significado
En ejecución	Los pasos se están ejecutando
Esperando	En pausa en un paso Esperar aprobación
Completada	El flujo llegó a un final, por una ruta de éxito o por una ruta de fallo
Fallida	La ejecución se detuvo con un error, o duró más que el máximo de 30 días
Cancelada	La ejecución se detuvo antes de terminar

Las ejecuciones en espera muestran Aprobar, Rechazar y Cancelar. Aprobar continúa por la ruta de éxito. Rechazar y el agotamiento del tiempo de espera siguen la ruta de error. Cancelar se comporta como Rechazar: la ejecución continúa por la ruta de error. El tiempo de espera se indica en segundos y por defecto es de 7 días (604.800 segundos). Si el paso indica un rol aprobador, solo los usuarios con ese rol pueden aprobar o rechazar.

Gestión de tickets e integraciones salientes

Plexicus se conecta con otros sistemas en dos lugares: Configuración Integraciones contiene los conectores de tickets que hay detrás del botón Crear ticket de los hallazgos, y la página Integraciones de automatización contiene los sistemas que usan tus flujos.

Conectar Jira y ServiceNow

Abre Configuración Integraciones Ticket Management , que muestra Jira, ServiceNow y Webhook.

Jira tiene cuatro pestañas: Credenciales, Configuración de etapa, Probar conexión y Crear ticket. Credenciales pide una Dirección de correo electrónico, un Token de API y la URL del servidor de tu instancia de Jira Cloud, como company.atlassian.net.

ServiceNow pide un Token de OAuth y la URL de la instancia, como https://dev12345.service-now.com. Plexicus abre incidentes en estado New con la categoría Security. Los conectores que puedes activar dependen de tu plan.

Ambos conectores tienen dos etapas que activas o desactivas en Configuración de etapa:

• Create Issue cubre los tickets creados a partir de hallazgos.
• Pull Request se aplica cuando Plexicus abre un pull request de remediación. Un ticket vinculado recibe un comentario con el enlace al PR y se marca como en curso. Si todavía no hay ningún ticket vinculado, Plexicus crea uno.

Cada etapa tiene un Mapeo de prioridades (por defecto, Jira asigna Crítico a Highest, y ServiceNow asigna Crítico a “1 - Critical”) y un Mapeo de campos opcional que rellena los campos del ticket con datos del hallazgo mediante marcadores como %Finding.title%. La etapa también ofrece opciones de filtro; pruébalas con un hallazgo de ejemplo antes de confiar en ellas. Ejecuta Probar conexión después de guardar las credenciales.

Crear un ticket desde un hallazgo

En la página de detalle de un hallazgo, el desplegable Crear ticket muestra cada proveedor configurado. Jira abre un formulario con Servicio, Tipo de incidencia (Error, Tarea, Historia, Épica), Clave del proyecto y una Prioridad de anulación opcional. ServiceNow abre el incidente al momento con los mapeos de la etapa. Webhook envía el hallazgo a tu endpoint configurado.

Plexicus vincula al hallazgo el ID, la URL y el estado del ticket, y añade a su línea de tiempo una entrada “ticket created”. No des por hecho que el ticket se cierra solo cuando se resuelve el hallazgo; ciérralo siguiendo el flujo de trabajo habitual de tu herramienta de seguimiento.

Webhooks salientes e integraciones de automatización

El conector Webhook envía hallazgos a un endpoint HTTP que controlas tú. Su asistente tiene cuatro pasos: Settings (Webhook Name, Webhook URL, HTTP Method POST o PUT, Data Format), Authentication (None, Basic o Bearer Token), Headers y Preview, donde revisas la carga útil y envías una prueba.

La página Integraciones de automatización muestra los sistemas externos conectados que pueden usar tus automatizaciones: HashiCorp Vault, Secretos de Kubernetes, Jira, ServiceNow, Control de código fuente, API HTTP y Webhook saliente. El campo Referencia de credenciales guarda un puntero a credenciales almacenadas, nunca el secreto en sí. Cada tarjeta muestra Sin verificar, Correcta o Con errores, y Guardar y probar comprueba una integración nueva al momento. No puedes eliminar una integración que todavía usa algún flujo.

Webhooks entrantes firmados

Un flujo con un disparador Webhook obtiene su propia URL de entrada. En el panel del disparador, haz clic en Generar nuevo secreto y cópialo inmediatamente, porque solo se muestra una vez. Generar un secreto nuevo sustituye al anterior al instante, así que actualiza todos los emisores a la vez. El emisor firma el cuerpo sin procesar de la petición con HMAC-SHA256 usando ese secreto y envía el digest hexadecimal en la cabecera X-Plexicus-Signature como sha256=HEX_DIGEST. El panel incluye una petición de ejemplo lista para usar. En una shell, el paso de firma queda así:

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"

Firma exactamente los bytes que envías. Si el emisor vuelve a serializar el JSON después de firmarlo, la firma deja de coincidir.

Respuesta HTTP	Etiqueta en Entregas recientes	Significado
202	Aceptada	Cada entrega aceptada inicia una ejecución nueva
401	Firma no válida	Falta la firma o no coincide con el cuerpo y el secreto actual, o todavía no se ha generado ningún secreto
409	Inactiva	El flujo está inactivo o no usa un disparador Webhook
400	JSON no válido	El cuerpo no es JSON válido
413	Carga útil demasiado grande	El cuerpo supera el límite de tamaño
429	Límite de tasa excedido	Demasiadas entregas para la organización

Acceso para desarrolladores: tokens de API y la API REST

Los scripts, los pipelines de CI y los agentes del IDE acceden a Plexicus mediante tokens. Elegir el adecuado mantiene el acceso trazable y fácil de revocar.

Tokens de API personales

Ve a Configuración Tokens de API . Escribe un Nombre del token, elige una Expiración (30 días, 90 días o Sin expiración) y haz clic en Generar token. El valor aparece una sola vez bajo “Guarda tu token ahora”. Cópialo y haz clic en Ya lo guardé. La tabla Tokens activos muestra Nombre, Creado, Expira y Tipo, con Revocar en cada fila.

Un token personal no tiene ámbitos propios. Actúa como tú, con tu rol y tus permisos en la organización. Un token creado por un desarrollador puede hacer lo que ese desarrollador puede hacer en la consola, y nada más. Revocar un token tiene efecto inmediato, y cualquier llamada posterior con él devuelve 401. La creación de tokens queda anotada en el registro de auditoría.

Buenas prácticas:

• Crea un token por herramienta (un script de informes, tu IDE, un job de CI) para poder revocar uno sin romper los demás.
• Elige preferiblemente una expiración de 30 o 90 días. Si eliges Sin expiración, revisa la columna Expira, porque puede seguir aplicándose una vigencia larga por defecto.

El token de Plexalyzer de la organización

El token de Plexalyzer, también llamado token del escáner de CI/CD, pertenece a la organización y no a una persona. Autentica el escáner Plexalyzer en tus pipelines. Los administradores lo crean, con una fecha de expiración opcional, en Configuración Token de Plexalyzer . En algunas versiones, el mismo token aparece como la sección del token del escáner de CI/CD dentro de Configuración Tokens de API . El módulo 3 explica cómo guardarlo como el secreto de CI PLEXALYZER_TOKEN y cómo configurar los pipelines.

Plexicus no tiene un token de organización para llamadas generales a la API. Un script que deba seguir funcionando cuando una persona pierda el acceso sigue necesitando un token de API personal, así que elige con criterio a su propietario, dale al token un nombre propio y revócalo cuando ya no se necesite.

Token	Propietario	Úsalo para
Token de API personal	Tú, con tu rol	Scripts, integraciones, el servidor MCP
Token de la CLI	Tú, con tu rol	Plexicus TUI, creado por plexicus login
Token de Plexalyzer	La organización	Solo el escáner Plexalyzer en CI/CD

Conceptos básicos de la API REST

Cada petición envía Authorization: Bearer seguido de tu token y Accept: application/json, además de Content-Type: application/json en POST, PUT y PATCH. La URL base de SaaS está en la guía de la API en docs.plexicus.ai; un despliegue autoalojado usa su propia URL. Las rutas de los recursos van en plural, como /repositories, /findings, /remediations, /repository-scans y /automations.

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

Las listas usan paginación por cursor. Una respuesta contiene items, total y un enlace next; pasa su cursor para obtener la página siguiente. La mayoría de los endpoints devuelven 25 elementos por página por defecto, y limit cambia ese valor.

Las acciones de larga duración devuelven 202 y continúan en segundo plano. POST /repository-scans con un repository_id y un scan_type de app o sbom inicia un escaneo. POST /remediations con un finding_id solicita una corrección con IA; consulta periódicamente GET /remediations?finding_id=... hasta que devuelva el diff y las indicaciones (un 404 significa que todavía no está lista). Las acciones de IA consumen tu cuota de uso de IA, que se muestra en Configuración Facturación y en tu menú de perfil (módulos 7 y 10). También puedes iniciar un flujo mediante el endpoint de ejecuciones de /automations, para hasta 100 hallazgos por llamada y, si quieres, como simulación.

Los errores usan el formato Problem Details de la RFC 7807. Un 401 significa que el token no es válido, ha caducado o se ha revocado. Un 403 significa que el token funciona, pero tu rol o tu plan no permiten la acción. Un 429 significa que has alcanzado un límite de tasa, así que reintenta con backoff exponencial.

Trabajar desde el terminal y el IDE

Dos herramientas para desarrolladores llevan los hallazgos a donde ya trabajas: Plexicus TUI en tu terminal y el Plexicus MCP server en tu IDE.

Plexicus TUI

Descarga el binario para macOS Apple Silicon, macOS Intel o Linux x86-64 desde la página GitHub Releases de github.com/plexicus/tui. Después:

plexicus --version   # confirma la instalación
plexicus login       # inicia sesión desde tu navegador
plexicus             # explora los hallazgos y los repositorios conectados

En el primer arranque, un asistente de configuración te pide la URL de tu servidor de Plexicus.

Tecla	Acción
F	Abrir los filtros
/	Buscar
Enter	Abrir el detalle del hallazgo
r	Solicitar una remediación con IA
p	Crear un pull request

Pulsa r, revisa el diff y solo entonces pulsa p. El pull request pasa por tu revisión habitual, y tu equipo mantiene el control sobre la fusión.

Qué hace plexicus login

plexicus login abre tu navegador en la página de autorización de Plexicus. Inicia sesión si hace falta, incluido el 2FA si lo tienes activado. La página muestra “Authorizing Plexicus CLI…” y después “CLI authorized”. Por detrás, Plexicus crea un token de API personal llamado CLI - YYYY-MM-DD, válido durante 365 días, y tu navegador se lo entrega a la CLI en una dirección local 127.0.0.1. La CLI lo guarda en ~/.config/plexicus.

Como es un token personal normal, aparece en Configuración Tokens de API , donde puedes revocarlo. plexicus logout solo borra la copia local. En una máquina headless, sin navegador, genera un token personal y expórtalo como PLEXICUS_API_TOKEN.

El Plexicus MCP server

El Plexicus MCP server (paquete plexicus-mcp) se ejecuta en local en tu equipo y da a un agente del IDE compatible con MCP acceso a la API REST de Plexicus con tu token personal. Entre los clientes documentados están Cursor, VS Code, Windsurf y un agente de programación de línea de comandos. La configuración tiene tres pasos:

1. Elige un cliente.
2. Elige un método de arranque: uvx plexicus-mcp (recomendado), pipx run plexicus-mcp o pip install plexicus-mcp.
3. Configura tu token y conecta. Después de generar un token, la sección Usar con tu IDE (MCP) de la página Tokens de API muestra fragmentos ya rellenados: un comando de una línea para los clientes de línea de comandos y una configuración JSON para Cursor, VS Code y Windsurf.

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

PLEXICUS_API_TOKEN es obligatorio. PLEXICUS_API_URL es opcional; por defecto apunta a la API SaaS y se configura en los despliegues autoalojados. Con un token incorrecto, las herramientas devuelven “Authentication failed — the API token is invalid, expired or revoked.”

El servidor expone 10 herramientas. Solo request_scan y generate_remediation cambian algo; el resto son de solo lectura.

Herramienta	Para qué sirve
get_current_repository	Asocia el remoto de git de tu espacio de trabajo con un repositorio de Plexicus
list_repositories, get_repository	Explora repositorios, recuentos por severidad y estado de los escaneos
list_findings, get_finding	Filtra por severidad, estado, CWE o título, y después lee el detalle
request_scan, get_scan_status	Inicia un escaneo de app o de SBOM y sigue su progreso
generate_remediation, get_remediation	Solicita una corrección con IA y obtén su diff y sus indicaciones
get_security_posture	Totales de toda la cuenta y los repositorios con más riesgo

También incluye tres prompts guiados (fix_finding, triage_findings, security_review) y dos recursos: plexicus://repositories y un recurso de hallazgos por repositorio. Cada herramienta devuelve un resumen legible junto con los datos sin procesar de la API.

Puntos clave

• Todo flujo tiene un disparador, pasos con rutas de éxito y de error, y una ejecución registrada. Un flujo se ejecuta una vez por hallazgo; solo un flujo con disparador Hallazgo reabierto se vuelve a ejecutar, en cada reapertura.
• Los flujos empiezan como borradores desactivados. Simúlalos, pide a un administrador que los active (la activación vuelve a probar las conexiones) y lee los logs por paso, porque Completada puede incluir un paso fallido.
• Jira, ServiceNow y los webhooks salientes están en Configuración Integraciones Ticket Management . Los webhooks entrantes deben firmarse con HMAC-SHA256 usando el secreto actual del flujo.
• Los tokens de API personales actúan con tu propio rol; el token de Plexalyzer de la organización es solo para el escáner. Usa un token por herramienta y revoca los que no uses.
• plexicus login crea un token personal revocable para Plexicus TUI. El servidor MCP da a los agentes del IDE 10 herramientas, y las correcciones sugeridas nunca se convierten en pull requests sin ti.