Troubleshooting

Common issues and how to resolve them. If you encounter a problem not listed here, check the console logs and backend output for details.

Python ML Not Starting

Symptoms

• Dashboard shows "Using JavaScript fallback"
• Console: "Python not found" or "Python subprocess start timeout"

Solutions

• Python not in PATH: Install Python from python.org and ensure it’s in your system PATH. Test with python --version or python3 --version.
• ML script missing: Ensure ml/predict.py exists in the project root. It may be missing in packaged builds.
• Dependencies: Install scikit-learn: pip install scikit-learn numpy.
• Disable Python ML: Set USE_PYTHON_ML=false in your environment to use the JavaScript fallback.

Firewall Block Fails

Symptoms

• Block IP returns success but traffic still allowed
• Console: "No firewall access"

Solutions

• Windows: Run DefenSys as Administrator. Right-click the executable → Run as administrator.
• Linux: Ensure sudo is configured for iptables. Test with sudo iptables -L -n.
• macOS: Firewall integration may require additional configuration. Check system preferences.

Packet Capture Not Working

Symptoms

• Dashboard shows 0 packets
• Traffic graph stays empty

Solutions

• Npcap: On Windows, install Npcap (or Wireshark which includes it). Enable "WinPcap API-compatible Mode" if needed.
• Interface: In Settings → Network, ensure the correct interface is selected. "Auto" may not always detect the right one.
• Permissions: On Linux, packet capture may require root or capabilities. Run with sudo or cap_net_raw.
• VPN: Some VPNs or virtual adapters can interfere with capture. Try disabling temporarily.

Too Many False Positives

Solutions

• ML thresholds: In combinedDetectionEngine.js, increase mlAnomalyScore (e.g. -0.3) and mlConfidence (e.g. 0.95) to be stricter.
• Retrain: Collect more normal traffic and retrain the ML model. See Training.
• Whitelist: Add trusted IPs to the firewall whitelist in Settings.

No Alerts

Solutions

• Thresholds too high: Lower ML thresholds or relax rule-based severity filters.
• Capture not running: Ensure packet capture is started (Header controls or Ctrl+Shift+S).
• Traffic filtered: Check if private traffic is being filtered. Some configs skip localhost or private ranges.

Mobile App Can't Connect

Solutions

• Same network: Mobile and desktop must be on the same network (or use port forwarding if remote).
• Firewall: Allow desktop app through Windows Firewall for inbound connections on the API port.
• URL: Use the desktop IP (e.g. 192.168.1.100:3000) not localhost. localhost on the phone refers to the phone itself.

Database Errors

Solutions

• Corrupted DB: Delete db/defensys.db and restart. Data will be recreated (alerts will be lost).
• Locked: Ensure only one instance of DefenSys is running. Close other instances and retry.