S.L.A Security Agent

Agente de IA para análise de capturas de rede utilizando Databricks, Unity Catalog, MCP e MLflow

Sobre o projeto

O S.L.A Security Agent é a camada de dados e inteligência artificial do projeto S.L.A — Security Log Analyzer.

Enquanto o S.L.A local é responsável pela captura e análise inicial do tráfego de rede, este projeto utiliza o Databricks para armazenar, processar e disponibilizar os relatórios para um agente de IA capaz de consultar informações reais das capturas através de ferramentas estruturadas.

O agente não recebe todo o relatório diretamente no prompt. Os dados são processados em tabelas Delta e expostos através de funções do Unity Catalog conectadas ao agente via MCP.

Isso permite consultas em linguagem natural sobre:

resumo das capturas;
endpoints;
portas;
protocolos;
DNS;
fluxos;
flags TCP;
direção do tráfego;
tamanho dos pacotes;
achados de segurança;
comparação entre capturas.

Arquitetura

S.L.A local
    │
    │ JSON
    ▼
Unity Catalog Volume
    │
    │ File Arrival Trigger
    ▼
Databricks Job
    │
    ▼
Bronze
    │
    ▼
Silver
    │
    ▼
Tabelas analíticas
    │
    ▼
Unity Catalog Functions
    │
    ▼
Managed MCP
    │
    ▼
OpenAI Agents SDK
    │
    ▼
S.L.A Security Agent
    │
    ▼
Databricks App

O MLflow é utilizado paralelamente para tracing e avaliação do comportamento esperado do agente.

Principais funcionalidades

Ingestão automática

Novos relatórios JSON são enviados para um Unity Catalog Volume.

/Volumes/workspace/security_agent/sla_raw/incoming/

Um File Arrival Trigger detecta novos arquivos e executa automaticamente o pipeline de atualização.

Arquitetura Bronze e Silver

Os dados passam por duas etapas principais.

Bronze

Mantém o relatório original e metadados do arquivo.

workspace.security_agent.bronze_sla_reports

Silver

Converte o JSON bruto para uma estrutura VARIANT, permitindo consultas sobre os campos internos.

workspace.security_agent.silver_sla_reports

A partir da Silver são construídas tabelas analíticas especializadas.

Unity Catalog Functions

O agente acessa os dados através de funções SQL registradas no Unity Catalog.

Função	Responsabilidade
`get_capture_summary`	Resumo geral da captura
`get_top_destination_ports`	Portas de destino e serviços
`get_top_endpoints`	Endpoints mais ativos
`get_top_dns_queries`	Consultas DNS
`get_protocol_summary`	Protocolos de rede e aplicação
`get_top_flows`	Principais fluxos entre endpoints
`get_tcp_flags_summary`	Distribuição das flags TCP
`get_security_findings`	Achados e nível de risco
`get_packet_length_summary`	Estatísticas de tamanho dos pacotes
`get_packet_length_distribution`	Distribuição por faixa de tamanho
`get_traffic_direction_summary`	Direção do tráfego
`get_latest_capture_pair`	Identificação das capturas mais recentes
`get_capture_comparison`	Comparação entre captura atual e anterior

MCP

As funções do Unity Catalog são disponibilizadas para o agente através do Managed MCP do Databricks.

/api/2.0/mcp/functions/workspace/security_agent

O MCP funciona como a camada de integração entre o agente e os dados estruturados.

Agente
   │
   ▼
MCP
   │
   ▼
Unity Catalog Functions
   │
   ▼
Delta Tables

Agente

O agente foi desenvolvido utilizando OpenAI Agents SDK integrado ao ambiente Databricks.

Modelo utilizado:

databricks-qwen3-next-80b-a3b-instruct

O agente seleciona as ferramentas com base na intenção da solicitação.

Pergunta
   │
   ▼
Identificação da intenção
   │
   ├── comparação
   │      ▼
   │  get_capture_comparison
   │
   ├── identificação das capturas
   │      ▼
   │  get_latest_capture_pair
   │
   └── consulta específica
          ▼
      ferramenta especializada

A seleção não depende de perguntas previamente definidas.

O agente procura utilizar a menor quantidade possível de ferramentas para responder.

Comparação entre capturas

O S.L.A consegue comparar automaticamente a captura mais recente com a imediatamente anterior.

A função:

get_capture_comparison

compara métricas como:

total de pacotes;
pacotes de entrada;
pacotes de saída;
tráfego interno ou não classificado;
tamanho mínimo;
tamanho máximo;
tamanho médio;
nível de risco.

Para métricas numéricas:

diferença = valor atual - valor anterior

A comparação é realizada no backend para evitar que o modelo precise calcular diferenças manualmente.

Segurança das respostas

O agente foi configurado para evitar conclusões que não sejam sustentadas pelos dados.

Ele diferencia:

Observação
Comportamento incomum
Possível indicador
Incidente confirmado

O agente não deve confirmar automaticamente atividade maliciosa apenas por observar:

grande volume de tráfego;
portas desconhecidas;
flags TCP específicas;
consultas DNS recorrentes;
tamanhos incomuns de pacotes;
diferenças entre entrada e saída.

Também não deve atribuir um endereço IP a uma organização ou serviço sem que essa informação tenha sido fornecida por uma ferramenta apropriada.

A ausência de um indicador também não é utilizada para descartar completamente possíveis ameaças.

Tratamento de timeout

Consultas MCP podem ocasionalmente exceder o tempo disponível.

Quando isso ocorre, o agente realiza uma única nova tentativa com os mesmos parâmetros.

