Skip to main content

OWASAKA SIEM - Nix Development Guide

Overview​

This project uses Nix Flakes for reproducible development environments. The flake.nix provides all necessary tools, dependencies, and scripts for O.W.A.S.A.K.A. development.

Prerequisites​

Install Nix with Flakes​

# Install Nix (multi-user installation recommended)
sh <(curl -L https://nixos.org/nix/install) --daemon

# Enable flakes (add to ~/.config/nix/nix.conf or /etc/nix/nix.conf)
mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf

Quick Start​

Enter Development Shell​

# From project root
nix develop

# Or for a pure environment (no system PATH pollution)
nix develop --pure

# First run might take a while (downloads all dependencies)

You'll see the O.W.A.S.A.K.A. welcome banner and a fully configured development environment!

Development Environment​

Included Tools​

Core Development​

  • Go 1.22+ - Latest stable Go compiler
  • gotools - godoc, goimports, etc.
  • gopls - Go language server (LSP)
  • delve - Go debugger

Go Development Tools​

  • golangci-lint - Comprehensive Go linter
  • air - Hot reload for Go applications
  • gotest - Enhanced testing
  • gotestsum - Pretty test output

Build Tools​

  • Make - Build automation
  • GCC - C compiler (for cgo)
  • pkg-config - Package configuration

Frontend Development​

  • Node.js 20 LTS - JavaScript runtime
  • npm - Package manager
  • pnpm - Fast package manager alternative

Browser Integration​

  • Firefox ESR - For browser integration testing

Network Analysis (PHASE 1)​

  • nmap - Network scanner
  • tcpdump - Packet capture
  • tshark - Terminal Wireshark
  • dig, host, nslookup - DNS tools
  • ip - Network configuration
  • netcat - Network debugging
  • socat - Socket relay
  • iperf3 - Network performance testing

Container Tools (PHASE 2)​

  • Docker - Container runtime
  • docker-compose - Multi-container orchestration

Security Tools​

  • OpenSSL - SSL/TLS toolkit
  • GnuPG - Cryptographic signing

Documentation​

  • mdbook - Markdown documentation generator
  • graphviz - Graph/diagram generation

Utilities​

  • jq - JSON processor
  • yq - YAML processor
  • ripgrep (rg) - Fast text search
  • fd - Fast file finder
  • bat - Enhanced cat with syntax highlighting
  • htop - Process monitor
  • bottom (btm) - Modern resource monitor

Custom Development Commands​

The development environment provides oswaka-dev wrapper for common tasks:

Build & Run​

oswaka-dev build          # Build the project
oswaka-dev run            # Build and run
oswaka-dev watch          # Hot reload development mode

Testing​

oswaka-dev test           # Run all tests
oswaka-dev test-coverage  # Tests with coverage report
oswaka-dev bench          # Run benchmarks

Code Quality​

oswaka-dev lint           # Run linters
oswaka-dev fmt            # Format code
oswaka-dev check          # Run all checks

Network Tools​

oswaka-dev scan-network   # Quick network scan
oswaka-dev capture        # Start packet capture
oswaka-dev dns-test       # Test DNS resolution

Documentation​

oswaka-dev docs           # Serve documentation

Utilities​

oswaka-dev clean          # Clean build artifacts
oswaka-dev info           # Show project info
oswaka-dev help           # Show all commands

Aliases​

The development shell provides convenient aliases:

Build Aliases​

dev           # oswaka-dev wrapper
build         # make build
run           # make run
test          # make test
lint          # make lint

Network Analysis​

scan          # sudo nmap -sn (network scan)
capture       # sudo tcpdump -i any (packet capture)
dns           # dig @8.8.8.8 (DNS query)
docs          # cd docs
internal      # cd internal
configs       # cd configs

Git Helpers​

git-status    # git status -sb (short format)
git-log       # git log --oneline --graph -10

Testing​

gotest        # go test -v -race -coverprofile=coverage.out

Environment Variables​

The development shell sets up:

Go Configuration​

GOPATH="$HOME/go"
GOBIN="$GOPATH/bin"
GOCACHE="$PWD/.cache/go-build"
GOMODCACHE="$PWD/.cache/go-mod"
GO111MODULE=on
GOMAXPROCS=$(nproc)

Project Configuration​

OSWAKA_ENV="development"
OSWAKA_CONFIG="$PWD/configs/examples/default.yaml"

Node.js Configuration​

NODE_ENV="development"
NPM_CONFIG_PREFIX="$PWD/.npm-global"

Privacy (Telemetry Disabled)​

CHECKPOINT_DISABLE=1
DO_NOT_TRACK=1
HOMEBREW_NO_ANALYTICS=1

Hot Reload with Air​

Air is pre-configured for automatic rebuilds on file changes:

# Start hot reload
oswaka-dev watch

# Or directly
air

# Configuration in .air.toml

Watched files:

  • *.go (except tests)
  • *.yaml, *.yml
  • *.html, *.tpl, *.tmpl

Excluded:

  • *_test.go
  • tmp/, vendor/, .git/, .cache/
  • web/node_modules/

Building with Nix​

Build the Package​

# Build oswaka using Nix
nix build

# Result in ./result/bin/oswaka
./result/bin/oswaka --version

Run Directly​

# Run without building
nix run

# With arguments
nix run . -- --config configs/examples/default.yaml

IDE Integration​

VSCode / VSCodium​

Install the Nix Environment Selector extension:

code --install-extension arrterian.nix-env-selector

Add to .vscode/settings.json:

{
  "nix.enableLanguageServer": true,
  "nix.serverPath": "nil",
  "go.toolsManagement.autoUpdate": true,
  "go.useLanguageServer": true,
  "go.alternateTools": {
    "gopls": "gopls"
  }
}

Neovim​

With direnv integration:

# Install direnv
nix-env -iA nixpkgs.direnv

# Create .envrc
echo "use flake" > .envrc
direnv allow

Emacs​

Install nix-mode and direnv-mode:

(use-package nix-mode
  :mode "\\.nix\\'")

(use-package direnv
  :config
  (direnv-mode))

Troubleshooting​

Flake is Too Old​

# Update flake inputs
nix flake update

# Re-enter shell
exit
nix develop

Missing Permissions for Network Tools​

Some tools require elevated privileges:

# For nmap, tcpdump, etc.
sudo -E oswaka-dev scan-network
sudo -E oswaka-dev capture

Go Module Issues​

# Clean Go cache
rm -rf .cache/go-build .cache/go-mod

# Re-download modules
go mod download
go mod tidy

Shell Hook Not Running​

# Force reload
nix develop --command bash

Advanced Usage​

Customize the Environment​

Fork flake.nix and modify buildInputs:

buildInputs = with pkgs; [
  # Add your custom tools here
  my-custom-tool
];

Add More Scripts​

Extend devScripts in flake.nix:

devScripts = pkgs.writeScriptBin "oswaka-dev" ''
  #!${pkgs.bash}/bin/bash

  function my-new-command() {
    echo "Custom command"
  }

  # Add to case statement
  case "$1" in
    my-command) my-new-command ;;
    # ...
  esac
'';

Override Go Version​

buildInputs = with pkgs; [
  go_1_23  # Use Go 1.23 instead
  # ...
];

Pinning Specific Versions​

The flake uses nixos-unstable for latest packages. To pin specific versions:

inputs = {
  nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.11";  # Pin to 23.11
  # ...
};

CI/CD Integration​

GitHub Actions​

name: CI
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: cachix/install-nix-action@v22
        with:
          extra_nix_config: |
            experimental-features = nix-command flakes
      - run: nix build
      - run: nix develop --command make test

Clean Up​

Exit Development Shell​

exit

Garbage Collect Nix Store​

# Remove unused packages
nix-collect-garbage

# Aggressive cleanup (remove old generations)
nix-collect-garbage -d

Resources​

Document Version: 1.0.0 Last Updated: 2025-10-25 Status: Production Ready