Metadata-Version: 2.4
Name: ret2shell-kit
Version: 0.1.4
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
```

### 动态FLAG生成

Ret2Shell Kit 支持以与比赛平台相同的方式生成 FLAG，这样只需要使用平台提供的评测脚本并确保两者的配置（密钥、FLAG模板）相同即可。在生成动态 UUID、Leet FLAG 前，需要让选手输入临时用户识别码或队伍密钥来较为安全地获取选手的用户 ID 或 队伍 ID。

使用临时身份识别码获取用户 ID 的方法如下：

```python
from ret2shell_kit import Ret2ShellClient

with Ret2ShellClient("https://ctf.xidian.edu.cn/api") as client:
    player = client.account.get_user_info("AAAAAA") # 通过临时身份识别码拿到用户对象
    print(player.id) # ID，例如 114514
    print(player.account) # 用户名，例如 foo
    print(player.nickname) # 昵称，例如 林林
```

使用队伍密钥获取队伍 ID 的方法如下：

```python
from ret2shell_kit import Ret2ShellClient

with Ret2ShellClient("https://ctf.xidian.edu.cn/api") as client:
    team = client.game.find_team_by_team_code(37, "xxxxxxxxxxxx")
    print(team.id) # id
    print(team.name) # 队名
```

通过以上的方法获取到队伍 ID 或用户 ID 后就可以生成动态 FLAG 了。

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

### 比赛队伍与排行榜

基于平台接口获取比赛队伍排行榜，按得分降序返回。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` 模型列表，可按得分/名称等字段访问：

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