tcpcat - Fast network scanner in Go with an eBPF/AF_XDP eng

项目说明

tcpcat — a fast network scanner in Go, with an eBPF/AF_XDP engine

<di="center">

*eBPF/AF_XDP kernel-space I/O · service & OS detection · C · WASM detection scripting*

![CI]()
![OpenSSF Best Practices]()
![Go Report Card]()
![Latest Release]()
![Discord]()
</div>

Fast network scanner in Go with an eBPF/AF_XDP engine, service and OS
detection, C, and JSON/SARIF reports. Built for authorized
security assessments.

<!--
DEMO: record a short terminal GIF of a real scan and drop it at docs/demo.gif,
then uncomment the line below. A ~10s asciinema/ of the Quick start
command works well.
!tcpcat demo
-->

Quick start

Prefer a prebuilt binary or a .deb/.dmg? Grab one from the
releases page. To build from
source, see Installation.

Add -j report.json for a full JSON report or --sarif report.sarif for
SARIF 2.1.0 output.

> Only scan hosts and networks you own or ha written permission to
> test. scanme.nmap.org is a public host Nmap provides for scan testing. See
> the Legal & Ethical Notice.

More recipes — eBPF high-throughput scans, OT/ICS, scope files, WASM detection
scripts, AWS discovery — are in examples/.

---

O

tcpcat is a next-generation network reconnaissance engine built in Go, engineered for high-throughput, authorized network assessment. It provides configurable packet and timing behavior for e IDS/IPS monitoring across multiple OSI layers.

Project Status

tcpcat is a dual-licensed project (AGPL-3.0 or commercial) maintained by Nicolas Blondelle (NycolazSec). It is free and open source under the AGPL-3.0, and does not provide a hosted scanning service, paid support, managed assessments, or customer accounts. Embedding it in a proprietary product or hosted service without the AGPL's copyleft obligations requires a commercial (OEM) license (see COMMERCIAL-LICENSE.md). The project is intended for learning, network administration, and authorized security testing.

Core Capabilities

L2-L7 Reconnaissance

Multi-protocol port enumeration (TCP, UDP, ICMP)

L3/L4 service topology mapping with fingerprinting

L7 intelligence integration

Asynchronous DNS/mDNS/NetBIOS service discovery

Ad Assessment Controls (Phase 4 - 29 Techniques)

Timing : Configurable jitter (0.0-1.0 coefficient)

Fragmentation Controls: IPv4 datagram fragmentation for monitoring

Decoy Traffic: Configurable source patterns for authorized testing

Protocol Controls: TCP/UDP window tuning and source-port selection

Traffic Modeling: Configurable traffic-pattern behavior for assessment scenarios

Programmable Intelligence

WebAssembly (WASM) detection engine with sandboxed execution

Custom protocol dissectors in Rust, C, Go, or AssemblyScript

Concurrent detection rules without memory o

---

Architecture

Kernel-Space Operations (eBPF/AF_XDP)

Direct packet I/O at the network dri, bypassing the socket layer entirely. Achie performance (~1M pps per core) with minimal CPU o.

Modular E Pipeline

Detection Integration

Real-time C across multiple intelligence feeds ( API, Google OS database).

---

Installation & Prerequisites

Requirements:

Go 1.26+

Linux kernel 5.8+ (for eBPF/XDP, optional but recommended)

CAP_SYS_ADMIN or root (for raw socket operations)

gcc/clang (for eBPF compilation, optional)

Install with Go (fastest):

Build from source:

Prebuilt packages: .deb, .dmg, and per-platform binaries are attached
to each GitHub release.

---

Common Scenarios

Rapid Topology Mapping (1K Most Common Ports)

Service Enumeration with Fingerprinting

IDS/IPS (Authorized Audits Only)

Ultra-Fast Enumeration (eBPF Mode)

Distributed Traceroute (Layer 3 Topology)

Enterprise Authorized Audit

Create a scope file containing only explicitly authorized IP addresses, CIDRs, or hostnames. Blank lines and comments beginning with # are ignored.

Run a conser scan that restricts resol to that scope and produces operational reports:

safe-production sets timing -T 2, limits scan traffic to 300 packets per second, enables service detection, and disables e, fragmentation, decoys, smart bypass, and unlimited concurrency. It is intended for appro assessments; it does not replace written authorization or a documented maintenance window.

Industrial / OT networks

Programmable logic controllers, RTUs and other field devices can fault under ordinary scanning: a half-open SYN can wedge a small TCP stack, parallelism and high rates o tiny connection tables, and malformed or fragmented packets are exactly the kind of input that trips fragile firmware. The ot profile is built for these networks — deliberately gentle rather than stealthy:

ot uses a full TCP connect scan only (never a raw SYN, UDP, or eBPF/AF_XDP scan), one connection at a time (-w 1), a 5 packets-per-second rate, timing -T 1, and sends nothing crafted — no e, fragmentation, decoys, or smart bypass. Service detection stays on but only reads what a device offers; no acti query is sent to control-plane ports. When no ports are given, it scans a curated set of industrial control ports and names the protocol behind each open one:

