go-packet-forge

A programmable packet crafting and inspection utility for educational purposes, testing, and protocol research.

Overview

go-packet-forge is a Go-based CLI tool that allows users to construct, send, receive, and validate raw TCP/UDP/ICMP packets using declarative specifications. It leverages Go's networking primitives and raw sockets with OS abstraction, making it suitable for:

• Education: Learn about network protocols and packet structures
• Testing: Test network applications and services
• Protocol Research: Experiment with custom packet structures

⚠️ Important: This tool is intended for educational and authorized testing purposes only. Do not use it for network scanning or unauthorized penetration testing.

Features

• ✅ Declarative Packet Specifications: Define packets using YAML or JSON
• ✅ Multi-Protocol Support: TCP, UDP, and ICMP packets
• ✅ Flexible TCP Control: Set custom TCP flags (SYN, ACK, FIN, RST, PSH, URG)
• ✅ Packet Sending: Send raw packets to network destinations
• ✅ Packet Receiving: Capture and inspect incoming packets
• ✅ Packet Validation: Validate received packets against defined rules
• ✅ OS Abstraction: Works across different operating systems (Linux, macOS, etc.)

Installation

Prerequisites

• Go 1.20 or later
• Root/Administrator privileges (required for raw sockets)

Build from Source

git clone https://github.com/BaseMax/go-packet-forge.git
cd go-packet-forge
go build -o packetforge ./cmd/packetforge

Install

go install github.com/BaseMax/go-packet-forge/cmd/packetforge@latest

Usage

Note: Raw sockets require root/administrator privileges. Run commands with sudo on Linux/macOS or as Administrator on Windows.

Send a Packet

sudo packetforge send <spec-file>

Example:

sudo packetforge send examples/tcp-syn.yaml

Receive Packets

sudo packetforge receive <protocol>

Example (receive TCP packets):

sudo packetforge receive TCP

Example (receive ICMP packets):

sudo packetforge receive ICMP

Validate Packets

sudo packetforge validate <spec-file> <validation-file>

Example:

sudo packetforge validate examples/tcp-syn.yaml examples/validation.yaml

Packet Specification Format

YAML Format

TCP Packet Example

protocol: TCP
source: 192.168.1.100
destination: 192.168.1.1
source_port: 12345
destination_port: 80
tcp_flags: SYN
seq_num: 1000
ack_num: 0
data: "GET / HTTP/1.1\r\nHost: example.com\r\n\r\n"

UDP Packet Example

protocol: UDP
source: 10.0.0.1
destination: 10.0.0.2
source_port: 53
destination_port: 53
data: "DNS query example"

ICMP Packet Example

protocol: ICMP
source: 192.168.1.100
destination: 8.8.8.8
icmp_type: 8
icmp_code: 0
data: "ping payload"

JSON Format

{
  "protocol": "TCP",
  "source": "192.168.1.100",
  "destination": "192.168.1.1",
  "source_port": 54321,
  "destination_port": 443,
  "tcp_flags": "SYN,ACK",
  "seq_num": 2000,
  "ack_num": 1001,
  "data": "HTTPS handshake"
}

Validation Rules Format

protocol: TCP
source_ip: 192.168.1.1
destination_ip: 192.168.1.100
destination_port: 80
data_contains: "HTTP"

All fields are optional. Only specified fields will be validated.

Field Reference

Common Fields

• protocol: Protocol type (TCP, UDP, or ICMP)
• source: Source IP address (IPv4)
• destination: Destination IP address (IPv4)
• data: Packet payload data (string)

TCP-Specific Fields

• source_port: Source port number (1-65535)
• destination_port: Destination port number (1-65535)
• tcp_flags: TCP flags as comma-separated values (SYN, ACK, FIN, RST, PSH, URG)
• seq_num: TCP sequence number
• ack_num: TCP acknowledgment number

UDP-Specific Fields

• source_port: Source port number (1-65535)
• destination_port: Destination port number (1-65535)

ICMP-Specific Fields

• icmp_type: ICMP type (e.g., 8 for echo request, 0 for echo reply)
• icmp_code: ICMP code (usually 0)

Examples

See the examples/ directory for more packet specifications:

• examples/tcp-syn.yaml - TCP SYN packet
• examples/tcp-synack.json - TCP SYN-ACK packet (JSON format)
• examples/udp.yaml - UDP packet
• examples/icmp-ping.yaml - ICMP echo request (ping)
• examples/validation.yaml - Validation rules example

Architecture

The project is organized into the following packages:

• cmd/packetforge - CLI application entry point
• pkg/packet - Packet construction, parsing, and validation logic
• pkg/socket - Raw socket handling with OS abstraction
• pkg/spec - Declarative specification parser (YAML/JSON)

Security Considerations

• Requires elevated privileges: Raw sockets require root/administrator access
• Use responsibly: Only use on networks you own or have permission to test
• Educational purpose: This tool is designed for learning and authorized testing
• Not for scanning: Do not use for unauthorized network scanning or attacks

License

See the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Disclaimer

This tool is provided for educational and research purposes only. The authors are not responsible for any misuse or damage caused by this tool. Always ensure you have proper authorization before testing network systems.