HaltProof

Verificaciones deterministas de fallo cerrado y recibos a prueba de manipulación para salidas de agentes de IA.

GitHubPrueba este MCPPatrocinado

Documentación

HaltProof

Orquestación de apagado de emergencia para clústeres Slurm, Kubernetes e IPMI, con un registro de atestación encadenado por hash y firmado con Ed25519 de exactamente lo que se ejecutó.

CI PyPI npm License: MIT

Orquestación de apagado firmada, con simulación previa por defecto, para clústeres Slurm, Kubernetes e IPMI, con un rastro de auditoría a prueba de manipulaciones.

HaltProof demo

HaltProof es una capa de orquestación de apagado de emergencia y prueba criptográfica de auditoría para clústeres de computación. No implementa un nuevo mecanismo de apagado de bajo nivel. Coordina las primitivas de clúster en las que ya confías (Slurm, Kubernetes, IPMI/BMC) y produce un registro firmado y a prueba de manipulaciones de exactamente qué se objetivo, qué se ejecutó y quién lo autorizó.

pip install haltproof-cli

(Las opciones completas de instalación, incluido el envoltorio npm, están en Instalación a continuación).

Por qué

Los operadores ya tienen las herramientas para drenar una partición de Slurm, aislar un grupo de nodos de Kubernetes o apagar físicamente un host mediante IPMI. Lo que suele faltar es:

  1. Una interfaz consistente entre esas herramientas durante un incidente, en lugar de tres conjuntos de comandos diferentes bajo presión.
  2. Una barandilla de seguridad con simulación previa por defecto, para que un grupo objetivo mal escrito no derribe los nodos equivocados.
  3. Un registro firmado y a prueba de manipulaciones de lo que sucedió: quién lo ejecutó, qué comandos se emitieron, contra qué nodos, si cada paso tuvo éxito y si el registro en sí ha sido alterado o le falta una pieza.

HaltProof es esa capa. Llama a scontrol, kubectl y ipmitool (o equivalentes invocables mediante mcp) y envuelve cada invocación en una atestación encadenada por hash y firmada con Ed25519.

Instalación

pip install haltproof-cli

También se publica un envoltorio npm para herramientas y tiempos de ejecución de agentes basados en Node.js:

npm install -g haltproof-cli

[!ADVERTENCIA] El paquete npm requiere que el paquete Python haltproof-cli ya esté instalado y en PATH. Es un envoltorio delgado de execFileSync, no una reimplementación. Si no puede encontrar la CLI de Python, imprime un error procesable y sale con código distinto de cero en lugar de hacer silenciosamente otra cosa.

Tabla de contenidos

Características

  • Simulación previa requerida por defecto. haltproof halt imprime exactamente qué comandos ejecutaría, contra qué nodos, y aún así escribe una atestación firmada de ese plan, a menos que pases --confirm. La compuerta reside en un único punto de estrangulamiento (haltproof.backends.runner.run_step) por el que pasan los tres backends, por lo que no puede ser eludida silenciosamente por la ruta de código de un backend.
  • Una interfaz para tres backends reales. kubernetes (vía kubectl), slurm (vía scontrol) y ipmi (vía ipmitool) implementan cada uno la misma interfaz de cuatro operaciones ClusterBackend: drain, isolate_network, power_fence, status. Un backend que no soporta una operación, por ejemplo Kubernetes no tiene una primitiva física de apagado por energía, devuelve un resultado SKIPPED con una explicación en lugar de lanzar una excepción, de modo que un apagado en un entorno mixto aún produce una atestación completa.
  • Atestaciones encadenadas por hash y firmadas con Ed25519. Cada apagado, simulado o ejecutado, agrega un registro firmado a un registro local NDJSON de solo agregar. Cada registro incorpora prev_hash, el hash de contenido del registro anterior, de modo que haltproof verify --chain puede detectar una entrada eliminada o reordenada que la verificación de firma de un solo registro pasaría por alto.
  • Salida estructurada en cada comando. --json (o --format json) está disponible en halt, verify, status y keygen, de modo que un script o un agente puede analizar el resultado sin extraer texto formateado para humanos.
  • Un servidor MCP real, construido para agentes. haltproof mcp-server expone halt, verify, verify_chain, status y keygen como herramientas MCP sobre stdio, construido sobre el SDK oficial de Python mcp. Llama a las mismas funciones haltproof.core que llama la CLI, de modo que un agente que invoca la herramienta MCP obtiene el comportamiento idéntico de simulación previa por defecto que un humano obtiene de la CLI.
  • Probado. 76 pruebas, 90% de cobertura general de líneas, ejecutadas y confirmadas en esta auditoría con pytest -v --cov=haltproof --cov-report=term-missing. Las pruebas de backend simulan llamadas subprocess; ninguna requiere un clúster real.