| Protocol | Port | Protocol | Port |
|---|---|---|---|
| S7comm (Siemens) | 102 | OPC UA | 4840 |
| Modbus | 502 | OMRON FINS | 9600 |
| Red Lion Crimson | 789 | DNP3 | 20000 |
| Foundation Fieldbus | 1089/1091 | ProConOS | 20547 |
| Niagara Fox (Tridium) | 1911/4911 | PROFINET | 34962/34964 |
| PCWorx (Phoenix Contact) | 1962 | EtherNet/IP | 2222/44818 |
| IEC 60870-5-104 | 2404 | BACnet | 47808 |
| CODESYS | 2455 | | |

By default, OT ports are named passively — no query is sent to a control port. To read an exact and (which enables C), add --ot-probe:

--ot-probe sends one well-formed, read-only protocol query per supported port and parses the reply. Currently supported: Modbus (function 43 / MEI 14, "Read Device Identification" → , product, re) and EtherNet/IP (encapsulation "List Identity" → product name, re). It ne a malformed frame and ne to or commands the device. It only fires on ports with a registered probe; any other port is still named passively. Because even a legitimate query can disturb the most fragile equipment, --ot-probe is strictly opt-in and is ne by the ot profile on its own.

Even the ot profile is not risk-free on the most sensiti. Scan only within an authorized scope and maintenance window, and coordinate with the OT/process owner first.

Use a valid earlier tcpcat JSON report as a baseline to identify newly exposed ports, service/ changes, and newly detected CVEs:

The baseline must be a non-empty JSON report created by tcpcat. A new, empty file cannot be used as a baseline.

---

CLI Reference

Target Specification

IPv6 literals, IPv6 CIDRs (capped at a /108, ~1M hosts, to avoid trying to
enumerate an infeasible address count), and hostnames that only resolve to
AAAA records are all accepted. -sT/-sU/service detection work over IPv6
exactly as over IPv4; the raw-socket scan techniques below (-sS/-sA/-sW/
-sN/-sF/-sX) and --ebpf remain IP and return a clear error if
pointed at an IPv6 target instead of silently misbehaving.

Discovery Methods

Scan Techniques

Port Specification

Service Intelligence

On a 443/8443 port, -sV also runs an independent TLS/certificate
probe and attaches the result as tls in JSON output: negotiated
/cipher, certificate subject/issuer/expiry, and warnings for a
self-signed or expired certificate, a hostname mismatch, a deprecated
protocol (< TLS 1.2), or a known-insecure cipher suite. It always
inspects the certificate presented, valid or not -- an invalid cert is
the finding, not a reason to skip the probe.

The same probe also reports post-quantum readiness (pqc_group/pqc_ready
in JSON): on TLS 1.3, tcpcat's Go toolchain offers a hybrid ML-KEM key
exchange (X25519MLKEM768, SecP256r1MLKEM768, or SecP384r1MLKEM1024)
by default, so whiche the target actually negotiates says whether
it's ready for the ongoing NIST post-quantum migration. A TLS 1.3 target
that falls back to a classical group (e.g. plain X25519) is flagged with
a warning.

With --jarm, -sV also computes an active JARM fingerprint (jarm.hash
in JSON) on TLS ports: 10 deliberately TLS ClientHellos (different
, cipher orderings, GREASE, ALPN sets) whose responses are
fuzzy-hashed into a 62-character fingerprint. Two servers running the same
TLS stack/config produce the same JARM hash regardless of hostname or IP --
useful for identifying C2 infrastructure, cloned or rogue servers, and
misconfigured load balancers, and for cross-referencing public JARM
threat-intel feeds. Opt-in because it's 10 extra connections with
non-standard ClientHellos per target, not part of the default -sV probe.

On a web port (80/443/8080/8443/8000/8888), -sV also runs an
independent HTTP security posture probe and attaches the result as
http_posture in JSON output: which common security response headers
(Content-Security-Policy, X-Frame-Options, X-Content-Type-Options,
Referrer-Policy, and Strict-Transport-Security over TLS) are missing,
and whether .git/HEAD, .git/config, or .env are actually exposed --
each checked against the response body's own content, not just its status
code, so a site whose router returns 200 for any path doesn't get
flagged for files that don't really exist.

IDS/IPS Controls (Phase 4)

Performance Tuning

Output & Reporting

Every format may be requested in the same run; each writes its own file.
All of them group results per scanned host, so a CIDR or -iL scan
reports each address separately. The XML export carries the full -sV
picture — service name//OS, the TLS block (negotiated ,
cipher, certificate details, warnings), HTTP posture findings (missing
security headers, exposed paths), and correlated CVEs — rather than just
the port state.

--update downloads the release archi the current OS and CPU architecture, it against the release checksums.txt, and replaces the current executable atomically. It requires a published GitHub release with matching assets and may require elevated permissions when the binary is installed in a system directory. The option does not update source checkouts or package-manager installations.

Enterprise Scan Controls

Report Semantics

For every open port examined with -sV, explains the outcome of matching:

