Usage Guide

Usage Guide

Bull works two ways: an interactive TUI menu, and a direct CLI. Both call the same underlying functions, so anything you can do in the menu you can script.

sudo ./bull.sh            # interactive menu
sudo ./bull.sh <command>  # direct CLI

Bull must run as root (it manages the hypervisor, iptables, and encrypted storage). After bull init you can use the bull alias.

Creating a VM

sudo bull create kali-lab --os kali --ram 4096 --cpu 2 --resolution 2560x1440

What happens:

1. Bull resolves the username (your --username, or the OS default such as kali).
2. It resolves the password (see below), then generates the Vagrantfile and boots the box.
3. Provisioning runs inside the VM as root: it creates your user, encrypts /home with ecryptfs, sets the keyboard layout and resolution, locks the default OS accounts, and applies hardening.
4. The password is encrypted with GPG and stored on the host, never in plaintext.
5. If you have saved toolkits, Bull offers to install them.
6. The VM is recorded in the inventory.

Passwords

Bull never wants a password on the command line if it can avoid it. In order of preference:

Method	Behavior
(nothing)	Bull generates a strong 24-char password. Reveal it later with bull show-pass <name>.
--password-file <path>	Reads the first line, then wipes the file (one-time use).
--password <pass>	Deprecated — visible in ps aux. Avoid.

Reveal a stored password at any time:

sudo bull show-pass kali-lab

Create options

Option	Default	Meaning
--os <kali|parrot>	kali	Guest OS
--ram <MB>	4096	Memory
--cpu <N>	2	vCPUs
--resolution <WxH>	1920x1080	Display resolution (prompted if omitted)
--username <user>	OS default	Login user inside the VM
--password-file <path>	—	Read password from a file (then wiped)
--keyboard <layout>	prompted	Keyboard layout (us, fr, de, …)

Parrot OS downloads a ~9 GB OVA on first use. Budget time and disk accordingly.

Lifecycle

sudo bull list                 # all VMs and their status
sudo bull start kali-lab       # boot
sudo bull stop kali-lab        # graceful halt
sudo bull connect kali-lab     # SSH in
sudo bull view kali-lab        # open the graphical console (alias: gui)
sudo bull destroy kali-lab     # remove permanently (irreversible, asks to confirm)

Snapshots

Take a snapshot before anything risky, then roll back if it goes wrong:

sudo bull snapshot kali-lab pre-exploit
# ... do something destructive ...
sudo bull restore kali-lab pre-exploit

The label is optional on snapshot (a timestamped one is generated) but required on restore.

VPN with kill switch

Route the VM's traffic through OpenVPN or WireGuard, and drop everything that is not the tunnel:

sudo bull vpn kali-lab ~/vpn/config.ovpn

Bull auto-detects OpenVPN vs WireGuard, installs the client inside the VM, brings the tunnel up, and applies an iptables kill switch. Verify after connecting:

sudo bull connect kali-lab
curl ifconfig.me      # should show the VPN exit IP

Details in VPN and Kill Switch.

Toolkits

Install a security tool from a Git URL onto a running VM:

sudo bull toolkit kali-lab https://github.com/owner/tool.git

Save tools to the registry so every new VM can get them automatically. See Toolkit Manager.

Inventory housekeeping

sudo bull status   # global overview
sudo bull sync     # reconcile the inventory with the hypervisor's real state

Use sync if a VM was changed outside Bull (e.g. stopped directly via virsh or VBoxManage).

For the exhaustive flag-by-flag list, see the CLI Reference.