chaos-client: querying the Chaos dataset for a domain's subdomains

A passive source with a hard domain-only query

The tool is small and its scope is defined by the API it wraps. It is a Go client to communicate with the Chaos DB API, and the Chaos API only supports a domain name to query. That single constraint shapes everything about how you use it. There is no wildcard, no certificate search, no ASN lookup, no host pattern. You name a domain and you get back the subdomains that the dataset knows about. The output for a domain is a list of hostnames, and in the documented example the command returns names covering distinct parts of an organisation's estate, including service names, staging environments, log hosts and regional subdomains. The reason a tool like this is worth having alongside your own enumeration is exactly that the dataset is passive, so it can surface hosts that your active scanning would not reach, and hosts that a certificate transparency log search would not have caught because no certificate was ever issued for them.

The rate limit is the first thing to plan around

The notes under the usage section are short and one of them is a hard constraint. The API is rate-limited to 60 requests per minute per IP. That is a per-IP limit rather than a per-key limit, which means running several instances of the client from the same host, or running a distributed scan behind a single egress address, shares one budget. The limit also interacts with the domain-only query, because a large enumeration effort that wants a result for thousands of domains will hit the ceiling quickly. The client offers no documented batching or concurrency control, and the flags list does not include a rate or concurrency option, so pacing is something you have to handle either by waiting in your own loop or by spreading requests across source addresses, and neither is something the tool helps with. For a handful of domains, or for a team running the tool on a laptop against a list of a few hundred targets, the limit is not the problem. For a continuous pipeline, it is the thing to design around.

The CLI surface is small and the flags read like every other ProjectDiscovery tool

Installing is a single go install of the command under the module path:

go install -v github.com/projectdiscovery/chaos-client/cmd/chaos@latest

And the help output lists the whole switch set, which is short enough to take in at a glance. There is a key flag for the ProjectDiscovery cloud API key, a domain flag for the domain to search for subdomains, a count flag that shows statistics for the specified domain, a silent flag to make the output silent, an output file flag, a flag for a file containing domains to search for subdomains, a json flag to print output as json, a version flag, a verbose flag, an update flag, and a flag to disable the automatic update check. The domain-list flag is worth noting, since it lets you feed a file of domains rather than one at a time, which is the natural shape for a batch run, and the json flag is what makes the output usable in a pipeline rather than only on a terminal. The key can also be supplied as an environment variable in your shell profile, which is the better habit for anything that runs on a shared machine:

export PDCP_API_KEY=xxxxx

You get the key by signing up or logging in at the ProjectDiscovery cloud site. The presence of a json flag and a silent flag, plus the shared goflags library in the dependency list, means the CLI behaves like the rest of the ProjectDiscovery tooling and will feel familiar to anyone who has used their other tools.

The library interface is the part worth embedding

The client can be used as a library, and that is the more interesting integration path for a Go team. Chaos can be used for subdomain enumeration by instantiating the Options struct and populating it with the same options that would be specified via the CLI. The documented example imports the runner from the internal directory and the chaos package from the public one:

package main

import (
	"os"
	"github.com/projectdiscovery/chaos-client/internal/runner"
	"github.com/projectdiscovery/chaos-client/pkg/chaos"
)

The runner options carry the domain, the API key read from the environment, and an OnResult callback that receives each result as an interface and type-asserts it to a chaos.Result, appending it to a slice. The runner then calls the enumeration function. Two things about this example deserve a second look. The results slice is captured by the callback closure and populated during the run, which is the shape you want if you intend to post-process the results in the same process rather than streaming them. And the key comes from the environment inside the program, matching the CLI's environment variable convention, so the same deployment works either way. The catch is visible in the import path. The runner lives under internal, which in Go means it is not importable from another module, so the example is illustrative of how the pieces fit together rather than something you can copy into your own repository without copying the runner too. The public chaos package is the part designed to be imported.

A Go module with ProjectDiscovery's shared dependencies

The dependency list tells you the tool is built on ProjectDiscovery's own shared libraries, and that is what gives it a consistent behaviour. The direct requirements are json-iterator for JSON handling, pkg/errors, and three ProjectDiscovery packages: goflags for the command line flag handling, gologger for logging, and retryablehttp-go for HTTP requests with retries. The retry client matters more than it sounds, because a client that talks to a rate-limited API needs to back off correctly rather than hammering a server that has already told you to slow down. The indirect list is long, as it is for any tool in this family, and includes a mixture of HTTP, parsing, terminal rendering and certificate handling libraries. The module requires Go 1.21, and the release build uses goreleaser with a Dockerfile in the repository, which builds the binary in a golang alpine stage and copies it into a slim alpine image with the bind-tools and ca-certificates packages added, since the tool resolves names. The repository also has a Chinese-language readme, which is a small thing that tells you something about who the audience is.

Maintenance state, and what a slow release cadence means here

The release history is the part to note. The tagged releases are v0.5.2 from 2024-04-22, v0.5.1 from 2023-03-20 and v0.5.0 from 2023-03-07, and the last push was on 2026-10-08, with the default branch being main. So the source is being worked on, but the most recent tag is more than two years old, and there is a gap of about a year between the two most recent tags before that. The practical consequence is that if you install with the at-latest suffix, you get whatever the tagged release is, not the current state of main. That is the safer choice for a tool that talks to a hosted API, because the API contract is what matters and the client code around it changes rarely, but it also means you do not get fixes that exist only on main. The repository publishes no GitHub releases beyond those tags, and the licence is MIT with the terms in a LICENSE.md file. The project also has an integration_tests directory, which is a good sign for a client whose correctness depends on the remote behaviour it wraps.

Editorial conclusion

chaos-client is a good fit for a security engineer who wants a passive subdomain source that is cheap to query and does not touch the target, and for a Go team that wants to embed the Chaos dataset into an existing enumeration pipeline rather than shell out to a binary. It is the wrong tool if you need to discover hosts in a way the target cannot see, since a dataset is limited to what has already been observed, and it is the wrong tool if you need a search that is not a domain, because the API only supports a domain name as the query. It is also the wrong tool if the rate limit is a problem for you, since the API is limited to 60 requests per minute per IP, which is tight for a large concurrent scan. Before adopting it, get a ProjectDiscovery cloud key, decide whether you want the CLI or the library interface, and check the release state, since the latest tagged release is v0.5.2 from 2024-04-22 while the last push was on 2026-10-08. The project is MIT licensed.

Frequently asked questions

Official sources

1. License: MIT
2. projectdiscovery/chaos-client on GitHub
3. Project website
4. README
5. Releases