# CipherBridge rewrites a live proxy chain around mitmdump, and TLS verification is off unless you turn it back on

> CipherBridge is a Chinese documented Python tool for authorized traffic analysis that puts a decrypt end and an encrypt end around Burp Suite so payloads can be edited as plaintext. It ships with the proxy already configured to accept invalid certificates, runs whatever is in extensions/ by dynamic import, and hands generated code to an AI agent that you are told to review yourself.

**CuriousLearnerDev/CipherBridge** — 面向APP/Web 加解密逆向分析、渗透测试人员的可视化解密框架

- Repository: https://github.com/CuriousLearnerDev/CipherBridge
- Stars: 433 · Forks: 70
- Language: Python
- License: not declared
- Published: 2026-09-18 · Updated: 2026-09-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/curiouslearnerdev-cipherbridge

## The chain runs decrypt end, then Burp, then encrypt end

The whole design is one sentence of topology: the decrypt end receives ciphertext, decrypts it and hands the result to Burp, and after Burp modifies the request the encrypt end re-encrypts and sends it on. You edit plaintext inside Burp while both ends handle the crypto, which is the answer to the situation the tool is built for, namely encrypted request bodies using AES, DES or SM4, parameters or headers signed with MD5, SHA256 or HMAC, and captures from Burp Suite that arrive as ciphertext too far gone to edit and replay.

Both ends are optional in the sense that one is enough. If only one direction of decryption debugging is needed, only the decrypt end has to be started. A button in the left panel opens a built-in proxy browser, which launches Chromium through the decrypt end port, and the AI lab's web mode attaches to the decrypt end automatically when it starts a browser, so collection and decryption share one endpoint instead of two configurations.

Two interfaces run this in parallel rather than one replacing the other. The PyQt desktop UI is started with python gui.py, and a Vue plus Electron desktop build in a directory named vue版 runs alongside it, with a local FastAPI service starting and stopping the proxy on its behalf. That second interface needs Node.js 18 or later, and the PyQt build needs PyQt6 with its WebEngine component, so the two front ends have separate dependency tails.

## HTTPS decryption needs a root certificate installed by hand on macOS and Linux

Because the proxy sits in the middle of TLS traffic, it has to impersonate the server, and the tool is explicit about the trust step. The certificate status is visible in the decrypt end area of the interface, and installing it is done through the HTTPS certificate entry in settings. Windows gets a one-click install. macOS and Linux instead open the certificate file so you can import it into the system trust store yourself, and the check after a browser restart is https://mitm.it.

The security notes state that mitmdump runs with TLS verification disabled by default, which is what makes HTTPS decryption work at all in a proxy setting, and the file is written in Chinese and scoped to local security testing and reverse engineering with a warning against use in unauthorized environments. The disclaimer is more explicit: no unauthorized attacks, no data theft, obtain the owner's permission before testing any target, and liability for unauthorized testing sits with the user.

Two further warnings in the same section matter for how you work. Anything under extensions/ is dynamically loaded and executed, so the directory is a code execution surface rather than a data folder. And a .cbproj.zip containing real keys, the file config/ai.yaml, or captured traffic should not be committed to a public repository.

## Hash and HMAC steps cannot produce a decrypt, and the interface says so

A hash is one way, so a pipeline that ends in MD5, SHA256 or HMAC has no inverse to generate. The project handles that case explicitly rather than silently emitting a broken plugin: when only hash or HMAC steps are present, the generate decrypt action raises a clear warning. A tool that emits plausible looking output in that situation would be worse than one that refuses.

The other half of the workflow addresses encrypted paths instead. When the encryption function can be hooked, the Bypass Hook rewrites the selected encryption or hash path into an identity operation, so the plaintext value travels into Burp where it can be edited, and once the chain is confirmed the generate encrypt action writes the code back into the plugin on the encrypt end. The loop is therefore identity, edit, verify, restore, which keeps the original cryptography in place except at the moment you are deliberately looking at it.

