Shield KYA

Registro de auditoría y trazabilidad para agentes de IA. Puerta MCP: evaluar, ingerir, solicitar aprobación.

Documentación

`@shield-agent/kya`

Rastro de auditoría y trazabilidad para agentes de IA. Ve lo que hizo cada agente de codificación, con aprobación humana opcional y certificación firmada. Cada llamada de herramienta se registra en un panel local en vivo y es certificable contra la Línea Base de Confianza de Agentes. Localmente, KYA es consultivo y falla abierto, excepto por una pequeña lista de nunca que se deniega; la aplicación de políticas vive en la ruta de la puerta MCP y en el plano alojado. Un comando. Gratis para siempre bajo MIT.

npm i -g @shield-agent/kya@latest && kya start

Requiere Node.js 24+. Reinicia Cursor / Claude Code / Codex una vez para que MCP se cargue. Escritorio alojado: shield-agent.com.

CLI y puerta MCP local para la ruta Know Your Agent de Shield.

Un agente que pregunta a Shield primero obtiene Allow, Review o Deny: registras el agente, envuelves la herramienta (o la enrutas a través de la puerta MCP o del plano alojado), y Review espera a una persona. Los hooks locales solo registran y bloquean la lista de nunca (ver Intercepción de hooks); el plano alojado es donde vive la aplicación de políticas. Este paquete no escanea tu red. Los agentes que nunca llaman a evaluate permanecen invisibles a propósito.

Guía: cómo se usa.

npx @shield-agent/kya@latest --help

Requiere Node.js 24+ (engines.node: >=24). En un Node más antiguo, el CLI ofrece instalar 24 por ti (vía volta / fnm / nvm / brew), reinstalarse a sí mismo y completar el comando - rechazar solo imprime una advertencia y continúa.

Funciona con cualquier host que hable MCP u OpenAPI. Los paquetes verticales son opcionales. Shield es el único punto de decisión de políticas: esta puerta nunca auto-aprueba un efecto secundario irreversible.

Si KYA_API_KEY está vacío contra un plano autenticado, los comandos de red salen con código no cero. eval-tool, wrap y invoke salen con 0 en ALLOW, 4 en REQUIRE_APPROVE y 1 en DENY o desconocido, así que una línea como eval-tool && write no puede saltarse la puerta.

--offline ejecuta evaluate de muestra sin una nube de pago (útil para demostraciones de DENY y REQUIRE_APPROVE). Crear un agente es en sí mismo una herramienta: sin conexión, kya.agent.register regresa REQUIRE_APPROVE. Los modos Allow, break-glass y approve mint viven en el plano de control.

Una línea

npm i -g @shield-agent/kya@latest && kya start

Ejecútalo en el directorio de tu proyecto. (Desde un clon de este repositorio, ./scripts/install-local.sh reemplaza la instalación de npm.)

Más formas de instalar (mismo paquete; npm sigue siendo la ruta de referencia):

# Homebrew. Homebrew 7 may ask you to trust a third-party tap: run `brew tap The-Pixel-Boys/tap` first.
# The formula installs about 270MB because of the optional semantic-search runtime.
brew install The-Pixel-Boys/tap/shield-kya

# Scoop (not yet verified on Windows)
scoop bucket add The-Pixel-Boys https://github.com/The-Pixel-Boys/scoop-bucket.git
scoop install shield-kya

Los usuarios de Claude Code y GitHub Copilot CLI también pueden instalar el plugin; los usuarios de Codex CLI el plugin de Codex; los usuarios de Gemini CLI la extensión de Gemini CLI.

Eso inicializa .kya/, conecta MCP local (.mcp.json, mcp.json, .cursor/mcp.json → kya serve-mcp --stdio), también conecta configuraciones a nivel de usuario para cada host instalado que detecta (~/.claude.json, ~/.kimi-code/, ~/.grok/, ~/.cursor/, …), y abre el informe de actividad en vivo. El informe se ejecuta en segundo plano - recuperas tu terminal; kya stop lo detiene, kya receipt --open lo reabre. Cursor, Kiro, Qwen, Amp, Droid, Cline y Grok recogen el servidor en vivo sin reinicio (Kimi: solo una nueva sesión); Claude Code, Codex, OpenCode, Gemini, Copilot CLI y Kilo CLI lo cargan en el próximo lanzamiento - claude --resume mantiene tu conversación.

kya start --no-open   # wire only
kya start --force     # rewrite MCP blocks
# Receipt change previews (clipped + redacted): on by default for writes
# KYA_DIFF_PREVIEW=0 to disable

Un comando por host

kya start cubre Claude Code, Cursor y cualquier host que lea .mcp.json - y conecta automáticamente la configuración a nivel de usuario de cada host instalado que detecta. Para el resto, kya connect escribe el dialecto de configuración del propio host directamente:

