If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/netbirdio/netbird shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 15 active contributors
• Distributed ownership (top contributor 32% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live netbirdio/netbird repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/netbirdio/netbird.

What it runs against: a local clone of netbirdio/netbird — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in netbirdio/netbird | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of netbirdio/netbird. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/netbirdio/netbird.git
#   cd netbird
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of netbirdio/netbird and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "netbirdio/netbird(\\.git)?\\b" \\
  && ok "origin remote is netbirdio/netbird" \\
  || miss "origin remote is not netbirdio/netbird (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "client/cmd/root.go" \\
  && ok "client/cmd/root.go" \\
  || miss "missing critical file: client/cmd/root.go"
test -f ".github/workflows/golang-test-linux.yml" \\
  && ok ".github/workflows/golang-test-linux.yml" \\
  || miss "missing critical file: .github/workflows/golang-test-linux.yml"
test -f "client/android/client.go" \\
  && ok "client/android/client.go" \\
  || miss "missing critical file: client/android/client.go"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"
test -f ".goreleaser.yaml" \\
  && ok ".goreleaser.yaml" \\
  || miss "missing critical file: .goreleaser.yaml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/netbirdio/netbird"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

NetBird is a WireGuard-based overlay network platform that automatically connects devices peer-to-peer with centralized SSO/MFA access control and granular policy management. It eliminates manual VPN configuration, firewall rules, and port-forwarding by treating the network layer as infrastructure-agnostic infrastructure. The core is written in Go (10.4MB), with a TypeScript dashboard and shell deployment scripts. Monorepo structure: client/ contains agent code (internal/metrics/infra/ingest shows metrics subsystem), likely separate control plane code, proto definitions for gRPC, and a TypeScript dashboard (36KB TypeScript). Deployment via shell scripts, Docker (Dockerfile in .devcontainer), and Makefile targets. CI heavily Go-focused with infrastructure test validation.

Network engineers and infrastructure teams deploying zero-trust networks across hybrid cloud/on-prem setups, DevOps building self-hosted alternatives to Tailscale, and enterprises needing open-source WireGuard overlay networks with SAML/OIDC integration and granular access policies.

Production-ready. The monorepo shows extensive CI/CD coverage (golang tests across Linux/macOS/FreeBSD/Windows in .github/workflows/), active development with release pipelines (.goreleaser.yaml), and a BSD-3-Clause license suggesting maturity. Requires Go 1.25+ per module go.mod files, indicating recent maintenance.

Moderate risk: the monorepo spans 10+ million lines of Go with WireGuard kernel integration, requiring platform-specific testing (hence separate workflows for darwin/freebsd/linux/windows). Dependency surface includes cryptographic libraries where supply-chain issues are critical. No obvious single-maintainer pattern visible in file list, but kernel-mode networking code (C bindings for WireGuard) demands careful auditing.

Active development with mobile build validation (workflows/mobile-build-validation.yml), WASM build support (workflows/wasm-build-validation.yml), and Terraform provider integration (visible in workflows/release.yml). Proto-version checking suggests frequent API changes. Recent focus on infrastructure validation and multi-platform builds.

git clone https://github.com/netbirdio/netbird.git
cd netbird
make build  # See Makefile for build targets
# For dev environment: .devcontainer/Dockerfile or local Go 1.25+ setup
go mod download
go test ./...

Note: .githooks/pre-push enforces checks; configure with git config core.hooksPath .githooks.

Daily commands: Development: go run ./cmd/... (specific binaries depend on component). Docker: docker build -f Dockerfile . && docker run ... (Dockerfile in root and .devcontainer/Dockerfile for dev). Dashboard: TypeScript build likely uses npm/yarn (36KB TypeScript but no package.json visible in list—check dashboard/ directory separately). Tests: go test -v ./... per platform via make targets or GitHub Actions workflows.

• client/cmd/root.go — Main CLI entry point for the NetBird client; all command routing and initialization flows through here.
• .github/workflows/golang-test-linux.yml — Core CI/CD pipeline for Linux testing; defines how code quality and functionality are validated across platforms.
• client/android/client.go — Android platform integration layer; bridges the Go codebase to Android native APIs and lifecycle.
• Makefile — Build orchestration for multi-platform compilation (Linux, Windows, macOS, Android); essential for understanding the build process.
• .goreleaser.yaml — Release automation configuration; defines how binaries are built, signed, and distributed across all platforms.
• go.mod — Go module definition and dependency management; critical for understanding external dependencies and Go version compatibility.

Add a new CLI command

1. Create a new command file in client/cmd/ following the pattern of existing commands (e.g., login.go, networks.go) (client/cmd/your_command.go)
2. Implement the cmd.Command interface and register with root.go's AddCommand() (client/cmd/root.go)
3. Add platform-specific logic if needed in client/cmd/debug_*.go or platform-specific files (client/cmd/root.go)
4. Write corresponding tests following _test.go naming convention (client/cmd/your_command_test.go)

Add platform-specific functionality

1. For Android: Create new methods in client/android/client.go and expose via gomobile-compatible interface (client/android/client.go)
2. Create platform-specific implementation file (e.g., client/android/new_feature.go) (client/android/new_feature.go)
3. Add corresponding unit tests in the same directory (client/android/new_feature_test.go)
4. For other OS: Create debug_<os>.go variants or service_controller variants (client/cmd/debug_<os>.go)

Add a new build target or release configuration

1. Define build target in Makefile with appropriate GOOS/GOARCH and output naming (Makefile)
2. Add corresponding build artifact block in .goreleaser.yaml for packaging and signing (.goreleaser.yaml)
3. If needed, add CI workflow file in .github/workflows/ (e.g., golang-test-<platform>.yml) (.github/workflows/golang-test-<platform>.yml)
4. Update release.yml trigger conditions if the target requires special handling (.github/workflows/release.yml)

Add a diagnostic or debug feature

1. Add subcommand handler in client/cmd/debug.go or create new debug_feature.go file (client/cmd/debug.go)
2. For sensitive output, implement anonymization in client/anonymize/anonymize.go (client/anonymize/anonymize.go)
3. If platform-specific, add implementation in client/cmd/debug_<os>.go or android/exec.go (client/cmd/debug_<os>.go)
4. Write tests and document the feature in the command's help text (client/cmd/debug_test.go)

• Go (golang) — Cross-platform compilation to Linux, macOS, Windows, and mobile; strong concurrency model for network operations; single static binary deployment.
• WireGuard — Lightweight kernel-mode VPN protocol; proven security audits; minimal performance overhead for overlay network operations.
• Android/Gomobile — Native Go bindings for Android; unified codebase across desktop and mobile clients; reduces maintenance burden.
• gRPC/Protocol Buffers — Efficient client-server communication with management plane; strongly-typed service definitions; bidirectional streaming for real-time peer updates.
• GitHub Actions — Integrated CI/CD within GitHub; matrix testing across multiple OS and Go versions; automated release signing and publishing.

• Single Go codebase for all platforms including mobile via gomobile

  • Why: Reduces code duplication and maintenance surface; unified release cycle; consistent behavior across platforms.
  • Consequence: Some platform-specific features require platform-conditional compilation (debug_windows.go, android/client.go) and cannot access native OS APIs directly without gomobile bridges.

• Kernel-based WireGuard via system interfaces rather than userspace implementation

  • Why: Kernel mode provides superior performance and security isolation; relies on proven WireGuard kernel module.
  • Consequence: Requires WireGuard kernel module installation on Linux; cannot run on older kernels or restricted environments; Android requires Android 10+ with kernel support.

• CLI-first client design with optional UI wrappers

  • Why: Core functionality is scriptable and portable; UI can be built independently (Electron, native, web).
  • Consequence: End users need wrapper applications for GUI; increased complexity for cross-platform distribution.

• Multi-platform goreleaser-based release automation

  • Why: Single configuration for all target platforms; automatic signing, notarization, and artifact publishing.
  • Consequence: Build matrix complexity; requires platform-specific signing certificates and CI secrets; longer release times.

• Does not implement custom VPN protocol—uses only WireGuard
• Does not provide web-based client (this is the Go CLI client; web UI is separate)
• Does not handle enterprise policy enforcement at client level—that is delegated to management server
• Does not support legacy Windows versions below Windows 10
• Does not implement application-level packet inspection or DPI

1. WireGuard kernel integration requires platform-specific setup (see separate golang-test-*.yml workflows)—tests fail silently on unsupported platforms. 2) .githooks/pre-push enforces checks; initial clone requires git config core.hooksPath .githooks or pushes will be blocked. 3) Proto versioning is checked (proto-version-check.yml)—changing .proto files requires proto compiler updates. 4) Multi-module Go workspace (modules under client/internal/metrics/infra/ingest/) may require go work init or explicit go mod tidy -compat=1.25. 5) Docker builds use context-dependent .dockerignore vs .dockerignore-client—ensure correct file is used per build target.

