🛡️ Network Profile History Manager — Sentinel

Enterprise-Grade, Safety-First Windows Network Profile & Hardware Adapter Manager

English • فارسی (Persian)

Sentinel solves the chronic Windows network location profile clutter, firewall misclassifications, and ghost adapter accumulation across physical and virtual network interfaces with zero risk of breaking connectivity.

---

📑 Table of Contents

• The Problem Sentinel Solves
• Key Features
• Architecture & Safety Protocol
• Installation & Getting Started
• Usage Guide
  • 1. PowerShell Pipeline Cmdlets
  • 2. Interactive Console Dashboard (TUI)
  • 3. Headless CLI Automation
• Real-World Scenarios
• Safety Model & Protections
• Verification & Development Test Suite
• Contributing
• License

---

⚡ The Problem Sentinel Solves

Whenever you plug into a USB-C dock, roam across Wi-Fi access points, tether via cellular hotspot, or spin up WSL2, Docker, or Hyper-V, Windows permanently registers an unmanaged location profile in:

HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\NetworkList

Over time, this causes:

1. Network Profile Creep: Accumulation of duplicate phantom profiles (Network, Network 2, Network 3... 45) that clutter the registry and slow down Windows Network Location Awareness (NLA) detection.
2. Dev-Environment Firewall Lockouts: WSL2, Hyper-V default switches, and Docker bridges frequently default to the Public profile, silently blocking inbound dev ports (3000, 8080, 5432, 22) and forcing developers to either turn off their firewall or wrestle with complex registry hacks.
3. Dangerous Ad-Hoc Scripts: Traditional community scripts blindly nuke registry keys (Remove-Item HKLM:\...), severing active VPN tunnels, corrupting NLM caches, and lacking any rollback mechanism.

Sentinel eliminates these pain points with an enterprise-grade, cryptographically verified, fail-closed safety engine.

---

✨ Key Features

Feature	Description
🔌 Physical NIC & MAC Binding	Automatically correlates active and stored profiles with physical NICs (Realtek, Intel AX211) and virtual switches (WSL2, Hyper-V, Tailscale, WireGuard).
📡 Gateway MAC (BSSID) Extraction	Unmarshals 6-byte binary DefaultGatewayMac signatures to reveal the physical gateway MAC / router BSSID.
🛡️ Fail-Closed Active Guard	Correlates COM Network List Manager (NLM), Get-NetConnectionProfile, and interface witnesses by both Name AND InstanceID GUID to prevent accidental disconnection.
🔄 Pipeline-First PowerShell Module	Native cmdlets: Get-SentinelProfile (gsp), Set-SentinelProfile (ssp), Remove-SentinelProfile (rsp), Get-SentinelDiagnostic, and Invoke-SentinelSafeCleanup.
💾 Cryptographic Rollback Engine	Creates full .reg backup packages with SHA-256 sidecars, machine-identity cryptographic binding, and target-only rollback bundles.
📝 Atomic Transaction Journaling	Maintains durable state machines (.inprogress.json ➔ .json) with an interactive Recovery Center for interrupted workflows.
🩺 Non-Destructive Safety Doctor	Verifies ACL permissions, 64-bit registry isolation, reparse-point security, and data consistency without making mutations.

---

🏗️ Architecture & Safety Protocol

All mutations executed by Sentinel adhere to a strict, atomic transaction protocol:

┌───────────┐     ┌───────────┐     ┌──────────────────────┐     ┌─────────────┐     ┌───────────┐     ┌────────────┐
│  OBSERVE  │ ──► │ VALIDATE  │ ──► │ FULL BACKUP / BUNDLE │ ──► │   JOURNAL   │ ──► │  MUTATE   │ ──► │   VERIFY   │
└───────────┘     └───────────┘     └──────────────────────┘     └─────────────┘     └───────────┘     └────────────┘
 Capture Subtree   Fail-Closed Guard  Generate .reg & Target     Atomic Journal      Execute Native    TOCTOU Target
 & NIC Witnesses   Safety Invariants  Cryptographic Sidecar      Persistence         Registry Ops      State Check