kya connect claude              # ~/.claude.json (merges mcpServers only)
kya connect grok                # ~/.grok/config.toml (appends [mcp_servers.shield-kya])
kya connect opencode            # ~/.config/opencode/opencode.json
kya connect qwen                # ~/.qwen/settings.json
kya connect amp                 # ~/.config/amp/settings.json
kya connect qwen --project      # project scope instead of global
kya connect kiro --force        # overwrite an existing shield-kya entry

Connect fusiona - nunca reescribe una configuración de host que no puede analizar, y mantiene tus otros servidores y claves. Hosts compatibles: claude, grok, opencode, kilo, kiro, qwen, kimi, mastracode, amp, copilot, cursor. Cada uno conecta serve-mcp --stdio con KYA_OFFLINE=1 para que la puerta arranque sin clave; establece KYA_API_KEY en el entorno del host cuando apuntes a un plano autenticado.

Los hosts sin un objetivo connect aún funcionan: kya wrap --offline -- <agent command> pone la misma puerta de evaluate frente a cualquier CLI. Recetas por host con pasos de verificación y solución de problemas viven en docs/hosts/.

Intercepción de hooks

kya start también conecta un hook de PreToolUse en cada host con capacidad de hooks instalado que detecta: Claude Code (~/.claude/settings.json, solo fusión), Grok (~/.grok/hooks/shield-kya.json, archivo gestionado por kya) y Kimi Code (~/.kimi-code/config.toml, [[hooks]] append). Cada llamada de herramienta que hace el agente pasa entonces por kya hook primero: evaluada localmente (sin conexión, sub-segundo, sin red) y registrada en el rastro global. (Si optaste por estadísticas de uso anónimas, el hook también inicia un helper separado como máximo una vez al día; ver Estadísticas de uso anónimas.)

Mapeo de decisiones: un DENY de la lista de nunca local bloquea la llamada de herramienta (salida 2 más hookSpecificOutput JSON de denegación con permissionDecision: "deny"). ALLOW y REQUIRE_APPROVE se registran en el rastro como consultivos y la llamada procede. El cableado manual puede pasar --strict en el comando del hook para también bloquear REQUIRE_APPROVE.

Los hooks fallan abierto: cualquier error o tiempo de espera del hook permite la llamada. Son alertas más aplicación de la lista de nunca local, no la única barrera - la aplicación del plano sigue siendo la ruta MCP kya.policy_evaluate. Los hooks surten efecto en nuevas sesiones; los tres hosts cargan hooks al inicio de la sesión.

kya connect claude --hooks   # wire the PreToolUse hook by hand
kya connect grok --hooks
kya connect kimi --hooks

Plugin de Claude Code / GitHub Copilot CLI

Este repositorio es también un mercado de plugins de Claude Code llamado shield-kya con un plugin, kya:

/plugin marketplace add The-Pixel-Boys/shield-kya
/plugin install kya@shield-kya

El plugin es consultivo y falla abierto: registra cada llamada de herramienta en el rastro local (~/.kya/trail.jsonl) y bloquea solo la pequeña lista de nunca. Si kya falta, se bloquea o expira, la llamada de herramienta procede y no se registra nada. Evalúa sin conexión, así que no tiene Hold ni aprobación; la aplicación alojada es la ruta de la puerta MCP.

Despliegue en equipo: confirma extraKnownMarketplaces (la fuente de GitHub shield-kya) y enabledPlugins ("kya@shield-kya": true) en el .claude/settings.json del repositorio, o fórzalo a nivel de organización con configuraciones gestionadas. Detalles, límites y notas de Copilot CLI (el soporte de hooks allí no está verificado; kya connect copilot es la ruta verificada): docs/hosts/claude-plugin.md.

Plugin de Codex

El mismo repositorio es un mercado de plugins de Codex (.agents/plugins/marketplace.json) con el mismo plugin kya:

codex plugin marketplace add The-Pixel-Boys/shield-kya
codex plugin add kya@shield-kya

Luego abre /hooks en Codex CLI y confía en los dos hooks de Shield KYA: Codex no ejecuta ningún hook de plugin hasta que lo hagas. Codex confía en el comando del hook, no en los scripts que ejecuta; el comando SessionStart lleva la versión de kya, así que cada lanzamiento de kya pregunta de nuevo. Codex también auto-actualiza los mercados de Git al inicio, así que cualquiera que pueda hacer push a este repositorio puede cambiar lo que se ejecuta después; los equipos pueden fijar una referencia de lanzamiento (ver la guía). Mismo comportamiento que el plugin de Claude Code: consultivo, falla abierto, registra cada llamada de herramienta que Codex envía a través de sus hooks (shell, apply_patch, MCP y otras herramientas locales; no herramientas alojadas como búsqueda web), bloquea solo la lista de nunca. No incluye servidor MCP; añade uno con kya connect codex. Detalles: docs/hosts/codex.md.

