Metadata-Version: 2.5
Name: rootme-sdk
Version: 0.5.0
Summary: Unofficial typed Python SDK for Root-Me accounts and challenges
Project-URL: Repository, https://github.com/Thomas97460/rootme-sdk
Project-URL: Documentation, https://github.com/Thomas97460/rootme-sdk/blob/main/API.md
Project-URL: Issues, https://github.com/Thomas97460/rootme-sdk/issues
Project-URL: Changelog, https://github.com/Thomas97460/rootme-sdk/releases
Author: Thomas Collet
License-Expression: MIT
License-File: LICENSE
Keywords: challenges,ctf,root-me,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: beautifulsoup4<5,>=4.13
Requires-Dist: httpx<1,>=0.28
Requires-Dist: playwright<2,>=1.55
Provides-Extra: browser
Description-Content-Type: text/markdown

# rootme-sdk

An unofficial, typed Python SDK for [Root-Me](https://www.root-me.org/): automated login, session reuse, profile and challenge exploration, and answer submission.

<p align="center">
  <a href="https://github.com/Thomas97460/rootme-sdk/actions/workflows/ci.yml">
    <img src="https://github.com/Thomas97460/rootme-sdk/actions/workflows/ci.yml/badge.svg" alt="CI">
  </a>
  <a href="https://pypi.org/project/rootme-sdk/">
    <img src="https://img.shields.io/pypi/v/rootme-sdk?style=flat-square&color=00d7d7&label=pypi" alt="pypi">
  </a>
  <a href="https://github.com/Thomas97460/rootme-sdk/releases/latest">
    <img src="https://img.shields.io/github/v/release/Thomas97460/rootme-sdk?style=flat-square&color=00d7d7&label=latest" alt="latest">
  </a>
  <a href="https://github.com/Thomas97460/rootme-sdk/actions/workflows/ci.yml">
    <img src="https://img.shields.io/badge/coverage-100%25-00d7d7?style=flat-square" alt="coverage">
  </a>
  <a href="https://github.com/Thomas97460/rootme-sdk/actions/workflows/ci.yml">
    <img src="https://img.shields.io/badge/types-mypy%20strict-00d7d7?style=flat-square" alt="mypy">
  </a>
  <a href="https://www.python.org/">
    <img src="https://img.shields.io/badge/python-3.13%2B-00d7d7?style=flat-square" alt="python">
  </a>
  <a href="https://github.com/Thomas97460/rootme-sdk/blob/main/LICENSE">
    <img src="https://img.shields.io/badge/license-MIT-00d7d7?style=flat-square" alt="license">
  </a>
</p>

> [!NOTE]
> This library is alpha software and is not affiliated with Root-Me. Respect Root-Me's terms of service and rate limits.

## Installation

Requires Python >= 3.13.

### With pip

```bash
# Install
pip install rootme-sdk

# Upgrade
pip install -U rootme-sdk
```

### With uv

```bash
# In a project
uv add rootme-sdk
uv lock --upgrade-package rootme-sdk

# In a virtual environment
uv pip install rootme-sdk
uv pip install -U rootme-sdk
```

Playwright is included. On first use, it automatically uses your local Chrome/Chromium or downloads a managed Chromium browser.

## Quickstart

Copy a snippet, replace the credentials and run it. Login opens a Chromium window
and fills the form automatically.

### 1. Find a challenge by its name and read its statement

```python
from rootme_sdk import RootMeClient

with RootMeClient("your-username", "your-password") as client:
    summary = next(client.search_challenges(query="ELF x86 - 0 protection"))
    challenge = client.get_challenge(summary.id)
    print(challenge.id, challenge.title)  # 41 ELF x86 - 0 protection
    print(challenge.statement)
```

### 2. Download the challenge files

```python
from rootme_sdk import RootMeClient

with RootMeClient("your-username", "your-password") as client:
    print(client.download_files(41))  # (PosixPath('ch1.zip'),)
```

### 3. Submit a flag

```python
from rootme_sdk import RootMeClient

with RootMeClient("your-username", "your-password") as client:
    result = client.submit_flag(41, "your-flag")
    print(result.status, result.message)  # SubmissionStatus.ACCEPTED ...
```

### 4. Browse challenges with filters

```python
from rootme_sdk import Category, Difficulty, RootMeClient

with RootMeClient("your-username", "your-password") as client:
    for item in client.search_challenges(
        category=Category.CRACKING, difficulty=Difficulty.EASY, limit=20
    ):
        print(f"[{item.id}] {item.title} ({item.score} pts)")
```

### 5. Reuse a session

```python
from rootme_sdk import RootMeClient, Session

with RootMeClient("your-username", "your-password") as client:
    client.session.save("session.json")

with RootMeClient(session=Session.load("session.json")) as client:
    print(client.get_challenge(41).title)
```

Credentials can also come from a JSON file `{"login": "...", "password": "..."}`:
`RootMeClient(credentials_file="credentials.json")`.

## Important Notes

- **Graphical Display**: Password login uses an isolated, headed Chromium browser to handle Root-Me's native login flow. A working graphical display is required (`DISPLAY` on Linux).
- **Security**: Never commit your passwords or `.secrets/` directory. Saved sessions contain cookies and should be restricted to your user account.
- **Documentation**:
  - [API Reference](API.md) — Exhaustive methods and types documentation.
  - [Capabilities & Limits](CAPABILITIES.md) — Observed platform behaviors and known limitations.
  - [Contributing](CONTRIBUTING.md) — Development workflow, quality gates, and testing guidelines.
  - [Security Policy](SECURITY.md) — Vulnerability reporting and security practices.

## Development

```bash
nix develop         # or install uv + task manually
uv sync --locked
git config core.hooksPath .githooks
task ci
```
