block-nuke-telemetry/docs/quick-start.md

Quick Start Guide for Nuke Telemetry Blocking

This guide walks a beginner through installing the required tools, running the monitoring scripts, and blocking telemetry from The Foundry’s Nuke compositor. All commands are written for an Arch‑Linux system.

---

1. Prerequisites

Package	Purpose
tcpdump	Capture packets for analysis
iptables / nftables	Firewall rules used by the scripts
notify-send (optional)	Desktop notifications from the monitor script
curl, nslookup	Verify that blocks are working

Install them with pacman:

sudo pacman -S --needed tcpdump iptables nftables libnotify curl nslookup

The scripts ship with a --help flag – run any script with -h to see its options.

---

2. Quick Reference Table

Script	What it does	Typical command
scripts/firewall_block_nuke.sh	Adds kernel‑level rules that reject outbound connections to Foundry telemetry IPs.	sudo bash scripts/firewall_block_nuke.sh
block_nuke_telemetry.sh	Modifies /etc/hosts so the domains resolve to 127.0.0.1.	bash block_nuke_telemetry.sh
scripts/monitor_nuke_network.sh	Continuously watches Nuke processes and logs any external connections.	bash scripts/monitor_nuke_network.sh --continuous
scripts/dns_sinkhole_config.sh	Generates configuration snippets for Pi‑Hole / dnsmasq that block Foundry domains.	bash scripts/dns_sinkhole_config.sh

---

3. Installation & Setup

1. Clone the repository (if you haven’t already):

   git clone https://github.com/your-org/block-nuke-telemetry.git
   cd block-nuke-telemetry
   

2. Make scripts executable – they should already be, but just in case:

   chmod +x *.sh scripts/*.sh
   

3. Run the firewall blocker (recommended first step):

   sudo bash scripts/firewall_block_nuke.sh
   

   This writes rules to /etc/iptables/iptables.rules or /etc/nftables.conf. Use --status to verify.

4. Apply the hosts‑file block (optional but adds a second layer):

   bash block_nuke_telemetry.sh
   

5. (Optional) Generate DNS sinkhole configs if you run Pi‑Hole or dnsmasq:

   bash scripts/dns_sinkhole_config.sh > ~/pi-hole-dns.conf
   

   Then add the generated lines to your DNS server.

---

4. Basic Usage

4.1 Monitoring Nuke in Real Time

# Run in a terminal; press Ctrl+C to stop
bash scripts/monitor_nuke_network.sh --continuous

The script prints lines like:

[2025-11-27 14:32:10] ALERT: Nuke process (PID 867114) connected to api.honeycomb.io:443

It also writes a log file nuke_telemetry_alerts.log that can be tail‑viewed.

4.2 Capturing Packets for Investigation

If you want to capture traffic yourself, use the following command (you may need sudo):

sudo tcpdump -i any -w nuke_foundry_capture.pcap 'host api.honeycomb.io or host learn.foundry.com'

Stop with Ctrl+C and analyze later.

4.3 Verifying the Blocks

After applying firewall/hosts rules, confirm that DNS resolves to localhost and that connections fail:

# DNS resolution should return 127.0.0.1
nslookup api.honeycomb.io
# Connection attempt should timeout or be refused
curl -I https://api.honeycomb.io --max-time 5

You should see Connection timed out or a refusal.

---

5. Troubleshooting Common Issues

Symptom	Likely Cause	Fix
Help menu in Nuke doesn’t load	learn.foundry.com is blocked	Temporarily comment out the hosts‑file entry or use a VPN that bypasses DNS filtering
Crash reports are not sent	Sentry domain blocked	Keep the hosts block but allow sentry.foundry.com if you need support
Nuke fails to start	Firewall rule accidentally blocks localhost	Ensure rules only target external IPs. Check with sudo iptables -L OUTPUT -v -n.

---

6. Further Reading

• Advanced Blocking Methods – detailed explanation of each technique: Advanced‑Blocking‑Methods.md
• Packet Capture Analysis – the raw 20‑minute capture and findings: nuke_foundry_analysis.md
• Full Investigation Report – legal, privacy, and mitigation summary: Foudry-Nuke-Monitoring.md

---

7. Appendix – Quick‑Start Script Flags

Flag	Meaning
--continuous	Keep the monitor running until stopped with Ctrl+C
--status	Show current firewall rule status
--restore	Remove firewall rules added by firewall_block_nuke.sh
-h, --help	Display usage information

---

Enjoy a privacy‑respectful Nuke workflow!