Extensión de Gemini CLI

La raíz del repositorio es también una extensión de Gemini CLI (gemini-extension.json + hooks/hooks.json):

gemini extensions install https://github.com/The-Pixel-Boys/shield-kya

Mismo comportamiento que los otros plugins: consultivo, falla abierto, registra cada llamada de herramienta que Gemini envía a través de su hook BeforeTool, bloquea solo la lista de nunca. Gemini ejecuta hooks de extensión sin un paso de confianza separado. La extensión fija la versión de kya con la que fue lanzada. No incluye servidor MCP; ver los ejemplos de MCP. Detalles: docs/hosts/gemini.md.

Puerta (puerta de enlace MCP local)

kya gate pone un solo listener de solo loopback (127.0.0.1, puerto predeterminado 3930) frente a cualquier servidor MCP que ya uses. Tu host habla con la puerta de enlace; la puerta de enlace se distribuye a los servidores reales. La política por herramienta se genera desde la taxonomía de servidores top-20 - nombres destructivos (drop/truncate/purge/transfer) y las herramientas de nivel ADMIN de cada servidor se deniegan directamente (y se filtran de tools/list), todo lo demás se ejecuta en modo observación: permitido y auditado. Cada llamada se rastrea en el rastro local y el informe en vivo, y puede reenviarse como OTLP a la ingesta alojada.

Cero intervención: kya start ya hace esto por ti. Escanea tus configuraciones de host detectadas en busca de servidores MCP de terceros, los importa a .kya/gateways.json (registrados con un campo de procedencia importedFrom), instala el binario de la puerta de enlace, inicia el listener y reescribe cada host fuente para que los servidores importados se enruten a través de la puerta de enlace - la configuración original del host se preserva bajo .kya/backups/ antes de que se elimine algo. Nada encontrado → nada descargado, sin listener. Opta por no participar con kya start --no-gate o KYA_GATE=off. Si la descarga del binario falla (sin conexión, sin red), kya start advierte una vez y continúa sin la puerta de enlace - las configuraciones de host permanecen intactas. La ruta manual de abajo sigue ahí cuando quieras control total:

kya gate init     # scaffold .kya/gateways.json with ready-to-move recipes
# edit gateways.json: move a recipe into "servers", fill its placeholders
kya gate setup    # download the pinned gateway binary into .kya/bin
kya gate run      # generate the gateway config, start the listener detached
kya connect claude --gate   # point the host at the gateway (server key shield-kya-gate)
kya gate doctor   # binary, config, listener health, loopback-only posture

kya gate stop detiene el supervisor y el binario con él. Notas honestas: kya gate setup (y el auto-arranque de kya start, solo cuando encontró servidores que gobernar) descarga el binario de puerta de enlace fijado de nuestros lanzamientos - nada más descarga nada (el único otro uso de red son las estadísticas de uso anónimas opcionales en docs/telemetry.md, desactivadas a menos que digas sí); run nunca descarga. El modo observación significa que las llamadas permitidas se registran, no se bloquean - el conjunto de denegación de arriba es la única parada dura, y la aplicación del plano permanece con kya.policy_evaluate. kya connect <host> --gate cubre los mismos hosts que connect simple - grok obtiene una tabla de URL [mcp_servers.shield-kya-gate] en su config.toml (Grok soporta servidores MCP remotos sobre HTTP). Niveles por servidor y recetas: docs/mcp-servers.md.

Ruta más larga (opcional)

# Offline sample evaluate
kya eval-tool --offline --tool-id org.sample.never.event --irreversible
kya wrap --offline --tool-id Write --irreversible --args '{"path":"src/x.ts","content":"hi"}'
kya receipt --open
# Org Hold: KYA_HOLD=1 kya wrap …
kya dash --once --offline

Centro de instalación: https://shield-agent.com/install

Rastro de actividad (global)

Un rastro para todos los proyectos: ~/.kya/trail.jsonl (KYA_HOME anula ~). kya receipt --open desde cualquier directorio muestra actividad de cada proyecto. Cada evento lleva el nombre de la carpeta de su proyecto - el informe añade un resumen de Proyectos una vez que aparecen dos o más proyectos, y muestra el proyecto en cada entrada del feed. Los archivos <project>/.kya/trail.jsonl por proyecto más antiguos aún se leen y fusionan; sin migración. El rastro está limitado a 1 MB (lectura de cola: los eventos más antiguos se eliminan), compartido entre todos los proyectos.

El informe en sí es un panel: una fila hero arriba (resultado de Certify en vivo, mezcla de veredictos, sparkline de actividad, showback) con secciones de pestañas abajo - Overview (analíticas, sesiones, razones), Certify (la tabla completa de requisitos en vivo - cada requisito agrupado por dominio con estado, evidencia y atestación), Activity (el feed de eventos filtrable), System (hosts conectados, sandboxes, ORR). Todo es una página HTML independiente sin conexión (la vista en vivo añade un solo enlace externo: "Star on GitHub"); el daemon en vivo de kya start la re-renderiza en cada evento.