| Status | Meaning |
|--------|---------|
| matched | One or more matches were found. |
| no_match | A service and were detected, but no matching entry exists in the selected source. |
| not_assessed | A reliable service was not detected, so no lookup was possible. |

findings include a C se, remediation guidance, and confidence: "". They are correlation results, not proof that an issue is exploitable on the target.

Without --, tcpcat uses its embedded offline database. The database currently includes selected Apache, nginx, and OpenSSH ; its co is intentionally limited and an absent match is not e that a target is secure.

---

IDS/IPS Testing

Packet , fragmentation, and decoy traffic can help an authorized team assess how its monitoring controls record different scan patterns. Results depend on the network, endpoint protections, IDS/IPS configuration, and operator behavior. tcpcat does not guarantee reduced detection, bypass of controls, or access to a target.

| Mode | | O | Recommended Use |
|------|-----------|----------|-----------------|
| off | Baseline traffic | 0% | Authorized in and fast reconnaissance |
| light | Limited timing and packet | +5% | Appro assessments |
| moderate | Standard | +15% | Monitoring in controlled en |
| aggressive | Extensi | +30% | Lab with an approved test plan |
| stealthy | High- profile | +50% | Controlled monitoring- scenarios |

Performance vs. Nmap and naabu (full port range):

| Tool | Mean Time | Range (min … max) |
|------|-----------|--------------------|
| tcpcat (eBPF/XDP) | 4.466 s ± 0.744 s | 3.623 s … 5.028 s |
| nmap | 11.723 s ± 0.503 s | 11.150 s … 12.094 s |
| naabu | 20.945 s ± 0.181 s | 20.739 s … 21.077 s |

2.62× faster than nmap, 4.69× faster than naabu — full 1-65535 SYN scan across 2 hosts, 25K pps rate limit, 3 runs each.

---

Platform Support

| OS | Raw Sockets | eBPF/XDP | Status |
|----|-------------|---------|--------|
| Linux (5.8+) | ✓ | ✓ | Full support |
| Linux (<5.8) | ✓ | — | Socket-based only |
| macOS 11+ | ✓ | — | Limited (no XDP) |
| Windows 10+ | — | — | Socket-only (connect-style scans) |
| BSD | ✓ | — | Experimental |

---

Legal & Ethical Notice

AUTHORIZATION REQUIRED. tcpcat is a dual-use tool for authorized security
audits, penetration testing, network engineering research, and system
administration only. It is not a hosted or managed scanning service — there
is no remote infrastructure, no user accounts, and no scanning performed on
anyone's behalf by the maintainers. Unauthorized access to, or interference
with, a computer system is a criminal offense in most jurisdictions,
including under the U.S. Computer Fraud and Abuse Act, Articles 323-1 to
323-3-1 of the French *Code pénal*, the UK Computer Misuse Act 1990, and
equi statutes elsewhere.

Before scanning any system or network you do not solely own or administer,
you must hold explicit, written authorization from its owner, co a
documented scope and assessment window. The Operator — not the maintainers
— bears full and exclusi and ci for every
packet the binary emits and every consequence that follows, including
collateral impact, unintended denial of service, and of a
network or hosting provider's Acceptable Use Policy.

Ad options such as decoy traffic, fragmentation, and packet
exist to help an authorized team what its own IDS/IPS and
monitoring stack records under traffic patterns. They are
instruments, not a warranty: they do not guarantee
security-control bypass, reduced detection, or access to a target, and a
/banner-based C is a lead requiring , not
confirmation of exploitability.

tcpcat is provided "AS IS", with zero warranty and zero liability for
the authors and contributors, to the maximum extent permitted by law (see
LICENSE §§8–9). See NOTICE.md for the full legal notice —
software status, operator responsibility, disclaimer of warranty, dual-use
capabilities, sanctions/export-control guidance, and the contribution policy
— and SECURITY.md to report a in tcpcat itself
through a private GitHub Security Ad. Neither document is legal advice
or a compliance certification.

---

Contributing

Bug reports and pull requests are welcome — see CONTRIBUTING.md
for the de setup, coding guidelines, and pre-PR checklist, and
CODE_OF_CONDUCT.md for community expectations. Security
should be reported pri per SECURITY.md,
not as public issues. See CHANGELOG.md for release history.

---

License

tcpcat is dual-licensed:

GNU Affero General Public License v3.0 (AGPL-3.0) — free and open source;

see LICENSE. You may use, modify, and self-host tcpcat, but if you
distribute it or offer it to others over a network, you must release your
product's complete source under the AGPL.

Commercial (OEM) license — for embedding tcpcat in a proprietary product

or hosted service without the AGPL's copyleft obligations. See
COMMERCIAL-LICENSE.md.

up to and including v1.4.1 were released under the Apache License
2.0 (LICENSE-Apache-2.0.txt) and remain a
under those terms.

项目信息

开发语言：Go

Star 数：10

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Fast network scanner in Go with an eBPF/AF_XDP engine, service and OS detection, CVE correlation, and JSON/SARIF reports. Built for authorized security assessments.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。