The AI lab version of that idea is narrower on purpose. The agent can be limited to specific request or response fields when it generates the hook, so it does not have to guess across a whole message, and the 5.0 notes list an AI lab separated into decryption and anti debugging halves, with the agent able to recognise a debugger statement and generate a hook for it. Against that, the response rewriting path for anti debugging is described in terms of turning a debugger check into an immediate return, and a browser extension plus a ReRes MV3 extension is listed as part of that work.

## Two loading modes decide whether mitmdump runs your plugin or the framework

How a project reaches mitmproxy is a setting, and the two modes behave differently on every code change. The default is direct plugin loading, where the generated file is passed straight to the tool:

```bash
mitmdump -s plugins/myapp/plugin.py -p 8083
```

The alternative is the framework mode, where a single main.py is loaded and the project is chosen through an environment variable, and the notes say that mode includes matching and logging hooks:

```bash
set PROFILE=myapp          # Windows
export PROFILE=myapp       # macOS / Linux
mitmdump -s main.py -p 8083
```

The Windows and POSIX spellings are given side by side because the variable has to be set differently, and getting it wrong means the framework loads without a project rather than failing loudly. In direct mode the file itself carries the logic and the setting says that editing the code takes effect after a restart, which is the trade: simpler generated output against a restart on every iteration. The example port in both snippets is 8083, while the UI reads its default port from config/settings.yaml, so a mismatch between what the interface shows and what the command line uses is the first thing to check when a project seems unreachable.

What gets generated is Python aimed at mitmdump, plus a state.json beside it holding the visual steps and parser state. That state file is saved automatically and is excluded from version control, so the configuration in profiles/ is the part you can commit and the state of a given attempt is not.

## SM2 is documented as a feature but is missing from requirements.txt

The dependency file is organised by role, which makes the gaps easy to spot. The GUI pair is PyQt6 and PyQt6-WebEngine, both pinned to the 6.6 series below 7. Configuration and projects use PyYAML. The cryptography layer is pycryptodome, with a comment stating that the Chinese national standards SM3 and SM4 are implemented as built in pure Python. HTTP work, used both for forwarding traffic to Burp and for calling AI APIs, is requests. The AI agent under vendor/agent_core speaks the Anthropic Messages API with tools and is built on httpx and pydantic. The proxy core is mitmproxy, bounded above 10 and below 12. The local API that the Vue and QWebEngine shell talks to is fastapi with uvicorn. Playwright is last and is marked optional, with a note that the line can be commented out when the browser features of the AI tab are unused, and the header of the file still tells you to run playwright install chromium for browser based collection.

The gap is SM2. The comment on the cryptography block says that selecting SM2 in the interface or in tests needs a separate install of gmssl, which does not appear anywhere in requirements.txt. So the national standard asymmetric option is a documented feature that a plain install does not satisfy, and the failure surfaces when you select it rather than at install time.

Two more optional toolchains sit outside the Python requirements. A JDK is needed only if you build the Burp extension yourself with python burp_ext/build.py, and the prebuilt JAR is deliberately not in the repository because of its size, with placement instructions in tools/burp/. Node.js 18 or later is needed only for the Vue and Electron build, which is optional in its own right. Windows, macOS and Linux are all named as supported.

## An exported project can carry your keys, and a cleaner script exists

One encryption scheme equals one project, and a project is a directory pair: a YAML file under profiles/ holding the name, role and matching rules, and a folder under plugins/ containing the generated plugin plus the auto saved state. Templates for profiles may be committed while user schemes are ignored by git, which is the line the project asks you to keep.

Export produces a single .cbproj.zip with a defined layout, meant for long running assessments on one target or for collaboration between people. It carries manifest.json with the format version and the export time, profile.yaml with the configuration, plugin.py with the plugin code, and state.json with the visual steps only if there are any. That format version field is what makes an old archive recognisable as old, since nothing in the file says when the format changed.

Because the archive contains the configuration and the plugin code, it can contain whatever secrets those files hold. The security notes say plainly not to commit a .cbproj.zip containing real keys, config/ai.yaml, or captured packet data to a public repository, and they point at an export script inside the repository that generates a clean github/ directory with keys, user projects, node_modules and jars already excluded. That script is the difference between making this project public and not, and it also explains the layout at the top level, where tools/ holds the App reverse engineering and Burp notes without the large jar and exe files.