Compartir un informe

kya receipt --share publica un resumen redactado de la ventana actual (conteos de veredictos agregados, resúmenes por producto y código de razón, y el estado de Certify - sin rutas, sin argumentos de herramientas, sin IDs de sesión) en shield-agent.com e imprime una URL pública (/r/<id>, expira después de 7 días) que cualquiera puede abrir - cada página compartida lleva la instrucción de instalación de una línea para que los lectores puedan auditar sus propios agentes. Apúntalo a un recolector diferente con --share-url <base> o KYA_SHARE_URL.

Compartir es un único intento por diseño (a prueba de tormentas: sin reintentos silenciosos contra el recolector); --share-retries <n> (máx. 3) opta por reintentos limitados en fallos 429/5xx/red con retroceso exponencial + jitter, respetando el Retry-After del servidor.

Búsqueda en lenguaje natural

El cuadro de búsqueda de Actividad entiende inglés sencillo. Ejecuta un híbrido de BM25 sobre IDs de herramientas, resúmenes, códigos de razón, veredictos, proyectos y etiquetas de servidores MCP, más un reordenamiento semántico local MiniLM (enviado como dependencia opcional; el informe vuelve a solo léxico si el runtime del modelo no está disponible). Un glosario de conceptos integrado mapea palabras cotidianas al vocabulario que los eventos realmente usan, así dangerous encuentra llamadas rm/kill/delete/sudo, blocked encuentra denegaciones, y held encuentra solicitudes de aprobación. También puedes escribir cosas como failed stripe transfers, files written by grok, o approval required production - las palabras vacías y la derivación se manejan automáticamente, y la misma búsqueda funciona en todo el rastro global.

Sin conexión o KYA_OFFLINE=1 mantiene la búsqueda puramente léxica (sin descarga de modelo).
Por defecto, el servidor en vivo descarga BAAI/bge-small-en-v1.5 una vez en ~/.kya/models y almacena en caché los vectores de eventos en ~/.kya/search-index.json.
KYA_SEARCH_SEMANTIC=off desactiva el modelo mientras mantiene BM25.

La consola alojada usa la misma búsqueda híbrida en el lado del servidor (Postgres full-text + incrustaciones opcionales compatibles con OpenAI), por lo que las consultas escritas en cualquier lugar se comportan de la misma manera.

Plano dual

 host=ide (authoring)          host=runtime (production)
        │                              │
        └────────── same agent ────────┘
                    identity
                    policy evaluate  → ALLOW | DENY | REQUIRE_APPROVE
                    approval + trail

Etiqueta sesiones con KYA_HOST=ide o KYA_HOST=runtime. Misma ruta de política en ambos casos.

Entorno

Variable	Requerida	Significado
`KYA_BASE_URL`	Sí (comandos de red)	Origen del plano de control
`KYA_API_KEY`	Cuando la autenticación está activa	Clave API (o Bearer JWT para verbos de decisión)
`KYA_HOST`	No (por defecto `ide`)	`ide` \| `runtime`
`KYA_AGENT_ID`	Después de registrar	ID principal del agente
`KYA_MCP_PORT`	No (por defecto `3920`)	Puerto de escucha MCP HTTP
`KYA_OFFLINE`	No	`1`/`true` para evaluar muestra
`KYA_HOLD`	No	`1`/`true` para la ruta de retención de la organización (REQUIRE_APPROVE abre un ticket humano)
`KYA_DASH_PLAN`	No	`enterprise` desbloquea paneles TUI con licencia
`KYA_DIFF_PREVIEW`	No	`0` desactiva las vistas previas de cambios recortadas en el recibo
`KYA_RECEIPT_AUTO`	No	`0` desactiva la apertura automática del recibo después del wrap; `1` fuerza
`KYA_SEARCH_SEMANTIC`	No	`off` desactiva el reordenamiento semántico MiniLM (BM25 aún funciona)
`KYA_SHARE_URL`	No	`kya receipt --share` base del recolector (por defecto `https://shield-agent.com`)
`KYA_TELEMETRY`	No	`0`/`off` fuerza las estadísticas de uso anónimas desactivadas (docs/telemetry.md); están desactivadas a menos que optes por ellas
`DO_NOT_TRACK`	No	`1` fuerza las estadísticas de uso anónimas desactivadas, igual que `KYA_TELEMETRY=0`

El modo de compuerta también se puede fijar en el .kya/config.json del proyecto: {"gateMode": "hold"} o {"gateMode": "offline"} (solo valores exactos - cualquier otra cosa se ignora). La compuerta en sí (wrap / hook / eval) lo respeta con precedencia flags > env > config > observe, y kya certify informa a través del mismo resolvedor, por lo que una aprobación de certificación en modo de compuerta siempre refleja cómo la compuerta realmente se ejecuta.

