# Firefox-Reverse is patches and scripts over an upstream tree, with 68 agent tools reading Gecko internals

> A Firefox build that puts a reverse engineering agent in the sidebar and manages isolated fingerprint environments, each its own process and Marionette port. The observation points sit in the C++ engine rather than in page script, and the whole project ships as patches plus build scripts.

**WhiteNightShadow/firefox-reverse** — 🦊 内置 AI 逆向 Agent 的 Firefox — 通用 JS/JSVMP/WASM/签名逆向工作站，SpiderMonkey 引擎层非侵入 trace，把加密参数从黑盒还原成不依赖浏览器的纯算法

- Repository: https://github.com/WhiteNightShadow/firefox-reverse
- Stars: 872 · Forks: 183
- Language: JavaScript
- License: not declared
- Published: 2026-09-17 · Updated: 2026-09-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/whitenightshadow-firefox-reverse

## The repository holds patches and scripts, not a browser

Look at the top level and there is no browser here. What is there is .github/, CHANGELOG.md, a Makefile, additions/, configs/, docs/, logo.png, patches/, scripts/, settings/, tests/ and tools/. The browser arrives at build time.

The Makefile is six targets and one shell declaration. bootstrap runs ./scripts/bootstrap.sh, whose stated job is to pull the upstream mozilla-firefox/firefox source into a directory named upstream by default. patch runs ./scripts/apply-patches.sh to apply everything under patches/. build runs ./scripts/build.sh, and package runs ./scripts/package.sh, which depends on a separate firefox-reverse-build/ repository. clean removes the build directory and every obj-* directory under upstream. reset goes into upstream/ and runs git reset --hard followed by git clean -fdx, which is the target that undoes a patch set.

So the project is a patch set and a driver around it. Every binary it ships is compiled from upstream Firefox plus whatever is in patches/, and the three content directories that make it its own thing are additions/, settings/ and tools/, which is a smaller surface than a fork of Gecko would normally mean.

The last commit is dated 2026-09-17, the same day as release v0.25.0, and the two releases before it are v0.24.1 on 2026-09-07 and v0.24.0-beta.2 on 2026-09-02. The project's own documentation is written in Chinese.

## Sixty-eight tools, and an engine that survives closing the sidebar

The agent in the sidebar registers exactly 68 tools, and the categories named for them are page actions, network capture, code search, cookies, WebAPI traces, JSVMP, WASM, file reads and writes, skills, extensions, environment management, and Node and Python verification of a reconstructed request.

The architectural claim is about where the observation happens. Four observation tools go into the SpiderMonkey and Gecko C++ core: tracing the signer's inputs, an instruction by instruction trace for JSVMP, the WASM import boundary, and a branch-level diff between what the browser really does and what the Node reconstruction does. The stated reason is that these points do not depend on monkey patching inside the page, so page script has a hard time interfering with them through ordinary reflection.

That is the whole difference the project claims over AI plus ordinary browser automation, and it is a placement claim rather than a capability claim. A hook installed by page script can be replaced by page script; an observation point in the engine cannot be reached the same way.

The runtime has its own resilience story. The conversation engine runs in a parent-process system module, so switching tabs or collapsing the sidebar does not interrupt a running agent, and multiple windows keep separate working directories. Everything the run produces, capture scripts, traces, restored code and progress notes, lands in the directory the session was given.

## Fingerprint configuration is read at process start, so an edit is not live

One environment is one independent Firefox profile, one independent browser process, and one Marionette port. Cookies, history, local storage, cache and configuration are kept apart between them, and the sidebar can create, rename, open, close, delete and import environments, and show running state, port, profile and the current main process fingerprint.

The storage layout is explicit. Environment data lives under ~/.firefox-reverse/environments, with a manifest.json as the index. Each environment directory holds env.json, fingerprint.json, proxy.json, and profile/, traces/, control/, captures/ and logs/ subdirectories. Deleting an environment deletes its profile with it, and the project asks you to confirm you no longer need the logins and site data in it.

The timing is the part that bites. Fingerprint configuration is handed to the C++ configuration layer at process start, so changing the fingerprint of a running environment requires closing and reopening that environment, and changing the main process fingerprint requires exiting and relaunching the whole browser. The sidebar will show the new values while the running process still holds the old ones.

Two environment capabilities are also exposed outside the sidebar, as built-in env_* tools, and through a separate MCP surface where frx_env_* tools query, create, import and start a named environment.

## Chrome-like fingerprints are deliberately no longer generated

This is the sharpest design note in the project. Isolation is environment level, not tab level, and new or regenerated environments no longer produce Chrome-like fingerprints, with the stated reason being that a browser should not declare itself as something its Gecko core cannot do.

Import goes the same way. You can paste in a fingerprint.json collected from another browser, and a result that did not come from Firefox is normalised into a Firefox identity rather than copied through. Historical environments are not migrated or rewritten either, so an environment created under the old behaviour keeps whatever it has.

What the C++ layer currently covers is listed: Navigator, Screen, device pixel ratio, language and time zone, user agent and Accept-Language, and the WebGL unmasked vendor and renderer strings. New environments default to Simplified Chinese for mainland China, with language, region and time zone editable, and browser version and operating system follow the actual build.

That is a narrower capability than a general spoofing stack, and it is also a more defensible one: the fingerprint agrees with what the engine can actually deliver rather than promising a Chrome that is not there.