Inicio rápido

[!IMPORTANTE] haltproof halt es una no-operación sin --confirm. Imprime el plan y escribe una atestación de simulación previa firmada, pero nada destructivo se ejecuta hasta que pases --confirm explícitamente.

# Generate a signing key for attestations (do this once).
haltproof keygen --output ~/.config/haltproof/ed25519_key

# See what backend HaltProof auto-detected on this host.
haltproof status

# Dry-run a halt against an explicit node list. Nothing runs yet.
haltproof halt gpu-pod-a --nodes node-1,node-2

# Same halt, actually executed.
haltproof halt gpu-pod-a --nodes node-1,node-2 --confirm

# Verify a past attestation's signature and print its timeline.
haltproof verify 1

# Verify the entire attestation log's hash chain instead of a single
# record: this catches a deleted or reordered entry that a
# single-record signature check alone would miss.
haltproof verify --chain --attestation-log ~/.local/share/haltproof/attestations.jsonl

Cada comando también admite --json para salida analizable por agentes:

haltproof status --json
haltproof halt gpu-pod-a --nodes node-1 --json

Archivo de configuración (opcional)

Los grupos objetivo, el backend preferido y las rutas predeterminadas pueden vivir en un archivo haltproof.toml (verificado en el directorio actual, luego ~/.config/haltproof/config.toml, o en una ruta dada por --config / HALTPROOF_CONFIG):

backend = "kubernetes"
operator_id = "ops-team"
attestation_log_path = "/var/log/haltproof/attestations.jsonl"

[groups]
gpu-pod-a = ["node-1", "node-2", "node-3"]

[kubernetes]
namespace = "training"

[ipmi]
user = "admin"

Cada valor de configuración tiene una bandera CLI correspondiente, y una bandera explícita siempre gana sobre el archivo de configuración.

Comandos

La referencia a continuación se regenera a partir de la salida real de --help de la CLI.

haltproof halt TARGET_GROUP

Drena, aísla y apaga físicamente TARGET_GROUP. La simulación previa es el valor predeterminado; nada destructivo se ejecuta sin --confirm.

haltproof keygen, halt, and verify in sequence

Options:
  --nodes TEXT             Comma-separated explicit node list, overrides
                           config group lookup.
  --backend TEXT           Backend to use: kubernetes, slurm, or ipmi.
  --confirm                Actually execute the halt. Without this, dry-run
                           only.
  --reason TEXT            Reason recorded for drain operations.
  --operator-id TEXT       Operator identity to record. Defaults to OS user.
  --config TEXT            Path to a haltproof.toml config file.
  --attestation-log TEXT   Path to the attestation log file.
  --attestation-key TEXT   Path to the Ed25519 private key used to sign the
                           attestation.
  --no-sign                Skip signing (not recommended); still logs the
                           record unsigned.
  --remote-collector TEXT  Optional URL to POST the signed attestation to.
  --format [human|json]    Output format.
  --json                   Shorthand for --format=json.

