← 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_…' | sudo install -m 600 /dev/stdin /root/.imtbl_key
sudo IMTBL_API_KEY_FILE=/root/.imtbl_key \
     IMTBL_AGENT_VERSION=0.1.8 \
     sh get.sh

Repare que aqui as variáveis vêm depois do sudo, e por isso este comando não usa --preserve-env: sem ele, a configuração padrão do sudoers descartaria qualquer variável posta antes do sudo. É o inverso do comando de uma linha lá em cima, que mantém a chave antes do sudo justamente porque passa --preserve-env. As duas formas funcionam; o que não funciona é misturar as duas. Pôr o caminho depois do sudo é seguro: o que nunca 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.

De onde vêm os eventos de acesso

O coletor de acesso lê o journal do sistema, seguindo sshd, sshd-session, sshd-auth, login e systemd-logind. Login que não passa por nenhum deles não vira evento — é o caso de AWS Session Manager, console serial do provedor e docker exec. Numa máquina acessada só por esses caminhos, o agente instala, sobe, valida a chave e sela o agent.started, mas nunca registra um login. E isso é indistinguível de ninguém ter entrado.

Antes de concluir que o agente está cego, confirme que a fonte existe:

bash

journalctl -t sshd -t sshd-session -t systemd-logind --since "-1h"

Se vier vazio numa máquina em que você acabou de entrar, o agente está correto e a fonte é que não existe. Nesses hosts, quem enxerga o acesso é a captura de comandos, que lê a auditoria do kernel e registra também o processo que o Session Manager abre.

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_API_KEY_FILE	—	Alternativa à anterior: caminho de um arquivo com a chave. Não depende da política de ambiente do sudo.
IMTBL_CORE_URL	https://api.immutablelog.com	Base do core que recebe os eventos. Troque se o seu core é próprio ou de staging.
IMTBL_AGENT_VERSION	última estável	Fixa a versão instalada, para instalação reprodutível. Sem ela, o instalador usa a estável do canal.
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