## Two models, two jobs, and one that never touches a tool

The agent has two working modes, chosen when a session starts and kept for that session. In the automatic mode you give it a target and it runs the whole chain, stopping only when it genuinely needs you, for a login state, a captcha, or a business decision. In the assisted mode it proposes a plan first, then stops after each stage and offers two or three directions for you to choose; the stages named are entry point location, bytecode trace, DOM and API analysis, and constructing the implementation.

The third arrangement is the interesting one, and it is a cost design. A strong model acting as director connects over MCP and supervises the agent inside the browser. That inner agent runs on a cheaper worker model in assisted mode and does all the tool work, while the director only reads stage conclusions and corrects direction, and never runs a tool itself. The project states the rationale in one line: the expensive model's judgement plus the cheap model's willingness to grind, split by token cost.

The companion piece is a separate repository, frx-director-mcp, described as ready to use once wired up.

Across sessions, confirmed facts and known pitfalls accumulate in a built-in SQLite, so a later session does not re-learn what an earlier one already established.

## An exported session carries no API key and no bindings

Sessions can be imported and exported one at a time as .frx-chat.json files, and the import path is deliberately inert. An import creates a new stationary session, does not execute anything from the history, and carries neither the model API key nor the working directory nor the environment bindings.

That last part is the safety property. A chat file can be shared or pasted into an issue, and the things that would make it dangerous on another machine, a live key, a path to someone's filesystem, a pointer to a running fingerprint environment, are exactly the things that do not travel.

Two smaller behaviours follow the same logic. Stopping an agent by hand leaves an explicit cancellation boundary, and the next message is treated as a new task unless you ask to continue the previous one, so a half-finished run does not silently resume. And model settings are saved as named configurations, so one provider channel can hold several accounts, endpoints, models and reasoning levels, and switching between them takes effect from the next turn.

Skills are found the same way, by discovery rather than configuration: a SKILL.md is looked for in the user's skills directory, in a workspace .agents/skills folder, and in a workspace .firefox-reverse/skills folder, and the agent loads the body and the referenced files when a task calls for one.

## macOS builds are unnotarised, so the first launch needs a terminal

The download table names five targets: a Windows installer or zip for x86_64, an arm64 disk image and an x86_64 disk image for macOS, and tarballs for x86_64 and ARM64 Linux. On Linux you extract and run ./firefox.

macOS has its own paragraph, and it is the most concrete piece of honesty in the project file. The application is self-signed and has not been through Apple notarisation, which costs 99 dollars a year, so a browser-downloaded copy gets the quarantine attribute and macOS reports it as damaged. The stated fix is one command:

```bash
xattr -dr com.apple.quarantine "/Applications/Firefox Reverse.app"
```

or the equivalent in System Settings under Privacy and Security, at the bottom of the list.

So the install instructions for the most privacy-conscious platform in the table are: disable the quarantine check. That is a real cost of building outside Apple's programme, and it is better that the project says so than that a first-time user discovers it alone.

The Windows row has the mirror-image note, telling you to choose more information and run anyway if SmartScreen blocks the installer.

## Conclusion

Only point this at code you own or have written permission to analyse. Reproducing a site's signed request parameters is the kind of work that needs a written scope from the site owner, and the anti-detection environments make the same point twice over: the project builds a browser whose fingerprint is internally consistent, not one built to impersonate someone else's device. Read it as engineering if you want the observation model: the interesting claim is that signer input tracing, JSVMP instruction traces and WASM import boundaries live in the engine, out of reach of page script that would otherwise patch them. Two practical warnings. Building it means fetching upstream Firefox and applying a patch set, so your build is your own maintenance burden. And fingerprint configuration is read at process start, so a change that looks applied in the sidebar can be live in nothing until the environment is reopened.

## FAQ

### What is Firefox-Reverse and what does its agent do?

It is a Firefox build with an AI reverse engineering agent in the sidebar and a manager for isolated fingerprint environments. The agent registers exactly 68 tools covering page actions, network capture, code search, cookies, WebAPI traces, JSVMP, WASM, file access, skills, extensions, environments, and Node and Python verification of a reconstructed request.

### Which AI providers can Firefox-Reverse use?

DeepSeek, Zhipu GLM, Kimi from Moonshot, MiniMax, Qwen, Claude and OpenAI, plus any custom endpoint speaking the OpenAI or Anthropic protocol by supplying a baseUrl, a token and a model name. Keys are kept locally and calls go directly to the chosen service.

### How does the MCP director mode split work in Firefox-Reverse?

A strong model acts as director over MCP, reads stage conclusions and corrects direction without running tools itself, while a cheaper worker model runs inside the browser in assisted mode and does the tool work. The split is a token cost decision, and the director side ships as a separate repository, frx-director-mcp.

### How does Firefox-Reverse isolate fingerprint environments?

Each environment is an independent Firefox profile, process and Marionette port with its own cookies, history, local storage, cache and configuration. Data lives under ~/.firefox-reverse/environments with a manifest.json index, and fingerprint changes only take full effect after the environment is closed and reopened.

### How do I build Firefox-Reverse from source?

The Makefile's bootstrap target runs ./scripts/bootstrap.sh to pull the upstream mozilla-firefox/firefox source, patch applies everything under patches/, build runs ./scripts/build.sh, and reset restores upstream/ with git reset --hard followed by git clean -fdx.

## Sources

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

---

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