Port Map 192.168.50.138

Requirements

Supported hardware: Lenovo ThinkPad T430, Dell Wyse 5070, Raspberry Pi 4/5 (4 GB+). Not supported: Pi 3B/3B+ (insufficient RAM).

Installation

Battleship package (recommended)

# On this machine — build the deployment tarball
bash /opt/Guarddex0/make-battleship-package.sh
# Copies to: guarddex-battleship-YYYYMMDD.tar.gz (~4 MB)

# SCP to target node
scp guarddex-battleship-*.tar.gz user@TARGET_IP:~

# On target node
tar -xzf guarddex-battleship-*.tar.gz && cd guarddex-battleship-*/
sudo bash install.sh

What install.sh prompts for (v1.2)

1. Server name + Public URL (auto-detected from hostname -I)
2. Admin email, password (with confirmation re-type), and optional admin settings PIN (with confirmation)
3. ntfy server URL, username, password (push notifications)
4. HIBP (HaveIBeenPwned) API key — optional, enables breach monitor
5. VirusTotal API key — optional, improves URL threat scoring
6. NextDNS API key + profile ID — optional, auto-adds blocked domains to DNS denylist
7. SMTP credentials for email alerts (optional)
8. Anthropic API key — write-only (not displayed), required for AI on battleships without Ollama

What install.sh does (in order)

1. RAM check — aborts if <2 GB, warns if <4 GB
2. Loads keys-preset.env if present (battleship package)
3. apt install: python3, pip, postgresql, redis, nmap (no Node.js on battleship)
4. Creates Python venv at /opt/guarddex/venv, pip install -r requirements.txt
5. Creates .env from prompts + presets
6. Creates PostgreSQL user + database; grants schema privileges (PG15+ compatible)
7. Runs python3 backend/init_db.py — creates all tables including LAN scanner + breach tables
8. Creates admin user + NotificationPrefs row via API bootstrap script
9. Writes and enables guarddex.service systemd unit with ExecStartPre that auto-updates PUBLIC_URL in .env from current LAN IP on every boot
10. Waits up to 24 seconds for service to start (retry loop), then tails first 20 log lines
11. Deletes keys-preset.env if present

Post-install Configuration

First login

http://<SERVER_IP>:8088/dashboard/login.html

Log in as the admin account you created during install. Go to Profile to confirm notification preferences are saved.

ntfy provisioning QR

Visit /dashboard/provision.html — this generates a QR code family members scan to subscribe their ntfy app automatically. Share this page URL or take a screenshot of the QR.

Verify the admin account is flagged as admin

SELECT email, is_admin FROM users;
-- If is_admin = false for admin account:
UPDATE users SET is_admin = true WHERE email = '[email protected]';

Cockpit — browser-based system monitor

Cockpit provides CPU, RAM, disk, network, logs, and a browser terminal. Available at http://<SERVER_IP>:9090. A shortcut is in the Admin Settings page Quick Links bar. Log in with your OS user credentials.

sudo apt install cockpit -y && sudo systemctl enable --now cockpit.socket

Dynamic MOTD (login message)

If hpt430-master-setup.sh was run before install.sh, the server displays a GuardDex status banner after every SSH login showing CPU, RAM, disk, service states, and fail2ban ban counts.

Verify Installation

bash /opt/Guarddex0/verify.sh

Runs 11 checks: RAM, systemd service, PostgreSQL (native or Docker), Redis (native or Docker), nmap, /health, register, login, notification prefs, URL scan, AI status. All should show [PASS]. A 3 GB machine will show 1 warning (RAM) — expected.

Service Management systemd

sudo systemctl start   guarddex      # start
sudo systemctl stop    guarddex      # stop
sudo systemctl restart guarddex      # restart (after .env changes)
sudo systemctl reload  guarddex      # reload config without full restart (if supported)
sudo systemctl status  guarddex      # current state + last few log lines
sudo systemctl enable  guarddex      # auto-start on boot
sudo systemctl disable guarddex      # remove from boot

Unit file location

/etc/systemd/system/guarddex.service

After editing the unit file: sudo systemctl daemon-reload && sudo systemctl restart guarddex

Other services

sudo systemctl restart guarddex-attackstudio   # Attack Studio :8089
sudo systemctl restart guarddex-testbench      # TestBench :9090
sudo systemctl restart postgresql              # native PostgreSQL (battleship)
sudo systemctl restart redis                   # native Redis (battleship)
docker restart data-postgres                   # Docker PostgreSQL (mothership)
docker restart data-redis                      # Docker Redis (mothership)

