DEV Community: Rong Zhu

Cloudflare blocked urllib's default User-Agent, and it took me two months to notice.

Rong Zhu — Sun, 11 Oct 2026 05:58:50 +0000

In September a customer emailed me. They had bought a Pro licence for pyobfus, my Python obfuscator, and activation kept failing with this:

License verification failed and no valid cache available: Access denied

I first treated it as a problem with their machine. It wasn't. Online activation was failing for everyone, on every platform, on every release up to that point. The last successful online verification in our records was on 8 July. The email arrived on 12 September.

I can't tell you exactly when it started, because I have no record of when the edge started rejecting the requests. What I can tell you is why it took two months to notice, and that part is entirely on me.

What was actually happening

The licence client used urllib.request without setting a User-Agent, so every request went out with urllib's default, Python-urllib/3.x.

The licence server is a Cloudflare Worker. Cloudflare's edge was rejecting that User-Agent before the request reached the Worker, with an HTTP 403 and a plain-text body:

error code: 1010

Cloudflare documents 1010 as a block based on the browser signature. In the requests I tested, changing only the User-Agent changed the result:

User-Agent sent	Result
`Python-urllib/3.12`	403, `error code: 1010`
`python-requests/2.x`	Worker's own JSON reply
a browser string	Worker's own JSON reply
no User-Agent header at all	Worker's own JSON reply

So this was not a "block everything that isn't a browser" rule. The signature my client sent was blocked, and the others I tried were not.

Why nobody saw it

Two things on my side turned an edge block into two months of silent failure.

The error message threw away the only clue. The client expected JSON. When it got a plain-text 403 it couldn't parse the body, so it fell back to a hard-coded string: "Access denied". That reads like "your key is wrong". A customer who sees it is likely to blame themselves or give up rather than write in.

Nothing was watching. There was no probe and no alert. The only monitoring was "a customer writes in".

Once I started digging, I found older problems in the same code.

I had never checked whether paid licences had ever completed an online verification. Some had not. An empty device list doesn't prove someone never used the product, since the offline path doesn't touch the server, but it was a question I should have been asking all along.
The device fingerprint included platform.release(), so a minor OS update gave the same machine a new identity. The local cache stopped matching and re-registering used up another of the three device slots, and customers had no way to free one. It also used uuid.getnode(), which returns a random number when Python can't read a hardware address, so a new Python process could identify the same machine differently. I had also failed to follow up on an earlier report of exactly this.
A server revocation could be swallowed by the offline-cache fallback. The client treated the server's rejection as a generic failure, fell back to the cache and reported the licence as valid, with the word "revoked" still in the message.

What I changed

Send a User-Agent that says who you are. The client's User-Agent now starts with pyobfus-license/<version>. If your urllib requests pass through a content delivery network (CDN), set a User-Agent explicitly (url, payload and __version__ come from your own code, and you still send the request with urllib.request.urlopen):

import urllib.request

req = urllib.request.Request(
    url,
    data=payload,
    headers={
        "Content-Type": "application/json",
        "User-Agent": f"yourtool/{__version__}",
    },
)

Say what actually failed.
The client now treats a 403 without the Worker's JSON error as an infrastructure failure. The message says the request was blocked before it reached the licence server, that the licence may still be valid, and gives the exact offline command to use instead.

Watch the real path, with a key that doesn't exist.
A scheduled GitHub Actions workflow runs twice a day. It first calls the production endpoint through the same client function customers use, with the same headers and User-Agent, sending a well-formed licence key that was never issued. A plain-text edge block, a 404 whose body doesn't match the expected unknown-key response, or a connection error fails the run, and GitHub emails me about the failure.

This avoids changing customer records or device lists and keeps real licence keys out of CI secrets. I tested it three ways before trusting it: green against the fixed client, red when I put the old User-Agent back, red when the endpoint was unreachable.

That wasn't enough. The first version only checked the client's error message, and the client reports every 404 the same way, so a missing route or a proxy's 404 page would have passed as healthy. A reviewer caught it while I was writing this post. The probe now repeats the request and checks that the 404 body matches the expected unknown-key JSON response, and I added a fourth test: a 404 page from a different site has to turn it red. It still only covers the rejection path. It does not prove that a valid key can activate.

Decide which failures allow a cache fallback.
The old client rejected its cache when the device fingerprint changed, yet accepted it after a generic server rejection, which is exactly backwards. Now a signed cache survives a drifting device identity, and an online answer that explicitly says revoked or expired refuses the cache fallback. The device ID is now a random value generated once and kept in ~/.pyobfus/device_id, so it survives OS updates, new virtualenvs and containers rebuilt with the same home directory. On the server, a fourth device now replaces the least recently verified one instead of being refused.

