diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 62883a5..34259c1 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -17,6 +17,20 @@ body: description: What concrete limitation or workflow gap should be addressed? validations: required: true + - type: dropdown + attributes: + label: Research area + options: + - Frida visibility reduction + - /proc and process-map consistency + - Virtual-environment fidelity + - Android or vendor compatibility + - Import, integrity, or ABI handling + - Controller and developer tooling + - Product UI and accessibility + - Documentation or validation + validations: + required: true - type: textarea attributes: label: Proposed boundary diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 45b2389..da482b1 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -20,11 +20,18 @@ Describe the problem and the narrow change that solves it. - [ ] Device validation attached when runtime behavior changed - [ ] Original guest APK remains unmodified - [ ] No credentials, private agents, proprietary APKs, or sensitive logs included +- [ ] I understand and can explain every submitted change, including AI-assisted code ## Evidence List exact commands, Android/device details, and sanitized output. +## Research assistance + +If Codex, Claude, or another assistant materially contributed, identify the +tool, the scoped task it helped with, and the manual review/device validation +you performed. Never include prompts or transcripts containing sensitive data. + ## Risks and limitations Describe compatibility impact, process-lifecycle assumptions, and remaining gaps. diff --git a/CHANGELOG.md b/CHANGELOG.md index a1fda31..b751610 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,15 @@ All notable FridaBox changes are documented here. The project follows semantic versioning for its public releases. +## [Unreleased] + +### Documentation + +- Added the public research roadmap for Frida visibility, `/proc`/maps + consistency, and higher-fidelity virtual-environment behavior. +- Added a contribution model that asks users to donate a bounded week of their + own Codex or Claude engineering time instead of money. + ## [4.0.0] - 2026-07-20 ### Added diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2ed4b2d..d0d10e8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -73,3 +73,18 @@ commit proprietary APKs or third-party scripts without redistribution rights. 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](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. diff --git a/README.md b/README.md index a59dd2a..06ba263 100644 --- a/README.md +++ b/README.md @@ -254,6 +254,34 @@ ClassLoader topology may all be observable. Read [docs/LIMITATIONS.md](docs/LIMITATIONS.md) and [docs/DETECTION_SURFACES.md](docs/DETECTION_SURFACES.md). +## Research roadmap + +The next research phase focuses on making the virtual environment more +internally consistent and reducing avoidable instrumentation fingerprints: + +- reduce unnecessary Frida-visible artifacts and default identifiers; +- research safe mediation of `/proc`, including coherent views of process maps; +- improve filesystem, package, process, Binder, identity, ClassLoader, and + service behavior so guests observe a more faithful sandbox; +- expand the Android/vendor test matrix and add regression probes for every + detection surface addressed. + +This work is tracked in [ROADMAP.md](ROADMAP.md). FridaBox will continue to +document what remains observable and will not describe best-effort hardening as +undetectability. + +### Contribute a week of engineering, not money + +FridaBox is not asking for financial donations. If the project is useful to you +and you already have access to Codex or Claude, consider dedicating one week of +your own usage quota to a scoped roadmap item: investigate it, implement the +narrowest fix, validate it on an authorized target, and open a pull request. + +Use your own account and review every generated change yourself. Never share +accounts, API keys, session tokens, private APKs, or proprietary agents. A small, +well-tested PR with reproducible device evidence is more valuable than a large +unreviewed code dump. + ## Project status FridaBox 4.0.0 is a device-validated research release. The full sample hook and diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..b1b8fe0 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,116 @@ +# FridaBox research roadmap + +FridaBox 4.0.0 proves the complete import, early instrumentation, guest +ClassLoader, native enumeration, On-device, Computer, and Clean flow on a real +ARM64 Android 16 device. The next phase is not a promise of invisibility. It is +a measured effort to remove unnecessary fingerprints and make the virtual +environment more coherent under guest observation. + +Every roadmap change must target software and devices the researcher is +authorized to assess, preserve a deterministic Clean mode, and add evidence to +the detection-surface documentation. + +## P0 — Regression laboratory + +Hardening without measurement becomes folklore. Before broad interception work, +build a repeatable probe suite that records: + +- `/proc/self/maps`, mount, status, task, fd, cmdline, and network observations; +- Java and native class/module/thread visibility; +- PackageManager, ActivityManager, user, UID, process, storage, and signature + responses; +- host/guest filesystem paths and permission behavior; +- differences between a normal installation, FridaBox Clean mode, and each + instrumented mode. + +Acceptance criteria: + +- probes run against owned sample applications; +- output is structured and diffable across Android versions/vendors; +- every future hardening PR includes a before/after result; +- the suite itself does not claim that an untested surface is protected. + +## P1 — Reduce avoidable Frida visibility + +Research and minimize identifiers that are implementation defaults rather than +requirements of the instrumentation architecture. Candidate surfaces include +module names and paths, configuration artifacts, listener behavior, thread +metadata, and other stable strings exposed to the guest. + +Guardrails: + +- preserve compatibility with the pinned official Frida engine; +- do not add app-specific bypasses; +- do not weaken loopback-only networking or artifact integrity checks; +- keep controller discovery deterministic; +- document residual native mappings, threads, sockets, and protocol surfaces. + +## P1 — `/proc` and process-map consistency + +Research a coherent mediation layer for guest reads of `/proc`, with special +attention to maps and related views. Filtering one file in isolation is usually +detectable because the same fact appears through multiple kernel and runtime +interfaces. + +The work should first map all relevant access paths—Java APIs, libc calls, +direct syscalls, file descriptors, memory APIs, and secondary proc entries—then +define which views can be made mutually consistent without destabilizing the +guest or concealing host security failures. + +Acceptance criteria: + +- behavior is specified before hooks are added; +- direct and indirect reads are tested; +- filtered output remains structurally valid; +- native crashes and anti-tamper loops have bounded failure handling; +- limitations and bypassable paths remain explicit. + +## P1 — Higher-fidelity virtual environment + +Improve consistency across the surfaces that reveal a virtualized application: + +- PackageManager and ActivityManager identity; +- UID, user, process, task, and component relationships; +- filesystem roots, storage volumes, permissions, and canonical paths; +- Binder attribution and calling identity; +- application info, signatures, installers, and source directories; +- ClassLoader, resources, providers, services, jobs, and broadcast behavior; +- WebView and isolated/external process boundaries where technically feasible. + +The goal is a sandbox whose answers agree with each other, not a collection of +hard-coded return values. Changes must be Android-version-aware and backed by +comparison tests against normal installations. + +## P2 — Compatibility expansion + +- Split APK and App Bundle import with explicit split integrity. +- Broader Android/vendor ROM device matrix. +- Multi-process and service instrumentation regression coverage. +- Better WebView renderer and isolated-process diagnostics. +- Optional architectures only after the full integrity and runtime flow can be + validated for them. + +## P2 — Research ergonomics + +- Exportable, sanitized runtime reports. +- Per-agent metadata, hashes, versions, and rollback. +- Script validation and clearer autonomous-agent diagnostics. +- Reusable probe packs for Java, native, Binder, storage, and lifecycle tests. +- Automated comparison of Computer, On-device, and Clean process snapshots. + +## How to contribute + +Choose one observable surface and open an issue before starting a large change. +Define the hypothesis, authorized test target, smallest implementation, expected +tradeoffs, and acceptance evidence. + +If you already have Codex or Claude access, consider dedicating one week of your +own quota to that bounded task instead of donating money. Use the assistant for +investigation, tests, documentation, and review—not as a source of unaudited bulk +changes. Keep credentials and private research material out of prompts, review +all output personally, and submit the result as a focused pull request following +[CONTRIBUTING.md](CONTRIBUTING.md). + +The most valuable contribution is not the largest patch. It is the smallest +change that makes one measured observation more correct without breaking the +validated FridaBox flow.