Skarn guard: plugins de agente

Configuración de hooks, habilidades de agente y una declaración de servidor MCP local para Skarn, empaquetado para cuatro hosts, con un quinto host servido desde su propio repositorio. Este repositorio se genera en cada lanzamiento de Skarn. No contiene binarios, ni reglas de detección, ni código de motor.

Cinco unidades viven aquí, cuatro de ellas son unidades de guardia. claude/ y codex/ son plugins en el marketplace que sirve el manifiesto raíz de este repositorio, para Claude Code y Codex CLI. antigravity/ es un directorio de plugin para la CLI de Antigravity (agy). La raíz del repositorio es en sí misma una extensión de Gemini CLI, porque el instalador y el rastreador de galería de Google leen el manifiesto desde la raíz. Un archivo en la raíz es o bien un archivo a nivel de repositorio (este README, LICENSE, SECURITY.md, el manifiesto del marketplace) o un archivo de Gemini (gemini-extension.json, GEMINI.md, hooks/, skills/); cualquier otro host recibe un subdirectorio. La quinta unidad, recall/, es un plugin solo de habilidades en el mismo marketplace: una habilidad, sin hooks, sin servidor MCP. La unidad de Cursor no está en este repositorio en absoluto; vive en https://github.com/skarn-security/cursor-plugin.

El guard es un hook de pre-ejecución. Antes de que tu agente ejecute un comando de shell, aplique un parche, escriba un archivo, obtenga una URL, llame a una herramienta MCP o envíe un prompt al proveedor del modelo, la acción pendiente es escaneada por el motor de detección de Skarn en tu máquina y recibe un veredicto: denegar (bloquear), preguntar (escalar a ti) o permitir (silencioso). Escanea localmente, no hace ninguna llamada de red y nunca imprime un secreto en bruto: un veredicto nombra la regla y una vista previa redactada.

Instalación

Instala primero el binario de skarn (el plugin no lo incluye; los hooks llaman a skarn guard en tu PATH):

brew install skarn-security/tap/skarn

Claude Code:

claude plugin marketplace add skarn-security/agent-guard
claude plugin install skarn-guard@skarn

Codex CLI:

codex plugin marketplace add skarn-security/agent-guard
codex plugin add skarn-guard-codex@skarn

Los dos plugins de guardia llevan nombres diferentes porque un marketplace no puede contener dos plugins con el mismo nombre, y cada uno incluye la forma de hook de su host (nombres de eventos, matchers de herramientas y el --agent sobre el que el guard enruta). Instala el que corresponda al host que estás conectando. Ambos llevan la habilidad skarn-audit, que ejecuta skarn assess y skarn vet sobre esta máquina e informa hallazgos redactados. La redacción enmascara los valores de credenciales que Skarn detecta; el contexto de transcripción circundante en un hallazgo sigue derivado de la sesión, por lo que la habilidad trata todo el resultado como datos de sesión en lugar de texto seguro.

Codex te pide que confíes en los hooks la primera vez que lo inicias después de instalarlo: elige "Confiar en todo y continuar" en el aviso "Los hooks necesitan revisión". Hasta que lo hagas, los hooks no se ejecutan y el guard no te está protegiendo. La confianza es un hash de contenido por hook, por lo que cualquier cambio posterior en un hook (un aumento de versión, o el cambio de auditoría a enforce) vuelve a preguntar. Claude Code no necesita paso de confianza; los hooks están activos en tu próxima sesión.

skarn-recall es un tercer plugin en el mismo marketplace, y la adición de marketplace anterior ya lo alcanza. Lleva una habilidad, sin hooks, y nada específico del host, por lo que el mismo plugin sirve a ambos hosts:

claude plugin install skarn-recall@skarn

codex plugin add skarn-recall@skarn

Esa habilidad reconstruye en qué trabajaste a partir de tus transcripciones de sesión, por eso se distribuye aparte del guard en lugar de dentro de él. El contenido de transcripción que lee sale de tu máquina hacia el proveedor del modelo que sirve al agente; la redacción enmascara las credenciales que Skarn detecta, no todo lo que considerarías sensible. Instálala cuando quieras eso, y limita lo que lee por proyecto y por ventana de tiempo.

Gemini CLI instala este repositorio como una extensión, que lleva los mismos hooks de guardia en modo auditoría, la habilidad skarn-audit, un archivo de contexto GEMINI.md y el servidor MCP a continuación:

gemini extensions install https://github.com/skarn-security/agent-guard
gemini extensions list
gemini extensions uninstall skarn

