---
name: protovision-report
description: Write the final report of a recorded-execution analysis (a protector, a packer, an anti-cheat, a launcher, a licence or integrity check, any program) from questions already answered on the recording. Use when the analysis is far enough along to be written up, or when asked to "write the report", "write up the analysis", "document what the program does". Produces a complete report - vocabulary, a chronological map in numbered stages, the mechanism in pseudo-code checked by a simulator, decisions, inputs and outputs, limits - and reviews it before delivery.
---

# Write the report of a recording analysis

The report discovers nothing. It lays out answers that were already obtained from the recording, each with its proof. A claim that has no proof in the answers does not go in the body: it goes in the limits or in the open questions.

The reader knows the subject but not this program. Every stage must be understandable without reading the others.

## Workflow

1. **Inventory** every answered question and file it under a theme (below).
2. **Write the skeleton** - titles and instant ranges - before any paragraph.
3. **Write each stage**, one section per stage, in the order of the run.
4. **Write the mechanism** (virtual machine, decoder, verifier, state machine) if the program has one, with pseudo-code and a simulator.
5. **Review** (last section). Nothing is delivered without this pass.

## 1. Inventory

For each question, one line:

| Field | Content |
|---|---|
| id | the question's identifier |
| Question | one sentence |
| State | answered, undecidable, open, pending |
| Answer | one sentence with exact values |
| Proof | instants (`@N`), thread, functions (address and the name given), bytes or registers |
| Confidence | high = read in the recording, medium = deduced, low = assumed |

Re-read the recording when an answer is ambiguous. Do not file an answer you do not understand.

## 2. Themes

A theme groups questions that are about the same thing *in the program*, not about the same tool. Start from this list and keep only what the recording contains:

1. Scope and capture quality (target, length, threads, what is missing)
2. Start-up: stub, loading, import resolution
3. Decryption, decompression, image mapping
4. Integrity: checksums, hashes, what they cover
5. Anti-analysis: debugger, timing, environment, hypervisor, hooks
6. Direct system calls and sensitive APIs
7. Virtual machine or interpreter: architecture, dispatcher, handlers
8. Verification (licence, key, signature, ticket): input, algorithm, verdict
9. Inputs and outputs: files, network, devices, child processes
10. End of the run: exit, return code, clean-up

Rules:
- One theme becomes one section, or a few consecutive ones. A theme with a single question is merged with its chronological neighbour.
- A question has one main theme. If it serves two, place it in the first by instant and cite it in the second by id only.
- Two questions with the same answer are merged; keep both ids in the proof.
- Never settle a contradiction silently. Keep both answers, say which is better proven and why, or flag it under "Keep in mind".
- A theme that does not apply gets one line: "N/A, because ...". It counts as an answer.

**Order.** Execution themes follow the order of their first instant. Ranges that overlap stay as they are, and the opening sentence says the recording interleaves several contexts. Cross-cutting themes (the machine, the verifier, key functions) come after. Scope opens the report; limits close it.

**Before writing, produce the theme table:**

| Theme | Questions | Instant range | Confidence | Gaps |
|---|---|---|---|---|

and two lists: *undecidable* (what prevents a conclusion: cut recording, a single pass, a branch never taken - they feed "Limits") and *open or pending* (what would have to be read - they feed "Open questions").

**Coverage check.** Every closed answer sits in a theme. The range from first to last instant has no hole of more than a few percent without a sentence explaining it. Every decision the recording crossed (verdict, exit jump) has an answer. Every input read and output produced is in a theme. If a hole remains, say so to the user instead of filling it.

## 3. Skeleton

```
Vocabulary (table: term | meaning)          <- define first what is used later
The run in N stages (table: range | stage)  <- the bounds, one sentence on interleaved contexts
## [a..b] Title of the stage                <- one section per stage
...
## The <name> machine                       <- one per layer, if any
## The verifier / licence / check           <- opcodes, program, algorithm, simulator
## Key functions                            <- pseudo-code of the functions that carry the logic
## Decisions                                <- guard, tested, taken, alternative, what flips it
## Inputs                                   <- what is read, by which function, at which instant
## Outputs                                  <- what is produced, with the instant
## Limits                                   <- what was not decoded, seen or proven
## Cost                                     <- only if asked, with real figures
```

