Metadata-Version: 2.5
Name: malvbox
Version: 2.1.0
Summary: Offensive-security container CLI wired to a WireGuard or OpenVPN tunnel
License-Expression: MIT
Keywords: docker,offensive-security,openvpn,pentest,wireguard
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# malvbox

An all-in-one offensive-security container, wired straight to your VPN —
**WireGuard** (the **malveillance** platform) or **OpenVPN** (TryHackMe, Hack The
Box, any lab). Name it, launch it, work — in a single command.

## Install

```bash
pipx install malvbox
```

**Requirements:** Docker and bash (already present on Linux/WSL/macOS). The
`wireguard` kernel module is only needed for WireGuard configs — OpenVPN runs in
user space.

The package ships only the launcher. The full toolset (Kali + wordlists +
privesc scripts + a large curated tool set) lives in the Docker image
`ghcr.io/loicosternaud/malvbox:default`, pulled automatically on first run.

## Use

```bash
# 1. Grab your VPN config: malveillance profile (.conf) or the lab's
#    "Download VPN" button on TryHackMe / Hack The Box (.ovpn)
# 2. Launch a named box, plugged into the VPN, sharing a folder:
malvbox start redteam --vpn ~/malveillance.conf -s ~/share
malvbox start htb     --vpn ~/lab_loic.ovpn
```

The format is detected from the file — WireGuard and OpenVPN take the same flag.
Add `--vpn-auth <file>` for a lab asking for a login (2 lines: user, password),
`--full-tunnel` to push all of the box's traffic through the VPN.

Inside the box:

```bash
malvbox-vpn-status     # tunnel state, whichever VPN is in use
ip a show wg           # WireGuard address (tun0 with OpenVPN)
nmap -sn 10.13.0.0/24  # the target range
firefox                # opens on your screen (FoxyProxy preset for Burp/Caido)
```

Graphical tools display on your screen automatically. Your `~/work` folder is a
persistent volume that survives restarts.

## Commands

| Command | What it does |
|---|---|
| `malvbox start <name>` | create the box (or reopen it) and drop into a shell |
| `malvbox exec <name> <cmd…>` | run a command without opening a shell |
| `malvbox update <name>` | pull the latest image and recreate the box |
| `malvbox info <name>` | show a box's status and mounts |
| `malvbox list` | list boxes and their state |
| `malvbox stop <name>` | stop a box (workspace kept) |
| `malvbox rm <name> --purge` | remove a box and its workspace |
