Skip to main content
OISP Sensor is built on a modular pipeline architecture that separates concerns into distinct stages: Capture, Decode, Enrich, Action, and Export.

​
High-Level Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        OISP Sensor                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────┐   ┌────────┐   ┌────────┐   ┌────────┐   ┌───────┐│
│  │ Capture  │──▶│ Decode │──▶│ Enrich │──▶│ Action │──▶│ Export││
│  │          │   │        │   │        │   │        │   │       ││
│  │ - eBPF   │   │ - HTTP │   │ - Host │   │ - Filt │   │ - JSONL│
│  │ - SSL    │   │ - AI   │   │ - Proc │   │ - Rdct │   │ - WS  ││
│  │ - Proc   │   │ - Sys  │   │ - DNS  │   │        │   │ - OTLP││
│  └──────────┘   └────────┘   └────────┘   └────────┘   └───────┘│
│                                                                  │
│  ┌──────────────────────────────────────────────────────────────┐│
│  │                      Web UI (React)                          ││
│  │    Timeline │ Process Tree │ Analytics │ Settings            ││
│  └──────────────────────────────────────────────────────────────┘│
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

​
Pipeline Stages

​
1. Capture

The capture stage collects raw events from the operating system. On Linux, this uses eBPF to intercept:
  • SSL/TLS traffic via uprobes on SSL_write and SSL_read
  • Process events via tracepoints on sched_process_exec and sched_process_exit
  • File operations via tracepoints on sys_enter_openat
  • Network connections via tracepoints on sys_enter_connect and sys_exit_connect
See eBPF Capture for technical details.

​
2. Decode

Raw captured bytes are transformed into structured events:
DecoderInputOutput
HttpDecoderSSL read/write bytesHTTP request/response, AI events
SystemDecoderProcess/file/network raw eventsOISP process, file, network events
The HTTP decoder is particularly sophisticated:
  • Parses HTTP/1.1 requests and responses
  • Correlates requests with responses using timing heuristics
  • Detects AI providers from URLs and headers
  • Handles streaming SSE responses (OpenAI, Anthropic)
  • Reassembles chunked transfer encoding

​
3. Enrich

Events are enhanced with additional context:
  • HostEnricher: Adds hostname, OS, architecture
  • ProcessTreeEnricher: Builds parent-child process relationships
  • Future: DNS resolution, geo-IP, container metadata

​
4. Action

Actions transform or filter events:
  • RedactionPlugin: Removes or masks sensitive data (API keys, PII)
  • Future: Sampling, alerting, custom transformations
See Redaction for configuration.

​
5. Export

Processed events are sent to one or more destinations:
ExporterUse Case
JSONLFile-based storage, offline analysis
WebSocketReal-time streaming to Web UI
OTLPOpenTelemetry-compatible backends (Grafana, Datadog, Honeycomb)
KafkaHigh-throughput event streaming
WebhookCustom HTTP endpoints
See Exports for configuration.

​
Crate Structure

The Rust codebase is organized into focused crates: 
crates/
├── oisp-core/           # Core types, pipeline, plugins
├── oisp-capture/        # Platform abstraction for capture
├── oisp-capture-ebpf/   # Linux eBPF capture implementation
├── oisp-decode/         # HTTP, AI, and system decoders
├── oisp-enrich/         # Enrichment plugins
├── oisp-redact/         # Redaction plugin
├── oisp-export/         # Export plugins (JSONL, WS, OTLP, etc.)
├── oisp-web/            # Web UI backend + embedded React app
├── oisp-tui/            # Terminal UI
└── oisp-sensor/         # Main binary

ebpf/
├── oisp-ebpf-capture-ebpf/    # eBPF programs (runs in kernel)
└── oisp-ebpf-capture-common/  # Shared types

​
Event Flow

All events follow the OISP v0.1 specification. See OISP Spec for the full schema.
  1. Raw capture: eBPF captures bytes from SSL/process/file/network
  2. Ring buffer: Events are sent to userspace via eBPF ring buffers
  3. Decoding: Raw bytes → structured RawCaptureEvent
  4. OISP conversion: RawCaptureEvent → OispEvent
  5. Enrichment: Host, process tree, and other metadata added
  6. Redaction: Sensitive data removed based on configuration
  7. Trace building: Events grouped into agent traces
  8. Export: Events sent to configured destinations
  9. Broadcast: Events sent to Web UI via WebSocket

​
Concurrency Model

OISP Sensor uses Tokio for async I/O:
  • eBPF polling task: Reads from ring buffers every 10ms
  • Pipeline task: Processes events through decode → enrich → action → export
  • WebSocket task: Broadcasts events to connected clients
  • HTTP server task: Serves Web UI and REST API
Events flow through bounded channels to prevent backpressure: 
eBPF Ring Buffer → mpsc channel → Pipeline → broadcast channel → WebSocket clients
                                          ↓
                                   Export plugins

​
Memory Management

  • Ring buffer size: 256 KB per event type (configurable)
  • Event buffer: Last 10,000 events kept in memory for Web UI
  • Trace builder: Automatic cleanup of stale traces (5 minute TTL)
  • Socket cache: LRU with 10,000 entry limit for SSL correlation

​
Next Steps