logira

OS-Level-Runtime-Audit für unvorhersehbare Automatisierung.

logira ist eine beobachtende (observe-only) Linux-CLI, die mittels eBPF exec-, file- und net-Ereignisse zur Laufzeit aufzeichnet. Sie hilft dir zu sehen, was während KI-Agentenläufen und anderen Formen der Automatisierung tatsächlich passiert ist – mit pro-Lauf-lokaler Speicherung für Auditing, Nachbereitung, Suche und Erkennungs-Triage.

Was ist logira?

• eBPF-basierte Erfassung von Prozessausführung, Dateiaktivität und Netzwerkaktivität zur Laufzeit.
• cgroup‑v2-Laufbereichsverfolgung, sodass Ereignisse einem einzelnen auditierten Lauf zugeordnet werden können.
• Pro-Lauf-lokale Speicherung in JSONL und SQLite für Zeitachsenansicht und schnelle Abfragen.
• Integrierte Standard-Erkennungsregeln, optional erweiterbar durch benutzerdefinierte YAML-Regeln.
• Von Grund auf beobachtend: logira zeichnet auf und erkennt, erzwingt oder blockiert jedoch nichts.

Warum logira?

• Prüfen, was ein KI-Agent während eines Laufs tatsächlich ausgeführt, geändert und womit er verbunden hat (z. B. codex --yolo oder claude --dangerously-skip-permissions).
• Eine vertrauenswürdige Ausführungsspur führen, die nicht von der textuellen Erzählung des Agenten abhängt.
• Riskante Verhaltensmuster erkennen, wie Zugriff auf Anmeldedaten, zerstörerische Befehle, Persistenzänderungen und verdächtigen Netzwerkverkehr nach außen.
• Nach einem Lauf forensische Beweise mit strukturiertem Ereignisverlauf und Erkennungsergebnissen prüfen und teilen.
• Leichtgewichtiges Laufzeit-Auditing zu lokaler Automatisierung oder CI-Aufgaben hinzufügen, ohne das Workload-Verhalten zu ändern.

Standard-Erkennungen

logira enthält eine meinungsbasierte, beobachtende Standard-Regelsammlung für das Auditing von KI-Agentenläufen. Du kannst mit logira run --rules <datei> auch eigene Regeln pro Lauf als YAML anhängen.

• Schreibzugriffe auf Anmeldedaten und Secrets: ~/.ssh, ~/.aws, kube/gcloud/docker‑Konfiguration, .netrc, .git-credentials, Registry-Credentials.
• Lesezugriffe auf sensible Anmeldedaten: SSH-Private-Keys, AWS-Zugangsdaten/-Konfiguration, kubeconfig, docker‑Konfiguration, .netrc, .git-credentials.
• Persistenz- und Konfigurationsänderungen: Schreibzugriffe unter /etc, systemd‑Units, cron, Benutzer-Autostart-Einträge, Shell-Startdateien.
• Temporäre Dropper: Ausführbare Dateien, die unter /tmp, /dev/shm, /var/tmp erstellt wurden.
• Verdächtige Ausführungsmuster: curl|sh, wget|sh, Tunnel-/Reverse-Shell-Werkzeuge und -Flags, base64‑Dekodierung mit Shell-Hinweisen.
• Zerstörerische Muster für Agenten-Sicherheit: rm -rf, , , , und ähnliche Befehle.

Installation

aus dem Skript (empfohlen)

Option 1. Installation über das praktische Skript:

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

Option 2. Manuelle Installation aus einem Release-Tarball:

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

Nach Neuinstallation / Upgrade:

• Erste Installation: normalerweise kein zusätzlicher Schritt nötig (install.sh führt systemctl enable --now aus).
• Neuinstallation/Upgrade über eine bestehende Installation: logirad neu starten, um sicherzustellen, dass die neue Binärdatei läuft.

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

aus dem Quellcode

Build:

make build

Starte den Root-Daemon (erforderlich für das Tracing):

sudo ./logirad

# 1) eBPF-Objekte generieren (nur nötig, wenn sie fehlen)
make generate

# 2) systemd-Unit installieren
sudo install -D -m 0644 packaging/systemd/logirad.service /etc/systemd/system/logirad.service

# 3) Daemon-Binärdatei installieren (Unit‑Standard: /usr/local/bin/logirad)
sudo install -m 0755 ./logirad /usr/local/bin/logirad