Logs & Monitoring

Live log tail

sudo journalctl -u guarddex -f

Time-scoped

sudo journalctl -u guarddex --since "1 hour ago"
sudo journalctl -u guarddex --since "2026-05-02 08:00" --until "2026-05-02 10:00"

Filter by severity

sudo journalctl -u guarddex -p err -n 50    # errors only
sudo journalctl -u guarddex -p warning -f   # warnings + errors, live

JSON scan stats

cat /opt/Guarddex0/guarddex_stats.json | python3 -m json.tool

AI status

curl -s http://localhost:8088/api/v1/analytics/ai-status | python3 -m json.tool

Recent scans (database)

SELECT url, verdict, created_at FROM url_scans ORDER BY created_at DESC LIMIT 20;

Recent alerts (database)

SELECT alert_type, severity, description, created_at FROM alerts ORDER BY created_at DESC LIMIT 20;

Upgrading

Standard upgrade (same node)

cd /opt/Guarddex0
sudo systemctl stop guarddex

# Pull latest source (if using git)
git pull origin main

# Or SCP a new battleship package and extract over the existing directory
# (only replaces backend/ and dashboard/ — .env is preserved)

# Upgrade Python dependencies
venv/bin/pip install -r backend/requirements.txt --quiet

# Run DB migrations if any (check CHANGES file first)
PYTHONPATH=backend venv/bin/python3 backend/init_db.py

sudo systemctl start guarddex
sudo journalctl -u guarddex -n 30   # verify clean startup

Rebuild blocklist rules after updating gd_blocklist.txt

python3 /opt/Guarddex0/extension/scripts/generate_rules.py
# Then rebuild extension zip
bash /opt/Guarddex0/extension/scripts/build.sh

Backup & Restore

Full backup script (run as cron or manually)

BACKUP_DIR="/opt/backups/guarddex/$(date +%Y%m%d)"
mkdir -p "$BACKUP_DIR"

# Database dump
pg_dump -U guarddex_user guarddex_db > "$BACKUP_DIR/guarddex_db.sql"
# Or via Docker:
docker exec data-postgres pg_dump -U guarddex_user guarddex_db > "$BACKUP_DIR/guarddex_db.sql"

# Config and stats
cp /opt/Guarddex0/.env              "$BACKUP_DIR/env.bak"
cp /opt/Guarddex0/guarddex_stats.json "$BACKUP_DIR/"
cp /opt/Guarddex0/guarddex_alerts.json "$BACKUP_DIR/"

echo "Backup complete → $BACKUP_DIR"

Restore from backup

# Restore .env first, then DB
sudo systemctl stop guarddex
cp /opt/backups/guarddex/20260502/env.bak /opt/Guarddex0/.env

# Native PostgreSQL
psql -U guarddex_user -d guarddex_db < /opt/backups/guarddex/20260502/guarddex_db.sql

# Docker PostgreSQL
docker exec -i data-postgres psql -U guarddex_user -d guarddex_db \
  < /opt/backups/guarddex/20260502/guarddex_db.sql

sudo systemctl start guarddex

User Management database

List all users

SELECT id, email, full_name, is_admin, created_at FROM users ORDER BY created_at;

Grant admin

UPDATE users SET is_admin = true WHERE email = '[email protected]';

Reset a user's password

# Generate bcrypt hash
python3 -c "from passlib.context import CryptContext; \
  print(CryptContext(schemes=['bcrypt']).hash('NewPassword123!'))"

# Apply it
UPDATE users SET hashed_password = '<hash_output>' WHERE email = '[email protected]';

Delete a user and their data

BEGIN;
DELETE FROM notification_prefs WHERE user_id = (SELECT id FROM users WHERE email = '[email protected]');
DELETE FROM url_scans           WHERE user_id = (SELECT id FROM users WHERE email = '[email protected]');
DELETE FROM alerts              WHERE user_id = (SELECT id FROM users WHERE email = '[email protected]');
DELETE FROM users WHERE email = '[email protected]';
COMMIT;

View a user's scan history

SELECT url, verdict, confidence, created_at
FROM url_scans
WHERE user_id = (SELECT id FROM users WHERE email = '[email protected]')
ORDER BY created_at DESC LIMIT 50;

Check notification preferences

