puncia turns two reconnaissance APIs into one JSON-producing CLI

One client for a subdomain API and an exploit API

puncia is the official command line client for two A.R.P. Syndicate intelligence APIs. Point it at a domain, a brand or a vulnerability identifier and it returns structured JSON, with no browser involved.

The two backends cover different ground. Subdomain Center is described as covering subdomain enumeration, subdomain takeover surfacing, shadow IT discovery and brand impersonation, or lookalike domain, detection at internet scale. Exploit Observer covers exploit and vulnerability intelligence across more than 150 identifier schemes, including CVE, GHSA, EDB, MSF and ZDI as well as nation-state feeds, with enrichment for CVE and GHSA records using EPSS and VEDAS maturity scoring, and SBOM scanning on top.

That combination is what makes the tool more than a subdomain finder. A brand protection team wants the impersonation and takeover view of a domain, a vulnerability team wants a CVE looked up, and a release team wants to know whether a component in a software bill of materials has known issues. The CLI puts all three behind the same verb structure and the same output format.

The package is on PyPI as puncia, written in Python with a floor of 3.9 and classifiers listing 3.9 through 3.13, and the licence is MIT. The last push was on 2026-10-05, and the release tags move quickly: v0.40 on 2026-10-05, v0.39 on 2026-10-04 and v0.38 on 2026-09-02.

Modes, engines and what each one is for

The command structure is a mode, a query and an optional output file, and the modes map onto distinct engines behind the service.

The subdomain mode queries domains clustered by domain and uses the cuttlefish engine. The replica mode queries lookalike domains clustered by brand, using the octopus engine, and accepts a match option with prefix, exact and substring as the values. A keyword mode queries by keyword, which surfaces hosts carrying a given keyword across the internet independently of any parent domain, and the exploit mode covers vulnerability and exploit intelligence. The sbom mode takes a CycloneDX document and writes its analysis into a directory, with a progress bar showing components processed.

The listing in the documentation is a set of practical applications rather than features, and it is worth reading as an indication of intended use. It includes brand impersonation and phishing domain detection, shadow IT and external attack surface discovery, subdomain takeover reconnaissance, advanced vulnerability research, contextual enrichment of CVE and GHSA data, vulnerability detection in software bill of materials, integration with CI and CD and threat intelligence workflows, monitoring of nation-state exploit trends, keyword-based subdomain discovery, bulk threat intelligence processing, passive reconnaissance for red teams, open source intelligence collection, and compliance and risk management support for audits such as ISO 27001 and SOC 2.

One of those entries deserves emphasis. The reconnaissance described here is passive, using data sources rather than interacting with the target directly, and that is the difference between this and an active scanner.

Installing and running the first three queries

Installation is from PyPI or from source, and the quick start is short enough to run as written:

pip3 install puncia

From source the documented alternative is pip3 install ., and the packaging is a standard setuptools project with the version held dynamically and the metadata in pyproject.toml.

The first query is a subdomain footprint lookup:

puncia subdomain example.com

The second looks for lookalike and typosquat domains around a brand:

puncia replica example.com

The third asks what is known about a vulnerability by identifier:

puncia exploit CVE-2021-44228

The output of the first command is a JSON array of hostnames, and the CLI prints a banner above it identifying the version and the service it belongs to. The banner, progress bars, warnings and errors all go to stderr, so a redirect of stdout always yields clean, valid JSON, for example puncia subdomain example.com > out.json.

For SBOM work, the command takes the document and an output directory:

$ puncia sbom bom.json ./out

stdout is data, stderr is everything else

The output contract is the most useful thing about the tool for anyone scripting it, and it is stated precisely in the documentation.

Results are printed to stdout. The banner, the progress bars, warnings and errors go to stderr. That separation means a redirect of stdout always yields clean, valid JSON, and it means the decorative parts of the interface do not have to be stripped before a file is fed to another tool.

There is a fixed set of exit codes as well. Zero means success, one means a request or input error, and two means a usage error. A pipeline can therefore distinguish a malformed command from a failed lookup, which is a distinction that many command line tools blur.

The general syntax is:

puncia <mode> <query> [output] [--match M] [--domain D] [--limit N] [--offset N]
                               [--crawl] [--filter KEY=VALUE] [--format json|csv]
                               [--api-key K] [--concurrency N]
                               [--timeout S] [--retries N] [--quiet]

