How stamusnetworks/stamusctl works
Project Type and Purpose
• This is primarily a Go-based CLI application (“stamusctl”) with an optional companion daemon (“stamusd”) exposing a REST API.
• It’s not a web front-end but rather a systems tool that manages containerized Stamus NDR stacks via Docker Compose and a template system.
File Structure Analysis
• Top level:
• cmd/ctl – the Cobra-based CLI commands (“compose”, “config”, “template”, “login”, etc.).
• cmd/daemon – Gin-based REST API server code (“stamusd run”, version, docs).
• internal/ – core business logic packaged by domain (“handlers”, “models”, “docker-compose”, “docker”, “logging”, “auth”, “stamus”, “embeds”).
• pkg/ – public helper libraries (mocking, daemon helpers).
• .test/ – end-to-end and unit test inputs & outputs for compose/init.
• docker/, .github/, scripts/, Makefile – build, CI, Dockerfiles for CLI/daemon.
• The separation (cmd vs. internal vs. pkg) follows a typical Go clean-architecture, with command plumbing in cmd/ and logic in internal/.
README Insights
• Core responsibilities:
• Template Consumer: loads Go templates from an external repo.
• Docker Compose Wrapper: generates, updates, and drives Docker Compose stacks.
• PCAP Reader: built-in packet capture analysis.
• Registry Connector: login/pull images from container registries.
• Daemon (stamusd): same functions over HTTP (Swagger documented).
Diagramming the Architecture
a. Main Components
• CLI Client (stamusctl)
• Daemon Server (stamusd)
• Internal Logic (handlers, models, utils, docker connectors)
• Template System (external stamusctl-templates repo + embedded defaults)
• Docker Engine & Docker Compose
• Containerized Services (Suricata, Logstash, Nginx, etc. as defined by templates)
• Registry (public/private container registries)
• File System (configuration directory, values.yaml, binds)
b. Relationships & Data Flows
1. User invokes stamusctl → Cobra CLI parses flags → calls internal handlers.
2. Handlers consult models & utils → load templates (local embed or external repo/registry).
3. Template consumer writes config files (Docker Compose YAML, Nginx conf, apps).
4. Handlers call Docker Compose wrapper (via Go Docker SDK or shell) → Docker Engine → spin up containers.
5. For readpcap, handlers invoke built-in PCAP reader module (internal/app).
6. For login and pull, handlers call Docker registry module (internal/docker).
7. stamusd sits behind Gin router, exposes same handler functions over HTTP.
c. Architectural Patterns
• Clean-architecture: cmd → handlers → models → lower-level Docker and template services.
• Separation of Concerns: CLI vs. Daemon vs. Template engine vs. Docker integration.
• Embedded resources: default templates embedded under internal/embeds.
• Dependency Injection: internal/docker uses mocks for unit testing.
d. Key Technologies
• Go, Cobra (CLI), Gin (REST API)
• Go templates + Sprig
• Docker SDK / Docker Compose
• Swagger (for API docs)