SELECT u.email, n.ntfy_enabled, n.ntfy_topic, n.email_enabled, n.sms_enabled
FROM notification_prefs n JOIN users u ON u.id = n.user_id;

Battleship Node Deployment new in v2.1

A battleship is a lean GuardDex node for a family member or remote office. It runs the API and dashboard but not Ollama or Attack Studio. AI falls back to Claude Haiku.

Build package on mothership

bash /opt/Guarddex0/make-battleship-package.sh
# Output: guarddex-battleship-YYYYMMDD.tar.gz (~4 MB)
# Contains: backend/ dashboard/ install.sh verify.sh APK guarddex.apk
# Also bundles keys-preset.env (chmod 600) — shareable API keys auto-loaded by install.sh
# Keys bundled: Anthropic, VT, HIBP, OTX, GreyNoise, Shodan, AbuseIPDB, URLScan, etc.
# Keys NOT bundled: NextDNS, SMTP, Twilio, DB/JWT secrets (per-node only)

Deploy

scp guarddex-battleship-*.tar.gz [email protected]:~
ssh [email protected]
tar -xzf guarddex-battleship-*.tar.gz && cd guarddex-battleship-*/
sudo bash install.sh

Key battleship .env settings

ENABLE_OLLAMA=false              # no local GPU — use Haiku
ANTHROPIC_API_KEY=sk-ant-...     # required for AI on battleship
DATABASE_URL=postgresql://guarddex_user:PASSWORD@localhost:5432/guarddex_db
# Note: native PostgreSQL uses port 5432 (not 5433 like Docker on mothership)

Provision Android app on a battleship

1. Install the APK on the user's phone: adb install guarddex-v2.2-release.apk — or download from /dashboard/guarddex.apk in a browser
2. On the battleship server, open /dashboard/provision.html
3. Show the user the QR code — phone camera scan → GuardDex app opens → server URL saved automatically
4. Guide user through enabling Notification Access (Settings → Apps → Special app access → Notification access → GuardDex → On)
5. Set GuardDex as default browser (Settings → Apps → Default apps → Browser)

Appliance Setup hpt430-master-setup.sh

Run this script before install.sh on a fresh OS install to harden the machine and prepare it for operation as a GuardDex appliance. Designed for HP t430 thin clients and similar low-power hardware.

sudo bash /opt/Guarddex0/hpt430-master-setup.sh

Key variables at the top of the script

What it configures (in order)

1. Static IP via Netplan (Ubuntu) or /etc/network/interfaces (Debian) if STATIC_IP is set
2. Base packages: curl, wget, git, htop, net-tools, fail2ban, unzip, tmux, rsync, nmap
3. Tailscale (auto-installs and displays auth URL for one-time setup)
4. Docker opt-in (disabled by default)
5. fail2ban SSH jail: 3 failures = 24-hour ban
6. zram compressed RAM (lz4, 50% of physical RAM) + swap file + sysctl swappiness=10
7. Dynamic MOTD at /etc/update-motd.d/10-guarddex — shows GuardDex banner, CPU/RAM/disk stats, service states, and fail2ban counts on every SSH login
8. TigerVNC + noVNC browser desktop on port 6080 (opt-in)
9. Chains into install.sh (opt-in)

Browser-based desktop (VNC over noVNC)

When ENABLE_VNC=1, the desktop accessible via HDMI can also be viewed in a browser at http://<SERVER_IP>:6080. Useful for diagnosing UI issues or running graphical apps remotely without needing an HDMI monitor attached.

# Start/stop the noVNC session manually
sudo systemctl start  guarddex-vnc
sudo systemctl stop   guarddex-vnc
sudo systemctl status guarddex-vnc

User Profile Features new in v2.2

Each logged-in user can access these features from their Profile page (/dashboard/profile.html).

Data Export

Downloads a full JSON file of the user's account data: profile, scan history, alerts, notification preferences, breach check history.

GET /api/v2/auth/export-data    # Auth: JWT  →  returns JSON download

Delete Account

Permanently removes the user and all their data across 6 database tables. Requires current password + the exact phrase DELETE MY ACCOUNT.

DELETE /api/v2/auth/account
# Body: {"password": "...", "confirmation": "DELETE MY ACCOUNT"}

Security Report

Generates a printable HTML security summary covering the past N days: URL scans, alert breakdown, breach status, notification history.

GET /api/v2/auth/security-report?days=30    # Auth: JWT  →  returns HTML

