feat(cli): add clap subcommands (serve/sniff) + sniff config

- Add clap 4 for CLI argument parsing
- Refactor main.rs: dispatch to serve (default) or sniff subcommand
- Create src/cli.rs with Cli/Command enums
- Create src/sniff/config.rs with SniffConfig (env + CLI args)
- Add new deps: clap, async-trait, reqwest, zstd
- Update .env.sample with sniff + AI provider config vars
- 12 unit tests (7 CLI parsing + 5 config loading)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: vsilent

.env.sample

@@ -5,3 +5,15 @@ APP_HOST=0.0.0.0
 APP_PORT=5000
 DATABASE_URL=stackdog.db
 RUST_BACKTRACE=full
+
+# Log Sniff Configuration
+#STACKDOG_LOG_SOURCES=/var/log/syslog,/var/log/auth.log
+#STACKDOG_SNIFF_INTERVAL=30
+#STACKDOG_SNIFF_OUTPUT_DIR=./stackdog-logs/
+
+# AI Provider Configuration
+# Supports OpenAI, Ollama (http://localhost:11434/v1), or any OpenAI-compatible API
+#STACKDOG_AI_PROVIDER=openai
+#STACKDOG_AI_API_URL=http://localhost:11434/v1
+#STACKDOG_AI_API_KEY=
+#STACKDOG_AI_MODEL=llama3

Cargo.toml

@@ -29,6 +29,7 @@ tracing-subscriber = "0.3"
 dotenv = "0.15"
 anyhow = "1"
 thiserror = "1"
+clap = { version = "4", features = ["derive"] }
 
 # Async runtime
 tokio = { version = "1", features = ["full"] }
@@ -37,6 +38,7 @@ actix-web = "4"
 actix-cors = "0.6"
 actix-web-actors = "4"
 actix = "0.13"
+async-trait = "0.1"
 
 # Database
 rusqlite = { version = "0.32", features = ["bundled"] }
@@ -45,6 +47,12 @@ r2d2 = "0.8"
 # Docker
 bollard = "0.16"
 
+# HTTP client (for LLM API)
+reqwest = { version = "0.12", features = ["json"] }
+
+# Compression
+zstd = "0.13"
+
 # eBPF (Linux only)
 [target.'cfg(target_os = "linux")'.dependencies]
 aya = "0.12"

src/cli.rs

@@ -0,0 +1,135 @@
+//! CLI argument parsing for Stackdog
+//!
+//! Defines the command-line interface using clap derive macros.
+//! Supports `serve` (HTTP server) and `sniff` (log analysis) subcommands.
+
+use clap::{Parser, Subcommand};
+
+/// Stackdog Security — Docker & Linux server security platform
+#[derive(Parser, Debug)]
+#[command(name = "stackdog", version, about, long_about = None)]
+pub struct Cli {
+    #[command(subcommand)]
+    pub command: Option<Command>,
+}
+
+/// Available subcommands
+#[derive(Subcommand, Debug, Clone)]
+pub enum Command {
+    /// Start the HTTP API server (default behavior)
+    Serve,
+
+    /// Sniff and analyze logs from Docker containers and system sources
+    Sniff {
+        /// Run a single scan/analysis pass, then exit
+        #[arg(long)]
+        once: bool,
+
+        /// Consume logs: archive to zstd, then purge originals to free disk
+        #[arg(long)]
+        consume: bool,
+
+        /// Output directory for consumed logs
+        #[arg(long, default_value = "./stackdog-logs/")]
+        output: String,
+
+        /// Additional log file paths to watch (comma-separated)
+        #[arg(long)]
+        sources: Option<String>,
+
+        /// Poll interval in seconds
+        #[arg(long, default_value = "30")]
+        interval: u64,
+
+        /// AI provider: "openai" or "candle"
+        #[arg(long)]
+        ai_provider: Option<String>,
+    },
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use clap::Parser;
+
+    #[test]
+    fn test_no_subcommand_defaults_to_none() {
+        let cli = Cli::parse_from(["stackdog"]);
+        assert!(cli.command.is_none(), "No subcommand should yield None (default to serve)");
+    }
+
+    #[test]
+    fn test_serve_subcommand() {
+        let cli = Cli::parse_from(["stackdog", "serve"]);
+        assert!(matches!(cli.command, Some(Command::Serve)));
+    }
+
+    #[test]
+    fn test_sniff_subcommand_defaults() {
+        let cli = Cli::parse_from(["stackdog", "sniff"]);
+        match cli.command {
+            Some(Command::Sniff { once, consume, output, sources, interval, ai_provider }) => {
+                assert!(!once);
+                assert!(!consume);
+                assert_eq!(output, "./stackdog-logs/");
+                assert!(sources.is_none());
+                assert_eq!(interval, 30);
+                assert!(ai_provider.is_none());
+            }
+            _ => panic!("Expected Sniff command"),
+        }
+    }
+
+    #[test]
+    fn test_sniff_with_once_flag() {
+        let cli = Cli::parse_from(["stackdog", "sniff", "--once"]);
+        match cli.command {
+            Some(Command::Sniff { once, .. }) => assert!(once),
+            _ => panic!("Expected Sniff command"),
+        }
+    }
+
+    #[test]
+    fn test_sniff_with_consume_flag() {
+        let cli = Cli::parse_from(["stackdog", "sniff", "--consume"]);
+        match cli.command {
+            Some(Command::Sniff { consume, .. }) => assert!(consume),
+            _ => panic!("Expected Sniff command"),
+        }
+    }
+
+    #[test]
+    fn test_sniff_with_all_options() {
+        let cli = Cli::parse_from([
+            "stackdog", "sniff",
+            "--once",
+            "--consume",
+            "--output", "/tmp/logs/",
+            "--sources", "/var/log/syslog,/var/log/auth.log",
+            "--interval", "60",
+            "--ai-provider", "openai",
+        ]);
+        match cli.command {
+            Some(Command::Sniff { once, consume, output, sources, interval, ai_provider }) => {
+                assert!(once);
+                assert!(consume);
+                assert_eq!(output, "/tmp/logs/");
+                assert_eq!(sources.unwrap(), "/var/log/syslog,/var/log/auth.log");
+                assert_eq!(interval, 60);
+                assert_eq!(ai_provider.unwrap(), "openai");
+            }
+            _ => panic!("Expected Sniff command"),
+        }
+    }
+
+    #[test]
+    fn test_sniff_with_candle_provider() {
+        let cli = Cli::parse_from(["stackdog", "sniff", "--ai-provider", "candle"]);
+        match cli.command {
+            Some(Command::Sniff { ai_provider, .. }) => {
+                assert_eq!(ai_provider.unwrap(), "candle");
+            }
+            _ => panic!("Expected Sniff command"),
+        }
+    }
+}

