synth-snmp-facade

Synthetic SNMP/ICMP facade for monitoring and test environments.

synth-snmp-facade provides lightweight, container-based network device facades that expose realistic SNMP and ICMP behaviour without implementing a full network data plane or network operating system.

The focus is on simulating what monitoring systems observe, not on emulating how network devices operate internally.

---

What it is

• Synthetic SNMPv2c device facade (AgentX-based)
• ICMP reachable (pingable)
• Deterministic, reproducible behaviour
• Counter64 interface statistics
• Designed specifically for monitoring and alerting tests
• Fast to start and cheap to scale (hundreds of devices)

---

What it is not

• Not a real switch or router
• No packet forwarding or data plane
• No routing protocols
• No control-plane emulation
• Not a replacement for containerlab or virtual NOS images

If you need full device behaviour, protocol interaction, or forwarding logic, this project is intentionally the wrong tool.

---

Typical use cases

• Testing network monitoring systems (NMS)
• Alerting and threshold validation
• Dashboard and visualization testing
• Synthetic network environments
• CI-friendly monitoring regression tests

---

Architecture overview

Each facade runs as a single container exposing:

• ICMP reachability
• SNMP system MIBs
• SNMP interface MIBs
• Synthetic traffic counters (Counter64)

Traffic and interface behaviour is generated internally and exposed only through monitoring interfaces. No real packet forwarding takes place.

The implementation uses an AgentX architecture:

• snmpd runs as AgentX master
• A custom subagent exposes synthetic device behaviour

---

Quick start

Build and run a test device:

./buildandrun.sh

Run an acceptance test from the host:

./test.sh sw-01

Example: starting a synthetic switch

docker run -d \
  --name sw-01 \
  -p 161:161/udp \
  snmp-switch:dev \
  --type switch \
  --name access-switch-01 \
  --max-capacity-mbps 1000 \
  --base-mbps 220 \
  --variance-percent 12 \
  --uptime-days 412 \
  --peak-hour 20 \
  --min-factor 0.4

All device behaviour can be configured via CLI arguments. YAML-based configuration may be added later but is not required.

Acceptance testing

The provided test script validates:

ICMP reachability

SNMP system MIB values

Interface presence

Counter64 monotonicity

Traffic throughput calculated over time

The test is designed as a monitoring acceptance test, not a unit test.

Design philosophy

This project intentionally implements a facade.

Only externally observable behaviour required by monitoring systems is simulated. This keeps the implementation simple, scalable, and predictable, while remaining useful for realistic monitoring tests.

Device types are intentionally separated. Currently implemented:

switch – throughput-focused device facade

Additional device types (e.g. routers) may be added later with different exposed metrics and behaviour.

License

MIT