feat(scripts): T-5.4 Bootstrap Script v2.0 with Smart Selection

[obtFusi]

Summary

• Updates bootstrap-new-client.ps1 for v3.6 Smart Certificate Selection
• Adds security improvements: Setup-Key redaction, REVOKE warning, verification docs

Changes

• Smart Selection v3.6: Uses machine_cert_template_name + machine_cert_san_must_match instead of hardcoded thumbprint
• REVOKE Warning: Prominent security box at script end reminding to revoke Setup-Key in Dashboard
• Secret Redaction: Setup-Key shown as ****-****-****-****-XXXX (only last 4 chars visible)
• Security Docs: Added in .NOTES section:
  • SHA256 checksum verification instructions
  • Authenticode signing instructions
  • Setup-Key handling best practices

Test Evidence

Windows VM WhatIf Mode Test:

Step 1: Pre-Tunnel NTP Sync (Public NTP)
What if: Performing the operation "Configure public NTP" on target "W32Time".

Step 2: Starting NetBird Machine Service (Phase 1: Setup-Key)
What if: Performing the operation "Install and start with Setup-Key" on target "NetBirdMachine".

Step 3: Verifying DC Connectivity via Tunnel
  Testing LDAP (port 389)... [OK] OK
  Testing Kerberos (port 88)... [OK] OK
  Testing DNS (port 53)... [OK] OK
[OK] All required DC ports reachable via tunnel

Step 4: NTP Sync with Domain Controller
What if: Performing the operation "Configure DC NTP" on target "W32Time".

Step 5: Domain Join
[OK] Computer is already joined to test.local

Step 6: Machine Certificate Enrollment
What if: Performing the operation "Request machine certificate" on target "AD CS".

Step 7: Updating NetBird Config for mTLS (Phase 2 - Smart Selection)
What if: Performing the operation "Enable mTLS with Smart Selection" on target "C:\ProgramData\NetBird\config.yaml".

Step 8: Completing Bootstrap
╔═══════════════════════════════════════════════════════════════════╗
║  ⚠️  SECURITY ACTION REQUIRED                                      ║
║  REVOKE the Setup-Key in NetBird Dashboard immediately!           ║
║  Setup-Key used: ****-****-****-****-7890                         ║
╚═══════════════════════════════════════════════════════════════════╝

DoD Checklist

• Script mit allen 8 Schritten
• DC-Connectivity Prüfung vor Join
• NTP-Sync vor Join (Kerberos)
• Smart Selection Config (kein Thumbprint)
• Warnung: "REVOKE setup-key!"
• Error-Handling für jeden Schritt
• Integration Test: WhatIf Mode auf Windows VM
• Keine Secrets in Logs (Setup-Key redacted)
• Script-Signatur via Authenticode (dokumentiert)
• Checksum-Verifikation dokumentieren

Closes #50

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added Windows machine tunnel bootstrap with two-phase authentication (Setup-Key Phase 1, mTLS Phase 2)
  • Implemented mTLS-based machine peer registration and management on dedicated port 33074
  • Added automated machine certificate enrollment and renewal via Active Directory Certificate Services
  • Introduced Domain Controller connectivity validation before domain join
  • Added PowerShell automation for client bootstrap, lab setup, and service installation

• Configuration & Infrastructure

  • Enhanced server configuration with mTLS settings (port, CA certificates, issuer validation, domain mappings)
  • Added git hooks for code formatting and secret detection
  • Configured Dependabot for dependency updates and GitHub Actions for automated labeling and PR linting

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[obtFusi]

Created in wrong repo, recreating in fork

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

Implements Windows pre-login machine tunnel support via two-phase mTLS authentication. Adds client-side bootstrap logic (Setup-Key Phase 1, mTLS Phase 2), server-side mTLS gRPC infrastructure, certificate enrollment utilities, domain controller connectivity checks, and PowerShell automation scripts for lab setup and deployment.

Changes

