agentgate

Evidencia de solo lectura para las herramientas que ejecutan los agentes: el registro de un servidor MCP, qué escáneres se ejecutaron realmente y verificaciones de políticas. Los registros incompletos nunca se consideran limpios.

GitHub

Prueba este MCPPatrocinado

Documentación

Español · 中文

agentgate

Un plano de control para las herramientas que ejecutan los agentes. Inventaría lo que está en uso, registra la evidencia detrás de cada afirmación, declara lo que una empresa rechaza y hace cumplir esa decisión en CI y en tiempo de ejecución.

Todo el proyecto sigue una regla:

clean se emite solo cuando se ejecutó cada verificación. Cualquier cosa que no se pudo medir es unmeasured, y un artefacto con una parte no medida es incomplete — nunca clean.

Esa regla existe porque el fallo habitual de un escáner de seguridad es una compilación en verde por trabajo que nadie hizo. Aquí, una verificación que falla hace que el resultado sea incompleto, por lo que no puede ocurrir en silencio.

Las cuatro partes

parte	qué hace	paquete
inventario	enumerar el registro, resolver paquetes, obtener repositorios	`packages/collect`
evidencia	unirlo en un registro por servidor, con los bytes detrás de cada afirmación	`packages/collect`
política	escanear configuraciones, hooks, manifiestos y código fuente para lo que una empresa rechazaría	`packages/guard`
verificación	comprobar una afirmación contra algo externo a la afirmación	`packages/verify`

Ejecutarlo

La configuración del servidor está en docs/operations/deployment-runbook.md. El primer despliegue, el 2026-09-16, está documentado en docs/verification.md junto con lo que se verificó y lo que aún no.

docs/capabilities.md enumera lo que este proyecto puede y no puede afirmar, una línea cada uno, cada línea con un comando que puedes ejecutar. Existe porque un consultor una vez escribió nuestras capacidades por nosotros e incluyó cuatro que no tenemos.

Pruébalo sin instalar

El servicio se ejecuta en https://xn--5kvo87g.com/: página de inicio, precios, el índice de evidencia (reconstruido diariamente) y la API en el mismo host.

https://ciceroyang.github.io/agentgate/ es la página de inicio en GitHub Pages. El índice es una única página navegable en https://ciceroyang.github.io/agentgate/evidence.html, reconstruida diariamente desde el registro en vivo — los registros están incrustados, el filtrado ocurre localmente y no hay nada que registrarse. Precios y un recorrido de diez minutos.

Inicio rápido

Actualización a 0.6.0: lee la guía de actualización antes de reemplazar una puerta de admisión existente o una instalación de watch. El paquete 0.5.0 puede pasar incorrectamente una puerta de evidencia requerida cuando la evidencia está ausente; no lo uses para una puerta nueva. Confirma la versión que instalaste y consulta el registro de versiones para la verificación del paquete público. Una copia del código fuente y el servicio alojado pueden ejecutar versiones diferentes.

Node 20 o más reciente, sin dependencias. Un clon ya incluye un índice de muestra, por lo que el servicio responde de inmediato; refresh lo reemplaza con uno actual.

node bin/agentgate.mjs serve
# agentgate serving http://127.0.0.1:8080

curl -s localhost:8080/health
curl -s localhost:8080/v1/index/summary
curl -s localhost:8080/v1/servers/<name>
curl -s localhost:8080/badge/<name>.svg

El paquete está en npm como @zhiliangtech/agentgate. Empuja una etiqueta v* y CI lo publica con procedencia; publish-checklist.md tiene la configuración y el registro de lo que se verificó.

npx --yes --ignore-scripts @zhiliangtech/agentgate@0.6.0 check --root .
npx --yes --ignore-scripts @zhiliangtech/agentgate@0.6.0 serve

Un comando npx sin versión sigue la etiqueta de distribución latest, no esta copia. Fija la versión aceptada; editar un número de versión local no cambia el paquete público.

Sin archivo de política, check usa un valor predeterminado integrado que no rechaza nada extra, y serve responde desde la instantánea con la que se envió el paquete. refresh escribe en ./data junto a ti, nunca dentro del paquete instalado.

