Skip to content
BranchesTags

Repository files navigation

Siren

A Linux-first adaptive defense stack that combines eBPF fast-path enforcement, protocol-faithful deception, and shared threat intelligence into one integrated system.

Rust Linux eBPF Mesh

Why This Exists

Most defenders can already collect alerts. The problem is what happens next.

  • Firewalls act quickly but know very little.
  • IDS and TIP stacks know more but sit outside the packet path.
  • Honeypots collect attacker behavior but usually live off to the side.
  • Shared intelligence often requires centralization, manual glue, or both.

Siren exists to collapse those seams.

Instead of running separate tools that barely talk to each other, Siren keeps the loop tight:

  1. inspect traffic in the kernel
  2. classify behavior in userspace
  3. redirect suspicious flows into believable deception services
  4. turn what was learned into feed-ready intelligence
  5. share that intelligence across a mesh and back into enforcement

The goal is not just detection. The goal is a defense stack where learning, deception, enforcement, and sharing reinforce each other.

What It Does

You run Siren on a Linux host. The system watches traffic at the interface, classifies it, optionally redirects suspicious actors into the tarpit, and exposes verified intelligence through a local API and mesh node.

Inbound traffic hits interface
        │
        ▼
┌─────────────────────┐     XDP / TC, ring buffers, shared maps
│ blackwall-ebpf      │────▶ Fast-path filtering, DPI tail calls, native redirect
└─────────┬───────────┘
          ▼
┌─────────────────────┐     JA4 assembly, behavior tracking, rule engine,
│ blackwall           │────▶ deterministic + optional Ollama-backed classification
└──────┬───────┬──────┘
       │       │
       │       └──────────────────────────────────────┐
       ▼                                              ▼
┌─────────────────────┐                      ┌─────────────────────┐
│ tarpit              │                      │ hivemind            │
│ HTTP / MySQL / DNS  │                      │ libp2p mesh,        │
│ SSH-style shell     │                      │ consensus, PoW, FL  │
└─────────┬───────────┘                      └─────────┬───────────┘
          │                                            ▼
          └──────────────────────────────┬─────────────────────────┐
                                         ▼                         ▼
                              ┌─────────────────────┐    ┌─────────────────────┐
                              │ hivemind-api        │    │ hivemind-dashboard  │
                              │ JSON, STIX/TAXII,   │    │ ANSI TUI + NDJSON   │
                              │ Splunk, QRadar, CEF │    │ operator visibility │
                              └─────────────────────┘    └─────────────────────┘

Core loop

Step What happens
Observe eBPF programs inspect packets at ingress and optional egress
Interpret Userspace assembles JA4, tracks behavior, and classifies events
Engage Suspicious flows can be redirected to protocol-faithful deception services
Learn Captured behavior, credentials, and signals become structured IoCs
Share The mesh and API distribute that intelligence in formats defenders already use

Key Features

Security capabilities

Feature Description
Kernel Fast Path XDP ingress and optional TC egress with native rule enforcement before normal userspace processing
Native Tarpit Redirect Suspicious traffic can be rewritten in-kernel to deception services through shared NAT state
Tail-Call DPI HTTP, DNS, and SSH protocol inspection inside the eBPF pipeline
JA4 at Ingress TLS ClientHello extraction in the fast path with userspace JA4 assembly and lookup
Behavior Engine Per-IP lifecycle tracking, thresholds, and phase transitions in userspace
Optional AI Classification Deterministic rules first, then optional Ollama-backed classification when useful
Protocol-Faithful Deception HTTP, MySQL, DNS, and SSH-style interactive responses built to keep suspicious actors engaged
Deterministic Fallback Shell SSH-style tarpit sessions remain coherent even if Ollama is unavailable
Mesh Intelligence libp2p transport, gossip, consensus, reputation, and proof-of-work-gated peer admission
Feed Distribution Verified IoCs exposed as JSON, STIX/TAXII, Splunk HEC JSON, QRadar LEEF, and CEF

Engineering capabilities

Feature Description
Coverage-Guided Fuzzing libfuzzer-sys harnesses for DPI parsers and tarpit sanitization
TAXII Validation Path CI exercises the TAXII endpoint surface in hivemind-api
Operator Dashboard ANSI terminal dashboard plus --json NDJSON mode for scripts and pipelines
Controller View blackwall-controller prints sensor status in a stable table instead of raw heartbeats
Cross-Platform Dev Surface tarpit, hivemind, hivemind-api, and hivemind-dashboard build on macOS and Linux
Feature-Gated Privacy Paths Optional real TFHE and Groth16 code paths live in the repo behind features

Architecture

Workspace layout

