HaltProof

HaltProof

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

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 del 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 apuntó, qué se ejecutó y quién lo autorizó.

Úsalo para respuesta a incidentes, evidencia de gestión de cambios y reportes de cumplimiento: por ejemplo, para generar un rastro auditable de "supervisión humana" para acciones de infraestructura de computación, el tipo de evidencia requerida por marcos como las disposiciones de supervisión humana de la Ley de IA de la UE.

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 aplicar un corte de energía a un host físico 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 de simulación previa por defecto, para que un grupo de destino 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 por mcp) y envuelve cada invocación en una atestación firmada con Ed25519 y encadenada por hash.

Instalación

Python (distribución principal):

pip install haltproof-cli

Node.js / npm (envoltorio alrededor de la CLI de Python):

npm install -g haltproof-cli

[!ADVERTENCIA] El paquete npm requiere que el paquete haltproof-cli de Python 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 un código distinto de cero en lugar de hacer silenciosamente otra cosa.

Inicio rápido

[!IMPORTANTE] haltproof halt es una operación nula 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 is intact, not just
# one record: 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 estructurada y analizable por agentes:

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

La simulación previa es el valor por defecto

haltproof halt nunca ejecuta nada destructivo a menos que pases --confirm. Sin él, HaltProof imprime exactamente qué comandos ejecutaría, contra qué nodos, en qué orden, y aún así escribe un registro de atestación firmado de ese plan de simulación previa, de modo que "qué habría sucedido" también sea auditable.

Archivo de configuración (opcional)

