@himorishige/noren-plugin-network

Network PII detection plugin for Noren

Specialized detectors and maskers for network-related Personally Identifiable Information including IPv4 addresses, IPv6 addresses, and MAC addresses.

Note: As of Noren v0.6.0, network PII detection has been moved from Core to this dedicated plugin for better performance and reduced false positives in web applications.

✨ Features

🌐 IPv4 Addresses

• Standard format: 192.168.1.1, 10.0.0.1
• Context-aware validation: Excludes version numbers and dates
• Private/public classification: Automatic detection
• False positive filtering: Smart exclusion of obvious non-IPs

🌐 IPv6 Addresses

• Full format: 2001:db8:85a3::8a2e:370:7334
• Compressed notation: ::1, 2001:db8::
• Link-local addresses: fe80:: range
• Proper parsing: Comprehensive validation with boundary detection

🔗 MAC Addresses

• Colon format: 00:1B:44:11:3A:B7
• Dash format: 00-1B-44-11-3A-B7
• Context validation: Hardware/network context required
• Reserved pattern exclusion: Filters broadcast and null addresses

🚀 Installation

npm install @himorishige/noren-plugin-network @himorishige/noren-core

Basic Usage

import { Registry, redactText } from '@himorishige/noren-core'
import * as networkPlugin from '@himorishige/noren-plugin-network'

// Create registry with network context hints
const registry = new Registry({
  defaultAction: 'mask',
  contextHints: ['ip', 'address', 'server', 'interface', 'mac', 'ethernet']
})

// Register the network plugin
registry.use(networkPlugin.detectors, networkPlugin.maskers)

const logData = `
Server startup log:
Primary interface: 192.168.1.100
Gateway: 192.168.1.1
IPv6 address: 2001:db8::1
MAC address: 00:1B:44:11:3A:B7
`

const result = await redactText(registry, logData)
console.log(result)
// Output:
// Server startup log:
// Primary interface: •••.•••.•••.•••
// Gateway: •••.•••.•••.•••
// IPv6 address: ••••:•••::•
// MAC address: ••:••:••:••:••:••

Detected Types

| PII Type | Description | Masking Example (mask) | Context Required | |:---------|:------------|:-------------------------|:-----------------| | ipv4 | IPv4 address | •••.•••.•••.••• | Recommended | | ipv6 | IPv6 address | ••••:•••::• | Recommended | | mac | MAC address | ••:••:••:••:••:•• | Recommended |

Context Hints for Better Accuracy

For optimal detection accuracy, provide relevant context hints:

const registry = new Registry({
  defaultAction: 'mask',
  contextHints: [
    // IPv4/IPv6 contexts
    'ip', 'address', 'server', 'host', 'endpoint', 'gateway', 'dns',
    // IPv6 specific
    'ipv6', 'ip6', 'interface', 'link-local',
    // MAC address contexts  
    'mac', 'ethernet', 'wifi', 'interface', 'adapter', 'nic', 'hardware'
  ]
})

Advanced Usage

Individual Detectors

Use specific detectors for targeted detection:

import { Registry } from '@himorishige/noren-core'
import { detectors, maskers } from '@himorishige/noren-plugin-network'

const registry = new Registry({ defaultAction: 'mask' })

// Use only IPv4 detection (example)
const ipv4Detector = detectors.find(d => d.id === 'network.ipv4')
if (ipv4Detector) {
  registry.use([ipv4Detector], maskers)
}

Custom Validation

Access validation functions for custom logic:

import { validateIPv4, validateIPv6, validateMAC } from '@himorishige/noren-plugin-network'

const ipResult = validateIPv4('192.168.1.1', {
  surroundingText: 'Server IP: 192.168.1.1',
  strictness: 'balanced',
  originalIndex: 0
})

console.log(ipResult.valid) // true
console.log(ipResult.confidence) // 0.8
console.log(ipResult.reason) // 'private_ip'

IPv6 Parsing

Use the built-in IPv6 parser:

import { parseIPv6 } from '@himorishige/noren-plugin-network'

const result = parseIPv6('2001:db8::1')
console.log(result.valid) // true
console.log(result.normalized) // Normalized form
console.log(result.isPrivate) // false

Performance Characteristics

• IPv4 Detection: ~0.1ms per candidate
• IPv6 Detection: ~0.3ms per candidate (complex parsing)
• MAC Detection: ~0.05ms per candidate
• Memory Usage: Minimal overhead with pre-compiled patterns
• False Positive Rate: <5% with proper context hints

Configuration Examples

Network Infrastructure Monitoring

const registry = new Registry({
  defaultAction: 'mask',
  contextHints: [
    'interface', 'gateway', 'dns', 'dhcp', 'route',
    'firewall', 'switch', 'router', 'ethernet'
  ]
})
registry.use(networkPlugin.detectors, networkPlugin.maskers)

Application Log Processing

const registry = new Registry({
  defaultAction: 'mask',
  contextHints: ['ip', 'address', 'server', 'api', 'endpoint']
})
registry.use(networkPlugin.detectors, networkPlugin.maskers)

Security/Audit Logs

const registry = new Registry({
  defaultAction: 'mask',
  validationStrictness: 'strict', // Higher accuracy
  contextHints: ['source', 'destination', 'client', 'remote', 'peer']
})
registry.use(networkPlugin.detectors, networkPlugin.maskers)

False Positive Prevention

The plugin includes sophisticated false positive filtering:

Automatically Excluded

• Version numbers: 1.2.3.4 in "Version 1.2.3.4"
• Date formats: 2024.12.31
• Product codes: AB-CD-EF-12-34-56 (for MAC)
• Reserved addresses: 127.0.0.1, 0.0.0.0, broadcast MACs

Context-Based Filtering

• IPv4: Requires network-related context or explicit hints
• IPv6: Benefits from IPv6-specific context
• MAC: Requires hardware/network context for accuracy

Migration from Core v0.5.x

If upgrading from Noren Core v0.5.x where network detection was built-in:

// Before (v0.5.x) - automatic network detection
const registry = new Registry()

// After (v0.6.0+) - explicit plugin
import * as networkPlugin from '@himorishige/noren-plugin-network'

const registry = new Registry({
  contextHints: ['ip', 'address'] // Recommended for accuracy
})
registry.use(networkPlugin.detectors, networkPlugin.maskers)

See Migration Guide for complete details.

Contributing

Issues and contributions welcome at noren repository.

License

MIT