Stackdog Security

🛡️ Security platform for Docker Containers & Linux Servers

Stackdog Security is a Rust-based security platform that provides real-time threat detection, AI-powered anomaly detection, and automated response for containerized applications.

🔥 Key Features

📊 Real-time Monitoring — eBPF-based syscall monitoring with minimal overhead (<5% CPU)
🔍 Log Sniffing — Discover, read, and AI-summarize logs from containers and system files
🤖 AI/ML Detection — Candle-powered anomaly detection + OpenAI/Ollama log analysis
🚨 Alert System — Multi-channel notifications (Slack, email, webhook)
🔒 Automated Response — nftables/iptables firewall, container quarantine
📈 Threat Scoring — Configurable scoring with time-decay
🎯 Signature Detection — 10+ built-in threat signatures
📦 Log Archival — Deduplicate and compress logs with zstd, optionally purge originals

🚀 Quick Start

Install with curl (Linux)

curl -fsSL https://github.com/vsilent/stackdog/main/install.sh | sudo bash

Pin a specific version:

curl -fsSL https://github.com/vsilent/stackdog/main/install.sh | sudo bash -s -- --version v0.2.1

If your repository has no published stable release yet, use --version explicitly.

Run as Binary

# Clone repository
git clone https://github.com/vsilent/stackdog
cd stackdog

# Start the HTTP server (default)
cargo run

# Or explicitly
cargo run -- serve

Log Sniffing

# Discover and analyze logs (one-shot)
cargo run -- sniff --once

# Continuous monitoring with AI analysis
cargo run -- sniff --ai-provider openai

# Use Ollama (local LLM)
STACKDOG_AI_API_URL=http://localhost:11434/v1 cargo run -- sniff

# Consume mode: archive to zstd + purge originals
cargo run -- sniff --consume --output ./log-archive

# Add custom log sources
cargo run -- sniff --sources "/var/log/myapp.log,/opt/service/logs"

Use as Library

Add to your Cargo.toml:

[dependencies]
stackdog = "0.2"

Basic usage:

use stackdog::{RuleEngine, AlertManager, ThreatScorer};

let mut engine = RuleEngine::new();
let mut alerts = AlertManager::new()?;
let scorer = ThreatScorer::new();

// Process security events
for event in events {
    let score = scorer.calculate_score(&event);
    if score.is_high_or_higher() {
        alerts.generate_alert(...)?;
    }
}

Docker Development

# Start development environment
docker-compose up -d

# View logs
docker-compose logs -f stackdog

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     Stackdog Security Core                       │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │  Collectors │  │   ML/AI     │  │   Response Engine       │  │
│  │             │  │   Engine    │  │                         │  │
│  │ • eBPF      │  │             │  │ • nftables/iptables     │  │
│  │ • Auditd    │  │ • Anomaly   │  │ • Container quarantine  │  │
│  │ • Docker    │  │   Detection │  │ • Auto-response         │  │
│  │   Events    │  │ • Scoring   │  │ • Alerting              │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────────────┐│
│  │  Log Sniffing                                               ││
│  │  • Auto-discovery (system logs, Docker, custom paths)       ││
│  │  • AI summarization (OpenAI/Ollama/Candle)                  ││
│  │  • zstd compression, dedup, log purge                       ││
│  └──────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘

Components

Component	Description	Status
Events	Security event types & validation	✅ Complete
Rules	Rule engine & signature detection	✅ Complete
Alerting	Alert management & notifications	✅ Complete
Firewall	nftables/iptables integration	✅ Complete
Collectors	eBPF syscall monitoring	✅ Infrastructure
Log Sniffing	Log discovery, AI analysis, archival	✅ Complete
ML	Candle-based anomaly detection	⏳ Planned

🎯 Features

1. Event Collection

use stackdog::{SyscallEvent, SyscallType};

let event = SyscallEvent::builder()
    .pid(1234)
    .uid(1000)
    .syscall_type(SyscallType::Execve)
    .container_id(Some("abc123".to_string()))
    .build();

Supported Events:

Syscall events (execve, connect, openat, ptrace, etc.)
Network events
Container lifecycle events
Alert events

2. Rule Engine

