voidaccess

voidaccess [--version] [--no-banner] command [options]

voidaccess is the Python CLI for VoidAccess, a self-hostable OSINT tool that turns a research query into collection, entity extraction, enrichment, a relationship graph, and an exportable report. The console script is `voidaccess` (`voidaccess_cli.main:run`, Typer). Python 3.10 or newer is required. The published package version is 2.1.0.A run walks a 13-stage pipeline: optional LLM query refinement, parallel collection from Tor search engines, paste sites, code forges, RSS feeds, and curated `.onion` seeds, filtering, enrichment, recursive link discovery, page fetch through Tor, persistence, entity extraction (regex, spaCy NER, optional LLM), cross-reference against stored data, graph construction, and a summary. Results are written under ~/.voidaccess/results as JSON and Markdown unless --output or --format changes that. Investigations are also stored in ~/.voidaccess/investigations.db.The same repository ships a Docker Compose stack (PostgreSQL, Tor, FastAPI, Next.js) for a browser UI. This page documents the installed CLI, not that stack.

--version

Print the version and exit. Eager; skips the rest of the CLI.

Skip the startup banner for this invocation. `VOIDACCESSNOBANNER=1` does the same for the whole session.

~/.voidaccess/config.json

Persistent CLI config: LLM provider, model, and API key; enrichment keys; Tor host and port; pacing profile; feature toggles for ScrapingAnt clearnet transports; output directory. Mode 0600 on POSIX. Created by voidaccess configure.

SQLite store for investigations, entities, and actor profiles.

Default report directory (`<slug>-<YYYYMMDD-HHMMSS>.json` and `.md`). Override with investigate --output or `output_dir` in the config.

Optional project-level secrets for a self-hosted checkout. voidaccess configure locks it to the owner when the file exists.

Pacing profile for this process: `quiet`, `normal`, or `aggressive`. investigate --pace sets it for one run and wins over the saved default.

Clearnet ScrapingAnt REST API transport and HTTP CONNECT proxy transport. Mutually exclusive; if both are on, the proxy wins. Never applied to Tor or `.onion` fetches.

Set to `1` to hide the banner on every command.

Set to `1` for the same trace events as investigate --trace.

Allow-list and disable-list for enrichment sources. A bad value aborts investigate before any network work (exit 2).

investigate QUERY

Run a new investigation. QUERY must be 3 to 500 characters after stripping whitespace. --depth is `shallow`, `normal` (default), or `deep`. --format is `json`, `md`, or `both` (default). --output overrides the results directory. --model overrides the configured LLM. --no-tor skips Tor (clearnet only). --no-llm skips query refinement, LLM filtering, and the LLM summary. --pace is `quiet`, `normal`, or `aggressive` for this run only. --use-scraping-api and --use-proxies turn on ScrapingAnt clearnet transports for this run; they never affect Tor or `.onion` traffic. --quiet prints only fatal errors. --events-jsonl PATH appends one JSON progress event per line. --trace adds per-engine and per-URL trace events to that file (same as `VOIDACCESSTRACEEVENTS=1`). SIGTERM finishes the current item, emits a cancelled event, and exits 143. Ctrl-C exits 130.

Open the Textual entity browser. TARGET is an investigation id or a `.json` export. With no target, pick from recent runs. --no-tui prints a summary table. --path FROM TO prints the shortest graph path (at most 6 hops) and does not start the TUI.

List saved investigations. -n / --limit defaults to 20. --json prints JSON.

Export an investigation id or `.json` file. --format is `stix`, `misp`, `sigma`, `yara`, `snort`, `suricata`, `package`, `csv`, `md`, or `json` (default `json`). --output is the destination file. --tlp is `white`, `green`, `amber`, or `red` (default `white`). --redact-credentials / --no-redact-credentials and --include-raw / --no-include-raw apply to IOC packages. STIX, MISP, and Sigma need a database investigation id, not a bare JSON file. An existing output path is not overwritten; a suffix is added.

Shortcut for export TARGET --format package. Builds an IOC package ZIP.

Re-enrich a stored investigation against current feeds (IP, domain, hash, email, breach, infostealer). --skip-ips, --skip-domains, --skip-hashes, --skip-emails, --skip-breach, and --skip-infostealer turn individual layers off.

Show version, config path, database path, output directory, LLM settings, Tor reachability, spaCy NER, enrichment-key counts, and clearnet routing. --engines prints search-engine scores. --cache adds enrichment-cache stats. --seeds adds the seed-pool breakdown.

List persistent actor profiles. -n / --limit defaults to 20. -s / --search is a case-insensitive partial match. --json prints JSON.

Show one actor profile (handle or UUID): aliases, infrastructure, investigation history, notes. --note TEXT appends a timestamped analyst note. --timeline prints the activity timeline. --event-types filters that timeline (`FIRSTSEEN`, `INVESTIGATION`, `NEWALIAS`, `NEWINFRASTRUCTURE`, `NOTEADDED`). --json prints JSON. --limit applies to list and timeline views.

Shortcut for actor HANDLE --timeline.

Interactive first-run wizard (LLM, optional enrichment keys, output directory). Needs a TTY. Subcommands: llm, keys, tor (--host, --port; defaults `127.0.0.1:9050`), pace (--profile `quiet`|`normal`|`aggressive`, --show), proxy (--enable / --disable, --enable-proxy / --disable-proxy, --show).

Pipeline metrics on the shipped query set, or a read-only Tor engine-health probe. metrics --llm turns LLM stages on (they are off by default). Both accept --no-tor, --pace, --out, and --queries. probe --sample N uses only the first N queries.

Grant the administrator role to a user in a self-hosted API database.

Print `voidaccess` and the package version. Same as --version.

Use only for authorized security research and threat-intelligence work. Queries, URLs, content, and extracted entities pass mandatory content-safety gates; a blocked query exits 1.Without an LLM configured, investigate exits 2 unless --no-llm is set. Ollama is the local, key-less provider. Missing enrichment keys skip those sources instead of failing the run.Tor is required for dark-web collection. --no-tor is clearnet only. Default SOCKS5 is `127.0.0.1:9050`.The first investigate may download the spaCy `encoreweb_sm` model. Optional NLP embeddings fall back to a deterministic SHA-256 encoder when PyTorch is absent.A stale SQLite schema raises a database error on every command; the project tells you to run `alembic upgrade head`. configure without a TTY exits 1 and names the non-interactive subcommands.

VoidAccess is a Python 3 project under the MIT License. The CLI is published on PyPI as voidaccess 2.1.0. It is built with Typer, Rich, and Textual, and is independent of Recorded Future, DarkOwl, and Flare.

theHarvester(1), recon-ng(1), maltego(1), amass(1), osintui(1), sherlock(1), tor(1), yara(1), snort(8), suricata(1), ollama(1), pip(1), python(1), docker-compose(1)

Source code · Documentation