systems-manager

Versión: 2.1.0

systems-manager es el proveedor tipado de operaciones de host para Agent Utilities y GraphOS. Expone capacidades multiplataforma de paquetes, servicios, procesos, red, disco, archivos gestionados, cortafuegos, almacenamiento físico, sistema operativo de agentes e ingesta de host con privacidad segura, sin exponer una herramienta de comandos sin procesar.

El paquete actual requiere Python 3.11–3.14 y agent-utilities>=2.0.0,<3.0.0.

Instalación y ejecución

Instala solo la interfaz que necesites:

pip install "systems-manager[mcp]"
systems-manager-mcp --transport stdio

Los extras opcionales son:

Para un lanzamiento MCP efímero:

uvx --from "systems-manager[mcp]" systems-manager-mcp --transport stdio

El mcp_config.json incluido es un catálogo de cliente solo de referencia. Contiene referencias env:// y valores predeterminados de denegación segura, nunca endpoints de despliegue, credenciales, rutas de certificados, rutas de sistema de archivos, nombres de host o identidades. Los valores específicos del proyecto pertenecen a AgentConfig o al lanzador de procesos.

Related MCP server: AETHER_01

Contrato de seguridad

• Los listeners MCP de red requieren autenticación configurada. Los listeners que no son de bucle local también requieren TLS directo o un proxy de terminación TLS de confianza, hosts permitidos exactos y las comprobaciones de transporte actuales de Agent Utilities.

• Las mutaciones de host se deniegan a menos que SYSTEMS_MANAGER_ALLOW_HOST_MUTATIONS=true y la solicitud individual reciba aprobación de operación destructiva.

• Las escrituras de archivos gestionados requieren además SYSTEMS_MANAGER_ALLOW_FILESYSTEM_MUTATIONS=true.

• Las lecturas sensibles y las sondas activas tienen compuertas de denegación predeterminadas independientes.

• Las rutas gestionadas están confinadas bajo un SYSTEMS_MANAGER_FILESYSTEM_ROOT explícito; no hay respaldo de directorio de trabajo.

• El shell sin procesar, los comandos arbitrarios, las credenciales en texto plano, la creación de cron por parte de modelos y los alias de comandos de compatibilidad no son capacidades.

• Los registros y la observabilidad son solo metadatos. Mantén LANGFUSE_CAPTURE_CONTENT=false.

AgentConfig, secretos y TLS

Usa TLS_PROFILE / TLS_PROFILE_REF con TLS_PROFILES_REF para la confianza de salida verificada compartida. Los perfiles específicos del servicio, como OIDC_TLS_PROFILE_REF, MODEL_TLS_PROFILE_REF y LANGFUSE_TLS_PROFILE_REF, pueden seleccionar entradas del mismo catálogo de runtime. No codifiques rutas de CA ni indicadores de verificación en el código de la aplicación, y no deshabilites la verificación para cadenas de certificados incompletas.

Las lecturas de salud BMC fuera de banda consumen una proyección de secreto de runtime de SYSTEMS_MANAGER_BMC_CREDENTIALS. AgentConfig resuelve la referencia env:// o de secreto comprobada antes del lanzamiento; el proveedor acepta exactamente un objeto JSON con host, user y password. No se incrusta ningún proveedor de almacén de secretos, ruta de secreto, token o valor de credencial en este paquete.

El certificado propio del listener MCP o el límite de proxy de confianza utiliza la configuración MCP_TLS_* actual de Agent Utilities. El listener de agente opcional usa SERVER_TLS_* y requiere configuración JWT para servir en interfaces que no sean de bucle local.

Herramientas MCP

El MCP_TOOL_MODE=intent predeterminado expone la pequeña superficie de verbos de intención. Las herramientas de respaldo enrutadas por acción permanecen disponibles para descubrimiento gobernado y carga bajo demanda. Los filtros de herramientas y etiquetas pueden reducir aún más la superficie visible.

Generado automáticamente desde el servidor MCP en vivo; no editar entre los marcadores.

Herramientas condensadas enrutadas por acción (MCP_TOOL_MODE=condensed)

27 herramienta(s) enrutadas por acción · 0 herramienta(s) verbosa(s) 1:1. Cada una está habilitada a menos que su alternancia <DOMAIN>TOOL se establezca en falso; MCP_TOOL_MODE selecciona la superficie (**intent predeterminado* — las seis herramientas de verbo, conjunto granular cargado bajo demanda · condensed enrutado por acción · verbose 1:1 · both). Generado automáticamente — no editar.*

Los dominios de respaldo típicos incluyen ciclo de vida de SO/paquetes, servicios, procesos, redes, discos, archivos gestionados, eliminación de cron, reglas de cortafuegos estructuradas, diagnósticos de almacenamiento/BMC, administración del sistema operativo de agentes e ingesta de telemetría de host gobernada. Descubre un esquema de acción antes de llamarlo; las operaciones no disponibles no deben emularse con otra herramienta.