Docker también funciona y ejecuta el mismo comando:

docker compose up                            # the service on :8080
docker compose --profile collect run --rm refresh   # rebuild data/index.json and seed the first snapshot

Inventario de herramientas

Ejecuta node bin/agentgate.mjs serve y abre /inventory.html en la dirección que imprime. Pega una lista de nombres de herramientas o elige un archivo de texto/JSON, resuelve coincidencias ambiguas, completa la versión que realmente usas y descarga un informe HTML independiente. La comparación ocurre en la memoria del navegador contra la instantánea del índice incrustado: la lista no se sube ni se almacena, tu máquina no se escanea y no se ejecuta ninguna herramienta. Cuando un registro lleva un bloque de cobertura, el informe también enumera qué escáneres se ejecutaron y cuáles no, y por qué; un registro cuyo bloque de cobertura propio dice que un escáner requerido no terminó no se mostrará como coincidente, por muy completa que parezca el resto de su evidencia.

Lo mismo sin navegador:

node bin/agentgate.mjs inventory --input examples/inventory/tools.json --out my-tools.html
node bin/agentgate.mjs inventory --input tools.json --index data/index.json --format json

Una entrada es un nombre por línea, un array JSON o { "tools": [...] }. Cada objeto puede llevar name, server, package, registry y version — nada más. Las configuraciones completas de clientes y las credenciales se rechazan a propósito. La guía de inventario tiene los detalles.

Los elementos sin coincidencia, ambiguos, sin versión, con versión no coincidente y con evidencia incompleta permanecen en el informe. Una coincidencia de versión no es prueba de lo que está instalado. La muestra confirmada es histórica y no puede producir una coincidencia confirmada; tampoco puede la evidencia antigua sin un enlace de contenido exacto. Incluso una coincidencia confirmada no es una certificación de seguridad ni un nuevo escaneo. Mira los alcances, los hallazgos, la fecha de la instantánea y las brechas antes de confiar en ello.

El código de salida 0 significa que se produjo un informe, no que todas las herramientas pasaron. La entrada malformada o los datos ilegibles salen con 2, y --out no sobrescribirá un archivo existente. Cuando quieras que CI rechace algo, usa check, no inventory.

Obtener la lista en primer lugar

Nadie tiene esta lista a mano. discover lee los archivos de configuración de MCP ya en la máquina y produce una entrada que inventory --input acepta. Imprime coordenadas de paquete como líneas cuando todas las identidades exportadas son conocidas; si alguna entrada es solo un alias, usa JSON para que un alias como tool@1.2.3 no pueda confundirse con un paquete y versión verificados:

node bin/agentgate.mjs discover --out tools.txt          # home directory + current directory
node bin/agentgate.mjs discover --roots ~/code/a,~/code/b --format json

Nunca imprime un valor env, un encabezado o un argumento, y una dirección remota se reduce a su host, porque las rutas y las cadenas de consulta llevan tokens. Lee las tablas MCP .codex/config.toml de Codex sin iniciar los servidores configurados. Las entradas explícitamente deshabilitadas permanecen visibles en --format json pero se omiten de las exportaciones de texto e inventario. Las formas TOML de MCP no compatibles, los archivos malformados y los archivos ilegibles se enumeran con una razón y hacen que el comando salga con 2. Los nombres y versiones de paquetes se toman solo de argumentos de ejecutor declarados reconocibles; un comando personalizado o un host remoto no se trata como un paquete o versión de runtime verificado.

Varios repositorios

node bin/agentgate.mjs audit --roots ~/code/a,~/code/b,~/code/c --index data/index.json

Un escaneo por directorio, un veredicto para el conjunto. Cualquier directorio incompleto hace que la auditoría sea incompleta, y un directorio que no existe cuenta como no medido en lugar de omitido.

Cambios desde la última vez

