logira

Auditoria em nível de SO para automação imprevisível.

logira é um CLI Linux de apenas observação que registra eventos de exec, file e net em tempo de execução via eBPF. Ele ajuda a ver o que realmente aconteceu durante execuções de agentes de IA e outras formas de automação, com armazenamento local por execução para auditoria, revisão pós-execução, busca e triagem de detecções.

O que é o logira?

• Coleta em tempo de execução baseada em eBPF de execução de processos, atividade de arquivos e atividade de rede.
• Rastreamento por escopo de execução via cgroup v2, permitindo atribuir eventos a uma única execução auditada.
• Armazenamento local por execução em JSONL e SQLite para revisão de linha do tempo e consultas rápidas.
• Regras de detecção padrão embutidas, com suporte a regras YAML personalizadas opcionais.
• Apenas observação por design: logira registra e detecta, mas não impõe ou bloqueia.

Por que logira?

• Auditar o que um agente de IA realmente executou, alterou e se conectou durante uma execução (por exemplo, codex --yolo ou claude --dangerously-skip-permissions).
• Manter um rastro de execução confiável que não depende da narrativa textual do próprio agente.
• Detectar padrões de comportamento arriscados, como acesso a credenciais, comandos destrutivos, alterações de persistência e saída suspeita de rede.
• Revisar e compartilhar evidências forenses após uma execução usando histórico estruturado de eventos e resultados de detecção.
• Adicionar auditoria leve em tempo de execução a tarefas de automação local ou CI sem alterar o comportamento da carga de trabalho.

Detecções Padrão

logira inclui um conjunto de regras padrão opinativas e apenas de observação voltadas para auditoria de execuções de agentes de IA. Você também pode anexar seu próprio arquivo YAML de regras por execução com logira run --rules <arquivo>.

• Escrita de credenciais e segredos: ~/.ssh, ~/.aws, configuração de kube/gcloud/docker, .netrc, .git-credentials, credenciais de registro.
• Leitura de credenciais sensíveis: chaves privadas SSH, credenciais AWS/config, kubeconfig, docker config, .netrc, .git-credentials.
• Alterações de persistência e configuração: escritas em /etc, unidades systemd, cron, entradas de inicialização automática do usuário, arquivos de inicialização do shell.
• Droppers temporários: arquivos executáveis criados em /tmp, /dev/shm, /var/tmp.
• Padrões suspeitos de execução: curl|sh, wget|sh, ferramentas e flags de tunelamento/reverse shell, decode base64 com indícios de shell.
• Padrões destrutivos de segurança de agentes: rm -rf, , , , e comandos similares.

Instalação

a partir do script (recomendado)

Opção 1: Instalar via script conveniente:

curl -fsSL https://raw.githubusercontent.com/melonattacker/logira/main/install.sh | sudo bash

Opção 2: Instalação manual a partir de um tarball de release:

tar -xzf logira_vX.Y.Z_linux-<arch>.tar.gz
cd logira_vX.Y.Z_linux-<arch>
sudo ./install-local.sh

Após reinstalação/atualização:

• Primeira instalação: normalmente nenhum passo extra é necessário (install.sh executa systemctl enable --now).
• Reinstalação/atualização sobre uma instalação existente: reinicie o logirad para garantir que o novo binário esteja em execução.

sudo systemctl daemon-reload
sudo systemctl restart logirad.service
sudo systemctl status logirad.service --no-pager

a partir do código fonte

Compilar:

make build

Iniciar o daemon root (necessário para rastreamento):

sudo ./logirad

# 1) Gerar objetos eBPF (necessário apenas se estiverem faltando)
make generate

# 2) Instalar a unidade systemd
sudo install -D -m 0644 packaging/systemd/logirad.service /etc/systemd/system/logirad.service

# 3) Instalar o binário do daemon (a unidade padrão usa /usr/local/bin/logirad)
sudo install -m 0755 ./logirad /usr/local/bin/logirad

# 4) (Recomendado) Apontar o systemd para os arquivos .o do eBPF via arquivo de ambiente.
# Isto evita depender do diretório de trabalho do serviço.
sudo mkdir -p /etc/logira
sudo tee /etc/logira/logirad.env >/dev/null <<'EOF'
LOGIRA_EXEC_BPF_OBJ=/caminho/absoluto/para/collector/linux/exec/trace_bpfel.o
LOGIRA_NET_BPF_OBJ=/caminho/absoluto/para/collector/linux/net/trace_bpfel.o
LOGIRA_FILE_BPF_OBJ=/caminho/absoluto/para/collector/linux/filetrace/trace_bpfel.o
EOF

