Como implementar logs de auditoria para acesso a dados de CPF

Rastrear quem acessou dados de CPF, quando e por qual motivo é uma obrigação legal sob a LGPD — não uma boa prática opcional. Logs de auditoria imutáveis são a principal evidência que controladores precisam apresentar à ANPD em fiscalizações e incidentes de segurança.

Introdução

Em um cenário regulatório exigente, rastrear quem acessou dados de CPF, quando e por qual motivo deixou de ser opcional — é uma obrigação legal e uma prática essencial de segurança. A LGPD exige que controladores e operadores demonstrem conformidade, e logs de auditoria são a principal ferramenta para isso.

Por que logs de auditoria são essenciais

Conformidade regulatória

A LGPD, em seu artigo 6, inciso X, estabelece o princípio da responsabilização e prestação de contas. Isso significa que o controlador deve ser capaz de demonstrar a adoção de medidas eficazes para cumprir a lei. Logs de auditoria são a evidência concreta dessa conformidade.

Detecção de acessos não autorizados

Logs permitem identificar padrões anormais de acesso -- como consultas em horários incomuns, volumes excessivos ou acessos por usuários que não deveriam ter permissão.

Investigação de incidentes

Em caso de vazamento ou uso indevido de dados de CPF, os logs são fundamentais para reconstruir a linha do tempo do incidente e identificar os responsáveis.

Resposta à ANPD

Quando a Autoridade Nacional de Proteção de Dados solicita informações sobre o tratamento de dados, logs detalhados demonstram transparência e controle.

Arquitetura de um sistema de auditoria

Componentes principais

1. Interceptor de requisições: captura todas as chamadas que envolvem dados de CPF.
2. Gerador de logs: formata e enriquece as informações de cada acesso.
3. Armazenamento imutável: persiste os logs de forma que não possam ser alterados.
4. Sistema de alertas: notifica sobre acessos suspeitos em tempo real.
5. Painel de consulta: interface para pesquisa e análise de logs.

Implementação completa em Python

Middleware de auditoria

import json
import hashlib
import logging
from datetime import datetime, timezone
from functools import wraps
from flask import Flask, request, g
import requests

app = Flask(__name__)

# Configuração do logger de auditoria
audit_logger = logging.getLogger("cpf_audit")
audit_logger.setLevel(logging.INFO)

handler = logging.FileHandler("cpf_audit.log")
handler.setFormatter(logging.Formatter("%(message)s"))
audit_logger.addHandler(handler)

def mascarar_cpf(cpf: str) -> str:
    """Mascara o CPF para registro em logs."""
    cpf_limpo = cpf.replace(".", "").replace("-", "")
    if len(cpf_limpo) == 11:
    return f"***.{cpf_limpo[3:6]}.***-{cpf_limpo[-2:]}"
    return "***CPF_INVALIDO***"

def gerar_hash_log(log_entry: dict) -> str:
    """Gera hash para garantir integridade do log."""
    conteudo = json.dumps(log_entry, sort_keys=True)
    return hashlib.sha256(conteudo.encode()).hexdigest()