Both the device ID and the local cache can be copied, and there has always been an offline registration command. The old fingerprint check caused false lockouts without reliably preventing copying. The server keeps three recent device records, which is not a hard limit on offline use, and revocation takes effect when the client receives an online rejection.

The part a release can't fix

A fix in a new version only reaches people who upgrade. Every copy already installed keeps sending Python-urllib and keeps failing, and a customer who has given up may never see the release notes.

So two things went out with the fix. The new error message names the offline path, which bypasses this network block because it never contacts the server (replace <KEY> with your licence key):

pyobfus-license register <KEY> --no-verify

And I wrote to the customers I knew were affected the day I found the cause, before the fix was released, including one who had never complained.

If you ship anything that phones home

Set an explicit User-Agent. The default one is a shared signature, and you don't control how the CDN in front of you treats it.
Never let a fallback message replace the evidence. If the response isn't in the shape you expected, say so and show the status code, without echoing keys or personal data.
Probe production with an input that has no side effects. A made-up ID that the server should reject is often enough for the rejection path. Break the probe on purpose once to see it go red, and check that the alert reaches you.
Check whether paid licences have ever completed an online verification. Support tickets won't show you everyone who gave up.

The fixes shipped in pyobfus 0.5.26 on 13 September, and online activation has worked for new purchases since. As of 11 October the monitor's only red run was a bug in the workflow itself, not an outage. This gives me a way to catch this kind of failure without waiting for a customer to report it.

I used an AI assistant to help organise this post. I checked the technical claims against the code, and the incident timeline against my own records.

I built a Python obfuscator that keeps production traces debuggable

Rong Zhu — Wed, 22 Jul 2026 02:22:06 +0000

Python obfuscation usually creates a second problem: the same renamed symbols
that slow down a casual reader also make production crashes useless to the
developer and their coding assistant.

That trade-off is why I built
pyobfus, an AST-based Python
obfuscator with a reversible debugging path. The Apache-2.0 core is public, the
commercial Pro source stays separately licensed, and both are developed in the
same public repository.

The basic workflow is deliberately ordinary:

pip install pyobfus
pyobfus --check src/ --json
pyobfus src/ -o dist/ --save-mapping mapping.json

The distributed code contains renamed symbols. The mapping file stays with the
developer. When a crash arrives:

pyobfus --unmap --trace error.log --mapping mapping.json --json

The result restores the original identifiers before the trace goes back to
Claude Code, Cursor, or a human debugger. Framework presets preserve reflective
APIs for FastAPI, Django, Flask, Pydantic, Click, and SQLAlchemy. A separate
pyobfus-mcp package exposes the risk scan, configuration, obfuscation, and
reverse-mapping workflow as machine-readable MCP tools.

What changed in 0.5.4

The latest release closes a concrete device-binding gap in the Pro pipeline.
Before 0.5.4, --bind-device protected the Selective Opacity L3 key but Runtime
String Vault keys could still be emitted as baked constants. In 0.5.4, every
vault gets its own salt and derives its key from the bound machine at runtime.
The normal syntax is:

pyobfus src/ -o dist/ --level pro --vault --bind-device

There is no pyobfus build subcommand. I am calling that out because several
older release notes used the wrong shorthand and copying it produced a path
error.

The release CI recorded 1,046 passing core tests, one skip, and 90% coverage.
Core, MCP, and end-to-end suites run separately across Python 3.9 through 3.14
on Linux, macOS, and Windows.

The threat model is intentionally limited

The community tier raises the cost of casual source inspection; it is not a
claim of irreversible protection. Pro can encrypt selected function bodies and
vaulted strings, bind decryption to a machine, seal code objects, and scrub
tracebacks. A determined attacker controlling a running process can still use
dynamic analysis or extract material from memory. The local Pro trial is also a
convenience control, not a security boundary; that limitation is documented and
pinned by tests.

If the requirement is nation-state resistance, an encrypted VM or hardware
boundary is the more honest answer. If the requirement is distributing Python
to customers while keeping routine debugging workable, this is the niche I am
trying to serve.

What I need feedback on

The next work should come from real use rather than another speculative feature.
The candidates are:

an ML/model-serving preset;
a signed build-provenance manifest;
a PyInstaller integration cookbook;
integrity verification for MCP tool descriptions.

I am especially interested in reproducible cases where a framework breaks,
where the mapping workflow is awkward, or where the documented threat model is
wrong. Issues and code are at
github.com/zhurong2020/pyobfus.

If you use pyobfus in research, the project has a version-independent Zenodo
DOI: 10.5281/zenodo.20846053.

Disclosure: I maintain pyobfus and license the optional Pro edition. Nobody
sponsored this post.

Let Claude Code Debug Your Obfuscated Python: A Guide to the pyobfus MCP Integration

Rong Zhu — Thu, 07 May 2026 14:58:30 +0000

Disclosure: I maintain pyobfus and the pyobfus-mcp server.

