HaltProof

HaltProof

Orquestração de desligamento de emergência para clusters Slurm, Kubernetes e IPMI, com um registro de atestação assinado por Ed25519 e encadeado por hash, documentando exatamente o que foi executado.

Orquestração de desligamento assinada, com dry-run por padrão, para clusters Slurm, Kubernetes e IPMI, com trilha de auditoria à prova de adulteração.

HaltProof é uma camada de orquestração de desligamento de emergência e prova criptográfica de auditoria para clusters de computação. Ele não implementa um novo mecanismo de desligamento de baixo nível. Ele coordena primitivas de cluster que você já confia (Slurm, Kubernetes, IPMI/BMC) e produz um registro assinado e à prova de adulteração, documentando exatamente o que foi alvo, o que foi executado e quem autorizou.

pip install haltproof-cli

(Opções completas de instalação, incluindo o wrapper npm, estão em Instalação abaixo.)

Por quê

Operadores já possuem as ferramentas para drenar uma partição Slurm, isolar um pool de nós Kubernetes ou desligar fisicamente um host via IPMI. O que geralmente falta é:

1. Uma interface consistente entre essas ferramentas durante um incidente, em vez de três conjuntos de comandos diferentes sob pressão.
2. Uma proteção de dry-run por padrão, para que um grupo de alvos digitado incorretamente não derrube os nós errados.
3. Um registro assinado e à prova de adulteração do que aconteceu: quem executou, quais comandos foram emitidos, contra quais nós, se cada etapa foi bem-sucedida e se o próprio registro foi alterado ou possui alguma parte ausente.

HaltProof é essa camada. Ele chama scontrol, kubectl e ipmitool (ou equivalentes invocáveis via mcp) e envolve cada invocação em uma atestação assinada por Ed25519 e encadeada por hash.

Instalação

pip install haltproof-cli

Um wrapper npm também é publicado para ferramentas baseadas em Node.js e runtimes de agentes:

npm install -g haltproof-cli

[!WARNING] O pacote npm requer que o pacote Python haltproof-cli já esteja instalado e no PATH. É um wrapper fino de execFileSync, não uma reimplementação. Se não encontrar o CLI Python, ele imprime um erro acionável e sai com código não zero, em vez de silenciosamente fazer outra coisa.

Sumário

• Recursos
• Início rápido
• Comandos
• Arquitetura
• Modelo de segurança
• Servidor MCP (para agentes de IA)
• Comparação
• O que é HaltProof e por que ele existe
• FAQ
• Contribuindo
• Licença

Recursos

• Dry-run obrigatório por padrão. haltproof halt imprime exatamente quais comandos executaria, contra quais nós, e ainda escreve uma atestação assinada desse plano, a menos que você passe --confirm. A proteção reside em um único ponto de verificação (haltproof.backends.runner.run_step) pelo qual todos os três backends passam, para que não possa ser silenciosamente contornada pelo caminho de código de um backend.
• Uma interface para três backends reais. kubernetes (via kubectl), slurm (via scontrol) e ipmi (via ipmitool) implementam cada um a mesma interface de quatro operações ClusterBackend: drain, isolate_network, power_fence, status. Um backend que não suporta uma operação, por exemplo Kubernetes não possui primitiva física de desligamento de energia, retorna um resultado SKIPPED com uma explicação em vez de gerar erro, para que um desligamento em um ambiente misto ainda produza uma atestação completa.
• Atestações assinadas por Ed25519 e encadeadas por hash. Cada desligamento, dry-run ou executado, anexa um registro assinado a um log local NDJSON somente de acréscimo. Cada registro incorpora prev_hash, o hash de conteúdo do registro anterior, para que haltproof verify --chain possa detectar uma entrada excluída ou reordenada que a verificação de assinatura de um único registro não detectaria.
• Saída estruturada em todos os comandos. --json (ou --format json) está disponível em halt, verify, status e keygen, para que um script ou agente possa analisar o resultado sem depender de texto formatado para humanos.
• Um servidor MCP real, construído para agentes. haltproof mcp-server expõe halt, verify, verify_chain, status e keygen como ferramentas MCP via stdio, construído sobre o SDK Python oficial mcp. Ele chama as mesmas funções haltproof.core que o CLI chama, para que um agente que invoque a ferramenta MCP obtenha o mesmo comportamento de dry-run por padrão que um humano obtém no CLI.
• Testado. 76 testes, 90% de cobertura geral de linhas, executados e confirmados nesta auditoria com pytest -v --cov=haltproof --cov-report=term-missing. Os testes de backend simulam chamadas subprocess; nenhum deles requer um cluster real.