The output format can be selected as json or csv, there is a quiet flag for when even the progress indication is unwanted, and the request itself is tunable through concurrency, timeout and retry options. The full reference is available through puncia --help.

That combination of a stable stdout contract, a machine readable format option and meaningful exit codes is what turns a banner-carrying CLI into something that can sit inside a scheduled job without anyone reading its output.

An API key turns a 500 row sample into a full walk

The free tier and the authenticated tier behave very differently, and the difference is in the documentation rather than hidden in the client.

Storing a key is a paid operation in the tool's own terms: puncia storekey <api-key> writes the key to ~/.puncia with 0600 permissions, and the PUNCIA_API_KEY environment variable overrides it, which the documentation says is usually what you want in CI, since a secret in the environment does not sit in a file on a build agent's disk.

Without a key, the subdomain, replica and keyword queries are capped on the server side. The documentation is explicit that anonymous requests ignore the --limit and --offset options and always return a shuffled sample of up to 500 rows, and that the tool warns rather than pretending the pagination flags did something.

With a key there is no total cap, and by default those three modes walk every page and merge the results. The --offset flag changes that behaviour: passed with or without --limit it fetches exactly one raw page, which is the shape you want for a resumable or streaming walk:

      puncia subdomain bigco.com --limit 50000 --offset 0
      puncia subdomain bigco.com --limit 50000 --offset 50000

After the first call the tool prints a note to stderr saying more results are available and which offset to continue from, so a long walk can be driven from the output of the previous step.

Live crawl is opt-in, cached for six hours and reports partial results

The --crawl flag adds a live discovery pass on top of the stored results, and it is authenticated only.

The caching rule is specific. A given domain is only actually re-crawled once every six hours or so, and requests inside that window get the cached crawl result immediately. So a crawl is not a way to force a fresh scan on demand, and a script that runs every minute will mostly be reading a cached answer.

The tool reports what happened on stderr, and the possible outcomes are worth knowing because they are not all success. A fresh result announces newly discovered names, while partial means part of the crawl is still running server-side and running means the same thing in a different phase, cooldown means the six hour window has not elapsed, and disabled means the capability is not available for that request.

For a partial or running outcome the documentation advises re-running with --crawl in a minute to pick up the rest:

      puncia subdomain bigco.com --crawl

So the crawl is best understood as an asynchronous enrichment rather than a synchronous check, and a pipeline that treats a partial result as complete will get a partial answer.

Accuracy caveats, rate limits and the practical verdict

The project states its own limits, and the first one is worth repeating word for word in substance: the results can sometimes be pretty inaccurate and unreliable, and they can differ greatly from time to time because of the self-improvement capabilities of the underlying data.

That is a real constraint on how the output can be used. A typosquat hit is a lead, not a confirmed phishing domain, and a subdomain listing is a candidate set rather than an inventory. The tool is best used to generate a review queue rather than as an authoritative source.

The second constraint is rate limiting. Aggressive rate limits can be avoided with an API key, which points at a pricing page, so a heavy user is paying for throughput.

The alternative to this CLI is writing your own calls against the same two HTTP APIs, which is entirely possible and gives full control over paging, retries and output format. The reason to use the client instead is that it already encodes the awkward parts: the distinction between anonymous and authenticated pagination, the crawl cache window, the partial and running states, and the separation of data from decoration on stdout and stderr. The reason not to use it is the accuracy caveat and the fact that the data comes from a commercial service whose cost and limits are not described in the repository.

The code is MIT licensed, the repository is not archived, and the release cadence is fast, with three releases in the last five weeks of the version numbers listed here. The trade-off for the user is that the client is cheap to try and quick to update, but its output is only as dependable as the service behind it.

Editorial conclusion

puncia suits a security engineer who wants subdomain, impersonation and exploit lookups from a script or a CI job without a browser, and it does not suit a team that needs guaranteed accuracy or a large anonymous sweep, since anonymous requests are capped at a shuffled sample of 500 rows and the project itself says the results can be inaccurate. Before relying on it, run puncia storekey with an API key so pagination and live crawl work, and compare the output against your own inventory before treating a lookalike domain as a finding.

Frequently asked questions

Official sources

1. ARPSyndicate/puncia on GitHub
2. License: MIT
3. Project website
4. README
5. Releases