If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Perfare/Il2CppDumper shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 12 active contributors
• MIT licensed
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 84% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Perfare/Il2CppDumper repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Perfare/Il2CppDumper.

What it runs against: a local clone of Perfare/Il2CppDumper — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Perfare/Il2CppDumper | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 659 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Perfare/Il2CppDumper. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Perfare/Il2CppDumper.git
#   cd Il2CppDumper
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Perfare/Il2CppDumper and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Perfare/Il2CppDumper(\\.git)?\\b" \\
  && ok "origin remote is Perfare/Il2CppDumper" \\
  || miss "origin remote is not Perfare/Il2CppDumper (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Il2CppDumper/Program.cs" \\
  && ok "Il2CppDumper/Program.cs" \\
  || miss "missing critical file: Il2CppDumper/Program.cs"
test -f "Il2CppDumper/Il2Cpp/Il2Cpp.cs" \\
  && ok "Il2CppDumper/Il2Cpp/Il2Cpp.cs" \\
  || miss "missing critical file: Il2CppDumper/Il2Cpp/Il2Cpp.cs"
test -f "Il2CppDumper/Il2Cpp/Metadata.cs" \\
  && ok "Il2CppDumper/Il2Cpp/Metadata.cs" \\
  || miss "missing critical file: Il2CppDumper/Il2Cpp/Metadata.cs"
test -f "Il2CppDumper/ExecutableFormats/ElfBase.cs" \\
  && ok "Il2CppDumper/ExecutableFormats/ElfBase.cs" \\
  || miss "missing critical file: Il2CppDumper/ExecutableFormats/ElfBase.cs"
test -f "Il2CppDumper/Outputs/Il2CppDecompiler.cs" \\
  && ok "Il2CppDumper/Outputs/Il2CppDecompiler.cs" \\
  || miss "missing critical file: Il2CppDumper/Outputs/Il2CppDecompiler.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 659 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~629d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Perfare/Il2CppDumper"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Il2CppDumper is a reverse engineering tool for Unity's il2cpp runtime that reconstructs .NET assemblies from compiled il2cpp executables. It parses both the il2cpp binary (ELF, Mach-O, PE, NSO, WASM formats) and the global-metadata.dat file to recover class definitions, methods, fields, and properties, then outputs restored DLLs and IDA/Ghidra/Binary Ninja analysis scripts. Modular single-project architecture: ExecutableFormats/ handles binary parsing (ELF, Mach-O, PE, NSO, WASM classes); Il2Cpp/ contains metadata and il2cpp structure parsing (Metadata.cs, Il2Cpp.cs); Outputs/ generates artifacts (DummyAssemblyExporter, StructGenerator, IL decompiler); Extensions/ provides utilities (binary readers, Boyer-Moore-Horspool search, hex/string helpers).

Security researchers, game modders, and reverse engineers who need to analyze Unity games compiled with il2cpp; also used by tool developers like UtinyRipper and UABE to extract game assets and scripts.

Production-ready and actively maintained. The project supports Unity 5.3–2022.2, has AppVeyor CI configured, includes structured output options (dummy DLLs, header files, multiple disassembler scripts), and the README shows established feature completeness. However, commit recency and star count are not visible in provided data.

Moderate risk: single maintainer (Perfare) with no visible test suite in file listing increases maintenance burden; il2cpp format evolves with Unity versions requiring ongoing parser updates; no obvious dependency management visible except standard .NET libraries. Reverse-engineering targets mean compatibility breaks are frequent and hard to catch without broad test coverage.

Not visible from file structure alone, but based on version support through Unity 2022.2 and feature-complete README, the project appears stable. The presence of il2cpp version forcing logic (ForceIl2CppVersion in Config.cs) suggests ongoing work to handle version-specific parsing quirks.

git clone https://github.com/Perfare/Il2CppDumper.git
cd Il2CppDumper
dotnet build Il2CppDumper.sln
# Then run: Il2CppDumper/bin/Debug/Il2CppDumper.exe <executable> <global-metadata.dat> <output-dir>

Daily commands:

# GUI mode (default):
Il2CppDumper.exe
# CLI mode:
Il2CppDumper.exe <executable-file> <global-metadata.dat> <output-directory>

Configuration via config.json in working directory (DumpMethod, GenerateDummyDll, ForceIl2CppVersion, etc.).