Los grupos de destino, el backend preferido y las rutas predeterminadas se pueden definir en un archivo haltproof.toml (en el directorio actual, en ~/.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.

Comparación

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

Capacidad	HaltProof	kubectl (nativo)	scontrol (nativo)	ipmitool (nativo)
Comando único en Slurm + Kubernetes + IPMI	Sí	No, solo Kubernetes	No, solo Slurm	No, solo IPMI
Puerta de simulación previa consistente antes de que cualquier backend ejecute	Sí, una bandera --confirm para los tres backends	Parcial: --dry-run=client valida solo sintaxis, no la mutación real del clúster	Sin modo de simulación integrado; state=drain surte efecto inmediatamente	Sin concepto de simulación previa para comandos de energía
Registro firmado criptográficamente de lo que se ejecutó	Sí, Ed25519	No	No	No
Detecta un registro eliminado o reordenado en el rastro de auditoría	Sí, registro encadenado por hash	No	No	No
Salida JSON estructurada para cada acción	Sí, cada comando	Parcial: -o json cubre comandos de lectura/obtención, no el resultado de la acción drain/cordon	No, solo texto plano	No, solo texto plano
Servidor MCP para invocación directa por agentes de IA	Sí	No	No	No

Una búsqueda en vivo de GitHub (2026-08-03) no encontró ningún proyecto de código abierto existente que combine orquestación unificada de múltiples backends, una puerta de simulación previa por defecto y un rastro de auditoría firmado criptográficamente y encadenado por hash para operaciones de apagado de clúster. Los proyectos adyacentes más cercanos apuntan a una capa completamente diferente: investigación de comportamiento/alineación en salidas de modelos, no orquestación de apagado a nivel de infraestructura con un rastro de auditoría.

Referencia de comandos CLI

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

haltproof halt TARGET_GROUP

Drena, aísla y aplica corte de energía a TARGET_GROUP.

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 que contiene el registro, o un id de atestación / número de secuencia para buscar en el registro de atestaciones. Pasa --chain en lugar de ATTESTATION_REF para verificar que un --attestation-log completo esté intacto: la firma de cada registro se mantiene, los números de secuencia no tienen huecos y ningún registro ha sido eliminado o reordenado.

Options:
  --attestation-log TEXT  Path to the attestation log to search when
                          ATTESTATION_REF is an id or sequence number, or
                          to verify with --chain.
  --trusted-key TEXT      Path to a trusted Ed25519 public key; if given, the
                          record's signing key must match it.
  --chain                 Verify the full hash chain of --attestation-log
                          instead of a single record.
  --format [human|json]   Output format.
  --json                  Shorthand for --format=json.

haltproof status

Muestra los resultados de detección automática de backend y la salud opcional del grupo de destino.

Options:
  --backend TEXT         Backend to check status for; defaults to auto-
                         detected/configured backend.
  --nodes TEXT           Comma-separated node list to report health for.
  --group TEXT           Named target group (from config) to report health
                         for.
  --config TEXT          Path to a haltproof.toml config file.
  --format [human|json]  Output format.
  --json                 Shorthand for --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.

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 transporte stdio, exponiendo halt, verify, verify_chain, status y keygen como herramientas MCP para que un agente de IA las invoque programáticamente.

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 puerta 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:

   Backend	drenar	aislar_red	corte_energía	Herramienta subyacente
   kubernetes	cordon + drain	NetworkPolicy de denegar todo	no compatible (usa ipmi)	kubectl
   slurm	scontrol update state=drain	state=power_down (hook SuspendProgram)	no compatible (usa ipmi)	scontrol
   ipmi	no compatible (usa slurm/kubernetes)	no compatible	ipmitool chassis power off	ipmitool

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

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

3. Capa de atestación (haltproof.attestation): cada operación de detención (simulación previa o real) produce un registro firmado y encadenado por hash y lo agrega a un registro local de solo anexión con líneas delimitadas por JSON.

Modelo de seguridad

• Firma. Los registros de atestación se firman con Ed25519 (biblioteca cryptography). La clave pública de firma del registro está incrustada en el propio registro (las claves públicas no son secretas), de modo que haltproof verify pueda verificar la validez de la firma interna por sí solo. Pasa --trusted-key para requerir adicionalmente que el registro esté firmado por una clave de operador conocida específica.
• Evidencia de manipulación, por registro. La firma cubre todo el registro (operador, nodos de destino, el comando y estado de cada paso, marcas de tiempo, el enlace de cadena descrito a continuación) excepto el propio campo de firma. Cambiar cualquier campo, incluido ocultar un paso fallido o reescribir quién autorizó la detención, invalida la firma.
• Evidencia de manipulación, en todo el registro. Una firma por sí sola solo prueba que el contenido de un registro no ha sido alterado. No dice nada sobre si un registro fue eliminado del registro o reordenado. Cada registro incrusta prev_hash, el hash de contenido del registro inmediatamente anterior, de modo que haltproof verify --chain pueda confirmar que los números de secuencia no tienen huecos y que cada enlace de la cadena coincide, detectando un registro eliminado o reordenado incluso aunque las firmas individuales de sus vecinos sigan siendo válidas por sí solas.
• Manejo de claves. haltproof keygen escribe la clave privada con permisos 0600 y nunca imprime ni registra material de clave, en la salida CLI, la salida JSON o el resultado de la herramienta MCP. Trata la clave privada como una clave privada SSH: haz una copia de seguridad en algún lugar con control de acceso y rótala si sospechas exposición. Cualquiera que la tenga puede firmar registros que se verifiquen como provenientes de ti.
• 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. Esto se aplica en un único punto de estrangulamiento (haltproof.backends.runner.run_step) por el que pasan todos los backends, no se reimplementa por backend.
• 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 que expone 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 halt con simulación previa por defecto y los mismos resultados con forma JSON que el modo --json de la CLI: la CLI y el servidor MCP llaman a las mismas funciones subyacentes en haltproof.core.

Preguntas frecuentes

¿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 simulación previa y un registro firmado. HaltProof añade orquestación y prueba, no un nuevo mecanismo de apagado de bajo nivel.

¿Qué sucede si la herramienta subyacente de un nodo no está instalada? El backend relevante 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, de modo que el fallo en sí es 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 se puede verificar como auténtico. ¿El registro de atestación necesita un servidor central? No. Es un archivo NDJSON local, de solo anexar (append-only) por defecto. --remote-collector opcionalmente envía cada registro firmado a una URL que configures, para equipos que quieran una copia central, pero nada en la verificación depende de que ese servidor sea accesible.

¿En qué se diferencia esto de simplemente escribir un runbook o un playbook de Ansible? Un runbook o playbook puede llamar a las mismas herramientas subyacentes, pero no produce un registro criptográficamente firmado y a prueba de manipulaciones de lo que realmente se ejecutó por sí solo. Tendrías que construir esa capa de registro y firma tú mismo. HaltProof lo incluye como comportamiento predeterminado.

¿Qué sucede si dos operadores ejecutan halt al mismo tiempo contra el mismo registro de atestación? Los anexos 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 una serialización estricta por operación.

¿Es esto un "interruptor de seguridad de IA"? No. HaltProof es una herramienta de respuesta a incidentes y auditoría de cumplimiento de infraestructura 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. Orquesta primitivas de apagado existentes y demuestra qué se ejecutó, de la misma manera que lo haría para una carga de trabajo no relacionada con IA.

Desarrollo

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

Consulta CONTRIBUTING.md para saber cómo agregar un nuevo backend y SECURITY.md para saber cómo reportar una vulnerabilidad.

Licencia

MIT © Rudrendu Paul y Sourav Nandy