Storage Security Enclave

Recovery artifacts and rollback bundles are stored in an ACL-hardened enclave: %ProgramData%\NetworkProfileHistoryManager\Sentinel-v6

• SID-Based Hardening: Strictly restricted to NT AUTHORITY\SYSTEM and BUILTIN\Administrators (FullControl), with all inheritance stripped.
• Ancestor Reparse-Point Validation: Rejects symbolic links, junctions, and mount points across the entire path hierarchy to prevent privilege escalation or directory traversal.
• Machine Identity Binding: Backup packages include a cryptographic hash of the host MachineGuid, preventing cross-machine restore errors.

---

📦 Installation & Getting Started

Option 1: PowerShell Module (Recommended)

Clone the repository and import the module directly:

# Clone the repository
git clone https://github.com/NetworkProfileSentinel/NetworkProfileSentinel.git
cd NetworkProfileSentinel

# Import module in an elevated PowerShell prompt
Import-Module .\NetworkProfileSentinel.psd1 -Force

Option 2: Portable Executable Script

Run the self-contained script directly from PowerShell (Run as Administrator):

& .\NetworkProfileHistoryManager.ps1

Or double-click NetworkProfileHistoryManager.bat from Windows Explorer to launch with automatic UAC elevation.

---

🚀 Usage Guide

1. PowerShell Pipeline Cmdlets (Recommended)

Sentinel includes idiomatic cmdlets designed to integrate seamlessly into PowerShell scripts and automation pipelines.

Inspect Network Profiles

# Get all profiles as typed Sentinel.NetworkProfile objects
Get-SentinelProfile

# Filter profiles by keyword (name, category, or adapter)
Get-SentinelProfile -Filter "vEthernet"
Get-SentinelProfile -Filter "Public"

# Short alias equivalent
gsp -Filter "Ethernet"

Dev Workflow: Elevate WSL / Docker Adapters

# Elevate all virtual switch profiles (WSL2, Docker, Hyper-V) to Private
Get-SentinelProfile | Where-Object { $_.IsVirtual -and $_.Category -eq 'Public' } | Set-SentinelProfile -Category Private

Safe Pipeline Cleanup

# Simulate cleanup of stale profiles older than 180 days with -WhatIf
Get-SentinelProfile | Where-Object { $_.AgeDays -gt 180 -and -not $_.IsCurrent } | Remove-SentinelProfile -WhatIf

# Execute verified removal
Get-SentinelProfile | Where-Object { $_.AgeDays -gt 180 -and -not $_.IsCurrent } | Remove-SentinelProfile

System & Safety Diagnostics

# Run non-destructive Safety Doctor and output structured table
Get-SentinelDiagnostic -Format Table

---

2. Interactive Console Dashboard (TUI)

Launch Sentinel interactively to navigate the menu-driven dashboard:

& .\NetworkProfileHistoryManager.ps1

========================================================================
           NETWORK PROFILE HISTORY MANAGER — SENTINEL v6.1
========================================================================
  Active Network : Network 45 [Ethernet] (Realtek PCIe GbE Family)
  Stored Profiles: 8 total (1 Active, 0 Managed, 7 Stale Candidates)
  Safety Status  : GREEN (All fail-closed guards verified)
------------------------------------------------------------------------
  [S]  Safe Cleanup (Threshold: 180 days)
  [D]  Safety Doctor (Non-destructive diagnostics)
  [1]  Profile Inventory (Search & view with hardware NIC bindings)
  [C]  Configure Profile (Switch Public/Private or rename)
  [2]  Delete One (Reviewed single-profile removal)
  [3]  Keep Selected (Delete all except chosen profiles)
  [4]  Delete All (Emergency cleanup of all stored history)
  [5]  Create Backup (Verified .reg export with SHA-256 sidecar)
  [6]  Restore Backup (Merge restore with machine binding check)
  [R]  Recovery Center (Inspect interrupted journals)
  [0]  Exit
========================================================================

---

3. Headless CLI Automation

