gogo: a red team scanner where the port list is a DSL, not a constant

The feature list is a statement about packet discipline

gogo describes itself as a highly controllable and extensionable automated scanning engine for red teams, and the repository description gives the same idea in Chinese before the English line. Four topics are attached: recon, redteam, security and security-tools.

The feature list in the README reads differently from most scanner READMEs, because several entries are about restraint rather than capability. There is a minimal packet principle, described as sending as few packets as possible to get as much information as possible. There is controllable heuristic scanning. There is a claim of harmless scanning, with the specific mechanism given: every added poc goes through manual review. And there is a performance claim about speed and low memory and CPU use.

Those four belong together. A scanner that shoots every template at every port will find things, but it is also the reason a target's IDS lights up. The design goal here is that a scan looks like ordinary traffic from a curious client, which is a constraint the rest of the feature list is built around.

The remaining features are the ones you would expect from a mature tool: free port configuration, active and passive fingerprint recognition, key information extraction such as title and certificate plus custom regular expressions, nuclei poc support through the neutron engine, a DSL so you can customise gogo through configuration files, thorough output design, and almost no dependency on third-party libraries. That last one is quantified: pure native Go, and the claim is that full vulnerability and fingerprint recognition works even on Windows 2003, which tells you something about how little it leans on the host operating system.

Port presets that compose with commas

Most scanners give you a port range and a flag for the top thousand ports. gogo gives you named tags and lets you combine them in one argument, which is the single feature that changes how you express a scan.

gogo -i 192.168.1.1/24 -p win,db,top2

The rules are spelled out. A bare dash means 1-65535, the whole space. A range like 1-1000 is a range. The tag `common` means ports commonly seen inside a network. `top2` and `top3` mean commonly seen web ports on the public internet. `all` is the union of every preset tag. And because configuration is comma-separated, you can mix a range with tags.

gogo -i 1.1.1.1/24 -p 1-1000,common,http,db

That second example is the one that shows the design working: a range for thoroughness, plus tags chosen for the environment. Running a scan against a datacentre and against a home network should not use the same port list, and a tag system means you express that difference once and reuse it.

The full list is inspectable at runtime with `gogo -P port`, which prints every tag and its ports, grouped by port type. The README shows that output beginning with `top1`, `top2` and `top3` in full, then `docker` at 2375 through 2380, then service-specific tags including `lotus`, `dubbo` and `oracle`. Being able to read the table rather than guess at it matters, because a tag is only useful if you know what is inside it.

Heuristic scanning and the mode flags

The heuristic section is where the README gets careful about a caveat, which is a good sign. When the subnet mask of your target range is smaller than 24, the recommendation is to enable smart mode scanning. The example uses a /12 range, and the README notes that such a run produces a lot of output, so it suggests the automatic file output flag and leaving the terminal for logs only.

gogo -i 172.16.1.1/12 -m ss --ping -p top2,win,db --af

Four flags do real work here. `-m ss` selects supersmart mode, and the README says there are also ss and sc modes for different situations, with the principle documented on the wiki. `--ping` checks whether an address responds before fingerprinting or fetching information from it, which cuts pointless packets to hosts that are not there. And `--af` means the output filename is generated for you.

The caveat is stated directly and is the kind of warning that earns trust: not being able to be pinged does not mean a target is definitely not alive, and you should keep that in mind. It is exactly the failure mode of ICMP pre-screening against a firewalled host that is, in fact, serving something.

So the modes are a ladder of increasing thoroughness. The default mode for a small range, ss and sc when the range is large, and ping pre-screening when you want fewer packets at the cost of possibly missing hosts.

Workflows are saved commands, and the CLI wins

The README is blunt that heuristic scan commands have grown complicated, and then offers workflows as the answer: write the complex command into a configuration file and invoke it by name.

gogo -w 172

The built-in workflow named 172 defaults to the `all` port preset, which makes that invocation equivalent to a /12 range in supersmart mode with ping pre-screening, automatic file output and every port. The README then immediately shows how to narrow it by adding flags, because a preset you cannot narrow is not much use.

Some workflows are reserved configurations rather than targets. They supply settings without a target, so you add one yourself with `-i`.

gogo -w ss -i 11.0.0.0/8

The precedence rule is stated once and matters: parameters preset in a workflow have lower priority than the command line, so anything you type overrides the file. That is the correct design for saved commands, because it means a workflow can never trap you into scanning something you did not intend.

Two more commands round out the surface. `gogo -P workflow` lists every available workflow, in the same way `-P port` lists ports. And the current flag surface is defined by `gogo -h`, which the README states explicitly, along with a convention that trips up newcomers: multi-character long options need a double dash, such as `--ipp`, `--sp` and `--ef`, while a single dash is only for single-character options such as `-i`, `-p` and `-F`.

