# projectdiscovery/vulnx: a CLI for querying vulnerability data

> vulnx is a Go command line client that queries ProjectDiscovery's vulnerability index with a filter syntax, facet aggregation and JSON output. It is a query tool for people who already know what they are looking for, not a scanner.

**projectdiscovery/vulnx** — Modern CLI for exploring vulnerability data with powerful search, filtering, and analysis capabilities.

- Repository: https://github.com/projectdiscovery/vulnx
- Stars: 2,669 · Forks: 197
- Language: Go
- License: MIT
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/projectdiscovery-vulnx

## The gap vulnx fills between a CVE feed and a spreadsheet

Anyone who tracks vulnerabilities ends up with the same problem. The raw feeds are enormous and flat. NVD gives you records, but filtering them by "remote, critical, actually exploited, published this year" means writing your own query layer or exporting to something that can hold the data. That is the job vulnx takes on. It is a client for a hosted vulnerability index, and it exposes that index through a small set of subcommands: search, id, filters, analyze, auth, version, update and healthcheck. The README describes it as a "Modern CLI for exploring vulnerability data with powerful search, filtering, and analysis capabilities", and the command surface backs that up. The audience is narrow and specific: security engineers, detection engineers and vulnerability management people who are comfortable in a terminal and who want the answer as text or JSON rather than as a dashboard. If you want a web UI or a scanner that probes your own hosts, this is the wrong shape of tool.

## How the filter syntax and the hosted index fit together

vulnx is a thin client. The go.mod lists retryablehttp-go for HTTP, cobra for the command tree, gologger for output and go-pretty for tables, which is what you would expect from a CLI whose real work happens on a server. Queries are written in a small expression language with && and ||, field:value pairs, comparison operators such as > and >=, and quoted strings. The README gives examples like severity:critical && is_remote:true, apache || nginx, and cvss_score:>8.0 && cve_created_at:2024. Fields are not something you guess. The filters command enumerates them, and the README shows the shape of one entry: severity is a string field, sortable, facetable, with a keyword-lower analyzer and enum values critical, high, medium, low, info and unknown. The README states the total is 69 filters. Two details in that output matter more than the rest. Facet Possible tells you whether the field can drive an aggregation, and Search Analyzer tells you how the string is tokenised, which is why a keyword-lower field will not behave like an analysed full-text field. The analyze subcommand aggregates over those facetable fields, so analyze --fields severity and analyze --fields affected_products.vendor return counts rather than records. The --term-facets and --range-facets flags let a search carry its own aggregation, and --range-facets numeric:cvss_score:high:8:10 shows the numeric form with a named bucket and bounds.

## Installing vulnx and running a first search

The README's quick start installs from source with the Go toolchain, and the module path carries the v2 major version suffix, so the command includes /v2/ and the @latest suffix.

```bash
go install github.com/projectdiscovery/vulnx/v2/cmd/vulnx@latest
```

If that succeeds, the binary lands in your Go bin directory. The README then suggests two orientation commands. The first lists every searchable field, and the second runs a query without any credentials, subject to rate limits.

```bash
vulnx filters
vulnx search apache
```

The filters output is the one to read before writing anything complex, because it tells you which fields exist, their types and their enum values. A first useful query combines a severity with an exploitation signal, which is the pattern the README repeats across its examples.

```bash
vulnx search "severity:critical && is_remote:true && is_kev:true"
```

For a single record, the id subcommand takes a CVE identifier directly, and --json switches the output to something a script can parse.

```bash
vulnx id CVE-2021-44228 --json
```

The README recommends registering for a free key at cloud.projectdiscovery.io through vulnx auth, and states that this removes the rate limits and speeds up id lookups. There is also a Dockerfile in the repository root that copies a prebuilt vulnx binary onto alpine:3.18.2 and sets it as the entrypoint, so container use assumes you built the binary first rather than pulling an image.

## The constraints the README is honest about

The dependency on a remote index is the first limitation and the largest. Unauthenticated searches work, but the README says they are subject to rate limits, and it does not document what those limits are, how they are measured, or how the client behaves when it hits one. That is a real gap if you are planning to loop over a list of vendors or run a query on a schedule. The second constraint is that the field vocabulary is owned by the server. The filters command reports 69 fields today, but the README does not describe a versioning or deprecation policy for them, so a query that works now is not guaranteed to keep working across releases. Third, the repository is a client and nothing else. There is no local cache, no offline mode and no bundled dataset, so healthcheck exists precisely because connectivity is a precondition for every meaningful command. Fourth, the output flags are documented but their composition is not: the README shows --json, --output results.json, --silent, --fields and --detailed as separate examples and does not say what happens when you combine them. Finally, this is a lookup tool. It will tell you that a CVE exists and carries a Nuclei template; it will not tell you whether the vulnerable software is running on your network.

