64 lines
3.5 KiB
Markdown
64 lines
3.5 KiB
Markdown
# AGENTS.md
|
|
|
|
## Project overview
|
|
|
|
Reverse-engineering project for the Rusty Hearts game server/client binaries
|
|
(Windows PE32+ x86-64). Analysis is performed with **Ghidra** (headless or GUI)
|
|
driven through **REA** (`reverse-engineer-anything` skill + `rea-agents` MCP
|
|
server). There is no application source code here — the binaries are the
|
|
primary evidence.
|
|
|
|
## Directory layout
|
|
|
|
| Path | Contents | Mutability |
|
|
|------|----------|------------|
|
|
| `binaries/` | Original shipped binaries: server EXEs (`GameServer_Release_USA_x64.exe`, `DungeonServer_...`, etc.), DLLs, and game data (maps, Lua scripts, tables, item/character assets) | **Read-only.** Never modify, move, or delete. Gitignored. |
|
|
| `schema/` | SQL Server database schema/log files (`.mdf` / `.ldf`) for `RustyHearts`, `RustyHearts_Account`, `RustyHearts_Auth`, `RustyHearts_Log`, `GMRustyHearts` | **Read-only.** Never modify. Gitignored. |
|
|
| `decomp/` | Raw decompilation objects exported from Ghidra/REA (pseudocode, listings, function metadata) | Derived output. Regenerable; created on demand. |
|
|
| `.agents/skills/` | Installed agent skills, notably `reverse-engineer-anything` (REA) | Agent configuration. |
|
|
|
|
## Tooling
|
|
|
|
- **Ghidra**: installed at `/opt/ghidra`; headless entrypoint
|
|
`/opt/ghidra/support/analyzeHeadless`. `GHIDRA_INSTALL_DIR=/opt/ghidra`.
|
|
- **REA MCP**: registered in `opencode.json` via `npx -y rea-agents@6.5.0 mcp`
|
|
with `GHIDRA_INSTALL_DIR` and `JAVA_HOME` set in its environment.
|
|
- **Runtime versions**: managed by `mise.toml` — Java 21, Node 26.
|
|
- **REA skill**: `.agents/skills/reverse-engineer-anything/SKILL.md`. Read the
|
|
relevant reference under `.agents/skills/reverse-engineer-anything/references/`
|
|
before non-trivial workflows (native binaries → `native-and-artifacts.md`).
|
|
|
|
## Analysis workflow
|
|
|
|
1. Route the target first: native executables/libraries go through REA
|
|
`open_binary` (never pass a Ghidra project file as the target — pass the
|
|
original binary path under `binaries/`).
|
|
2. Work summary-first: `binary_overview` / summary detail before drilling into
|
|
`analyze_function` or pseudocode. Reuse retained Evidence IDs instead of
|
|
re-running identical analysis.
|
|
3. Export raw decompilation artifacts (pseudocode, listings) into `decomp/`
|
|
using per-binary subdirectories, e.g. `decomp/GameServer_Release_USA_x64/`.
|
|
Keep filenames stable and function-address-based so results are reproducible.
|
|
4. Close the REA session (`close_binary`) when the investigation is complete.
|
|
|
|
## Evidence and claims
|
|
|
|
- Every conclusion must distinguish **observation** (from evidence),
|
|
**inference**, and **unknown**. Cite Evidence IDs or `file:line`-style
|
|
references to decomp output.
|
|
- Static analysis never establishes runtime behavior — say so explicitly.
|
|
- Do not infer behavior from filenames, strings, or binary layout alone;
|
|
corroborate with decompilation or data from `schema/`.
|
|
- Keep a finding ledger for multi-step investigations (conclusion → evidence →
|
|
remaining gaps).
|
|
|
|
## Ground rules
|
|
|
|
- Treat `binaries/` and `schema/` as immutable inputs; all outputs go to
|
|
`decomp/` or a new file, never beside the originals.
|
|
- Do not install Ghidra, Java, Node, or REA prerequisites ad hoc — they are
|
|
provisioned via `mise.toml` and `/opt/ghidra`; repair configuration instead.
|
|
- Version-pin REA at `rea-agents@6.5.0` as declared in `opencode.json`.
|
|
- When tooling is missing or an MCP call is blocked, diagnose the specific
|
|
blocker (registration vs. restart vs. provider) rather than re-running setup
|
|
wholesale — see the REA skill's connection-and-recovery reference.
|