Início rápido

[!IMPORTANT] haltproof halt é um no-op sem --confirm. Ele imprime o plano e escreve uma atestação de dry-run assinada, mas nada destrutivo é executado até que você passe --confirm explicitamente.

# 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

Todo comando também suporta --json para saída analisável por agentes:

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

Arquivo de configuração (opcional)

Grupos de alvos, o backend preferido e caminhos padrão podem estar em um arquivo haltproof.toml (verificado no diretório atual, depois em ~/.config/haltproof/config.toml, ou em um caminho fornecido 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"

Todo valor de configuração possui uma flag CLI correspondente, e uma flag explícita sempre prevalece sobre o arquivo de configuração.

Comandos

A referência abaixo é regenerada a partir da saída real de --help do CLI.

haltproof halt TARGET_GROUP

Drenar, isolar e desligar fisicamente TARGET_GROUP. Dry-run é o padrão; nada destrutivo é executado sem --confirm.

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]

Verificar a assinatura de um registro de atestação, ou a cadeia de hash de um log inteiro. ATTESTATION_REF é um caminho para um arquivo de registro, ou um id de atestação / número de sequência para buscar no log. Passe --chain em vez de ATTESTATION_REF para verificar um --attestation-log inteiro: a assinatura de cada registro é válida, e nenhum foi excluído ou reordenado.

Flag	Descrição
--attestation-log TEXT	Log a ser pesquisado quando ATTESTATION_REF é um id/número de sequência, ou para verificar com --chain.
--trusted-key TEXT	Caminho para uma chave pública Ed25519 confiável; se fornecido, a chave de assinatura do registro deve corresponder a ela.
--chain	Verificar a cadeia de hash completa de --attestation-log em vez de um único registro.
--format [human|json]	Formato de saída.
--json	Abreviação para --format=json.

haltproof status

Mostrar resultados de autodetecção de backend e, opcionalmente, a saúde do grupo de alvos.

Flag	Descrição
--backend TEXT	Backend para verificar o status; o padrão é o backend autodetectado/configurado.
--nodes TEXT	Lista de nós separada por vírgulas para relatar a saúde.
--group TEXT	Grupo de alvos nomeado (do config) para relatar a saúde.
--config TEXT	Caminho para um arquivo de configuração haltproof.toml.
--format [human|json]	Formato de saída.
--json	Abreviação para --format=json.

haltproof keygen

Gerar um par de chaves Ed25519 para assinatura de atestação. A chave privada é escrita com permissões 0600 e nunca é impressa ou registrada em log.

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 o servidor MCP HaltProof via stdio, expondo halt, verify, verify_chain, status e keygen como ferramentas MCP. Sem flags além de --help.

Todo subcomando também aceita --help diretamente para a mesma referência mostrada acima.

Arquitetura

HaltProof possui três camadas:

1. Camada de transporte: o CLI baseado em Click (haltproof.cli) e o servidor MCP (haltproof.mcp_server). Ambos são wrappers finos sobre as mesmas funções principais em haltproof.core, para que um humano executando o CLI e um agente chamando a ferramenta MCP obtenham comportamento idêntico, incluindo a proteção de dry-run por padrão em halt.

