From 2a35ad7d6d9b30a759a19ee4da22e81265b1c379 Mon Sep 17 00:00:00 2001 From: jacobyoby Date: Tue, 8 Sep 2026 14:07:54 -0700 Subject: [PATCH] fix(snmp): mark parsed neighbors provisional --- NetDiagram-PS/NetDiagram-PS.psm1 | 60 ++++++++++++++-------- README.md | 10 ++-- tests/NetDiagram.Tests.ps1 | 87 ++++++++++++++++++++++++++++++++ 3 files changed, 130 insertions(+), 27 deletions(-) diff --git a/NetDiagram-PS/NetDiagram-PS.psm1 b/NetDiagram-PS/NetDiagram-PS.psm1 index e84ea15..6dd57ed 100644 --- a/NetDiagram-PS/NetDiagram-PS.psm1 +++ b/NetDiagram-PS/NetDiagram-PS.psm1 @@ -335,7 +335,9 @@ function Get-SnmpNeighbors { .DESCRIPTION Queries nodes for LLDP neighbor information via SNMP. Uses credential map to resolve community strings from SecretManagement. - Adds discovered edges to the topology with L2-SNMP confidence. + Adds discovered edges with provisional L2-SNMP-Heuristic confidence. The parser + does not assign verified L2-SNMP confidence because it does not fully correlate + structured LLDP/CDP table rows. NODE ELIGIBILITY: By default every node is queried EXCEPT nodes that have been explicitly marked unreachable (Reachable -eq $false). Nodes with unknown @@ -518,12 +520,12 @@ All SNMP attempts will be logged to verbose output. $targetIP = $null - # net-snmp renders an LLDP management address either as a dotted quad - # (sometimes prefixed 'IpAddress:') or as a 4-octet Hex-STRING. - if ($value -match '(?:IpAddress:\s*)?\b((?:25[0-5]|2[0-4]\d|1?\d?\d)(?:\.(?:25[0-5]|2[0-4]\d|1?\d?\d)){3})\b') { + # Only typed address values are eligible. Arbitrary STRING values can + # contain known IPs but are not evidence of a neighbor relationship. + if ($value -match '^IpAddress:\s*((?:25[0-5]|2[0-4]\d|1?\d?\d)(?:\.(?:25[0-5]|2[0-4]\d|1?\d?\d)){3})\s*$') { $targetIP = $matches[1] } - elseif ($value -match 'Hex-STRING:\s*([0-9A-Fa-f]{2})[ :]+([0-9A-Fa-f]{2})[ :]+([0-9A-Fa-f]{2})[ :]+([0-9A-Fa-f]{2})') { + elseif ($value -match '^Hex-STRING:\s*([0-9A-Fa-f]{2})[ :]+([0-9A-Fa-f]{2})[ :]+([0-9A-Fa-f]{2})[ :]+([0-9A-Fa-f]{2})\s*$') { $targetIP = @( [Convert]::ToInt32($matches[1], 16) [Convert]::ToInt32($matches[2], 16) @@ -552,7 +554,7 @@ All SNMP attempts will be logged to verbose output. TargetIP = $targetIP Label = $label Source = 'SNMP' - Confidence = 'L2-SNMP' + Confidence = 'L2-SNMP-Heuristic' } $null = $discoveredEdges.Add($edge) @@ -642,7 +644,8 @@ function Merge-Edges { Merges and deduplicates edge candidates .DESCRIPTION Deduplicates edges using sorted endpoints as key. - Prioritizes L2-SNMP confidence over L3-Inferred. + Prioritizes verified L2-SNMP, then provisional L2-SNMP-Heuristic, then + L3-Inferred. An SNMP source alone never promotes an edge to verified. Keeps first non-empty label. .PARAMETER Edges Array of edge objects to merge @@ -677,13 +680,30 @@ function Merge-Edges { $endpoints = @($edge.SourceIP, $edge.TargetIP) | Sort-Object $key = "$($endpoints[0])|$($endpoints[1])" + $incomingConfidence = if ($edge.PSObject.Properties['Confidence']) { + $edge.Confidence + } + elseif ($edge.PSObject.Properties['Source'] -and $edge.Source -eq 'SNMP') { + 'L2-SNMP-Heuristic' + } + else { + 'L3-Inferred' + } + + $confidenceRank = @{ + 'L3-Inferred' = 1 + 'L2-SNMP-Heuristic' = 2 + 'L2-SNMP' = 3 + } + if ($edgeMap.Contains($key)) { $existing = $edgeMap[$key] - # Prioritize L2-SNMP confidence - if ($edge.Source -eq 'SNMP' -and $existing.Source -ne 'SNMP') { - $existing.Source = 'SNMP' - $existing.Confidence = 'L2-SNMP' + $existingRank = if ($confidenceRank.ContainsKey($existing.Confidence)) { $confidenceRank[$existing.Confidence] } else { 0 } + $incomingRank = if ($confidenceRank.ContainsKey($incomingConfidence)) { $confidenceRank[$incomingConfidence] } else { 0 } + if ($incomingRank -gt $existingRank) { + $existing.Source = if ($edge.PSObject.Properties['Source']) { $edge.Source } else { 'Unknown' } + $existing.Confidence = $incomingConfidence } # Keep first non-empty label @@ -693,22 +713,12 @@ function Merge-Edges { } else { # Add new edge with confidence - $confidence = if ($edge.PSObject.Properties['Confidence']) { - $edge.Confidence - } - elseif ($edge.Source -eq 'SNMP') { - 'L2-SNMP' - } - else { - 'L3-Inferred' - } - $edgeMap[$key] = [pscustomobject]@{ SourceIP = $edge.SourceIP TargetIP = $edge.TargetIP Label = if ($edge.PSObject.Properties['Label']) { $edge.Label } else { '' } Source = if ($edge.PSObject.Properties['Source']) { $edge.Source } else { 'Unknown' } - Confidence = $confidence + Confidence = $incomingConfidence } } } @@ -945,6 +955,12 @@ function Export-DrawIO { $edgeStyle += 'strokeColor=#2D7600;strokeWidth=2.5;' $edgeStyle += 'endArrow=classic;endFill=1;' } + elseif ($confidence -eq 'L2-SNMP-Heuristic') { + # Provisional SNMP hint: amber and dashed, visually distinct from + # verified physical topology. + $edgeStyle += 'strokeColor=#B26A00;strokeWidth=2;dashed=1;dashPattern=8 4;' + $edgeStyle += 'endArrow=classic;endFill=0;' + } elseif ($confidence -eq 'L3-Inferred') { # L3-Inferred: Dashed line, gray (inferred connection) $edgeStyle += 'strokeColor=#808080;strokeWidth=1.5;dashed=1;dashPattern=5 5;' diff --git a/README.md b/README.md index 208fa2f..0848fad 100644 --- a/README.md +++ b/README.md @@ -119,9 +119,10 @@ $topo | Export-DrawIO -OutFile '.\network.drawio' > end without a separate reachability pass. Add `-OnlyReachable` (after piping through > `Test-DeviceReachability`) to query only nodes that answered a ping. > -> **LLDP/CDP parsing is best-effort (MVP):** it extracts management IPs from `snmpwalk` -> output and links them to known nodes, but does not fully decode the LLDP MIB. Treat the -> resulting SNMP edges as hints to verify, not authoritative topology. The community +> **LLDP/CDP parsing is best-effort (MVP):** it extracts typed management-address values +> from `snmpwalk` output and links them to known nodes, but does not fully decode the +> LLDP/CDP tables. These links are labeled `L2-SNMP-Heuristic` and drawn as amber dashed +> hints. Only structured, correlated neighbor data may use verified `L2-SNMP`. The community > string is redacted from verbose logging, but is briefly visible in the local process > list while `snmpwalk` runs — prefer SNMPv3 for anything sensitive. @@ -173,7 +174,7 @@ Generated diagrams include: - Subnet containers for visual grouping by network segment - Color-coded status indicators: green (reachable), red (unreachable), and gray (unknown) - Orthogonal connectors with rounded corners -- Confidence levels: solid lines (layer 2 SNMP verified) and dashed lines (layer 3 inferred) +- Confidence levels: solid green (verified layer 2 SNMP), dashed amber (provisional SNMP hint), and dashed gray (layer 3 inferred) - Labels that include device names, IP addresses, and connection details - Hierarchical layouts that align devices by network layer @@ -419,4 +420,3 @@ Import-Inventory my-network-inventory.json | Export-DrawIO -OutFile my-network.d 2. Check command help: `Get-Help -Examples` 3. Review example files in `examples/` 4. Report issues with detailed error messages - diff --git a/tests/NetDiagram.Tests.ps1 b/tests/NetDiagram.Tests.ps1 index e321402..f3a7e4e 100644 --- a/tests/NetDiagram.Tests.ps1 +++ b/tests/NetDiagram.Tests.ps1 @@ -145,6 +145,18 @@ Describe 'Merge-Edges' { $merged[0].Confidence | Should -Be 'L2-SNMP' } + It 'Does not promote a provisional SNMP hint to verified confidence' { + $edges = @( + [pscustomobject]@{ SourceIP = '192.168.1.1'; TargetIP = '192.168.1.10'; Label = 'Inferred'; Source = 'Manual'; Confidence = 'L3-Inferred' } + [pscustomobject]@{ SourceIP = '192.168.1.1'; TargetIP = '192.168.1.10'; Label = 'Hint'; Source = 'SNMP'; Confidence = 'L2-SNMP-Heuristic' } + ) + + $merged = Merge-Edges -Edges $edges + $merged | Should -HaveCount 1 + $merged[0].Confidence | Should -Be 'L2-SNMP-Heuristic' + $merged[0].Confidence | Should -Not -Be 'L2-SNMP' + } + It 'Should keep first non-empty label' { $edges = @( [pscustomobject]@{ SourceIP = '192.168.1.1'; TargetIP = '192.168.1.10'; Label = 'FirstLabel'; Source = 'Manual' } @@ -502,6 +514,81 @@ Describe 'Get-SnmpNeighbors node eligibility (#1 regression)' { } } +Describe 'Get-SnmpNeighbors provisional parser confidence (#20 regression)' { + BeforeEach { + $script:CredMapPath = Join-Path $script:TestDataPath 'credmap-parser.json' + '{}' | Out-File -FilePath $script:CredMapPath -Force + $script:ParserTopology = [pscustomobject]@{ + Nodes = @( + [pscustomobject]@{ IP = '192.168.1.1'; Reachable = $true } + [pscustomobject]@{ IP = '192.168.1.2'; Reachable = $true } + ) + Edges = @() + Subnets = @() + } + } + + It 'Accepts typed management addresses and rejects unrelated or unsafe values' { + Mock Invoke-SnmpWalk { + if ($TargetIP -eq '192.168.1.1') { + @( + 'oid.1 = STRING: "peer text mentions 192.168.1.2"' + 'oid.2 = IpAddress: 192.168.1.1' + 'oid.3 = IpAddress: 192.168.1.999' + 'oid.4 = IpAddress: 203.0.113.9' + 'oid.5 = IpAddress: 192.168.1.2' + ) + } + else { @() } + } -ModuleName 'NetDiagram-PS' + + $result = $script:ParserTopology | Get-SnmpNeighbors ` + -CredentialMapPath $script:CredMapPath -TryPublic -WarningAction SilentlyContinue + + $result.Edges | Should -HaveCount 1 + $result.Edges[0].TargetIP | Should -Be '192.168.1.2' + $result.Edges[0].Confidence | Should -Be 'L2-SNMP-Heuristic' + } + + It 'Accepts a typed four-octet Hex-STRING as a provisional hint' { + Mock Invoke-SnmpWalk { + if ($TargetIP -eq '192.168.1.1') { @('oid.1 = Hex-STRING: C0 A8 01 02') } + else { @() } + } -ModuleName 'NetDiagram-PS' + + $result = $script:ParserTopology | Get-SnmpNeighbors ` + -CredentialMapPath $script:CredMapPath -TryPublic -WarningAction SilentlyContinue + + $result.Edges | Should -HaveCount 1 + $result.Edges[0].TargetIP | Should -Be '192.168.1.2' + $result.Edges[0].Confidence | Should -Be 'L2-SNMP-Heuristic' + } + + It 'Exports provisional hints with a distinct amber dashed style' { + $script:ParserTopology.Edges = @( + [pscustomobject]@{ + SourceIP = '192.168.1.1'; TargetIP = '192.168.1.2'; Label = 'LLDP hint' + Source = 'SNMP'; Confidence = 'L2-SNMP-Heuristic' + } + ) + foreach ($node in $script:ParserTopology.Nodes) { + $node | Add-Member -NotePropertyName Hostname -NotePropertyValue $node.IP + $node | Add-Member -NotePropertyName Role -NotePropertyValue 'switch' + $node | Add-Member -NotePropertyName Vendor -NotePropertyValue 'Test' + $node | Add-Member -NotePropertyName OS -NotePropertyValue 'Test' + $node | Add-Member -NotePropertyName Layer -NotePropertyValue 'Access' + } + $drawioPath = Join-Path $script:TestDataPath 'provisional-snmp.drawio' + + $script:ParserTopology | Export-DrawIO -OutFile $drawioPath + $xml = [xml](Get-Content -Path $drawioPath -Raw) + $edge = $xml.SelectSingleNode('//mxCell[@edge="1"]') + + $edge.style | Should -Match 'strokeColor=#B26A00' + $edge.style | Should -Match 'dashed=1' + } +} + Describe 'Invoke-SnmpWalk parameter validation (#6 regression)' { It 'Rejects an invalid SNMP version' { { Invoke-SnmpWalk -TargetIP '192.0.2.1' -Community 'public' -Version 'v9' } | Should -Throw