pyonyphe

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.
• pyonyphe CLI with table / JSON / NDJSON output.
• Automatic pagination, retries with backoff, Retry-After support.

Install

The library on its own:

uv add pyonyphe

The pyonyphe command needs the cli extra, which pulls in Typer and Rich:

uv add 'pyonyphe[cli]'
uv run pyonyphe --help

Since 3.1.0 those two are no longer runtime dependencies, so importing the client no longer constrains rich in your own resolution.

Library

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())

CLI

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 list

Configuration

The API key is resolved in this order:

1. api_key= argument, or --api-key on the CLI
2. the ONYPHE_API_KEY environment variable
3. ~/.config/pyonyphe/config.toml
4. ~/.onyphe.ini — the file used by the official ONYPHE CLI

# ~/.config/pyonyphe/config.toml
[onyphe]
api_key = "..."

Docker

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 5

Tags: 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.ndjson

MCP server

An optional MCP server exposes ONYPHE to an assistant:

uv add 'pyonyphe[mcp]'
ONYPHE_API_KEY=... pyonyphe-mcp

Four 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.

Documentation

• Installation
• Usage
• CLI reference
• MCP server
• API reference
• Migrating from 2.x
• Contributing

License

MIT — see LICENSE.