Wirecat: A Native C Networking Utility

What Wirecat Is

Wirecat, or wcat, is a native C stream and session utility for Linux/POSIX systems. It is designed for connecting, listening, relaying, proxying, transferring files, inspecting traffic, and handling interactive process sessions from one compact command-line binary.

The project started from a practical need: I wanted a tool that keeps the direct feel of traditional socket utilities, but with modern transport support, clearer command structure, safer defaults, and documentation from the first release.

The Design Goal

The goal is not to build a large framework. Wirecat is meant to be a focused operator utility: one binary, predictable command behavior, direct input and output, clear errors, and surfaces that work well in scripts.

That design affects the shape of the project. Commands are grouped by workflow. The code is split into small modules. TLS behavior has explicit verification controls. Listener access control uses IP and CIDR rules. JSON logs are available for automation, while human-readable output stays useful for interactive work.

Why Another Networking Utility

There are already classic tools for sockets, pipes, and quick listeners. They are useful because they are direct. The problem is that modern workflows often need more than a plain TCP stream. A single debugging session may involve TLS verification, a proxy path, a local Unix socket, a file capture, a process bridge, or a structured log stream that another program can parse.

I built Wirecat to bring those workflows into one native tool without turning the command line into a framework. The important part is the balance: keep the core commands short, but make the advanced features explicit when the operator needs them. A tool like this should be easy to run from a terminal and also predictable enough to run from scripts and CI jobs.

What I Wanted From Version 0.1.0

For the first public release, I did not want a placeholder project that only demonstrates a parser. Version 0.1.0 needed to have a real command surface, real network behavior, packaging, tests, fuzzing notes, and enough documentation that another person could install it and understand the intended boundaries.

The release is Linux/POSIX-first. That was a deliberate decision because the project uses features that are native to that environment: POSIX PTYs, Unix domain sockets, Linux VSOCK, SCTP availability, Debian packaging, and OpenSSL integration. Windows can be considered later, but it should be designed honestly around Windows APIs instead of pretending every Linux feature has a direct equivalent.

Main Capabilities

The first release covers the core workflows I wanted before calling the tool usable. It supports TCP, UDP, SCTP, Unix domain sockets, Linux VSOCK, IPv4, IPv6, TLS, mTLS, QUIC single-stream transport, SOCKS5 proxying, HTTP CONNECT proxying, HTTP CONNECT proxy server mode, bidirectional relay mode, file send and receive, process execution, POSIX PTY-backed sessions, broker/chat mode, JSON logs, hex inspection, timeouts, and CIDR allow/deny controls.

The Linux/POSIX focus is intentional. Features like POSIX PTY, Unix sockets, SCTP, VSOCK, and Debian packaging fit that environment naturally. Windows support would need its own plan instead of being treated as a simple recompile.

Command Model

Wirecat is organized around explicit subcommands. The command name tells you the workflow before you read the options. Connect mode opens an outbound connection. Listen mode accepts a peer. Send and recv handle file movement. Relay mode bridges two endpoints. Broker mode handles multiple clients. Proxy mode runs an HTTP CONNECT proxy server.

That structure keeps common commands readable and avoids hiding very different behaviors behind a pile of flags. It also gives each workflow a clearer validation path. A connect command should validate a host and port. A relay command should validate endpoint grammar. A broker command should validate client limits and buffer sizes. Keeping those surfaces separate makes error handling cleaner.

wcat connect [options] HOST PORT
wcat listen  [options] HOST PORT
wcat send    [options] FILE HOST PORT
wcat recv    [options] FILE HOST PORT
wcat relay   [options] LEFT RIGHT
wcat broker  [options] HOST PORT
wcat proxy   [options] HOST PORT

Basic Usage

The command surface uses subcommands for the main workflows. A user should be able to look at the command and understand whether it connects, listens, transfers a file, relays endpoints, starts a broker, or runs a proxy.

wcat connect example.com 80
wcat listen 0.0.0.0 4444
wcat listen --keep-open 0.0.0.0 4444
wcat --version

Common Options

Most options are shared across the workflows where they make sense. Transport selection, TLS configuration, logging, timeouts, proxy configuration, process execution, PTY allocation, and access control all have explicit flags. I prefer this style because it is readable in shell history and easier to audit in saved scripts.

The important safety point is that risky behavior is visible. Disabling TLS verification requires --tls-insecure. Starting a process requires --exec. Allocating a PTY requires --pty. Opening a listener requires choosing the bind address. These decisions should be visible in the command line.

-u, --udp
-4
-6
-k, --keep-open
--json
--hex
--timeout SEC
--tls
--quic
--tls-insecure
--ca-file FILE
--sni NAME
--cert FILE
--key FILE
--client-cert FILE
--client-key FILE
--require-client-cert
--proxy URL
--exec PATH
--pty
--allow LIST
--deny LIST