node bin/agentgate.mjs watch --input tools.txt --index data/index.json --archive ./archive
node bin/agentgate.mjs watch --verify --archive ./archive
node bin/agentgate.mjs watch --input tools.txt --index data/index.json --archive ./archive \
  --webhook https://example.invalid/hook --webhook-format wecom

Cada ejecución agrega una línea a un archivo encadenado (prev es el hash de la línea anterior) y almacena lo que vio bajo snapshots/<sha256>.json. --verify recalcula la cadena y cada instantánea retenida, y sale con 1 si algo no coincide. No se envía nada a ningún lugar a menos que --webhook nombre una dirección, y el archivo se escribe antes del push, por lo que un servicio de chat caído no puede perder una captura.

Mapeo de cuestionarios

node bin/agentgate.mjs framework                       # who answers which AI-CAIQ item
node bin/agentgate.mjs inventory --input tools.json --framework aicaiq --out report.html

Para cada elemento de AI-CAIQ, el mapeo dice qué podemos proporcionar, dónde se detiene nuestra cobertura y si la respuesta es nuestra, del cliente o de un evaluador independiente. Describe evidencia. No es una conclusión de cumplimiento y no reproduce el texto oficial. Los 58 elementos de los cuatro dominios sobre los que un revisor pregunta a un proveedor están clasificados: 13 respuestas son nuestras, 41 son del cliente y 4 necesitan un evaluador independiente.

Paquete de evidencia

El mapeo dice qué podemos proporcionar. pack produce la cosa en sí: un directorio que un proveedor entrega a la persona que lo revisa, donde cada respuesta que afirmamos apunta a evidencia en el mismo directorio y todo lo que no pudimos medir se cuenta en la parte superior.

node bin/agentgate.mjs pack --input tools.json --archive ./agentgate-archive --out agentgate-pack
node bin/agentgate.mjs pack --verify agentgate-pack     # recompute every hash and the seal

Escribe pack.json (legible por máquina), pack.html (para el revisor), answers.aicaiq.md (los 58 elementos, cada uno clasificado), manifest.txt (un sha256 por archivo) y manifest.sha256 (el sello en el manifiesto). Una respuesta cuya evidencia falta lee unmeasured y el comando sale con 2, no 0. Ejemplo construido desde el índice en vivo: docs/samples/evidence-pack-example — verificable con pack --verify. Contrato: docs/spec/evidence-pack-v1.md.

Servidor MCP

Cualquier cosa que hable MCP puede preguntar al índice directamente. Agrega esto a claude_desktop_config.json, un .mcp.json de un repositorio, o lo que tu cliente lea:

{
  "mcpServers": {
    "agentgate": { "command": "npx", "args": ["--yes", "@zhiliangtech/agentgate@next", "mcp"] }
  }
}

Cuatro herramientas de solo lectura: lookup_server (un registro, con su bloque de cobertura), inventory_tools (coincide con las herramientas que realmente usas), coverage_report (cuánto del índice se midió) y check_project (escanea un directorio local). Lee el índice local, nunca escribe, nunca sube y nunca ejecuta una herramienta escaneada. Un registro incompleto se informa como incompleto, y un registro que el índice no tiene se informa como faltante en lugar de seguro. Detalles: docs/spec/mcp-server-v1.md.

Política

Una política declara lo que una empresa rechaza. Es datos en lugar de código, y tiene una especificación: docs/spec/policy-v1.md.

{
  "version": "agentgate.policy/v1",
  "threshold": "high",
  "required": { "pinnedPackages": true, "measuredEvidence": ["packageManifest"] },
  "forbidden": { "rules": ["AG-INSTALL-001"], "servers": ["internal/*"] }
}

node bin/agentgate.mjs check --policy agentgate.policy.json --root . --index data/index.json

La política anterior requiere evidencia indexada. Proporciona un índice real que coincida con el nombre y la versión exactos del paquete npm local: la evidencia faltante sale con 2; un índice explícitamente faltante, malformado o de muestra sale con 3. Un escaneo de código fuente local no sustituye la evidencia de paquete requerida.

