Getting Started with ZPK

ZPK is a network monitoring tool for Windows that watches your network traffic, flags anything unusual, and gives you a clear report. Everything runs locally — no cloud, no accounts, no data leaves your PC.

Requirements

• Windows 10 or Windows 11
• Run as Administrator (right-click terminal → "Run as administrator")
• That's it. No Python, no installers, no dependencies.

Quick Start

Windows SmartScreen: The EXE is not code-signed, so Windows may warn you on first run. Click "More info" then "Run anyway." This is normal for unsigned software.

First Run Setup

Before your first scan, you need two things:

Install Npcap (required)

Npcap is the driver that lets ZPK see network traffic. Without it, ZPK cannot capture packets.

1. Run zpk.exe and choose option 8 (Setup & Tools).
2. Choose Check/Install Npcap.
3. Follow the installer prompts. Make sure "WinPcap API-compatible mode" is checked.
4. Close and reopen your terminal after installation.

Or download Npcap yourself from npcap.com.

Download GeoIP Database (recommended)

The GeoIP database tells ZPK where external IPs are located (country, city, organization). It powers the world map and adds geographic context.

1. Run zpk.exe and choose option 8 (Setup & Tools).
2. Choose Update GeoIP & ASN databases.
3. ZPK downloads two small files automatically.

Optional but recommended. Without GeoIP, scans still work — you just won't see location data.

Running Your First Scan

1. Choose option 1 (Quick Scan) from the menu.
2. ZPK captures traffic for 30 seconds.
3. When done, you see a summary: connections, protocols, top destinations, and any findings.
4. Results are saved automatically to a timestamped folder.

What does a normal scan look like?

• Connections to your router (e.g. 192.168.1.1)
• DNS queries to your DNS server
• HTTPS connections to websites and cloud services
• A few INFO findings (normal observations)
• A green "All clear" verdict

Understanding Results

ZPK uses four severity levels:

INFO — Lowest

Normal activity logged for awareness. First connection to a new server, uncommon port, long-lived session. Action: Nothing needed.

WATCH

Unusual but probably fine. Traffic bursts, DNS failures, cleartext data, packet congestion. Action: Glance at it. If you recognize the activity, it's fine.

SUSPICIOUS

Could be a problem. Large outbound transfers, one host contacting many destinations, regular timed connections (beaconing). Action: Investigate. Check the process name and destination.

CRITICAL — Highest

Likely malicious or a serious misconfiguration. SYN floods, port scans across 100+ ports, rogue DHCP servers. Action: Investigate immediately.

The Verdict

• Green — "All clear": No issues found.
• Cyan — "Minor items": Only INFO/WATCH findings.
• Yellow — "SUSPICIOUS ACTIVITY": Warrants a closer look.
• Red — "CRITICAL ISSUES": Immediate investigation needed.

Viewing Past Sessions

Every scan is saved automatically. To review:

1. Choose option 4 (View Sessions) from the menu.
2. Pick a session from the list.
3. Choose: Summary, HTML Map, Export, or Delete.

zpk.exe sessions

Exporting Reports

1. Choose option 6 (Export Session) from the menu.
2. Pick a session and format:

Format	Best for
PDF	Client deliverables, printing, emailing
Markdown	Readable text with tables
JSON	Programmatic processing, integrations
CSV	Spreadsheets (Excel, Google Sheets)
TXT	Pasting into emails or tickets

HTML Map

1. Choose option 5 (View Map) from the menu.
2. Pick a session. An interactive map opens in your browser.

• Green dot — Your location
• Cyan markers — 1-2 connections
• Yellow/orange — 3-9 connections
• Red — 10+ connections

Hover over any marker to see city, country, organization, and connection count.

AI Analysis (Optional)

ZPK can use a local AI model to assess your scan and give plain-English results. Everything runs on your machine — no cloud, no API keys.

What you need

• Ollama — free tool that runs AI models locally (~200 MB installer)
• A GPU with enough VRAM, or system RAM for CPU mode (slower)

Recommended models

