Kizuna - GitLite

KO | EN

gitlite — search

#claude #ruby #graphql #vue #cpp #llm #docker #svg #json #pdf

Kizuna

(★ 9)

Self-hosted Windows NCSI/NLA compatibility service written in Go.

File Explorer

ZIP Download

- - bug_report.md
  - config.yml
  - feature_request.md
- - ci.yml
  - docker-publish.yml
- PULL_REQUEST_TEMPLATE.md
- - main.go
- config.yaml
- - Caddyfile
- - dashboard.json
- - deployment.yaml
- - nginx.conf
- - Containerfile
- - prometheus.yml
- - kizuna.service
- - kizuna-logo.png
- - portal.go
- - config.go
  - config_test.go
- - net.go
  - server.go
- - health.go
- - server.go
- - logger.go
- - metrics.go
- - ratelimit.go
  - ratelimit_test.go
- - upstream.go
- integration_test.go
CODE_OF_CONDUCT.md
CONTRIBUTING.md
docker-compose.yml
Dockerfile
go.mod
go.sum
LICENSE
README.md
SECURITY.md
SELFHOSTING.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<p align="center">
  <img src="docs/assets/kizuna-logo.png" alt="Kizuna logo" width="180">
</p>

Kizuna is a self-hosted Windows connectivity probe service built for restricted, unstable, and private network environments. It provides Microsoft-compatible NCSI and NLA probe behavior, local DNS answers, health reporting, and production-friendly deployment options.

Repository: `github.com/behdanisohrab/kizuna`
Container image: `ghcr.io/behdanisohrab/kizuna`
License: BSD 3-Clause

## What Kizuna Does

Kizuna serves the probe endpoints Windows expects and allows you to keep that logic under your own control.

The HTTP side exposes `/connecttest.txt` with `Microsoft Connect Test`, `/ncsi.txt` with `Microsoft NCSI` (or a redirect in captive-portal mode), `/healthz` for service health, and `/metrics` for Prometheus.

The DNS side serves UDP and TCP and returns configurable records, including the common compatibility mapping `dns.kizuna.ir. -> 131.107.255.255`.

## Quick Start

Build and run locally:

```bash
go mod tidy
go build -o kizuna ./cmd/kizuna
./kizuna -config configs/config.yaml
```

Verify behavior:

```bash
curl -i http://127.0.0.1:8080/connecttest.txt
curl -i http://127.0.0.1:8080/ncsi.txt
curl -s http://127.0.0.1:8080/healthz
```

## Configuration

Kizuna reads `configs/config.yaml` and then applies environment overrides. This makes it easy to keep a shared base file while changing values per environment.

Use `KIZUNA_*` variables in Docker, Kubernetes, and systemd. Backward-compatible `PARCH_*` variables are still accepted for migration.

Common overrides:

```env
KIZUNA_HTTP_ADDR=:8080
KIZUNA_HTTP_BEHIND_PROXY=true
KIZUNA_HTTP_REAL_IP_HEADER=X-Forwarded-For
KIZUNA_DNS_ADDR=:5353
KIZUNA_DNS_A_RECORDS=dns.kizuna.ir=131.107.255.255,connectivity.example.ir=203.0.113.10
KIZUNA_SECURITY_TRUSTED_PROXY_IPS=172.16.0.0/12,10.0.0.0/8,192.168.0.0/16
```

## Reverse Proxy and Domains

Kizuna works directly on the edge or behind reverse proxies such as Caddy and NGINX. When deployed behind a proxy, keep `behind_proxy` enabled and set trusted proxy CIDRs to prevent spoofed source IPs.

To run custom domains, set your DNS records in `dns.a_records` or with `KIZUNA_DNS_A_RECORDS`, then point your Windows probe host registry values to those domains.

Detailed self-hosting guidance, including Caddy and Compose, is available in [SELFHOSTING.md](SELFHOSTING.md).

## Deployment Options

Native Linux deployments can use [deploy/systemd/kizuna.service](deploy/systemd/kizuna.service). Containerized deployments can use [Dockerfile](Dockerfile), [docker-compose.yml](docker-compose.yml), and [deploy/k8s/deployment.yaml](deploy/k8s/deployment.yaml).

For metrics and dashboards, use [deploy/prometheus/prometheus.yml](deploy/prometheus/prometheus.yml) and [deploy/grafana/dashboard.json](deploy/grafana/dashboard.json).

## Windows Client Compatibility

Windows 10, 11, and Server clients can be pointed to Kizuna via registry or Group Policy. Example values:

```cmd
reg add "HKLM\SYSTEM\CurrentControlSet\Services\NlaSvc\Parameters\Internet" /v ActiveWebProbeHost /t REG_SZ /d connectivity.kizuna.ir /f
reg add "HKLM\SYSTEM\CurrentControlSet\Services\NlaSvc\Parameters\Internet" /v ActiveWebProbePath /t REG_SZ /d connecttest.txt /f
reg add "HKLM\SYSTEM\CurrentControlSet\Services\NlaSvc\Parameters\Internet" /v ActiveDnsProbeHost /t REG_SZ /d dns.kizuna.ir /f
reg add "HKLM\SYSTEM\CurrentControlSet\Services\NlaSvc\Parameters\Internet" /v ActiveDnsProbeContent /t REG_SZ /d 131.107.255.255 /f
```

## CI and Image Publishing

CI test workflow: [`.github/workflows/ci.yml`](.github/workflows/ci.yml)

GHCR publish workflow: [`.github/workflows/docker-publish.yml`](.github/workflows/docker-publish.yml)

The publish workflow builds multi-arch images and pushes to `ghcr.io/behdanisohrab/kizuna` when a new GitHub release is published. The image is tagged with the release tag and `latest`.