# NimPacket CLI

Command-line interface for crafting, parsing, and sending network packets.

## Installation

```bash
cd NimPacket/python
python build.py        # build the Nim extension
```

## Usage

```bash
python cli/nimpacket_cli.py <command> [options]
```

**Important:** Run your terminal as administrator for full functionality (send/listen require admin).

To see every command at once:
```bash
python cli/nimpacket_cli.py help-all
```

---

## Commands (54 total)

### `info` - Show version and protocol info

```bash
nimpacket info                   # version + supported protocols
nimpacket info --check-admin     # also check admin privileges
```

---

### `craft` - Create packets

All craft commands support these output flags:
- `--hex` - Output raw hex string only
- `--raw` - Output raw bytes to stdout (for piping)
- Default: human-readable hex dump

#### Complete Packets (IP + transport + checksums)

```bash
# TCP SYN packet
nimpacket craft tcp-syn --src-ip 192.168.1.1 --dst-ip 10.0.0.1 --src-port 54321 --dst-port 80 [--ttl 64]

# ICMP Echo Request
nimpacket craft icmp-echo --src-ip 192.168.1.1 --dst-ip 8.8.8.8 --id 1234 --seq 1 [--payload "data"] [--ttl 64]

# UDP packet
nimpacket craft udp --src-ip 10.0.0.1 --dst-ip 10.0.0.2 --src-port 12345 --dst-port 53 [--payload "Hello"] [--ttl 64]

# ARP frame (Ethernet + ARP)
nimpacket craft arp-frame --src-mac AA:BB:CC:DD:EE:FF --src-ip 192.168.1.1 --dst-ip 192.168.1.254 [--dst-mac FF:FF:FF:FF:FF:FF]
```

#### ARP

```bash
# ARP Request
nimpacket craft arp-request --sender-mac AA:BB:CC:DD:EE:FF --sender-ip 192.168.1.1 --target-ip 192.168.1.254

# ARP Reply
nimpacket craft arp-reply --sender-mac AA:BB:CC:DD:EE:FF --sender-ip 192.168.1.1 --target-mac 11:22:33:44:55:66 --target-ip 192.168.1.254
```

#### DNS

```bash
nimpacket craft dns-query --domain google.com [--type A|AAAA|MX|CNAME|TXT|NS|SOA|PTR|SRV|ANY] [--txid 0x1234]
```

#### DHCP

```bash
nimpacket craft dhcp-discover --mac AA:BB:CC:DD:EE:FF [--txid 0xDEADBEEF]
nimpacket craft dhcp-request --mac AA:BB:CC:DD:EE:FF --requested-ip 192.168.1.100 --server-ip 192.168.1.1 [--txid 0xCAFEBABE]
nimpacket craft dhcp-release --mac AA:BB:CC:DD:EE:FF --client-ip 192.168.1.100 --server-ip 192.168.1.1 [--txid 0]
```

#### Individual Headers

```bash
# Ethernet header
nimpacket craft ethernet --src-mac AA:BB:CC:DD:EE:FF --dst-mac FF:FF:FF:FF:FF:FF --ether-type 0x0800

# IPv4 header
nimpacket craft ipv4 --src-ip 192.168.1.1 --dst-ip 10.0.0.1 --protocol 6 [--ttl 64]

# IPv6 header
nimpacket craft ipv6 --src-ip ::1 --dst-ip ::2 --next-header 6 [--hop-limit 64]

# TCP header
nimpacket craft tcp --src-port 54321 --dst-port 80 --flags SYN [--seq 0] [--ack 0] [--window 65535]

# UDP header
nimpacket craft udp-header --src-port 12345 --dst-port 53 [--length 8]

# ICMP header
nimpacket craft icmp --type 8 [--code 0] [--id 0] [--seq 0]

# ICMPv6
nimpacket craft icmpv6-echo-request --id 1234 --seq 1
nimpacket craft icmpv6-echo-reply --id 1234 --seq 1
```

TCP flags can be combined: `--flags SYN,ACK` or `--flags SYN|ACK`

---

### `parse` - Decode packets

All parse commands support:
- `--hex "..."` - Hex-encoded packet data
- `--file packet.bin` - Binary packet file
- `--json` - Output as JSON (default: pretty-printed table)

```bash
# Auto-detect protocol layers
nimpacket parse --hex "450000280001..."
nimpacket parse --file packet.bin

# Parse specific protocol
nimpacket parse dns --hex "..."
nimpacket parse dhcp --hex "..."
nimpacket parse arp --hex "..."
nimpacket parse ethernet --hex "..."
nimpacket parse ipv4 --hex "..."
nimpacket parse ipv6 --hex "..."
nimpacket parse tcp --hex "..."
nimpacket parse udp --hex "..."
nimpacket parse icmp --hex "..."
nimpacket parse icmpv6 --hex "..."
```

---

### `send` - Send raw packets (requires admin)

```bash
nimpacket send tcp-syn --dst-ip 10.0.0.1 --dst-port 80 --src-ip 192.168.1.1 --src-port 54321
nimpacket send icmp-echo --dst-ip 8.8.8.8 --src-ip 192.168.1.1 --id 1234 --seq 1
nimpacket send udp --dst-ip 10.0.0.2 --dst-port 53 --src-ip 10.0.0.1 --src-port 12345 [--payload "data"]
nimpacket send arp-frame --src-mac AA:BB:CC:DD:EE:FF --src-ip 192.168.1.1 --dst-ip 192.168.1.254
nimpacket send raw --hex "4500..." --dst-ip 10.0.0.1
nimpacket send raw --file packet.bin --dst-ip 10.0.0.1
```

**Privileges:** Windows requires Administrator, Linux requires root or CAP_NET_RAW.

When not running as admin, the CLI will prompt:
```
This command requires administrator/root privileges.
Restart as admin? [y/N]:
```
- **Windows:** Triggers a UAC elevation prompt and relaunches in a new window
- **Linux/macOS:** Relaunches with `sudo` in the same terminal

---

### `scan` - Network scanning (requires admin)

Scan targets specified as single IPs, CIDR notation, IP ranges, or from a file.

#### Target formats

```
192.168.1.1                 Single IP
192.168.1.0/24              CIDR (254 hosts)
192.168.1.1-254             Last-octet range
192.168.1.1-192.168.1.254   Full range
--target-file targets.txt   File (one IP/CIDR per line)
```

#### `scan ports` - SYN port scan

```bash
# Scan common ports on one host
nimpacket scan ports --target 192.168.1.1 --src-ip 192.168.1.100

# Scan entire subnet for SSH and HTTP
nimpacket scan ports --target 192.168.1.0/24 --ports 22,80,443 --src-ip 192.168.1.100

# Scan top 20 well-known ports
nimpacket scan ports --target 10.0.0.0/24 --top-ports 20 --src-ip 10.0.0.1

# Scan port range 1-1024
nimpacket scan ports --target 192.168.1.1 --ports 1-1024 --src-ip 192.168.1.100

# Only show open ports, save to file
nimpacket scan ports --target 192.168.1.0/24 --top-ports 24 --src-ip 192.168.1.100 --open-only -o results.json

# Scan from a file of targets
nimpacket scan ports --target 192.168.1.1 --target-file targets.txt --ports 80,443 --src-ip 192.168.1.100

# Slow scan to avoid IDS (100ms delay between probes)
nimpacket scan ports --target 10.0.0.0/24 --ports 22,80 --src-ip 10.0.0.1 --delay 100
```

#### `scan hosts` - ICMP ping sweep

```bash
# Discover live hosts on a /24 subnet
nimpacket scan hosts --target 192.168.1.0/24 --src-ip 192.168.1.100

# Only show alive hosts
nimpacket scan hosts --target 10.0.0.0/24 --src-ip 10.0.0.1 --alive-only

# JSON output for scripting
nimpacket scan hosts --target 192.168.1.0/24 --src-ip 192.168.1.100 --json

# Save results
nimpacket scan hosts --target 192.168.1.0/24 --src-ip 192.168.1.100 -o hosts.json
```

#### `scan arp` - ARP scan (LAN only)

```bash
# Discover hosts + MAC addresses on local network
nimpacket scan arp --target 192.168.1.0/24 --src-mac AA:BB:CC:DD:EE:FF --src-ip 192.168.1.100

# Only show alive hosts
nimpacket scan arp --target 192.168.1.1-254 --src-mac AA:BB:CC:DD:EE:FF --src-ip 192.168.1.100 --alive-only
```

#### `scan sweep` - Port sweep (one port, many hosts)

```bash
# Which hosts have SSH open?
nimpacket scan sweep --target 192.168.1.0/24 --port 22 --src-ip 192.168.1.100

# Which hosts have HTTP open?
nimpacket scan sweep --target 10.0.0.0/24 --port 80 --src-ip 10.0.0.1 --open-only

# RDP sweep
nimpacket scan sweep --target 192.168.1.0/24 --port 3389 --src-ip 192.168.1.100 -o rdp_hosts.json
```

#### Scan options (all scan commands)

| Option | Description |
|--------|-------------|
| `--target` | IP, CIDR, or range |
| `--target-file` | File with targets |
| `--src-ip` | Your source IP |
| `--timeout` | Per-probe timeout in ms (default: 1000) |
| `--delay` | Delay between probes in ms (default: 0) |
| `--open-only` / `--alive-only` | Filter results |
| `--json` | JSON output |
| `-o FILE` | Save results to JSON file |

---

### `listen` - Capture incoming packets (requires admin)

```bash
nimpacket listen [--protocol tcp|udp|icmp|all] [--timeout 5000] [--count 10] [--size 65535]
nimpacket listen --protocol icmp --count 5 --json
nimpacket listen --protocol tcp --hex
nimpacket listen --broadcast --hdrincl
```

Options:
- `--protocol` - Filter by protocol (default: all)
- `--timeout` - Receive timeout in ms (default: 5000)
- `--count` - Stop after N packets (0 = unlimited, Ctrl+C to stop)
- `--size` - Max packet size (default: 65535)
- `--json` - Output parsed packets as JSON
- `--hex` - Output raw hex
- `--hdrincl` - Include IP headers in received data
- `--broadcast` - Enable broadcast packet reception