La instalación pide consentimiento, porque la extensión declara tanto hooks como un servidor MCP, y te pide que confíes en la carpeta. Responde a ambos.

Antigravity CLI instala el directorio antigravity/ de un clon:

git clone https://github.com/skarn-security/agent-guard
agy plugin install agent-guard/antigravity
agy plugin list
agy plugin uninstall skarn-guard

agy plugin list informa del plugin con sus recuentos de hook, habilidad y servidor MCP. Copiar antigravity/ a ~/.gemini/config/plugins/skarn-guard/ manualmente hace lo mismo.

Cursor tiene su propio repositorio, https://github.com/skarn-security/cursor-plugin, generado por el mismo lanzamiento. El marketplace de Cursor y su revisión son por repositorio, por eso esa unidad no vive aquí.

skarn setup es la ruta de instalación alternativa para Claude Code, Codex CLI, Cursor, Copilot CLI, Gemini CLI y Grok Build: fusiona los mismos hooks en la configuración nativa de cada uno de esos hosts sin el sistema de plugins. No conoce la CLI de Antigravity, por lo que ese host instala el directorio de plugin anterior o fusiona su archivo de hook manualmente.

Related MCP server: netallion-mcp-lite

Servidor MCP local

Cada una de las cuatro unidades de guardia (claude/, codex/, antigravity/ y la extensión de Gemini en la raíz) declara el mismo servidor MCP stdio, que el host inicia ejecutando skarn mcp desde tu PATH. Cursor y VS Code lo toman con un clic:

Ambos botones registran el servidor como skarn y ejecutan skarn mcp desde tu PATH, así que instala primero el binario. Si prefieres no instalarlo, la forma de lanzador fijado funciona con solo Node presente: Cursor o VS Code - descarga @skarn-security/skarn@0.26.0 en la primera ejecución y reutiliza la caché de npx después; un Skarn más nuevo necesita un enlace más nuevo.

Configuración manual para cualquier cliente:

{
  "mcpServers": {
    "skarn": {
      "command": "skarn",
      "args": ["mcp"]
    }
  }
}

Se ejecuta en tu máquina, no hace ninguna llamada de red y expone cuatro herramientas de solo lectura: scan_sessions (hallazgos de sesiones pasadas, cada valor previsualizado redactado), vet_configs (un informe enmascarado sobre la superficie de configuración de tu asistente), list_sessions y session_stats (metadatos y agregados, nunca contenido de mensajes). No hay herramienta de escritura ni herramienta que devuelva contenido de mensajes.

Dos herramientas de contenido, search_sessions y get_session, aparecen solo si inicias el servidor como skarn mcp --enable-recall. Ambas enmascaran lo que devuelven, y el contenido aún sale de tu máquina hacia el proveedor del modelo que sirve la sesión, por lo que las declaraciones anteriores no establecen la bandera. search_sessions rechaza una llamada que no nombre ni hours ni project; get_session toma un session_id exacto, que ya es su alcance.

Si prefieres no instalar el binario tú mismo, una forma de npx con versión fijada funciona:

{
  "mcpServers": {
    "skarn": {
      "command": "npx",
      "args": ["-y", "@skarn-security/skarn@0.26.0", "mcp"]
    }
  }
}

npx descarga el paquete la primera vez que el servidor se inicia y lo almacena en caché después, por lo que el primer inicio es más lento y necesita acceso a la red. Fija la versión. La forma sin fijar resuelve a lo que el registro sirva en el momento del inicio, y skarn vet lo informa como vet-mcp-unpinned. No lo uses.

llms-install.md en la raíz de este repositorio es la misma instalación en pasos legibles por agentes, para un cliente que configura el servidor por ti.

Cada host informa de un binario faltante a su manera. claude mcp list dice Failed to connect con Executable not found in $PATH: "skarn". gemini mcp list muestra el servidor skarn como Disconnected. codex mcp list no ejecuta ninguna comprobación de salud, por lo que la fila permanece listada y habilitada y el servidor falla cuando una sesión lo inicia. Cursor muestra la fila del plugin como Error - Show Output, y el panel de salida termina con spawn skarn ENOENT. En cada caso, ejecuta skarn --version en una terminal: command not found significa que el binario no está instalado o no está en el PATH que ese host hereda, que es la respuesta habitual para una aplicación lanzada desde un escritorio en lugar de un shell.

Audita primero, luego aplica

