← VoltarLinux

Agente de host

O agente roda no seu servidor e registra cada acesso e cada comando na chain imutável, sem exigir nenhuma alteração no seu código. Ele complementa os SDKs: enquanto eles registram o que a sua aplicação faz, o agente registra o que fazem na máquina onde ela roda.

Requisitos

• Linux com systemd (Debian/Ubuntu, RHEL/Rocky/Alma, ou qualquer distro com systemd via tarball).
• Arquiteturas x86_64 e aarch64. O binário é estático — roda também em distros antigas.
• Uma API key do seu tenant com o scope events:write.
• Saída HTTPS para a API da ImmutableLog. Nenhuma porta de entrada é aberta.

Windows e macOS ainda não são suportados.

Instalação

O instalador detecta a distribuição e a arquitetura, baixa o pacote certo, verifica o SHA-256 e só então instala, configura a chave e sobe o serviço. Se o checksum não conferir, nada é instalado.

install.sh

curl -sSL https://get.immutablelog.com/agent \
  | IMTBL_API_KEY=iml_live_… sudo --preserve-env=IMTBL_API_KEY sh

Prefere inspecionar antes de executar?

O instalador é um arquivo único, de propósito. Baixe, leia e rode depois — ou use --dry-run, que baixa e verifica o pacote sem instalar nada.

bash

curl -sSL https://get.immutablelog.com/agent -o get.sh
less get.sh
IMTBL_API_KEY=iml_live_… sudo --preserve-env=IMTBL_API_KEY sh get.sh --dry-run

Instalação automatizada (Ansible, CI, imagem)

Passe a chave por arquivo, o que não depende da política de ambiente do sudo, e fixe a versão para instalações reprodutíveis.

bash

printf %s 'iml_live_…' > /root/.imtbl_key && chmod 600 /root/.imtbl_key
sudo IMTBL_API_KEY_FILE=/root/.imtbl_key \
     IMTBL_AGENT_VERSION=0.1.8 \
     sh get.sh

Repare que as variáveis vêm depois do sudo. Antes dele, a configuração padrão do sudoers as descarta e a instalação para por falta de chave. Aqui isso é seguro: o que não pode aparecer na linha de comando é a chave, não o caminho do arquivo onde ela está.

A regra da API key

A sua chave nunca deve aparecer na linha de comando. O sudo grava os argumentos que recebe no log de autenticação e no journal do sistema — e o journal é justamente o que este agente lê e sela na chain. Uma chave passada como argumento seria capturada pelo próprio agente e ficaria registrada de forma imutável, sem como apagar.

CorretoIMTBL_API_KEY=… sudo --preserve-env=IMTBL_API_KEY shA chave viaja no ambiente, não nos argumentos.

Nuncasudo IMTBL_API_KEY=… shAqui a chave vira argumento do sudo — e vai para o journal.

O instalador detecta essa forma de invocação, recusa instalar e orienta a rotacionar a chave. Note também que é --preserve-env=IMTBL_API_KEY, e não -E: com a configuração padrão do sudo na maioria das distribuições, o -E é ignorado e a variável chega vazia.

Depois de instalada, a chave fica em /etc/imtbl_agent/imtbl_agent.env, com dono root e permissão 0600 — nem o usuário que roda o serviço consegue lê-la.

O que é capturado

Cada evento abaixo é enviado à API, selado na chain e segue para o SIEM já normalizado.

alert.user.login

alert.user.logout

Encerramento de sessão — fecha a janela de quanto tempo o acesso durou.

alert.auth.failed_login

Tentativa recusada. É o evento que alimenta a detecção de brute force no SIEM.

alert.process.exec

Comando executado, com usuário, PID e linha de comando já redigida. Opt-in.

alert.agent.gap

Janela em que o agente não estava observando — inclusive por queda ou kill.

alert.agent.heartbeat

Sinal de vida periódico com os contadores do agente, selado na chain.

Para que tentativas com senha ou chave inválida apareçam com detalhe, o sshd precisa estar com LogLevel VERBOSE.

Captura de comandos (opt-in)

