Disposable, ephemeral network infrastructure powered by GitHub Codespaces.
Deploy SOCKS5 proxies, HTTPS file hosting, and WireGuard tunnels in seconds, for free.
Warning
This software is provided strictly for educational, research, and authorized security testing purposes.
GitHub's Terms of Service and Acceptable Use Policies explicitly prohibit certain uses of Codespaces, including:
- Using Codespaces to disrupt services, gain unauthorized access to networks/devices, or support attack infrastructure (see GitHub Terms for Additional Products and Features - Codespaces section).
- Placing disproportionate burden on GitHub's servers (e.g. excessive bandwidth, proxy/CDN-like usage).
- Any activity violating applicable laws, third-party rights, or GitHub's Acceptable Use Policies (e.g. unauthorized scanning, proxying for malicious purposes).
Misuse may result in suspension/termination of your GitHub account, Codespaces access restrictions, or other enforcement actions by GitHub. The author is not liable for any harm or damage resulting from its unauthorized use.
Full documentation at https://dstours.github.io/fluffy-barnacle/
Fluffy-Barnacle is an operator-focused toolkit that turns GitHub Codespaces into free, ephemeral network infrastructure. It provides a suite of CLI tools for rapid deployment and teardown.
| Tool | Description |
|---|---|
| cs-proxy | SOCKS5 and HTTP proxy via SSH tunnel with auto-reconnect, circuit breaker, and Burp Suite integration |
| cs-serve | Instant public HTTPS file hosting, redirect servers, custom HTTP responses, and data capture via *.app.github.dev |
| cs-wg | Full WireGuard VPN tunnel with route management and traffic monitoring |
| cs-tools | Drop-in wrappers for nmap, ffuf, httpx, nuclei, sqlmap with automatic SOCKS5 proxy arguments and smart tunnel rotation |
Codespace IPs rotate on each creation, giving you fresh egress IPs on demand. Each tool works from the CLI or as a Python library.
pip install -e .
gh auth login
cs-proxy check # verify your setup
cs-proxy start
cs-tools ipcheck # verify you're proxiedSee the Quick Start Guide for detailed setup.
cs-proxy start # single proxy, auto-select codespace
cs-proxy start # (if already running) adds another codespace + tunnel
cs-proxy create # create a new codespace and track it
cs-proxy start # picks up unstarted tracked codespaces
cs-proxy -n 2 start -l WestEurope -l EastUs # two proxies, different regions (ports 1080 + 1081)
cs-proxy status # codespace state + per-tunnel exit IP
cs-proxy status --watch # auto-refresh every 2 seconds
cs-proxy doctor --fix # diagnose and repair safe local state/config issues
cs-proxy pool list # list managed tunnel pool entries
cs-proxy pool rotate # print a healthy tunnel port for scripts
cs-proxy ssh # interactive shell (menu if multiple codespaces tracked)
cs-proxy env # export statements for tools that read env vars
cs-proxy burp # upstream proxy config for Burp Suite
cs-proxy pac # generate Proxy Auto-Config (PAC) file
cs-proxy chain create eu-us --hop WestEurope --hop EastUs
cs-proxy chain start eu-us # local SOCKS -> EU Codespace -> US Codespace
cs-proxy check # diagnose setup, auth, ports, and state healthAdding a second proxy:
There are two workflows for running multiple exit IPs:
- Auto-add: Run
cs-proxy startagain when a proxy is already running — it creates a new codespace and starts a second tunnel automatically. - Manual: Run
cs-proxy createto create a codespace first, thencs-proxy startto tunnel it (skips the first running tunnel and starts one for the new codespace).
Dry-run mode:
cs-proxy --dry-run start # show what would happen without making changes
cs-proxy --dry-run stop # show what would stop without stopping anythingShell completion:
cs-proxy completion bash > ~/.config/cs-proxy/completion.bash
source ~/.config/cs-proxy/completion.bashcs-tools automatically picks a healthy tunnel from state.json. If you have multiple tunnels running, tool traffic is rotated across them without manual port selection.
Experimental chain mode routes one local SOCKS endpoint through two Codespaces:
cs-proxy chain create eu-us --hop WestEurope --hop EastUs
cs-proxy chain start eu-us --port 1080
cs-proxy chain status eu-us
cs-proxy chain stop eu-usThe first hop runs a SOCKS relay and the second hop runs a WebSocket exit relay. Chain mode is intended for authorized testing of region-specific routing behavior and adds latency.
Named accounts can be used when each hop should be managed with a different PAT:
export GH_TOKEN_EU=...
export GH_TOKEN_US=...
cs-proxy account add eu --token-env GH_TOKEN_EU
cs-proxy account add us --token-env GH_TOKEN_US
cs-proxy chain create eu-us --hop eu:WestEurope --hop us:EastUsRaw PATs are intentionally not accepted as command arguments.
cs-serve file payload.bin # serve a file
cs-serve redirect http://169.254.169.254/metadata/ # SSRF redirect
cs-serve custom 9999 '{"pwned":true}' application/json # custom response
cs-serve capture # capture POST data
cs-serve -d dev.example.com file payload.bin # custom domain via Cloudflarecs-wg up
cs-wg route add 192.168.10.0/24 # route a specific subnet
cs-wg route all # route everything
cs-wg monitor http # tcpdump with labeled output
cs-wg downcs-tools ipcheck
cs-tools pnmap -p 80,443,8080 target.com
cs-tools pffuf -u https://target.com/FUZZ -w list.txt
cs-tools phttpx -l domains.txt -title -status-code
cs-tools pcs gobuster dir -u https://target.com -w list.txtcs-tools supports global flags before the tool name:
cs-tools --port 1081 pcurl https://target.com # pin to a specific tunnel
cs-tools --dry-run pnmap -p 80 target.com # preview the command
cs-tools --timeout 900 pnmap -sV -p- target.com # override default timeoutpnmap automatically sanitizes nmap arguments — it strips incompatible flags (-sS, -sU, -O, --traceroute) and forces -sT -Pn to keep traffic inside the SOCKS tunnel. Running nmap as root would default to SYN scan and leak your real IP; cs-tools prevents this.
Requirements: Python 3.10+, GitHub CLI (gh), ssh, curl
git clone https://github.com/dstours/fluffy-barnacle.git
cd fluffy-barnacle
pip install -e .Optional dependencies for specific features:
wg,wg-quick,socat,ip-- forcs-wgproxychains4,tinyproxy-- forcs-proxy proxychains/cs-proxy httptcpdump-- forcs-wg monitor
See the Installation Guide for platform-specific instructions.
from csproxy import SSHTunnel, Config, GitHubManager, CodespaceSelector, GitHubAccount
config = Config()
gh = GitHubManager()
cs_name = CodespaceSelector(gh, config).select()
tunnel = SSHTunnel(config, cs_name)
tunnel.start()
from csproxy import check_proxy, ipcheck, pnmap
if check_proxy():
ipcheck()
pnmap(['-p', '80,443', 'target.com'])Config file: ~/.config/cs-proxy/config.yaml
socks_port: 1080
http_proxy_port: 8080
num_proxies: 1 # 1-2 on free tier; each gets its own tunnel on consecutive ports
codespace_name: ""
locations: [] # e.g. [WestEurope, EastUs] — one region per codespace
reconnect_delay: 5
max_reconnect_delay: 300
verbose: false
# Named accounts store token environment variable names, not token values.
accounts:
eu:
token_env: GH_TOKEN_EU
us:
token_env: GH_TOKEN_US
# Chain definitions are usually managed with `cs-proxy chain create`.
chains: {}
# Profiles let you switch between preset configurations
profile: ""
profiles:
redteam:
num_proxies: 2
locations: [WestEurope, EastUs]
stealth:
dns_proxy: true
verbose: trueSee the Configuration Reference for all options, environment variables, and profiles.