## The tag list skips 4.x, the file is Chinese, and the license field is unresolved

Three facts about the repository itself are worth knowing before you rely on any of it. First, the documentation is in Chinese, and the code comments in requirements.txt are as well, so the operational details in this file come from a Chinese source with section headings that map onto the panels of the interface.

Second, the version numbering and the release list do not line up. The releases are 5.0, 3.5 and 3.1, and the file documents a 5.0 build dated 2026.8.22, a 4.0 build dated 2026.8.7, a 3.5 build dated 2026.7.27 and a 3.1 build dated 2026.7.24, so there is a documented 4.0 with no matching tag in the three most recent releases. The tags also drop the v prefix the other projects in this queue use. The last push was 2026-08-22, the same date as the 5.0 tag.

Third, licensing is unresolved in one direction and asserted in the other. The license field for the repository reads as unknown, while the disclaimer states that the project is released under the LICENSE file included in the repository and that users must follow the corresponding open source license when using, modifying or redistributing it. Read the file rather than rely on either statement.

Last is the one the disclaimer itself raises. Parts of the project depend on AI generated code, scripts or configuration, the AI output is stated to be for reference only, and the user is told to review its correctness, safety and legality. The disclaimer also notes third party components such as mitmproxy and Playwright, whose own licenses apply.

## Conclusion

CipherBridge is a fit for someone doing protocol debugging or vulnerability verification on a target they own or have written permission to test, and the proxy chain, the project format and the export hygiene are all documented well enough to plan around. Do not run it on a network you are not authorized to touch: the proxy accepts unverified TLS by default, the root certificate has to be trusted system wide, and anything dropped into extensions/ executes. Before a session, confirm the authorization, install the root certificate only on a throwaway profile, run make-equivalent checks offline, and read every generated plugin before loading it.

## FAQ

### What does CipherBridge need beyond Python 3.10?

PyQt6 and PyQt6-WebEngine for the desktop UI, pycryptodome for AES, DES and RSA, and mitmproxy for the proxy core. Node.js 18 or later is optional and only for the Vue and Electron build, a JDK is only for compiling the Burp extension, and SM2 support additionally needs gmssl installed by hand.

### How do I load a CipherBridge project with mitmdump from the command line?

In the default mode the generated plugin is loaded directly with mitmdump -s plugins/myapp/plugin.py -p 8083, and code changes take effect after a restart. Framework mode instead loads main.py and selects the project through the PROFILE environment variable.

### What does the Bypass Hook in CipherBridge do?

When the encryption function can be hooked, it rewrites the selected encryption or hash path into an identity operation so the plaintext enters Burp for editing, after which the generate encrypt action writes the code back into the plugin on the encrypt end.

### How is HTTPS traffic decrypted in CipherBridge?

The mitmproxy root certificate has to be trusted: check the certificate status in the decrypt end area and install it from the HTTPS certificate entry in settings, with a one click install on Windows and manual import into the system trust store on macOS and Linux, verified at https://mitm.it after a browser restart.

### What files are inside a CipherBridge .cbproj.zip export?

manifest.json with the format version and export time, profile.yaml with the project configuration, plugin.py with the plugin code, and state.json with the visual steps when there are any.

### What should not be committed from a CipherBridge working copy?

Exported .cbproj.zip packages that contain real keys, the config/ai.yaml API key file, and captured packet data should stay out of public repositories, and a clean github/ directory can be generated with the export script included in the repository.

## Sources

- [CuriousLearnerDev/CipherBridge on GitHub](https://github.com/CuriousLearnerDev/CipherBridge)
- [Issues](https://github.com/CuriousLearnerDev/CipherBridge/issues)
- [README](https://github.com/CuriousLearnerDev/CipherBridge/blob/main/README.md)
- [Releases](https://github.com/CuriousLearnerDev/CipherBridge/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/curiouslearnerdev-cipherbridge