Filtered output as deflate-compressed JSON Lines

gogo writes its results to a file next to the binary, and the format is specific enough to be worth knowing. Running with automatic file naming produces a file whose name encodes the target, the port set and the mode, something like a dot-prefixed name carrying the address, the port preset and `_dat.dat`. The first file uses the `.dat` suffix and a number is appended on a name collision.

The content is deflate-compressed JSON Lines, and gogo can read it back and reformat it into something readable with `-F`, which is how you get a per-host grouped view of the same scan instead of a stream of lines.

For chaining into other tools there is `-q` or `--quiet`, which suppresses the log lines and keeps only results on standard output. That is the difference between a readable terminal session and something you can pipe.

The filtering story was reworked recently and the README is explicit about the split into three separate flags. `--filter` filters historical results. `--output-filter` filters the live output. `--scan-filter` stops a deep scan early. Collapsing those into one flag would have been tidier and less useful, because filtering what you already have and filtering what you are still collecting are different decisions with different costs.

From CLI tool to embeddable engine across three releases

The three most recent releases describe a project moving from a command line tool towards a library, and the breaking changes are worth reading before you build on it.

v2.14.0 in July 2025 was itself labelled a breaking update, because it added support for writing multiple tasks to one file and restructured the output file format around that. It also added deriving the output format from the `-f` suffix when neither `-o` nor `-O` is given, excluding ports with a `!` marker, and automatic merging of scan results.

v2.14.1 in December 2025 carried an explicit breaking-change warning: global variables were removed and the internal structure was refactored, with a note that anyone using gogo as a library might need to adjust their code. The same release implemented the gogo SDK with examples, refactored the SDK interface, added scan timing, and fixed a TCP fingerprint loading failure, an ineffective `-v`/`-e` pair, and a CIDR parsing panic in `-m s`/`-m ss` mode.

v2.15.0 in July 2026 is the one that spells out the new integration points, and the list reads like a library API design. Context support, so a scan task can be cancelled and exit gracefully. A result callback, so results stream to the caller as they arrive instead of after the scan ends. A resource provider, so fingerprints, templates and port configuration can be injected from outside instead of using the embedded data. `BeforeInit` and `AfterInit` hooks for extension around initialisation. A `RunWithArgs` entry point exposing a reusable runner. And an instance-level proxy dialer, so concurrent tasks can use different proxies rather than sharing one global transport.

That last one is the clearest signal of direction. A tool that only needs to run scans does not care which proxy each concurrent task uses.

A repository with a v2 directory and a tinygo experiment

The tree is short enough to be revealing: `.github/`, `.gitignore`, `.gitmodules`, `LICENSE`, `README.md`, `make.bat`, and then `v2/`, `tools/` and `tinygo/`, with a `.claude/` directory alongside them.

Two of those entries are worth pausing on. The `tinygo/` directory suggests an experiment with compiling gogo under TinyGo, which is the usual route to much smaller binaries for tools you push onto target machines, where a 40 megabyte Go binary is a liability rather than a detail. And `make.bat` instead of a Makefile suggests that Windows is a first-class build target rather than an afterthought, which fits the README's claim about running on Windows 2003.

The `.gitmodules` entry means at least some dependencies are vendored as submodules, and the feature list's claim of almost no third-party dependency is relative rather than absolute. `v2/` as the main source directory tells you where the current code lives relative to the repository history.

Documentation is split across three places, which is the main friction in adopting this. The README links a blog post introducing gogo, the full wiki at chainreactors.github.io/wiki/gogo, and a separate templates repository at chainreactors/templates holding the fingerprints and pocs. The templates repository being separate is the most architecturally interesting thing here: it means the database of what to look for is versioned independently of the scanner, and the SDK's resource provider is the direction that pushes further, letting a caller supply that data at runtime.

The project is GPL-3.0 licensed, with 2,138 stars, 201 forks and 19 open issues, the last push on 2026-07-28 and no archive flag.

Editorial conclusion

gogo is aimed at people who have outgrown a fixed port list and a fixed fingerprint database, and its design follows from that: port presets as tags, heuristics as selectable modes, templates and pocs as replaceable data, and a DSL on top when the flags stop being enough. Two things to weigh before adopting it. The README is written in Chinese and the English documentation lives on the chainreactors wiki, which is where the flag reference actually is. And v2.14.1 was a breaking release that removed global variables, so anyone embedding gogo as a library had to rework their integration. The current release, v2.15.0 from 2026-07-14, moves further in that direction with context cancellation, result callbacks and injectable resources. The last push was 2026-07-28.

Frequently asked questions

Official sources

1. chainreactors/gogo on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases