Agent Debugging Guide¶

# Method 1: Command line flag
./krakenhashes-agent --debug --host backend.example.com:31337

# Method 2: Environment variable
export DEBUG=true
export LOG_LEVEL=DEBUG
./krakenhashes-agent --host backend.example.com:31337

# Method 3: Edit .env file
echo "DEBUG=true" >> .env
echo "LOG_LEVEL=DEBUG" >> .env
./krakenhashes-agent --host backend.example.com:31337

./krakenhashes-agent --help

  --debug               Enable debug logging (default: false)
  --host string         Backend server host (e.g., localhost:31337)
  --tls                 Use TLS for secure communication (default: true)
  --interface string    Network interface to listen on (optional)
  --heartbeat int       Heartbeat interval in seconds (default: 5)
  --config-dir string   Configuration directory for certificates and credentials
  --data-dir string     Data directory for binaries, wordlists, rules, and hashlists
  --hashcat-params string  Extra parameters to pass to hashcat (e.g., '-O -w 3')

# Logging Configuration
DEBUG=true                    # Enable debug logging
LOG_LEVEL=DEBUG              # Set minimum log level (DEBUG, INFO, WARNING, ERROR)

# Server Configuration
KH_HOST=backend.example.com  # Backend hostname
KH_PORT=31337               # Backend port
USE_TLS=true                # Use secure connections

# WebSocket Timing Configuration
KH_WRITE_WAIT=10s           # WebSocket write timeout
KH_PONG_WAIT=60s            # Server pong timeout
KH_PING_PERIOD=54s          # Ping interval

# File Transfer Configuration
KH_MAX_CONCURRENT_DOWNLOADS=3  # Concurrent download limit
KH_DOWNLOAD_TIMEOUT=1h         # Download timeout
KH_MAX_DOWNLOAD_RETRIES=3      # Download retry attempts

# Development Configuration
HEARTBEAT_INTERVAL=5        # Heartbeat frequency (seconds)

# Show all messages
LOG_LEVEL=DEBUG

# Show info, warnings, and errors
LOG_LEVEL=INFO

# Show only warnings and errors
LOG_LEVEL=WARNING

# Show only errors
LOG_LEVEL=ERROR

# Add to .env file
DEBUG=true
LOG_LEVEL=DEBUG

# Monitor WebSocket messages
tail -f agent.log | grep -E "(WebSocket|WSMessage|connection)"

# Connection timeout
[ERROR] Failed to create connection on attempt 1: dial tcp: i/o timeout

# Certificate issues
[ERROR] Failed to load CA certificate: certificate signed by unknown authority

# Authentication failures
[ERROR] WebSocket handshake failed: HTTP 401 Unauthorized

# Filter sync-related logs
tail -f agent.log | grep -E "(sync|download|FileInfo)"

# Debug specific file types
tail -f agent.log | grep -E "(wordlist|rule|binary)"

# Job-specific logs
tail -f agent.log | grep -E "(job|task|hashcat|progress)"

# Real-time hashcat output
tail -f agent.log | grep "hashcat_output"

# Monitor state transitions
tail -f agent.log | grep -E "(state|State|transition|Transition)"

# Monitor ACK protocol
tail -f agent.log | grep -E "(ACK|ack|waiting|acknowledge)"

# Monitor stuck detection
tail -f agent.log | grep -E "(stuck|Stuck|recovery|Recovery|pending)"

# Look for state info in logs
tail -f agent.log | grep -E "GetState|currentState|GetStateInfo"

# Hardware detection logs
tail -f agent.log | grep -E "(hardware|GPU|device|monitor)"

# Device capabilities
tail -f agent.log | grep -E "(OpenCL|CUDA|compute)"

# Build with debug symbols (no optimization)
cd agent
make clean

# Set debug build flags
export GOFLAGS="-gcflags=-N -gcflags=-l"
make build

# Or build with race detection
go build -race -o debug-agent ./cmd/agent

# Install delve
go install github.com/go-delve/delve/cmd/dlv@latest

# Build and debug
cd agent
go build -gcflags="all=-N -l" -o debug-agent ./cmd/agent

# Start debugging session
dlv exec ./debug-agent -- --debug --host localhost:31337

# Common delve commands:
# (dlv) break main.main
# (dlv) continue
# (dlv) print cfg
# (dlv) step
# (dlv) next

# CPU profiling
go tool pprof http://localhost:6060/debug/pprof/profile

# Memory profiling
go tool pprof http://localhost:6060/debug/pprof/heap

# Goroutine profiling
go tool pprof http://localhost:6060/debug/pprof/goroutine

# Monitor memory usage
while true; do
    ps -p $(pgrep krakenhashes-agent) -o pid,rss,vsz,pcpu,pmem,cmd
    sleep 5
done

# Monitor goroutines (with pprof endpoint)
curl http://localhost:6060/debug/pprof/goroutine?debug=1

# Enable debug logging
export DEBUG=true
export LOG_LEVEL=DEBUG

# Test network connectivity
telnet backend.example.com 31337
curl -k https://backend.example.com:31337/health

# Check certificate issues
openssl s_client -connect backend.example.com:31337

# Verify API key and agent ID
cat config/agent_credentials.json
cat config/api_key.json