Consulta
   │
   ├── sucesso
   │
   └── timeout
          │
          ▼
      segunda tentativa
          │
          ├── sucesso
          └── timeout
                 │
                 ▼
          informa a limitação

Resultados não são inventados quando uma consulta falha.

MLflow

O projeto utiliza MLflow para observabilidade e avaliação.

Tracing

As execuções do agente podem ser registradas através do MLflow Tracing.

Isso permite acompanhar:

chamadas do modelo;
execução do agente;
uso das ferramentas;
duração das operações;
comportamento durante as consultas.

Evaluation

O projeto possui um Job dedicado para avaliação:

sla-security-evaluation

Notebook:

tests/evaluate_agent.py.ipynb

A avaliação utiliza:

mlflow.genai.evaluate(...)

com:

Guidelines
ExpectationsGuidelines

Os testes verificam regras como:

respostas em português;
ausência de conclusões sem evidência;
tratamento correto de IPs;
cuidado com DNS;
cuidado com flags TCP;
cuidado com tamanho dos pacotes;
tratamento de comparação entre capturas;
reconhecimento de limitações dos dados.

A avaliação representa a aderência aos comportamentos esperados e não uma porcentagem direta de precisão do agente em produção.

Databricks App

O agente é executado como um Databricks App.

agent-sla-security

O App recebe acesso controlado aos recursos necessários:

endpoint do modelo;
experimento MLflow;
Unity Catalog Functions.

As funções possuem permissão:

EXECUTE

O agente não precisa acessar diretamente as tabelas ou os arquivos JSON para responder às consultas.

Automação de ingestão

O pipeline é executado pelo Job:

sla-security-ingestion

O Job monitora:

/Volumes/workspace/security_agent/sla_raw/incoming/

e executa:

jobs/refresh_sla_tables.py.ipynb

Esse notebook atualiza as estruturas utilizadas pelo agente sempre que uma nova captura é processada.

Estrutura do projeto

sla-security-agent/
│
├── app/
│   └── agent-openai-agents-sdk/
│       └── agent_server/
│           └── agent.py
│
├── docs/
│   └── databricks-architecture.md
│
├── jobs/
│   └── refresh_sla_tables.py.ipynb
│
├── sql/
│   ├── 00_setup.sql.dbquery.ipynb
│   ├── 01_bronze_sla_reports.sql.dbquery.ipynb
│   ├── ...
│   ├── 12_capture_comparison.sql.dbquery.ipynb
│   └── 13_capture_comparison_summary.sql.dbquery.ipynb
│
├── tests/
│   └── evaluate_agent.py.ipynb
│
├── databricks.yml
└── README.md

Tecnologias

Tecnologia	Uso
Python	Agente e automações
SQL	Transformação e consultas
Databricks	Plataforma de dados e IA
Delta Lake	Armazenamento estruturado
Unity Catalog	Governança, funções e volumes
Databricks Jobs	Automação do pipeline
File Arrival Trigger	Detecção de novas capturas
MCP	Integração entre agente e ferramentas
OpenAI Agents SDK	Orquestração do agente
Databricks Model Serving	Inferência do modelo
MLflow	Tracing e avaliação
Databricks Apps	Execução e interface do agente
Databricks Asset Bundles	Deploy e versionamento da infraestrutura

Pré-requisitos

Para reproduzir o projeto são necessários:

workspace Databricks;
Databricks CLI;
acesso ao Unity Catalog;
acesso a Databricks Apps;
endpoint de modelo compatível;
permissões para criação de Jobs, funções, tabelas e volumes.

O projeto foi desenvolvido utilizando recursos disponíveis no Databricks Free Edition, respeitando as limitações do ambiente.

Configuração

O principal arquivo de infraestrutura é:

databricks.yml

Ele contém:

App
Jobs
recursos
permissões
variáveis
targets

Os targets utilizados são:

dev
prod

O target padrão é:

dev

Validando o Bundle

Na raiz do projeto:

databricks bundle validate

Deploy

Para implantar os recursos:

databricks bundle deploy --target dev

Para atualizar e executar o App:

databricks bundle run agent_sla_security --target dev

Para executar a avaliação:

databricks bundle run sla_evaluation --target dev

A ingestão normalmente é iniciada automaticamente pelo File Arrival Trigger.

Adicionando uma nova captura

Após gerar e exportar um relatório JSON no S.L.A local, envie o arquivo para:

/Volumes/workspace/security_agent/sla_raw/incoming/

O fluxo seguinte ocorre automaticamente:

Novo JSON
   │
   ▼
File Arrival Trigger
   │
   ▼
sla-security-ingestion
   │
   ▼
Bronze
   │
   ▼
Silver
   │
   ▼
Tabelas analíticas
   │
   ▼
Unity Catalog Functions
   │
   ▼
Agente atualizado

Exemplos de consultas

O agente pode responder consultas em linguagem natural envolvendo os dados disponíveis.

Entre os tipos de consulta suportados estão:

resumo da captura

protocolos observados

portas com maior volume

endpoints mais ativos

consultas DNS

principais fluxos

flags TCP

direção do tráfego

estatísticas de tamanho dos pacotes

achados de segurança

diferenças entre capturas

evolução das métricas entre capturas

A escolha das ferramentas é feita pela intenção da solicitação e não por frases predefinidas.

Projeto S.L.A

Este repositório contém a integração Databricks e o agente de IA do S.L.A.

O projeto principal do Security Log Analyzer está disponível em:

https://github.com/MagyoDev/security-log-analyzer

FilesExpand file tree

README.md

Latest commit

History