[PR #5175] [CLOSED] feat(scripts): T-5.4 Bootstrap Script v2.0 with Smart Selection #27280

Closed
opened 2026-08-05 07:08:28 -04:00 by saavagebueno · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/netbirdio/netbird/pull/5175
Author: @obtFusi
Created: 1/25/2026
Status: Closed

Base: mainHead: feature/t-5.4-bootstrap-script


📝 Commits (10+)

  • dfcaebe ci: add GitHub configuration from network-agent pattern
  • 3d1defe Merge pull request #1 from obtFusi/ci/github-config
  • b036814 feat(auth): Add mTLS authentication for Machine Tunnel (S-1 Spikes)
  • 634bd3c chore: add AUDIT files to gitignore
  • 5357588 feat(spike): Add S-1 Windows mTLS spikes - CNG signer and SAN parser
  • e594b07 feat(lab): Add CA bootstrap and verification scripts
  • f52cd3d fix(lab): Fix verify-lab-ca.ps1 parsing bugs
  • 6f72ca7 feat(proto): Generate Go code for Machine Tunnel RPCs
  • a4deec3 feat(mtls): Add per-account AllowedDomains for multi-tenant isolation
  • 648b532 feat(mtls): Add Machine Tunnel RPC handlers (T-3.6)

📊 Changes

61 files changed (+11073 additions, -1912 deletions)

View changed files

.githooks/pre-commit (+31 -0)
.github/ISSUE_TEMPLATE/bug_report.md (+29 -0)
.github/ISSUE_TEMPLATE/config.yml (+8 -0)
.github/ISSUE_TEMPLATE/epic.md (+39 -0)
📝 .github/ISSUE_TEMPLATE/feature_request.md (+2 -2)
.github/ISSUE_TEMPLATE/story.md (+32 -0)
.github/ISSUE_TEMPLATE/task.md (+31 -0)
.github/dependabot.yml (+31 -0)
.github/workflows/auto-label.yml (+97 -0)
.github/workflows/pr-lint.yml (+36 -0)
📝 .gitignore (+48 -1)
📝 Makefile (+51 -2)
client/internal/tunnel/bootstrap.go (+470 -0)
client/internal/tunnel/bootstrap_test.go (+319 -0)
client/internal/tunnel/certenroll.go (+451 -0)
client/internal/tunnel/certenroll_test.go (+540 -0)
client/internal/tunnel/domainjoin.go (+346 -0)
client/internal/tunnel/domainjoin_test.go (+267 -0)
docs/ADR-001-mTLS-Port-Strategy.md (+139 -0)
docs/ADR-002-CNG-Signer-Interface.md (+132 -0)

...and 41 more files

📄 Description

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.


🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/netbirdio/netbird/pull/5175 **Author:** [@obtFusi](https://github.com/obtFusi) **Created:** 1/25/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `feature/t-5.4-bootstrap-script` --- ### 📝 Commits (10+) - [`dfcaebe`](https://github.com/netbirdio/netbird/commit/dfcaebe41c86a8aadccc35876b55a2f4d8361bed) ci: add GitHub configuration from network-agent pattern - [`3d1defe`](https://github.com/netbirdio/netbird/commit/3d1defea7cece943ec2b11e760478d0c524ae62b) Merge pull request #1 from obtFusi/ci/github-config - [`b036814`](https://github.com/netbirdio/netbird/commit/b036814fdcdf153323cefc3765c9fd40ae428084) feat(auth): Add mTLS authentication for Machine Tunnel (S-1 Spikes) - [`634bd3c`](https://github.com/netbirdio/netbird/commit/634bd3c19ec7831c3390ba88b3435f16ed626b87) chore: add AUDIT files to gitignore - [`5357588`](https://github.com/netbirdio/netbird/commit/535758810ff5885e4444ac30a8b54d7301844af4) feat(spike): Add S-1 Windows mTLS spikes - CNG signer and SAN parser - [`e594b07`](https://github.com/netbirdio/netbird/commit/e594b07f096b340c63b361b24e13d47105d39203) feat(lab): Add CA bootstrap and verification scripts - [`f52cd3d`](https://github.com/netbirdio/netbird/commit/f52cd3d7880e02974d826c5eeb8f55721beef64d) fix(lab): Fix verify-lab-ca.ps1 parsing bugs - [`6f72ca7`](https://github.com/netbirdio/netbird/commit/6f72ca78a1a3817d35ee4078ec2282ab55c61ea5) feat(proto): Generate Go code for Machine Tunnel RPCs - [`a4deec3`](https://github.com/netbirdio/netbird/commit/a4deec3109066e55f11c61f5d999df84a4c2ad4c) feat(mtls): Add per-account AllowedDomains for multi-tenant isolation - [`648b532`](https://github.com/netbirdio/netbird/commit/648b532034cf9d829fdfdad3dab6034fbf0e04a8) feat(mtls): Add Machine Tunnel RPC handlers (T-3.6) ### 📊 Changes **61 files changed** (+11073 additions, -1912 deletions) <details> <summary>View changed files</summary> ➕ `.githooks/pre-commit` (+31 -0) ➕ `.github/ISSUE_TEMPLATE/bug_report.md` (+29 -0) ➕ `.github/ISSUE_TEMPLATE/config.yml` (+8 -0) ➕ `.github/ISSUE_TEMPLATE/epic.md` (+39 -0) 📝 `.github/ISSUE_TEMPLATE/feature_request.md` (+2 -2) ➕ `.github/ISSUE_TEMPLATE/story.md` (+32 -0) ➕ `.github/ISSUE_TEMPLATE/task.md` (+31 -0) ➕ `.github/dependabot.yml` (+31 -0) ➕ `.github/workflows/auto-label.yml` (+97 -0) ➕ `.github/workflows/pr-lint.yml` (+36 -0) 📝 `.gitignore` (+48 -1) 📝 `Makefile` (+51 -2) ➕ `client/internal/tunnel/bootstrap.go` (+470 -0) ➕ `client/internal/tunnel/bootstrap_test.go` (+319 -0) ➕ `client/internal/tunnel/certenroll.go` (+451 -0) ➕ `client/internal/tunnel/certenroll_test.go` (+540 -0) ➕ `client/internal/tunnel/domainjoin.go` (+346 -0) ➕ `client/internal/tunnel/domainjoin_test.go` (+267 -0) ➕ `docs/ADR-001-mTLS-Port-Strategy.md` (+139 -0) ➕ `docs/ADR-002-CNG-Signer-Interface.md` (+132 -0) _...and 41 more files_ </details> ### 📄 Description ## 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 - [x] Script mit allen 8 Schritten - [x] DC-Connectivity Prüfung vor Join - [x] NTP-Sync vor Join (Kerberos) - [x] Smart Selection Config (kein Thumbprint) - [x] Warnung: "REVOKE setup-key!" - [x] Error-Handling für jeden Schritt - [x] Integration Test: WhatIf Mode auf Windows VM - [x] Keine Secrets in Logs (Setup-Key redacted) - [x] Script-Signatur via Authenticode (dokumentiert) - [x] Checksum-Verifikation dokumentieren Closes #50 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## 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 <sub>✏️ Tip: You can customize this high-level summary in your review settings.</sub> <!-- end of auto-generated comment: release notes by coderabbit.ai --> --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
saavagebueno added the pull-request label 2026-08-05 07:08:28 -04:00
Sign in to join this conversation.
No Label pull-request
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: DYNR/netbird#27280