Transport Coverage

The transport layer is wider than plain TCP. TCP and UDP cover the common internet workflows. SCTP is useful in environments where stream-oriented SCTP behavior matters. Unix domain sockets are useful for local services, local brokers, and testing daemon-style workflows without exposing a TCP port. Linux VSOCK is useful in virtualization contexts where host and guest communication should avoid normal network addressing.

IPv4 and IPv6 are handled through normal address resolution. The -4 and -6 options give the operator a way to force the address family when a hostname resolves to more than one family or when a test needs to prove behavior on one stack.

wcat connect -4 example.com 80
wcat connect -6 example.com 80
wcat listen -u 0.0.0.0 5353
wcat listen --unix --exec /usr/bin/tee /tmp/wcat.sock
wcat connect --unix /tmp/wcat.sock
wcat listen --sctp 0.0.0.0 5555
wcat connect --sctp 127.0.0.1 5555
wcat listen --vsock any 5555
wcat connect --vsock 2 5555

TLS And mTLS

TLS support is provided through OpenSSL. Client verification is enabled by default, and the user can set a CA bundle, SNI name, ALPN value, client certificate, and client key. Server mode can require verified client certificates for mTLS workflows.

The insecure mode is explicit. It exists for local testing and controlled private labs, not for production trust decisions.

wcat connect --tls example.com 443
wcat connect --tls --ca-file ./ca.pem --sni service.example service.example 443
wcat connect --tls --ca-file ./ca.pem --sni service.example --client-cert client.crt --client-key client.key service.example 443
wcat listen --tls --cert server.crt --key server.key 0.0.0.0 8443
wcat listen --tls --require-client-cert --ca-file ./clients-ca.pem --cert server.crt --key server.key 0.0.0.0 8443

QUIC Support

Wirecat includes QUIC single-stream transport support when it is built against an OpenSSL version that exposes the OpenSSL QUIC APIs. The QUIC path shares the same general TLS controls for certificates, SNI, ALPN, and verification.

If the linked OpenSSL build does not provide QUIC APIs, the command-line option remains visible but Wirecat returns a clear runtime error. That is better than hiding the feature or failing silently.

wcat connect --quic --alpn h3 example.com 443
wcat listen --quic --cert server.crt --key server.key 0.0.0.0 8443
wcat listen --quic --tls-insecure --cert server.crt --key server.key --pty --exec /bin/bash 127.0.0.1 8443

QUIC Lessons From Testing

QUIC was the most sensitive part of the release because it depends on the OpenSSL version and on correct handshake configuration. During testing, I treated QUIC as a first-class feature but also documented the dependency clearly. If the OpenSSL build does not expose the required QUIC APIs, Wirecat should fail in a way the user can understand.

The practical troubleshooting checklist is simple: both peers must use --quic, ALPN must match the intended workflow, the server must have a certificate and key, the client must trust the certificate or explicitly choose insecure local testing, and the linked OpenSSL build must support QUIC. That is now captured in the wiki so users are not left guessing when a handshake fails.

Relay Mode

Relay mode is one of the most useful parts of Wirecat. It connects two endpoints and moves bytes in both directions. Endpoints can be standard input/output, TCP connections, TCP listeners, Unix sockets, files, processes, or PTY-backed processes.

This makes Wirecat useful for temporary bridges, local debugging, controlled service inspection, capture workflows, and small test setups where writing a custom relay would waste time.

wcat relay - tcp:example.com:80
wcat relay listen:127.0.0.1:9000 tcp:10.0.0.5:22
wcat relay unix-listen:/tmp/wcat.sock exec:/usr/bin/tee
wcat relay tcp:127.0.0.1:9000 file:./capture.bin
wcat relay listen:0.0.0.0:4444 pty:/bin/sh
wcat relay --hex --timeout 10 tcp:127.0.0.1:8000 file:./trace.bin

Relay Endpoint Grammar

Relay mode uses a small endpoint grammar. I wanted it to be readable enough that a command can be understood without opening the documentation. The left and right sides describe what Wirecat should connect together.

The current grammar intentionally stays conservative. A stable small grammar is better than an expressive one that is hard to test. More endpoint types can be added later behind the same relay abstraction, but the first release focuses on endpoints that are immediately useful.

-                    standard input/output
stdio                standard input/output
tcp:HOST:PORT        outbound TCP connection
listen:HOST:PORT     inbound TCP listener, accepts one peer
unix:PATH            outbound Unix domain socket connection
unix-listen:PATH     inbound Unix domain socket listener, accepts one peer
file:PATH            read/write file endpoint, created if missing
exec:PATH            process endpoint using pipes
pty:PATH             process endpoint using a POSIX PTY

Process And PTY Handling

