fluffy-barnacle - Disposable, ephemeral network infrastructure power

项目说明

<p align="center">
<img src="docs/assets/logo.png" alt="fluffy-barnacle" width="280">
</p>

<h1 align="center">Fluffy-Barnacle</h1>

<p align="center">
<b>Disposable, ephemeral network infrastructure powered by GitHub Codespaces.</b><br>
Deploy SOCKS5 proxies, HTTPS file hosting, and WireGuard tunnels in seconds, for free.
</p>

<p align="center">
<img src=" alt="Python 3.10+">
<a href="LICENSE"><img src=" alt="Apache 2.0 License"></a>
<a href=" src=" alt="Code style: black"></a>
</p>

---
> [!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. excessi, proxy/CDN-like usage).
> - Any activity 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.

Documentation

Full documentation at

What is 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 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 |
| cs-mcp | Model Context Protocol ser the toolkit to MCP-aware clients (Claude Desktop, Claude Code, Cursor) |

Codespace IPs rotate on each creation, giving you fresh egress IPs on demand. Each tool works from the CLI or as a Python library.

Quick Start

See the Quick Start Guide for detailed setup.

Feature Highlights

SOCKS5 Proxy with Auto-Reconnect & Circuit Breaker

Terminal UI (cs-tui)

A li dashboard for monitoring and managing tunnels, codespaces,
diagnostics, and logs — built on Textual. It
reads the same state and drives the same service layer as the CLI, and
auto-refreshes.

!cs-tui dashboard

The tabs — Tunnels, Codespaces, Chains, Diagnostics, Logs —
each carry their own selectable rows. All blocking work runs in a background
worker, so the UI ne while a gh/ssh call is in flight.

Actions operate on the selected row of the active tab (destructive ones ask for
confirmation first):

| Key | Action |
|-----|--------|
| r | Refresh now |
| c | Create a codespace (Codespaces tab; prompts for owner/repo) |
| s | Start the selected codespace / chain |
| x | Stop the selected tunnel / codespace / chain (confirm) |
| d | Drain the selected tunnel |
| o | Show a healthy tunnel port (rotate) |
| Del | Delete the selected codespace / chain definition (confirm) |
| q | Quit |

On the Codespaces tab, c opens an input modal to create a new codespace.
It is prefilled with github/codespaces-blank (o the default via the
codespace_repo config key); type any owner/repo and press Enter to pro
it in the background.

!cs-tui create codespace

The Chains tab lists defined and running two-hop chains; each hop shows its
region and, when bound to a named account, the account that PAT belongs to
(e.g. WestEurope · work) so multi-account setups are clear at a glance.

Adding a second proxy:

There are two workflows for running multiple exit IPs:

1. Auto-add: Run cs-proxy start again when a proxy is already running — it creates a new codespace and starts a second tunnel automatically.
2. Manual: Run cs-proxy create to create a codespace first, then cs-proxy start to tunnel it (skips the first running tunnel and starts one for the new codespace).

Dry-run mode:

Shell completion:

Smart Proxy Rotation

cs-tools automatically picks a healthy tunnel from state.json. If you ha tunnels running, tool traffic is rotated across them without manual port selection.

Two-Hop Codespaces Chains

Experimental chain mode routes one local SOCKS endpoint through two Codespaces:

The 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:

Raw PATs are intentionally not accepted as command arguments.

Public File Hosting

WireGuard VPN

Proxied Tool Wrappers

cs-tools supports global flags before the tool name:

pnmap 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.

Installation

Requirements: Python 3.10+, GitHub CLI (gh), ssh, curl

Optional dependencies for specific features:

See the Installation Guide for platform-specific instructions.

Python API

Configuration

Config file: ~/.config/cs-proxy/config.yaml

See the Configuration Reference for all options, en , and profiles.

License

Apache-2.0

项目信息

开发语言：Python

Star 数：127

技术要点

该项目属于红蓝攻防方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Disposable, ephemeral network infrastructure powered by GitHub Codespaces.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。