Crate Kind Purpose
blackwall-ebpf binary XDP ingress, TC egress, tail-call DPI, in-kernel redirect, connection tracking
blackwall binary eBPF loader, event consumer, classifier, rule writer, peer publisher
tarpit library + binary Deception services and SSH-style interaction path
hivemind library + binary Mesh node, consensus, reputation, PoW admission, FL modules
hivemind-api library + binary Feed server, STIX/TAXII surface, stats endpoint
hivemind-dashboard binary ANSI dashboard and NDJSON telemetry output
blackwall-controller binary Controller and status monitor for sensor nodes
common library Shared ABI, event structs, mesh-facing types, constants
xtask binary Build helper for blackwall-ebpf and other workspace tasks

Platform boundaries

Surface Status
blackwall-ebpf Linux-only, built separately with nightly and bpfel-unknown-none
blackwall Linux-only because it loads and manages eBPF programs
tarpit, hivemind, hivemind-api, hivemind-dashboard, blackwall-controller, xtask Normal Rust userspace crates

For the full implementation-level walkthrough, see docs/architecture.md.

Quick Start

Build

Linux userspace crates:

cargo build --workspace

eBPF object:

cargo xtask build-ebpf

Cross-platform verification subset:

cargo test -p tarpit -p hivemind -p hivemind-api -p hivemind-dashboard

Run

sudo RUST_LOG=info ./target/release/blackwall config.toml
RUST_LOG=info ./target/release/tarpit
RUST_LOG=info ./target/release/hivemind
RUST_LOG=info ./target/release/hivemind-api
./target/release/hivemind-dashboard
./target/release/blackwall-controller 10.0.0.2:9471

Operator examples

# Live dashboard
./target/release/hivemind-dashboard

# Scripted monitoring
./target/release/hivemind-dashboard --json | jq '.peer_count'

# Feed query
curl -H "Authorization: Bearer <api-key>" http://127.0.0.1:8090/api/v1/feed

Project Structure

siren/
├── README.md
├── docs/
│   ├── README.md                  # Documentation index
│   ├── architecture.md           # Current code paths and system flow
│   ├── problem.md                # Why the codebase exists
│   ├── moat.md                   # What is hard to replicate
│   ├── testing.md                # Verification story and current gaps
│   ├── threat-model.md           # Trust boundaries and known limits
│   ├── team.md                   # Four-person execution model and ownership map
│   ├── code-map.md               # File-level source inventory
│   ├── glossary.md               # Shared terminology
│   ├── components/               # One page per crate
│   └── specs/                    # External contracts such as OpenAPI
├── blackwall-ebpf/
├── blackwall/
├── tarpit/
├── hivemind/
├── hivemind-api/
├── hivemind-dashboard/
├── blackwall-controller/
├── common/
├── xtask/
└── CONTRIBUTING.md

API and Operator Surfaces

Main feed endpoints

Endpoint Method Description
/api/v1/feed GET Verified IoCs as JSON
/api/v1/feed/stix GET STIX 2.1 bundle
/api/v1/feed/splunk GET Splunk HEC-compatible JSON
/api/v1/feed/qradar GET QRadar LEEF output
/api/v1/feed/cef GET CEF output
/api/v1/stats GET Feed statistics
/taxii2/ GET TAXII discovery document
/taxii2/collections/ GET TAXII collections
/taxii2/collections/{id}/objects/ GET TAXII object retrieval
/stats GET Dashboard stats endpoint

Full contract: docs/specs/hivemind-api-openapi.yaml

Operator interfaces

Surface Description
ANSI dashboard Live terminal view of mesh and firewall state
NDJSON dashboard mode Script-friendly stream for jq, files, and shippers
Controller table Multi-node sensor status via blackwall-controller

Testing and Validation

Area Current state
Workspace tests cargo test --workspace
Fuzzing Coverage-guided cargo-fuzz targets for DPI parsers and tarpit sanitization
TAXII path CI test coverage for the TAXII endpoint surface
Pagination contracts API contract tests in hivemind-api/tests/load_test.rs
Build matrix Linux, eBPF nightly build, macOS userspace subset, feature-matrix builds

More detail: docs/testing.md

Documentation

Implementation-focused documentation lives in docs/.

Document Contents
Architecture Current process and data flow
Problem Concrete security problems Siren addresses
Moat Technical properties that are hard to copy
Testing Verification story, CI, fuzzing, and remaining gaps
Threat Model Active trust boundaries and implementation limits
Team Four-person execution model and division of labor
Code Map Crate and file inventory
Components One page per crate
Specs External contracts and OpenAPI description
Glossary Shared terms and acronyms

Team

Member Role Ownership
Ian Roybal Architecture and kernel lead blackwall-ebpf, common, cross-workstream integration
Arav Lohe Userspace enforcement lead blackwall, blackwall-controller, policy and orchestration
Chinonso U. Ogwudu Deception lead tarpit, protocol fidelity, attacker interaction quality
Rishi Gandhe Mesh and operator-surface lead hivemind, hivemind-api, hivemind-dashboard

More detail: docs/team.md

About

No description, website, or topics provided.

Resources

Readme

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages