Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 38 additions & 22 deletions NetDiagram-PS/NetDiagram-PS.psm1
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
}
}
}
Expand Down Expand Up @@ -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;'
Expand Down
10 changes: 5 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -419,4 +420,3 @@ Import-Inventory my-network-inventory.json | Export-DrawIO -OutFile my-network.d
2. Check command help: `Get-Help <CommandName> -Examples`
3. Review example files in `examples/`
4. Report issues with detailed error messages

87 changes: 87 additions & 0 deletions tests/NetDiagram.Tests.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -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' }
Expand Down Expand Up @@ -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
Expand Down
Loading