Navi MCP Server

Servidor MCP para automatizar la gestión de exposición.

Documentación

suite navi-mcp

Un servidor MCP para la CLI navi de Tenable (Tenable Vulnerability Management / Tenable One), además de un conjunto de 13 habilidades complementarias de Claude que documentan cómo utilizarlo correctamente.

Este repositorio es el resultado de una auditoría y reconstrucción completa: la superficie de herramientas del servidor fue corregida contra una captura recursiva autoritativa de navi --help, y todas las habilidades fueron corregidas para coincidir con el servidor + CLI y reestructuradas para una divulgación progresiva.

Estructura

server/      server.py — the MCP server (19 tools + resources)
skills/      the 13 corrected skills, in NAVI_SKILL_DIR layout
             (<skill>/SKILL.md, plus references/ on the denser ones)
dist/        the same 13 skills packaged as .skill files
tools/       navi_mcp_config.py — auto-detects paths, emits the install config
docs/        audit framework, gap ledger, verified findings, help-crawler
INSTALL.md   step-by-step install for Claude Desktop
README.md    this file

Las 13 habilidades

navi (enrutador) · navi-core · navi-mcp · navi-troubleshooting · navi-acr · navi-export · navi-scan · navi-was · navi-action · navi-mail · navi-remote-exec · navi-explore · navi-enrich