Why I built pyobfus

Story starts about six months back. Cardiac imaging research project. Real patent filings in flight, software-copyright applications half-submitted, the kind of work where the lawyers actually read commit messages. The team needed algorithm modules they could hand to outside collaborators as binaries, no readable source. Python, naturally. Every research project is Python now. So: an obfuscator.

PyArmor is the answer when you ask the internet. I pulled up the docs, read the feature matrix, checked the pricing page. The serious protection — bytecode-level encryption, control-flow flattening, the things that actually slow a determined reverse engineer down — sits behind the paid Pro tier. Fine, that's a normal business model. But it made me stop for a second and ask the obvious question. Was I about to pay a license fee for a tool that fits my workflow, or was I about to pay a license fee for a tool that fits somebody's workflow, just not mine?

My workflow had a specific shape. The thing writing half my code those evenings was Claude Code, vibe coding sessions where I'd describe what I needed and iterate on output. The thing I'd reach for to debug a production trace was also Claude Code. If I shipped binaries where every class name was now I0 and every method was I2, what happened the first
time something crashed in production? I'd paste the trace into Claude, and Claude would say "I have no idea what I0 or I2 refer to. Could you share the source?" The protection meant for keeping outsiders out would also lock out the assistant I was already paying for. The only people it would actually help were the attackers, who have all the time in the world to unmangle.

PyArmor was designed for a workflow where the human reads the production logs. Cython compiles to machine code, even further from anything LLM-readable. Both made sense in 2013, in 2017. Neither made sense for an evening-vibes project where the model was the one in the debug seat.

So instead of paying for a tool I'd then have to fight, I started building a smaller one. About a month of evenings vibe-coding with Claude Code itself, organized around a single trade-off: keep the obfuscator's output opaque to outsiders, keep one tiny mapping file readable to me. That's pyobfus 0.4.0, which I shipped on 2026-04-22.

The tools on PyPI were built for a different workflow

Quick history check. PyArmor: 2013. Cython: older still. Oxyry: showed up around 2017. None of them were designed for a world where the thing reading your production logs is a language model. They all assume the same thing: you write code, you obfuscate, you ship, then you read the production logs.

For about a decade that worked fine. Friction on the obfuscator side was friction for attackers (good), and you paid a small ergonomics tax to debug your own production crashes (acceptable, fair trade).

Trade went sideways the year an LLM took over the debug seat. Models can read your trace and your source code side-by-side in the same window (they're disturbingly good at it), but the names have to line up. Trace says I0, source still says UserService, the model has nothing to anchor on. (Polite stranger problem above.)

Used to be a free, invisible cost, paid by humans doing that lookup mentally. Now it's a visible cost, every crash, every customer report, every time.

So the fix can't be "obfuscate less." Obfuscate just as much. Keep one mapping file somewhere only you can reach.

What's in 0.4.0

The release is built around closing that mapping gap. There are four pieces, but really only one matters. I added the other three so that one could be used without ceremony.

Preflight check. Run pyobfus --check src/ and the tool walks your AST looking for things that obfuscation tends to break (eval, exec, dynamic getattr, framework reflection, __all__ exports, __name__ string compares). With --json you get a structured report with an ai_hint field at the bottom that just spells out the next command in plain English. So if it spots FastAPI in your project and finds two high-severity issues, the hint reads "Start with: pyobfus src/ -o dist/ --preset fastapi --dry-run". That hint is the small trick that makes the rest agent-friendly. An MCP-enabled IDE can read the JSON, find the suggested command, and chain it without anyone in the loop typing anything.

Zero-config init. pyobfus --init src/ looks at your imports, decides whether you're on FastAPI / Django / Flask / Pydantic / Click / SQLAlchemy, and drops a pyobfus.yaml next to your code with the matching preset. The YAML has inline comments so when an LLM later reads it back, it has context for why each setting is there.

Save-mapping and unmap. This is the one I wrote the whole release for. When you obfuscate, you pass --save-mapping mapping.json. The dist/ you ship goes to customers. The mapping.json goes wherever you keep secrets (password manager, encrypted vault, private S3, anywhere that isn't inside the artifact and isn't in git). Then a few weeks later when a production trace lands in your inbox, you run:

pyobfus --unmap --trace error.log --mapping mapping.json

and what comes back is that same trace with every identifier restored to what it was before obfuscation. You paste that into Claude Code (or Cursor, or Windsurf) and the AI reads it as if the code had never been obfuscated. The customer's copy is still mangled. Yours isn't.

MCP server. pyobfus-mcp wraps all of the above as a Model Context Protocol server. Once it's installed and your IDE is pointed at it, the assistant can call any of the obfuscation tools from inside a chat turn, without you dropping out to a shell. The five exposed tools are check_obfuscation_risks, generate_pyobfus_config, unmap_stack_trace, list_presets, and explain_preset, and they all return the same {status, payload, ai_hint} JSON envelope.

60-second setup

pip install pyobfus pyobfus-mcp

For Claude Desktop, add to claude_desktop_config.json (macOS path: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "pyobfus": {
      "command": "pyobfus-mcp"
    }
  }
}

