{"id":29583778,"url":"https://github.com/eunomia-bpf/agentsight","last_synced_at":"2026-03-07T00:14:19.580Z","repository":{"id":303862592,"uuid":"1015665264","full_name":"eunomia-bpf/agentsight","owner":"eunomia-bpf","description":"Zero instrucment LLM and AI agent (e.g. claude code, gemini-cli) observability in eBPF","archived":false,"fork":false,"pushed_at":"2026-02-10T02:19:10.000Z","size":11453,"stargazers_count":197,"open_issues_count":14,"forks_count":27,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-10T07:21:02.969Z","etag":null,"topics":["agent","ebpf","llm","observability"],"latest_commit_sha":null,"homepage":"https://www.arxiv.org/abs/2508.02736","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eunomia-bpf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["yunwei37","Officeyutong"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2025-07-07T21:16:41.000Z","updated_at":"2026-02-10T07:01:30.000Z","dependencies_parsed_at":"2025-08-24T03:30:51.606Z","dependency_job_id":"2a9ecd6b-a9fa-41bb-a3ea-7d0dc6198d17","html_url":"https://github.com/eunomia-bpf/agentsight","commit_stats":null,"previous_names":["eunomia-bpf/agent-tracer","eunomia-bpf/agentsight"],"tags_count":106,"template":false,"template_full_name":"eunomia-bpf/libbpf-starter-template","purl":"pkg:github/eunomia-bpf/agentsight","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eunomia-bpf%2Fagentsight","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eunomia-bpf%2Fagentsight/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eunomia-bpf%2Fagentsight/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eunomia-bpf%2Fagentsight/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eunomia-bpf","download_url":"https://codeload.github.com/eunomia-bpf/agentsight/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eunomia-bpf%2Fagentsight/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30092979,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T20:42:30.420Z","status":"ssl_error","status_checked_at":"2026-03-04T20:42:30.057Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ebpf","llm","observability"],"created_at":"2025-07-19T23:38:51.897Z","updated_at":"2026-03-07T00:14:19.568Z","avatar_url":"https://github.com/eunomia-bpf.png","language":"C","readme":"# AgentSight: Zero-Instrumentation LLM Agent Observability with eBPF\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)\n[![Build Status](https://img.shields.io/badge/build-passing-brightgreen)](https://github.com/eunomia-bpf/agentsight)\n\nAgentSight is a observability tool designed specifically for monitoring LLM agent behavior through SSL/TLS traffic interception and process monitoring. Unlike traditional application-level instrumentation, AgentSight observes at the system boundary using eBPF technology, providing comprehensive insights into AI agent interactions with minimal performance overhead.\n\n**✨ Zero Instrumentation Required** - No code changes, no new dependencies, no SDKs. Works with any AI framework or application out of the box.\n\n## Quick Start\n\n```bash\nwget https://github.com/eunomia-bpf/agentsight/releases/latest/download/agentsight \u0026\u0026 chmod +x agentsight\n# Record Claude Code activity (Bun-based, requires --binary-path for statically-linked BoringSSL)\nsudo ./agentsight record -c claude --binary-path ~/.local/share/claude/versions/$(claude --version | head -1)\n# Record agent behavior from claude (old version)\nsudo ./agentsight record -c \"claude\"\n# Record agent behavior from gemini-cli (comm is \"node\")\nsudo ./agentsight record -c \"node\"\n# For Python AI tools (e.g. aider, open-interpreter)\nsudo ./agentsight record -c \"python\"\n# For Node.js apps with NVM (statically-linked OpenSSL)\nsudo ./agentsight record -c node --binary-path ~/.nvm/versions/node/v20.0.0/bin/node\n```\n\nVisit [http://127.0.0.1:7395](http://127.0.0.1:7395) to view the recorded data.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/eunomia-bpf/agentsight/raw/master/docs/demo-tree.png\" alt=\"AgentSight Demo - Process Tree Visualization\" width=\"800\"\u003e\n  \u003cp\u003e\u003cem\u003eReal-time process tree visualization showing AI agent interactions and file operations\u003c/em\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/eunomia-bpf/agentsight/raw/master/docs/demo-timeline.png\" alt=\"AgentSight Demo - Timeline Visualization\" width=\"800\"\u003e\n  \u003cp\u003e\u003cem\u003eReal-time timeline visualization showing AI agent interactions and system calls\u003c/em\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/eunomia-bpf/agentsight/raw/master/docs/demo-metrics.png\" alt=\"AgentSight Demo - Metrics Visualization\" width=\"800\"\u003e\n  \u003cp\u003e\u003cem\u003eReal-time metrics visualization showing AI agent memory and CPU usage\u003c/em\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n## 🚀 Why AgentSight?\n\n### Traditional Observability vs. System-Level Monitoring\n\n| **Challenge** | **Application-Level Tools** | **AgentSight Solution** |\n|---------------|----------------------------|------------------------|\n| **Framework Adoption** | ❌ New SDK/proxy for each framework | ✅ Drop-in daemon, no code changes |\n| **Closed-Source Tools** | ❌ Limited visibility into operations | ✅ Complete visibility into prompts \u0026 behaviors |\n| **Dynamic Agent Behavior** | ❌ Logs can be silenced or manipulated | ✅ Kernel-level hooks for reliable monitoring |\n| **Encrypted Traffic** | ❌ Only sees wrapper outputs | ✅ Captures real unencrypted requests/responses |\n| **System Interactions** | ❌ Misses subprocess executions | ✅ Tracks all process behaviors \u0026 file operations |\n| **Multi-Agent Systems** | ❌ Isolated per-process tracing | ✅ Global correlation and analysis |\n\nAgentSight captures critical interactions that application-level tools miss:\n\n- Subprocess executions that bypass instrumentation\n- Raw encrypted payloads before agent processing\n- File operations and system resource access  \n- Cross-agent communications and coordination\n\n## 🏗️ Architecture\n\n```ascii\n┌─────────────────────────────────────────────────┐\n│              AI Agent Runtime                   │\n│   ┌─────────────────────────────────────────┐   │\n│   │    Application-Level Observability      │   │\n│   │  (LangSmith, Helicone, Langfuse, etc.)  │   │\n│   │         🔴 Can be bypassed               │   │\n│   └─────────────────────────────────────────┘   │\n│                     ↕ (Can be bypassed)         │\n├─────────────────────────────────────────────────┤ ← System Boundary\n│  🟢 AgentSight eBPF Monitoring (Kernel-level)   │\n│  ┌─────────────────┐  ┌─────────────────────┐   │\n│  │   SSL Traffic   │  │    Process Events   │   │\n│  │   Monitoring    │  │    Monitoring       │   │\n│  └─────────────────┘  └─────────────────────┘   │\n└─────────────────────────────────────────────────┘\n                      ↓\n┌─────────────────────────────────────────────────┐\n│         Rust Streaming Analysis Framework       │\n│  ┌─────────────┐  ┌──────────────┐  ┌────────┐  │\n│  │   Runners   │  │  Analyzers   │  │ Output │  │\n│  │ (Collectors)│  │ (Processors) │  │        │  │\n│  └─────────────┘  └──────────────┘  └────────┘  │\n└─────────────────────────────────────────────────┘\n                      ↓\n┌─────────────────────────────────────────────────┐\n│           Frontend Visualization                │\n│     Timeline • Process Tree • Event Logs       │\n└─────────────────────────────────────────────────┘\n```\n\n### Core Components\n\n1. **eBPF Data Collection** (Kernel Space)\n   - **SSL Monitor**: Intercepts SSL/TLS read/write operations via uprobe hooks\n   - **Process Monitor**: Tracks process lifecycle and file operations via tracepoints\n   - **\u003c3% Performance Overhead**: Operates below application layer with minimal impact\n\n2. **Rust Streaming Framework** (User Space)\n   - **Runners**: Execute eBPF programs and stream JSON events (SSL, Process, Agent, Combined)\n   - **Analyzers**: Pluggable processors for HTTP parsing, chunk merging, filtering, logging\n   - **Event System**: Standardized event format with rich metadata and JSON payloads\n\n3. **Frontend Visualization** (React/TypeScript)\n   - Interactive timeline, process tree, and log views\n   - Real-time data streaming and analysis\n   - See \"Web Interface Access\" section for details\n\n### Data Flow Pipeline\n\n```\neBPF Programs → JSON Events → Runners → Analyzer Chain → Frontend/Storage/Output\n```\n\n## Usage\n\n### Prerequisites\n\n- **Linux kernel**: 4.1+ with eBPF support (5.0+ recommended)\n- **Root privileges**: Required for eBPF program loading\n- **Rust toolchain**: 1.88.0+ (for building collector)\n- **Node.js**: 18+ (for frontend development)\n- **Build tools**: clang, llvm, libelf-dev\n\n### Installation\n\n#### Option 1: Using Docker (Recommended)\n\nAgentSight runs in Docker with `--privileged` for eBPF, `--pid=host` to access host processes, `-v /sys:/sys:ro` for process monitoring, and `-v /usr:/usr:ro -v /lib:/lib:ro` for SSL library access (required to attach uprobes to shared libraries like `libssl.so`). Example:\n\n```bash\n# Monitor Python AI tools\ndocker run --privileged --pid=host --network=host \\\n  -v /sys:/sys:ro -v /usr:/usr:ro -v /lib:/lib:ro \\\n  -v $(pwd)/logs:/logs \\\n  ghcr.io/eunomia-bpf/agentsight:latest \\\n  record --comm python --log-file /logs/record.log\n\n# Monitor Claude Code (mount home dir for binary access)\ndocker run --privileged --pid=host --network=host \\\n  -v /sys:/sys:ro -v /usr:/usr:ro -v /lib:/lib:ro \\\n  -v $HOME/.local/share/claude:/claude:ro \\\n  -v $(pwd)/logs:/logs \\\n  ghcr.io/eunomia-bpf/agentsight:latest \\\n  record --comm claude --binary-path /claude/versions/2.1.39 --log-file /logs/record.log\n```\n\n#### Option 2: Build from Source\n\n```bash\n# Clone repository with submodules\ngit clone https://github.com/eunomia-bpf/agentsight.git --recursive\ncd agentsight\n\n# Install system dependencies (Ubuntu/Debian)\nmake install\n\n# Build all components (frontend, eBPF, and Rust)\nmake build\n\n# Or build individually:\n# make build-frontend  # Build frontend assets\n# make build-bpf       # Build eBPF programs\n# make build-rust      # Build Rust collector\n\n```\n\n### Usage Examples\n\n#### Monitoring Claude Code\n\nClaude Code is a Bun-based application with BoringSSL statically linked and\nsymbols stripped. AgentSight auto-detects BoringSSL functions via byte-pattern\nmatching when `--binary-path` is provided:\n\n```bash\n# Find the Claude binary version\nCLAUDE_BIN=~/.local/share/claude/versions/$(claude --version | head -1)\n\n# Record all Claude activity with web UI\nsudo ./agentsight record -c claude --binary-path \"$CLAUDE_BIN\"\n# Open http://127.0.0.1:7395 to view timeline\n\n# Advanced: full trace with custom filters\nsudo ./agentsight trace --ssl true --process true --comm claude \\\n  --binary-path \"$CLAUDE_BIN\" --server true --server-port 8080\n```\n\nThis captures:\n- **Conversation API**: `POST /v1/messages` requests with full prompt/response SSE streaming\n- **Telemetry**: heartbeat, event logging, Datadog logs\n- **Process activity**: file operations, subprocess executions\n\n\u003e **Note**: All SSL traffic in Claude flows through an internal \"HTTP Client\"\n\u003e thread, not the main \"claude\" thread. When `--binary-path` is specified,\n\u003e the `--comm` filter is automatically skipped for SSL monitoring (but still\n\u003e applied for process monitoring) to ensure traffic is captured correctly.\n\n#### Monitoring Python AI Tools\n\n```bash\n# Monitor aider, open-interpreter, or any Python-based AI tool\nsudo ./agentsight record -c \"python\"\n\n# Custom port and log file\nsudo ./agentsight record -c \"python\" --server-port 8080 --log-file /tmp/agent.log\n```\n\n#### Monitoring Node.js AI Tools (Gemini CLI, etc.)\n\nFor Node.js applications installed via NVM that statically link OpenSSL, use\n`--binary-path` to point to the actual Node.js binary:\n\n```bash\n# Monitor Gemini CLI or other Node.js AI tools\nsudo ./agentsight record -c node --binary-path ~/.nvm/versions/node/v20.0.0/bin/node\n\n# Or with system Node.js (uses dynamic libssl, no --binary-path needed)\nsudo ./agentsight record -c node\n```\n\n#### Advanced Monitoring\n\n```bash\n# Combined SSL and process monitoring with web interface\nsudo ./agentsight trace --ssl true --process true --server true\n\n# Custom port and log file\nsudo ./agentsight record -c \"python\" --server-port 8080 --log-file /tmp/agent.log\n```\n\n#### Browser Plaintext Capture\n\nFor browser-specific plaintext capture, use the standalone `browsertrace` BPF\ntool instead of `sslsniff`:\n\n```bash\n# Chrome / Chromium\nsudo ./bpf/browsertrace --binary-path /opt/google/chrome/chrome\n\n# Firefox on Ubuntu Snap\nsudo ./bpf/browsertrace --binary-path /snap/firefox/current/usr/lib/firefox/firefox\n```\n\n\u003e **Note**: On Ubuntu, `/usr/bin/firefox` is often a wrapper script rather than\n\u003e the real browser ELF. Point `browsertrace` at the actual Firefox binary.\n\n#### Local MCP over stdio\n\nFor local MCP servers that communicate over `stdio` instead of HTTP/TLS, use\nthe standalone `stdiocap` BPF tool:\n\n```bash\n# Capture stdin/stdout/stderr payloads for a local MCP server process\nsudo ./bpf/stdiocap -p \u003cmcp_server_pid\u003e\n```\n\nAgentSight also includes a minimal MCP fixture for local testing under\n[`docs/mcp-test/README.md`](docs/mcp-test/README.md). It provides both `stdio`\nand HTTP test modes so you can generate predictable MCP traffic before wiring\nit into the Rust collector.\n\n#### Direct eBPF Program Usage\n\n```bash\n# Run sslsniff directly on Claude binary\nsudo ./bpf/sslsniff --binary-path ~/.local/share/claude/versions/2.1.39\n\n# Run sslsniff on NVM Node.js\nsudo ./bpf/sslsniff --binary-path ~/.nvm/versions/node/v20.0.0/bin/node --verbose\n\n# Run browsertrace directly on Chrome\nsudo ./bpf/browsertrace --binary-path /opt/google/chrome/chrome\n\n# Run stdiocap directly on a local MCP server PID\nsudo ./bpf/stdiocap -p 12345\n\n# Run process tracer\nsudo ./bpf/process -c python\n```\n\n#### Web Interface Access\n\nAll monitoring commands with `--server` flag provide web visualization at:\n- **Timeline View**: http://127.0.0.1:7395/timeline\n- **Process Tree**: http://127.0.0.1:7395/tree\n- **Raw Logs**: http://127.0.0.1:7395/logs\n\n\n## ❓ Frequently Asked Questions\n\n### General\n\n**Q: How does AgentSight differ from traditional APM tools?**\nA: AgentSight operates at the kernel level using eBPF, providing system-level monitoring that is independent of application code. Traditional APM requires instrumentation that can be modified or disabled.\n\n**Q: What's the performance impact?**\nA: Less than 3% CPU overhead due to optimized eBPF kernel-space data collection.\n\n**Q: Can agents detect they're being monitored?**  \nA: Detection is extremely difficult since monitoring occurs at the kernel level without code modification.\n\n### Technical\n\n**Q: Which Linux distributions are supported?**\nA: Any distribution with kernel 4.1+ (5.0+ recommended). Tested on Ubuntu 20.04+, CentOS 8+, RHEL 8+.\n\n**Q: Can I monitor multiple agents simultaneously?**  \nA: Yes, use combined monitoring modes for concurrent multi-agent observation with correlation.\n\n**Q: How do I filter sensitive data?**  \nA: Built-in analyzers can remove authentication headers and filter specific content patterns.\n\n**Q: Why doesn't AgentSight capture traffic from Claude Code or NVM Node.js?**\nA: These applications statically link their SSL library (BoringSSL for Claude/Bun, OpenSSL for NVM Node.js) instead of using system `libssl.so`. Use `--binary-path` to point to the actual binary so AgentSight can auto-detect SSL functions via byte-pattern matching. See the \"Monitoring Claude Code\" and \"Monitoring Node.js AI Tools\" sections for examples.\n\n**Q: Why does `--comm claude` not capture SSL traffic?**\nA: Claude Code's SSL traffic runs on an internal \"HTTP Client\" thread, not the main \"claude\" thread. The `--comm` filter in sslsniff matches thread name (from `bpf_get_current_comm()`), not process name. When using `--binary-path`, the collector automatically skips the `--comm` filter for SSL monitoring.\n\n### Troubleshooting\n\n**Q: \"Permission denied\" errors**  \nA: Ensure you're running with `sudo` or have `CAP_BPF` and `CAP_SYS_ADMIN` capabilities.\n\n**Q: \"Failed to load eBPF program\" errors**\nA: Verify kernel version meets requirements (see Prerequisites). Update vmlinux.h for your architecture if needed.\n\n\n## 🤝 Contributing\n\nWe welcome contributions! After cloning and building (see Installation above), you can:\n\n```bash\n# Run tests\nmake test\n\n# Frontend development server\ncd frontend \u0026\u0026 npm run dev\n\n# Build debug versions with AddressSanitizer\nmake -C bpf debug\n```\n\n### Key Resources\n\n- [CLAUDE.md](CLAUDE.md) - Project guidelines and architecture\n- [collector/DESIGN.md](collector/DESIGN.md) - Framework design details\n- [docs/why.md](docs/why.md) - Problem analysis and motivation\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n**💡 The Future of AI Observability**: As AI agents become more autonomous and capable of self-modification, traditional observability approaches become insufficient. AgentSight provides independent, system-level monitoring for safe AI deployment at scale.\n","funding_links":["https://github.com/sponsors/yunwei37","https://github.com/sponsors/Officeyutong"],"categories":["Provenance, Instrumentation \u0026 Observability"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feunomia-bpf%2Fagentsight","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feunomia-bpf%2Fagentsight","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feunomia-bpf%2Fagentsight/lists"}