Ambos plugins de guardia se distribuyen en modo auditoría (skarn-recall no tiene hooks, por lo que no tiene modo): el guard informa del veredicto que habría devuelto y nunca cambia lo que tu agente hace. Ejecútalo así primero y mide tu tasa real de bloqueo. Establece SKARN_GUARD_LOG=<path> en el entorno que tu agente hereda y el guard añade un registro JSONL redactado por llamada marcada (ts, verdict, tool, rule, severity, razón redactada, session, cwd, latency_ms); las llamadas limpias no se registran.

Cuando el registro se vea limpio, cambia el --guard-mode audit en el comando del hook a --guard-mode enforce, o ejecuta skarn setup --update --mode enforce. La aplicación requiere una licencia de Skarn; sin una, el guard permanece en auditoría e informa en lugar de bloquear, por lo que una licencia caducada nunca rompe tu editor.

Mantener un hook actualizado a medida que los lanzamientos de Skarn amplían el conjunto de eventos de un host es la actualización de plugin a continuación, no un comando de Skarn: estos plugins llevan sus propios archivos de hook, y skarn setup --update refresca solo las entradas propiedad de Skarn que skarn setup mismo escribió, en el ámbito en que las escribió (por usuario por defecto, o la configuración del repo bajo --scope project). Para una configuración conectada de esa otra manera, --update reescribe esas entradas a lo que el binario instalado escriba, reemplazando cada una por completo excepto un tiempo de espera de llamada de hook que hayas ajustado tú mismo (timeout, o timeoutSec en Copilot), que se conserva cuando se empareja sin ambigüedad con su reemplazo y el valor es razonable, por lo que un presupuesto por máquina sobrevive al refresco; cualquier otro campo que hayas añadido a tal entrada se descarta. Ejecutado en una terminal, skarn guard report y skarn assess nombran un hook por usuario conectado por setup que se ha quedado atrás, una vez por lanzamiento, con el comando de actualización exacto para ese host.

Actualización

Claude Code:

claude plugin marketplace update skarn
claude plugin update skarn-guard@skarn

Codex CLI (no tiene verbo de actualización; volver a añadir instala la nueva versión):

codex plugin marketplace upgrade
codex plugin add skarn-guard-codex@skarn

Las actualizaciones de plugin y de binario son independientes: los comandos de hook invocan skarn guard en PATH, por lo que brew upgrade skarn solo te da el motor de detección más nuevo. Una actualización de plugin importa cuando cambia algo que el propio plugin lleva: la forma del hook (un nuevo evento, una nueva bandera, un nuevo matcher), el texto de una habilidad o los metadatos del manifiesto.

Seguridad

El guard solo puede endurecer una decisión, nunca aflojarla. Lo que sucede cuando el guard mismo falla depende del host, porque cada host decide qué significa un fallo de hook, un tiempo de espera o una salida malformada.

Claude Code, Codex CLI y Gemini CLI fallan abiertos: un evento malformado, una herramienta fuera de alcance o cualquier error del guard produce allow, y el guard nunca bloquea tu agente. La única ruta de fallo cerrado en esos hosts es --strict con un enforce con licencia, que cada README de host documenta.

La CLI de Antigravity falla cerrada en cada resultado de hook excepto un allow explícito: un fallo, un tiempo de espera, JSON inválido y un {} vacío bloquean la llamada coincidente, tanto en modo auditoría como en enforce, y un hook conectado sin binario skarn en PATH bloquea cada llamada coincidente. El guard responde a cada evento que recibe con una decisión explícita, y el matcher incluido nombra solo las herramientas que abarca para que un paso fuera del matcher nunca pueda ser bloqueado por un fallo del guard. Instala skarn antes de conectar ese hook y elimina la entrada antes de desinstalar skarn. Documentación: https://getskarn.com/?utm_source=agent-guard-readme&utm_medium=referral&utm_campaign=home&utm_content=documentation

Licencia, privacidad y soporte

Este repositorio tiene licencia MIT; consulta LICENSE. Lleva solo configuración, por lo que eso cubre los manifiestos de plugin, los hooks, las habilidades y las declaraciones de servidor MCP que contiene.

El binario skarn que invocan esos archivos es una descarga independiente y no es de código abierto. Está licenciado bajo el Acuerdo de Licencia de Usuario Final de Skarn en https://getskarn.com/terms/, y su ejecución implica la aceptación de dicho acuerdo. Lo que lee, lo que conserva y lo que nunca envía a ningún sitio: https://getskarn.com/privacy/.

Soporte: hello@getskarn.com. Los informes de vulnerabilidades se envían a security@getskarn.com; consulte SECURITY.md en este repositorio.