use stackdog::RuleEngine;
use stackdog::rules::builtin::{SyscallBlocklistRule, ProcessExecutionRule};

let mut engine = RuleEngine::new();
engine.register_rule(Box::new(SyscallBlocklistRule::new(
    vec![SyscallType::Ptrace, SyscallType::Setuid]
)));

let results = engine.evaluate(&event);

Built-in Rules:

Syscall allowlist/blocklist
Process execution monitoring
Network connection tracking
File access monitoring

3. Signature Detection

use stackdog::SignatureDatabase;

let db = SignatureDatabase::new();
println!("Loaded {} signatures", db.signature_count());

let matches = db.detect(&event);
for sig in matches {
    println!("Threat: {} (Severity: {})", sig.name(), sig.severity());
}

Built-in Signatures (10+):

🪙 Crypto miner detection
🏃 Container escape attempts
🌐 Network scanners
🔐 Privilege escalation
📤 Data exfiltration

4. Threat Scoring

use stackdog::ThreatScorer;

let scorer = ThreatScorer::new();
let score = scorer.calculate_score(&event);

if score.is_critical() {
    println!("Critical threat detected! Score: {}", score.value());
}

Severity Levels:

Info (0-19)
Low (20-39)
Medium (40-69)
High (70-89)
Critical (90-100)

5. Alert System

use stackdog::AlertManager;

let mut manager = AlertManager::new()?;

let alert = manager.generate_alert(
    AlertType::ThreatDetected,
    AlertSeverity::High,
    "Suspicious activity detected".to_string(),
    Some(event),
)?;

manager.acknowledge_alert(&alert.id())?;

Notification Channels:

Console (logging)
Slack webhooks
Email (SMTP)
Generic webhooks

6. Firewall & Response

use stackdog::{QuarantineManager, ResponseAction, ResponseType};

// Quarantine container
let mut quarantine = QuarantineManager::new()?;
quarantine.quarantine("container_abc123")?;

// Automated response
let action = ResponseAction::new(
    ResponseType::BlockIP("192.168.1.100".to_string()),
    "Block malicious IP".to_string(),
);

Response Actions:

Block IP addresses
Block ports
Quarantine containers
Kill processes
Send alerts
Custom commands

7. Log Sniffing & AI Analysis

# Discover all log sources and analyze with AI
stackdog sniff --once --ai-provider openai

# Continuous daemon with local Ollama
stackdog sniff --interval 60 --ai-provider openai

# Consume: archive (zstd) + purge originals to free disk
stackdog sniff --consume --output ./archive

# Add custom sources alongside auto-discovered ones
stackdog sniff --sources "/app/logs/api.log,/app/logs/worker.log"

Capabilities:

🔍 Auto-discovers system logs, Docker container logs, and custom paths
🤖 AI summarization via OpenAI, Ollama, or local pattern analysis
📦 Deduplicates and compresses logs with zstd
🗑️ Optional --consume mode: archives then purges originals
📊 Incremental reading — tracks byte offsets, never re-reads old entries
🚨 Anomaly alerts routed to configured notification channels

REST API:

# List discovered sources
curl http://localhost:5000/api/logs/sources

# Add a custom source
curl -X POST http://localhost:5000/api/logs/sources \
  -H 'Content-Type: application/json' \
  -d '{"path": "/var/log/myapp.log", "name": "My App"}'

# View AI summaries
curl http://localhost:5000/api/logs/summaries?source_id=myapp

📦 Installation

Prerequisites

Rust 1.75+ (install)
SQLite3 + libsqlite3-dev
Linux kernel 4.19+ (for eBPF features)
Clang/LLVM (for eBPF compilation)

Install Dependencies

Ubuntu/Debian:

apt-get install libsqlite3-dev libssl-dev clang llvm pkg-config

macOS:

brew install sqlite openssl llvm

Fedora/RHEL:

dnf install sqlite-devel openssl-devel clang llvm

Build from Source

git clone https://github.com/vsilent/stackdog
cd stackdog
cargo build --release

Run Tests

# Run all tests
cargo test --lib

# Run specific module tests
cargo test --lib -- events::
cargo test --lib -- rules::
cargo test --lib -- alerting::
cargo test --lib -- sniff::

