Metadata-Version: 2.4
Name: ret2shell-kit
Version: 0.1.2
Summary: Ret2Shell工具箱
Author-email: Zonglin Xiao <xiaozonglin@stu.xidian.edu.cn>
Project-URL: Homepage, https://github.com/Xiaozonglin/ret2shell-steganography
Project-URL: Bug Tracker, https://github.com/Xiaozonglin/ret2shell-steganography/issues
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pycryptodome
Requires-Dist: httpx
Dynamic: license-file

# Ret2Shell All-in-One Kit

[![PyPI version](https://badge.fury.io/py/ret2shell-kit.svg)](https://pypi.org/p/ret2shell-kit/)

回归终端 Ret2Shell 工具箱，目前包含动态 FLAG 生成校验、接口管理（计划）等功能。

[Ret2Shell](https://github.com/ret2shell/ret2shell) is a feature-riches CTF challenge platform developed by [Reverier Xu](https://github.com/Reverier-Xu) and other contributors.

This package obeys the same license of Ret2Shell, GNU GPL-3.0.

### 如何使用

```
pip install ret2shell-kit
```

leet mode
```python
from ret2shell_kit import LeetStego
# 初始化一个密钥，需要与平台上设置的相同
stego = LeetStego("your_secret_key")

# 定义 Flag 模板，获取ID（team_id优先，user_id次之）
template = "this-is-an-example"
data_id = 12345

# 生成 Flag 内容
encoded = stego.encode(template, data_id)
print(f"编码结果 {encoded}")

# 解码验证
decoded = stego.decode(template, encoded)
print(f"解码结果 {decoded}")  # 12345
```

uuid mode
```python
from ret2shell_kit import UUIDStego

# 初始化（带连字符格式）
uuid_stego = UUIDStego("your_secret_key", with_hyphen=True)

template = "this-is-an-example"
data_id = 12345

# 生成 UUID
encoded = uuid_stego.encode(template, data_id)
print(f"UUID: {encoded}")

# 解码
decoded = uuid_stego.decode(template, encoded)
print(f"解码结果: {decoded}")  # 12345
```

### API 客户端

基于平台接口获取比赛队伍排行榜，按得分降序返回。token 可选，不传则以游客身份访问。

```python
from ret2shell_kit import Ret2ShellClient

with Ret2ShellClient("https://your-platform.example/api", token="your_token") as client:
    # 1. 整场比赛排行榜（分页拉取全部队伍）
    board = client.game.get_leaderboard(game_id=1)

    # 2. 只取前 10 名
    top10 = client.game.get_leaderboard(game_id=1, top_n=10)

    # 3. 按机构 ID 过滤，只取该机构前 10 名
    by_id = client.game.get_leaderboard_by_institute_id(
        game_id=1, institute_id=5, top_n=10
    )

    # 4. 按机构名称过滤（内部先查询机构列表解析出机构 ID）
    by_name = client.game.get_leaderboard_by_institute_name(
        game_id=1, institute_name="西安电子科技大学", top_n=10
    )
```

各方法返回 `Team` 模型列表，可按得分/名称等字段访问：

```python
for team in top10:
    print(f"#{team.score:>5}  {team.name:<20} institute_id={team.institute_id}")
```

说明：`top_n=None`时返回全部队伍；页面较大时会自动分页拉取。如需排除被禁用的队伍，可传`min_state`。排行榜默认按 `score` 字段降序排列。机构名对应不上时会抛出`ValueError`。
