Skip to content

QUICKSTART.md

Latest commit

 

History

History
317 lines (219 loc) · 4.81 KB

QUICKSTART.md

File metadata and controls

317 lines (219 loc) · 4.81 KB

Quick Start Guide - Stackdog Security Development

Getting Started

1. Prerequisites

# Install Rust (if not installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install system dependencies (Ubuntu/Debian)
apt-get install libsqlite3-dev libssl-dev clang llvm pkg-config

# Install system dependencies (macOS)
brew install sqlite openssl llvm

2. Clone and Setup

cd /Users/vasilipascal/work/stackdog

# Copy environment file
cp .env.sample .env

# Generate secret key
head -c16 /dev/urandom > src/secret.key

3. Build and Test

# Build the project
cargo build

# Run all tests
cargo test --all

# Run specific test module
cargo test --test events::syscall_event_test

# Check code formatting
cargo fmt --all -- --check

# Run clippy linter
cargo clippy --all

4. Run the Application

# Run with debug logging
RUST_LOG=debug cargo run

# Run in release mode
cargo run --release

Development Workflow

TDD Workflow

  1. Write a failing test in tests/ directory
  2. Run the test to verify it fails: 
    cargo test --test <test_file>
  3. Implement minimal code to make the test pass
  4. Run test again to verify it passes
  5. Refactor while keeping tests green
  6. Repeat

Example: Creating a New Event Type

// 1. Write test first (tests/events/my_event_test.rs)
#[test]
fn test_my_event_creation() {
    let event = MyEvent::new("test");
    assert_eq!(event.name, "test");
}

// 2. Run test (should fail)
cargo test --test events::my_event_test

// 3. Implement in src/events/my_event.rs
pub struct MyEvent {
    pub name: String,
}

impl MyEvent {
    pub fn new(name: &str) -> Self {
        Self { name: name.to_string() }
    }
}

// 4. Run test again (should pass)
cargo test --test events::my_event_test

// 5. Refactor and add documentation

Module Structure

Adding a New Module

  1. Create directory under src/:

    mkdir src/my_module

  2. Create mod.rs:

    //! My module documentation

pub mod my_submodule;

pub struct MyModuleMarker;

  3. Add to main.rs:

    mod my_module;

  4. Create tests:

    mkdir tests/my_module

Running Specific Tests

# All tests
cargo test --all

# Specific test file
cargo test --test events::syscall_event_test

# Specific test function
cargo test test_syscall_event_creation

# Tests with pattern
cargo test test_syscall

# Integration tests
cargo test --test integration

# With output
cargo test -- --nocapture

# With coverage (requires cargo-tarpaulin)
cargo tarpaulin --all --out Html

Code Quality Commands

# Format code
cargo fmt --all

# Check formatting
cargo fmt --all -- --check

# Run linter
cargo clippy --all

# Run linter with all features
cargo clippy --all-features

# Security audit
cargo audit

# Check dependencies
cargo deny check

Debugging

Enable Debug Logging

RUST_LOG=debug cargo run
RUST_LOG=stackdog=debug cargo run
RUST_LOG=trace cargo run

Print Debug Information

// In your code
dbg!(&variable);
println!("Debug: {:?}", variable);

Using gdb/lldb

# Build with debug symbols
cargo build

# Run with debugger
lldb target/debug/stackdog

eBPF Development

Build eBPF Programs

cd ebpf
cargo build --release

Load eBPF Programs

# Requires root
sudo cargo bpf build

Debug eBPF

# List loaded eBPF programs
bpftool prog list

# View eBPF maps
bpftool map list

ML Development with Candle

Load Model

use candle_core::{Tensor, DType, Device};

let tensor = Tensor::new(&[1.0f32, 2.0, 3.0], &Device::Cpu)?;

Run Inference

use candle_nn::{Module, Linear};

let output = model.forward(&input)?;

Common Issues

Issue: Compilation errors with aya

Solution: Ensure you have LLVM installed:

# Ubuntu/Debian
apt-get install llvm clang

# macOS
brew install llvm

Issue: eBPF programs won't load

Solution: Check kernel version (requires 4.19+):

uname -r

Issue: Tests failing

Solution: Clean and rebuild:

cargo clean
cargo build
cargo test

Resources

Getting Help

Last updated: 2026-03-13