src/lib.rs

@@ -59,6 +59,9 @@ pub mod database;
 // Configuration
 pub mod config;
 
+// Log sniffing
+pub mod sniff;
+
 // Re-export commonly used types
 pub use events::syscall::{SyscallEvent, SyscallType};
 pub use events::security::{SecurityEvent, NetworkEvent, ContainerEvent, AlertEvent};

src/main.rs

@@ -22,19 +22,26 @@ mod config;
 mod api;
 mod database;
 mod docker;
+mod cli;
+mod sniff;
 
 use std::{io, env};
 use actix_web::{HttpServer, App, web};
 use actix_cors::Cors;
+use clap::Parser;
 use tracing::{Level, info};
 use tracing_subscriber::FmtSubscriber;
 use database::{create_pool, init_database};
+use cli::{Cli, Command};
 
 #[actix_rt::main]
 async fn main() -> io::Result<()> {
     // Load environment
     dotenv::dotenv().expect("Could not read .env file");
 
+    // Parse CLI arguments
+    let cli = Cli::parse();
+
     // Setup logging
     env::set_var("RUST_LOG", "stackdog=info,actix_web=info");
     env_logger::init();
@@ -49,8 +56,17 @@ async fn main() -> io::Result<()> {
     info!("🐕 Stackdog Security starting...");
     info!("Platform: {}", std::env::consts::OS);
     info!("Architecture: {}", std::env::consts::ARCH);
-    
-    // Display configuration
+
+    match cli.command {
+        Some(Command::Sniff { once, consume, output, sources, interval, ai_provider }) => {
+            run_sniff(once, consume, output, sources, interval, ai_provider).await
+        }
+        // Default: serve (backward compatible)
+        Some(Command::Serve) | None => run_serve().await,
+    }
+}
+
+async fn run_serve() -> io::Result<()> {
     let app_host = env::var("APP_HOST").unwrap_or_else(|_| "0.0.0.0".to_string());
     let app_port = env::var("APP_PORT").unwrap_or_else(|_| "5000".to_string());
     let database_url = env::var("DATABASE_URL").unwrap_or_else(|_| "./stackdog.db".to_string());
@@ -99,3 +115,33 @@ async fn main() -> io::Result<()> {
     .run()
     .await
 }
+
+async fn run_sniff(
+    once: bool,
+    consume: bool,
+    output: String,
+    sources: Option<String>,
+    interval: u64,
+    ai_provider: Option<String>,
+) -> io::Result<()> {
+    let config = sniff::config::SniffConfig::from_env_and_args(
+        once,
+        consume,
+        &output,
+        sources.as_deref(),
+        interval,
+        ai_provider.as_deref(),
+    );
+
+    info!("🔍 Stackdog Sniff starting...");
+    info!("Mode: {}", if config.once { "one-shot" } else { "continuous" });
+    info!("Consume: {}", config.consume);
+    info!("Output: {}", config.output_dir.display());
+    info!("Interval: {}s", config.interval_secs);
+    info!("AI Provider: {:?}", config.ai_provider);
+
+    // TODO: Implement sniff orchestrator (Checkpoint 6)
+    info!("⚠️  Sniff orchestrator not yet implemented");
+    Ok(())
+}
+