Restart Claude Desktop, then try a prompt like:

"Check if the src/ folder in my project is safe to obfuscate, and if it's a FastAPI app, generate a pyobfus.yaml for me."

What happens next is that Claude calls check_obfuscation_risks(path="src/"), reads the JSON it gets back, notices suggested_preset: fastapi, then calls generate_pyobfus_config(path="src/", preset_override="fastapi") on its own and hands you the result. Zero shell commands. Cursor, Windsurf, and Zed have slightly different config files; the recipes are in the pyobfus-mcp README.

One nice side effect: the package is live in the official MCP Registry under the name io.github.zhurong2020/pyobfus-mcp, so any MCP client that queries the registry for "python obfuscator" finds it without you doing anything else.

End to end on a toy FastAPI project

Six commands, each a one-liner.

Pre-flight scan:

pyobfus --check src/ --json

The response includes frameworks: [{"name": "FastAPI"}], suggested_preset: "fastapi", and an ai_hint. Zero high-severity findings, we're clear.

Generate config:

pyobfus --init src/ --json

This writes src/pyobfus.yaml with preset: fastapi already selected, framework-aware excludes, and preserve_param_names: true (which you need for FastAPI's Depends() and Pydantic's field-name-to-JSON-key binding).

Obfuscate with a mapping file:

pyobfus src/ -o dist/ -c src/pyobfus.yaml --save-mapping mapping.json --json

The dist/ directory is what you ship. The mapping.json is what you keep. Password manager, encrypted vault, private S3, anywhere that's not in the artifact and not in git.

Weeks later, a customer crash:

File "dist/routers/users.py", line 23
AttributeError: 'I0' object has no attribute 'I2'

Reverse it:

pyobfus --unmap --trace error.log --mapping mapping.json

Output:

File "dist/routers/users.py", line 23
AttributeError: 'UserService' object has no attribute 'get_profile'

Line numbers still point at the obfuscated file (known limitation, sitting on the v0.5 list), but every identifier is the original. Paste that into Claude Code and you're effectively back to debugging your own source. The AI suggests a fix, you apply it, you ship the patch, you move on with your evening.

The customer-facing copy is still as mangled as it was the day you shipped it. They still see I0 and I2. The only thing that links the two halves of the world is mapping.json, which lives on your machine and nowhere else.

Threat model + what you actually get

I should be honest about what pyobfus is. It's name-mangling plus optional string encryption. It's not bytecode-level encryption, it's not VM-style virtualization (which is the lane PyArmor 9.2 went down in late 2025), and a sufficiently motivated reverse engineer with enough hours on their hands can take most of it apart. The community tier in particular is friction, not a wall. If you're worried about nation-state-grade adversaries, this isn't your tool, and frankly Python probably isn't your language.

What pyobfus does buy you, against the threat model most of us actually have, is roughly four things. Casual scanning of your dist/ directory for class names, API endpoints, or business-logic strings turns up mangled noise. The Pro tier's string encryption hides literal secrets from a strings-style inspection pass. Pro's control-flow flattening makes static analysis genuinely painful. And, the reason you're reading this post: AI-assisted debugging keeps working on production traces, as long as you've kept mapping.json somewhere your AI can reach but your customers can't.

The other obfuscators on PyPI mostly force you to pick between protection and debuggability. pyobfus is my attempt at a third option, where the only thing standing between the two is a single small file you control.

Try it

pip install pyobfus pyobfus-mcp
pyobfus --check your-project/ --json

Source: https://github.com/zhurong2020/pyobfus
MCP server: https://github.com/zhurong2020/pyobfus/tree/main/pyobfus_mcp
Drop-in AI integration templates (CLAUDE.md, .cursorrules, AGENTS.md, etc.): https://github.com/zhurong2020/pyobfus/tree/main/templates/ai-integration
Full JSON schemas + CLI reference for AI agents: https://github.com/zhurong2020/pyobfus/blob/main/llms-full.txt

v0.5 is in planning. The headline items are layered protection (so you can pick per-module what your AI is allowed to see), a VS Code extension, and the long-overdue dropping of Python 3.8 (EOL was 2024-10 and our CI matrix has been carrying that weight for over a year now). If there's a specific pain you'd like prioritized, GitHub issues are the place.

One last thing. If you do ship with pyobfus, please put mapping.json somewhere safe. It's a small boring JSON file, and six months from now when a customer pings you about a crash, it's the only thing standing between you and 40 minutes of doing what I did manually that first night.