# 5) Ativar + iniciar
sudo systemctl daemon-reload
sudo systemctl enable --now logirad

# Acompanhar logs
sudo journalctl -u logirad -f

# Verificar status
systemctl status logirad --no-pager

# Parar + desativar
sudo systemctl stop logirad
sudo systemctl disable --now logirad

Uso

Execute um agente sob auditoria como seu usuário normal (os eventos são salvos automaticamente):

./logira run -- bash -lc 'echo hi > x.txt; curl -s https://example.com >/dev/null'
./logira run --rules ./my-rules.yaml -- bash -lc 'cat ~/.aws/credentials >/dev/null'

Execute Codex CLI:

./logira run -- codex --yolo "Update the README to be clearer and add examples."

Execute Claude Code CLI:

./logira run -- claude --dangerously-skip-permissions "Find and fix flaky tests."

Listar execuções:

./logira runs

Visualizar e explicar a última execução:

./logira view last
./logira view last --ts both
./logira view last --color always
./logira explain last
./logira explain last --show-related
./logira explain last --drill 35

Consultar eventos:

./logira query last --type detection
./logira query last --type net --dest 140.82.121.4:443
./logira query last --related-to-detections --type net
./logira query last --contains curl

Comandos

• logira run -- <comando...>: executa um comando sob auditoria e salva automaticamente uma nova execução
• logira runs: lista execuções salvas
• logira view [last|<run-id>]: painel da execução (use --raw para texto legado)
• logira query [last|<run-id>] [filtros...]: pesquisa eventos com saída em tabela específica por tipo
• logira explain [last|<run-id>]: detecções agrupadas por padrão (--show-related, --drill)

Regras:

• o conjunto de regras padrão embutido está sempre ativo (internal/detect/rules/default_rules.yaml)
• regras personalizadas opcionais por execução podem ser anexadas com logira run --rules <arquivo-yaml>
• exemplos de regras personalizadas e comandos de teste: examples/rules/README.md
• a retenção de eventos de arquivo é orientada por regras de arquivo; --watch está obsoleto apenas para compatibilidade

Onde os Dados São Armazenados?

Diretório base padrão: ~/.logira (substituir: LOGIRA_HOME)

Cada execução é armazenada em:

~/.logira/
  runs/<run-id>/
    events.jsonl
    index.sqlite
    meta.json

Formato run-id: YYYYMMDD-HHMMSS-<ferramenta>

Documentação

• Esquema JSONL: docs/jsonl.md
• Esquema SQLite: docs/sqlite.md
• Sintaxe de regras personalizadas: docs/rules.md
• Notas de desenvolvimento (geração BPF, testes): docs/development.md

Notas

• Kernel Linux 5.8+ é necessário.
• systemd é necessário (o daemon root logirad deve rodar sob systemd para instalações normais).
• cgroup v2 é necessário (verificar com logira status).
• O rastreamento requer que o daemon root logirad esteja em execução; logira run em si não requer sudo.
• Se os arquivos de objeto BPF estiverem faltando, defina LOGIRA_EXEC_BPF_OBJ / LOGIRA_NET_BPF_OBJ / LOGIRA_FILE_BPF_OBJ.

Caminhos Instalados (padrão)

O instalador coloca:

• binários: /usr/local/bin/logira, /usr/local/bin/logirad
• objetos BPF: /usr/local/lib/logira/bpf/
• unidade systemd: /etc/systemd/system/logirad.service
• arquivo de ambiente: /etc/logira/logirad.env (define LOGIRA_EXEC_BPF_OBJ, LOGIRA_NET_BPF_OBJ, LOGIRA_FILE_BPF_OBJ)

Licença

Licença Apache 2.0. Veja LICENSE para detalhes.

Programas eBPF sob collector/linux/ são duplamente licenciados: Apache-2.0 OU GPL-2.0-only.

Isso garante compatibilidade com o kernel Linux ao carregar programas eBPF que exigem helpers apenas GPL.