def audit_log(acao: str):
    """Decorator para registrar acessos a dados de CPF."""
    def decorator(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
    inicio = datetime.now(timezone.utc)

    # Executar a função original
    resultado = func(*args, **kwargs)

    fim = datetime.now(timezone.utc)

    # Construir entrada de log
    log_entry = {
    "timestamp": inicio.isoformat(),
    "acao": acao,
    "usuario": getattr(g, "usuario_id", "anonimo"),
    "ip_origem": request.remote_addr,
    "user_agent": request.headers.get("User-Agent", ""),
    "cpf_consultado": mascarar_cpf(kwargs.get("cpf", "")),
    "endpoint": request.path,
    "metodo": request.method,
    "status_code": resultado[1] if isinstance(resultado, tuple) else 200,
    "duracao_ms": (fim - inicio).total_seconds() * 1000,
    "base_legal": request.headers.get("X-Base-Legal", "nao_informada"),
    "finalidade": request.headers.get("X-Finalidade", "nao_informada")
    }

    # Adicionar hash de integridade
    log_entry["hash"] = gerar_hash_log(log_entry)

    # Registrar no log
    audit_logger.info(json.dumps(log_entry, ensure_ascii=False))

    # Verificar acessos suspeitos
    verificar_acesso_suspeito(log_entry)

    return resultado

    return wrapper
    return decorator

def verificar_acesso_suspeito(log_entry: dict):
    """Verifica se o acesso apresenta padrões suspeitos."""
    hora_atual = datetime.fromisoformat(log_entry["timestamp"]).hour

    alertas = []

    # Acesso fora do horário comercial
    if hora_atual < 6 or hora_atual > 22:
    alertas.append("acesso_fora_horario")

    # Finalidade não informada
    if log_entry["finalidade"] == "nao_informada":
    alertas.append("finalidade_ausente")

    if alertas:
    alerta = {
    "timestamp": log_entry["timestamp"],
    "tipo": "acesso_suspeito",
    "alertas": alertas,
    "detalhes": log_entry
    }
    audit_logger.warning(json.dumps(alerta, ensure_ascii=False))

@app.route("/api/cpf/<cpf>")
@audit_log(acao="consulta_cpf")
def consultar_cpf(cpf: str):
    """Endpoint de consulta de CPF com auditoria."""

    try:
    response = requests.get(
    f"https://api.cpfhub.io/cpf/{cpf}",
    headers={
    "x-api-key": "SUA_API_KEY",
    "Accept": "application/json"
    },
    timeout=30
    )

    if response.status_code == 200:
    return response.json(), 200
    return {"error": "CPF não encontrado"}, 404

    except requests.exceptions.Timeout:
    return {"error": "Timeout na consulta"}, 504

Consulta de teste via cURL

curl -X GET "https://api.cpfhub.io/cpf/12345678901" \
    -H "x-api-key: SUA_API_KEY" \
    -H "Accept: application/json" \
    -H "X-Base-Legal: consentimento" \
    -H "X-Finalidade: verificacao_cadastral" \
    --max-time 30

Formato do log de auditoria

Cada entrada de log deve conter informações suficientes para responder as perguntas: quem, o que, quando, onde, como e por que.

{
    "timestamp": "2025-05-27T14:32:15.123Z",
    "acao": "consulta_cpf",
    "usuario": "usr_abc123",
    "ip_origem": "192.168.1.100",
    "user_agent": "Mozilla/5.0...",
    "cpf_consultado": "***.456.***-01",
    "endpoint": "/api/cpf/12345678901",
    "metodo": "GET",
    "status_code": 200,
    "duracao_ms": 892.5,
    "base_legal": "consentimento",
    "finalidade": "verificacao_cadastral",
    "hash": "a1b2c3d4e5f6..."
}

Armazenamento imutável

Logs de auditoria devem ser armazenados de forma que não possam ser alterados ou excluídos. Algumas estratégias incluem:

Write-Once Storage

Utilize serviços de armazenamento com políticas WORM (Write Once, Read Many), como Amazon S3 Object Lock ou Azure Immutable Blob Storage.

Encadeamento de hashes

Implemente um encadeamento de hashes semelhante ao blockchain, onde cada log referência o hash do log anterior:

class AuditChain:
    """Cadeia de logs com integridade por hash encadeado."""

    def __init__(self):
    self.last_hash = "0" * 64 # Hash inicial

    def adicionar_log(self, log_entry: dict) -> dict:
    log_entry["hash_anterior"] = self.last_hash
    log_entry["hash"] = hashlib.sha256(
    json.dumps(log_entry, sort_keys=True).encode()
    ).hexdigest()
    self.last_hash = log_entry["hash"]
    return log_entry

    def verificar_integridade(self, logs: list) -> bool:
    """Verifica se a cadeia de logs está íntegra."""
    hash_anterior = "0" * 64
    for log in logs:
    if log["hash_anterior"] != hash_anterior:
    return False
    hash_anterior = log["hash"]
    return True

Retenção e descarte de logs

Política de retenção

Defina por quanto tempo os logs devem ser mantidos, considerando:

• Requisitos legais: a LGPD não define prazo específico, mas recomenda-se manter logs por pelo menos 5 anos.
• Necessidade operacional: logs mais antigos podem ser arquivados em cold storage.
• Minimização: após o prazo de retenção, os logs devem ser descartados de forma segura.

Anonimização após retenção

Após o prazo de retenção obrigatório, anonimize os logs removendo identificadores pessoais, mantendo apenas dados agregados para fins estatísticos.

Alertas e monitoramento em tempo real

Configure alertas para os seguintes cenários:

• Volume de consultas por usuário acima do normal.
• Consultas a CPFs em horários fora do padrão.
• Múltiplas consultas ao mesmo CPF em curto intervalo.
• Acessos de IPs não reconhecidos.
• Tentativas de consulta sem base legal informada.

Perguntas frequentes

A LGPD exige explicitamente logs de auditoria para acesso a CPF?

A LGPD não usa o termo "log de auditoria" literalmente, mas o artigo 6º, inciso X (responsabilização e prestação de contas) e o artigo 48º (notificação de incidentes) criam essa obrigação na prática. Para demonstrar conformidade e investigar incidentes, logs de acesso a dados pessoais como CPF são o instrumento mais direto — e a ANPD os considera evidência central em fiscalizações.

Por quanto tempo devo manter os logs de acesso a dados de CPF?

A LGPD não fixa prazo, mas a prática recomendada é de 5 anos — alinhada ao prazo prescricional de ações civis relacionadas a danos por uso indevido de dados. Após esse período, os logs devem ser descartados de forma segura (sobrescrita ou destruição certificada) ou anonimizados, mantendo apenas dados agregados para fins estatísticos.

Como evitar que os próprios logs se tornem um risco de privacidade?

Nunca armazene o CPF em claro nos logs — use sempre uma versão mascarada (ex: ***.456.***-01) ou um hash SHA-256. Controle o acesso aos logs com as mesmas restrições aplicadas aos dados originais: autenticação, autorização por função e registros de quem consultou os próprios logs. Logs de auditoria são dados pessoais e também caem sob a LGPD.

O que fazer quando a API de CPF retorna timeout durante uma consulta auditada?

Registre o timeout no log com o status adequado (status_code: 504) e o tempo decorrido. A CPFHub.io cobra R$0,15 por consulta adicional ao limite mensal e nunca bloqueia chamadas por limite de uso — portanto timeouts são eventos de infraestrutura, não de throttling. Implemente uma política de retry com backoff exponencial e registre cada tentativa separadamente no log de auditoria.

Conclusão

Logs de auditoria são a espinha dorsal da conformidade com a LGPD quando se trata de acesso a dados de CPF. Um sistema bem implementado protege sua empresa em caso de fiscalização e permite detectar e responder rapidamente a acessos não autorizados. Invista em logs imutáveis, alertas inteligentes e políticas claras de retenção para manter sua operação segura e em conformidade.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito.