syzbot-client

syzbot-client is an unofficial Python client for querying, parsing, and analyzing bug reports from the syzbot dashboard. It uses the versioned syzbot public JSON API and provides typed Python models for bug listings and details.

Use it to:

• query open, fixed, and invalid bugs from public syzbot targets;
• check whether a kernel crash title matches a known syzbot report;
• retrieve bug details, crash reports, kernel configs, and reproducers; and
• build and cache multi-target snapshots for repeated analysis.

The client discovers live dashboard targets, records partial snapshot failures, and applies conservative HTTP throttling and retries. It also ships inline type information through py.typed.

This project is not affiliated with or endorsed by the syzkaller or syzbot maintainers.

Installation

Python 3.10 or newer is required.

pip install syzbot-client

Quick start

Check whether a crash is already known, then retrieve the complete record only for the selected match:

from syzbot_client import BugGroup, SyzbotClient, SyzbotIndex

with SyzbotClient() as client:
    bugs = client.fetch_group("upstream", BugGroup.OPEN)
    matches = SyzbotIndex(bugs).match(
        "possible deadlock in example_func"
    )

    if matches:
        summary = matches[0].bug
        bug = client.fetch_bug(summary.link)
        print(matches[0].kind.value, bug.title)

Other common workflows include discovering targets with client.fetch_targets(), aggregating targets with client.fetch_snapshot(), retrieving linked artifacts with client.fetch_text(), and persisting results with save_snapshot() and load_snapshot(). See the usage guide for complete, runnable examples and error-handling guidance.

Agent skill

The repository includes a ready-to-use Agent Skills-compatible package that teaches coding agents how to query syzbot data, match crash titles, fetch reproducers, and reuse cached snapshots with this library.

Copy skills/syzbot-client/ from a source checkout into the skills directory recognized by your agent. Compatible agents can then invoke $syzbot-client; the Python package and the skill can also be used independently.

Development and contributing

Create a project-local environment and install the development dependencies:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install --editable '.[dev]'

Then run the standard checks:

python -m pytest
python -m ruff check src tests
python -m mypy src

Windows setup, coding conventions, test requirements, artifact validation, and the maintainer-only release workflow are documented in the contribution guide.

Community use cases

• SyzGPT: result_parser.py (integration commit) scans syzkaller crash directories and uses syzbot-client for live target discovery, source-aware snapshot caching, and exact or similar title matching. It turns the resulting evidence into conservative existence results (Yes, Maybe, No, or unknown), demonstrating how the library can support fuzzing-crash triage.

Using syzbot-client in a research project, fuzzing workflow, CI pipeline, or open-source tool? Share it by opening a pull request that adds a short entry to this section, or create an issue with the project link and a brief introduction for the maintainer to add.

Security

The client sends only HTTP GET requests and rejects cross-origin links returned by the dashboard. Do not load snapshots from untrusted sources without reviewing them. Report suspected vulnerabilities through the repository's private security reporting channel rather than a public issue.

License

Licensed under the Apache License 2.0.