2. Camada de backend: uma interface abstrata ClusterBackend (haltproof.backends.base) com quatro operações:

   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
   

   Três backends a implementam hoje:

   Backend	drain	isolate_network	power_fence	Ferramenta subjacente
   kubernetes	cordon + drain	deny-all NetworkPolicy	não suportado (use ipmi)	kubectl
   slurm	scontrol update state=drain	state=power_down (hook SuspendProgram)	não suportado (use ipmi)	scontrol
   ipmi	não suportado (use slurm/kubernetes)	não suportado	ipmitool chassis power off	ipmitool

   Um backend que não suporta uma determinada operação retorna um resultado SKIPPED com uma explicação em vez de gerar erro, para que uma sequência de desligamento em um ambiente misto ainda produza um registro de atestação completo e honesto. Adicionar suporte para um novo agendador ou ferramenta de isolamento significa adicionar um módulo de backend e registrá-lo em haltproof.backends.detect, sem tocar nas camadas de orquestração ou atestação.

   Ordem de seleção de backend: uma flag explícita --backend, depois a chave backend do arquivo de configuração, depois autodetecção baseada em qual de kubectl / scontrol / ipmitool é encontrado no PATH.

3. Camada de atestação (haltproof.attestation): toda operação de desligamento, dry-run ou real, produz um registro assinado e encadeado por hash e o anexa a um log local NDJSON somente de acréscimo.

Modelo de segurança

• Assinatura. Registros de atestação são assinados com Ed25519 (biblioteca cryptography). A chave pública de assinatura é incorporada no próprio registro, para que haltproof verify possa verificar a validade interna da assinatura por conta própria. Passe --trusted-key para exigir adicionalmente que o registro seja assinado por uma chave específica de operador conhecido.
• Evidência de adulteração, por registro. A assinatura cobre o registro inteiro, operador, nós alvo, comando e status de cada etapa, timestamps e o link da cadeia abaixo, exceto o próprio campo de assinatura. Alterar qualquer campo, incluindo ocultar uma etapa com falha, invalida a assinatura.
• Evidência de adulteração, em todo o log. A assinatura de um registro apenas prova que o conteúdo daquele registro não foi alterado; ela não diz nada sobre se um registro inteiro foi excluído ou reordenado. Cada registro incorpora prev_hash, o hash de conteúdo do registro imediatamente anterior, para que haltproof verify --chain possa confirmar que os números de sequência não têm lacunas e que cada link da cadeia corresponde.
• Manuseio de chaves. haltproof keygen escreve a chave privada com permissões 0600 e nunca imprime ou registra material de chave, na saída do CLI, na saída JSON ou no resultado da ferramenta MCP. Qualquer pessoa que possua a chave pode assinar registros que serão verificados como vindos de você, portanto trate-a como uma chave privada SSH.
• Credenciais BMC. O backend IPMI lê a senha BMC da variável de ambiente IPMI_PASSWORD e passa ipmitool -E, para que nunca apareça como argumento de linha de comando, na lista de processos ou no comando registrado no log da atestação.
• Dry-run por padrão. haltproof halt exige um --confirm explícito para executar qualquer coisa destrutiva, aplicado em um único ponto de verificação (haltproof.backends.runner.run_step) pelo qual todo backend passa.
• Identidade do operador. Registrada a partir de, em ordem, um --operator-id explícito, uma identidade de certificado SSH se o ambiente expuser uma, ou o usuário do SO que executa o comando.

Servidor MCP (para agentes de IA)

haltproof mcp-server

Inicia um servidor MCP via stdio expondo halt, verify, verify_chain, status e keygen como ferramentas, construído sobre o SDK Python oficial mcp. Um agente conectado via MCP obtém o mesmo comportamento halt de dry-run por padrão e os mesmos resultados em formato JSON que o modo --json do CLI, porque o CLI e o servidor MCP chamam as mesmas funções subjacentes em haltproof.core.

Comparação