💡 Usage Examples

Example 1: Detect Suspicious Syscalls

use stackdog::{RuleEngine, SyscallEvent, SyscallType};
use stackdog::rules::builtin::SyscallBlocklistRule;

let mut engine = RuleEngine::new();
engine.register_rule(Box::new(SyscallBlocklistRule::new(
    vec![SyscallType::Ptrace, SyscallType::Setuid]
)));

let event = SyscallEvent::new(
    1234, 1000, SyscallType::Ptrace, Utc::now()
);

let results = engine.evaluate(&event);
if results.iter().any(|r| r.is_match()) {
    println!("⚠️ Suspicious syscall detected!");
}

Example 2: Container Quarantine

use stackdog::QuarantineManager;

let mut quarantine = QuarantineManager::new()?;

// Quarantine compromised container
quarantine.quarantine("container_abc123")?;

// Check quarantine status
let state = quarantine.get_state("container_abc123");
println!("Container state: {:?}", state);

// Release after investigation
quarantine.release("container_abc123")?;

Example 3: Multi-Event Pattern Detection

use stackdog::{SignatureMatcher, PatternMatch, SyscallType};

let mut matcher = SignatureMatcher::new();

// Detect: execve followed by ptrace (suspicious)
matcher.add_pattern(
    PatternMatch::new()
        .with_syscall(SyscallType::Execve)
        .then_syscall(SyscallType::Ptrace)
        .within_seconds(60)
);

let result = matcher.match_sequence(&events);
if result.is_match() {
    println!("⚠️ Suspicious pattern detected!");
}

More Examples

See examples/usage_examples.rs for complete working examples.

Run examples:

cargo run --example usage_examples

📚 Documentation

Document	Description
DEVELOPMENT.md	Complete development plan (18 weeks)
TESTING.md	Testing guide and infrastructure
TODO.md	Task tracking and roadmap
CHANGELOG.md	Version history
CONTRIBUTING.md	Contribution guidelines
STATUS.md	Current implementation status

API Documentation

# Generate docs
cargo doc --open

# View online (after release)
# https://docs.rs/stackdog

🛠️ Development

Project Structure

stackdog/
├── src/
│   ├── cli.rs           # Clap CLI (serve/sniff subcommands)
│   ├── events/          # Event types & validation
│   ├── rules/           # Rule engine & signatures
│   ├── alerting/        # Alerts & notifications
│   ├── firewall/        # nftables/iptables
│   ├── collectors/      # eBPF collectors
│   ├── sniff/           # Log sniffing & AI analysis
│   │   ├── config.rs    # SniffConfig (env + CLI)
│   │   ├── discovery.rs # Log source auto-discovery
│   │   ├── reader.rs    # File/Docker/Journald readers
│   │   ├── analyzer.rs  # AI summarization (OpenAI + pattern)
│   │   ├── consumer.rs  # zstd compression, dedup, purge
│   │   └── reporter.rs  # Alert routing
│   ├── api/             # REST API endpoints
│   ├── database/        # SQLite + repositories
│   ├── ml/              # ML infrastructure
│   └── config/          # Configuration
├── examples/            # Usage examples
├── tests/               # Integration tests
├── benches/             # Performance benchmarks
├── ebpf/                # eBPF programs
└── docs/                # Documentation

Development Workflow

# 1. Clone and setup
git clone https://github.com/vsilent/stackdog
cd stackdog
cp .env.sample .env

# 2. Build
cargo build

# 3. Run tests
cargo test --lib

# 4. Run example
cargo run --example usage_examples

# 5. Check code quality
cargo fmt --all -- --check
cargo clippy --all

Running on Linux

For full eBPF and firewall functionality:

# Requires root for eBPF
sudo cargo test --lib -- firewall::

# Check eBPF support
bpftool version
uname -r  # Should be 4.19+

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Quick Start for Contributors

# Fork and clone
git clone https://github.com/YOUR_USERNAME/stackdog
cd stackdog

# Create branch
git checkout -b feature/my-feature

# Make changes, run tests
cargo test --lib

# Commit and push
git commit -m "Add my feature"
git push origin feature/my-feature

Good First Issues

Look for issues labeled:

🟢 good first issue - Easy tasks for newcomers
🟡 help wanted - Need community help
🔵 documentation - Improve docs

📊 Project Status

Current Phase: Phase 2 - Detection & Response

Phase	Status	Progress
Phase 1: Foundation	✅ Complete	100%
Phase 2: Detection & Response	🚧 In Progress	60%
Phase 3: ML & Automation	⏳ Pending	0%
Phase 4: Web Dashboard	⏳ Pending	0%

Completed Tasks

✅ Project structure (TASK-001)
✅ Event types (TASK-002)
✅ eBPF infrastructure (TASK-003)
✅ Event enrichment (TASK-004)
✅ Rule engine (TASK-005)
✅ Signature detection (TASK-006)
✅ Alert system (TASK-007)
✅ Firewall integration (TASK-008)
✅ Log sniffing & AI analysis (TASK-009)

Upcoming Tasks

⏳ ML anomaly detection (TASK-010)
⏳ Web dashboard (TASK-011)
⏳ Kubernetes support (BACKLOG)

📜 License

This project is licensed under the MIT License.

Copyright (c) 2026 Vasili Pascal

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software...

🙏 Acknowledgments

Inspired By

Portainer - Docker management UI
Falco - Cloud-native runtime security
Sysdig - System visibility

Technologies

aya-rs - Rust eBPF framework
Candle - HuggingFace ML framework
Actix-web - Rust web framework
rusqlite - SQLite bindings for Rust
r2d2 - Connection pool

📬 Contact

Project Lead: Vasili Pascal
Email: info@try.direct
Twitter: @VasiliiPascal
Gitter: stackdog/community
GitHub: vsilent/stackdog

🐕 Built with ❤️ using Rust

Name		Name	Last commit message	Last commit date
Latest commit History 150 Commits
.githooks		.githooks
.github		.github
.qwen		.qwen
benches		benches
docker		docker
docs		docs
ebpf		ebpf
examples		examples
migrations		migrations
scripts		scripts
src		src
tests		tests
web		web
.coveralls		.coveralls
.editorconfig		.editorconfig
.env.sample		.env.sample
.gitignore		.gitignore
BUGS.md		BUGS.md
CHANGELOG.md		CHANGELOG.md
CLEANUP_SUMMARY.md		CLEANUP_SUMMARY.md
CODE-OF-CONDUCT.md		CODE-OF-CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.test.toml		Cargo.test.toml
Cargo.toml		Cargo.toml
DEVELOPMENT.md		DEVELOPMENT.md
INTEGRATION_TESTING_SUMMARY.md		INTEGRATION_TESTING_SUMMARY.md
LICENSE		LICENSE
QWEN.md		QWEN.md
README.md		README.md
ROADMAP.md		ROADMAP.md
STATUS.md		STATUS.md
TESTING.md		TESTING.md
TODO.md		TODO.md
VERSION.md		VERSION.md
docker-compose.yml		docker-compose.yml
install.sh		install.sh
package-lock.json		package-lock.json

Folders and files

Latest commit

History

Repository files navigation

Stackdog Security

🛡️ Security platform for Docker Containers & Linux Servers

🔥 Key Features

📖 Table of Contents

🚀 Quick Start

Install with curl (Linux)

Run as Binary

Log Sniffing

Use as Library

Docker Development

🏗️ Architecture

Components

🎯 Features

1. Event Collection

2. Rule Engine

3. Signature Detection

4. Threat Scoring

5. Alert System

6. Firewall & Response

7. Log Sniffing & AI Analysis

📦 Installation

Prerequisites

Install Dependencies

Build from Source

Run Tests

💡 Usage Examples

Example 1: Detect Suspicious Syscalls

Example 2: Container Quarantine

Example 3: Multi-Event Pattern Detection

More Examples

📚 Documentation

API Documentation

🛠️ Development

Project Structure

Development Workflow

Running on Linux

🤝 Contributing

Quick Start for Contributors

Good First Issues

📊 Project Status

Current Phase: Phase 2 - Detection & Response

Completed Tasks

Upcoming Tasks

📜 License

🙏 Acknowledgments

Inspired By

Technologies

📬 Contact

About

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages