Python client and command line interface for ONYPHE, the Cyber Defense Search Engine.
- Sync (
Onyphe) and async (AsyncOnyphe) clients, both fully typed. - Covers APIv2: User, Search, Export, Summary, Simple, Simple Best, the Bulk
variants, Discovery and Alert — plus a
request()escape hatch for anything ONYPHE ships next. pyonypheCLI with table / JSON / NDJSON output.- Automatic pagination, retries with backoff,
Retry-Aftersupport.
The library on its own:
uv add pyonypheThe pyonyphe command needs the cli extra, which pulls in Typer and Rich:
uv add 'pyonyphe[cli]'
uv run pyonyphe --helpSince 3.1.0 those two are no longer runtime dependencies, so importing the
client no longer constrains rich in your own resolution.
from pyonyphe import Onyphe
with Onyphe() as api: # key read from ONYPHE_API_KEY
page = api.search("category:datascan product:Nginx country:FR")
print(page.total, "results")
for hit in api.search_iter("domain:example.com", max_results=500):
print(hit["ip"], hit.get("port"))
for doc in api.export("category:vulnscan domain:example.com"):
...Async, same surface:
import asyncio
from pyonyphe import AsyncOnyphe
async def main() -> None:
async with AsyncOnyphe() as api:
page = await api.search("protocol:rdp")
async for hit in api.export("domain:example.com"):
print(hit["ip"])
asyncio.run(main())Needs uv add 'pyonyphe[cli]', or use the container image below.
export ONYPHE_API_KEY=...
pyonyphe user
pyonyphe search 'protocol:rdp country:FR' --size 20
pyonyphe search 'domain:example.com' --all --format ndjson -o results.ndjson
pyonyphe export 'category:vulnscan domain:example.com' -o export.ndjson
pyonyphe summary ip 8.8.8.8
pyonyphe simple whois 8.8.8.8 --best
pyonyphe resolve example.com
pyonyphe bulk simple datascan ips.txt -o out.ndjson
pyonyphe alert listThe API key is resolved in this order:
api_key=argument, or--api-keyon the CLI- the
ONYPHE_API_KEYenvironment variable ~/.config/pyonyphe/config.toml~/.onyphe.ini— the file used by the official ONYPHE CLI
# ~/.config/pyonyphe/config.toml
[onyphe]
api_key = "..."The CLI is published as a container image on GHCR, built for linux/amd64
and linux/arm64:
docker run --rm -e ONYPHE_API_KEY ghcr.io/onyphe/pyonyphe:latest \
search 'category:datascan product:Nginx country:FR' --size 5Tags: latest and the semver ones (3, 3.0, 3.0.0) on each release,
main and sha-<commit> on every push to the default branch.
The image runs as an unprivileged user and its working directory is /work,
so mount there to read an asset list or write an export:
docker run --rm -e ONYPHE_API_KEY -v "$PWD:/work" ghcr.io/onyphe/pyonyphe:latest \
bulk simple datascan ips.txt -o datascan.ndjsonAn optional MCP server exposes ONYPHE to an assistant:
uv add 'pyonyphe[mcp]'
ONYPHE_API_KEY=... pyonyphe-mcpFour read-only tools — search, summary, resolve, user — with clamped
page sizes and truncated fields, so a model cannot drain your credits or your
context window. See docs/mcp.md.
MIT — see LICENSE.