• Il2CppDumper/Program.cs — Main entry point orchestrating the entire dump workflow; all execution flows start here
• Il2CppDumper/Il2Cpp/Il2Cpp.cs — Core Il2Cpp binary parsing engine that extracts metadata and reconstructs type information
• Il2CppDumper/Il2Cpp/Metadata.cs — Parses global-metadata.dat file structure; critical for extracting all assembly metadata
• Il2CppDumper/ExecutableFormats/ElfBase.cs — Abstract base for executable format handlers; defines interface for all binary file parsers
• Il2CppDumper/Outputs/Il2CppDecompiler.cs — Generates human-readable IL code and reconstructs DummyDll assemblies from parsed metadata
• Il2CppDumper/Config.cs — Configuration management including version detection and binary structure offsets

Add Support for a New Executable Format

1. Create a new format class inheriting from ElfBase or the appropriate base class (Il2CppDumper/ExecutableFormats/YourFormat.cs)
2. Implement format-specific section parsing and Il2Cpp metadata offset resolution (Il2CppDumper/ExecutableFormats/YourFormatClass.cs)
3. Register the new format in Il2Cpp.cs LoadMetadata() method's format detection logic (Il2CppDumper/Il2Cpp/Il2Cpp.cs)

Add Support for a New Unity Version

1. Determine the Il2Cpp struct field offsets for the target Unity version (Il2CppDumper/Config.cs)
2. Add a new version entry with version-specific offsets in the config (Il2CppDumper/Config.cs)
3. Test with a sample global-metadata.dat and executable from that Unity version (Il2CppDumper/Il2Cpp/Metadata.cs)

Add a New Debugger Integration Script

1. Generate JSON output containing function offsets and type metadata (Il2CppDumper/Outputs/ScriptJson.cs)
2. Create a new Python script that parses the JSON and applies annotations in the target tool (Il2CppDumper/your_debugger.py)
3. Use existing ida.py or ghidra.py as templates for API bindings (Il2CppDumper/ida.py)

• C#/.NET Framework — Enables native .NET assembly reconstruction and easy integration with dnSpy/ILSpy decompilers for final inspection
• Binary I/O (BinaryReader/custom streams) — Required for precise parsing of multiple executable formats and complex Il2Cpp metadata structures
• Python scripts (IDA, Ghidra, Binary Ninja) — Integrates with widely-used reverse engineering tools to automatically annotate functions and structures
• LZ4 decompression — Necessary to decompress Android memory-dumped libil2cpp.so files

• Version-based offset configuration instead of dynamic struct detection

  • Why: Il2Cpp field offsets vary per Unity version; manual mapping is more reliable than heuristics
  • Consequence: New Unity versions require manual offset discovery; Config.cs must be updated frequently

• Output multiple formats (DummyDll, JSON, headers, debugger scripts) simultaneously

  • Why: Different users need different artifacts (reverse engineers, tool integrators, researchers)
  • Consequence: Higher complexity in output generation; larger disk footprint

• Format detection via binary header inspection rather than file extension

  • Why: Executables often have wrong or ambiguous extensions; magic bytes are reliable
  • Consequence: Slightly slower initial load; more resilient to misnamed files

• Runtime code execution or instrumentation—only static binary analysis
• Support for obfuscated or encrypted Il2Cpp binaries (focuses on standard Unity builds)
• Cross-platform code re-hosting; output is for analysis only, not execution
• GUI for manual struct offset discovery; assumes config.json is pre-populated

1. Version-specific parsing: Il2Cpp format changed significantly across Unity versions; ForceIl2CppVersion config option required for older Android binaries—mismatching parser version causes silent struct corruption. 2) Pointer redirection: Memory dumps use redirected pointers; NoRedirectedPointer config must be true for certain devices or offsets will be wrong. 3) Metadata alignment: global-metadata.dat requires correct architecture detection (32 vs 64-bit); wrong assumptions cause all type lookups to fail silently. 4) LZ4 decompression: MetadataClass.cs may decompress metadata; Lz4DecoderStream.cs must be used or raw metadata fails to parse. 5) Section mapping: ELF/Mach-O parsers must correctly map virtual addresses to file offsets; address space layout assumptions vary by binary protection.

