Contributing to FridaBox

FridaBox welcomes focused contributions that improve correctness, compatibility, observability, documentation, or responsible research workflows.

Before opening an issue

Confirm the target and device are authorized for your testing.
Read docs/LIMITATIONS.md and docs/DETECTION_SURFACES.md.
Search existing issues for the Android version, vendor ROM, package type, and failure signature.
Remove credentials, personal data, proprietary APKs, private agents, tokens, and device identifiers from logs.

Security vulnerabilities should follow SECURITY.md, not a public issue.

Development setup

Use JDK 21, Android SDK 35, NDK 29.0.14206865, Python 3.10+, and Node.js 20+. Follow docs/BUILDING.md for Gadget verification and the Windows no-space native-build workaround.

npm ci
python tools/build_frida_agents.py
./gradlew :app:assembleDebug :Bcore:testDebugUnitTest :app:testDebugUnitTest :app:check

Pull requests

Keep changes narrow and explain the runtime boundary they affect. A useful pull request includes:

the problem and why the current behavior is incorrect;
the smallest viable implementation;
affected Android versions, ABIs, and process types;
host-side test results;
device evidence for lifecycle, native, Binder, or virtualization changes;
explicit confirmation that imported APK bytes were not modified;
documentation updates for new behavior or limitations.

Do not combine unrelated reformatting, package renames, or generated-file churn with a runtime fix.

Runtime changes

Changes around BActivityThread, NativeCore, IO redirection, Binder proxies, Gadget loading, process allocation, or package persistence require device validation. At minimum, test:

import of an original ARM64 base APK;
absence of the guest from the real PackageManager;
Computer-mode pause and attach;
Java hook execution with the guest ClassLoader;
native module enumeration;
process recycling into Clean mode;
a second instrumented launch after Clean mode.

Add exact commands and relevant log lines to a dedicated validation note. Never commit proprietary APKs or third-party scripts without redistribution rights.

Style

Preserve existing source encoding and line endings where practical.
Keep user-facing language precise; do not promise stealth or universal app compatibility.
Prefer explicit failure states over silent fallbacks.
Keep network listeners loopback-only by default.
Pin and verify externally fetched runtime artifacts.
Add tests for parsers, integrity rules, state transitions, and regressions.

By contributing, you agree that your contribution is licensed under the repository's Apache License 2.0.

Contribute engineering time instead of money

FridaBox does not request financial donations. If you already subscribe to Codex or Claude, a valuable way to support the project is to dedicate one week of your own quota to one bounded issue from ROADMAP.md, then submit a reviewed and tested pull request.

Work only through your own account; never transfer or share credentials.
Do not paste private APKs, agents, logs, keys, or user data into an AI tool.
Treat generated code as untrusted until you understand, review, and test it.
Keep the PR small enough for a human reviewer to audit.
Include exact build commands and authorized-device evidence.
Disclose meaningful AI assistance in the PR so reviewers understand the development process, not as a substitute for technical ownership.

3.6 KiB Raw Permalink Blame History