A captura de comandos vem desligada por padrão, e isso é deliberado: a linha de comando vai selada e imutável para a chain. A redação de segredos roda antes do envio, mas ela reconhece padrões — um segredo em formato desconhecido pode passar, e não há como apagar depois. Ligue conscientemente.

bash

# 1. regra de auditoria do kernel
sudo cp /usr/share/imtbl_agent/imtbl-agent-execve.rules \
        /etc/audit/rules.d/99-imtbl-agent.rules
sudo augenrules --load

# 2. ligar no agente
sudo sed -i 's/^IMTBL_CAPTURE_COMMANDS=.*/IMTBL_CAPTURE_COMMANDS=1/' \
        /etc/imtbl_agent/imtbl_agent.env
sudo systemctl restart imtbl-agent

Um teto configurável de comandos por minuto protege a sua cota em picos de atividade. Ele vale só para comandos: eventos de acesso nunca são limitados, porque é justamente durante um brute force que não se pode amostrar. Tudo que for descartado pelo teto é contado e reportado.

Configuração

Tudo fica em /etc/imtbl_agent/imtbl_agent.env. Depois de editar, reinicie o serviço.

Variável	Padrão	Para que serve
IMTBL_API_KEY	—	A chave do tenant. Obrigatória.
IMTBL_CAPTURE_COMMANDS	0	Liga a captura de comandos.
IMTBL_MAX_EVENTS_PER_MIN	600	Teto de comandos por minuto. 0 remove o teto.
IMTBL_REDACT_MODE	full	Política de redação. Não há como desligar.
IMTBL_HEARTBEAT_SECS	3600	Intervalo do sinal de vida selado. 0 desliga.
IMTBL_QUEUE_CAPACITY	50000	Teto de eventos na fila durável.
IMTBL_HOST_LABEL	hostname	Como o host aparece nos eventos.

Operação

bash

systemctl status imtbl-agent
journalctl -u imtbl-agent -f

# reprocessa eventos que ficaram retidos após erro do servidor
sudo systemctl kill -s USR1 --kill-whom=main imtbl-agent

O --kill-whom=main é obrigatório: sem ele o sinal atinge todos os processos do serviço, incluindo o auxiliar que lê o journal.

Se a chave for rotacionada, atualize o arquivo de configuração e reinicie. Enquanto a chave for recusada, o agente continua capturando e guardando na fila — nada é perdido, e o motivo fica no journal.

Garantias

O agente não apaga o próprio rastro

Cada evento é selado na chain no momento em que acontece. Mesmo quem tem root no host não reescreve o que já foi registrado — só é possível parar de gerar eventos novos, e isso também fica registrado.

Parar o agente deixa marca

O agente grava um sinal de vida em disco a cada minuto. Se ele for parado, morto ou o servidor cair, a janela sem observação vira um evento de gap na próxima subida — com início, fim e se a parada foi limpa.

Segredos são redigidos antes do envio

A redação roda no host, antes de qualquer envio e antes até do log local. Como o registro é imutável, não existe corrigir depois — por isso ela é obrigatória e não há como desligá-la, só configurá-la para redigir mais.

Queda de rede não perde evento

Os eventos vão para uma fila durável em disco e são entregues quando a rede voltar. A fila sobrevive a reinício do processo e do servidor, e cada evento carrega uma chave de idempotência — reenvio não duplica.

Não roda como root e não abre porta

O serviço roda com um usuário próprio, sem shell, com uma única capability de leitura de auditoria. Não expõe nenhuma porta de rede: os contadores vão para o log e para o próprio heartbeat selado.

Chave inválida não sobe o serviço

A chave é validada contra a API no boot. Se for recusada, o agente não sobe e o motivo aparece no journal — um serviço rodando sem conseguir registrar nada é pior que um serviço que falha na cara do operador.

Desinstalar

bash

sudo systemctl disable --now imtbl-agent
sudo apt purge imtbl-agent        # ou: sudo dnf remove imtbl-agent

O diretório de dados é preservado de propósito, mesmo no purge: a fila pode conter eventos capturados que ainda não foram selados na chain, e apagá-la em silêncio destruiria prova. Remova à mão quando tiver certeza.

Documentação da API