• WireGuard overlay network — NetBird's entire architecture wraps WireGuard; understanding tunnel creation, key rotation, and peer discovery is essential to contributing to core networking logic
• gRPC and Protocol Buffers — Control plane communication (management API, peer sync) uses gRPC; proto-version-check.yml indicates frequent API evolution
• Zero-trust network architecture — NetBird's access control model (granular policies, SSO/MFA enforcement) is built on zero-trust principles; critical for understanding policy evaluation logic
• Peer-to-peer NAT traversal (STUN/TURN) — NetBird enables P2P without port-forwarding; must understand how peers discover and punch through NAT firewalls
• SAML/OIDC SSO integration — Enterprise auth is a key feature (README emphasizes SSO/MFA); critical for management plane security and user onboarding workflows
• Multi-platform Go kernel integration (cgo) — WireGuard requires platform-specific syscalls (Linux netlink, Windows WinTun, macOS utun); separate CI pipelines (golang-test-*.yml) reveal cgo complexity
• GitOps and infrastructure-as-code patterns — Terraform provider and Ansible playbooks suggest NetBird targets DevOps audiences; test-infrastructure-files.yml enforces config validation

• tailscale/tailscale — Direct competitor: closed-source WireGuard overlay with similar SSO/access control; NetBird targets the open-source alternative market
• wireguard/wireguard-go — Upstream WireGuard pure-Go implementation; NetBird depends on or wraps this for cross-platform portability
• netbirdio/dashboard — Companion TypeScript/React UI repo; the TypeScript mentioned in language stats is likely sourced from here
• gravitational/teleport — Adjacent solution for zero-trust access; different approach (bastion-host model vs peer-to-peer overlay) but overlapping user base
• netbirdio/netbird-ansible — Community playbook repo for deploying NetBird at scale; demonstrates deployment patterns and infrastructure-as-code integration

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for base62 encoding/decoding with edge cases