Cada SKILL.md tiene menos de 500 líneas. El material profundo (esquema completo, catálogo exhaustivo de selectores, ejemplos largos trabajados) vive en references/*.md y se consulta bajo demanda.

Ejecutar el servidor MCP

El servidor invoca el binario navi y lee el navi.db local. No gestiona claves API — configúrelas fuera de banda con navi config keys primero (consulte skills/navi-core).

Ejecútelo a través de stdio (para Claude Desktop / Claude Code) o HTTP:

python server/server.py            # stdio (default); waits for a client
python server/server.py --http     # streamable HTTP on :8000

Variables de entorno:

Variable	Propósito	Valor predeterminado
`NAVI_SKILL_DIR`	Ruta al directorio `skills/` en este repositorio (para que los recursos `navi://skill/...` se resuelvan)	—
`NAVI_MCP_ALLOW_WRITES`	Establézcalo en `1` para habilitar las herramientas de escritura en la plataforma (etiquetado, ACR, eliminación, rotación, control de escaneo, …). Desactivado = solo lectura.	sin establecer (solo lectura)
`NAVI_EMAIL`	Establézcalo en `1` para habilitar `navi_action_mail` (correo electrónico). Doble compuerta — también requiere `NAVI_MCP_ALLOW_WRITES=1`.	sin establecer (desactivado)
`NAVI_REMOTE_CODE_EXECUTION`	Establézcalo en `1` para habilitar `navi_action_push` (ejecución remota de comandos/archivos a través de SSH). Doble compuerta — también requiere `NAVI_MCP_ALLOW_WRITES=1`.	sin establecer (desactivado)
`NAVI_WORKDIR`	Directorio que contiene `navi.db` y exportaciones CSV	cwd
`NAVI_BIN`	Ruta al ejecutable `navi`	`navi`

NAVI_EMAIL y NAVI_REMOTE_CODE_EXECUTION son opciones de activación deliberadas y separadas apiladas sobre la compuerta maestra de escritura: habilitar escrituras por sí solo no habilita el correo electrónico ni la ejecución remota. navi_action_mail necesita SMTP configurado mediante navi config smtp; navi_action_push needs SSH creds via navi config ssh (ambos fuera de banda). El asistente de configuración expone banderas coincidentes: --allow-email y --allow-remote-code-execution (cada una utilizada junto con --allow-writes).

Apunte NAVI_SKILL_DIR a la carpeta skills/ de este repositorio (no a dist/ — el servidor lee carpetas descomprimidas, no archivos zip .skill).

Instalación en Claude Desktop

Guía completa en INSTALL.md. La versión corta: no escriba rutas a mano — ejecute el asistente con el intérprete de Python que desea que Claude Desktop use (el que tenga mcp y navi), y este descubrirá server/server.py, su navi.db, el binario navi y skills/, luego imprimirá (o, con --write, instalará) la configuración:

python tools/navi_mcp_config.py            # print the mcpServers JSON
python tools/navi_mcp_config.py --write    # merge it into your Claude Desktop config (backs up first)

El punto de entrada del servidor lanzado es server/server.py (use una ruta absoluta en la configuración — Claude Desktop no tendrá el PATH de su shell). Después de editar la configuración, cierre y vuelva a abrir completamente Claude Desktop, luego lea navi://workdir para confirmar que se conectó.

Herramientas (19) y la compuerta de escritura

Las herramientas de lectura (navi_explore_data, navi_explore_info, navi_explore_query SELECT, navi_export, navi_explore_api GET, vistas de lectura de escaneo, …) se ejecutan libremente. Las herramientas de escritura en la plataforma requieren tanto NAVI_MCP_ALLOW_WRITES=1 como confirm=True y deben narrarse al usuario antes de la invocación: navi_enrich_tag, navi_enrich_acr, navi_enrich_add, navi_scan (crear/iniciar/detener/pausar/reanudar), navi_was (escaneo/inicio/carga), navi_action_delete, navi_action_rotate, navi_action_cancel, navi_config(kind="url") y navi_explore_api POST/PUT.

Herramientas de doble compuerta necesitan una variable de entorno de capacidad adicional además de la compuerta de escritura, más confirm=True:

navi_action_mail — correo electrónico; requiere NAVI_MCP_ALLOW_WRITES=1 y NAVI_EMAIL=1. Entorno de pruebas: skills/navi-mail.
navi_action_push — ejecución remota de comandos/archivos a través de SSH; requiere NAVI_MCP_ALLOW_WRITES=1 y NAVI_REMOTE_CODE_EXECUTION=1. Entorno de pruebas: skills/navi-remote-exec.

Recursos

navi://schema/{table} — definiciones de columnas en vivo para una tabla de navi.db
navi://workdir — directorio de trabajo, estado de la compuerta de escritura, binario, presupuesto de llamadas y frescura de navi.db
navi://skill/{name} — cargar una habilidad (enrutador/núcleo/mcp/…); lista sus referencias
navi://skill/{name}/{ref} — cargar una referencia incluida (por ejemplo, navi://skill/core/schema)

Además del prompt navi_workflow, que inyecta la habilidad del enrutador.

Operaciones de larga duración

Las exportaciones de navi pueden ejecutarse durante decenas de minutos en inquilinos grandes — más allá del límite de ~4 minutos por llamada de herramienta del host MCP. El servidor aplica un presupuesto de llamadas (~220s) y devuelve un error claro que nombra el comando CLI que debe ejecutarse en su lugar. Las sincronizaciones fundamentales (navi config update full) siguen siendo intencionalmente solo CLI. La ejecución remota de comandos y el correo electrónico (navi_action_push / navi_action_mail) ahora se exponen como herramientas, pero cada una tiene doble compuerta (ver arriba). Consulte skills/navi-core y skills/navi-troubleshooting.

Instalación de las habilidades como habilidades de Claude

Los archivos en dist/ están empaquetados para instalarse en Claude.ai / Claude Cowork / Claude Code como habilidades. (El servidor MCP usa las carpetas descomprimidas skills/ a través de NAVI_SKILL_DIR; los dos son el mismo contenido en dos formatos de entrega).

Estado de validación

server.py compila limpiamente y cada herramienta está anotada. No ha sido probado en tiempo de ejecución contra un inquilino de Tenable en vivo. Antes de confiar en él, valide la corrección de la causa raíz con una lectura en vivo, por ejemplo, navi_explore_data(subcommand="cve", cve="CVE-2021-44228"). Las anotaciones de herramientas requieren un SDK mcp reciente.

Consulte docs/verified-findings.md para el inventario por error y docs/gap-ledger.md para el registro de auditoría completo.