Scripts reference

The Scripts USB at a glance

The Scripts USB is a virtual disk SecVF builds on demand. It packages the scripts from scripts/ in the repo, creates an HFS+ disk image, and attaches it to a chosen guest as a USB device. The guest mounts it, runs whatever it needs, then ejects.

scripts/                              # in the SecVF repo
├── README.md                          # this is summarized below
├── kali-router-setup.sh               # primary router setup
├── kali-fakenet-setup.sh              # FakeNet on top of router
├── kali-disable-sleep.sh              # keep router VMs awake
├── macos-network-setup.sh             # host-side network config
├── provision-macos-vm.sh              # AI sandbox base bundle setup
├── test_virtual_switch.sh             # diagnostic
├── build-release.sh                   # release builder (host-only)
├── generate-icon.swift                # icon generator (build tooling)
└── writemon.d/                        # (reserved — write-monitor DTrace probes)

How to deliver a script to a guest

Two paths:

1. Scripts USB (GUI): VM Library → right-click VM → Mount Scripts USB…. SecVF builds a fresh image and attaches it. Inside the guest, mount and run.
2. CLI: secvf usb create-virtual --name secvf-scripts --size 64 --format dmg --source ./scripts && secvf usb mount secvf-scripts --to <vm>.

From inside any Linux guest after mount:

sudo mount /dev/sdb1 /mnt                       # mount point varies
cd /mnt
ls                                              # see all scripts
sudo bash <script-name>

kali-router-setup.sh

Purpose

Converts a clean Kali Linux VM into the analysis lab's router. Configures static IP, IP forwarding, DHCP, DNS, iptables, traffic-analysis tooling, and installs the three helper commands (secvf-status, secvf-monitor, secvf-capture).

When to run

• First time: immediately after installing a fresh Kali VM that you intend to use as the router.
• After reset: if the router VM gets in a weird state and you'd rather rebuild from a clean Kali than untangle it.
• Idempotent: safe to re-run — it skips parts already done and re-applies anything that drifted.

What it changes

• Sets static IP 10.0.100.1/24 on eth0 via /etc/network/interfaces.d/eth0
• Enables IP forwarding in /etc/sysctl.d/99-secvf.conf
• Installs isc-dhcp-server + config, dnsmasq + config
• Installs analysis tools: tcpdump, tshark, wireshark, nmap, netcat, socat, ettercap, dsniff, arpwatch, iftop, nethogs, vnstat, bettercap, suricata, zeek
• Writes iptables rules to /etc/iptables/rules.v4 and enables netfilter-persistent
• Creates /etc/secvf-router.conf with detected interface name (used by the FakeNet script)
• Drops the three helper scripts in /usr/local/bin/
• Creates /var/captures/ for packet captures
• Writes setup log to /var/log/secvf-router-setup.log

Usage

sudo /mnt/kali-router-setup.sh
# Then reboot — required for the network changes to take cleanly.
sudo reboot

Recovery / rollback

The script has no dedicated --undo. To revert: re-create the VM from a clean Kali ISO (cheapest path), or manually undo each section (apt-get remove, restore /etc/network/interfaces.d/eth0, etc.). Always snapshot the VM before running for the first time so you can roll back the whole bundle if needed.

kali-fakenet-setup.sh

Purpose

Layers FakeNet honeypot capability on top of an already-router-configured Kali VM. All DNS resolves to the router; HTTP/HTTPS/FTP/SMTP/IRC/POP3 are answered by fake services.

Prerequisite

Must run kali-router-setup.sh first — it consumes /etc/secvf-router.conf for the interface name.

When to run

• When you need offline malware behaviour capture — see FakeNet.
• When you want to reveal hidden C2 infrastructure (see Traffic analysis).

What it changes

• Replaces /etc/dnsmasq.conf with a wildcard-A-record sinkhole config
• Adds an nginx server block at /etc/nginx/sites-available/fakenet on ports 80 + 443
• Generates a self-signed CA in /etc/ssl/fakenet/
• Configures sslsplit as a transparent TLS MITM
• Configures inetsim for FTP/SMTP/POP3/IRC/NTP/daytime/discard/quotd
• Adds iptables PREROUTING redirects to capture outbound 80/443 → mitm
• Creates /var/log/fakenet/ with logrotate config
• Modes: start (default), stop, status — the script is its own toggle

Usage

sudo /mnt/kali-fakenet-setup.sh start    # activate FakeNet
sudo /mnt/kali-fakenet-setup.sh stop     # restore live-internet routing
sudo /mnt/kali-fakenet-setup.sh status   # show what's running

Recovery / rollback

Use stop — it restores the saved /etc/dnsmasq.conf.orig and flushes the iptables NAT PREROUTING chain. Cleaner approach: keep two router bundles (live and FakeNet) and switch lab gateways via VM Library.

kali-disable-sleep.sh

Purpose

Disables every sleep, lock-screen, screen-blanking, and DPMS pathway on a Kali Linux VM. Without this, a long-running router VM can lock its screen mid-analysis and obscure logs you wanted to glance at.

When to run

• On the router VM if you're going to leave it running unattended (overnight detonations, multi-hour beacon studies).
• On any analysis VM where you need the desktop visible at all times for ongoing observation.
• Not needed for headless or short-session VMs.

What it changes