Capacidade	HaltProof	kubectl (nativo)	scontrol (nativo)	ipmitool (nativo)
Comando único em Slurm + Kubernetes + IPMI	Sim	Não, apenas Kubernetes	Não, apenas Slurm	Não, apenas IPMI
Gate de simulação consistente antes de qualquer backend executar	Sim, uma flag --confirm para os três backends	Parcial: --dry-run=client valida apenas sintaxe, não a mutação real do cluster	Sem modo de simulação integrado; state=drain entra em vigor imediatamente	Sem conceito de simulação para comandos de energia
Registro assinado criptograficamente do que foi executado	Sim, Ed25519	Não	Não	Não
Detecta um registro excluído ou reordenado na trilha de auditoria	Sim, log encadeado por hash	Não	Não	Não
Saída JSON estruturada para cada ação	Sim, todos os comandos	Parcial: -o json cobre comandos de leitura/obtenção, não o resultado da ação drain/cordon	Não, apenas texto simples	Não, apenas texto simples
Servidor MCP para invocação direta por agente de IA	Sim	Não	Não	Não

Uma pesquisa no GitHub realizada para esta auditoria (agosto de 2026) não encontrou nenhum projeto de código aberto existente que combine orquestração de cluster multi-backend unificada, um gate de simulação por padrão e uma trilha de auditoria assinada criptograficamente e encadeada por hash. Os projetos adjacentes mais próximos, como proxies de política de chamada de ferramentas de agentes de IA, operam uma camada acima: eles interceptam e auditam o que as chamadas de ferramentas de um agente de IA podem fazer, não o desligamento em nível de infraestrutura da própria computação subjacente. Veja o FAQ abaixo para saber como o HaltProof se relaciona a essa categoria.

O que é o HaltProof e por que ele existe

O HaltProof é uma camada de orquestração e prova de auditoria sobre primitivas de desligamento de cluster que os operadores já confiam: scontrol para Slurm, kubectl para Kubernetes, ipmitool para IPMI/BMC. Ele não reimplementa o dreno, o isolamento ou o power-fencing de um nó. Ele chama a ferramenta real, protege a chamada com uma verificação de segurança de simulação por padrão e assina um registro à prova de adulteração de exatamente o que foi alvo, o que foi executado e quem autorizou.

Ele existe porque três problemas separados tendem a aparecer juntos durante um incidente real:

1. Três conjuntos de comandos diferentes sob pressão. Os operadores já sabem como drenar uma partição Slurm, isolar um pool de nós Kubernetes ou fazer power-fencing de um host físico via IPMI, mas fazer isso de forma consistente nos três durante um incidente significa três ferramentas diferentes, três convenções de flags diferentes e três modos de falha diferentes para lembrar no pior momento possível.
2. Sem trilho de segurança compartilhado. kubectl drain --dry-run=client apenas valida sintaxe; não simula a mutação real do cluster. scontrol update state=drain entra em vigor no momento em que você o executa. Um grupo de destino digitado incorretamente não tem uma maneira consistente e independente de ferramenta de se auto-corrigir antes que algo real aconteça.
3. Sem prova depois do fato. Nenhuma das três ferramentas nativas produz um registro assinado e à prova de adulteração do que foi alvo, do que realmente foi executado, se teve sucesso e quem autorizou. Construir essa camada de registro e assinatura você mesmo, para evidências de gerenciamento de mudanças ou para um framework de conformidade como as disposições de supervisão humana do EU AI Act, significa escrever do zero.

O HaltProof é a camada que responde a todos os três de uma vez: uma CLI e uma superfície MCP, um gate --confirm pelo qual todo backend passa, e um log de atestação assinado com Ed25519 e encadeado por hash.

FAQ

O que o HaltProof realmente faz e qual é a diferença mais marcante em relação a apenas criar scripts com kubectl/scontrol/ipmitool diretamente? O HaltProof chama as mesmas ferramentas que você chamaria diretamente, scontrol, kubectl, ipmitool, mas envolve cada chamada em um gate de simulação por padrão e produz um registro de atestação assinado com Ed25519 e encadeado por hash. Um script feito à mão pode chamar os mesmos comandos subjacentes, mas não se recusa a executar sem --confirm e não produz um registro que prove, depois do fato, que nada foi alterado ou excluído do log.

