Punching Bag

Overview

Punching Bag is an IPv6 ICMP echo responder designed for network testing and simulation scenarios.
It listens for ICMPv6 Echo Requests (ping) on a specified network interface and responds with ICMPv6 Echo Replies according to configurable prefix-based response rates.
The tool uses libpcap for packet capture, libnet for packet crafting, and a trie-based IPv6 prefix table (loaded from a JSON configuration) to determine probabilistic reply behavior.

---

Features

• Simulate ICMPv6 echo responses using multithreaded workers.
• Prefix-based probability response rates via an IPv6 trie.
• Configurable thread count, pcap capture timeout, and max queue size.
• Queue monitoring and logging with timestamped performance stats.
• Graceful shutdown via CTRL+C with cleanup of all threads.
• Efficient packet processing with minimal overhead.

---

Requirements

Build Dependencies

• C++17 compiler
• CMake ≥ 3.10
• libpcap
• libnet
• nlohmann JSON
• pthreads (POSIX threads)

Install via apt:

apt install libnet-dev nlohmann-json3-dev

Runtime Requirements

• Root or equivalent permissions (required for raw socket operations)
• A valid JSON configuration file with IPv6 prefixes and response rates (examples are provided in JSON_configs)

---

Building

mkdir build && cd build
cmake ..
make

This produces the executable:

./punchingbag

---

Command-line Arguments

Argument	Description	Required	Default
--interface=<iface>	Network interface to listen on (e.g., eth0)	Yes	—
--json-config=<path>	Path to JSON file containing IPv6 prefixes and response rates	Yes	—
--thread-count=<n>	Number of worker threads	No	1
--pcap-timeout=<ms>	Timeout for pcap capture loop in milliseconds	No	50
--max-queue-size=<n>	Maximum packet queue length before dropping packets	No	250.000
--random-responses	Replaces deterministic random responses with true random respones	No

---

JSON Configuration Format

Example prefixes.json:

{
  "subnets": [
    {
      "ipv6_prefix": "2001:db8:abcd:12::/64",
      "default_response_rate": 0.01,
      "EUI_response_rate": 0.0,
      "lower_response_rate": 1.0,
      "higher_response_rate": 0.5
    }
  ]
}

• prefix — IPv6 prefix in CIDR notation
• response_rate — Probability (0.0–1.0) of replying to a ping

---

Logging

The program generates a queue log file named:

queue_log_YYYY-MM-DD_HH-MM-SS.txt

This file contains:

• Queue size
• Queue usage percentage
• Total received packets
• Libnet write error count
• Timestamps

---

Internals

Main components:

• Packet capture: pcap_loop filters and queues ICMPv6 Echo Requests.
• Worker threads: Process queued packets and send responses based on trie lookup.
• IPv6 trie: Efficient prefix matching with configurable probabilities.
• Logger thread: Periodically logs queue statistics to a file.

BPF filter used:

icmp6 and ip6[40] == 128

This ensures only ICMPv6 Echo Requests are captured.