Two-Factor Authentication (TOTP)

TOTP-based 2FA using any authenticator app (Google Authenticator, Authy, Bitwarden, etc.).

1. Go to Profile → Two-Factor Authentication → Set Up 2FA
2. A QR code appears — scan it with your authenticator app
3. Enter the 6-digit code from the app to confirm setup
4. On future logins, the login page will prompt for the 6-digit code after your password

Build APK

# Prerequisites (mothership only)
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
# Node.js 22 must be installed (via NodeSource)

# Debug build (default)
bash /opt/Guarddex0/build-apk.sh

# Release build (requires keystore)
bash /opt/Guarddex0/build-apk.sh release

Output: /opt/Guarddex0/guarddex-v2.2-release.apk (~3.1 MB signed). Also copied to dashboard/guarddex.apk — downloadable from /dashboard/guarddex.apk.

Source: /opt/Guarddex0/mobile/ — Capacitor 8 + Android SDK API 34

Key source files

Build Browser Extension new in v2.1

bash /opt/Guarddex0/extension/scripts/build.sh
# Regenerates rules, icons, zips to guarddex-extension.zip (15 KB)

Rebuild blocklist rules (after updating gd_blocklist.txt)

python3 /opt/Guarddex0/extension/scripts/generate_rules.py
# Reads mobile/android/app/src/main/assets/gd_blocklist.txt
# Writes extension/rules/blocklist_rules.json (132 rules)

Install in Chrome (development)

# chrome://extensions → Developer mode → Load unpacked
# Point to: /opt/Guarddex0/extension/

Install in Firefox (temporary)

# about:debugging → Load Temporary Add-on
# Select: /opt/Guarddex0/guarddex-extension.zip

Requires Chrome 111+ / Firefox 128+ for world: "MAIN" fingerprint guard support.

Environment Variables /opt/Guarddex0/.env

Key API Endpoints

Scan response shape

{
  "verdict":       "safe" | "challenge" | "block",
  "is_blocked":     false,
  "is_challenged":  false,
  "matched_brand":  "Bank of America" | null,
  "confidence":     0.0 – 1.0,
  "signals":        ["typosquatting", "fresh domain"],
  "reason":         "string explanation"
}

AI Configuration

Install Ollama (mothership)

curl -fsSL https://ollama.com/install.sh | sh
ollama pull nous-hermes2:10.7b   # security assistant
ollama pull phi3:mini            # URL analyzer
ollama pull dolphin-mistral:7b   # Attack Studio red team AI

Check AI status

curl -s http://localhost:8088/api/v1/analytics/ai-status | python3 -m json.tool

NextDNS Integration

When configured, scan verdicts of block auto-add the domain to the NextDNS denylist, protecting all devices on your network at the DNS level.

NEXTDNS_API_KEY=your_api_key
NEXTDNS_PROFILE_ID=4344ac   # "Dave's" profile

Manually check denylist count

curl -H "X-Api-Key: YOUR_KEY" \
  "https://api.nextdns.io/profiles/4344ac/denylist" | python3 -m json.tool | grep -c domain

Architecture

  Android / Browser Extension
        │  HTTPS :8088
        ▼
  ┌────────────────────────────────────────┐
  │  FastAPI  (backend/main.py)            │
  │  ─────────────────────────────────     │
  │  /api/v1/   challenge_api.py           │  scan, brands, analytics
  │             security_api.py           │  15 detectors, AI assistant
  │  /api/v2/   auth_api.py               │  JWT register/login/me
  │             notification_api.py       │  prefs, test, dispatch
  │  ─────────────────────────────────     │
  │  services/  url_scanner.py            │  threat intel aggregator
  │             notification_service.py   │  ntfy / email / SMS
  │  security/  phishing_detector.py      │  44-brand + heuristics
  │             ai_analyzer.py            │  Ollama or Haiku
  └──────────┬─────────────────────────────┘
             │
    ┌────────┴──────────┐
    │                   │
  PostgreSQL           Redis          Ollama
  :5433 (Docker)       :6379          :11434
  :5432 (native)       rate limit     models
  users, scans         cache          (mothership)
  alerts, prefs

Troubleshooting — Service / Boot

Service fails to start

sudo journalctl -u guarddex -n 50 --no-pager

Common causes and fixes:

Troubleshooting — Database

Test connectivity

# Native
psql -U guarddex_user -d guarddex_db -c "SELECT 1"