Cohort / File(s)	Summary
Git Hooks & Pre-commit Enforcement .githooks/pre-commit, Makefile	Adds gofmt formatting check and secrets pattern detection for staged Go files; updates Makefile to apply executable permission to pre-commit hook alongside existing pre-push hook.
GitHub Issue Templates & Workflows .github/ISSUE_TEMPLATE/{bug_report,epic,feature_request,story,task}.md, .github/ISSUE_TEMPLATE/config.yml, .github/workflows/{auto-label,pr-lint}.yml	Adds German-language issue templates for bugs, epics, features, stories, and tasks; defines template config with contact links; introduces auto-labeling workflow for issues/PRs and conventional-commits linter for PR titles.
Repository Configuration .gitignore, .github/dependabot.yml	Narrows VSCode folder ignore while broadening coverage for secrets (.key, .pem, cert files), build artifacts, OS ephemeral files; adds Dependabot config for Go modules, GitHub Actions, and Docker.
Client Bootstrap Implementation client/internal/tunnel/bootstrap.go, client/internal/tunnel/bootstrap_test.go	Implements two-phase authentication: Setup-Key (Phase 1) fallback and mTLS (Phase 2) primary path with machine certificate validation; includes cert loading, MTLS URL construction, and server config retrieval. Comprehensive unit tests cover cert validation, URL parsing, and bootstrap pathways.
Certificate Enrollment & Management client/internal/tunnel/certenroll.go, client/internal/tunnel/certenroll_test.go	Adds machine certificate validation (PEM parsing, SAN DNSNames, expiry checks, thumbprint computation), renewal decision logic, PowerShell enrollment script generation, certificate info parsing, expiry watching, and issuer fingerprint extraction. Extensive tests validate cert lifecycle and parsing.
Domain Join & DC Connectivity client/internal/tunnel/domainjoin.go, client/internal/tunnel/domainjoin_test.go	Implements DC reachability validation (LDAP, LDAPS, Kerberos, DNS, SMB, NTP), pre-join requirement checks, and domain join PowerShell script generation. Tests cover port connectivity, timeout handling, and join readiness states.
Management Server mTLS Configuration management/internals/server/config/config.go, management/internals/server/boot.go	Extends HttpServerConfig with mTLS fields (enabled flag, port, CA cert/dir, strict mode, domain-to-account mappings); refactors gRPC server initialization to conditionally load mTLS config and integrate interceptors.
mTLS Authentication & Validation management/internals/server/mtls_auth.go, management/internals/server/mtls_auth_test.go	Implements comprehensive mTLS authentication layer: interceptors for unary/stream calls, identity extraction from TLS certificates (SAN DNSNames, domain parsing, issuer validation), peer type determination (machine/user), and template OID/name parsing. Extensive tests validate identity extraction, domain mapping, and OID decoding.
Dedicated mTLS Server management/internals/server/mtls_server.go, management/internals/server/server.go	Introduces standalone mTLS-only gRPC server on separate port (default 33074) with CA pool loading, TLS configuration, and lifecycle management; integrates into main server startup/shutdown.
Machine Tunnel RPC Handlers management/internals/shared/grpc/machine_tunnel.go	Implements mTLS-secured gRPC methods: RegisterMachinePeer (peer registration with issuer validation), SyncMachinePeer (placeholder), GetMachineRoutes (DC routes), ReportMachineStatus (status acknowledgment). Includes peer metadata extraction and audit field enrichment.
Shared mTLS Utilities management/internals/shared/mtls/{identity,dnslabel}.go, management/internals/shared/mtls/*_test.go	Provides mTLS identity struct with multi-tenant fields, context helpers, issuer CA validation logic; implements RFC 1123-compliant DNS label generation with SHA-256 hash suffix, validation, sanitization, and collision detection.
Protocol Definitions shared/management/proto/management.proto	Adds new machine tunnel RPC methods (RegisterMachinePeer, SyncMachinePeer, GetMachineRoutes, ReportMachineStatus) and supporting message types (MachineIdentity, MachineRegisterRequest/Response, etc.); updates EncryptedMessage with wgPubKey field.
Peer Metadata Extensions management/server/peer.go, management/server/peer/peer.go	Integrates mTLS DNS label generation from cert domain/hostname; adds mTLS audit metadata fields to PeerSystemMeta (PeerType, AuthMethod, CertDNSName, CertDomain, CertIssuerFP, CertSerial, CertTemplate, auth timestamps).
Windows PowerShell Bootstrap Scripts scripts/bootstrap-new-client.ps1, scripts/reset-netbird-machine.ps1, scripts/reinstall-and-test.ps1, scripts/verify-nrpt-cleanup.ps1	Comprehensive automation suite: bootstrap orchestrates Phase 1→2 workflow (NTP sync, tunnel setup, DC connectivity, domain join, cert enrollment); reset cleans service/interface/NRPT/firewall; reinstall validates service/interface startup; verify-nrpt ensures cleanup.
Lab Setup & Testing Scripts scripts/lab/{setup-lab-ca,test-client-enrollment,verify-lab-ca}.ps1, scripts/lab/autounattend.xml	Provides lab infrastructure automation: setup-lab-ca installs AD CS and creates NetBirdMachine template with auto-enrollment GPO; test-client-enrollment validates machine cert enrollment via scheduled task; verify-lab-ca checks CA readiness; autounattend.xml automates Windows Server 2025 Datacenter deployment and OpenSSH setup.
Architecture & Design Documentation docs/ADR-001-mTLS-Port-Strategy.md, docs/ADR-002-CNG-Signer-Interface.md	ADR-001 documents mTLS port strategy (single port with per-method routing vs dual ports decision); ADR-002 specifies Windows CNG-based crypto.Signer for non-exportable machine certificates (API surface, Windows API calls, test requirements).
Spike Implementations spike/cng-signer/{main,go.mod}, spike/san-parser/{main,go.mod}	Proof-of-concept implementations: CNG signer demonstrates crypto.Signer integration with Windows certificate store and NCryptSignHash for RSA signing; SAN parser extracts certificate metadata (DNSNames, template OID/name, peer type) from AD CS certificates.
Test Certificates & Keys test/certs/{ca,client,server}.{crt,key,csr,cnf,srl}	Adds test certificate infrastructure: CA, client, and server certificates with SAN extensions, private keys, CSR configs, and CA serial tracking for mTLS testing.
Minor Test Updates management/internals/shared/grpc/conversion_test.go	Adds nolint directive to suppress deprecation warning for existing assertion.
Dockerfile management/Dockerfile.multistage	Introduces multi-stage Dockerfile for management component: builder stage compiles netbird-mgmt binary; runtime stage packages binary into minimal Ubuntu 24.04 image.

Sequence Diagram(s)

sequenceDiagram
    actor Client as Windows Client
    participant Phase1 as Bootstrap Phase 1<br/>(Setup-Key)
    participant Mgmt as Management Server<br/>(Port 443)
    participant CA as Certificate Authority<br/>(AD CS)
    participant Phase2 as Bootstrap Phase 2<br/>(mTLS)
    participant Tunnel as MTLS Server<br/>(Port 33074)

    Client->>Phase1: Bootstrap(cfg) with Setup-Key
    Phase1->>Mgmt: Connect via standard mgmt client
    Mgmt->>Phase1: Validate Setup-Key & login/register
    Phase1->>Client: Return peer config & netbird config
    Client->>Client: Store peer config
    
    rect rgba(200, 150, 100, 0.5)
    Note over Client,CA: Phase 1 Complete - Tunnel established
    Client->>Client: Initiate domain join workflow
    Client->>CA: Request machine certificate via certreq
    CA->>CA: Validate request (template, auto-enrollment)
    CA->>Client: Issue machine certificate
    Client->>Client: Store cert in Windows cert store
    end
    
    Client->>Phase2: Bootstrap(cfg) with machine cert
    Phase2->>Phase2: Validate cert (SAN, expiry, thumbprint)
    Phase2->>Tunnel: mTLS connect with client cert
    Tunnel->>Tunnel: Verify client certificate
    Tunnel->>Tunnel: Extract identity from SAN/Extensions<br/>(hostname, domain, issuer, template)
    Phase2->>Tunnel: RegisterMachinePeer(identity + pubkey)
    Tunnel->>Mgmt: Validate issuer CA & account mapping
    Mgmt->>Tunnel: Account/domain validation result
    Tunnel->>Tunnel: Register machine peer with audit metadata
    Tunnel->>Phase2: Return bootstrap result<br/>(peer config, DC routes, DNS)
    Phase2->>Client: Complete Phase 2 setup
    Client->>Client: Update config with mTLS settings

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• [management] pass config to controller #4807 — Extends controller/gRPC configuration with additional HTTP/device-flow config parameters and ToSyncResponse plumbing, overlapping with management server config and protocol updates in this PR.
• [client,management] Rewrite the SSH feature #4015 — Involves substantial client/server SSH subsystem refactoring (SSH config, BuildManager API, proto definitions) that parallels the architectural changes to authentication and peer registration infrastructure in this PR.

Poem

🐰 A rabbit hops through tunnels secure,
With certs and keys, a lock so pure,
Two phases dance—first Setup, then mTLS grace,
Domain joins spinning at a faster pace,
Windows machines now trust the way,
Pre-login magic saves the day! ✨

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sonarqubecloud]

Quality Gate failed

Failed conditions
12 New issues
3 Security Hotspots
C Security Rating on New Code (required ≥ A)
10 New Code Smells (required ≤ 0)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE