Skip to content
HookProbe Docs

Debugging

Debugging

This guide helps diagnose and resolve common HookProbe issues.

Quick Diagnostics

Health Check

Terminal window
hookprobe-ctl health --verbose

Service Status

Terminal window
hookprobe-ctl status
systemctl status hookprobe-agent.service

View Logs

Terminal window
hookprobe-ctl logs -f
journalctl -u hookprobe-agent.service --since "1 hour ago"

Common Issues

Service Won’t Start

Symptoms:

  • hookprobe-ctl status shows “stopped”
  • Service fails to start

Diagnostics:

Terminal window
# Check status
systemctl status hookprobe-agent.service


# View detailed errors
journalctl -u hookprobe-agent.service -n 100


# Check provision
systemctl status hookprobe-provision.service

Common Causes:

  1. Missing dependencies

    Terminal window
    sudo apt install -y podman openvswitch-switch
    sudo systemctl start hookprobe-provision.service

  2. Port conflict

    Terminal window
    sudo ss -tlnp | grep 8888
    # Kill conflicting process or change port

  3. Permission issues

    Terminal window
    sudo chown -R root:root /opt/hookprobe
    sudo chmod 755 /opt/hookprobe

XDP Not Loading

Symptoms:

  • No XDP in ip link show
  • hookprobe-ctl metrics | grep xdp shows zeros

Diagnostics:

Terminal window
# Check kernel version (need 5.4+)
uname -r


# Check NIC driver
ethtool -i eth0 | grep driver


# Check XDP programs
bpftool prog list

Solutions:

  1. Wrong mode

    Terminal window
    # Try generic mode
    XDP_MODE="skb"
    sudo systemctl restart hookprobe-agent.service

  2. Unsupported NIC

  3. Kernel too old

    Terminal window
    # Upgrade kernel (Ubuntu)
    sudo apt install linux-generic-hwe-22.04
    sudo reboot

High QSecBit Score

Symptoms:

  • Score stuck in AMBER or RED
  • False positives

Diagnostics:

Terminal window
# View score breakdown
hookprobe-ctl metrics | jq '.qsecbit'


# Check which component is high
hookprobe-ctl metrics | jq '.qsecbit.components'

Analysis:

High ComponentLikely Cause
threatsActive attack or false positive
mobileUntrusted network (normal on public WiFi)
idsIDS rules triggering (review alerts)
xdpHigh packet rate (DDoS or busy network)
dnsxaiMany blocked domains (check if legitimate)

Solutions:

  1. Review alerts

    Terminal window
    hookprobe-ctl logs | grep alert

  2. Adjust thresholds

    /etc/hookprobe/network-config.sh
    QSECBIT_AMBER_THRESHOLD=0.50
    QSECBIT_RED_THRESHOLD=0.75

  3. Whitelist false positives

    /etc/hookprobe/dnsxai.yaml
    whitelist:
      - "legitimate-domain.com"

High Memory Usage

Symptoms:

  • System sluggish
  • OOM kills in logs

Diagnostics:

Terminal window
# Check memory usage
free -h


# Check HookProbe processes
ps aux | grep hookprobe


# Check container memory
podman stats --no-stream

Solutions:

  1. Set memory limits

    Terminal window
    sudo systemctl edit hookprobe-agent.service
    

    [Service]
    MemoryMax=1G

  2. Reduce log retention

    logging:
      max_size_mb: 50
      max_files: 5

  3. Switch to efficiency mode

    Terminal window
    hookprobe-ctl hotshot --mode efficiency

WiFi Hotspot Not Working (Guardian)

Symptoms:

  • Can’t see “HookProbe-Guardian” WiFi
  • Clients can’t connect

Diagnostics:

Terminal window
# Check hostapd
systemctl status hostapd
journalctl -u hostapd -n 50


# Check WiFi interfaces
iw dev


# Check DHCP
systemctl status dnsmasq

Solutions:

  1. Wrong country code

    Terminal window
    # Check/set WiFi country
    sudo raspi-config  # Localisation Options

  2. Interface not available

    Terminal window
    # Check WiFi adapters
    iw dev
    

    # Restart networking
    sudo systemctl restart NetworkManager

  3. Channel conflict

    Terminal window
    # Edit hostapd.conf
    channel=6  # Try different channel

Mesh Connection Failed

Symptoms:

  • hookprobe-ctl mesh status shows disconnected
  • No peers visible

Diagnostics:

Terminal window
# Check mesh status
hookprobe-ctl mesh status


# Check HTP connectivity
nc -vuz validator1.hookprobe.mesh 8144


# Check gossip port
nc -vz validator1.hookprobe.mesh 7946

Solutions:

  1. Firewall blocking

    Terminal window
    sudo ufw allow 8144/udp
    sudo ufw allow 7946/tcp
    sudo ufw allow 7946/udp

  2. Wrong bootstrap nodes

    /etc/hookprobe/dsm.yaml
    gossip:
      bootstrap_nodes:
        - "validator1.hookprobe.mesh:7946"

  3. Network issue

    Terminal window
    # Test DNS resolution
    dig validator1.hookprobe.mesh
    

    # Test connectivity
    ping validator1.hookprobe.mesh

Log Analysis

Log Locations

LogPath
Agent/var/log/hookprobe/agent.log
Provision/var/log/hookprobe/provision.log
Update/var/log/hookprobe/update.log
NAPSE/var/log/napse/events.json

Search Logs

Terminal window
# Find errors
grep -i error /var/log/hookprobe/agent.log


# Find specific event
grep "QSecBit" /var/log/hookprobe/agent.log | tail -20


# JSON log analysis
cat /var/log/hookprobe/agent.log | jq 'select(.level=="ERROR")'

Log Levels

Terminal window
# Enable debug logging
sudo systemctl edit hookprobe-agent.service


[Service]
Environment="LOG_LEVEL=DEBUG"


sudo systemctl daemon-reload
sudo systemctl restart hookprobe-agent.service

Debug Mode

Enable Debug Output

Terminal window
# Run agent in foreground with debug
sudo /opt/hookprobe/agent/main.py --debug --foreground

Debug Endpoints

Terminal window
# Debug metrics
curl http://localhost:8888/debug/metrics


# Debug state
curl http://localhost:8888/debug/state


# Debug connections
curl http://localhost:8888/debug/connections

Forensic Analysis

Capture State

Terminal window
# Create debug bundle
hookprobe-ctl debug-bundle --output /tmp/debug-$(date +%Y%m%d).tar.gz

What’s Included

  • Configuration files
  • Recent logs
  • System information
  • Network state
  • Service status
  • Metrics snapshot

Getting Help

Before Reporting

  1. Check this debugging guide
  2. Create debug bundle
  3. Note steps to reproduce

Report Issues

Include

  • Debug bundle
  • HookProbe version
  • OS and kernel version
  • Steps to reproduce
  • Expected vs actual behavior

Next Steps