From ac6ef95e12335bdc054ccaaa96c32474cf8789ea Mon Sep 17 00:00:00 2001 From: Ysopwnable <161784452+N0zoM1z0@users.noreply.github.com> Date: Mon, 12 Oct 2026 23:36:56 +0800 Subject: [PATCH] docs: define contribution scope and simplify proposal forms Define REA contribution scope and fail closed on unresolved integration boundaries. Make proposal forms easier to complete with structured choices, explicit unknowns, and optional technical details; welcome exploratory drafts while retaining maintainer review before integration. --- .github/ISSUE_TEMPLATE/config.yml | 3 + .github/ISSUE_TEMPLATE/design_discussion.yml | 68 +++++++++++--- .github/ISSUE_TEMPLATE/feature_request.yml | 75 +++++++++++++--- .github/pull_request_template.md | 32 ++++++- AGENTS.md | 2 + CONTRIBUTING.md | 95 ++++++++++++++++++++ 6 files changed, 248 insertions(+), 27 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 02c8ed478..e45d5d566 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,5 +1,8 @@ blank_issues_enabled: false contact_links: + - name: Contribution scope and integration requirements + url: https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope + about: Check supported capabilities, excluded workflows, and the fail-closed integration rule before proposing a feature. - name: REA Documentation url: https://github.com/morluto/rea#readme about: Read the README and AGENTS.md for usage guides and configuration details. diff --git a/.github/ISSUE_TEMPLATE/design_discussion.yml b/.github/ISSUE_TEMPLATE/design_discussion.yml index 912e18c44..38d33ac82 100644 --- a/.github/ISSUE_TEMPLATE/design_discussion.yml +++ b/.github/ISSUE_TEMPLATE/design_discussion.yml @@ -1,5 +1,5 @@ name: Design discussion -description: Resolve an REA architecture, provider, or contract question before implementation +description: Discuss an REA architecture, provider, contract, or scope decision title: "[Design] " labels: - enhancement @@ -9,7 +9,12 @@ body: attributes: value: | Use this for a substantial provider, public/persisted contract, or - authority-boundary decision. Keep one decision per discussion. + authority-boundary decision. One question and a short explanation are + enough to start. Choose "Not sure yet" where needed; maintainers can help + with technical details, alternatives, and verification. + + Read the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope). + Unresolved boundaries block integration, not opening a discussion. - type: checkboxes id: before-submitting @@ -18,14 +23,16 @@ body: options: - label: I searched the open and closed issues and pull requests for a related discussion. required: true - - label: I removed credentials, tokens, private paths, and sensitive target data. + - label: I understand the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope) must be reviewed before integration; open questions are welcome here. + required: true + - label: This discussion does not include credentials, private samples, or sensitive target data. required: true - type: textarea id: decision attributes: label: Decision needed - description: State the exact question maintainers need to resolve. + description: What would you like maintainers to help decide? A short question is enough. placeholder: Should REA ... or ...? validations: required: true @@ -34,23 +41,57 @@ body: id: context-evidence attributes: label: Context and evidence - description: Explain why the decision is needed now. Separate observed behavior, derived evidence, and inference. + description: Explain the problem or motivation. If you have evidence, distinguish observed behavior from ideas or guesses. + validations: + required: true + + - type: dropdown + id: target-interaction + attributes: + label: Expected interaction with targets + description: >- + Select all known effects, including upstream tool behavior. Add "Not sure + yet" if anything is unclear. Use "No target interaction" only on its own. + These selections help discussion and do not establish scope approval. + multiple: true + options: + - Read existing files or captured data + - Launch or attach to a process + - Inject instrumentation or run scripts/code + - Change process memory or registers + - Write or change files/configuration + - Contact network services + - Recover protected code or work around protections + - No target interaction (documentation or usability only) + - Not sure yet validations: required: true - type: textarea id: boundary-invariants attributes: - label: Boundary and invariants - description: Identify the owning layer, provider/bridge boundary, artifact or evidence invariants, and any process or authorization constraints. - validations: - required: true + label: Boundary details (optional) + description: >- + If known, clarify target selection, selected effects, provider boundaries, + non-goals, or evidence invariants. Leave blank if you need help identifying + them. Do not include private samples or proof-of-authorization documents. - type: textarea id: options attributes: label: Options and tradeoffs - description: Compare a small number of viable approaches, including platform, compatibility, safety, evidence, and maintenance costs. + description: Optional approaches or tradeoffs. One idea is enough; maintainers can help compare alternatives. + + - type: dropdown + id: verification-readiness + attributes: + label: Verification available so far + description: Pick the closest match. An idea without samples or test results is welcome. + options: + - Idea only; I need help defining checks + - I can suggest a sample or manual check + - I have a prototype or observed results + - Not sure yet validations: required: true @@ -58,9 +99,10 @@ body: id: success-criteria attributes: label: Success criteria and open questions - description: State what outcome would settle the decision and list only unresolved questions that could change the choice. - validations: - required: true + description: >- + Optional expected output, sample, possible check, or unresolved question. + A complete test plan is not required to start; maintainers and implementers + will resolve material verification gaps before integration. - type: textarea id: references diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 7b0767b27..4125f3db5 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -8,9 +8,13 @@ body: - type: markdown attributes: value: | - Keep one primary capability or workflow outcome per request. For a - substantial provider, public contract, or architecture change, explain - the decision maintainers need to make before implementation. + Describe one problem and the outcome you would like. Short answers are + welcome. Choose "Not sure yet" wherever needed; you do not need code, a + finished design, or a complete test plan to propose an idea. + + Read the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope). + Maintainers can help resolve scope and technical questions. Unresolved + boundaries block integration, not opening a request for discussion. - type: checkboxes id: before-submitting @@ -19,7 +23,9 @@ body: options: - label: I searched the open and closed issues and pull requests for a related proposal. required: true - - label: I removed credentials, tokens, private paths, and sensitive target data. + - label: I understand the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope) must be reviewed before integration; open questions are welcome here. + required: true + - label: This request does not include credentials, private samples, or sensitive target data. required: true - type: dropdown @@ -36,6 +42,7 @@ body: - MCP or agent integration - Documentation - Other + - Not sure yet validations: required: true @@ -43,7 +50,7 @@ body: id: current-limitation attributes: label: Current limitation - description: What user or agent workflow is blocked, ambiguous, or unnecessarily difficult today? + description: What are you trying to understand or do, and what is difficult today? A short example is enough. validations: required: true @@ -51,23 +58,69 @@ body: id: use-cases attributes: label: Use cases - description: Give concrete applications, targets, callers, or investigation workflows. Explain why current tools are insufficient. - validations: - required: true + description: Optional additional examples of applications, targets, or callers. Leave blank if covered above. - type: textarea id: desired-outcome attributes: label: Desired outcome and success criteria - description: Describe observable behavior, inputs, outputs, evidence, and compatibility criteria that would make this useful. + description: What would a useful result look like? Describe the output or behavior you want; implementation details are optional. + placeholder: For a selected APK, show whether it is packed and include the detection evidence. + validations: + required: true + + - type: dropdown + id: target-interaction + attributes: + label: Expected interaction with targets + description: >- + Select all known effects, including upstream tool behavior. Add "Not sure + yet" if anything is unclear. Use "No target interaction" only on its own. + These selections help discussion and do not establish scope approval. + multiple: true + options: + - Read existing files or captured data + - Launch or attach to a process + - Inject instrumentation or run scripts/code + - Change process memory or registers + - Write or change files/configuration + - Contact network services + - Recover protected code or work around protections + - No target interaction (documentation or usability only) + - Not sure yet validations: required: true - type: textarea id: boundaries attributes: - label: Authority boundaries and non-goals - description: Call out process execution, target mutation, provider licensing, evidence provenance, supported platforms, and work that should remain out of scope. + label: Target and scope details (optional) + description: >- + If known, name the target/platform, clarify selected effects, or list a + non-goal or scope question. You can leave this blank; maintainers can help. + Do not include private samples or proof-of-authorization documents. + + - type: dropdown + id: verification-readiness + attributes: + label: Verification available so far + description: Pick the closest match. An idea without samples or test results is welcome. + options: + - Idea only; I need help defining checks + - I can suggest a sample or manual check + - I have a prototype or observed results + - Not sure yet + validations: + required: true + + - type: textarea + id: verification + attributes: + label: Verification details (optional) + description: >- + Share an expected output, a possible check, or existing results if you have + them. Self-owned or appropriately licensed samples can help, but are not + required to open a request. Do not attach private or sensitive data. - type: textarea id: alternatives diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index e33ce01f4..3dec52bd0 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -19,17 +19,39 @@ describe the use case and observable outcome. --> +Follow the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope). +Unresolved scope, authority, side effects, or required verification block +integration. Link the required maintainer scope decision for new providers or +capabilities involving target execution, injection, mutation, or protection +recovery; ordinary fixes within existing boundaries may state "not applicable". +Draft PRs may leave the scope decision pending and the final review checklist +unchecked. Maintainers can help resolve open questions. + ## Contract and boundary impact - + - Semantic owner and earliest changed stage: +- Contribution scope fit and linked maintainer decision: - CLI and MCP/tool-catalog contract: - Provider, bridge, target-format, or platform compatibility: - Evidence, artifact, provenance, or reconstruction contract: -- Process execution, authorization, cleanup, or containment impact: +- Target selection, authority, upstream behavior, and cleanup details (if applicable): - Generated metadata (`docs/public/product-catalog.json`), package, or installation impact (CI generates and validates ignored catalogs and `skills/`; edit authored instructions in `.agents/skills/reverse-engineer-anything/` and never commit build outputs): +Expected effects (check known effects; use documentation-only on its own). +Unchecked items do not establish absence; leave uncertainties visible. + +- [ ] Read existing files or captured data. +- [ ] Launch or attach to a process. +- [ ] Inject instrumentation or run scripts/code. +- [ ] Change process memory, registers, files, or configuration. +- [ ] Contact network services. +- [ ] Recover protected code or work around protections. +- [ ] Documentation or usability only; no target interaction. +- [ ] Not sure yet; investigation or maintainer guidance needed. + ## Evidence and regression coverage - [ ] This PR addresses a concrete problem or an agreed enhancement. +- [ ] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [ ] The PR has one focused outcome and the title follows `type(scope): outcome`. - [ ] Related issue is linked, or the reason for not linking one is stated above. - [ ] Tests cover changed observable behavior and meaningful failure paths. diff --git a/AGENTS.md b/AGENTS.md index 6ee0229f2..9fb27e765 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,6 +4,8 @@ REA is a local-only reverse-engineering tool with shared CLI/MCP workflows. Distinguish observations, derivations, inferences, and unknowns; preserve Evidence provenance and session semantics through both adapters. Provider support and setup live in [README.md](README.md#choosing-a-deep-analysis-provider) and its linked guides. +Follow the [contribution scope and fail-closed integration rule](CONTRIBUTING.md#contribution-scope). Do not integrate capabilities while material scope, authority, side-effect, or required verification questions remain unresolved. For new providers or capabilities involving target execution, injection, mutation, or protection recovery, seek the required maintainer scope decision before substantial implementation for integration. Welcome early proposals, small exploratory prototypes, and draft PRs that help resolve questions; they do not authorize integration. + Ghidra uses ephemeral databases without modifying executable bytes or controlling a GUI; Windows Ghidra P0 has no mutation authority. IDA analysis is read-only; never save or close an attached GUI database. Configuration changes must be additive and idempotent, with backups. Installers must not install or upgrade unrelated software, including Homebrew, Node.js, npm, Java, or Ghidra. Ghidra and IDA are bring-your-own. `rea setup` must show its planned changes and require approval before writing files or installing Hopper. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f7a65be58..1dc0dd420 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,6 +19,101 @@ boundaries are checked by `npm run verify:module-boundaries`, included in lint. When adding or changing an MCP tool, follow the [tool design guide](docs/tool-design.md) and preserve the canonical contracts and generated catalog. +## Contribution scope + +REA focuses on software structure, runtime behavior, and evidence through +general-purpose reverse-engineering workflows. Evaluate a proposal by its actual +capabilities, side effects, defaults, and complete workflow. A tool name or a +reference to vulnerability research, malware analysis, or CTFs does not determine +whether it belongs in REA. + +Supported contributions include format inspection, ordinary archive and standard +compression extraction, disassembly, decompilation, cross-references, general +static deobfuscation, vulnerability analysis, and evidence reporting. Static +protection detection is distinct from defeating that protection. Security fixes +and isolated regression tests remain in scope. + +Runtime investigation needs explicit boundaries. Launching or attaching to a +process, injecting instrumentation, running scripts, and changing memory or +registers require review of target selection, execution and mutation authority, +provenance, resource limits, cancellation, and cleanup. General Frida or debugger +support is not inherently read-only, and existing support does not authorize +every workflow built on it. General-purpose interfaces are not classified as +dedicated bypass workflows solely because caller-provided code could be misused; +their execution and mutation authority must still be reviewed. + +REA does not integrate or officially distribute: + +- Purpose-built workflows to defeat commercial packing or code-virtualization + protections and automatically recover protected code. +- Anti-debugging or anti-instrumentation evasion, or DRM, license, anti-cheat, or + access-control bypass workflows. +- Exploit or attack-payload automation, credential theft, covert persistence, + unauthorized access, or bulk attack workflows. + +These boundaries apply to first-party providers, adapters, plugins, bundled +scripts, defaults, examples, and documentation. Moving a capability into an +optional dependency or plugin does not exempt it. Review what the integration +exposes, including upstream defaults and raw-command or script execution paths. +Ordinary extraction and general static deobfuscation are not excluded merely +because the input is packed or obfuscated; assess added bypass or execution +behavior separately. + +This is a product and maintenance boundary, not a judgment about a contributor's +intentions or a declaration that all excluded research is unlawful. Contributors +must have the rights and authorization needed for their work. A local-only design +or an "authorized use only" disclaimer does not establish containment or settle +legal and scope questions. + +### Fail-closed integration + +If scope fit, target or authorization boundaries, side effects, or the verification +needed to establish those boundaries remain materially unresolved, **do not merge, +enable, or include the capability in official packages or distributions**. Keep +the proposal pending, narrow it, or decline it. Record unknowns explicitly; do not +turn them into "none" or assumed safety. Passing CI, completed implementation, +upstream popularity, or silence from maintainers is not scope approval. + +For a new provider or a capability involving target execution, injection, +mutation, or protection recovery, seek an explicit maintainer scope decision in +the linked issue or design discussion before substantial implementation intended +for integration. Small exploratory prototypes and draft PRs may help inform that +decision; they do not authorize integration. The decision must cover the final +proposed behavior; a scope expansion needs a new decision. Routine fixes and +documentation changes within existing boundaries do not need a separate advance +decision, but must not silently expand those boundaries. + +### Starting a proposal + +To open a feature request or design discussion, describe the problem and desired +outcome or decision. Short answers and the forms' "Not sure yet" options are +welcome. You do not need code, a complete design or test plan, legal analysis, or +private proof-of-authorization documents to start a discussion. Share what you +know and leave optional details blank when you need help. + +Form selections guide triage; they are not proof of authorization or scope +approval. Unselected effects must not be treated as established absence. +Maintainers and implementers work together to resolve the following before +integration: + +- The concrete analyst question, requested inputs and outputs, and why existing + REA operations are insufficient. +- Why the workflow fits this scope, its non-goals, and any protection recovery, + bypass, or attack automation it would expose. +- The selected targets and every execution, injection, mutation, network, or + persistence effect, including behavior inherited from upstream tools. +- How the boundaries and outcome will be verified with self-owned or appropriately + licensed samples; identify real CLI/MCP and provider coverage, cleanup and + resource checks, and remaining unknowns. Do not publish private binaries, + credentials, or sensitive target data; follow [SECURITY.md](SECURITY.md) for + private vulnerability reports. + +Mixed proposals should separate acceptable analysis capabilities from excluded +workflows so each can be decided independently. An issue may discuss unresolved +questions; opening an issue or PR does not authorize integration. This is a +maintainer integration gate, not a per-call confirmation requirement or a sandbox +guarantee. + ## Development setup Use the development toolchain pinned in `.nvmrc` and