• IL2CPP metadata and runtime separation — Il2cpp splits .NET metadata (types, methods, fields) from compiled code; understanding this split is why Il2CppDumper requires both global-metadata.dat and the il2cpp binary
• Pointer redirection and address space layout — Memory dumps use virtual addresses that may be redirected; Il2CppDumper's NoRedirectedPointer config compensates for ASLR and runtime relocation—critical for correct offset calculation
• Binary format parsing (ELF, Mach-O, PE, NSO, WASM) — Il2cpp binaries ship in multiple executable formats across platforms; ExecutableFormats/ must parse section headers, symbol tables, and relocations for each—core skill for adding platform support
• LZ4 compression in metadata — global-metadata.dat often uses LZ4 compression; Lz4DecoderStream.cs decompresses it transparently—unhandled compression breaks all metadata parsing
• Boyer-Moore-Horspool pattern matching — Stripped il2cpp binaries lack symbol tables; BoyerMooreHorspool.cs searches for il2cpp structure signatures in binary data by pattern—enables reverse engineering without symbols
• .NET assembly generation via reflection — DummyAssemblyExporter.cs reconstructs .NET DLLs in memory using reflection APIs; output DLLs are consumable by dnSpy/ILSpy—the key output artifact for users
• Il2cpp version detection and format evolution — Il2cpp binary format changed across Unity versions (5.3–2022.2); Il2Cpp.cs must detect version and apply version-specific parsers—missing version handling causes silent struct corruption

• Perfare/Zygisk-Il2CppDumper — Companion project for runtime il2cpp dumping on Android using Zygisk; complements Il2CppDumper for memory-based analysis
• dnSpy/dnSpy — Primary consumer of Il2CppDumper's DummyDll output; users decompile restored assemblies with dnSpy to read recovered code
• mafaca/UtinyRipper — Uses Il2CppDumper's restored DLLs to extract MonoBehaviour and game assets; directly dependent on accurate class/field recovery
• AssetRipper/AssetRipper — Modern successor to UtinyRipper; extracts Unity game assets using il2cpp metadata dumped by Il2CppDumper
• Cpp2IL/Cpp2IL — Alternative il2cpp reverse engineering tool with different architecture (source-level C++ analysis); solves the same problem with different output format

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for IL2CPP metadata parsing (Metadata.cs and MetadataClass.cs)

The Il2Cpp folder contains core metadata parsing logic but there are no visible test files in the repo structure. This is critical for a reverse engineering tool where metadata parsing correctness directly impacts all downstream analysis. Tests would catch regressions when supporting new Unity versions and help validate against different il2cpp binary formats.

• [ ] Create Il2CppDumper.Tests project alongside Il2CppDumper.csproj
• [ ] Add test fixtures for various Unity versions (5.3, 2020.x, 2022.x) in test data folder
• [ ] Write tests for Metadata.cs parsing: magic numbers, version detection, section offsets
• [ ] Write tests for MetadataClass.cs: type resolution, class hierarchy reconstruction
• [ ] Add tests for edge cases: corrupted metadata, unsupported versions, malformed structures

Add GitHub Actions CI workflow for multi-platform builds and test execution

Currently only AppVeyor is used (visible in README badge). The repo supports multiple executable formats (ELF, Mach-O, PE, NSO, WASM) and should verify builds work cross-platform. A GitHub Actions workflow would provide Linux/macOS/Windows matrix testing, validate the tool against sample binaries, and ensure the Il2CppBinaryNinja plugin builds correctly.