Herramientas MCP

Herramienta	Rol
`kya.policy_evaluate`	`ALLOW` \| `DENY` \| `REQUIRE_APPROVE`
`kya.session_ingest`	Observar / riesgo solo de elevación
`kya.request_approval`	Abrir una retención humana. No ejecuta el efecto secundario

Entrada del Registro MCP: server.json más paquete mcpName io.github.The-Pixel-Boys/shield-kya.

{
  "mcpServers": {
    "shield-kya": {
      "command": "npx",
      "args": ["--no-install", "@shield-agent/kya@0.27.0", "serve-mcp", "--stdio"],
      "env": {
        "KYA_BASE_URL": "http://127.0.0.1:8090",
        "KYA_API_KEY": "${KYA_API_KEY}",
        "KYA_HOST": "ide"
      }
    }
  }
}

Wrap y decidir

npx @shield-agent/kya wrap --offline --tool-id org.sample.data.write --irreversible
npx @shield-agent/kya approve --id <approval-id>
npx @shield-agent/kya reject --id <approval-id>

wrap evalúa y puede abrir un ticket pendiente. Nunca ejecuta el efecto secundario. invoke pide al plano en vivo autorizar después de Allow o APPROVED. No ejecuta la escritura en esta máquina. La TUI (dash) puede a/x decidir solo después de que y confirme con un JWT (sk_* rechazado).

Shims SDK en proceso

Los agentes construidos en LangGraph.js, el SDK de IA de Vercel, Mastra, OpenAI Agents TS, o el SDK de Claude Agent pueden enrutar llamadas de herramientas a través de la misma ruta de evaluación sin una puerta de enlace:

import { governed, governLangGraphTool, KyaDeniedError } from "@shield-agent/kya/sdk";

const run = governed({ toolId: "write_file", server: "filesystem", fn: myWrite });
await run({ path: "out.txt", content: "hi" }); // throws KyaDeniedError on DENY

Evaluación sin conexión por defecto (sin red, sin plano alojado); una configuración explícita honra el plano en vivo. governA2aSend compuerta los envíos agente-a-agente en proceso. Un shim Python fail-open con middleware LangChain está en desarrollo y aún no se ha publicado. Matriz de soporte y recetas: docs/sdk-integrations.md; scripts ejecutables: examples/sdk/.

Conector Claude

Desktop / Claude Code (stdio local):

# Prefer a preinstalled package (no registry auto-install):
npx --no-install @shield-agent/kya@0.27.0 serve-mcp --stdio
# Or after npm i -g / local install:
kya serve-mcp --stdio

Copia claude/claude_desktop_config.example.json en la configuración MCP de Claude Desktop, o usa .mcp.json para Claude Code. Empaqueta una extensión de Desktop con npx @anthropic-ai/mcpb pack (ver manifest.json). Ese paquete ejecuta el dist/cli.js empaquetado, no npx -y.

Claude.ai / Cowork (alojado): agrega un conector personalizado en https://shield-agent.com/mcp con el encabezado de solicitud Authorization: Bearer <KYA_API_KEY> (o X-API-Key). Aún no está listado en el Directorio (autenticación por clave API, sin OAuth DCR).

OpenAI (Codex / Responses)

Plugin CLI Codex (hooks): ver Plugin Codex. CLI / IDE Codex (MCP): copia openai/codex.config.example.toml en ~/.codex/config.toml. El stdio local usa npx --no-install @shield-agent/kya@0.27.0 serve-mcp --stdio. Codex alojado usa url = "https://shield-agent.com/mcp" con bearer_token_env_var = "KYA_API_KEY".

API Responses: ver openai/responses-mcp.example.json (server_url + Authorization: Bearer <KYA_API_KEY>).

Apps ChatGPT (chatgpt.com): diferido. El Modo Desarrollador quiere OAuth. Usa Codex hasta entonces.

CLI Gemini

Fusiona gemini/settings.example.json (stdio) o gemini/settings.hosted.example.json (httpUrl + Bearer) en ~/.gemini/settings.json o .gemini/settings.json. No habilites ambos a la vez.

Grok

CLI Grok (local): kya connect grok agrega una tabla [mcp_servers.shield-kya] a ~/.grok/config.toml (serve-mcp --stdio, evaluación de muestra sin conexión sin clave). En una sesión en ejecución, presiona r en /mcps para actualizar.

grok.com (alojado): conector personalizado en https://shield-agent.com/mcp (ver grok/README.md). Grok rechaza localhost. Prefiere una clave de máquina Bearer cuando la interfaz ofrece un encabezado de solicitud.

Más hosts