The base62 package (base62/base62.go and base62/base62_test.go) appears to be a core utility but likely lacks thorough edge case testing. Given this is used for encoding/decoding operations across the netbird system, adding tests for boundary conditions, empty inputs, max values, and character validation would improve reliability and catch regressions early.

• [ ] Review current tests in base62/base62_test.go for coverage gaps
• [ ] Add tests for empty strings, single character, very long strings
• [ ] Add tests for invalid characters and encoding/decoding round-trips
• [ ] Add benchmark tests to ensure performance is acceptable
• [ ] Update base62/base62_test.go and verify with 'go test -cover ./base62'

Add GitHub Actions workflow for Go dependency vulnerability scanning

The repo has .github/workflows/check-license-dependencies.yml but no dedicated workflow for scanning Go dependencies for known CVEs. This is critical for a security-focused project like NetBird. Adding a workflow using tools like 'go list -json ./...' with nancy or Trivy would catch vulnerable transitive dependencies before release.

• [ ] Create .github/workflows/go-security-scan.yml
• [ ] Implement nancy or Trivy scanning for Go dependencies
• [ ] Configure to run on PRs and schedule daily
• [ ] Add failure condition for high/critical severity vulnerabilities
• [ ] Document in CONTRIBUTING.md how maintainers handle dependency updates