Ingesta de grafo de conocimiento

systems_ingest_host lee telemetría tipada local y envía una proyección en lista blanca a través del límite de ingesta gobernado nativo de Agent Utilities. Emite solo:

• Nodos HardwareNode, NetworkInterface y DiskVolume;

• Relaciones hasInterface y hasVolume;

• Identificadores opacos HMAC-SHA-256 derivados con la SYSTEMS_MANAGER_PSEUDONYMIZATION_KEY propiedad del despliegue.

Los nombres de host, direcciones de red, direcciones de hardware, nombres de usuario, rutas locales, credenciales y campos adicionales arbitrarios se rechazan o excluyen. La falta de autoridad de grafo, el contenido inválido y la ingesta no disponible fallan explícitamente; no son no-operaciones silenciosas.

Delegación de GraphOS

Las operaciones de host se ejecutan dentro del límite del sistema operativo local del servicio. Para trabajo de flota, GraphOS delega a un servicio systems-manager autenticado en el límite objetivo. El inventario, los endpoints, las credenciales, los perfiles TLS y los alias de destino permanecen como configuración de despliegue externa. Persiste solo referencias opacas y no personales.

La habilidad incluida systems-manager-operations cubre todos los flujos de trabajo actuales del proveedor. Las habilidades antiguas de comandos BMC y scripts de enlace NIC se consolidaron porque esas superficies de scripts sin procesar no forman parte del contrato tipado actual.

Servidor de agente

Instala el extra de agente y lanza:

pip install "systems-manager[agent]"
systems-manager-agent --help

Workspace, catálogo MCP y rutas de habilidades personalizadas solo se aceptan cuando están explícitamente configurados y presentes. No hay respaldo de configuración empaquetada ni de directorio actual. Un listener que no sea de bucle local requiere una puerta de permiso explícita, TLS directo o de proxy de confianza, configuración de emisor/JWKS/audiencia JWT y modo de depuración deshabilitado.

Variables de entorno

La tabla generada se obtiene de .env.example sin valores más el contrato heredado de Agent Utilities.

Variables de entorno del paquete

Variables heredadas de agent-utilities (aplican a cada conector)

47 variables del paquete + 19 heredadas. Generado automáticamente desde .env.example + el conjunto compartido de agent-utilities — no editar.

Puertas de desarrollo y lanzamiento

pytest -q
ruff check systems_manager tests
black --check systems_manager tests
mkdocs build --strict
pre-commit run --all-files

Ejecute operaciones de host solo a través de mocks durante las pruebas. No ejecute compilaciones nativas ni mutaciones de host en vivo como atajo de validación. El piso de dependencia de origen es intencionalmente agent-utilities>=2.0.0; regenere y confirme un lock neutral solo después de que esa versión esté disponible desde el índice de paquetes configurado. Nunca confirme una fuente local editable ni una resolución de dependencias obsoleta.

Consulte la documentación para detalles de instalación, despliegue, configuración, uso, delegación multi-host y seguridad.

Desplegar con agent-utilities-deployment

Aprovisione este paquete con el flujo de trabajo consolidado agent-utilities-deployment. Selecciona una ruta de paquete instalado, fuente editable o contenedor inmutable; registra solo referencias de secretos y perfiles TLS en tiempo de ejecución en AgentConfig; y ejecuta puertas de doctor, registro, políticas, observabilidad y reversión. Pida a su agente que "despliegue systems-manager con agent-utilities-deployment".

El repositorio no incluye ningún perfil de despliegue, valor de credencial, ruta de certificado ni endpoint específico de entorno. Proporcione esos en tiempo de ejecución a través de AgentConfig y el proveedor de secretos configurado.

Contrato de capacidad gobernada

Este paquete incluye una superficie de habilidades canónica y compacta con procedimientos especializados mantenidos como flujos de trabajo referenciados. Las herramientas MCP actuales, los metadatos de habilidades, connector_manifest.yml, la ontología, las asignaciones, las formas, los fixtures, las migraciones, las huellas de esquema de herramientas y los metadatos de certificación forman un contrato de capacidades versionado. Valídelos juntos; no confíe en nombres de herramientas obsoletos ni en envoltorios de habilidades históricos por tarea.

Los endpoints de tiempo de ejecución, las credenciales, la confianza de certificados, la identidad del inquilino, la retención y la política de observabilidad son entradas de despliegue y nunca son valores empaquetados. Consulte Configuración, confianza y privacidad antes de habilitar un transporte de red, la ingesta de conectores, la delegación de GraphOS o la exportación de trazas.