REWiki:Fact reference
To connect an AI agent through MCP, see REWiki:Connect.
How to write facts, symbol maps and the data the export tools turn into Ghidra/IDA scripts and C headers. The tool descriptions keep only what a call needs; this page has the details. A dry run (dry_run: true) checks a write and says what is missing, unknown or suspicious, so when in doubt, dry-run first.
A complete fact
Every field below is required except key (inside a batch, the same object goes in arguments):
{"kind": "magic", "subject": "Format:Pcapng", "key": "Section Header Block magic",
"claim": "A pcapng file starts with the Section Header Block type 0x0A0D0D0A, followed by the byte-order magic 0x1A2B3C4D.",
"scope": {"level": "format", "applies_to": "all pcapng files"},
"data": {"bytes": "0A 0D 0D 0A", "offset": "0x0", "meaning": "pcapng Section Header Block"},
"evidence": [{"type": "source", "detail": "SHB definition in the pcapng draft", "repo": "https://github.com/ietf-opsawg-wg/draft-ietf-opsawg-pcap", "commit": "<sha>", "path": "draft-ietf-opsawg-pcapng.md"}],
"confidence": "high"}
claim is one or two sentences a reader can check; scope.applies_to says which versions, builds or files it holds for; each evidence entry has a type and a detail (what it shows), and lines only when you read the exact lines.
Fields by kind
data holds the kind's fields. Fields outside these get a warning (they are kept, but exports ignore them).
| Kind | Required | At least one of | Optional | Example |
|---|---|---|---|---|
function |
name |
rva, address, signature, export |
ordinal, prototype, calling_convention, size, rva_end, signature_offset, multiple |
{"name":"Player::TakeDamage","rva":"0x141230","signature":"48 89 5C 24 ?? 57 48 83 EC 20","prototype":"void __fastcall(Player*, float)"}
|
global |
name, type |
rva, address, signature |
size, signature_offset, multiple |
{"name":"g_GameState","type":"GameState*","rva":"0x2F1A80"}
|
struct |
name, fields |
size, size_min |
size_max, alignment, abi, variant, address, endianness |
{"name":"Weapon","size":"0x88","fields":[{"offset":"0x0","size":8,"type":"void*","name":"vtable"},{"offset":"0x8","size":1,"type":"uint8_t","name":"kind","notes":"0 = rifle, 1 = shotgun"},{"offset":"0x9","size":1,"type":"uint8_t","name":"flags","bits":[{"bit":"0","name":"is_loaded"},{"bit":"4-5","name":"palette","notes":"CGB only"}]}]}
|
vtable |
class, slots |
rva, address, rtti, iid, api |
base |
{"class":"Weapon","rtti":".?AVWeapon@@","rva":"0x1D3E00","slots":[{"index":0,"name":"~Weapon"}]}
|
enum |
name, values |
underlying_type, complete |
{"name":"WeaponClass","values":{"0":"AssaultRifle","1":"Shotgun"}}
| |
typedef |
name, type |
abi |
{"name":"FT_Long","type":"int32_t","abi":"win64"}
| |
magic |
bytes, offset, meaning |
mask, relative_to, alternatives |
{"bytes":"52 41 42 00","offset":"0x0","meaning":"RAB archive header"}
| |
string |
value, meaning |
encoding, rva, address, offset, relative_to |
{"value":"EDF5_SAVE","meaning":"Save file tag","encoding":"ascii"}
| |
signature |
pattern, matches |
name, offset, multiple, target |
{"pattern":"48 8B 05 ?? ?? ?? ?? 48 85 C0","matches":"load of g_GameState"}
| |
identification |
method, indicator |
table |
{"method":"string","indicator":"CRI Middleware"}
| |
behavior |
(free claim) | trigger, effect, condition, rva, rva_end, address, signature, function, setting |
{"trigger":"the Witch is shot by another survivor","effect":"she switches target after a 5 s timer","function":"Witch::OnTakeDamage","rva":"0x2A41C0","rva_end":"0x2A4230","setting":{"name":"z_witch_retarget_time","default":"5"}}
|
Every kind also takes data.test_vectors and data.samples (below; given at the top level they are moved into data). Every fact needs evidence (one file per entry: {type: "source", repo, commit, path, lines} for code you read; runtime_test, byte_pattern, comparison… for what you checked) and a confidence. Give it a short key (the page title) when the claim is a sentence.
Scope and subjects
scope.levelis the most general level where the claim holds: technique, platform, format, library, tool, software, build. Put a finding about a bundled library on theLibrary:page, not on the game.- A topic subpage as subject (
Format:PE (Portable Executable)/Rich header) stores the fact on the subject page and lists it on the topic page. - A Format and a Library with the same name keep separate fact titles (
Fact:X (Library)/…for the second).
Addresses and builds
- An address belongs to one exact binary:
scope.level = "build"andscope.applies_to= aBuild:page or the SHA-256 of one of its files (also one registered earlier in the same batch). One address per fact; many names at once go in a symbol map. - PE:
data.rva(relative to the image base, never absolute), e.g."0x141230". - Other binaries:
data.address = {kind, value}:va(fixed-address images, PlayStation, consoles):"0x80012345"; declareimage_baseon the build when it has one.file(file offset):"0x1A2B0".segmented(16-bit/DOS):"1000:5AFA","DS:00CC","seg2:00CC".banked(cartridges):"03:8000".wasm(WebAssembly function index, imported functions counted first):"func:123".hardware(memory-mapped I/O, vectors, BIOS calls, the same in every program of a platform):"0xFF46", on thePlatform:page withscope.level = "platform".- A block of memory-mapped registers: one struct fact with
data.address{kind: "hardware", value: "<base>"}and the registers as fields at offsets from the base ({offset: "0x0", size: 2, name: "LSPC_VRAMADDR"}), on thePlatform:page; a single register is a global fact with its own address.
- Builds (
register_build): file hashes and metadata, never the file. SHA-256 is best; consoles may use the SHA-1/MD5/CRC32 that ROM and disc databases publish; without the file, size plus PE timestamp or version text is a partial identity. A library's own DLL is a build of itsLibrary:page (software"Library:Name").
Structs, typedefs and enums
- Struct fields:
{offset, size, type, name, notes?, bits?, condition?}. Types as C spells them (uint32_t,unsigned short,const char *,Foo *);uint8,u32,int16_le,uint32_be,f32are read as stdint types with the byte order noted. bits: [{bit: "0" or "4-5", name, notes?}]for flags;condition: "flags & 0x08"for a field present only when a flag is set, orcondition: "version >= 7"for one present only in some versions (each version's offset as its own field with its condition). Fields that follow a variable-length field have no fixed offset: describe them as a second struct fact whose offsets count from where that part starts, and link it in notes.- Exact size unknown:
size_minand/orsize_max. Entries after a header or a trailing name: the last field typedT[]orT[count_field](a C flexible array member;sizeis then the fixed part, or"variable"withoutsize_min/size_max). A field after a variable part can have an offset like"4+length": it is written as a comment. - Byte order:
data.endiannesson every struct with multi-byte fields:"little","big","native"(an in-memory structure of one process: C++ ABI objects, runtime and kernel structures), or"mixed: <what decides it>"("mixed: big when the BOM is FE FF, little when FF FE","mixed: follows EI_DATA"). Sweeps found it missing on a third to half of the corrected structs, often where the reader was big-endian. - Library types (
FT_Long,DWORD,j_common_ptr): onetypedeffact each ({name, type}), so headers use them instead of bytes. - Layouts that differ by ABI:
data.abi("win64","lp64","ilp32") on struct and typedef facts, one fact per ABI;export_headertakesabi. Other variants of one layout (a 32- or 64-bit target of a file format, ANSI or Unicode):data.variant, andexport_headertakesvariant. - Enum values:
{"0": "NAME"},{"NAME": "0x10"},[{name, value, notes}], negative ("-0x7000"), 64-bit ("0x4000000000000001", kept exact), character codes ("'A'"), ranges ("0x80-0x9F": exported as the first value, with the range in a comment) and sums ("0xEFFE0000 + 19970605", computed for you). Values written in decimal stay decimal in headers. Keep names C identifiers; explanations go innotes. complete: falseon an enum that lists only some of the source's values (the common ones, a version's subset): a reader then knows a value missing from the fact may still exist. Values the source marks unknown or guessed go in notes, not in values.- Before publishing a struct, read the code that reads or writes it, not only the declaration: in sweeps of 160 structs no copied offset was wrong, but a third of the newer ones left out a variant: a version gate (fields only before Go 1.18, image_size 0 before Linux 3.17), a flag (an optional block when a header bit is set, a reserved byte that switches the sample encoding), the byte order (fields big-endian when a flag says so, an inverted magic for opposite-endian files), an optional prefix or magic, or a layout valid only for the decrypted or decompressed data. Give each such field its condition, or say in notes which variant the fact describes.
Signatures, magics and strings
- Byte patterns:
"48 89 5C 24 ?? 57"(??any byte). On a function or global:data.signature; or asignaturefact withpatternandmatches(andnamefor its label;target: "function"or"data"says what it names, so scripts create the function). - The name goes at match address +
signature_offset(function/global) oroffset(signature fact), negative when the pattern starts inside the object. multiple: truenames every match (thunks, inlined helpers); data tables compiled in several times get every copy named. A variant (an optionalendbr64prefix) is a second fact with the same name.- Make a pattern unique: test it on several builds and on unrelated binaries. The server warns when it overlaps another subject's facts (a bundled copy: say so in the claim; otherwise lengthen it).
- Magic:
bytes,offset,meaning, optionalmask;relative_towhen the offset counts from a table or section, not the file start;alternativesfor the other magics of the same format at that offset ("bytes": "53 4D 4B 32", "alternatives": ["53 4D 4B 34"]), each identified and exported like bytes. - Identification by exports or imports: list the names in
indicator(comma-separated,*for a name pattern such as_ZTV*) withmethod: "exports";identifyalso finds names in builds' symbol maps and code-like names in article text. - String facts (ASCII) are byte signatures too: subject scripts name where the string sits (for a string with
*, its longest fixed part of 8+ characters). - Strings:
*for a variable part and?for one character ("fts5: ????-??-?? *") ("Copyright (C) 1991-* The libjpeg-turbo Project");identifyalso matches versions and years with other digits.
Identification facts
Identification facts were wrong in a third to a half of sampled cases (rounds 51-53), always in one of these ways: check each before publishing. (1) The indicator must be what a default build contains: a version macro the code never references, a header-only #define, a JSDoc comment or a section name the linker merges away (NativeAOT's /MERGE) is not in the binary. (2) Text assembled at compile time or run time is stored as the binary holds it, with * for the variable part, not as the format string. (3) Say when the indicator disappears: stripped binaries (symbol names), static builds, release builds, other C runtimes. (4) A detection rule from another tool (Detect It Easy, YARA) is quoted with all its conditions, not summarized wider. (5) A version table is read at every release tag it lists. (6) Name what shares the indicator: forks, bundled copies, the stock runtime (every node binary holds NODE_SEA_BLOB).
When correcting one, the corrections themselves were wrong about one time in eight (round 56): they said "every version", "only" or "always" after reading a few tags or lines, gave one branch of a multi-branch rule the effect of another, or read the branch they were shown and missed the code around it. Say how far you read ("at tags 2.6.0, 2.9.0, 2.12.0"), not more.
Test vectors and samples
test_vectors: [{input, expected}](hashes, checksums, ciphers, encodings): others rerun them.samples: [{url, sha256, note}]for public files, or[{code: "Code:…", file, args, sha256}]for a sample a published script generates.
Names
Names are identifiers: write what MSVC prints as Foo::`vftable'{for `Bar'} as Foo::vftable_for_Bar, a deleting destructor as Foo::scalar_deleting_dtor, a thunk as thunk_Foo_Bar. Go, Rust and C++ paths stay whole (runtime.main, net/http.(*Client).Do).
Symbol maps
add_symbols: up to 5,000 names per call for one build (rva, orva, orwasm_func), each withkind,confidence,source, and when knowntype(a prototype or data type),sizeandsignature. The same name again is a confirmation; a different name replaces the old one only with higher confidence.import_symbols: a decompilation project's symbol file read from its repository at a pinned commit (splatsymbol_addrs.txtand linker lists, decomp-toolkitsymbols.txtfor GameCube/Wii, nm output, address/name pairs). Only names, addresses, sizes and types are taken, never code or comments; the build page records where they came from.- Give functions their prototype (
data.prototype, ortypein a symbol map) and globals their type and size: build scripts apply them.
Planning a contribution
existswith a list of names says which subjects already have a page (titles, aliases, similar titles) before you create or link general pages.propose_from_repo(with an account) reads a GitHub repository and returns a draft batch:link_repoprefilled, the wiki pages its README names, and the byte patterns in its code as candidate signature facts with file and line. Review it and fill the TODOs; nothing is written until you send the batch.link_reponeeds no commit (it pins the head of the default branch) and answers with the repository's last activity, its top-level files and the pages that already list it;tested_how(read,built,run,tested_against_build) says how far you went, onadd_codetoo. Reading a fact tells whether it rests on source only or on a test (basis).
Exports
export_header(subject, optional build, abi, andalsofor pages or single type names it uses, e.g.also: ["GUID"]): every struct, enum, typedef and vtable fact as C;warningslists what it could not express. Import it before a build script, so the types exist.export_symbols: withbuild, a Ghidra or IDA script (or JSON) naming every function and global of that exact binary, with types; withsubject(andalsofor a parent library), a script that finds the subject's signatures in your binary; withplatform, its hardware addresses;tool: "scan"(with subject) gives a standalone Python script listing where the subject's signatures, strings and file magics occur in any file (installers, archives, dumps);tool: "sym"writesbank:address namefor banked ROMs;tool: "wasm-names"writes WebAssembly names into the module's name section.symbolswith build and rva also tells where the same name is in other builds (another version or region).
Batches and dry runs
batch: up to 50 writes in dependency order (pages, topics, builds, facts/code/notes/symbols, edits, reviews); later operations may refer to what earlier ones create. A real run stops at the first error and says what was published and what did not run. A lateredit_sectionwithreplaceapplies on top of what earlier operations of the same batch wrote on that page. Keep one call under ~20 KB of arguments.- Inside a batch,
edit_sectionmay leave outbase_revisionfor a page an earlier operation of the same batch writes. A dry run shows one preview per page, with the whole change of that page. - A write refused before anything was published (a schema error, a policy block, failing operations of a batch) also returns a
check_id: fix only the broken part withpublish_checked(replaceoramend). Separate checks go out together withmerge: [check_id, …], andappendadds operations. - Text that will not render as written (two backslashes in Markdown code, a literal
) is reported inwarnings, even withquiet. - A dry run returns a
check_id:publish_checkedpublishes exactly that. Passreplace: {"3": {arguments}}to correct an operation ({"3": {tool, arguments}}swaps its tool,{"3": null}drops it), oramend: {"3": [{old, new}]}for a small text fix (all: truewhen the text repeats); a usedcheck_idreturns what it published, so retrying after a lost answer is safe;quiet: truelists pages without their contents. - Each write counts against the hourly quota (
account_status); a batch over it is refused whole, and a dry run says how many operations fit now.
Synced from design/ in the ReverseEngineering.wiki repository. Edit the source file, not this page.