SentinAI

AI-powered eBPF/Kqueue threat detection agent — a Rust monorepo that streams system telemetry (process starts + file changes) over gRPC to an LLM-backed analysis engine, maps findings to MITRE ATT&CK, and optionally executes containment actions.

Architecture

flowchart LR
  subgraph host ["Host"]
    A["sentinai-agent"]
    FS["watch: /tmp, /etc"]
    PROC["process table"]
    EBPF["eBPF execve tracepoint"]
    A -->|"kqueue / inotify"| FS
    A -->|"poll (fallback)"| PROC
    A -.->|"aya (Linux, optional)"| EBPF
  end
  subgraph brain_svc ["Brain"]
    B["sentinai-brain"]
    L["Ollama / OpenAI"]
    B --> L
  end
  A -->|"gRPC stream"| B
  B -->|remediation| A
  D["sentinai-dashboard"] -->|tails| LOG["threats.jsonl"]
  B --> LOG

Loading

Crate	Role
sentinai-agent	Monitors process starts + file changes; executes remediation
sentinai-agent-bpf	eBPF tracepoint program (syscalls/sys_enter_execve), compiled to bpfel-unknown-none
sentinai-agent-common-bpf	Shared ExecEvent type (no_std, shared between BPF & userspace)
sentinai-brain	gRPC server; batches events; LLM/heuristic analysis
sentinai-dashboard	Terminal UI for live threats
sentinai-proto	Protobuf + tonic codegen

Platform monitoring

OS	File monitoring	Process monitoring
macOS	kqueue (EVFILT_VNODE)	Poll-based (sysinfo) — kqueue companion
Linux	inotify	eBPF via aya (default) with poll-based fallback
Fallback	FSEvents via notify crate	—

Process monitoring on Linux uses eBPF by default when BTF is available (/sys/kernel/btf/vmlinux). The eBPF program hooks syscalls/sys_enter_execve to capture process starts instantly via a PerfEventArray, then enriches with cmdline and PPid from /proc. Falls back to polling if eBPF is unavailable or --no-bpf is passed.

Prerequisites

# Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

# Protobuf compiler (macOS)
brew install protobuf

# Local LLM (optional)
brew install ollama
ollama pull llama3.2

# eBPF build dependencies (Linux only)
rustup toolchain install nightly --component rust-src
cargo install bpf-linker

Quick start

Terminal 1 — Brain

cd /Users/vamp/Desktop/Projects/SentiAI
cargo run -p sentinai-brain

Terminal 2 — Agent (default: poll-based, works everywhere)

cargo run -p sentinai-agent -- --brain http://127.0.0.1:50051

Terminal 2 — Agent with eBPF (Linux only, requires root + BTF kernel)

make run-agent-ebpf -- --brain http://127.0.0.1:50051

Terminal 3 — Dashboard (optional)

cargo run -p sentinai-dashboard

Terminal 4 — Simulate suspicious activity (brain and agent must already be running)

bash scripts/demo-suspicious.sh

The dashboard reads ~/.sentinai/threats.jsonl, which is only written when the agent streams events to the brain and analysis flags them as suspicious. Running the demo script alone is not enough.

Configuration

Variable / Flag	Default	Description
SENTINAI_BRAIN_ADDR	http://127.0.0.1:50051	Agent → Brain gRPC URL
SENTINAI_WATCH_PATHS	/tmp,/etc	Comma-separated watch paths
SENTINAI_AUTO_REMEDIATE	false	Auto-run kill/quarantine commands
--poll-ms	750	Process poll interval in ms (used when eBPF unavailable)
--no-bpf	false	Force-disable eBPF even if available
SENTINAI_USE_OLLAMA	true	Prefer Ollama over OpenAI
OLLAMA_HOST	http://127.0.0.1:11434	Ollama API
OLLAMA_MODEL	llama3.2	Model name
OPENAI_API_KEY	—	OpenAI-compatible API key
OPENAI_MODEL	gpt-4o-mini	Model when using OpenAI

OpenAI instead of Ollama

export SENTINAI_USE_OLLAMA=false
export OPENAI_API_KEY=sk-...
cargo run -p sentinai-brain

Auto-remediation (use with caution)

cargo run -p sentinai-agent -- --auto-remediate

Quarantined files land in ~/.sentinai/quarantine/.

Build

make build               # release binaries (default, poll-based)
make build-ebpf          # release binaries with eBPF support (Linux)
make run-brain
make run-agent
make run-agent-ebpf      # run with eBPF via sudo (Linux)
make run-dashboard

Binaries: target/release/sentinai-{agent,brain,dashboard}

When built with --features ebpf, the build script cross-compiles sentinai-agent-bpf to bpfel-unknown-none and embeds the bytecode into the agent binary. The ebpf feature is a no-op on macOS (the BPF module is cfg-gated to Linux only).