# 4) (Empfohlen) systemd über eine Umgebungsdatei auf die eBPF .o‑Dateien hinweisen.
# So wird vermieden, dass der Dienst auf das Arbeitsverzeichnis angewiesen ist.
sudo mkdir -p /etc/logira
sudo tee /etc/logira/logirad.env >/dev/null <<'EOF'
LOGIRA_EXEC_BPF_OBJ=/absolute/path/to/collector/linux/exec/trace_bpfel.o
LOGIRA_NET_BPF_OBJ=/absolute/path/to/collector/linux/net/trace_bpfel.o
LOGIRA_FILE_BPF_OBJ=/absolute/path/to/collector/linux/filetrace/trace_bpfel.o
EOF

# 5) Aktivieren + starten
sudo systemctl daemon-reload
sudo systemctl enable --now logirad

# Logs verfolgen
sudo journalctl -u logirad -f

# Status prüfen
systemctl status logirad --no-pager

# Stoppen + deaktivieren
sudo systemctl stop logirad
sudo systemctl disable --now logirad

Verwendung

Einen Agenten unter Audit als normaler Benutzer ausführen (Ereignisse werden automatisch gespeichert):

./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'

Codex CLI ausführen:

./logira run -- codex --yolo "Aktualisiere die README, damit sie klarer wird und füge Beispiele hinzu."

Claude Code CLI ausführen:

./logira run -- claude --dangerously-skip-permissions "Finde und repariere flaky Tests."

Läufe auflisten:

./logira runs

Letzten Lauf anzeigen und erklären:

./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

Ereignisse abfragen:

./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

Befehle

• logira run -- <befehl...>: Einen Befehl unter Audit ausführen und automatisch einen neuen Lauf speichern
• logira runs: Gespeicherte Läufe auflisten
• logira view [last|<lauf-id>]: Lauf-Dashboard (verwende --raw für Legacy-Text)
• logira query [last|<lauf-id>] [filter...]: Ereignisse mit typ-spezifischer Tabellenausgabe durchsuchen
• logira explain [last|<lauf-id>]: Gruppierte Erkennungen standardmäßig (--show-related, --drill)

Regeln:

• Der integrierte Standard-Regelsatz ist immer aktiv (internal/detect/rules/default_rules.yaml)
• Optionale benutzerdefinierte Regeln pro Lauf können mit logira run --rules <yaml-datei> angehängt werden
• Beispiele für benutzerdefinierte Regeln und Testbefehle: examples/rules/README.md
• Die Aufbewahrung von Dateiereignissen wird durch Dateiregeln gesteuert; --watch ist veraltet und dient nur zur Kompatibilität

Wo werden Daten gespeichert?

Standard‑Home‑Verzeichnis: ~/.logira (überschreibbar mit LOGIRA_HOME)

Jeder Lauf wird gespeichert unter:

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

lauf-id‑Format: YYYYMMDD-HHMMSS-<tool>

Dokumentation

• JSONL‑Schema: docs/jsonl.md
• SQLite‑Schema: docs/sqlite.md
• Syntax für benutzerdefinierte Regeln: docs/rules.md
• Entwicklungsnotizen (BPF‑Generierung, Tests): docs/development.md

Hinweise

• Linux‑Kernel 5.8+ ist erforderlich.
• systemd wird benötigt (der Root‑Daemon logirad wird bei normalen Installationen unter systemd erwartet).
• cgroup v2 ist erforderlich (überprüfen mit logira status).
• Für das Tracing muss der Root‑Daemon logirad laufen; logira run selbst benötigt kein sudo.
• Fehlen BPF‑Objektdateien, setze LOGIRA_EXEC_BPF_OBJ / LOGIRA_NET_BPF_OBJ / LOGIRA_FILE_BPF_OBJ.

Installierte Pfade (Standard)

Das Installationsskript platziert:

• Binärdateien: /usr/local/bin/logira, /usr/local/bin/logirad
• BPF‑Objekte: /usr/local/lib/logira/bpf/
• systemd‑Unit: /etc/systemd/system/logirad.service
• Umgebungsdatei: /etc/logira/logirad.env (setzt LOGIRA_EXEC_BPF_OBJ, LOGIRA_NET_BPF_OBJ, LOGIRA_FILE_BPF_OBJ)

Lizenz

Apache License 2.0. Details siehe LICENSE.

eBPF‑Programme unter collector/linux/ sind dual lizenziert: Apache‑2.0 ODER GPL‑2.0‑only.

Dies gewährleistet Kompatibilität mit dem Linux‑Kernel beim Laden von eBPF‑Programmen, die GPL‑nur‑Helfer benötigen.