StarHub Kit

Zero-dependency declarative compiler and native stdio MCP server for AI coding agent sandbox firewalls (nftables, macOS pf, Tailscale ACL) and Sing-box/Mihomo QUIC mesh routing.

文档

StarHub Kit (starhub-kit)

OpenSSF Best Practices OpenSSF Scorecard SLSA 3 License: MIT

Language: English | 简体中文 (Simplified Chinese)
Version: v1.3.0 · Runtime: Python 3.9+ (Zero Third-Party Dependencies) · MCP: starhub mcp (stdio) · Nix: flake.nix · Assurance: OpenSSF Silver (#16658) + OSPS Baseline L3

StarHub Kit is a zero-dependency AI Agent sandbox firewall & cross-platform network policy compiler for Linux nftables/iptables, macOS Packet Filter (pf), official Tailscale ACL JSON, Sing-box / Mihomo split-DNS & surgical QUIC (UDP/443) governance, and multi-site 100.x + 4via6 mesh routing — with a built-in Model Context Protocol (MCP) server.

Prevent autonomous coding agents (Claude Code, Codex, OpenHands, Cursor, Docker MCP containers) from scanning your RFC 1918 LAN or reaching :22 SSH / :5432 Postgres / :6379 Redis, eliminate hotel Wi-Fi subnet collisions, and cure mobile QUIC blackholes from one declarative JSON topology (STARHUB_GROUND_TRUTH.json).

StarHub Kit 15-Second Zero-Root Terminal Demo

Try in 10 Seconds (Zero Root, Zero Disk Writes)

# Option A — One-command install via official Homebrew tap (macOS & Linuxbrew)
brew install Ziqi/tap/starhub-kit
starhub render --profile ai-sandbox --target tailscale-acl --dry-run
starhub render --profile ai-sandbox --target macos-pf --dry-run
starhub render --profile ai-sandbox --target nftables --dry-run

# Option B — Preview Sing-box or Mihomo split-DNS & surgical QUIC rulesets directly to stdout
git clone https://github.com/Ziqi/starhub-kit.git && cd starhub-kit
./bin/starhub render --target singbox --dry-run
./bin/starhub render --profile minimal --only mihomo --dry-run

# Option C — Mount directly in Claude Desktop / Cursor / Windsurf as a zero-dependency MCP Server
# Add to mcpServers: { "starhub": { "command": "starhub", "args": ["mcp"] } }
nix run github:Ziqi/starhub-kit -- audit --profile ai-sandbox

Why StarHub Kit? (4 Real-World Infrastructure Pain Points Solved)

Pain Point in Typical Homelab / Multi-Site SetupsStarHub Declarative Engineering Architecture
1. Hotel / Coffee-Shop Wi-Fi Subnet Collisions
Advertising raw /24 or /32 RFC 1918 LAN routes over Tailscale breaks local gateway routing whenever remote Wi-Fi shares the same LAN prefix.
Zero-Collision Native 100.x + 4via6
Containers run native tailscale0 (100.64.0.0/10); non-Tailscale hypervisors use Tailscale 4via6 IPv6 translation (2001:db8:4a6::10 pattern) with STARHUB-IPV6-EXIT-GUARD blocking IPv6 leaks.
2. Cross-Border Proxy Stalls & QUIC Blackholes
Blind DNS fallback: racing causes hundreds of half-open TLS context canceled drops per day; Apple Media DRM and mobile Gmail inline attachments hang 50s on dead XUDP UDP/443, while global UDP/443 REJECT breaks YouTube Cronet subtitles.
Deterministic Split-DNS + Top-Ordered (Section 9a) QUIC Governance
Zero fallback: racing (nameserver-policy only) + top-ordered surgical UDP/443 REJECT for Apple Media and mobile Gmail/attachment endpoints (placed above broad Google proxy rules), with automated YouTube Cronet zero-collateral assertions.
3. Cloud AI Agent Split-Brain & Lateral Movement Risk
Multiple cloud AI sandboxes sharing a Tailscale state file collide on NodeKey/HomeDERP, or gain dangerous :22 SSH / Docker access to internal hosts.
Restricted Cloud Sandbox Guest Pass (B2 Pattern)
Per-instance /tmp/tailscale-<id> isolation (agent-tailscale-bootstrap.sh) + dual-stack STARHUB-BOT-NOSSH / NOSSH6 chains that allow Web APIs (:3001/:8080) while hard-dropping TCP :22 SSH.
4. Documentation Sprawl, Drift & Accidental PII / Inventory Leaks
Dozens of stale .md files contradict live firewall/proxy configs, and AI coding agents hallucinate retired IPs or leak personal hardware inventory when open-sourcing.
Unified Governance (EGM 3.0: 1 Core + 6 Books + 2 Ledgers)
Unified AGENTS.md (CLAUDE.md / GROK.md symlinks), strict Markdown whitelist, compiler parity gate (render --check), and a mathematical Zero-PII & Zero-Inventory Release Sanitizer (--verify-public-export).

Architecture Overview

flowchart LR
    subgraph Controllers["Controllers & Cloud Sandboxes"]
        LAP["Primary Controller (laptop)<br/>127.0.0.1:17890 Adaptive Tunnel"]
        WS["Compute Workstation (workstation)<br/>Dedicated VPS2 + Host Firewall Isolation"]
        BOT["Cloud AI Agent Pool (B2)<br/>Isolated /tmp/tailscale-id"]
    end

    subgraph Core["Site-A Core Cluster (Proxmox VE)"]
        GW["gw (LXC 100 · .11 + .12 VIP)<br/>Mihomo gvisor TUN + Split-DNS<br/>Cam-Gate + IPv6 Exit Guard"]
        PAN["panel (LXC 102 · .15:3001)<br/>16 Probes + Zero-Drift Doctor<br/>STARHUB-DASH-ACL + BOT-NOSSH"]
        HOM["home (LXC 103 · .20:8080)<br/>Smart Home & AI Hub<br/>STARHUB-HOME-ACL + BOT-NOSSH"]
    end

    subgraph Relay["Out-of-Band Bastion & Egress"]
        DERP["Custom DERP + Lifeline Bastion<br/>:8443 + STUN :3478 + 127.0.0.1:2201..2204"]
        VPS["VLESS-Reality Egress Fleet<br/>VPS1 / VPS2 / VPS3 (bbr + fq)"]
    end

    LAP & WS -->|"Native 100.x / Dual-Stack Allowlist"| GW & PAN & HOM
    BOT -->|"HTTP :3001/:8080 ONLY (:22 Hard DROP)"| PAN & HOM
    GW & WS -->|"Anti-Loop Direct Exemption"| VPS
    GW & WS -.->|"Reverse SSH Lifeline (:2203/:2204)"| DERP

Choose Your Adoption Tier (30 Seconds to Full Blueprint)

You do not need Proxmox VE, dedicated observability hosts, or three overseas relays to benefit from StarHub Kit. Choose the tier or modular slice (--only mihomo|firewall|ai-sandbox|lifeline) that fits your setup (see docs/ARCHITECTURE-AND-PLAYBOOK-EN.md):

TierHardware NeededSetup TimeHow to Use
Tier AI · Autonomous Agent Firewall (ai-sandbox)Any Mac / Linux workstation or Tailscale tailnet running Claude Code, Codex, OpenHands, or Docker AI containers15 secondsstarhub render --profile ai-sandbox --target nftables|macos-pf|tailscale-acl --dry-run (profiles/topology.ai-sandbox.json) or run starhub mcp
Tier 0 · Drop-In Ruleset (singbox / mihomo)Any existing Sing-box / OpenWrt / Clash Verge / Mihomo Party / Stash + Tailscale setup30 secondsRun starhub render --target singbox --dry-run or copy scripts/profiles/standalone-mihomo-tailscale-guardrails.yaml
Tier 1 · StarHub Lite (minimal)1 Gateway + 1 Laptop/PC + 1 Egress (no PVE, no custom DERP, no extra VMs)3 minutesEdit 3 items in profiles/topology.minimal.json and run ./bin/starhub render --profile minimal --out-dir ./dist-minimal
Tier 2 · Full Blueprint (full)Multi-site mesh + isolated compute workstation + cloud AI sandboxes + IoT camera kill-switch15 minutes./bin/starhub init && ./bin/starhub render --out-dir ./dist (topology.example.json)

3-Minute Full Workflow

# 1. Initialize STARHUB_GROUND_TRUTH.json (full or --profile minimal)
./bin/starhub init

# 2. Preview individual subsystems to stdout (zero disk writes) or export a deployment bundle
./bin/starhub render --only firewall --dry-run
./bin/starhub render --out-dir ./dist

# 3. Run the 7-dimension static harness, bit-for-bit reproducible archive gate & 2,000-iteration fuzz suite
./bin/starhub render --check
./bin/starhub archive --verify
./bin/starhub doctor --local-docs-only
python3 ./tests/fuzz_starhub_ctl.py --iterations 2000

# 4. Install the Git pre-commit guardrail
cp scripts/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit

Repository Structure (1 Core + 6 Books + 2 Ledgers)

PathDescription
STARHUB_GROUND_TRUTH.json / topology.example.json / profiles/topology.minimal.jsonSingle Source of Truth (SSOT): role-based declarative node inventory, dual-stack allowlists, egress definitions, IoT guardrails, and Markdown whitelist
./bin/starhub, scripts/starhub-ctl.py & flake.nixDeclarative Compiler & Reproducible Builder: modular --only / --dry-run compiler, bit-for-bit PAX tarball builder (archive --verify), and Nix Flake entrypoint
scripts/starhub-doctor.pyVerification Harness: 8-dimension drift detector + --verify-public-export Zero-PII & Zero-Inventory Release Sanitizer
AGENTS.md (CLAUDE.md / GROK.md symlinks)Unified AI & Operator Entrypoint: Ten Iron Guardrails and zero-hallucination workflow
docs/01-架构与IP全景.md – docs/06-AI接力开发与Prompt手册.mdThe 6 Golden Books: Architecture, Daily Ops & Security Matrix, Troubleshooting & 1-Hour Bare-Metal DR, Audit Index, Smart Home Hub, and Multi-Agent Playbook
docs/ROADMAP-v2.mdStarHub v2.0 Plugin Specification: declarative :3001 probe schema and :8080 Home OS drivers/* plugin contract
docs/ops/STARHUB-LEDGER.md & docs/incidents/README.mdDual Ledgers: append-only [UPD]/[BUGFIX]/[WORKSTATION] master ledger and 5-Why postmortem template

Dual-Repo Private/Public Workflow (Zero-PII & Zero-Inventory Sanitizer)

If you run a private production repository alongside a public fork of starhub-kit, verify mathematically before every public release that zero private IPs, Tailscale addresses, MACs, domains, handles, or private device/vendor identifiers exist anywhere in the public working tree or .git commit history:

python3 scripts/starhub-doctor.py \
  --verify-public-export /path/to/starhub-kit \
  --private-gt /path/to/private/STARHUB_GROUND_TRUTH.json

Security, OSPS Baseline L3 & Supply-Chain Assurance

Supply-Chain Attestations OSPS Baseline L3 StarHub EGM 3.0 CI CodeQL SAST SBOM: SPDX 2.3 REUSE 3.2 Homebrew Tap SWHID

Every release and main build publishes a Sigstore + GitHub OIDC SLSA Build Level 3 provenance certificate, an ISO/IEC 5962 (SPDX-2.3) SBOM, a bit-for-bit reproducible source archive (mtime=0, uid/gid=0), and an offline Ed25519 signature, audited under OpenSSF Best Practices Silver (#16658) and aligned with OpenSSF OSPS Baseline (Level 3):

# 1. Verify GitHub OIDC / Sigstore SLSA Build Level 3 provenance certificate
gh attestation verify starhub-kit-v1.3.0.tar.gz --repo Ziqi/starhub-kit

# 2. Verify bit-for-bit reproducible tarball against source tag
./bin/starhub archive --verify-file ./starhub-kit-v1.3.0.tar.gz --prefix starhub-kit-v1.3.0

Released under the MIT License. Please review GOVERNANCE.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md, and SECURITY.md before submitting a pull request.