Cada uno incluye un ejemplo de copiar y pegar en su propio directorio; kya connect <host> escribe lo mismo para los marcados con estrella. Recetas completas (verificar, desinstalar, solución de problemas): docs/hosts/.

Host	Configuración	Ejemplo
Claude Code	`kya connect claude` (o `kya start`)	- (fusiona `~/.claude.json` / `.mcp.json`)
Grok CLI	`kya connect grok`	- (agrega `[mcp_servers.shield-kya]` a `~/.grok/config.toml`)
OpenCode	`kya connect opencode`	`opencode/opencode.example.json`
Kilo Code	`kya connect kilo`	`kilo/kilo.example.json`
Kiro	`kya connect kiro`	`kiro/mcp.example.json`
Qwen Code	`kya connect qwen`	`qwen/settings.example.json` (+ `settings.hosted.example.json`)
Kimi Code	`kya connect kimi`	`kimi/mcp.example.json`
MastraCode	`kya connect mastracode`	`mastracode/mcp.example.json`
Amp	`kya connect amp`	`amp/settings.example.json`
GitHub Copilot CLI	`kya connect copilot`	`copilot/mcp-config.example.json`
Cline	copia en globalStorage de VS Code	`cline/cline_mcp_settings.example.json`
Droid	`droid mcp add` (esquema no verificado)	`droid/mcp.example.json`
Pi · OMP · Devin · Hermes · Qoder · Maki · Muse · Antigravity	`kya wrap --offline -- <cmd>`	docs/hosts/

Plugin Cursor

El paquete incluye .cursor-plugin/plugin.json, mcp.json, y una habilidad de wrap. Repositorio de listado público: https://github.com/The-Pixel-Boys/shield-kya

ORR (solo informes)

npx @shield-agent/kya orr run --path . --out ./orr-report --skip-optional-producers
npx @shield-agent/kya orr run --path . --out ./orr-report --scorecard ./scorecard.json --producer openssf.scorecard
npx @shield-agent/kya orr run --path . --out ./orr-report --producer harness.agentshield --agentshield-json ./agentshield-report.json

ORR es un tablero de informes. Escáneres, --scorecard, y harness.agentshield son evidencia. Nunca PERMITEN un efecto secundario de alto riesgo, por lo que no son una segunda compuerta de política. AgentShield es opcional y de solo lectura: sin --fix, sin MiniClaw, sin hook de runtime. Este paquete no depende de ecc-agentshield. Si pasas --producer harness.agentshield y no tienes ni --agentshield-json ni un binario agentshield, ORR registra una brecha de cobertura y aún así sale con 0. --producer explícito siempre intenta; --skip-optional-producers solo omite productores que no solicitaste.

Certify (aseguramiento continuo del agente)

kya certify evalúa el catálogo abierto de Línea Base de Confianza del Agente (catalog/agent-trust-baseline-v0.json - 30 requisitos en Datos y Privacidad, Seguridad, Seguridad Física, Confiabilidad, Responsabilidad, Sociedad) contra evidencia local: el rastro global, salida de ORR, hosts conectados, inventario de sandbox, recibos, showback, y tus atestaciones registradas. Escribe un informe de brechas en .kya/certify/ (JSON + Markdown + HTML). La lista de brechas es tu plan de trabajo. El informe de recibo muestra el mismo estado en vivo: un panel de Certify recalculado en cada renderizado (así el informe en vivo de kya start se actualiza a medida que llegan los eventos), más una pestaña dedicada de Certify con la tabla completa de requisitos en vivo - ejecuta kya certify para el informe de brechas completo + paquete de evidencia firmado.

npx @shield-agent/kya certify                  # gap report; exit 1 when gaps exist (CI-friendly)
npx @shield-agent/kya certify --open           # open the HTML report
npx @shield-agent/kya certify --fail-on never  # report only, always exit 0
npx @shield-agent/kya certify --attest SOC-01 --text "Acceptable-use policy: https://example.com/aup"
npx @shield-agent/kya certify --sign           # also emit a signed evidence-bundle.json

Certify es solo evidencia. Nunca PERMITE, NIEGA, o bloquea nada - el único PEP sigue siendo Shield KYA. Las verificaciones automáticas basadas en rastro nunca pasan en un rastro vacío (informan insufficient_evidence). Lo que una máquina no puede verificar está cubierto por atestaciones locales explícitas (--attest), registradas en .kya/attestations.json - declaraciones de operador no verificadas, etiquetadas como tales.

--sign emite evidence-bundle.json: JSON canónico, firmado con ed25519 por una clave generada localmente (~/.kya/keys/evidence-ed25519.json, modo 0600, creada automáticamente en el primer uso). Cada ejecución de --sign imprime la huella de la clave de firma; cuando la clave se acaba de crear, la CLI nota que la continuidad de la clave se restablece allí (los paquetes anteriores siguen siendo verificables solo bajo la clave pública anterior). Una clave de desarrollador autofirmada prueba la integridad del paquete y la continuidad de una clave - no identidad. El enlace de identidad y la insignia verificada son el producto de verificación alojado (separado). El formato del paquete es abierto y está documentado en docs/certify.md; cualquiera puede verificar un paquete sin conexión con la clave pública incrustada.

