Metadata-Version: 2.4
Name: ctfbridge
Version: 0.2.0
Summary: A Python library for interacting with multiple CTF platforms.
Author-email: bjornmorten <bjornmdev@proton.me>
License: MIT
Project-URL: Documentation, https://ctfbridge.readthedocs.io
Project-URL: Repository, https://github.com/bjornmorten/ctfbridge/
Project-URL: Issues, https://github.com/bjornmorten/ctfbridge/issues
Keywords: ctf
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3.0,>=2.25
Requires-Dist: beautifulsoup4<5.0,>=4.9
Requires-Dist: pydantic<3.0,>=2.0
Requires-Dist: httpx>=0.28
Provides-Extra: dev
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: types-beautifulsoup4; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Dynamic: license-file

# CTFBridge

[![PyPI](https://img.shields.io/pypi/v/ctfbridge)](https://pypi.org/project/ctfbridge/)
[![Docs](https://img.shields.io/badge/docs-readthedocs-blue.svg)](https://ctfbridge.readthedocs.io)
![License](https://img.shields.io/github/license/bjornmorten/ctfbridge)

CTFBridge is a Python library for interacting with multiple CTF platforms through a unified interface.

> [!WARNING]
> **Under active development** – expect breaking changes.

## Overview

CTFBridge provides a simple, unified API to interact with different Capture the Flag (CTF) competition platforms like CTFd and more.

It hides platform-specific quirks and gives you consistent access to challenges, submissions, and authentication across platforms.

## Features

- 🌟 Unified API across different CTF platforms
- 📄 Fetch challenges, attachments, and challenge metadata
- 🔑 Handle logins, sessions, and authentication cleanly
- ⚡ Automatic rate-limiting and retry handling
- 🧩 Easy to extend with new platform clients
- 🧪 Demo client for quick testing without external servers

## Installation

```bash
pip install ctfbridge
```

## Basic Usage

```python
import asyncio
from ctfbridge import create_client

async def main():
    # Connect and authenticate
    client = await create_client("https://demo.ctfd.io")
    await client.auth.login(username="admin", password="password")

    # Get challenges
    challenges = await client.challenges.get_all()
    for chal in challenges:
        print(f"[{chal.category}] {chal.name} ({chal.value} points)")

    # Submit flags
    await client.challenges.submit(challenge_id=1, flag="CTF{flag}")

    # View the scoreboard
    scoreboard = await client.scoreboard.get_top(5)
    for entry in scoreboard:
        print(f"[+] {entry.rank}. {entry.name} - {entry.score} points")

if __name__ == "__main__":
    asyncio.run(main())
```

## Supported Platforms

| Platform             | Status            |
| -------------------- | ----------------- |
| CTFd                 | ✅ Supported      |
| rCTF                 | ✅ Supported      |
| _More platforms_     | 🚧 In development |

## Documentation

Full documentation: [ctfbridge.readthedocs.io](https://ctfbridge.readthedocs.io/)

## Projects Using CTFBridge

These projects use `ctfbridge`:

- [`ctf-dl`](https://github.com/bjornmorten/ctf-dl) — Automates downloading all challenges from a CTF.
- [`pwnv`](https://github.com/CarixoHD/pwnv) — Manages CTFs and challenges.

## License

MIT License © 2025 bjornmorten