Sin archivo de política y sin --policy, la verificación aún se ejecuta. Informa lo que encontraron las verificaciones y dice que usó el valor predeterminado integrado, que no rechaza nada extra; inventar obligaciones en tu nombre haría que el resultado signifique menos, no más. Una política que nombras explícitamente y que no se puede leer es un error, porque eso es un error tipográfico.

La misma evaluación puede ir a una persona en lugar de una terminal:

node bin/agentgate.mjs check --policy agentgate.policy.json --root . --index data/index.json --format html --out report.html

Un archivo estático e imprimible sin script. Cualquier cosa que no se pudo medir tiene su propia sección arriba de los hallazgos: un informe que entierra lo que no verificó se lee como más completo de lo que es. Este archivo es lo que entrega la revisión gratuita.

Hay tres resultados, y incomplete supera a findings. Si una verificación no se ejecutó, o un bloque de evidencia que la política requiere es unmeasured, el código de salida es 2 por muy limpios que se vean los hallazgos. Ningún umbral convierte una respuesta parcial en un aprobado.

salida	significado
0	limpio
1	hallazgos
2	incompleto

Cumplimiento

Una solicitud de extracción que agrega algo que la política rechaza no se fusionará, y la razón se publica en la solicitud de extracción en lugar de dejarse en un registro que nadie abre.

- uses: ciceroyang/agentgate@main
  with:
    policy: agentgate.policy.json
    index: data/index.json

Consulta examples/github-actions/policy.yml. La acción ejecuta la verificación, escribe SARIF para el escaneo de código, comenta el informe en la solicitud de extracción y sale con el propio código de la verificación — por lo que un escaneo incompleto aún falla la compilación en 2.

Tiempo de ejecución

La misma política puede aplicarse a lo que ya se envió, si pones una puerta de enlace frente al servidor en lugar de apuntar tu cliente a él:

node bin/agentgate.mjs proxy --policy agentgate.policy.json --log calls.jsonl -- \
  npx -y @modelcontextprotocol/server-filesystem /data

Una llamada que la política rechaza se responde localmente con una razón y nunca llega al servidor. Una herramienta prohibida se elimina de la lista anunciada, por lo que un cliente no puede pedirla en absoluto. Cada decisión, permitida o rechazada, se agrega al registro.

Historial

El índice se mantiene, por lo que se pueden comparar dos compilaciones. La columna interesante es la última: cambios que una versión habría explicado y no lo hizo.

node bin/agentgate.mjs diff --from previous-index.json --to data/index.json

  added:           0
  removed:         0
  verdict changed: 1
  package changed: 0
  silent (no version move, different evidence): 1

Un nuevo hallazgo en una versión sin cambios generalmente significa que un paquete fue reemplazado sin una versión, un repositorio fue editado en su lugar, o el escaneo ha comenzado a ver algo. Ese registro no se puede rellenar. Solo existe si alguien estaba mirando en ese momento.

Las canalizaciones detrás del índice

node packages/collect/mcp-audit.mjs --max 6000 --out data/census.json
node packages/collect/scripts/guard-scan.mjs --census data/census.json --out data/guard-scan.json
node packages/collect/scripts/build-index.mjs --census data/census.json --guard data/guard-scan.json --out data/index.json
node scripts/coverage-stats.mjs --index data/index.json   # how much of it was actually measured

Y el escáner en un proyecto local:

node packages/guard/bin/agent-guard.mjs . --fail-on high
node packages/collect/bin/agent-add.mjs --index data/index.json <server-name>

Escritura

Indexamos 11,605 registros de MCP y pudimos auditar 258 de ellos (中文) — cuántos de los servidores recopilados se midieron realmente y qué impidió el resto. Los números corresponden a la compilación del 2026-09-19 sobre la que se escribió el artículo; el índice se reconstruye varias veces al día y cambia.
La regla más ruidosa falló nueve de nueve veces
Limpio es una afirmación sobre el trabajo realizado
Una razón que se lee como un hallazgo — cinco brechas de cobertura cuyo texto describía el sujeto cuando debería haber descrito el escáner. Cuatro de ellas son mías.

Prueba

