Security Model

Security Model

RE-Toolkit processes hostile input by design. This page describes the trust boundaries, the protections at each one, and the operational practices those protections assume.

For reporting a vulnerability in RE-Toolkit itself, see SECURITY.md.

Contents

• Threat model
• Trust boundaries
• The input sandbox
• Bounded execution
• Destructive tool options
• Execution boundaries
• Installer trust
• Output handling
• Operational practice
• What RE-Toolkit does not protect against

Threat model

The adversary is the target file. It was authored by someone who may anticipate that it will be analyzed, and who may have taken steps to interfere with that analysis.

Concretely, RE-Toolkit assumes a target may attempt to:

• Exploit a parser in one of the tools that examines it
• Consume unbounded time or memory to stall or crash a run
• Detect analysis and alter behavior accordingly
• Damage or alter itself to frustrate repeat analysis
• Escape a sandbox if it is executed

Two assumptions are deliberately not made. RE-Toolkit does not assume the tools it orchestrates are free of vulnerabilities, since binary parsers are a historically rich source of memory-safety bugs. And it does not assume that an operator's intent to analyze safely translates into a safe default; the defaults are what enforce it.

Trust boundaries

Untrusted: the target file, and everything derived from it
    |
    | copied into the run sandbox
    v
Bounded: tool execution, under timeout, output captured
    |
    | parsed into structured findings
    v
Untrusted content, trusted structure: _summary.json and the report

The boundary that matters most sits at the top. Everything derived from a target remains untrusted content: extracted strings, carved files, decompiled source, and resources are all attacker-controlled. They are safe to read, not safe to execute.

The input sandbox

The operator's original file is never touched by any stage.

Before analysis begins, the target is copied into <outdir>/_input/. The driver then reassigns its working target to the copy, so every subsequent stage operates on it. The original becomes unreachable by anything RE-Toolkit runs.

After the run, the original's SHA-256 is re-checked against the value recorded before analysis. This proves the protection held rather than assuming it.

The two mechanisms serve different purposes and are deliberately both present. The copy prevents damage. The hash check detects it, including from a future tool with a destructive option nobody has noticed yet. If that verification ever fails, it is a security bug worth reporting.

Copying rather than marking the original read-only is intentional. Read-only permissions are weaker: some tools fail confusingly on read-only input, and a sufficiently privileged process can restore write access. Copying is unconditional and holds regardless of tool behavior.

Bounded execution

Every external tool runs through run_tool, which enforces a timeout. A stage invoking a tool directly would bypass this, and is not permitted.

The timeout defends against the simplest denial of service available to a hostile input: a malformed structure that sends a parser into an unbounded loop. Without a bound, one target could stall a batch indefinitely.

Timeouts are recorded distinctly from failures, so a report shows where a limit was reached rather than silently omitting the result.

Output is captured rather than suppressed. A tool that fails leaves its stderr in 90-logs/, which is what makes the failure diagnosable afterward.

Destructive tool options

Several analysis tools offer options that modify their input. Those options are deliberately omitted from RE-Toolkit's invocations, and the reason is recorded in the source at the call site rather than only in a commit message.

This matters because the omission looks like an oversight to anyone unfamiliar with the tool. A future contributor adding a flag "for completeness" could reintroduce input mutation, which is precisely why the call sites carry an explicit note not to.

The sandbox makes this defense in depth rather than the only protection: even if a destructive option were reintroduced, it would operate on the copy.

Execution boundaries

Static analysis never executes the target. Nothing in the default path runs the binary. Stages read, parse, disassemble, and decompile it.

Dynamic Tier 1 emulates rather than executes. qiling interprets instructions in userspace and emulates system calls, so nothing reaches the host kernel. This is why Tier 1 requires no consent flag.

Dynamic Tiers 2 through 4 genuinely execute the target and require the explicit --allow-real-execution flag. Without it they skip cleanly and record why.

The consent flag exists because the risk difference between emulation and execution is categorical rather than incremental. It cannot be set implicitly by any other option.

See Dynamic Analysis for per-tier detail.

Installer trust

The installer runs with sudo and performs a system-wide install, which makes it the most privileged component and the one with the largest trust surface.

• Distribution packages are preferred, so most software arrives through the distribution's existing signature verification.
• Source builds and vendor downloads are used only where a tool is not packaged.
• Downloads use HTTPS. Fetching over plain HTTP is not acceptable, and a change introducing it should be rejected in review.
• Provenance for dual-use tooling is recorded, so what was fetched and from where is auditable after the fact.

The installer writes to /opt, /usr/local/bin, and /etc/profile.d. Anything that can write to those paths can influence later privileged execution, so their permissions matter as much as the install itself.

Output handling

Treat the output tree as untrusted content. It contains strings, resources, and files extracted from a hostile binary. Carved output from a malicious sample is still malicious.

Specifically:

• Do not execute anything found under an output directory.
• Be careful opening extracted documents and archives in applications that process active content.
• Extracted content retains whatever properties it had inside the original.

Reports are safe to open, and their content is not trusted. The HTML is self-contained: inline SVG and inline styling, with no external stylesheet, no content delivery network reference, and no JavaScript library fetched at view time. Opening a report generates no network traffic, so reviewing a sample cannot signal to an adversary that analysis is underway.

The data rendered inside a report still originated from the target. Values shown are attacker-controlled strings, displayed as text.

Operational practice

Analyze inside a disposable virtual machine. Snapshot before, revert after. This is the control that makes everything else a second line of defense rather than the last one.

Give the analysis host nothing worth taking. No mounted credentials, no shared filesystems with a host you care about, no network path to production.

Prefer no network. --dynamic-network none is the default and should stay that way unless observing network behavior is the specific goal.

Escalate deliberately. Start with static analysis, add Tier 1 when behavior matters, and move to real execution only when emulation cannot answer the question.

Check tool coverage before concluding. A stage that did not run produces no findings, which is not the same as finding nothing. The report distinguishes these; the raw absence of an output file does not.

What RE-Toolkit does not protect against

Being explicit about the limits is more useful than implying completeness.

Vulnerabilities in the tools it orchestrates. RE-Toolkit invokes many third-party parsers. A malicious file that exploits one of them is exploiting that tool. Timeouts and the sandbox limit the consequences; they do not prevent the exploitation.

Sandbox escapes during dynamic analysis. Namespace, container, and virtual-machine escapes all exist. The tiers reduce risk and are not a guarantee. This is why the disposable VM matters.

Sandbox-aware malware. A sample that detects analysis and behaves benignly will be reported as it behaved. Benign observed behavior is not proof of a benign sample.

Analysis quality. A missed detection or an incorrect severity is a bug, not a security boundary. The scoring model is a triage aid, and its evidence list is there so a verdict can be questioned rather than trusted blindly.

A compromised host. RE-Toolkit assumes it is running on a host that is not already controlled by an adversary. It offers no protection if that assumption is false.