diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..27ee794 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,53 @@ +name: CI + +on: + push: + branches: [ main, improve-and-package ] + pull_request: + branches: [ main ] + +jobs: + test: + name: Pester (${{ matrix.os }}) + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [ ubuntu-latest, macos-latest, windows-latest ] + + steps: + - uses: actions/checkout@v4 + + - name: Validate module manifest + shell: pwsh + run: Test-ModuleManifest ./NetDiagram-PS/NetDiagram-PS.psd1 + + - name: Install Pester + shell: pwsh + run: Install-Module -Name Pester -MinimumVersion 5.0.0 -Force -Scope CurrentUser -SkipPublisherCheck + + - name: Run Pester tests + shell: pwsh + run: | + $config = New-PesterConfiguration + $config.Run.Path = './tests/NetDiagram.Tests.ps1' + $config.Output.Verbosity = 'Detailed' + $config.Run.Exit = $true + Invoke-Pester -Configuration $config + + lint: + name: PSScriptAnalyzer + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Install PSScriptAnalyzer + shell: pwsh + run: Install-Module -Name PSScriptAnalyzer -Force -Scope CurrentUser + + - name: Run analyzer (fail on errors) + shell: pwsh + run: | + $results = Invoke-ScriptAnalyzer -Path ./NetDiagram-PS -Recurse -Severity Error + $results | Format-Table -AutoSize + if ($results) { throw "PSScriptAnalyzer reported $($results.Count) error(s)" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 50297f3..07b387a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,31 @@ All notable changes to NetDiagram-PS will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [1.2.0] - 2025-11-02 + +### Fixed +- **SNMP discovery on macOS/Linux** - `Invoke-SnmpWalk` hard-coded `snmpwalk.exe`, so + SNMP neighbor discovery never worked on the platforms added in 1.1.0. It now resolves + `snmpwalk` (Unix) or `snmpwalk.exe` (Windows) from PATH. +- Pester suite no longer asserts a stale hard-coded module version; the version test now + reads the manifest, and the module path is built with `Join-Path` (no literal backslash), + so tests run on macOS/Linux as well as Windows. + +### Changed +- **Minimum PowerShell raised to 7.4.** The reachability functions use + `Test-Connection -TimeoutSeconds`, which only exists in PowerShell 7.4+. The manifest + previously advertised 7.0, on which those calls error. +- Added `CompatiblePSEditions = @('Core')` to the manifest. +- LICENSE copyright holder and README license section aligned with the manifest (MIT, + Jacob Yoby). + +### Added +- Additional Pester tests for `Get-MACVendor`, `Get-CommonSNMPStrings`, + `Resolve-IPHostname`, `Invoke-SnmpWalk` (missing-binary path), and the private + `Test-IPInSubnet` helper. +- `PUBLISHING.md` documenting the PowerShell Gallery release process. +- GitHub Actions workflow running the Pester suite on Windows, macOS, and Linux. + ## [1.1.0] - 2025-10-31 ### Added diff --git a/LICENSE b/LICENSE index 728fb1f..2da1ae2 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2025 NetDiagram-PS Contributors +Copyright (c) 2025 Jacob Yoby Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/NetDiagram-PS/NetDiagram-PS.psd1 b/NetDiagram-PS/NetDiagram-PS.psd1 index 1656aaf..8707496 100644 --- a/NetDiagram-PS/NetDiagram-PS.psd1 +++ b/NetDiagram-PS/NetDiagram-PS.psd1 @@ -1,12 +1,13 @@ @{ RootModule = 'NetDiagram-PS.psm1' - ModuleVersion = '1.1.0' + ModuleVersion = '1.2.0' GUID = 'a8f7e9c4-6d2b-4a1c-9e3f-7b8c9d0e1f2a' Author = 'Jacob Yoby' CompanyName = 'NetDiagram-PS' Copyright = '(c) 2025 Jacob Yoby. All rights reserved.' Description = 'Automatically discover your network topology and generate professional draw.io diagrams with Cisco icons, SNMP discovery, and multi-level device detection.' - PowerShellVersion = '7.0' + PowerShellVersion = '7.4' + CompatiblePSEditions = @('Core') FunctionsToExport = @( # Core inventory and topology @@ -41,7 +42,7 @@ LicenseUri = 'https://github.com/jacobyoby/PSNetMap/blob/main/LICENSE' ProjectUri = 'https://github.com/jacobyoby/PSNetMap' IconUri = '' - ReleaseNotes = 'Version 1.1.0 - Cross-platform support for Windows, macOS, and Linux with native command integration' + ReleaseNotes = 'Version 1.2.0 - Fixed SNMP discovery on macOS/Linux (snmpwalk binary resolution), raised the minimum PowerShell version to 7.4 (Test-Connection -TimeoutSeconds), added CompatiblePSEditions, expanded the Pester suite, and documented the PowerShell Gallery publish path.' } } } diff --git a/NetDiagram-PS/NetDiagram-PS.psm1 b/NetDiagram-PS/NetDiagram-PS.psm1 index a6d7f16..f1dda37 100644 --- a/NetDiagram-PS/NetDiagram-PS.psm1 +++ b/NetDiagram-PS/NetDiagram-PS.psm1 @@ -1,4 +1,4 @@ -#Requires -Version 7.0 +#Requires -Version 7.4 <# .SYNOPSIS @@ -11,7 +11,7 @@ Set-StrictMode -Version Latest $ErrorActionPreference = 'Stop' # Module-level variables -$script:ModuleVersion = '1.1.0' +$script:ModuleVersion = '1.2.0' #region Helper Functions @@ -217,9 +217,10 @@ function Test-DeviceReachability { function Invoke-SnmpWalk { <# .SYNOPSIS - Invokes snmpwalk.exe against a target device + Invokes the net-snmp snmpwalk binary against a target device .DESCRIPTION - Calls snmpwalk.exe directly (must be in PATH) with specified OID and credentials. + Calls snmpwalk directly (must be in PATH) with specified OID and credentials. + Resolves 'snmpwalk' on macOS/Linux and 'snmpwalk.exe' on Windows. Returns raw output lines. .PARAMETER TargetIP IP address to query @@ -252,10 +253,18 @@ function Invoke-SnmpWalk { [int]$TimeoutSeconds = 2 ) - # Check if snmpwalk.exe is available - $snmpWalkPath = Get-Command -Name 'snmpwalk.exe' -ErrorAction SilentlyContinue - if (-not $snmpWalkPath) { - throw "snmpwalk.exe not found in PATH. Please install net-snmp tools." + # Locate the snmpwalk binary. It is 'snmpwalk.exe' on Windows and 'snmpwalk' + # on macOS/Linux, so probe for both rather than assuming the Windows name. + $snmpWalkCmd = $null + foreach ($candidate in @('snmpwalk', 'snmpwalk.exe')) { + $found = Get-Command -Name $candidate -ErrorAction SilentlyContinue + if ($found) { + $snmpWalkCmd = $found.Source + break + } + } + if (-not $snmpWalkCmd) { + throw "snmpwalk not found in PATH. Please install net-snmp tools (brew install net-snmp, apt install snmp, or choco install net-snmp)." } try { @@ -267,12 +276,12 @@ function Invoke-SnmpWalk { $OID ) - Write-Verbose "Running: snmpwalk.exe $($arguments -join ' ')" + Write-Verbose "Running: $snmpWalkCmd $($arguments -join ' ')" - $output = & snmpwalk.exe @arguments 2>&1 + $output = & $snmpWalkCmd @arguments 2>&1 if ($LASTEXITCODE -ne 0) { - Write-Warning "snmpwalk.exe failed for $TargetIP with exit code $LASTEXITCODE" + Write-Warning "snmpwalk failed for $TargetIP with exit code $LASTEXITCODE" return @() } @@ -520,11 +529,14 @@ function Test-IPInSubnet { $ipValue = [System.BitConverter]::ToUInt32($ipBytes, 0) $networkValue = [System.BitConverter]::ToUInt32($networkBytes, 0) + # Build the prefix mask. Compute in UInt64 to avoid the int overflow that + # '[uint32]0xFFFFFFFF -shl n' triggers (0xFFFFFFFF parses as int -1), then + # truncate back to 32 bits. $mask = if ($prefixLength -eq 0) { [uint32]0 } else { - [uint32]0xFFFFFFFF -shl (32 - $prefixLength) + [uint32]((([uint64]4294967295) -shl (32 - $prefixLength)) -band [uint64]4294967295) } return (($ipValue -band $mask) -eq ($networkValue -band $mask)) diff --git a/PUBLISHING.md b/PUBLISHING.md new file mode 100644 index 0000000..a597d7d --- /dev/null +++ b/PUBLISHING.md @@ -0,0 +1,86 @@ +# Publishing NetDiagram-PS + +This document describes how NetDiagram-PS is validated and published to the +[PowerShell Gallery](https://www.powershellgallery.com/). + +## Prerequisites + +- PowerShell 7.4+ +- A PowerShell Gallery account and an **API key** (Account → API Keys) +- Modules used for validation/publishing: + + ```powershell + Install-Module -Name Pester -MinimumVersion 5.0.0 -Force + Install-Module -Name PSScriptAnalyzer -Force + # PowerShellGet v2 ships with PowerShell; Publish-Module comes from it + ``` + +## 1. Validate the manifest + +```powershell +Test-ModuleManifest ./NetDiagram-PS/NetDiagram-PS.psd1 +``` + +This must succeed with no errors. It confirms the manifest parses, the +`RootModule` resolves, and `FunctionsToExport` matches the module. + +## 2. Lint + +```powershell +Invoke-ScriptAnalyzer -Path ./NetDiagram-PS -Recurse -Severity Warning,Error +``` + +Resolve anything at `Error` severity before publishing. Warnings are advisory. + +## 3. Run the test suite + +```powershell +Invoke-Pester -Path ./tests/NetDiagram.Tests.ps1 -Output Detailed +``` + +All tests must pass on the target platform(s). + +## 4. Dry-run the publish + +`Publish-Module` has no true `-WhatIf` for content, so verify what will be +packed by pointing at the module folder and confirming the version is new: + +```powershell +$manifest = Import-PowerShellDataFile ./NetDiagram-PS/NetDiagram-PS.psd1 +$manifest.ModuleVersion # must be greater than the version already on the Gallery +Find-Module NetDiagram-PS -ErrorAction SilentlyContinue # what's live now (if anything) +``` + +Bump `ModuleVersion` in `NetDiagram-PS.psd1` and add a `CHANGELOG.md` entry for +any release. The Gallery rejects re-publishing an existing version. + +## 5. Publish + +```powershell +$apiKey = '' # do NOT commit this +Publish-Module -Path ./NetDiagram-PS -NuGetApiKey $apiKey -Verbose +``` + +Notes: +- `-Path` points at the **module folder** (`NetDiagram-PS/`), not the repo root. +- The manifest's `PrivateData.PSData` already supplies `Tags`, `LicenseUri`, + `ProjectUri`, and `ReleaseNotes`, which populate the Gallery listing. +- After publishing, confirm with `Find-Module NetDiagram-PS`. + +## 6. Tag the release + +```powershell +git tag v +git push origin v +``` + +## Release checklist + +- [ ] `ModuleVersion` bumped in `NetDiagram-PS.psd1` +- [ ] `PrivateData.PSData.ReleaseNotes` updated +- [ ] `CHANGELOG.md` entry added +- [ ] `Test-ModuleManifest` passes +- [ ] `Invoke-ScriptAnalyzer` clean (no Errors) +- [ ] `Invoke-Pester` green +- [ ] `Publish-Module` succeeded and `Find-Module` shows the new version +- [ ] Git tag pushed diff --git a/README.md b/README.md index 9428a88..9a193e1 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ The wizard performs the following actions: ## Prerequisites -- **PowerShell 7.0+** (required, cross-platform) +- **PowerShell 7.4+** (required, cross-platform — 7.4 is the current LTS and provides `Test-Connection -TimeoutSeconds`) - Windows: https://aka.ms/powershell - macOS: `brew install --cask powershell` or download from https://aka.ms/powershell - Linux: Follow instructions at https://aka.ms/powershell @@ -47,6 +47,26 @@ The wizard performs the following actions: --- +## Installation + +### From PowerShell Gallery (once published) + +```powershell +Install-Module -Name NetDiagram-PS -Scope CurrentUser +Import-Module NetDiagram-PS +``` + +### From source (clone) + +```powershell +git clone https://github.com/jacobyoby/PSNetMap.git +Import-Module ./PSNetMap/NetDiagram-PS/NetDiagram-PS.psd1 +``` + +See [PUBLISHING.md](PUBLISHING.md) for how the module is packaged and released to the Gallery. + +--- + ## Usage ### Method 1: Quick Start Wizard (recommended) @@ -360,7 +380,7 @@ Contributions welcome! Please: ## License -This project is provided as-is for educational and professional use. +Released under the [MIT License](LICENSE). Copyright (c) 2025 Jacob Yoby. --- diff --git a/STRUCTURE.md b/STRUCTURE.md index 68cffb3..728fdb8 100644 --- a/STRUCTURE.md +++ b/STRUCTURE.md @@ -73,5 +73,5 @@ For the easiest experience, run the wizard: --- -**Last Updated:** 2025-11-01 -**Module Version:** 1.0.1 +**Last Updated:** 2025-11-02 +**Module Version:** 1.1.0 diff --git a/examples/New-NetworkDiagram.ps1 b/examples/New-NetworkDiagram.ps1 index 6ba4bf1..d617cf0 100644 --- a/examples/New-NetworkDiagram.ps1 +++ b/examples/New-NetworkDiagram.ps1 @@ -1,5 +1,5 @@ #!/usr/bin/env pwsh -#Requires -Version 7.0 +#Requires -Version 7.4 <# .SYNOPSIS diff --git a/tests/NetDiagram.Tests.ps1 b/tests/NetDiagram.Tests.ps1 index 7ecd33b..883e126 100644 --- a/tests/NetDiagram.Tests.ps1 +++ b/tests/NetDiagram.Tests.ps1 @@ -1,10 +1,13 @@ #Requires -Modules @{ ModuleName='Pester'; ModuleVersion='5.0.0' } BeforeAll { - # Import module - $modulePath = Join-Path $PSScriptRoot '..\NetDiagram-PS\NetDiagram-PS.psd1' + # Import module (Join-Path built cross-platform, no backslash literal) + $modulePath = Join-Path $PSScriptRoot '..' 'NetDiagram-PS' 'NetDiagram-PS.psd1' Import-Module $modulePath -Force + # Read the manifest so version assertions track the manifest instead of a hard-coded string + $script:Manifest = Import-PowerShellDataFile -Path $modulePath + # Setup test data directory $script:TestDataPath = Join-Path $PSScriptRoot 'TestData' if (-not (Test-Path $script:TestDataPath)) { @@ -38,7 +41,7 @@ Describe 'Module Import' { It 'Should import the module successfully' { $module = Get-Module -Name 'NetDiagram-PS' $module | Should -Not -BeNullOrEmpty - $module.Version | Should -Be '1.0.1' + $module.Version | Should -Be $script:Manifest.ModuleVersion } It 'Should export all required cmdlets' { @@ -385,3 +388,76 @@ Describe 'Defensive Coding Tests' { { Import-Inventory -Path $badJsonPath } | Should -Throw } } + +Describe 'Get-MACVendor' { + It 'Should resolve a known OUI to its vendor' { + $result = Get-MACVendor -MACAddress '00:1A:A0:12:34:56' + $result.Vendor | Should -Be 'Dell' + $result.OUI | Should -Be '00:1A:A0' + } + + It 'Should normalize MAC formats to colon-delimited uppercase' { + (Get-MACVendor -MACAddress '001aa0123456').MACAddress | Should -Be '00:1A:A0:12:34:56' + (Get-MACVendor -MACAddress '00-1a-a0-12-34-56').MACAddress | Should -Be '00:1A:A0:12:34:56' + } + + It 'Should report Unknown for an unmapped OUI' { + (Get-MACVendor -MACAddress 'FF:FF:FF:FF:FF:FF').Vendor | Should -Be 'Unknown' + } + + It 'Should flag a too-short MAC as invalid' { + (Get-MACVendor -MACAddress '00:1A').Vendor | Should -Be 'Invalid MAC' + } + + It 'Should accept pipeline input for multiple MACs' { + $results = @('00:1A:A0:00:00:00', '00:50:56:00:00:00') | Get-MACVendor + $results | Should -HaveCount 2 + $results[1].Vendor | Should -Be 'VMware' + } +} + +Describe 'Get-CommonSNMPStrings' { + It 'Should return the common default community strings' { + $strings = Get-CommonSNMPStrings + $strings | Should -Contain 'public' + $strings | Should -Contain 'private' + $strings.Count | Should -BeGreaterThan 5 + } +} + +Describe 'Resolve-IPHostname' { + It 'Should return a failure object for an unresolvable address' { + # 192.0.2.0/24 is TEST-NET-1 (RFC 5737) and never resolves + $result = Resolve-IPHostname -IPAddress '192.0.2.1' + $result.IPAddress | Should -Be '192.0.2.1' + $result.Success | Should -Be $false + } +} + +Describe 'Invoke-SnmpWalk' { + It 'Should throw a helpful error when the snmpwalk binary is missing' { + Mock Get-Command { $null } -ModuleName 'NetDiagram-PS' -ParameterFilter { $Name -like 'snmpwalk*' } + { Invoke-SnmpWalk -TargetIP '192.0.2.1' -Community 'public' } | + Should -Throw -ExpectedMessage '*snmpwalk not found*' + } +} + +Describe 'Test-IPInSubnet (private helper)' { + It 'Should match an IP inside its CIDR range' { + InModuleScope 'NetDiagram-PS' { + Test-IPInSubnet -IP '192.168.1.50' -CIDR '192.168.1.0/24' | Should -Be $true + } + } + + It 'Should reject an IP outside the CIDR range' { + InModuleScope 'NetDiagram-PS' { + Test-IPInSubnet -IP '192.168.2.50' -CIDR '192.168.1.0/24' | Should -Be $false + } + } + + It 'Should return false for a malformed CIDR' { + InModuleScope 'NetDiagram-PS' { + Test-IPInSubnet -IP '192.168.1.50' -CIDR 'not-a-cidr' | Should -Be $false + } + } +}