---

### `fragment` - IP fragmentation

```bash
nimpacket fragment --src-ip 192.168.1.1 --dst-ip 10.0.0.1 --payload "data" --strategy tiny [--fragment-size 8]
```

Strategies: `tiny`, `overlap`, `outoforder`, `timedelayed`, `polymorphic`

### `send-fragmented` - Send fragmented packets (requires admin)

```bash
nimpacket send-fragmented --src-ip 192.168.1.1 --dst-ip 10.0.0.1 --payload "data" --strategy tiny [--delay 100]
```

---

### `util` - Utility functions

```bash
# IP address conversion
nimpacket util ip-parse 192.168.1.1          # -> 3232235777
nimpacket util ip-to-string 3232235777       # -> 192.168.1.1

# MAC address
nimpacket util mac-parse AA:BB:CC:DD:EE:FF   # -> hex bytes
nimpacket util mac-to-string aabbccddeeff    # -> AA:BB:CC:DD:EE:FF
nimpacket util broadcast-mac                 # -> FF:FF:FF:FF:FF:FF

# IPv6 address conversion
nimpacket util ipv6-parse ::1                # -> hex bytes
nimpacket util ipv6-to-string <hex>          # -> string

# Byte order
nimpacket util htons 80                      # -> 20480
nimpacket util ntohs 20480                   # -> 80
nimpacket util htonl 12345
nimpacket util ntohl 12345

# DNS
nimpacket util encode-domain google.com      # -> DNS wire format hex

# Checksums
nimpacket util checksum ipv4 --hex "..."
nimpacket util checksum tcp --ip-hex "..." --tcp-hex "..." [--payload-hex "..."]
nimpacket util checksum udp --ip-hex "..." --udp-hex "..." [--payload-hex "..."]
nimpacket util checksum icmp --hex "..." [--payload-hex "..."]
```

---

## Examples

### Craft a TCP SYN and parse it back

```bash
# Craft
$ python cli/nimpacket_cli.py craft tcp-syn --src-ip 192.168.1.1 --dst-ip 10.0.0.1 --src-port 54321 --dst-port 80 --hex
45000028000000004006...

# Parse
$ python cli/nimpacket_cli.py parse --hex "45000028000000004006..."
ipv4:
  src_ip: 192.168.1.1
  dst_ip: 10.0.0.1
  protocol: 6
  ttl: 64
tcp:
  src_port: 54321
  dst_port: 80
  flags: 2
```

### Craft a DNS query

```bash
$ python cli/nimpacket_cli.py craft dns-query --domain google.com --type AAAA --hex
```

### Pipe raw output

```bash
# Craft and save to file
$ python cli/nimpacket_cli.py craft icmp-echo --src-ip 192.168.1.1 --dst-ip 8.8.8.8 --id 1 --seq 1 --raw > packet.bin

# Parse from file
$ python cli/nimpacket_cli.py parse --file packet.bin --json
```

### Utility conversions

```bash
$ python cli/nimpacket_cli.py util ip-parse 192.168.1.1
3232235777

$ python cli/nimpacket_cli.py util broadcast-mac
FF:FF:FF:FF:FF:FF
```

---

## Red Team / Offensive Security Reference

> **LEGAL WARNING:** Using these techniques without written authorization is a criminal offense.
> Penalties include prison time (5-20 years), fines, and criminal records.
> Only use on your own lab, CTF challenges, or with a signed penetration testing agreement.

Run this command to see all 14 attack categories with full examples:

```bash
python cli/nimpacket_cli.py redteam
```

### Attack Categories

| # | Attack | Commands Used | Risk Level |
|---|--------|-------------|------------|
| 1 | **SYN Flood** (DoS) | `send tcp-syn` with spoofed source | Critical |
| 2 | **ARP Spoofing** (MITM) | `send arp-frame`, `craft arp-reply` | Critical |
| 3 | **ARP Scanning** (Recon) | `send arp-frame` | Medium |
| 4 | **ICMP Flood / Smurf** (DoS) | `send icmp-echo` to broadcast | Critical |
| 5 | **UDP Flood** (DoS) | `send udp` with spoofed source | Critical |
| 6 | **Port Scanning** (Recon) | `send tcp-syn` + `listen` | Medium |
| 7 | **IDS/IPS Evasion** | `send-fragmented` (5 strategies) | High |
| 8 | **Packet Sniffing** | `listen` | High |
| 9 | **DHCP Starvation** (DoS) | `craft dhcp-discover` + `send raw` | Critical |
| 10 | **DHCP Spoofing** (MITM) | `craft dhcp-request` | Critical |
| 11 | **DNS Reconnaissance** | `craft dns-query` (MX/NS/ANY/TXT) | Low |
| 12 | **IP Spoofing** | Any `send` with fake `--src-ip` | High |
| 13 | **Raw Packet Injection** | `craft` + `send raw` | High |
| 14 | **DHCP Release Attack** (DoS) | `craft dhcp-release` | High |

**27 commands** out of 54 have offensive potential. The `redteam` command shows full usage examples and explains how each attack works.