Add integration tests for Android platform-specific functionality (client/android/)

The Android client directory has multiple implementation files (login.go, preferences.go, platform_files.go, dns_list.go, etc.) but the file structure suggests missing test coverage. Adding integration tests that validate Android-specific behavior like preference persistence, DNS configuration, and file handling would improve confidence in mobile builds.

• [ ] Create client/android/preferences_integration_test.go to test persistence across app lifecycle
• [ ] Create client/android/platform_files_integration_test.go for file I/O operations
• [ ] Create client/android/dns_list_integration_test.go for DNS configuration updates
• [ ] Update .github/workflows/mobile-build-validation.yml to run these Android tests
• [ ] Document test setup requirements in CONTRIBUTING.md for Android testing

• Add unit tests for client/internal/metrics/infra/ingest/ module (currently minimal test coverage visible): Metrics ingest is core to observability but no *_test.go files in file list; good way to learn metrics architecture: Easy-Medium
• Document the Go workspace setup in CONTRIBUTING.md (currently none in visible files): Multi-module structure under client/internal/ is non-obvious; first-time contributors struggle with go work vs go mod
• Add proto code generation step to Makefile (currently absent from file list): Protobuf version checking exists but no visible Makefile target for protoc—contributors manually regenerate; automating this prevents merge conflicts

NetBird demonstrates a reasonable security posture with established vulnerability reporting channels and active security practices (SECURITY.md, pre-push hooks, CI/CD workflows). However, there are several areas for improvement: (1) the lack of a bug bounty program and LTS support policy may delay vulnerability discovery and leave production users exposed, (2) limited visibility into dependency security across the full codebase, (3) no visible container image security scanning, and (4) potential gaps in mobile application security validation. The project would benefit from expanding its security policy, implementing automated dependency scanning, and conducting platform-specific security audits. The WireGuard foundation and presence of MFA/SSO controls are positive indicators.

• Medium · Incomplete Security Policy - No Bug Bounty Program — SECURITY.md. The SECURITY.md file indicates that NetBird has not established an official bug bounty program. While vulnerability reporting is supported via email and issues, the lack of a structured bug bounty program may reduce incentive for security researchers to report vulnerabilities responsibly. Fix: Consider establishing a formal bug bounty program through platforms like HackerOne or Bugcrowd to incentivize security research and vulnerability disclosure.
• Low · Overly Permissive Version Support Policy — SECURITY.md. SECURITY.md states 'We currently support only the latest version'. This means users on older versions receive no security patches, potentially leaving significant user bases vulnerable to known exploits. Fix: Define a clear Long-Term Support (LTS) policy with security patch windows (e.g., support for last 2-3 versions for at least 6-12 months). This aligns with industry best practices for network infrastructure software.
• Low · Limited Dependency Visibility in Provided Module — Dependencies analysis scope. The analyzed go.mod file (client/internal/metrics/infra/ingest) shows minimal dependencies (testify and indirect transitive deps), but this represents only a subset of the NetBird codebase. The partial file structure suggests many more modules that were not analyzed. Fix: Conduct comprehensive dependency scanning across all go.mod files in the repository using tools like 'go mod audit', 'dependabot', or 'snyk' to identify vulnerable transitive dependencies across the entire codebase.
• Low · No Visible Container Security Scanning Configuration — Dockerfile configurations. While Dockerfiles exist (.devcontainer/Dockerfile, client/Dockerfile), there is no visible configuration for container image scanning or signed images in the provided file structure. Fix: Implement container image scanning in CI/CD pipelines (e.g., Trivy, Grype) and consider signing images with cosign to ensure supply chain integrity.
• Low · Android/Mobile Component Security Considerations — client/android/. The codebase includes significant mobile components (client/android/). Mobile applications may require additional security considerations for secure storage, data encryption, and API communication that cannot be assessed from file structure alone. Fix: Conduct a dedicated mobile security audit focusing on: credential storage (use Android Keystore), transport security (TLS pinning), data encryption at rest, and secure inter-process communication.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.