logira: eBPF-Based Runtime Auditing for AI Agents and Automation

GitHub - melonattacker/logira: OS-level runtime auditing for unpredictable automation.

logira is an observe-only Linux CLI that records runtime exec, file, and net events via eBPF. It helps you see what actually happened during AI agent runs and other forms of automation, with per-run local storage for auditing, post-run review, search, and detection triage.

What is logira?

eBPF-based runtime collection of process execution, file activity, and network activity. cgroup v2 run-scoped tracking, so events can be attributed to a single audited run. Per-run local storage in JSONL and SQLite for timeline review and fast querying. Built-in default detection rules, with optional custom YAML rules. Observe-only by design: logira records and detects, but does not enforce or block.

Why logira?

Audit what an AI agent actually executed, changed, and connected to during a run (for example, codex --yolo or claude --dangerously-skip-permissions). Keep a trustworthy execution trail that does not depend on the agent's own textual narrative. Detect risky behavior patterns such as credential access, destructive commands, persistence changes, and suspicious network egress. Review and share forensic evidence after a run using structured event history and detection results. Add lightweight runtime auditing to local automation or CI tasks without changing workload behavior.

Default Detections

logira includes an opinionated, observe-only default ruleset aimed at auditing AI agent runs. You can also append your own per-run rules YAML with logira run --rules <file>.

Credential and secrets writes: ~/.ssh, ~/.aws, kube/gcloud/docker config, .netrc, .git-credentials, registry creds. Sensitive credential reads: SSH private keys, AWS credentials/config, kubeconfig, docker config, .netrc, .git-credentials. Persistence and config changes: writes under /etc, systemd units, cron, user autostart entries, shell startup files. Temp droppers: executable files created under /tmp, /dev/shm, /var/tmp. Suspicious exec patterns: curl|sh, wget|sh, tunneling/reverse shell tools and flags, base64 decode with shell hints. Agent safety destructive patterns: rm -rf, git clean -fdx, find -delete, mkfs, terraform destroy, and similar commands. Network egress: suspicious destination ports and cloud metadata endpoint access.

Installation

from script (recommended) Option1. Install via the convenitent script: curl -fsSL https://raw.githubusercontent.com/melonattacker/logira/main/install.sh | sudo bash Option2. Manual install from a release tarball: tar -xzf logira_vX.Y.Z_linux-<arch>.tar.gz cd logira_vX.Y.Z_linux-<arch> sudo ./install-local.sh

After reinstall / upgrade: First install: no extra step is usually needed (install.sh runs systemctl enable --now). Reinstall/upgrade over an existing install: restart logirad to ensure the new binary is running. sudo systemctl daemon-reload sudo systemctl restart logirad.service sudo systemctl status logirad.service --no-pager

from source Build: make build Start the root daemon (required for tracing): sudo ./logirad

How to run

Run an agent under audit as your normal user (events are auto-saved): ./logira run -- bash -lc 'echo hi > x.txt; curl -s https://example.com >/dev/null'

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

Run Claude Code CLI: ./logira run -- claude --dangerously-skip-permissions "Find and fix flaky tests."

List runs: ./logira runs

View and explain the last run: ./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

Query events: ./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

Commands

logira run -- <command...>: run a command under audit and auto-save a new run logira runs: list saved runs logira view [last|<run-id>]: run dashboard (use --raw for legacy text) logira query [last|<run-id>] [filters...]: search events with type-specific table output logira explain [last|<run-id>]: grouped detections by default (--show-related, --drill)

Rules

Built-in default ruleset is always active (internal/detect/rules/default_rules.yaml) optional per-run custom rules can be appended with logira run --rules <yaml-file> sample custom rules and trial commands: examples/rules/README.md

Where Is Data Stored?

Default home directory: ~/.logira (override: LOGIRA_HOME) Each run is stored at: ~/.logira/ runs// events.jsonl index.sqlite meta.json run-id format: YYYYMMDD-HHMMSS-

Docs

JSONL schema: docs/jsonl.md SQLite schema: docs/sqlite.md Custom rule syntax: docs/rules.md Development notes (BPF generation, tests): docs/development.md

Notes

Linux kernel 5.8+ is required. systemd is required (the root daemon logirad is expected to run under systemd for normal installs). cgroup v2 is required (check with logira status). Tracing requires the root daemon logirad to be running; logira run itself does not require sudo. If BPF object files are missing, set LOGIRA_EXEC_BPF_OBJ / LOGIRA_NET_BPF_OBJ / LOGIRA_FILE_BPF_OBJ.

Installed Paths (defaults)

The installer places: binaries: /usr/local/bin/logira, /usr/local/bin/logirad BPF objects: /usr/local/lib/logira/bpf/ systemd unit: /etc/systemd/system/logirad.service environment file: /etc/logira/logirad.env (sets LOGIRA_EXEC_BPF_OBJ, LOGIRA_NET_BPF_OBJ, LOGIRA_FILE_BPF_OBJ)

License

Apache License 2.0. See LICENSE for details. eBPF programs under collector/linux/ are dual-licensed: Apache-2.0 OR GPL-2.0-only. This ensures compatibility with the Linux kernel when loading eBPF programs that require GPL-only helpers.