# xorscan

> **Tool `tools/formats/xorscan.py`** (program, Formats). Find the key of a simply obfuscated data file: XOR with one byte or a repeating key, adding a byte, a key that steps by a fixed amount each byte, or each byte XORed with the one before.

Run it with `./gameframe run xorscan ARGS` or `python3 tools/formats/xorscan.py`. [Source on GitHub](https://github.com/tanepiper/game-frame/blob/main/tools/formats/xorscan.py).

## Its own help

This is the help text in the tool itself, as `./gameframe tool xorscan` prints it.

```text
Find the key of a simply obfuscated data file: XOR with one byte or a repeating key, adding
a byte, a key that steps by a fixed amount each byte, or each byte XORed with the one before.

Usage: xorscan.py FILE [--offset N] [--length N] [--known HEX@OFFSET] [--top N]
       xorscan.py FILE --apply SCHEME -o OUT

  --offset, --length   scan only part of the file (a header's encrypted body, one entry)
  --known HEX@OFFSET   bytes you know are there once decoded (a magic number, a name, zeros),
                       for example 52494646@0 for "RIFF" at the start
  --top N              how many candidates to show (default 8)
  --apply SCHEME       decode the whole file with one result line's scheme, such as
                       xor:5a  xor-key:1f2e3d  add:80  step:5a+3  chain:00  rol:3

Many games hide their text, scripts or tables with a simple XOR so that people cannot read
them in a file viewer. The schemes are weak, and the decoded bytes give the key away: game
data has many zero bytes and much ASCII. Each candidate is scored by how much of the result
is zeros or printable text, with a bonus when a known format's signature appears. Read the
preview, then confirm the scheme in the code that reads the file (re-format, re-trace) before
porting it: the code may also compress, or change the key per file or per entry.

If nothing scores well, the file may be compressed (filetypes.py shows its entropy) or use
a real cipher. Then find the decoder in the code. Decoded files are game material: write
them into target/ or another folder that git ignores. Standard library only.
```

## Named by

Skills: [re-format](/skills/re-format).