# Check file permissions
ls -la data/wordlists/
ls -la data/rules/

# Verify network connectivity for downloads
curl -I https://backend.example.com:31337/api/files/download/wordlist/1

# Check available disk space
df -h data/

# Manual MD5 verification
md5sum data/wordlists/rockyou.txt

# Check hashcat installation
which hashcat
hashcat --version

# Test hashcat manually
hashcat -m 1000 -a 3 --stdout ?d?d?d?d | head -10

# Check GPU availability
hashcat -I

# Monitor system resources
top -p $(pgrep hashcat)
nvidia-smi  # For NVIDIA GPUs

# Enable memory profiling
export DEBUG=true
go tool pprof http://localhost:6060/debug/pprof/heap

# Check for memory leaks
# Monitor over time with:
watch "ps -p $(pgrep krakenhashes-agent) -o pid,rss,vsz"

# Reduce concurrent operations
# In .env file:
KH_MAX_CONCURRENT_DOWNLOADS=1
HEARTBEAT_INTERVAL=10

#!/bin/bash
# debug-helper.sh

# Show only error messages
show_errors() {
    grep "\[ERROR\]" agent.log | tail -20
}

# Show WebSocket connection events
show_websocket() {
    grep -E "(WebSocket|connection|disconnect)" agent.log | tail -20
}

# Show file sync activity
show_sync() {
    grep -E "(sync|download|upload)" agent.log | tail -20
}

# Show job execution
show_jobs() {
    grep -E "(job|task|hashcat)" agent.log | tail -20
}

# Usage: ./debug-helper.sh show_errors
$1

# Multi-pane monitoring with tmux
tmux new-session -d -s agent-debug

# Pane 1: Agent output
tmux send-keys -t agent-debug "tail -f agent.log" Enter

# Pane 2: System resources
tmux split-window -v -t agent-debug
tmux send-keys -t agent-debug "htop" Enter

# Pane 3: Network connections
tmux split-window -h -t agent-debug
tmux send-keys -t agent-debug "watch 'netstat -an | grep :31337'" Enter

# Attach to session
tmux attach-session -t agent-debug

#!/bin/bash
# validate-config.sh

echo "=== Agent Configuration Validation ==="

# Check required directories
echo "Checking directories..."
[ -d "config" ] && echo "✅ config/" || echo "❌ config/ missing"
[ -d "data" ] && echo "✅ data/" || echo "❌ data/ missing"

# Check .env file
echo "Checking .env configuration..."
if [ -f ".env" ]; then
    echo "✅ .env file exists"
    grep -q "KH_HOST=" .env && echo "✅ KH_HOST set" || echo "❌ KH_HOST missing"
    grep -q "DEBUG=" .env && echo "✅ DEBUG set" || echo "❌ DEBUG missing"
else
    echo "❌ .env file missing"
fi

# Check certificates
echo "Checking certificates..."
[ -f "config/agent.crt" ] && echo "✅ Agent certificate" || echo "❌ Agent certificate missing"
[ -f "config/ca.crt" ] && echo "✅ CA certificate" || echo "❌ CA certificate missing"

# Check API key
[ -f "config/api_key.json" ] && echo "✅ API key" || echo "❌ API key missing"

echo "=== Validation Complete ==="

cd agent

# Run all tests with verbose output
go test -v ./...

# Run specific package tests
go test -v ./internal/config
go test -v ./internal/agent
go test -v ./pkg/debug

# Run tests with race detection
go test -race -v ./...

# Generate test coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out -o coverage.html

# Start local backend for testing
cd ../backend
docker-compose -f docker-compose.dev-local.yml up -d

# Test agent connection
cd ../agent
./krakenhashes-agent --debug --host localhost:31337

# Start agent with profiling
go tool pprof -http=:8080 http://localhost:6060/debug/pprof/profile?seconds=30

# During heavy computation (hashcat jobs)
go tool pprof http://localhost:6060/debug/pprof/profile?seconds=60

# Heap profiling
go tool pprof -http=:8080 http://localhost:6060/debug/pprof/heap

# Allocation profiling
go tool pprof http://localhost:6060/debug/pprof/allocs

# Goroutine dump
curl http://localhost:6060/debug/pprof/goroutine?debug=1

# Interactive analysis
go tool pprof http://localhost:6060/debug/pprof/goroutine

# Clean build with debug symbols
cd agent
make clean

# Build with debug flags
go build -gcflags="all=-N -l" -ldflags="-X main.BuildMode=debug" -o debug-agent ./cmd/agent

# Run with additional debugging
./debug-agent --debug --host backend.example.com:31337

# Build with additional debugging
go build -tags debug -gcflags="all=-N -l" ./cmd/agent

# Build with memory debugging
go build -gcflags="all=-m" ./cmd/agent

# Build with race detection (development only)
go build -race ./cmd/agent

# On remote system
dlv exec ./krakenhashes-agent --listen=:2345 --headless=true --api-version=2 -- --debug

# From local system
dlv connect remote-host:2345

# Build debug container
docker build -f Dockerfile.debug -t agent-debug .

# Run with debug enabled
docker run -e DEBUG=true -e LOG_LEVEL=DEBUG agent-debug

# Attach debugger to container
docker exec -it <container_id> dlv attach <pid>