Your hardware	Model	Download
GPU 8-12 GB VRAM (RTX 3060/4060/4070)	qwen3:8b	~5 GB
GPU 6 GB or less	qwen3:4b	~2.5 GB
No GPU, 16 GB+ RAM	qwen3:4b	~2.5 GB
No GPU, 8 GB RAM	gemma3:1b	~1 GB

Setup

1. Install Ollama from ollama.com.
2. Open a terminal and download a model:
   

   ollama pull qwen3:8b

3. Done. ZPK connects to Ollama automatically.

Running analysis

Choose option 9 from the menu, or run:

zpk.exe analyze

The AI returns a color-coded assessment: risk level, concerns, normal traffic, actions to take, and a one-line summary.

Alerts Setup (Optional)

Get notified via Slack or email when ZPK finds something suspicious. Alerts fire automatically after each scan.

Config file

Create a config file by running:

zpk.exe config

This creates config.toml at C:\Users\YourName\.zpk\.

Slack alerts

1. Go to api.slack.com/apps and create a new app.
2. Enable Incoming Webhooks and add one to your channel.
3. Copy the webhook URL and add to your config:

[alerts]
slack_webhook = "https://hooks.slack.com/services/YOUR/WEBHOOK/URL-HERE"

Gmail alerts

1. Enable App Passwords in your Google account (requires 2FA).
2. Create an app password for "ZPK."
3. Add to your config:

[alerts]
email_to = "you@gmail.com"
email_from = "you@gmail.com"
smtp_host = "smtp.gmail.com"
smtp_port = 587
smtp_user = "you@gmail.com"
smtp_pass = "your-app-password-here"

Configuration

ZPK works with sensible defaults. To customize:

zpk.exe config          # create default config
zpk.exe config --edit   # open in Notepad

Common customizations

Allowlist trusted hosts:

[allowlist]
hosts = ["192.168.1.1", "192.168.1.254"]
ports = [53, 80, 443, 8080]

Adjust sensitivity:

[thresholds]
dns_failure_count = 10
high_fanout_hosts = 50
large_egress_bytes = 10000000

Set your map location:

[location]
lat = 40.7128
lon = -74.0060
city = "New York"

Command Reference

Run zpk.exe with no arguments for the interactive menu, or use commands directly:

Command	Description
run	Capture and analyze network traffic
live	Capture with per-packet output
sessions	Browse saved sessions
summary	Show report from a saved session
export	Export to PDF, JSON, CSV, Markdown, TXT
import	Analyze a .pcap file
map	World map of connections (--html for browser)
analyze	AI security assessment via Ollama
history	Trends across sessions
diff	Compare two sessions
baseline	Save or compare traffic baseline
schedule	Periodic captures via Task Scheduler
explain	Show all risk tags
setup	Install Npcap
interfaces	List network interfaces
config	View/edit configuration
geoip-update	Download GeoIP databases
cleanup	Remove temp files
uninstall	Remove Npcap and ZPK data

Useful examples

zpk.exe run --duration 60 --geoip              # 60 second scan with GeoIP
zpk.exe run --preset suspicious --duration 120  # Sensitive mode
zpk.exe run --dns-only --duration 60            # DNS traffic only
zpk.exe run --host 192.168.1.100 --duration 60  # Watch specific host
zpk.exe run --external-only --geoip -d 60       # External connections only

Troubleshooting

"Npcap not detected"

• Install Npcap via menu option 8, or download from npcap.com.
• Check "WinPcap API-compatible mode" during install.
• Restart your terminal after installation.
• Make sure you're running as Administrator.

No packets captured (0 packets)

• Run terminal as Administrator.
• Close other capture tools (Wireshark) that may lock the interface.
• Try: zpk.exe interfaces then zpk.exe run --interface "Ethernet"

GeoIP download fails

• DNS-level ad blockers (Pi-hole, AdGuard) may block the download. Temporarily disable and retry.
• Scans work fine without GeoIP — you just won't see maps or location data.

SmartScreen blocks zpk.exe

Click "More info" then "Run anyway." This only happens once.

AI says "Ollama not found"

• Install Ollama from ollama.com.
• Check the system tray for the Ollama icon.
• Restart your terminal after installing.

Too many false positives

• Add trusted hosts to your allowlist: zpk.exe config --edit
• Use the --preset health flag for balanced thresholds.