kya certify es local, gratuito y sin conexión: sin cuenta, sin llamadas de red, sin verificación de licencia (nunca envía estadísticas de uso). El catálogo tiene licencia MIT y los PRs son bienvenidos. Una tabla de correspondencia de la Ley de IA de la UE (requisitos de línea base mapeados a los Artículos 9-15, 26, 72) se incluye en docs/certify-eu-ai-act.md y src/certify/eu-ai-act-map.json.

Importar trazas (LangSmith, Langfuse, Phoenix, OTel, AGT, ADR Sensor)

Trae exportaciones de observabilidad existentes al rastro para que el recibo y certify las vean:

kya import --from langsmith ./runs.json
kya import --from langfuse ./observations.jsonl
kya import --from otel ./otraces.json
kya import --from agt   # Microsoft Agent Governance Toolkit audit log
kya import --from adr-sensor ./adr-sensor-events.jsonl

El importador AGT verifica la cadena de hash de AGT, marca registros manipulados con chainVerified=false, y nunca duplica filas en la reimportación; ver docs/import-agt.md. Los eventos de ADR Sensor mapean un AgentEvent a uno o más eventos de rastro, con deduplicación estable de uuid en la reimportación; ver docs/import-adr-sensor.md. La cadena de hash de AGT no tiene clave, por lo que "verificado" significa internamente consistente, no auténtico. La consola alojada acepta los mismos formatos (docs/import-agt-hosted.md).

Las importaciones llegan como eventos en modo observación (host: import, reasonCode: IMPORTED, las ejecuciones con error se convierten en DENY/IMPORTED_ERROR), con latencia y conteos de tokens mapeados cuando la fuente los lleva. Los archivos de más de 50MB se rechazan; los registros malformados se omiten, nunca son fatales. El informe (kya start / kya receipt) muestra una tarjeta de Importación con conteos por formato, conteo de errores, y el evento importado más reciente una vez que cualquier importación ha aterrizado.

Investigación (detecciones + resúmenes de corrección)

kya investigate ejecuta detectores locales deterministas sobre el rastro, sin llamadas a LLM: fugas de PII en resúmenes, picos de DENY, bucles de reintento de aprobación, intentos repetidos de eventos nunca permitidos, herramientas desconocidas en espera, herramientas lentas. Los hallazgos se agrupan en incidentes, y cada incidente genera un resumen de corrección en Markdown diseñado para pegarse en Claude Code / Cursor / Codex. Cada ejecución también persiste un resumen compacto en ~/.kya/investigate-last.json, que el informe renderiza como una tarjeta de Investigaciones (hallazgos por severidad con IDs de detectores, más el resumen de corrección principal).

kya investigate           # summary: counts by severity + top incidents
kya investigate --json    # findings + incidents + briefs, machine-readable

Descubrimiento de endpoints

kya discover inventaría agentes de IA, extensiones de IDE, aplicaciones de escritorio, runtimes de modelos y servidores MCP en la estación de trabajo actual. El escáner solo inspecciona rutas y archivos de configuración; nunca ejecuta binarios descubiertos ni se conecta a puertos de runtime. Las instantáneas se escriben en ~/.kya/discovery/<iso-ts>.json con una copia latest.json, y el informe en vivo muestra una tarjeta de Descubrimiento con totales, conteos de aprobados/revisados y categorías principales.

kya discover                              # scan, save snapshot, print summary
kya discover --json                       # print snapshot JSON to stdout
kya discover --diff ~/.kya/discovery/latest.json  # compare current scan to saved snapshot
kya discover --push                       # scan and push to hosted console

El envío requiere KYA_BASE_URL y KYA_API_KEY:

export KYA_BASE_URL=https://shield-agent.com
export KYA_API_KEY=your-token
kya discover --push

Los prefijos del directorio de inicio se redactan de las rutas de evidencia (reemplazados con ~). La instantánea incluye un endpointUid estable derivado del sistema operativo, hash del hostname y hash del usuario; ningún hostname o nombre de usuario sin procesar sale de la máquina. Consulta docs/discovery.md para la lista completa de escaneo y notas de privacidad.

Webhooks de alertas (enrutamiento de veredictos)

Enruta eventos de DENY / REQUIRE_APPROVE a Slack, Linear, Jira o cualquier webhook. La configuración vive en .kya/config.json (proyecto) o ~/.kya/config.json (global):

{
  "notify": {
    "webhooks": [
      { "url": "https://hooks.slack.com/services/...", "template": "slack", "events": ["DENY", "REQUIRE_APPROVE"] },
      { "url": "https://example.invalid/jira", "template": "jira", "events": ["DENY"] }
    ]
  }
}

