Reverse-Engineering Workflow

Reverse engineering in this ecosystem is evidence-driven work for authorized preservation, interoperability, compatibility, security research, and repair. It must be reproducible and must not endanger live services or unrelated users.

1. Define the question

Write one falsifiable question before opening tools. Examples:

• Which client field selects the login endpoint?
• At which protocol stage does client build X diverge from server revision Y?
• Which runtime/library behavior prevents this preserved binary from starting?
• Is a crash caused by client data, user data, configuration, or server response?

Link the question to a finding and, when it represents work, a Forgejo issue.

2. Freeze the evidence

• Assign artifact IDs to every input.
• Hash original files and store them read-only.
• Record operating system, architecture, locale, clock, tool versions, and network layout.
• Use a generated working copy for experiments.
• Capture a control run before modifying anything.

3. Prefer the least invasive technique

Recommended order:

1. Existing source, documentation, symbols, strings, version resources, config, logs.
2. Static structural comparison and format inspection.
3. Controlled runtime tracing and filesystem/process observation.
4. Isolated packet capture of traffic generated by test systems you control.
5. Debugging/instrumentation.
6. Binary patching only after the behavior and rollback path are understood.

Avoid changing several variables at once.

4. Capture experiments

Each experiment record includes:

Question:
Artifact IDs and hashes:
Environment:
Tools and versions:
Procedure:
Control result:
Changed variable:
Observed result:
Interpretation:
Confidence:
Next test:
Evidence locations:

Redact credentials, personal data, private addresses, and unrelated traffic before sharing.

5. Separate observation from interpretation

Use explicit language:

• Observed: the log contains error code X after message Y.
• Inferred: X may indicate a client/server version mismatch.
• Confirmed: changing only the client build causes the failure and restoring it removes the failure across repeated runs.

Confidence levels:

Level	Meaning
Low	Plausible interpretation with limited evidence.
Medium	Supported by repeatable evidence but alternative explanations remain.
High	Repeated controlled tests and independent evidence agree.

Negative results are valuable. Record failed approaches so future work does not repeat them.

6. Turn a finding into a repair

A repair should be the smallest auditable derived change:

• Store source patches as unified diffs or normal commits.
• Store binary patches as a patch recipe with input/output hashes, offsets/signatures, rationale, and a revert path; do not publish restricted original binaries.
• Prefer configuration generators, wrappers, compatibility shims, converters, or isolated legacy runtimes when they preserve original bytes.
• Add a regression test or smoke test that fails without the repair.
• Link repair → finding → evidence → artifact IDs → bug/issue.

7. Validate modernization

Compare the modified path with the unmodified baseline. Verify functionality, data integrity, security boundaries, restart/rollback, and reproducibility from clean inputs. A successful one-off launch is not enough.

Network research rules

• Capture only traffic from systems and accounts you are authorized to test.
• Isolate legacy clients from public networks unless a specific endpoint is required and approved.
• Never collect unrelated third-party traffic.
• Store raw captures as restricted by default; publish sanitized dissections or minimal fixtures.
• Record interface, capture filter, endpoint roles, TLS/encryption state, and tool version.

Deliverables

Every completed investigation produces at least one of:

• Confirmed finding with evidence.
• Rejected hypothesis with the experiment that rejected it.
• Minimal reproducible test case.
• Documented patch/shim and regression test.
• Newly identified missing artifact or preservation gap.

Use Template — Finding and Template — Bug.