Skip to main content
Glama

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 Setups

StarHub Declarative Engineering Architecture

1. Hotel / Coffee-Shop Wi-Fi Subnet CollisionsAdvertising 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 + 4via6Containers 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 BlackholesBlind 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 GovernanceZero 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 RiskMultiple 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 LeaksDozens 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).


Related MCP server: claude-mac-bridge

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

Tier

Hardware Needed

Setup Time

How to Use

Tier AI · Autonomous Agent Firewall (ai-sandbox)

Any Mac / Linux workstation or Tailscale tailnet running Claude Code, Codex, OpenHands, or Docker AI containers

15 seconds

starhub 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 setup

30 seconds

Run 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 minutes

Edit 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-switch

15 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)

Path

Description

STARHUB_GROUND_TRUTH.json / topology.example.json / profiles/topology.minimal.json

Single 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.nix

Declarative Compiler & Reproducible Builder: modular --only / --dry-run compiler, bit-for-bit PAX tarball builder (archive --verify), and Nix Flake entrypoint

scripts/starhub-doctor.py

Verification 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手册.md

The 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.md

StarHub v2.0 Plugin Specification: declarative :3001 probe schema and :8080 Home OS drivers/* plugin contract

docs/ops/STARHUB-LEDGER.md & docs/incidents/README.md

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

Available Tools

3 tools
audit_topology_securityC

Audit a StarHub topology JSON for RFC 1918 Wi-Fi subnet collisions and exposed AI sandbox SSH/database ports.

Inputs: topology_json.

compile_ai_sandbox_policyC

Compile zero-lateral-movement firewall / ACL policy for autonomous AI coding agents (Linux nftables, macOS pf, Tailscale ACL JSON, or Linux iptables).

Inputs: backend, sandbox_ips, allowed_api_targets.

render_quic_mesh_guardrailsC

Render deterministic Tailscale split-DNS + surgical Apple/Gmail UDP/443 QUIC ruleset for Sing-box or Mihomo (Clash Meta).

Inputs: engine.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct action and target: rendering QUIC/mesh guardrails, auditing topology security, and compiling AI sandbox policy. There is little risk of confusing one tool for another despite the shared networking/security domain.

    Naming Consistency5/5

    All tool names use consistent snake_case with a leading verb and descriptive noun phrase. The pattern is predictable across render_, audit_, and compile_.

    Tool Count5/5

    Three tools is well-scoped for a specialized network/security policy kit, with each tool covering a distinct workflow. No tool appears redundant or out of place.

    Completeness4/5

    The surface covers rendering guardrails, auditing topology, and compiling sandbox policy, which are the core operations implied by the kit. Minor gaps exist around validating generated outputs or applying policies, but agents can work around these.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      A local-first MCP server that gives AI coding agents persistent memory and controlled commands. Features a git-backed markdown knowledge vault with FTS5 search, surgical section edits, token-aware context budgeting, and a sandboxed command engine with human approval gates. Works with Claude Code, Cursor, Copilot, Gemini, and more.
      62
      601 npm
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      A macOS-native MCP server that provides AI hosts with fresh workspace state, bounded context, and retained execution evidence, avoiding collapsing operations into shell strings.
      23 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      A local-first MCP server that enables AI-assisted coding through workspace-scoped tools for file reading/editing, command execution, jobs, Git, LSP, media, browser, and desktop workflows. It enforces OAuth, workspace ACL, trust policies, and file/secret guards so owners can safely grant inspect, edit, or trusted capabilities.
      559 npm
      MIT