# Docker (mothership)
docker exec data-postgres psql -U guarddex_user -d guarddex_db -c "SELECT 1"

Recreate all tables (dev only — destroys data)

PYTHONPATH=backend venv/bin/python3 backend/init_db.py

Check tables exist

\dt     -- inside psql: should list users, url_scans, alerts, notification_prefs

API returns 500 on every request

Almost always a database connection issue. Check DATABASE_URL in .env — watch for @, #, $ in password (must be URL-encoded or avoided). Mothership uses port 5433; battleship uses 5432.

Troubleshooting — Auth / JWT

Login returns 401 for valid credentials

Check SECRET_KEY in .env is set and hasn't changed since the token was issued. Changed SECRET_KEY invalidates all existing tokens — users must log in again.

Admin account shows is_admin = false

UPDATE users SET is_admin = true WHERE email = '[email protected]';

Forgot admin password

python3 -c "from passlib.context import CryptContext; \
  print(CryptContext(schemes=['bcrypt']).hash('NewPassword!'))"
UPDATE users SET hashed_password = '<hash>' WHERE email = '[email protected]';

Troubleshooting — Notifications

Notifications not arriving

Troubleshooting — Android App

Troubleshooting — Browser Extension

Troubleshooting — AI / Ollama

# Check Ollama is running
curl http://localhost:11434/api/tags

# Check available models
ollama list

# Pull a missing model
ollama pull nous-hermes2:10.7b

# Check GuardDex AI status endpoint
curl -s http://localhost:8088/api/v1/analytics/ai-status | python3 -m json.tool

If haiku_available: false in the AI status response and ENABLE_OLLAMA=false, set ANTHROPIC_API_KEY in .env and restart the service.

If ollama_available: false and ENABLE_OLLAMA=true, check that ollama.service is running and a model from the SECURITY_MODELS list is installed.

Third-party API Keys optional integrations

GuardDex's core scanner works out of the box with no external accounts. These integrations are optional add-ons that improve detection coverage, add notification channels, or enable DNS-level blocking. Each key goes in /opt/Guarddex0/.env, then sudo systemctl restart guarddex.

Anthropic — Claude AI

Used for: AI assistant in Security Center, URL phishing confidence scoring. Required on battleship nodes where Ollama is not available (ENABLE_OLLAMA=false).

ANTHROPIC_API_KEY=sk-ant-api03-...

VirusTotal — URL & IP Threat Intelligence

Used for: Enriches URL scans with VirusTotal's multi-engine verdict (70+ AV engines). Adds signal confidence to the phishing scorer.

VIRUSTOTAL_API_KEY=64-char-hex-key

Shodan — Network & Host Intelligence

Used for: DNS Scanner enrichment — looks up open ports, services, and known vulnerabilities on scanned IPs. Useful for IMSI catcher and C2 beacon detection context.

SHODAN_API_KEY=your-shodan-key

AbuseIPDB — IP Reputation

Used for: Flags IP addresses that have been reported for abuse, spam, or attacks. Adds a signal layer to network-based detectors.

ABUSEIPDB_API_KEY=your-key

PhishTank — Phishing URL Database

Used for: Cross-checks scanned URLs against a community-maintained database of verified phishing pages. Zero false positives since every entry is human-verified.

PHISHTANK_API_KEY=your-app-key

NextDNS — DNS-level Blocking

Used for: Auto-adds newly blocked domains to your NextDNS denylist, protecting every device on your network at the DNS level — not just those with the app.

NEXTDNS_API_KEY=your-api-key
NEXTDNS_PROFILE_ID=4344ac

Twilio — SMS Alerts

Used for: Sends SMS text message notifications when a phishing block or security alert fires, as an alternative or backup to ntfy push notifications.

TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your-auth-token
TWILIO_FROM_NUMBER=+15555550100

ntfy — Push Notifications

Used for: Real-time push alerts to phones. Preferred over SMS for instant delivery with no per-message cost.

NTFY_SERVER=https://ntfy.richeyda.com   # or https://ntfy.sh for the public server
NTFY_USERNAME=guarddex
NTFY_PASSWORD=your-ntfy-password

Changelog

v2.2 — 2026-05-18

v2.1 — 2026-05-02

v2.0.5 — 2026-02-25

JWT auth, PostgreSQL persistence, 44-brand phishing DB, 15 security detectors, Ollama AI assistant, notification system (ntfy/email/SMS), family dashboard, user profile, TestBench 10 suites.