For automated deployments, remote administration (WinRM / SSH), and scheduled maintenance:

# Display inventory table
.\NetworkProfileHistoryManager.ps1 -Inventory

# Output inventory as JSON
.\NetworkProfileHistoryManager.ps1 -Inventory -Format Json

# Non-destructive preview of Safe Cleanup (WhatIf mode)
.\NetworkProfileHistoryManager.ps1 -SafeCleanup -StaleDays 180 -WhatIf

# Execute Safe Cleanup with verified backup package
.\NetworkProfileHistoryManager.ps1 -SafeCleanup -StaleDays 180 -Force

# Change network category via CLI
.\NetworkProfileHistoryManager.ps1 -SetCategory "Network 45" -Category Private -Force

# Rename a profile via CLI
.\NetworkProfileHistoryManager.ps1 -RenameProfile 1 -NewName "Office High-Speed" -Force

# Run Safety Doctor diagnostic check
.\NetworkProfileHistoryManager.ps1 -Doctor

---

💡 Real-World Scenarios

Scenario A: Unlocking Local Dev Services on WSL2 / Docker

• Issue: Windows NLA categorizes vEthernet (WSL) as an Unidentified Public Network, dropping port 3000 (Node/React), 8000 (Python), and 22 (SSH).
• Sentinel Solution:

  Get-SentinelProfile | Where-Object { $_.IsVirtual } | Set-SentinelProfile -Category Private

  Host-to-container connections are immediately permitted without exposing physical Wi-Fi interfaces.

Scenario B: Enterprise Fleet & Laptop Hygiene via Intune

• Issue: Mobile users accumulate 50+ phantom Wi-Fi profiles from airports and hotels, resulting in registry bloat and slow network transitions.
• Sentinel Solution:

  .\NetworkProfileHistoryManager.ps1 -SafeCleanup -StaleDays 90 -Force

  Automatically cleans obsolete networks while fail-closed guards preserve corporate VPN and domain networks.

---

🔒 Safety Model & Protections

Safe Cleanup is deliberately conservative. Automated deletion is strictly blocked whenever current-network evidence, domain state, registry stability, or profile structure is uncertain:

• Unconditional Protections:
  • Active connections (matched by GUID, Name, and Adapter)
  • DomainAuthenticated profiles (Category = 2)
  • Joined-domain DNS suffix matches
  • Managed profiles and signatures (Managed = 1)
• Structural Uncertainty Guard:
  • Profiles with missing/corrupted signatures, malformed GUIDs, or timestamp anomalies (DateCreated > DateLastConnected) are permanently protected from automated removal.

---

🧪 Verification & Development Test Suite

Sentinel includes a comprehensive test suite built on Pester:

# Run the test suite under Windows PowerShell 5.1
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\tests\Run-Tests.ps1

# Run under PowerShell 7+
pwsh.exe -NoProfile -ExecutionPolicy Bypass -File .\tests\Run-Tests.ps1

========================================================================
Tests completed in 20.07s
Passed: 45 Failed: 0 Skipped: 0 Pending: 0 Inconclusive: 0
PASS: 45 Pester tests completed.
========================================================================

All 45 contracts validate:

• 4,096 randomized safety states and invariant guarantees.
• Fail-closed current-network witness degradation.
• TOCTOU target fingerprint validation and rollback replay.
• Reparse-point traversal defenses.
• Native 64-bit registry and binary MAC parsing.
• Pipeline cmdlets, -WhatIf, and module manifest integrity.

---

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository and create your feature branch: git checkout -b feature/amazing-feature.
2. Ensure all changes adhere strictly to the Fail-Closed Safety Invariants.
3. Run the full Pester test suite (.\tests\Run-Tests.ps1) to ensure 100% test passing.
4. Update SHA-256.txt with the cryptographic hash of NetworkProfileHistoryManager.ps1 if modified.
5. Open a Pull Request with a detailed explanation of changes.

---

📜 License

Distributed under the MIT License. See LICENSE for details.

---

_{Built with precision for systems architects, DevOps engineers, and Windows administrators.}