Project 1 - OMEGA: L4 Scanner

Author: Ľubor Pačaj (xpacajl00)
Language: C (C17)
Assignment See ASSIGNMENT for details
License: GPL-3.0-only (see LICENSE)

Project Overview

Layer 4 (L4) network scanner that reports TCP and UDP port states on a target host. Supports IPv4 and IPv6, resolves hostnames via DNS, and uses raw sockets for packet injection with libpcap sniffing for responses.

Build and Run Instructions

Prerequisites

• Preferred: reference VM x86_64-linux with the Nix devShell c (see make NixDevShellName).
• Manual setup: any recent Linux with make, gcc, libpcap, and netcat (for tests).
• Running the scanner requires super-user privileges (raw sockets and pcap capture).

Compilation

To build the project, use the provided root-level Makefile:

# To get the required Nix devShell name (in this case prints c)
make NixDevShellName

# Activate the reference C dev environment (recommended)
nix develop --refresh "git+https://git.fit.vutbr.cz/NESFIT/dev-envs.git#c"

# To build the executable (ipk-L4-scan)
make

The build process produces a standalone executable named ipk-L4-scan in the project root.

Usage

sudo ./ipk-L4-scan -i INTERFACE [-u PORTS] [-t PORTS] HOST [-w TIMEOUT] [-h|--help]
sudo ./ipk-L4-scan -i               # lists active interfaces and exits
sudo ./ipk-L4-scan -h | --help      # prints usage and exits

Arguments

• -i INTERFACE: Required. When passed alone, prints active interfaces and exits 0.
• -t PORTS: TCP ports (num-num or num,num,...). Mixed range/list combos are intentionally not supported.
• -u PORTS: UDP ports (num-num or num,num,...).
• -w TIMEOUT: Optional timeout per port in milliseconds (default 1000).
• HOST: Hostname or IPv4/IPv6 address. Multiple DNS answers are all scanned.

Output format

Each result line on stdout: IP PORT PROTOCOL STATE

Examples

sudo ./ipk-L4-scan -i lo -t 22 localhost
127.0.0.1 22 tcp open

sudo ./ipk-L4-scan -i lo -t 21,22 -u 53,67 localhost
127.0.0.1 53 udp closed
127.0.0.1 67 udp open
127.0.0.1 21 tcp closed
127.0.0.1 22 tcp open

Implemented Features and Behavior

• TCP SYN scan: Sends SYN, waits, retries once before declaring filtered.
  • open: SYN-ACK received.
  • closed: RST received.
  • filtered: No response after retry within timeout.
• UDP scan: Sends empty datagram.
  • closed: ICMP Type 3 Code 3 (port unreachable) seen.
  • open: No ICMP response within timeout.
• Interface discovery: -i alone prints active interfaces to stdout.
• IPv4/IPv6 support: All resolved addresses are scanned.

Design Decisions

1. Response Monitoring with libpcap: Instead of blocking on standard socket reads, the application uses libpcap to eavesdrop on all relevant traffic (TCP and ICMP) on the interface, which is more reliable for raw packet responses.
2. Timeout Chunking: To improve speed, the specified timeout is split into 10 intervals . The scanner sleeps for one interval and then checks if the expected packet has been captured, allowing it to return results faster than the full timeout duration if the network is responsive.
3. TCP Retry Logic: According to the assignment, a port is only marked "filtered" after a lack of response is verified with a second packet.
4. Pseudo-Header Checksums: Manual calculation of TCP checksums includes the mandatory IPv4 or IPv6 pseudo-header to ensure compatibility across different network layers.

Testing

Automated tests are provided as bash scripts that utilize netcat (nc) to simulate open and closed ports on the loopback (local) interface.

Reproducible Test Procedure

To execute the automated test suite, run:

make test

This target executes test_tcp.sh and test_udp.sh, which perform the following:

1. What is tested: TCP/UDP port states (open/closed/filtered) for IPv4 and IPv6, range handling, and edge cases (invalid ports, missing arguments).
2. Why: To ensure the scanner correctly identifies port statuses according to RFCs and the project specification.
3. How: By creating local listeners using nc, running the scanner against them, and grepping the output for expected status strings.
4. Environment: Reference VM (x86_64-linux) with libpcap and netcat installed.
5. Results: Detailed pass/fail counts are printed to stdout and also written to tests/test_tcp.out and tests/test_udp.out.

Concrete Test Cases (Input / Expected / Actual)

The following examples are included directly in the automated scripts and demonstrate concrete evaluator-style checks.

1. TCP closed port (loopback)

• Input: sudo ./ipk-L4-scan -i lo 127.0.0.1 -w 500 -t 53532
• Expected output contains: 127.0.0.1 53532 tcp closed
• Actual output (example from a passing run): 127.0.0.1 53532 tcp closed

2. TCP open port with nc listener

• Input: start listener nc -l 53531, then run sudo ./ipk-L4-scan -i lo 127.0.0.1 -w 500 -t 53531
• Expected output contains: 127.0.0.1 53531 tcp open
• Actual output (example from a passing run): 127.0.0.1 53531 tcp open

3. UDP closed port (ICMP unreachable)

• Input: sudo ./ipk-L4-scan -i lo 127.0.0.1 -w 500 -u 53532
• Expected output contains: 127.0.0.1 53532 udp closed
• Actual output (example from a passing run): 127.0.0.1 53532 udp closed

4. UDP open port in scanned range (slow test style)

• Input: start listener nc -u -l 20026, then run sudo ./ipk-L4-scan -i lo 127.0.0.1 -w 200 -u 20000-20030
• Expected output contains: 127.0.0.1 20026 udp open
• Actual output (example from a passing run): 127.0.0.1 20026 udp open

5. Invalid argument handling

• Input: sudo ./ipk-L4-scan -i lo 127.0.0.1 -u 65536
• Expected: error message containing invalid and non-success behavior
• Actual output (example): error line with invalid is produced and test is marked PASS

Note: The tests use a chosen high port range by default; if other services on your system are bound to those ports the test results may be incorrect.

Known Limitations

• Port specification supports either a single range (num-num) or a comma-separated list of single ports, not mixed range/list combinations.
• Linux-only support.
• Only two link-layer datalink types are supported in pcap capture: DLT_EN10MB and DLT_RAW.
• VPN-related note: tunnel interfaces (for example tun0) often use DLT_RAW and do not carry an Ethernet header. This scanner explicitly handles that case. Linux Wi-Fi/other interfaces usually expose an emulated Ethernet header (DLT_EN10MB), which is why Linux-specific behavior is assumed here.
• Other pcap datalink formats (for example Linux cooked capture types such as DLT_LINUX_SLL / DLT_LINUX_SLL2) are currently not supported.

Assignment Coverage

• CLI per spec: -i, -t, -u, -w, -h|--help, DNS resolution, IPv4/IPv6 handling.
• Output format matches IP port protocol state on stdout; errors to stderr; exit code 0 on success paths.
• TCP SYN scan with retry before declaring filtered.
• UDP scan using ICMP Port Unreachable for closed; no response implies open.
• -i alone lists active interfaces and exits 0.

AI Assistance

• The automated test suite and related test scripts were developed with assistance from an AI tool to accelerate iterative development and reduce downtime during the coding process.
• The AI was used as a supplementary learning and explanation resource for networking concepts (for example, libpcap library usage or various function parameters explanation).
• AI contributed to drafting and polishing this README.

References and Citations

• RFC 793: Transmission Control Protocol (1981) [Accessed 16 March 2025].
• RFC 8200: Internet Protocol, Version 6 (IPv6) Specification (2017) [Accessed 16 March 2025].
• RFC 768: User Datagram Protocol (1980) [Accessed 16 March 2025].
• Klassen, F. & Turner, A.: Checksum calculation logic adapted from checksum.c in the tcpreplay project (GPL-3.0). Source: https://github.com/appneta/tcpreplay [Accessed 16 March 2025].