For a target with several protections, add after the stages: **Protection inventory** (one entry per protection: present, absent, not seen), **Protection level** (the writer's assessment, said to be one) and **Facts and hypotheses**. Begin with an executive summary.

If fewer than half of the root questions are closed, write anyway but start with: "Provisional report: X answers closed out of Y". The sections claim only what is closed.

## 4. A stage section

```
## [a..b] Short title of the stage
> **In one sentence.** What the program does during this stage, with no undefined jargon.

**What happens.**
1. First fact, with @instant, the function (address), exact values.
2. Second fact ...

| Instant | Event | Value |
|---|---|---|
| @475084 | `GetModuleHandleA("kernel32.dll")` | loader VM entered at `0x140781d9a` |

**Why it matters.** (optional) What the stage changes for the rest or for a conclusion.

**Keep in mind.** What this stage did not prove.
```

- The range is `[first..last]`, in whole instants. Consecutive stages touch or overlap.
- The title says *what is done*, not the name of a tool: "Checksums of the loader table", not "CRC".
- "In one sentence" is one subject-verb-object sentence. Hypotheses are written as hypotheses.
- "What happens": in order of instants, four to nine points (more means split the stage). Each point has an action verb, an instant, the function and exact values. Loops are summarised: "464 passes, @5581 to @27599", with one formula for what each pass does. Values are the recording's, never "typical" ones. If a return value is not in the recording (untraced system code), say so.
- The table has three to six rows: the instants that carry the proof, not a summary. It adds no information absent from the text.
- "Why it matters" only when the stage can be confused with another or changes a conclusion.
- "Keep in mind" is one to three sentences on what the stage does *not* prove: an unfound consumer, a name inferred from argument shapes, a branch not read, a sample instead of a full check.
- A stage is 150 to 250 words outside the table. Do not write a conclusion the section does not prove, leave an instant without function or value, mix two stages, or write "we can see that" without saying where. Never state a programmer's motive ("to protect against ...") unless marked as deduced.

## 5. Machine, algorithm and pseudo-code

The pseudo-code is what the recording executed, not what the code could do. Code that was read but never executed is written as such.

**One section per machine layer** (a protector's loader, an inner VM, the target's own verifier):

```
## The <name> machine
> **In one sentence.** What it is (stack VM, threaded code, re-entry stubs) and how it dispatches.

### Architecture
| Element | Value |   (unit, dispatch hub with the exact target formula, stacks, operand stream, virtual registers, re-entry stubs and the hottest one)

### Record format and how to decode it
Numbered steps a person can apply by hand to find the handler of one step. Say if no decoder was written and the steps were read by hand at chosen instants.

### Handlers seen in this run
| Handler | Effect | Passes |   (one row per decoded handler, the effect as a formula)
Below it, the undecoded share: number of blocks and percentage of the run, and why.
```

**A decoded verifier** (licence, key, check), in order: (1) a table of elements - program (address, size), constants, work space, stack and fuel limits, dispatch table (entries, entries executed), input; (2) opcodes: Op | Name | Encoding | Effect | Passes - only *executed* opcodes are decoded, and the others are named as existing but never run; (3) the program, as blocks of pseudo-instructions with repetition ("eight rounds of the same shape, then a tail") and the decoys and never-read writes flagged; (4) the algorithm in pseudo-code, the shortest that reproduces the computation, exact constants, comments only for what is not obvious; (5) the simulator.

**The simulator is mandatory.** A short, standalone script that takes its constants *from the recording*, replays the computation on the *real input of the run*, prints the recorded value next to the simulated one at round boundaries or at the instants the report cites, and exits with an error if they differ. If they differ, the pseudo-code is wrong: fix it before writing anything else, and never adjust the simulator until it "fits". The simulator may evaluate another input; say "computed, not executed in the recording". A computed solution is not claimed to be the solution until the target has accepted it in a run. Paste the script in the report with the expected output as a comment.

**Key functions.** For `main` and each function that carries the logic, pseudo-code with the names from the recording (inferred names flagged) and, on each branch, the instant where it was taken or "not taken". Calls into untraced code are written as calls, without a body.

**Decisions.** One entry per decision the recording crossed:

```
### <Name of the decision>
- **Guard**: the instruction that decides (@instant).
- **Tested**: the value compared, and against what (value read).
- **Taken**: the branch followed in this run.
- **Alternative**: the other branch, and whether it was read in the code ("not executed") or never seen.
- **Flips when**: the condition that changes the outcome, or "not shown".
```

For anti-analysis checks give the branch taken *and* the one that would be taken elsewhere (another machine, an attached debugger).

**Inputs and outputs.** Inputs: each datum read - value, the function that consumes it, the instants of the reads; say when an input was not followed after being read. Outputs: each observable effect - message printed (instant, source string, exit code and what decided it), restored sections, patches written, import table filled, files, network - each saying what was *not* followed.

## 6. Rules for the whole report

- **One instant per claim.** `@N` is the rank of an instruction in the recording. Instant numbers are written whole, never rounded.
- **Observed, deduced, assumed.** What is read in the recording is written in the present and without reserve. What is deduced carries "deduced" and its source question. What is assumed carries "hypothesis" and a confidence. Never write a hypothesis as a fact.
- **The branch not taken is unknown.** A recording shows one path.
- **Limits are visible** where they touch a conclusion, then repeated in "Limits": undecoded parts (with their share of the run), inferred names, a cut recording, a single pass, consumers not found, loops whose content is not identified.
- **One language**, that of the request. Acronyms are defined at first use or in the vocabulary.
- **Describe the analysed program**, not the tools, protocol or internal instructions used to analyse it.
- **No secrets of the target in the report**: no key, no protector constant (use a symbol), no bypass recipe, no server address, no machine identifier.
- Dates are absolute.

## 7. Review before delivery

Look for what is wrong or unproven, not for what is badly written.

1. **Proof.** Every sentence about the program has an instant, a function or value, or a source question; otherwise prove it, move it to limits, or delete it. Spot-check at least five claims (one per major stage, including an exact value, an address and a pass count) against the recording. If one differs, widen the check to the whole stage. Copy exact values; do not retype them.
2. **Observed, deduced, assumed** are distinguishable at reading time. No "therefore" links a fact to a motive unless the motive is marked deduced.
3. **Numbers.** Stage ranges cover the run in order; holes and overlaps are explained once, at the top. The total instruction count is the same everywhere. A number cited twice is identical. A percentage has its denominator.
4. **Pseudo-code and simulator.** The simulator was run and its output is the one in the comment. It reproduces the recorded values at the cited instants. No never-executed opcode is presented as decoded. No computed solution is claimed valid. Every branch says if it was taken.
5. **Limits** contain, where they apply: the undecoded share and why; branches not taken; what the recording does not contain (another machine, another date, a debugger, cut threads, a truncated recording); consumers not found; inferred names; unidentified loops.
6. **Reading.** The vocabulary defines every term used afterwards, and only those. A reader who knows the subject but not this program understands each stage alone. The level of detail is even from stage to stage.
7. **Delivery.** The cost section exists only if requested, with real figures and their basis. A provisional report says how many answers are closed.

End the review with a short account:

```
Reviewed: <file>
Fixed: <n> unproven claims moved to limits, <n> values corrected, <n> ranges adjusted
Spot-check: <n> claims re-read on the recording, <n> mismatches
Simulator: run, output matches (or: mismatch on <value>, fixed)
For the author to decide: <list, or "nothing">
```

## Delivery

Write to the requested folder, otherwise `report-<target>.md` next to the analysis. Open the message with one line naming the audience as you understood it (technical team, management, client). Close with the number of answers used, the number of limits, and what remains open.