|
| 1 | +# Stackdog Security — Copilot Instructions |
| 2 | + |
| 3 | +## What This Project Is |
| 4 | + |
| 5 | +Stackdog is a Rust-based security platform for Docker containers and Linux servers. It collects events via eBPF syscall monitoring, runs them through a rule/signature engine and optional ML anomaly detection, manages firewall responses (nftables/iptables + container quarantine), and exposes a REST + WebSocket API consumed by a React/TypeScript dashboard. |
| 6 | + |
| 7 | +## Workspace Structure |
| 8 | + |
| 9 | +This is a Cargo workspace with two crates: |
| 10 | +- `.` — Main crate (`stackdog`): HTTP server, all security logic |
| 11 | +- `ebpf/` — Separate crate (`stackdog-ebpf`): eBPF programs compiled for the kernel (uses `aya-ebpf`) |
| 12 | + |
| 13 | +## Build, Test, and Lint Commands |
| 14 | + |
| 15 | +```bash |
| 16 | +# Build |
| 17 | +cargo build |
| 18 | +cargo build --release |
| 19 | + |
| 20 | +# Tests |
| 21 | +cargo test --lib # Unit tests only (in-source) |
| 22 | +cargo test --all # All tests including integration |
| 23 | +cargo test --lib -- events:: # Run tests for a specific module |
| 24 | +cargo test --lib -- rules::scorer # Run a single test by name prefix |
| 25 | + |
| 26 | +# Code quality |
| 27 | +cargo fmt --all |
| 28 | +cargo clippy --all |
| 29 | +cargo audit # Dependency vulnerability scan |
| 30 | + |
| 31 | +# Benchmarks |
| 32 | +cargo bench |
| 33 | + |
| 34 | +# Frontend (in web/) |
| 35 | +npm test |
| 36 | +npm run lint |
| 37 | +npm run build |
| 38 | +``` |
| 39 | + |
| 40 | +## Environment Setup |
| 41 | + |
| 42 | +Requires a `.env` file (copy `.env.sample`). Key variables: |
| 43 | +``` |
| 44 | +APP_HOST=0.0.0.0 |
| 45 | +APP_PORT=5000 |
| 46 | +DATABASE_URL=stackdog.db |
| 47 | +RUST_BACKTRACE=full |
| 48 | +``` |
| 49 | + |
| 50 | +System dependencies (Linux): `libsqlite3-dev libssl-dev clang llvm pkg-config` |
| 51 | + |
| 52 | +## Architecture |
| 53 | + |
| 54 | +``` |
| 55 | +Collectors (Linux only) Rule Engine Response |
| 56 | + eBPF syscall events → Signatures → nftables/iptables |
| 57 | + Docker daemon events → Threat scoring → Container quarantine |
| 58 | + Network events → ML anomaly det. → Alerting |
| 59 | +
|
| 60 | + REST + WebSocket API |
| 61 | + React/TypeScript UI |
| 62 | +``` |
| 63 | + |
| 64 | +**Key src/ modules:** |
| 65 | + |
| 66 | +| Module | Purpose | |
| 67 | +|---|---| |
| 68 | +| `events/` | Core event types: `SyscallEvent`, `SecurityEvent`, `NetworkEvent`, `ContainerEvent` | |
| 69 | +| `rules/` | Rule engine, signature database, threat scorer | |
| 70 | +| `alerting/` | `AlertManager`, notification channels (Slack/email/webhook) | |
| 71 | +| `collectors/` | eBPF loader, Docker daemon events, network collector (Linux only) | |
| 72 | +| `firewall/` | nftables management, iptables fallback, `QuarantineManager` (Linux only) | |
| 73 | +| `ml/` | Candle-based anomaly detection (optional `ml` feature) | |
| 74 | +| `correlator/` | Event correlation engine | |
| 75 | +| `baselines/` | Baseline learning for anomaly detection | |
| 76 | +| `database/` | SQLite connection pool (`r2d2` + raw `rusqlite`), repositories | |
| 77 | +| `api/` | actix-web REST endpoints + WebSocket | |
| 78 | +| `response/` | Automated response action pipeline | |
| 79 | + |
| 80 | +## Key Conventions |
| 81 | + |
| 82 | +### Platform-Gating |
| 83 | +Linux-only modules (`collectors`, `firewall`) and deps (aya, netlink) are gated: |
| 84 | +```rust |
| 85 | +#[cfg(target_os = "linux")] |
| 86 | +pub mod firewall; |
| 87 | +``` |
| 88 | +The `ebpf` and `ml` features are opt-in and must be enabled explicitly: |
| 89 | +```bash |
| 90 | +cargo build --features ebpf |
| 91 | +cargo build --features ml |
| 92 | +``` |
| 93 | + |
| 94 | +### Error Handling |
| 95 | +- Use `anyhow::{Result, Context}` for application/binary code |
| 96 | +- Use `thiserror` for library error types |
| 97 | +- Never use `.unwrap()` in production code; use `?` with `.context("...")` |
| 98 | + |
| 99 | +### Database |
| 100 | +The project uses raw `rusqlite` with `r2d2` connection pooling. `DbPool` is `r2d2::Pool<SqliteConnectionManager>`. Tables are created with `CREATE TABLE IF NOT EXISTS` in `database::connection::init_database`. Repositories are in `src/database/repositories/` and receive a `&DbPool`. |
| 101 | + |
| 102 | +### API Routes |
| 103 | +Each API sub-module exports a `configure_routes(cfg: &mut web::ServiceConfig)` function. All routes are composed in `api::configure_all_routes`, which is the single call site in `main.rs`. |
| 104 | + |
| 105 | +### Test Location |
| 106 | +- **Unit tests**: `#[cfg(test)] mod tests { ... }` inside source files |
| 107 | +- **Integration tests**: `tests/` directory at workspace root |
| 108 | + |
| 109 | +### eBPF Programs |
| 110 | +The `ebpf/` crate is compiled separately for the Linux kernel. User-space loading is handled by `src/collectors/ebpf/` using the `aya` library. Kernel-side programs use `aya-ebpf`. |
| 111 | + |
| 112 | +### Async Runtime |
| 113 | +The main binary uses `#[actix_rt::main]`. Library code uses `tokio`. Avoid mixing runtimes. |
0 commit comments