haltproof verify [ATTESTATION_REF]

Verifica la firma de un registro de atestación, o toda la cadena de hash de un registro. ATTESTATION_REF es una ruta a un archivo de registro, o un id de atestación / número de secuencia para buscar en el registro. Pasa --chain en lugar de ATTESTATION_REF para verificar un --attestation-log completo: la firma de cada registro se mantiene, y ninguno ha sido eliminado o reordenado.

BanderaDescripción
--attestation-log TEXTRegistro a buscar cuando ATTESTATION_REF es un id/número de secuencia, o para verificar con --chain.
--trusted-key TEXTRuta a una clave pública Ed25519 de confianza; si se da, la clave de firma del registro debe coincidir.
--chainVerifica la cadena de hash completa de --attestation-log en lugar de un solo registro.
--format [human|json]Formato de salida.
--jsonAbreviatura de --format=json.

haltproof status

Muestra los resultados de auto-detección del backend y, opcionalmente, la salud del grupo objetivo.

BanderaDescripción
--backend TEXTBackend para verificar el estado; por defecto es el backend auto-detectado/configurado.
--nodes TEXTLista de nodos separada por comas para informar la salud.
--group TEXTGrupo objetivo nombrado (desde la configuración) para informar la salud.
--config TEXTRuta a un archivo de configuración haltproof.toml.
--format [human|json]Formato de salida.
--jsonAbreviatura de --format=json.

haltproof keygen

Genera un par de claves Ed25519 para la firma de atestaciones. La clave privada se escribe con permisos 0600 y nunca se imprime ni se registra.

haltproof keygen followed by status --json

Options:
  --output TEXT          Path to write the private key to.
  --force                Overwrite an existing key at the output path.
  --format [human|json]  Output format.
  --json                 Shorthand for --format=json.

haltproof mcp-server

Inicia el servidor MCP de HaltProof en stdio, exponiendo halt, verify, verify_chain, status y keygen como herramientas MCP. Sin banderas más allá de --help.

Cada subcomando también acepta --help directamente para la misma referencia mostrada arriba.

Arquitectura

HaltProof tiene tres capas:

  1. Capa de transporte: la CLI basada en Click (haltproof.cli) y el servidor MCP (haltproof.mcp_server). Ambos son envoltorios delgados sobre las mismas funciones centrales en haltproof.core, de modo que un humano que ejecuta la CLI y un agente que llama a la herramienta MCP obtienen un comportamiento idéntico, incluida la compuerta de simulación previa por defecto en halt.

  2. Capa de backend: una interfaz abstracta ClusterBackend (haltproof.backends.base) con cuatro operaciones:

    ClusterBackend
├── drain(nodes, dry_run, reason)         -> stop new work being scheduled
├── isolate_network(nodes, dry_run)       -> cut nodes off from the workload network
├── power_fence(nodes, dry_run)           -> hard power off
└── status(nodes)                         -> current reachability/state

    Tres backends la implementan hoy:

    Backenddrenaraislar_redapagado_físicoHerramienta subyacente
    kubernetescordon + draindeny-all NetworkPolicyno soportado (usa ipmi)kubectl
    slurmscontrol update state=drainstate=power_down (hook SuspendProgram)no soportado (usa ipmi)scontrol
    ipmino soportado (usa slurm/kubernetes)no soportadoipmitool chassis power offipmitool

    Un backend que no soporta una operación dada devuelve un resultado SKIPPED con una explicación en lugar de lanzar una excepción, de modo que una secuencia de apagado contra un entorno mixto aún produce un registro de atestación completo y honesto. Agregar soporte para un nuevo programador o herramienta de aislamiento significa agregar un módulo de backend y registrarlo en haltproof.backends.detect, sin tocar las capas de orquestación o atestación.

    Orden de selección del backend: una bandera explícita --backend, luego la clave backend del archivo de configuración, luego auto-detección basada en cuál de kubectl / scontrol / ipmitool se encuentra en PATH.

  3. Capa de atestación (haltproof.attestation): cada operación de apagado, simulada o real, produce un registro firmado y encadenado por hash y lo agrega a un registro local NDJSON de solo agregar.

Modelo de seguridad

  • Firma. Los registros de atestación se firman con Ed25519 (biblioteca cryptography). La clave pública de firma está incrustada en el propio registro, de modo que haltproof verify puede verificar la validez interna de la firma por sí solo. Pasa --trusted-key para requerir adicionalmente que el registro esté firmado por una clave de operador específica conocida.
  • Evidencia de manipulación, por registro. La firma cubre todo el registro, operador, nodos objetivo, el comando y estado de cada paso, marcas de tiempo y el enlace de la cadena debajo, excepto el campo de firma en sí. Cambiar cualquier campo, incluido ocultar un paso fallido, invalida la firma.
  • Evidencia de manipulación, a través del registro. La firma de un registro solo prueba que el contenido de ese registro no está alterado; no dice nada sobre si un registro completo fue eliminado o reordenado. Cada registro incorpora prev_hash, el hash de contenido del registro inmediatamente anterior, de modo que haltproof verify --chain puede confirmar que los números de secuencia no tienen huecos y que cada enlace de la cadena coincide.
  • Manejo de claves. haltproof keygen escribe la clave privada con permisos 0600 y nunca imprime ni registra material de clave, en la salida de la CLI, la salida JSON o el resultado de la herramienta MCP. Cualquiera que tenga la clave puede firmar registros que se verifican como tuyos, así que trátala como una clave privada SSH.
  • Credenciales BMC. El backend IPMI lee la contraseña BMC de la variable de entorno IPMI_PASSWORD y pasa ipmitool -E, de modo que nunca aparece como argumento de línea de comandos, en la lista de procesos o en el comando registrado del registro de atestación.
  • Simulación previa por defecto. haltproof halt requiere un --confirm explícito para ejecutar cualquier cosa destructiva, aplicado en un único punto de estrangulamiento (haltproof.backends.runner.run_step) por el que pasan todos los backends.
  • Identidad del operador. Registrada desde, en orden, un --operator-id explícito, una identidad de certificado SSH si el entorno expone una, o el usuario del sistema operativo que ejecuta el comando.

Servidor MCP (para agentes de IA)

haltproof mcp-server

Inicia un servidor MCP en stdio exponiendo halt, verify, verify_chain, status y keygen como herramientas, construido sobre el SDK oficial de Python mcp. Un agente conectado a través de MCP obtiene el mismo comportamiento de simulación previa por defecto de halt y los mismos resultados con forma JSON que el modo --json de la CLI, porque la CLI y el servidor MCP llaman a las mismas funciones subyacentes en haltproof.core.

Comparación

HaltProof no compite con Slurm, Kubernetes o IPMI. Se sitúa sobre las herramientas que los operadores ya usan para esta tarea y añade lo que ninguna de ellas proporciona por sí sola: una interfaz, una puerta de seguridad y un registro firmado.

CapacidadHaltProofkubectl (nativo)scontrol (nativo)ipmitool (nativo)
Comando único en Slurm + Kubernetes + IPMISíNo, solo KubernetesNo, solo SlurmNo, solo IPMI
Puerta de dry-run consistente antes de que cualquier backend ejecuteSí, una bandera --confirm para los tres backendsParcial: --dry-run=client solo valida sintaxis, no la mutación real del clústerSin modo de simulación integrado; state=drain surte efecto de inmediatoSin concepto de dry-run para comandos de energía
Registro criptográficamente firmado de lo que se ejecutóSí, Ed25519NoNoNo
Detecta un registro eliminado o reordenado en la pista de auditoríaSí, registro encadenado por hashNoNoNo
Salida JSON estructurada para cada acciónSí, cada comandoParcial: -o json cubre comandos de lectura/obtención, no el resultado de la acción drain/cordonNo, solo texto planoNo, solo texto plano
Servidor MCP para invocación directa por agentes de IASíNoNoNo

Una búsqueda en GitHub realizada para esta auditoría (agosto de 2026) no encontró ningún proyecto de código abierto existente que combine orquestación de clústeres multi-backend unificada, una puerta de dry-run por defecto y una pista de auditoría encadenada por hash y criptográficamente firmada. Los proyectos adyacentes más cercanos, como los proxies de políticas de llamadas a herramientas de agentes de IA, operan una capa más arriba: interceptan y auditan lo que las llamadas a herramientas de un agente de IA pueden hacer, no el apagado a nivel de infraestructura de la propia computación subyacente. Consulta las preguntas frecuentes a continuación para ver cómo se relaciona HaltProof con esa categoría.

Qué es HaltProof y por qué existe

HaltProof es una capa de orquestación y prueba de auditoría sobre las primitivas de apagado de clústeres que los operadores ya confían: scontrol para Slurm, kubectl para Kubernetes, ipmitool para IPMI/BMC. No reimplementa el drenaje, el aislamiento o el corte de energía de un nodo. Llama a la herramienta real, protege la llamada detrás de una verificación de seguridad de dry-run por defecto y firma un registro a prueba de manipulaciones de exactamente qué se apuntó, qué se ejecutó y quién lo autorizó.

Existe porque tres problemas separados tienden a aparecer juntos durante un incidente real:

  1. Tres conjuntos de comandos diferentes bajo presión. Los operadores ya saben cómo drenar una partición de Slurm, aislar un grupo de nodos de Kubernetes o cortar la energía de un host físico mediante IPMI, pero hacerlo de manera consistente en los tres durante un incidente significa tres herramientas diferentes, tres convenciones de banderas diferentes y tres modos de fallo diferentes que recordar en el peor momento posible.
  2. Sin riel de seguridad compartido. kubectl drain --dry-run=client solo valida sintaxis; no simula la mutación real del clúster. scontrol update state=drain surte efecto en el momento en que lo ejecutas. Un grupo de destino mal escrito no tiene una forma consistente e independiente de la herramienta de detectarse antes de que algo real suceda.
  3. Sin prueba después del hecho. Ninguna de las tres herramientas nativas produce un registro firmado y a prueba de manipulaciones de qué se apuntó, qué se ejecutó realmente, si tuvo éxito y quién lo autorizó. Construir esa capa de registro y firma por tu cuenta, para evidencia de gestión de cambios o para un marco de cumplimiento como las disposiciones de supervisión humana de la Ley de IA de la UE, significa escribirlo desde cero.

HaltProof es la capa que responde a los tres a la vez: una CLI y una superficie MCP, una puerta --confirm por la que pasan todos los backends y un registro de atestación encadenado por hash y firmado con Ed25519.

Preguntas frecuentes

¿Qué hace realmente HaltProof y cuál es su diferencia más marcada con simplemente escribir scripts de kubectl/scontrol/ipmitool directamente? HaltProof llama a las mismas herramientas que llamarías directamente, scontrol, kubectl, ipmitool, pero envuelve cada llamada en una puerta de dry-run por defecto y produce un registro de atestación encadenado por hash y firmado con Ed25519. Un script hecho a mano puede llamar a los mismos comandos subyacentes, pero no se niega a ejecutar sin --confirm y no produce un registro que demuestre, después del hecho, que nada fue alterado o eliminado del registro.

¿HaltProof realmente corta la energía o el acceso a la red por sí mismo? No. Llama a scontrol, kubectl y ipmitool, herramientas que ya ejecutas y en las que confías, y envuelve cada invocación en una puerta de dry-run y un registro firmado. HaltProof añade orquestación y prueba, no un nuevo mecanismo de apagado de bajo nivel.

