{"id":48987567,"url":"https://github.com/naxonm/snispf-core","last_synced_at":"2026-04-18T13:11:46.210Z","repository":{"id":352040177,"uuid":"1213576845","full_name":"NaxonM/snispf-core","owner":"NaxonM","description":"Terminal-first Go core for SNI spoofing DPI bypass with fragment, fake_sni, combined, and wrong_seq modes","archived":false,"fork":false,"pushed_at":"2026-04-17T14:55:06.000Z","size":137,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-17T16:47:53.000Z","etag":null,"topics":["dpi-bypass","go","network","openwrt","proxy","sni","sni-spoofing"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NaxonM.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-17T14:27:06.000Z","updated_at":"2026-04-17T15:38:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/NaxonM/snispf-core","commit_stats":null,"previous_names":["naxonm/snispf-core"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/NaxonM/snispf-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NaxonM%2Fsnispf-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NaxonM%2Fsnispf-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NaxonM%2Fsnispf-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NaxonM%2Fsnispf-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NaxonM","download_url":"https://codeload.github.com/NaxonM/snispf-core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NaxonM%2Fsnispf-core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31970027,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dpi-bypass","go","network","openwrt","proxy","sni","sni-spoofing"],"created_at":"2026-04-18T13:11:33.800Z","updated_at":"2026-04-18T13:11:46.201Z","avatar_url":"https://github.com/NaxonM.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SNISPF Core (Go)\n\nTerminal-first DPI bypass core, designed to run headless as a stable runtime process.\n\nThis core follows [patterniha's SNI-Spoofing](https://github.com/patterniha/SNI-Spoofing) DPI bypass technique. All credit for the original idea and method goes to [@patterniha](https://github.com/patterniha).\n\nPersian guide: `README_fa.md`\n\n## What This Core Does\n\nSNISPF runs as a local TCP forwarder between your client and upstream endpoint:\n\n1. Your client connects locally to SNISPF (`LISTEN_HOST:LISTEN_PORT`).\n2. SNISPF connects to your upstream endpoint (`CONNECT_IP:CONNECT_PORT`).\n3. SNISPF applies a bypass strategy (`fragment`, `fake_sni`, `combined`, or strict `wrong_seq`).\n\nThis design keeps your client config simple and moves bypass behavior into one controllable core process.\n\n## Before You Start\n\nUse this section as a quick decision table for permissions and prerequisites.\n\n| Platform | Basic methods (`fragment`, `fake_sni`, `combined`) | Strict `wrong_seq` |\n|---|---|---|\n| Linux | Works unprivileged | Requires raw packet capability (`root` or `CAP_NET_RAW`) |\n| Windows | Works normally | Requires Administrator + `WinDivert.dll` + `WinDivert64.sys` |\n| OpenWrt | Works normally | Requires `CAP_NET_RAW`/root and AF_PACKET support |\n\nRun this to inspect runtime capability flags:\n\n```powershell\n.\\snispf.exe --info\n```\n\n`--info` is config-independent and does not require `--config` or `config.json`.\n\nIf raw injection is unavailable, `--info` can print `raw_injection_diagnostic=...` with the reason.\n\n## Quickstart (4 Steps)\n\n### Step 1) Build\n\n```powershell\ngo build -o snispf.exe ./cmd/snispf\n```\n\n### Step 2) Generate and Validate Config\n\n```powershell\n.\\snispf.exe --generate-config .\\config.json\n.\\snispf.exe --config .\\config.json --config-doctor\n```\n\n### Step 3) Configure Minimal Safe Profile\n\nStart from the safest baseline (`fragment`):\n\n```json\n{\n  \"LISTEN_HOST\": \"127.0.0.1\",\n  \"LISTEN_PORT\": 40443,\n  \"LOG_LEVEL\": \"info\",\n  \"CONNECT_IP\": \"188.114.98.0\",\n  \"CONNECT_PORT\": 443,\n  \"FAKE_SNI\": \"auth.vercel.com\",\n  \"BYPASS_METHOD\": \"fragment\"\n}\n```\n\nField mapping:\n\n| Field | Meaning |\n|---|---|\n| `LISTEN_HOST:LISTEN_PORT` | Local address your client should connect to |\n| `LOG_LEVEL` | Runtime verbosity: `error`, `warn`, `info`, `debug` |\n| `CONNECT_IP:CONNECT_PORT` | Upstream destination SNISPF dials |\n| `FAKE_SNI` | SNI used by fake/combined logic and endpoint defaults |\n| `BYPASS_METHOD` | Strategy (`fragment`, `fake_sni`, `combined`, `wrong_seq`) |\n\nConfig precedence note:\n\n- If `ENDPOINTS` exists, runtime endpoint dial values come from `ENDPOINTS`.\n- Top-level `CONNECT_IP`, `CONNECT_PORT`, and `FAKE_SNI` remain backward-compatible defaults.\n- If top-level values conflict with `ENDPOINTS[0]`, startup logs a warning showing that `ENDPOINTS[0]` overrides top-level fields.\n\n### Step 4) Run and Point Client\n\n```powershell\n.\\snispf.exe --config .\\config.json\n```\n\nSet your client to:\n\n- Address: `127.0.0.1`\n- Port: `40443` (or your configured `LISTEN_PORT`)\n\nKeep the rest of your client protocol settings unchanged.\n\n## Choosing a Bypass Method\n\nUse this order unless you have a specific reason not to:\n\n1. `fragment` (best first run)\n2. `fake_sni` or `combined` (next step after baseline stability)\n3. `wrong_seq` only when strict prerequisites are met\n\n`wrong_seq` guardrails and requirements:\n\n1. Exactly one enabled endpoint.\n2. Raw injection available on current platform.\n3. SNI length \u003c= `219` bytes.\n4. Generated fake ClientHello size \u003c= `1460` bytes.\n5. Optional timeout tuning: `WRONG_SEQ_CONFIRM_TIMEOUT_MS` (default `2000`).\n6. For multi-WAN/multi-WLAN route changes, `wrong_seq` may need restart to rebind raw injector.\n\nMulti-WAN practical note:\n\n- `wrong_seq` is strict mode and is best with a single stable upstream path.\n- For automatic per-connection route adaptation across changing WAN paths, prefer `fragment`/`combined`.\n\n## Run Modes\n\n### Direct Mode (Simplest)\n\n```powershell\n.\\snispf.exe --config .\\config.json\n```\n\nOptional one-off overrides:\n\n```powershell\n.\\snispf.exe --config .\\config.json --listen 0.0.0.0:40443 --connect 188.114.98.0:443 --sni auth.vercel.com --method combined\n```\n\n### Service API Mode (Desktop/Automation)\n\n```powershell\n.\\snispf.exe --service --service-addr 127.0.0.1:8797\n```\n\nWith auth token:\n\n```powershell\n.\\snispf.exe --service --service-addr 127.0.0.1:8797 --service-token your-token\n```\n\nUse service mode when another process (UI, launcher, script) should control start/stop/health.\n\n## Service API Quick Reference\n\nBase URL: `http://127.0.0.1:8797` (or your `--service-addr`)\n\n- `GET /v1/status`\n- `POST /v1/start`\n- `POST /v1/stop`\n- `GET /v1/health`\n- `GET /v1/validate`\n- `GET /v1/logs?limit=300\u0026level=ALL`\n\nIf token is enabled, send header `X-SNISPF-Token: \u003ctoken\u003e`.\n\nRecommended troubleshooting order:\n\n1. `/v1/status`\n2. `/v1/validate`\n3. `/v1/health`\n4. `/v1/logs`\n\n`/v1/health` includes `wrong_seq` counters from logs:\n\n- `confirmed`\n- `timeout`\n- `failed`\n- `not_registered`\n- `first_write_fail`\n\nFull request/response contract: `docs/api-contract.md`\n\n## OpenWrt Deployment (Practical Flow)\n\nBuild OpenWrt artifacts:\n\n```powershell\npowershell -ExecutionPolicy Bypass -File .\\scripts\\build_openwrt_matrix.ps1\n```\n\nCopy to router:\n\n```bash\nscp ./release/openwrt/snispf_openwrt_armv7 root@192.168.1.1:/tmp/\nscp ./config.json root@192.168.1.1:/tmp/snispf_config.json\nscp ./release/openwrt/openwrt_snispf.sh root@192.168.1.1:/tmp/\n```\n\nInstall and run on router:\n\n```sh\nssh root@192.168.1.1\nchmod +x /tmp/openwrt_snispf.sh\nash /tmp/openwrt_snispf.sh install --binary /tmp/snispf_openwrt_armv7 --config /tmp/snispf_config.json\n```\n\nInstaller behavior (default):\n\n- Schedules one delayed restart after install/start (default `20s`).\n- Asks to install watchdog in interactive shell (`--watchdog ask`).\n- In non-interactive mode, `ask` behaves like auto install.\n\nWatchdog defaults and tuning:\n\n- Default schedule is every `1` minute.\n- It restarts on down process, missing listen port, and degraded raw-injector patterns in logs.\n\nForce watchdog install or tune delayed restart:\n\n```sh\nash /tmp/openwrt_snispf.sh watchdog-install\nash /tmp/openwrt_snispf.sh install --binary /tmp/snispf_openwrt_armv7 --config /tmp/snispf_config.json --watchdog auto --post-restart-delay 20\n```\n\nUseful operations:\n\n```sh\nash /tmp/openwrt_snispf.sh status\nash /tmp/openwrt_snispf.sh logs --follow\nash /tmp/openwrt_snispf.sh monitor --watch 30 --interval 2\nash /tmp/openwrt_snispf.sh doctor\n```\n\nFor strict `wrong_seq` on OpenWrt, use root or grant capability:\n\n```sh\nsetcap cap_net_raw+ep /path/to/snispf_openwrt_armv7\n```\n\n## Build and Release Scripts\n\nLocal build:\n\n```powershell\ngo build -o snispf.exe ./cmd/snispf\n```\n\nCross-build scripts:\n\n- Windows amd64: `powershell -ExecutionPolicy Bypass -File .\\scripts\\build_windows_amd64.ps1`\n- Linux amd64 (PowerShell): `powershell -ExecutionPolicy Bypass -File .\\scripts\\build_linux_amd64.ps1`\n- Linux amd64 (bash): `bash ./scripts/build_linux_amd64.sh`\n- Full release matrix: `powershell -ExecutionPolicy Bypass -File .\\scripts\\build_release_matrix.ps1`\n- OpenWrt matrix (PowerShell): `powershell -ExecutionPolicy Bypass -File .\\scripts\\build_openwrt_matrix.ps1`\n- OpenWrt matrix (bash): `bash ./scripts/build_openwrt_matrix.sh`\n\nVerification scripts:\n\n- `powershell -ExecutionPolicy Bypass -File .\\scripts\\verify_release.ps1`\n- `bash ./scripts/verify_release.sh`\n\nRelease outputs:\n\n- Core binaries: `release/snispf_windows_amd64.exe`, `release/snispf_linux_amd64`, `release/snispf_linux_arm64`\n- Bundled archives: `release/snispf_windows_amd64_bundle.zip`, `release/snispf_linux_amd64_bundle.tar.gz`, `release/snispf_linux_arm64_bundle.tar.gz`\n- Metadata: `release/checksums.txt`, `release/release_manifest.json`\n- OpenWrt: `release/openwrt/` (includes binaries + `openwrt_snispf.sh`), `release/openwrt/checksums.txt`, `release/openwrt/release_manifest.json`\n\n## GitHub Actions Release\n\nWorkflow: `.github/workflows/release.yml`\n\n1. Trigger manually with `workflow_dispatch` for draft/test release builds.\n2. Push tag (for example `v1.2.3`) to build and publish assets.\n3. Workflow publishes both core and OpenWrt artifacts with checksums/manifest.\n\n## CLI Snapshot\n\nCommon flags:\n\n- `--config`, `--generate-config`, `--config-doctor`, `--info`\n- `--listen`, `--connect`, `--sni`, `--method`\n- `--service`, `--service-addr`, `--service-token`\n- `--build-info`, `--version`\n\nBackward-compatible aliases:\n\n- `snispf run ...` -\u003e direct core mode\n- `snispf service ...` -\u003e service mode\n- `snispf doctor ...` -\u003e config doctor\n- `snispf build-info` -\u003e build metadata\n\n## Multi-Listener Example\n\n```json\n{\n  \"BYPASS_METHOD\": \"wrong_seq\",\n  \"LISTENERS\": [\n    {\n      \"NAME\": \"edge-a\",\n      \"LISTEN_HOST\": \"127.0.0.1\",\n      \"LISTEN_PORT\": 40443,\n      \"CONNECT_IP\": \"104.19.229.21\",\n      \"CONNECT_PORT\": 443,\n      \"FAKE_SNI\": \"hcaptcha.com\"\n    },\n    {\n      \"NAME\": \"edge-b\",\n      \"LISTEN_HOST\": \"127.0.0.1\",\n      \"LISTEN_PORT\": 40444,\n      \"CONNECT_IP\": \"104.19.229.22\",\n      \"CONNECT_PORT\": 443,\n      \"FAKE_SNI\": \"hcaptcha.com\",\n      \"BYPASS_METHOD\": \"fragment\"\n    }\n  ]\n}\n```\n\nWhen `LISTENERS` is present, each listener runs independently in the same process.\n\n## Verification Checklist\n\n```powershell\ngo test ./...\ngo vet ./...\ngo build -o snispf.exe ./cmd/snispf\npowershell -ExecutionPolicy Bypass -File .\\scripts\\build_linux_amd64.ps1\npowershell -ExecutionPolicy Bypass -File .\\scripts\\build_release_matrix.ps1\npowershell -ExecutionPolicy Bypass -File .\\scripts\\verify_release.ps1\n```\n\nWindows service lifecycle integration:\n\n```powershell\npowershell -ExecutionPolicy Bypass -File .\\scripts\\integration_service_lifecycle.ps1\n```\n\n## Docs Map\n\n- `docs/README.md`: documentation index and reading order.\n- `docs/beginner-guide.md`: first-time setup and troubleshooting path.\n- `docs/api-contract.md`: full service API contract.\n- `docs/internals.md`: detailed architecture and data path.\n- `docs/examples.md`: sanitized example profiles.\n- `docs/roadmap.md`: planned future direction.\n\n## Troubleshooting Checklist\n\n1. Run config doctor and fix reported errors.\n2. Confirm client points to local SNISPF listener.\n3. Confirm upstream reachability (`/v1/health` or startup logs).\n4. For `wrong_seq`, verify platform privilege and single endpoint.\n5. Inspect `/v1/logs` for `timeout`, `failed`, and `not_registered` outcomes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnaxonm%2Fsnispf-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnaxonm%2Fsnispf-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnaxonm%2Fsnispf-core/lists"}