Logs de Auditoria no MQTT: O Que Registrar e Por Quê

Logs de auditoria no MQTT significam registrar quem se conectou, quem não conseguiu se conectar, o que mudou na configuração e quais ações foram relevantes, para que você possa investigar incidentes e mostrar aos auditores que os controles funcionam. Este guia explica quais eventos registrar, quais campos cada entrada precisa ter, por quanto tempo guardá-los e como montar um pipeline de logs em torno de um broker MQTT gerenciado. O foco está em eventos de segurança e operacionais, não em armazenar cada payload de mensagem.

Logs de auditoria versus dados de mensagens

Ajuda separar três tipos de registros:

• Logs de auditoria: eventos relevantes para a segurança, como logins, logins com falha, mudanças de credenciais e ações administrativas. Pequenos, estruturados e mantidos por um período definido.
• Logs operacionais: quedas de conexão, erros, atingimento de cotas e sinais de desempenho usados para manter o sistema funcionando.
• Histórico de mensagens: a própria telemetria, normalmente armazenada em um banco de dados de séries temporais ou historiador para analytics.

Misturá-los causa problemas. Arquivos de payloads são grandes, podem conter dados pessoais ou confidenciais e soterram os eventos de segurança de que você realmente precisa durante uma investigação. Mantenha os logs de auditoria enxutos e focados.

O que registrar

A última linha merece atenção. A telemetria raramente precisa de trilha de auditoria, mas comandos que alteram o estado de equipamentos muitas vezes precisam. Registre o comando, a identidade que o enviou e a confirmação, e não apenas o fato de que uma mensagem passou.

Campos que toda entrada precisa ter

Seja qual for a origem, normalize as entradas em uma estrutura consistente:

{
  "ts": "2026-10-16T09:41:07.312Z",
  "event": "client.disconnected",
  "source": "connectmq-monitor",
  "client_id": "gw-plant1-01",
  "username": "gw-plant1-01",
  "ip": "203.0.113.24",
  "reason_code": "0x8E",
  "details": { "previous_state": "connected" }
}

Use timestamps em UTC com milissegundos, mantenha os nomes dos eventos estáveis e nunca registre senhas, tokens ou payloads completos que contenham dados pessoais.

De onde vêm os eventos

Em um ambiente auto-hospedado, os arquivos de log do próprio broker são a fonte principal. O Mosquitto, por exemplo, registra conexões, desconexões e falhas de autenticação quando as opções log_type correspondentes estão habilitadas, e você envia esses arquivos para um sistema central.

Com um broker MQTT gerenciado, você combina o que a plataforma expõe com o que seus próprios clientes e aplicações registram. É importante ser preciso sobre o que é cada coisa. Na ConnectMQ, as fontes visíveis são:

• Topics de estado de conexão: $SYS/broker/connection/{clientId}/state informa se um cliente está conectado, e você pode assiná-lo e registrá-lo.
• Dashboard do portal e visualização de dispositivos: visibilidade operacional dos clientes conectados e dos topics.
• Regras de alerta por limite e registro de alertas: um registro de quando os dados ultrapassaram os limites que você definiu.
• Reason codes do MQTT 5: retornados aos clientes em caso de recusa, incluindo o 0x97 para cota excedida, que seus clientes podem registrar.
• Proteções da plataforma: a proteção contra inundação e o bloqueio de IP após logins com falha repetidos rodam no lado do broker.

Esses são sinais operacionais, não uma trilha de auditoria para conformidade. Para uma trilha de auditoria completa, registre eventos do lado dos clientes e das aplicações em um armazenamento que você controla e documente os procedimentos administrativos nos seus próprios registros de mudança. Essa é uma divisão de responsabilidade compartilhada comum em brokers MQTT gerenciados; o guia vinculado na introdução mostra como as responsabilidades se dividem.

Monte um pipeline de auditoria simples

Um pequeno serviço que assina os topics de estado de conexão e grava linhas estruturadas em um arquivo ou em um coletor de logs oferece um histórico de conexões confiável. Este exemplo usa paho-mqtt 2.x e acompanha uma lista conhecida de client IDs:

import json
import logging
from datetime import datetime, timezone
import paho.mqtt.client as mqtt

WATCHED_CLIENTS = ["gw-plant1-01", "gw-plant1-02", "dashboard-01"]

logging.basicConfig(filename="mqtt-audit.jsonl", level=logging.INFO, format="%(message)s")

def audit(event, **fields):
    entry = {"ts": datetime.now(timezone.utc).isoformat(timespec="milliseconds"),
             "event": event, "source": "connectmq-monitor", **fields}
    logging.info(json.dumps(entry))

def on_connect(client, userdata, flags, reason_code, properties):
    audit("monitor.connected", reason_code=str(reason_code))
    for cid in WATCHED_CLIENTS:
        client.subscribe(f"$SYS/broker/connection/{cid}/state", qos=1)

def on_message(client, userdata, msg):
    cid = msg.topic.split("/")[3]
    audit("client.state", client_id=cid, state=msg.payload.decode("utf-8", "replace"))