¿Qué sistemas operativos y versiones de Python soporta HaltProof? El paquete PyPI publicado está dirigido a Python 3.10 y superior, en Linux y macOS (consulta sus clasificadores Operating System :: POSIX :: Linux y Operating System :: MacOS). Aún no hay un clasificador para Windows, y el backend de IPMI en particular depende de ejecutar comandos externos a ipmitool, que no es el objetivo principal en Windows. Si lo necesitas allí, abre un issue.

¿En qué se diferencia esto de escribir un runbook o un playbook de Ansible que llame a las mismas herramientas? Un runbook o un playbook de Ansible puede llamar a los mismos comandos subyacentes, pero no produce un registro criptográficamente firmado y a prueba de manipulaciones de lo que realmente se ejecutó por sí solo; necesitarías construir esa capa de registro y firma por tu cuenta. HaltProof lo incluye como comportamiento predeterminado, y también te da una única puerta de dry-run por defecto en los tres backends en lugar de tres playbooks separados con tres convenciones de seguridad separadas.

¿Es esto un "interruptor de seguridad para IA"? No. HaltProof es una herramienta de respuesta a incidentes de infraestructura y auditoría de cumplimiento para operadores de clústeres. No tiene opinión sobre el comportamiento de los modelos de IA y no hace afirmaciones sobre seguridad o alineación de IA. Las herramientas que interceptan y auditan las llamadas individuales a herramientas de un agente de IA operan en una capa completamente diferente; HaltProof orquesta el apagado de la computación subyacente en sí, de la misma manera que lo haría para una carga de trabajo no relacionada con IA.

¿Qué sucede si la herramienta subyacente de un nodo no está instalada? El backend correspondiente informa ese paso como failed con el error real, por ejemplo executable not found, y el registro de atestación aún se escribe y firma, por lo que el fallo en sí mismo pasa a formar parte del historial auditable.

¿Puedo usar HaltProof sin firmar atestaciones? Sí, --no-sign omite la firma pero aún escribe el registro en el registro. Esto está pensado para pruebas locales, no para respuesta a incidentes en producción, ya que un registro sin firmar no puede verificarse como auténtico.

¿El registro de atestación necesita un servidor central? No. Es un archivo NDJSON local de solo añadido por defecto. --remote-collector opcionalmente envía cada registro firmado a una URL que configures, para equipos que quieran una copia central, pero la verificación no depende de que ese servidor sea accesible.

¿Qué sucede si dos operadores ejecutan halt al mismo tiempo contra el mismo registro de atestación? Los añadidos están bloqueados por archivo (fcntl.flock en POSIX) para que las escrituras no se intercalen, pero los números de secuencia se asignan leyendo el registro en el momento en que cada comando comienza. Apunta a ambos operadores a archivos de registro específicos del backend o por incidente si necesitas serialización estricta por operación.

¿Bajo qué licencia está HaltProof y puedo usarlo comercialmente? MIT. Puedes usar, modificar y redistribuirlo, incluso comercialmente, siempre que el aviso de copyright y el texto de la licencia permanezcan adjuntos. Consulta LICENSE.

Contribuciones

Las contribuciones son bienvenidas. Lee CONTRIBUTING.md primero: cubre la configuración de un entorno de desarrollo, la ejecución de la suite de pruebas (pytest -v --cov=haltproof --cov-report=term-missing) y los pasos para añadir un nuevo backend implementando la interfaz ClusterBackend. Los cambios que toquen la firma/verificación de atestaciones o la puerta de dry-run/--confirm reciben revisión adicional, según CODEOWNERS. Consulta SECURITY.md para informar una vulnerabilidad de forma privada en lugar de abrir un issue público.

git clone https://github.com/RudrenduPaul/HaltProof.git
cd HaltProof
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -v --cov=haltproof --cov-report=term-missing

Licencia

MIT © Rudrendu Paul y Sourav Nandy