O HaltProof realmente corta energia ou acesso à rede por conta própria? Não. Ele chama scontrol, kubectl e ipmitool, ferramentas que você já executa e confia, e envolve cada invocação em um gate de simulação e um registro assinado. O HaltProof adiciona orquestração e prova, não um novo mecanismo de desligamento de baixo nível.

Quais sistemas operacionais e versões do Python o HaltProof suporta? O pacote PyPI publicado tem como alvo Python 3.10 e superior, em Linux e macOS (veja seus classificadores Operating System :: POSIX :: Linux e Operating System :: MacOS). Ainda não há classificador para Windows, e o backend IPMI em particular depende de chamadas externas para ipmitool, que não é o alvo principal no Windows. Se você precisar disso, abra uma issue.

Como isso é diferente de escrever um runbook ou um playbook do Ansible que chama as mesmas ferramentas? Um runbook ou um playbook do Ansible pode chamar os mesmos comandos subjacentes, mas não produz um registro assinado criptograficamente e à prova de adulteração do que realmente foi executado por conta própria; você precisaria construir essa camada de registro e assinatura você mesmo. O HaltProof entrega isso como comportamento padrão, e também oferece um único gate de simulação por padrão em todos os três backends, em vez de três playbooks separados com três convenções de segurança separadas.

Isso é um "interruptor de segurança de IA"? Não. O HaltProof é uma ferramenta de resposta a incidentes de infraestrutura e auditoria de conformidade para operadores de cluster. Ele não tem opinião sobre o comportamento de modelos de IA e não faz afirmações sobre segurança ou alinhamento de IA. Ferramentas que interceptam e auditam as chamadas de ferramentas individuais de um agente de IA operam em uma camada completamente diferente; o HaltProof orquestra o desligamento da computação subjacente em si, da mesma forma que faria para uma carga de trabalho não-IA.

O que acontece se a ferramenta subjacente de um nó não estiver instalada? O backend relevante relata essa etapa como failed com o erro real, por exemplo executable not found, e o registro de atestação ainda é gravado e assinado, então a falha em si se torna parte do histórico auditável.

Posso usar o HaltProof sem assinar atestações? Sim, --no-sign pula a assinatura, mas ainda grava o registro no log. Isso é destinado a testes locais, não a resposta a incidentes em produção, pois um registro não assinado não pode ser verificado como autêntico.

O log de atestação precisa de um servidor central? Não. É um arquivo NDJSON local, somente anexação, por padrão. --remote-collector opcionalmente envia via POST cada registro assinado para uma URL que você configura, para equipes que desejam uma cópia central, mas a verificação não depende de esse servidor estar acessível.

O que acontece se dois operadores executarem halt ao mesmo tempo contra o mesmo log de atestação? As anexações são bloqueadas por arquivo (fcntl.flock no POSIX) para que as gravações não se intercalem, mas os números de sequência são atribuídos lendo o log no momento em que cada comando começa. Aponte ambos os operadores para arquivos de log específicos do backend ou por incidente se você precisar de serialização estrita por operação.

Sob qual licença está o HaltProof e posso usá-lo comercialmente? MIT. Você pode usar, modificar e redistribuir, inclusive comercialmente, desde que o aviso de direitos autorais e o texto da licença permaneçam anexados. Veja LICENSE.

Contribuindo

Contribuições são bem-vindas. Leia CONTRIBUTING.md primeiro: ele cobre a configuração de um ambiente de desenvolvimento, a execução da suíte de testes (pytest -v --cov=haltproof --cov-report=term-missing) e as etapas para adicionar um novo backend implementando a interface ClusterBackend. Alterações que tocam assinatura/verificação de atestação ou o gate de simulação/--confirm recebem revisão extra, conforme CODEOWNERS. Veja SECURITY.md para relatar uma vulnerabilidade em particular, em vez de abrir uma issue pública.

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

Licença

MIT © Rudrendu Paul e Sourav Nandy