Metadata-Version: 2.4
Name: syzbot-client
Version: 0.1.0
Summary: Unofficial Python client for querying, parsing, and analyzing bug reports from the syzbot public JSON API
Author: QGrain
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/QGrain/syzbot-client
Project-URL: Issues, https://github.com/QGrain/syzbot-client/issues
Project-URL: Source, https://github.com/QGrain/syzbot-client
Keywords: syzkaller,syzbot,kernel,fuzzing,security
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Operating System Kernels
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3,>=2.32.4
Provides-Extra: dev
Requires-Dist: build<2,>=1.2.2; extra == "dev"
Requires-Dist: mypy<3,>=2; extra == "dev"
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: ruff<1,>=0.16; extra == "dev"
Requires-Dist: twine<7,>=6; extra == "dev"
Requires-Dist: types-requests<3,>=2.32.4; extra == "dev"
Dynamic: license-file

# syzbot-client

`syzbot-client` is an unofficial Python client for querying, parsing, and
analyzing bug reports from the [syzbot dashboard](https://syzbot.org/). It uses
the versioned
[syzbot public JSON API](https://github.com/google/syzkaller/tree/master/dashboard/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.

```bash
pip install syzbot-client
```

## Quick start

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

```python
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](https://github.com/QGrain/syzbot-client/blob/main/docs/Usage.md)
for complete, runnable examples and error-handling guidance.

## Agent skill

The repository includes a ready-to-use
[Agent Skills-compatible package](https://github.com/QGrain/syzbot-client/tree/main/skills/syzbot-client)
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:

```bash
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:

```bash
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](https://github.com/QGrain/syzbot-client/blob/main/docs/Contribution.md).

## 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](https://github.com/QGrain/syzbot-client/blob/main/LICENSE).