• systemctl mask sleep.target suspend.target hibernate.target hybrid-sleep.target
• setterm -blank 0 -powerdown 0 + persistent consoleblank=0 kernel param via grub
• Writes /etc/X11/xorg.conf.d/10-no-blanking.conf for X11 DPMS-off
• Disables gnome-screensaver / lock-on-suspend if GNOME is installed
• Reverses the autosuspend USB power management

Usage

sudo /mnt/kali-disable-sleep.sh
# Reboot to make the grub change take effect for the console blank.
sudo reboot

Recovery / rollback

To undo: sudo systemctl unmask sleep.target suspend.target hibernate.target hybrid-sleep.target, remove /etc/X11/xorg.conf.d/10-no-blanking.conf, edit /etc/default/grub to remove consoleblank=0, update-grub, reboot.

macos-network-setup.sh

Purpose

Configures the host macOS network interface to participate in the SecVF virtual network. Sets a static IP, configures DNS pointing at the Kali router, and verifies the configuration.

When to run

• Only when the host itself needs a presence on the analysis lab's subnet — e.g. running an inspection tool on the host that needs to reach a lab VM directly.
• Skip in normal use. SecVF's switch is intra-VM; the host doesn't usually need to be on it.

What it changes

• Sets manual IP on the host's primary network service: networksetup -setmanual
• Sets DNS to the router IP: networksetup -setdnsservers
• Defaults to 10.0.100.50/24 with gateway 10.0.100.1; override via first argument

Usage

# Run on the HOST (not in a VM). Requires sudo.
sudo /Users/me/SecVF/scripts/macos-network-setup.sh                # uses default IP
sudo /Users/me/SecVF/scripts/macos-network-setup.sh 10.0.100.99    # custom IP

Recovery / rollback

# Restore DHCP on the host's primary service
sudo networksetup -setdhcp Wi-Fi
# or
sudo networksetup -setdhcp Ethernet

provision-macos-vm.sh

Purpose

Sets up the AI sandbox base bundle. Runs inside a fresh macOS guest VM after the framework's installer finishes, before the bundle is frozen as the canonical base for cloning.

This is the only script that ships with the macOS guest provisioner — it's not on the Scripts USB by default; SecVF mounts it during base-bundle build via vsock.

When to run

Only once per base bundle generation. SecVF runs this automatically as part of the AI sandbox install flow. You only invoke it manually if you're rebuilding a base bundle or debugging the provisioning steps.

What it changes (inside the guest)

• Sets SIP flags for ESF / DTrace — does not fully disable SIP
• Disables Spotlight, Time Machine, telemetry, push notifications
• Installs Homebrew + Node.js 22
• Installs the AI agent runtime (Claude Code CLI) with a staged-tarball fallback if network is restricted
• Creates the agent non-admin user with workspace-only write access
• Configures VirtioFS mount points at /workspace and /sessions-ro
• Starts the vsock exec agent on port 2222 (the host-to-guest command channel)
• Installs DTrace probes + an ESF helper for syscall tracing
• Writes provision manifest at /var/db/secvf-provision.json

Usage

# Inside the macOS guest, manually (only during base build):
sudo /var/run/secvf/provision-macos-vm.sh

# Idempotent — re-running validates and refreshes anything stale.

Recovery / rollback

Don't rollback a session bundle — destroy it and clone fresh from the base. For the base bundle itself: if provisioning gets stuck, rebuild from IPSW (the bundle keeps the original IPSW, so this is reasonably fast).

test_virtual_switch.sh

Purpose

End-to-end smoke test for the host-side VirtualNetworkSwitch. Useful when troubleshooting network issues that smell host-side rather than guest-side.

When to run

• VMs can't talk to each other even on the same virtual switch.
• Switch Statistics shows zero forwarding.
• Network logs aren't being written.
• Before opening an issue on GitHub — include the output.

What it checks

• Socket directory exists: ~/.avf/sockets/
• Network log file is being written: ~/.avf/logs/network-YYYY-MM-DD.log
• Per-VM socket count under ~/.avf/sockets/vm-*.sock
• Recent log entries (tail of the network log)

Usage

# On the host. No sudo.
bash scripts/test_virtual_switch.sh

Output interpretation

• All PASS: switch is healthy. Issue is somewhere else.
• Socket dir missing: SecVF has never started the switch — check the app is running and at least one VM is on Virtual or Router mode.
• Log file missing: the switch is running but logging is disabled or the logs directory has permission issues.
• Zero connected VMs but VMs are running: guest's virtio-net failed to attach. Check ~/.avf/logs/error-audit.log.

build-release.sh

Purpose

Builds a signed, archived release of SecVF for direct distribution. Handles version increment, archive, export, and notarisation prep.

When to run

Only when cutting a release. You don't need this for everyday development.

What it does

• Reads MARKETING_VERSION and CURRENT_PROJECT_VERSION from SecVF.xcodeproj
• Increments the build number (or marketing version if specified)
• Runs xcodebuild archive into build/SecVF.xcarchive
• Exports the .app bundle into build/Release/
• Codesigns with the Developer ID identity in the build settings
• Prepares a .dmg wrapper for upload

Usage

cd ~/Code/SecVF
./scripts/build-release.sh              # increments build number
./scripts/build-release.sh --version 1.2.0   # bumps marketing version

Helper commands installed by the router setup

These three commands live in /usr/local/bin/ on the router VM after kali-router-setup.sh runs. They're documented in detail on the Router VM page; quick reference here:

Config files written

Quick reference for "where did setup put this":