{"id":46765736,"url":"https://github.com/christo/revenge","last_synced_at":"2026-03-09T22:34:02.352Z","repository":{"id":151421047,"uuid":"619438424","full_name":"christo/revenge","owner":"christo","description":"Reverse Engineering Environment for Retro-Programming","archived":false,"fork":false,"pushed_at":"2025-10-29T06:05:00.000Z","size":13831,"stargazers_count":11,"open_issues_count":11,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-10-29T07:32:43.686Z","etag":null,"topics":["6502","c64","disassembler","retrocomputing","reverse-engineering","vic20"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/christo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-03-27T06:28:06.000Z","updated_at":"2025-10-29T06:05:04.000Z","dependencies_parsed_at":"2024-03-05T04:23:59.798Z","dependency_job_id":"d951611b-206c-402d-897a-c2dab609224c","html_url":"https://github.com/christo/revenge","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/christo/revenge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christo%2Frevenge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christo%2Frevenge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christo%2Frevenge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christo%2Frevenge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/christo","download_url":"https://codeload.github.com/christo/revenge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christo%2Frevenge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30314631,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T20:05:46.299Z","status":"ssl_error","status_checked_at":"2026-03-09T19:57:04.425Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["6502","c64","disassembler","retrocomputing","reverse-engineering","vic20"],"created_at":"2026-03-09T22:34:01.380Z","updated_at":"2026-03-09T22:34:02.335Z","avatar_url":"https://github.com/christo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Revenge\n\n\u003c!--suppress HtmlDeprecatedAttribute --\u003e\n\u003cimg alt=\"revenge logo\" align=\"right\" src=\"client/public/revenge-logo192.png\"\u003e\n\nRetrocomputing Reverse Engineering Environment\n\nThis is a web app for programmers to reverse engineer software written\nfor 1980s era home computers. It's a work in progress.\n\n![automated tests](https://github.com/christo/revenge/actions/workflows/workflow.yml/badge.svg)\n\nThe grand idea is a web-based reverse engineering environment for retro computers\nwith very small initial goals: binary file type detection and simple disassembly of\n6502 machine code for the Vic-20 and C64. Z80 is a likely supported architecture\nin future.\n\nBeyond the small initial goals lies a vast land of unfulfilled wishes.\n\n**Project Status**: _pre alpha_ (it sort of works with plenty left [TODO](TODO.md))\n\n![revenge screenshot](docs/revenge-screenshot-20250407.png)\n\nCurrently, the disassembler is fully automatic, although it identifies very few bytes\ndefinitively as data. Binary content type (basic, machine code with basic stub, cart\nimage, etc.) is detected using heuristics and falls back to a hex dump if it can't\ndetect the filetype.\n\nWork is in progress to train a classifier (you can call it AI) to recognise\nbinaries based on statistics collected by various implementations of `FeatureExtractor`.\nThe model can be trained in `server` with `bun train`. Note that a corpus of binary\nfiles must exist in the `server/data/training/c64` and `server/data/training/vic20`\ntrees. Based on my current testing, the results are still very poor, but I am confident\nthis method will work once the implementation is good enough. Recognising compressed\nfiles and other container formats like disk images is not yet tested.\n\n## Architecture\n\nImplemented in [TypeScript](https://www.typescriptlang.org/), using [Bun](https://bun.sh/),\n[Vite](https://vite.dev/), [MUI](https://mui.com/), [React](https://react.dev/) and\n[Mocha](https://mochajs.org/)/[Chai](https://www.chaijs.com/) for testing.\n\n## Quick Start\n\nAfter checking out this repo, from a shell in the root directory, run the sanity script\nto check you have the relevant/recommended tools installed:\n\n```shell\n./sanity.sh\n```\n\nThe main system is a single page web app with an optional server component which provides\naccess to retro binaries stored on the local filesystem a few are included in this\nrepo. Without the server, you can drag and drop files from your computer into the browser or click\nthe upload button. The plan for the server is to manage the state of interactive sessions\nand provide access to a file tree of binaries for bulk analysis.\n\nRun the server in its own shell from the `server` dir:\n\n```shell\ncd server\nbun dev\n```\n\nRun the client in its own shell from the `client` dir:\n\n```shell\ncd client\nbun dev\n```\n\nThe URL to point your browser to is shown in the client console.\n\n## System Design\n\nBuild and execution environment is `vite` for the client and `bun` for both client and server.\nNode should also work with `npm` or `pnpm`. I'm not sure how to structure the project to be\ntransparently agnostic about this but if you have opinions and skills, get in touch and I will\naccommodate any sane suggestions. To use `npm` or `pnpm`, check the `client/package.json` and\n`server/package.json` files to see what scripts are defined.\n\n## Features\n\n* drag and drop file loading\n* load file contents into summary view\n* hex view (minimal)\n* dumb disassembly - exemplary detection of code vs data is a project goal\n* file type recognition\n  * can recognise at least two types and offer to disassemble if it knows how\n  * vic20 raw cartridge image recognition\n  * BASIC programs\n  * Machine code programs with a [Basic Stub](docs/basic-headers.md).\n* representation of a syntax-independent assembler pseudo-op and Dialect can implement\n  syntax-specifics\n* assembly syntax highlighting\n* Trace code paths to build call graph for detecting code vs data.\n* Track static addresses written to and read from during trace execution (in progress)\n* Decode BASIC programs on VIC-20 and C64\n* Test suite\n* High quality reference data from the [c64ref](https://github.com/mist64/c64ref) project, initiated\n  by [Michael Steil](https://pagetable.com/) of\n  [The Ultimate C64 Talk](https://youtu.be/ZsRRCnque2E) fame.\n* Stats/summary of file interpretation action taken\n  * execution time for disassembly\n  * trace time\n  * symbol detection count (disassembly)\n* System kernal subroutine symbol recognition (VIC-20, C64)\n* Visual plot of bi-gram frequency analysis of overlapping byte pairs in a binary. These\n  are pretty good at visually distinguishing encrypted or compressed binaries. Machine code looks\n  pretty different to BASIC.\n* Content hash system for identifying uploads that exist in local corpus \n  * future support of third-party software databases \n\n## System Support Status\n\nThe design aims to reduce the effort of supporting multiple different systems, however at this\nstage only VIC-20 and C64 carts, prg files and BASIC files have been tested and there is no\ncomprehensive test suite yet. Also, I'm not sure how feasible it would be to support some systems.\nWithin the communities of each system, different assembler tool chains are more prevalent.\n\nIn general, project scope includes support for 6502-based and Z80-based 80s Microcomputers and a\ngenerous subset of the more common assembler syntax dialects. Other 80s 8-bit CPUs are possible\nbut their inclusion would probably be driven by personal interest and the availability of large\nsoftware libraries. The following table shows estimations, not promises.\n\n| Machines                     | Status      | CPU Family |\n|------------------------------|-------------|------------|\n| VIC-20                       | In Progress | 6502       |\n| C64                          | In Progress | 6502       |\n| CHIP-8                       | Planned     | virtual    |\n| Apple II                     | Planned     | 6502       |\n| BBC B                        | Planned     | 6502       |\n| C128                         | Planned     | 6502       |\n| NES                          | Probable    | 6502       |\n| Oric                         | Probable    | 6502       | \n| Atari 8-bit                  | Probable    | 6502       | \n| SNES                         | Probable    | 6502       |\n| ZX Spectrum \u0026 clones         | Planned     | Z80        |\n| TRS-80 I-III                 | Probable    | Z80        |\n| Microbee                     | Probable    | Z80        |\n| VZ-200 / VZ-300 / Laser      | Probable    | Z80        |\n| GameBoy, GameBoy Color       | Probable    | Z80 -ish   |\n| GameBoy Advance              | Possible    | ARM        |\n| Vectrex, TRS-80 Coco, Dragon | Possible    | 6809       |\n\n## File Formats\n\nInfo on [binary file formats](docs/file-formats.md) is documented to guide the design of content\ndetection and disassembly.\n\n## Assembly Dialects\n\nSee document about plans and ideas to support various\n[assembler dialects](docs/assembler-dialects.md). Supporting a new dialect is a matter of\nimplementing the **Dialect** interface, possibly subclassing **BaseDialect**.\n\nCurrently only one arbitrary custom dialect is implemented while the API is being stabilised.\n\n## Code Detection\n\nIt's not hard to make good guesses about what parts of a binary are code or data, but it is harder to\ndo reliably and automatically. Therefore, most reverse engineering tools are interactive; the user\nmust get involved to interpret and understand the binary and to dictate what is code, text data,\nimage data, audio etc. and this is even trickier when code is self-modifying, compressed, encrypted,\nobfuscated or when bytes are treated as both code and data.\n\nUsing a hybrid approach to code detection, some parts of a binary can be confidently identified as\ncode through a mixture of static and dynamic analysis. A `Tracer` is implemented which follows code\nexecution paths, including both sides of conditional branches and records which addresses hold\ninstructions. In many cases this approach can determine parts which are almost certainly code and\nalso to identify regions of almost certain data.\n\nWork on this is ongoing.\n\nSolving this problem deterministically for all possible programs is equivalent to solving\n[The Halting Problem](https://en.wikipedia.org/wiki/Halting_problem) which has been famously proved\nto be impossible. Solving it deterministically for certain programs, constrained to a useful subset\nof possible instructions is at an early stage of implementation and further work to extend this with\npartial evaluation and probabilistic execution could be very useful for accelerating reverse\nengineering on small retro systems.\n\nUsing a combination of preemptive emulation, detailed machine architecture definitions and static\nanalytic techniques like program transformation, escape analysis, peephole optimisation and dynamic\ntechniques like speculative partial execution, combined with a large cross-referenced database built\nfrom a corpus of known software, I hope to give insight to a human reverse engineer about any\nsoftware written for these enigmatic retro systems.\n\nRead more notes about [Dynamic Analysis](docs/dynamic-analysis.md).\n\nRead more about how machine learning techniques are being developed to build a\n[Classifier](docs/classifier_improvements.md) that may be able to identify salient features\nof binaries. This is a work in progress.\n\n## Useful Resources Documented Here\n\n* [Reverse Engineering](docs/reverse-engineering.md) references\n* [Retro Assembler Dialects](docs/assembler-dialects.md)\n* [Emulators](docs/emulators.md)\n* Relevant [file formats](docs/file-formats.md) for retro computing\n* [Dynamic Analysis](docs/dynamic-analysis.md) - some thoughts on prospects for runtime techniques for\n  automating the detection of code and data and topics like program comprehension and program transformation.\n* How [Basic Stubs](docs/basic-headers.md) work on 8-bit Commodore machines.\n* [Ideas for the future](docs/ideas.md) of Revenge covering not only reverse engineering but\nreengineering and source renovation.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchristo%2Frevenge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchristo%2Frevenge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchristo%2Frevenge/lists"}