Process bridging is useful, but interactive programs behave badly when they only get pipes. That is why Wirecat separates --exec from --pty. Plain --exec bridges a peer to a process through pipes. Adding --pty allocates a POSIX PTY, which is the better choice for shells and programs that expect terminal behavior.

This matters for line discipline, terminal-aware programs, job-control expectations, and general interactivity. It also makes commands honest: the operator can see whether a peer is connected to a pipe-backed process or a PTY-backed session.

wcat listen --exec /usr/bin/tee 127.0.0.1 9001
wcat listen --pty --exec /bin/bash 0.0.0.0 4444
wcat relay listen:0.0.0.0:4444 pty:/bin/sh

Proxy Workflows

Wirecat supports outbound SOCKS5 and HTTP CONNECT proxy negotiation, and it can also run a small HTTP CONNECT proxy server. This is useful when testing how a service behaves through a proxy path or when building controlled local network experiments.

wcat connect --proxy socks5://127.0.0.1:9050 example.com 80
wcat connect --proxy http://proxy.local:8080 example.com 443
wcat proxy 127.0.0.1 3128

Broker And Chat Mode

Broker mode accepts multiple clients and forwards bytes between them. Plain broker mode relays raw data. Chat mode adds client labels and escapes terminal control bytes, which makes it better for multi-user terminal chat during local labs, CTFs, and manual collaboration.

The broker is bounded. Operators can set a maximum client count and per-client buffer size. Slow clients are dropped instead of being allowed to block every other peer.

wcat broker 0.0.0.0 5555
wcat broker --chat 0.0.0.0 5555
wcat broker --chat --max-clients 16 --broker-buffer 131072 0.0.0.0 5555
wcat broker --unix --chat /tmp/wcat-chat.sock

Access Control

Listeners and brokers can use allow and deny rules based on exact IPs or CIDR ranges. Deny rules are evaluated before allow rules. The first version intentionally avoids hostname policy for accepted peers because the kernel gives the accepted peer address directly, and that is the decision point the access control layer should use.

This is not a full firewall. It is an application-level guardrail for operators who want a listener to accept only a known peer range during a lab, demo, or controlled internal workflow.

wcat listen --allow 192.0.2.0/24 0.0.0.0 4444
wcat listen --deny 198.51.100.0/24 0.0.0.0 4444
wcat broker --allow 192.0.2.10 0.0.0.0 5555

File Transfer And Inspection

Wirecat includes direct file send and receive commands for simple controlled transfers. Relay mode can also connect a network endpoint to a file endpoint for capture or replay-style workflows. For inspection, Wirecat can print hex output and JSON logs, which helps when the same command needs to work for both humans and scripts.

wcat recv ./archive.tar 0.0.0.0 9000
wcat send ./archive.tar 192.0.2.10 9000
wcat connect --json --hex example.com 80

Automation And Logging

Human-readable logs are useful during interactive debugging, but automation needs a more stable interface. Wirecat includes JSON logging so scripts can consume events without scraping prose. Hex output exists for the opposite case: a human wants to inspect bytes directly while testing a protocol, relay, or service.

The release documentation includes a JSON logging schema so external scripts can depend on event names and fields more safely. This is the kind of detail that matters when a CLI tool grows from personal use into something other people run in their own workflows.

Code Structure

The implementation is split by responsibility. The CLI parser handles command shape and validation. The socket layer owns TCP, UDP, SCTP, Unix socket, and VSOCK behavior. TLS and QUIC are isolated behind stream behavior so relay logic does not need to know whether a peer is plain or encrypted. The relay engine owns the bidirectional byte pump. Process handling owns pipe-backed and PTY-backed execution. Broker mode owns multi-client fan-out and buffering.

This structure keeps the code easier to audit. Networking tools become difficult to maintain when transport setup, command parsing, process handling, and relay loops are mixed together. Wirecat keeps those boundaries explicit.

Module Responsibilities

The codebase is organized around ownership boundaries. main.c initializes logging and signal handling, then dispatches to the selected command. cli.c validates the command-line shape. socketx.c owns address resolution and socket creation. tls.c wraps OpenSSL behavior. quic.c owns the QUIC transport when available. relay.c moves bytes. process.c handles subprocesses and PTYs. broker.c handles multi-client fan-out. filexfer.c owns send and receive workflows. proxy.c owns SOCKS5 and HTTP CONNECT negotiation. access.c owns listener allow and deny logic. log.c owns human logs, JSON logs, and hex formatting.

This is not only a code organization choice. It makes testing and review easier. When a bug appears in proxy negotiation, it should not require understanding PTY allocation. When a CLI parsing edge case appears, it should not be mixed into the relay loop. The project is still small, so keeping these boundaries clear now matters.

Testing And Release Quality

For the first release, I wanted more than a binary that compiles. The repository includes unit tests, integration tests, sanitizer targets, static analysis, Debian packaging metadata, a libFuzzer harness for CLI parsing, release checksums, reproducible build notes, and GitHub Wiki documentation.

The documented local fuzz run for version 0.1.0 ran for one hour with libFuzzer, AddressSanitizer, and UndefinedBehaviorSanitizer. It completed without crash artifacts and without ASan or UBSan findings. The Debian package was also checked through repeated clean builds with matching hashes for the generated package artifacts.

Fuzzing The CLI Surface

The fuzz harness targets CLI parsing and option validation. That may sound less exciting than fuzzing a protocol parser, but command parsing is a real attack surface for local tools, wrappers, scripts, CI systems, and packaged utilities. Bad parser behavior can become crashes, undefined behavior, confusing validation, or unexpected command interpretation.

For release validation, I ran the fuzz target for one hour with libFuzzer, AddressSanitizer, and UndefinedBehaviorSanitizer. The documented run executed 582,830,506 units over 3,601 seconds, with no crash artifacts and no sanitizer findings. The corpus retained coverage-increasing inputs from the run, so future parser changes have a better regression base.

make clean
make fuzz-harness
make fuzz-cli FUZZ_TIME=3600

Packaging And Reproducibility

Wirecat includes Debian packaging metadata because I want the release path to be practical for Debian, Kali, and Ubuntu users. The package build uses Debian hardening flags through dpkg-buildflags and inherits SOURCE_DATE_EPOCH behavior from the Debian changelog.

For the local reproducibility check, I performed repeated clean binary package builds and compared the generated package hashes. The resulting wirecat package and debug-symbol package matched across clean rebuilds. That does not replace distribution infrastructure or maintainer signing, but it is a useful baseline before publishing release artifacts.

make clean
dpkg-buildpackage -us -uc -b
sha256sum wirecat_0.1.0-1_amd64.deb wirecat-dbgsym_0.1.0-1_amd64.deb

Release Artifacts

The 0.1.0 release provides a Debian package for amd64 systems, a standalone Linux amd64 archive, a source archive, and SHA256 checksums. That gives users more than one path: install a package, unpack a standalone binary, or build from source.

The release notes and wiki describe the project from different levels. The wiki is the extended manual, while the release notes explain what changed and what artifacts belong to the release.

wirecat_0.1.0-1_amd64.deb
wirecat-0.1.0-linux-amd64.tar.gz
wirecat-0.1.0-source.tar.gz
SHA256SUMS

Security Positioning

Wirecat is a general-purpose network utility. It is intended for lawful administration, debugging, research, educational use, and authorized testing.

The project intentionally avoids persistence, stealth, autonomous operation, embedded scripting, offensive automation, and C2 framework behavior. Use it only on systems and networks that you own, administer, or have explicit permission to test.

What Wirecat Is Not

Wirecat is not a red team framework, not a persistence mechanism, not a stealth agent, and not a remote tasking platform. It does not embed a scripting engine, does not hide itself, does not install persistence, and does not try to automate offensive chains.

That boundary matters because many networking tools can be misused. The project documentation is clear about responsible use: run it only on systems and networks that you own, administer, or have explicit permission to test. The useful workflows are administration, debugging, authorized research, education, lab work, transport inspection, and controlled relay testing.

Current Limitations

The first release is intentionally Linux/POSIX-focused. Windows is not supported yet. QUIC depends on OpenSSL QUIC APIs being available in the linked OpenSSL build. SCTP depends on host kernel and library support. VSOCK depends on a virtualization environment that supports AF_VSOCK. PTY behavior depends on POSIX terminal semantics.

Those limitations are better documented than hidden. A tool is easier to trust when it says what it supports and what it does not support. Future work can add portability layers, expanded relay expressions, more policy modes, and deeper test coverage, but the first release is focused on getting the Linux/POSIX foundation correct.

Documentation Layout

The documentation is split by reader intent. The wiki is for deeper usage: installation, TLS and mTLS, QUIC, relay mode, broker mode, release verification, and troubleshooting. The repository docs cover architecture, JSON logging, fuzzing, reproducible builds, and the manual page.

I like this split because users can start from a focused project page, then move into dedicated wiki pages when they need deeper examples or troubleshooting details.

Release And Documentation

The 0.1.0 release provides a Debian package, a standalone Linux amd64 archive, a source archive, and SHA256 checksums. The GitHub Wiki contains deeper pages for installation, usage, TLS and mTLS, QUIC, relay mode, broker mode, the security model, release verification, and troubleshooting.

Wirecat starts with a focused goal: provide a reliable native networking utility for Linux/POSIX workflows, backed by a clean C codebase, practical command design, tests, fuzzing, packaging, and documentation from the first release.

https://github.com/blue0x1/wirecat
https://github.com/blue0x1/wirecat/releases/latest
https://github.com/blue0x1/wirecat/wiki