npm test                              # the whole suite; it prints how many ran
node scripts/bench.mjs 50000 200      # lookups must stay under 10 ms p50
node scripts/measure-verify.mjs       # claim extraction, against a small labelled set
node packages/guard/scripts/regression.mjs   # benign must stay silent, positives must fire

Diseño

packages/guard     the scanner: engine, nine checks, CLI, corpus, GitHub Action
packages/collect   census, package and repository scanning, the evidence index
packages/policy    policy evaluation and human-readable reports
packages/gateway   runtime policy enforcement for MCP servers over stdio
packages/history   index snapshots and change comparisons
packages/service   the read-only evidence API
packages/verify    cross-model claim checking
docs/              architecture and product notes

Verificación

Las pruebas están escritas por las mismas personas que escribieron el código. docs/verification.md registra las comprobaciones que no lo están: un servidor MCP real a través de la puerta de enlace, y la lista de lo que aún no está verificado.

node scripts/verify-real-server.mjs

Para ver si los hallazgos de high y critical del índice aún coinciden con las revisiones humanas registradas, ejecuta node scripts/review-criticals.mjs. Una revisión debe vincular el hallazgo y su evidencia a una versión exacta del paquete y a una procedencia completa del contenido escaneado, incluido el resumen SHA-256 y el alcance. Un enlace faltante o modificado requiere otra revisión humana, y las aprobaciones heredadas no se actualizan automáticamente. --accept registra una revisión que ya ha ocurrido y rechaza procedencia incompleta; no realiza la revisión ni certifica código de terceros.

Operaciones

docs/operations/deployment-runbook.md — aliyun más el dominio 智量.com, incluida la advertencia sobre el registro ICP.
docs/operations/plan-b-no-icp.md — qué hacer cuando un servidor en el continente no tiene registro ICP.
deploy/ — el Caddyfile y una unidad systemd, listos para copiar a un servidor.
docs/operations/pilot-package.md — el resumen del piloto: entregables, cronograma, qué pedimos y qué no.
site/index.html y site/pricing.html — las páginas de inicio y precios, autónomas, sin recursos externos.
scripts/onboard-server.sh — los pasos de implementación como un script que imprime lo que haría y solo actúa con --apply.
scripts/smoke.mjs — la comprobación posterior a la implementación: accesible, índice presente y reciente, registros reales en lugar de la muestra.

Estado

Este es un núcleo de código abierto temprano. Cubre recopilación, un índice de evidencia, escaneo, comprobaciones de políticas en CI, una puerta de enlace en tiempo de ejecución para servidores MCP sobre stdio, diferencias históricas y un servicio de solo lectura. Los scripts de implementación y un runbook están en el árbol, y la primera implementación con sus comprobaciones está documentada en docs/verification.md. Ese documento no dice nada sobre la salud actual del servicio alojado. La ruta del contenedor no está verificada, pero está construida: CI ejecuta docker compose up --build y luego una comprobación de salud contra el contenedor en ejecución.

Lo que prometen los identificadores de versión y qué versiones están soportadas está documentado en docs/spec/compatibility.md; SECURITY.md explica cómo informar una vulnerabilidad y qué esperar. Ninguno sustituye a la puerta 3 y la puerta 4 anteriores — la superficie empresarial aún falta y nadie fuera de este repositorio depende de ella todavía.

Las características empresariales descritas en la propuesta de precios — SSO/SAML, RBAC, multiinquilino y exportación de auditoría firmada — no están implementadas. Los precios de Team y Enterprise son hipótesis no validadas; el piloto gratuito es cómo probamos si alguien quiere esto. Consulta el alcance del piloto y la licencia.

Una invariante está en el conjunto de pruebas: una comprobación bloqueada nunca puede producir clean. Ejecuta npm test para los números actuales; esta página no repite un recuento de pruebas.

Licencia

AGPL-3.0-only. Si deseas ofrecer un agentgate modificado como un servicio cerrado sin publicar tus cambios — el caso que la AGPL no permite — hay disponible una licencia comercial. Consulta docs/product/licensing.md.