KYA_NOTIFY_WEBHOOK=<url> es la variante de configuración cero (payload genérico). La entrega reintenta con backoff exponencial (250ms/1s/4s + jitter), timeouts por intento, un circuit breaker por URL y un limitador de tasa de envío; los payloads se construyen solo con campos redactados del rastro, con un fallback minimizado automático si el escaneo de secretos se activa. Desde spawns de hook/wrap de corta duración, la entrega viaja con un helper separado (kya notify-flush), por lo que la ruta de la puerta nunca espera en la red. Cada intento de entrega se agrega a ~/.kya/notify-log.jsonl (solo el host de destino, nunca la URL completa; limitado a las últimas 500 entradas), y la pestaña del Sistema del informe muestra un panel de Alertas con conteos de entregados/fallidos por destino y el último intento.

Envoltura de sandbox opcional (Firecracker)

Junto a la puerta, no dentro de MCP. Solo opt-in:

KYA_SANDBOX=mock kya sandbox spawn
KYA_SANDBOX=mock kya sandbox exec --sandbox-id <id> --cmd "true"
KYA_SANDBOX=mock kya sandbox kill --sandbox-id <id>

org.sample.sandbox.exec sin --sandbox-id es DENY MISSING_SANDBOX_ID. Firecracker real necesita firecracker + jailer en PATH y env de kernel/rootfs (KYA_SANDBOX_KERNEL, KYA_SANDBOX_ROOTFS). No incluimos esos binarios. serve-mcp aún expone solo evaluate / ingest / request_approval.

Showback de costos (solo observación)

kya orr run --usage ./usage.json (o .kya/usage.json) agrega una sección de showback: tokens y USD estimados por agente y ejecución. Los subagentes se anidan bajo parentRunId. Esa sección no es un medidor de facturación ni una puerta de política. Las métricas alojadas muestran el mismo rollup cuando el uso se ingiere con una sesión. Los eventos del rastro que llevan conteos de tokens reportados por el host (payloads de hook con un objeto usage, trazas importadas) se prefieren sobre la estimación estática por evento, y el informe indica cuántos eventos de la ventana tenían uso real.

Enterprise (nivel separado)

Pin, registro privado, densidad multi-tenant, operaciones de tablero ORR y soporte no son necesarios para la ruta npx del día 1 anterior.

Desarrollar

pnpm install
pnpm test
pnpm build

Documentación

Estadísticas de uso anónimas (opt-in, desactivadas por defecto)

La primera vez que ejecutas kya start, kya init o kya connect en una terminal, KYA pregunta una vez si deseas compartir estadísticas de uso anónimas ([y/N], el valor predeterminado es No). Solo un y o yes explícito lo activa. No se envía nada en CI, en ejecuciones no interactivas, con --json, o cuando DO_NOT_TRACK=1 / KYA_TELEMETRY=0 está configurado. kya hook en sí nunca toca la red; cuando optas, inicia un helper separado como máximo una vez al día que envía un ping, por lo que las instalaciones solo con hook aún cuentan como activas.

kya telemetry show        # the exact payload, field by field
kya telemetry status      # on / off / not asked, and what overrides it
kya telemetry off --purge # turn off and erase what the server holds for this install

Detalles completos, el payload, la retención y cómo auto-alojar el endpoint: docs/telemetry.md.

OTLP (opcional)

Opt-in. Desactivado por defecto.

CLI OSS: configura KYA_OTLP_ENDPOINT (o OTEL_EXPORTER_OTLP_ENDPOINT) para exportar latencia delgada de evaluate (kya.client.evaluate.latency) solo con etiquetas verdict y host. Sin argumentos de herramientas ni claves de API.

Exportación de span de veredicto: configura KYA_OTLP_EXPORT_ENDPOINT (o "otlpExport": { "endpoint": ... } en .kya/config.json) para emitir cada veredicto como un span GenAI OTLP/JSON (gen_ai.tool.name, kya.verdict, kya.reason_code, atributos de tokens cuando se conocen) a cualquier backend OTLP/HTTP. Los procesos de larga duración (puerta MCP, gateway) exportan cada veredicto; los spawns de hook/wrap exportan DENY / REQUIRE_APPROVE a través del helper separado notify-flush. Se acepta http en texto plano solo para loopback a menos que "insecure": true. Los resultados de flush se acumulan en ~/.kya/otel-stats.json (etiqueta de host del endpoint, spans enviados/fallidos, última hora de exportación), renderizados como el panel de Exportación OTel en la pestaña del Sistema del informe.

Plano alojado: medidores y temporizadores Micrometer más ricos cuando KYA_OTLP_ENABLED=true.

Env completo, notas de Grafana/Datadog, lista de prohibidos y una muestra de Collector: docs/otlp.md.