wulu-shumei-bypass

| English | 简体中文 |

A Python framework for interacting with Shumei (数美) CAPTCHA service — handles registration, image fetching, parameter encryption, and verification submission.

The framework itself is fully open-source. Reverse-engineered solvers for specific captcha modes are distributed as private extension modules (see Private Extensions).

Features

• 🧩 Protocol-level integration — handles captcha registration, image fetching, field encryption, and verification submission against the Shumei (数美) API
• 🔐 Correct encryption out of the box — DES-encrypted protocol fields (selectData, mouseData, duration, etc.) with the right parameter names per protocol version
• 🖱️ Realistic trajectory generation — human-like mouse movement paths for slide captchas
• 🧠 Pluggable solver architecture — register your own solver per mode with @Shumei.add_solver, or use the private extensions
• 📦 Multi-mode support — slide, auto_slide, select, icon_select, seq_select, spatial_select

Installation

uv add "wulu-shumei-bypass[all]"
# or
pip install "wulu-shumei-bypass[all]"

Optional extras

Legend: ✅ = open source · 🔒 = private extension · ❌ = not available

Quick Start

Register & verify (slide)

import asyncio

from wulu_shumei_bypass import Shumei


async def main():
    s = Shumei(
        organization='your-organization-id',
        mode='slide',
    )
    result = await s.solve()
    print(result)


asyncio.run(main())

Register manually & fetch images

import asyncio

from wulu_shumei_bypass import Shumei


async def main():
    s = Shumei(organization='your-organization-id', mode='icon_select')
    reg = await s.register()  # -> RegisterResult (rid, bg, fg, ...)
    bg = await s.fetch_img(reg['bg'])  # raw bytes of background image
    fg = await s.fetch_img(reg['fg'])  # raw bytes of foreground image


asyncio.run(main())

Low-level verify with a custom solver

import asyncio

from wulu_shumei_bypass import Shumei


@Shumei.add_solver('seq_select')
def solve_seq(bg: bytes) -> list[list[float]]:
    # return a list of [x_ratio, y_ratio] click points in click order
    ...


async def main():
    s = Shumei(organization='your-organization-id', mode='seq_select')
    reg = await s.register()
    result = await s.fverify(reg)
    print(result)  # {'code': 1100, 'riskLevel': 'PASS', ...}


asyncio.run(main())

API Overview

Shumei(**params)

Methods

• await s.register() -> RegisterResult — obtain a new captcha challenge
• await s.fetch_img(path: str) -> bytes — download a captcha image
• await s.fverify(reg: RegisterResult) -> VerifyResult — submit a solution
• await s.solve(retry: int = 3) -> VerifyResult — register → solve → verify until PASS
• @Shumei.add_solver(mode) — register a custom solver for a mode

Solver contract

Each solver receives the image bytes and returns click coordinates as ratios (0.0–1.0 relative to image dimensions), in click order:

Private Extensions

Solvers for icon_select, seq_select, and select are not bundled with this open-source package. They live in private repositories and are loaded automatically when installed:

• wulu-shumei-bypass-icon
• wulu-shumei-bypass-seq

Contact the author for access to the private extensions.

Development

uv sync --dev
uv run pytest

Disclaimer

⚠️ For educational and research purposes only. Use at your own risk.

This project is intended solely for security research, reverse-engineering education, and interoperability testing. The author is not responsible for any misuse, unauthorized access, or violation of third-party terms of service. Always ensure your use complies with applicable laws and the terms of the services you interact with.

License

MIT