## Where vulnx sits next to cvemap and the rest of the ProjectDiscovery set

The closest thing to an alternative in the same family is cvemap, which appears in the related searches alongside vulnx. Both are CLIs over ProjectDiscovery's vulnerability data and both use a filter expression syntax, so the difference is not the data source. It is the command model. vulnx splits the work into verbs: search for queries, id for a single record, analyze for aggregation, filters for schema discovery. That separation is what makes pipelines readable, because analyze --fields severity is a different command from a search that happens to print counts, and --term-facets and --range-facets are opt-in rather than default. A team already running cvemap in scripts should treat vulnx as a different interface over similar data rather than as a drop-in replacement, and check whether the field names their queries use appear in vulnx filters before switching anything. Outside that family, the alternative is not another CLI at all. It is pulling a feed such as the NVD JSON data and querying it locally, which trades freshness and the derived fields for offline operation and full control over the schema. vulnx's derived signals, such as is_kev, is_poc, is_template and age_in_days, are the reason to prefer the hosted index; if you do not need them, a local dataset removes the network dependency entirely.

## Building from source, licensing and what upgrades cost

The repository ships a Makefile with the targets you would expect: build, test, lint, vet, fmt, tidy, integration and a pre-push target that chains formatting, tidying, vetting, linting, testing and building. The build target reads the version string out of cmd/vulnx/clis/version.go and injects it with -X github.com/projectdiscovery/vulnx/v2/cmd/vulnx/clis.Version, and the comment above VERSION shows it can be overridden, for example with make build VERSION=v2.0.3. Static linking is applied on non-darwin platforms. The go.mod declares go 1.25.5, so building from source requires a toolchain at least that new, and anyone on an older Go release should use a released binary instead. Upgrades are handled two ways: vulnx update updates the binary, and vulnx version reports the current version and checks for updates. The release history shows v2.0.0 in March 2026, v2.0.1 later that month and v2.0.2 in July 2026, and the last push to the repository was on 2026-09-21. The licence is MIT, which is permissive and imposes no copyleft obligation on your own code, but note that the licence covers the client. The index it queries is a separate hosted service with its own terms, and nothing in the repository grants you rights to that data. This is not legal advice; read the service terms if you plan to redistribute results.

## Conclusion

Adopt vulnx if you already know the shape of the question you are asking: a severity band, a vendor, a KEV flag, a date window, and you want the answer as JSON in a shell pipeline. Do not adopt it as a scanner, and do not expect it to work offline, because every command except the local help and version output talks to ProjectDiscovery Cloud. Before rolling it into anything automated, run vulnx filters and confirm the fields your query depends on are still listed, then check whether your query still works without a key or whether the rate limits push you into vulnx auth.

## FAQ

### How do I install vulnx?

The README's quick start uses the Go toolchain: go install github.com/projectdiscovery/vulnx/v2/cmd/vulnx@latest. The module path includes the v2 major version suffix, and go.mod declares go 1.25.5, so the installed toolchain needs to be at least that version. The release history also lists tagged releases for anyone who prefers a prebuilt binary.

### Does vulnx need an API key?

No. The README states that basic searches work without a key but are subject to rate limits. Running vulnx auth registers for a free key at cloud.projectdiscovery.io, and the README says this removes the rate limits and makes id lookups faster.

### How do I find out which fields vulnx can search on?

Run vulnx filters. The README states it lists every searchable field with its data type, description, whether it supports sorting and faceting, its enum values and its search analyzer type, and reports a total of 69 filters. The --json flag returns the same information in machine-readable form.

### Can vulnx scan my hosts for vulnerabilities?

No. The README describes vulnx as a CLI for exploring vulnerability data through search, filtering and analysis. It queries a hosted index and returns records; it does not probe systems. The is_template field tells you a Nuclei template exists for a CVE, which is information about the CVE rather than a scan of your infrastructure.

## Sources

- [Issues](https://github.com/projectdiscovery/vulnx/issues)
- [License: MIT](https://github.com/projectdiscovery/vulnx/blob/main/LICENSE)
- [projectdiscovery/vulnx on GitHub](https://github.com/projectdiscovery/vulnx)
- [README](https://github.com/projectdiscovery/vulnx/blob/main/README.md)
- [Releases](https://github.com/projectdiscovery/vulnx/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/projectdiscovery-vulnx