• [ ] Create .github/workflows/build-and-test.yml for Windows/Linux/macOS matrix
• [ ] Add step to build Il2CppDumper.sln and verify no build errors
• [ ] Add step to run unit tests (once PR #1 is completed)
• [ ] Add validation step that runs Il2CppDumper.exe against a small test binary with known metadata
• [ ] Add separate workflow for Python plugin validation (ida.py, ghidra.py, hopper-py3.py syntax checks)

Extract and document the Il2Cpp binary format specifications (add BINARY_FORMAT.md)

The codebase contains implicit knowledge about il2cpp binary structure scattered across Il2Cpp/Il2Cpp.cs, Outputs/Il2CppConstants.cs, and multiple executable format handlers. A structured specification document would help new contributors understand how the tool parses metadata offsets, handles version differences (5.3-2022.2), and work with different architectures (ARM, x64, WASM).

• [ ] Create BINARY_FORMAT.md documenting the global-metadata.dat structure and sections
• [ ] Document version-specific differences and how VersionAttribute.cs maps versions to parsing rules
• [ ] Add diagrams or tables explaining: magic numbers, section headers, metadata layout for major Unity versions
• [ ] Document the role of ExecutableFormats/* in extracting il2cpp binary metadata and how PE/ELF/Mach-O differ
• [ ] Reference specific line numbers in Il2Cpp.cs and Il2CppConstants.cs for each structure definition

• Add unit tests for BoyerMooreHorspool.cs pattern matching with known il2cpp binary patterns (test data could be extracted from public games); currently no test suite exists in file listing.
• Document the il2cpp version detection algorithm in Il2Cpp.cs with a README table mapping version numbers to Unity releases and format changes; helps contributors understand why ForceIl2CppVersion exists.
• Add verbose logging to Metadata.cs metadata parsing (LZ4 decompression, type offset resolution) to help debug 'metadata parse failure' errors users report in issues; currently errors are silent.

• High · Execution of Untrusted Code via Il2Cpp Binary Analysis — Il2CppDumper/ExecutableFormats/ (all format handlers). The application processes and analyzes compiled IL2CPP binaries from external sources. Without proper validation, this could allow execution of malicious code through specially crafted binary files. The tool loads executable formats (ELF, Mach-O, PE, WASM) and parses their structure, which could be exploited. Fix: Implement strict binary format validation, sandboxing of binary parsing operations, and cryptographic verification of input files before processing.
• High · Insecure Deserialization via Custom Assembly Loading — Il2CppDumper/Utils/DummyAssemblyGenerator.cs, Il2CppDumper/Utils/MyAssemblyResolver.cs, Il2CppDumper/Outputs/DummyAssemblyExporter.cs. The codebase uses custom assembly resolution and dummy assembly generation (DummyAssemblyGenerator.cs, MyAssemblyResolver.cs) which could be exploited to load malicious assemblies. The DummyAssemblyExporter generates DLLs dynamically without apparent validation. Fix: Implement assembly signing verification, use AppDomains/AssemblyLoadContext with strict security policies, and validate all generated assembly contents before execution.
• High · Unsafe Native Interop Operations — Il2CppDumper/Utils/FileDialogNative.cs, Il2CppDumper/Utils/PELoader.cs. The application uses P/Invoke and native interop (FileDialogNative.cs, PELoader.cs) to interact with system libraries and file dialogs. This could be exploited for privilege escalation or system compromise if not properly validated. Fix: Minimize native interop calls, use safe wrappers, validate all parameters passed to native functions, and run with minimal required privileges.
• Medium · Hardcoded Configuration and Library Paths — Il2CppDumper/Libraries/Il2CppDummyDll.dll, Il2CppDumper/config.json. The presence of hardcoded paths like 'Il2CppDummyDll.dll' in Libraries folder and config.json suggests potential hardcoded sensitive paths or configurations that could be exploited or become stale. Fix: Move all configuration to secure configuration management systems, use environment variables for paths, implement path validation, and never hardcode library paths.
• Medium · Memory Handling in Binary Parsing — Il2CppDumper/IO/BinaryStream.cs, Il2CppDumper/Extensions/BinaryReaderExtensions.cs. The BinaryStream.cs and BinaryReaderExtensions.cs are used extensively for parsing untrusted binary data. Improper bounds checking or buffer handling could lead to information disclosure or denial of service. Fix: Implement strict bounds checking for all binary read operations, validate array indices before access, use safe parsing libraries, and implement size limits on parsed structures.
• Medium · Unrestricted File Operations — Il2CppDumper/Program.cs, Il2CppDumper/Utils/OpenFileDialog.cs. The application reads and writes files directly without apparent restrictions on file paths. Command-line arguments accept file paths that could allow directory traversal attacks via metadata files or executable paths. Fix: Implement strict path validation using canonical paths, whitelist allowed directories, reject paths with '..' sequences, and use secure file APIs with minimal permissions.
• Medium · Python Script Security Risk — Il2CppDumper/ida.py, Il2CppDumper/ghidra.py, Il2CppDumper/ghidra_wasm.py, Il2CppDumper/hopper-py3.py, Il2CppDumper/ida_with_struct_py3.py. Multiple Python scripts are included (ida.py, ghidra.py, hopper-py3.py) which are executed to integrate with reverse engineering tools. These could be exploited if the Python environment is compromised or if the scripts are modified. Fix: Sign Python scripts cryptographically, verify script integrity before execution, run Python in isolated environments, and restrict script permissions.
• **** · undefined — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.