def on_disconnect(client, userdata, flags, reason_code, properties):
    audit("monitor.disconnected", reason_code=str(reason_code))

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="YOUR_CLIENT_ID",
                     protocol=mqtt.MQTTv5)
client.username_pw_set("YOUR_USERNAME", "YOUR_PASSWORD")
client.tls_set()
client.on_connect = on_connect
client.on_message = on_message
client.on_disconnect = on_disconnect
client.reconnect_delay_set(min_delay=1, max_delay=60)
client.connect("YOUR_BROKER_HOST", 8883, keepalive=60)
client.loop_forever()

O arquivo de linhas JSON pode ser coletado por qualquer coletor de logs e encaminhado ao SIEM ou à plataforma de logs que sua organização já usa. Observe que o monitor também registra as próprias desconexões: lacunas na sua trilha de auditoria são, por si só, eventos importantes.

Registre também no lado do cliente

Dispositivos e aplicações veem eventos que o broker nunca informa a você, como suas próprias tentativas de conexão com falha e publicações recusadas. Faça cada cliente registrar:

1. Tentativas de conexão com o reason code do resultado.
2. Assinaturas recusadas (códigos SUBACK de 0x80 em diante).
3. Publicações recusadas, especialmente 0x97 quota exceeded e 0x87 not authorized.
4. Comandos recebidos, resultados da validação e ações executadas.
5. Eventos de rotação de credenciais.

Para gateways em plantas industriais, de uma usina a um frigorífico, envie esses logs a um coletor central em vez de mantê-los apenas no dispositivo. O guia de segurança OT com MQTT mostra como fazer isso sem abrir portas de entrada.

Retenção, integridade e privacidade

Logs de auditoria só são úteis se forem completos, confiáveis e legalmente armazenáveis.

• Retenção: defina um período com base nas suas necessidades regulatórias, contratuais e de investigação, e documente-o. Exclua os logs quando o período terminar.
• Integridade: grave em armazenamento somente de acréscimo (append-only) ou em um sistema que restrinja exclusões, e limite quem pode alterar os logs.
• Sincronização de horário: use NTP em todo host que gera logs; relógios desencontrados tornam as linhas do tempo inúteis.
• Privacidade: endereços IP e nomes de usuário podem ser dados pessoais, sujeitos à LGPD no Brasil. Colete o que você precisa, proteja o acesso e aplique sua política de privacidade.
• Acesso: registre o acesso aos próprios logs.

Transformando logs em alertas

Logs que ninguém lê não melhoram a segurança. Comece com alguns alertas de alto valor:

1. Muitas falhas de autenticação para um usuário ou a partir de um IP em uma janela curta.
2. Um dispositivo conhecido se conectando a partir de uma rede inesperada.
3. Um gateway desconectado por mais tempo do que sua queda máxima esperada.
4. Recusas repetidas por cota ou limite de taxa vindas de um cliente.
5. Qualquer comando em um topic de controle fora do horário de trabalho ou vindo de uma identidade inesperada.

Esses alertas se relacionam de perto com as ideias de verificação contínua de zero trust para mensageria IoT e com as expectativas de monitoramento de eventos de frameworks como a IEC 62443.

Checklist de logs de auditoria

1. Lista definida de eventos de segurança e responsáveis por cada fonte.
2. Estrutura JSON consistente com timestamps em UTC.
3. Estado de conexão monitorado para cada cliente crítico.
4. Registro no lado do cliente de reason codes, recusas e comandos.
5. Mudanças administrativas registradas no seu processo de gestão de mudanças.
6. Armazenamento central, com controle de acesso e período de retenção documentado.
7. Alertas para logins com falha, desconexões inesperadas e anomalias de taxa.
8. Revisão periódica de que o próprio pipeline está funcionando.

Comece a monitorar seu broker com a ConnectMQ

Crie um broker privado no plano Serverless (Free) em app.connectmq.com (sem cartão de crédito), conecte o monitor acima com as credenciais geradas e veja os eventos de conexão aparecerem. Se quiser experimentar antes sem credenciais, use o servidor MQTT público (gratuito) apenas com dados de teste, nunca com dados de produção. O artigo de melhores práticas de segurança MQTT aborda os controles que seus logs devem verificar.

Perguntas frequentes

Devo registrar todas as mensagens MQTT para auditoria?

Normalmente não. Registre eventos de segurança e administrativos, além dos comandos em topics de controle. Armazene a telemetria separadamente em um historiador ou banco de dados se precisar dela para analytics.

Qual é o evento MQTT mais importante a auditar?

As tentativas de autenticação com falha, porque revelam cedo tentativas de adivinhação, credenciais vazadas ou expiradas e dispositivos mal configurados.

Por quanto tempo os logs de auditoria MQTT devem ser mantidos?

Não existe uma resposta única. A retenção depende dos seus requisitos regulatórios, contratuais e de investigação, então defina um período, documente-o e aplique a exclusão quando ele terminar.

Consigo obter eventos de conexão de um broker MQTT gerenciado?

Na ConnectMQ, você pode assinar $SYS/broker/connection/{clientId}/state para obter o estado de conexão e combiná-lo com logs de reason codes no lado do cliente para montar seu próprio histórico de conexões.