qprotect-research

KO | EN

gitlite — search

#electron #proxy #codex #c #deep-learning #bash #api #vue #shell #data-science

qprotect-research

(★ 9)

qProtect virtualization research

File Explorer

ZIP Download

- opcode_handlers.json
- fingerprint.json
- seeds.json
- - __init__.py
  - bytecode.py
  - classfile.py
  - classwriter.py
  - jar.py
  - jvm_emit.py
  - vm_constants.py
  - vm_decrypt.py
  - vm_payload.py
- __init__.py
- decrypt.py
- lifter.py
- - codes.som.oof4j.fizzbuzz.enterprise.computation.EnterpriseFizzBuzzComputationFactory.java
  - codes.som.oof4j.fizzbuzz.enterprise.computation.EnterpriseFizzBuzzComputationTask.java
  - codes.som.oof4j.fizzbuzz.enterprise.computation.unit.FizzBuzzComputationUnit.java
  - codes.som.oof4j.fizzbuzz.enterprise.computation.unit.FizzBuzzComputationUnitLookupTableEntry.java
  - codes.som.oof4j.fizzbuzz.enterprise.computation.unit.FizzBuzzRuleApplicator.java
  - codes.som.oof4j.fizzbuzz.enterprise.computation.unit.Flags.java
  - codes.som.oof4j.fizzbuzz.enterprise.EnterpriseFizzBuzzCommandLineResultSubscriber.java
  - codes.som.oof4j.fizzbuzz.enterprise.EnterpriseFizzBuzzExecutionEnvironment.java
  - codes.som.oof4j.fizzbuzz.enterprise.results.internal.AbstractFizzBuzzResultPublisherImpl.java
  - codes.som.oof4j.fizzbuzz.enterprise.results.internal.FizzBuzzResultImpl.java
  - dev.sim0n.app.Application.java
  - dev.sim0n.app.Main.java
  - dev.sim0n.app.test.factory.PartitioningTestRepositoryFactory.java
  - dev.sim0n.app.test.factory.SimpleTestRepositoryFactory.java
  - dev.sim0n.app.test.impl.annotation.AnnotationTest.java
  - dev.sim0n.app.test.impl.crypttest.Blowfish$BlowfishCBC.java
  - dev.sim0n.app.test.impl.crypttest.Blowfish$BlowfishECB.java
  - dev.sim0n.app.test.impl.crypttest.Blowfish.java
  - dev.sim0n.app.test.impl.crypttest.BlowfishTest.java
  - dev.sim0n.app.test.impl.enumtest.EnumConstant.java
  - dev.sim0n.app.test.impl.enumtest.EnumConstantsTest.java
  - dev.sim0n.app.test.impl.evaluation.Evaluation.java
  - dev.sim0n.app.test.impl.evaluation.EvaluationTest.java
  - dev.sim0n.app.test.impl.evaluation.operation.IntMathOperation$1.java
  - dev.sim0n.app.test.impl.evaluation.operation.IntMathOperation$2.java
  - dev.sim0n.app.test.impl.evaluation.operation.IntMathOperation$3.java
  - dev.sim0n.app.test.impl.evaluation.operation.IntMathOperation$4.java
  - dev.sim0n.app.test.impl.evaluation.operation.IntMathOperation$5.java
  - dev.sim0n.app.test.impl.evaluation.operation.IntMathOperation$6.java
  - dev.sim0n.app.test.impl.evaluation.operation.IntMathOperation.java
  - dev.sim0n.app.test.impl.fizzbuzz.FizzBuzzTest.java
  - dev.sim0n.app.test.impl.flow.AES.java
  - dev.sim0n.app.test.impl.flow.OpaqueConditionTest.java
  - dev.sim0n.app.test.impl.flow.WeirdLoopTest.java
  - dev.sim0n.app.test.impl.inheritance.ClassB.java
  - dev.sim0n.app.test.impl.inheritance.InheritanceTest.java
  - dev.sim0n.app.test.impl.interfaceoverlap.InterfaceOverlap.java
  - dev.sim0n.app.test.impl.interfaceoverlap.InterfaceOverlapTest.java
  - dev.sim0n.app.test.impl.numbers.NumberComparisonTest.java
  - dev.sim0n.app.test.impl.trycatch.TryCatchTest.java
  - dev.sim0n.app.test.impl.visitor.AppVisitor.java
  - dev.sim0n.app.test.impl.visitor.VisitableApp.java
  - dev.sim0n.app.test.impl.visitor.VisitorTest.java
  - dev.sim0n.app.test.TestRepository.java
  - dev.sim0n.iridium.collection.map.ClassToInstanceMapBuilder.java
  - dev.sim0n.iridium.math.GCD.java
  - dev.sim0n.iridium.math.helper.CommonMathFunctions.java
  - dev.sim0n.iridium.math.statistic.function.AbstractStatisticFunction.java
  - dev.sim0n.iridium.math.statistic.function.impl.Entropy.java
  - dev.sim0n.iridium.math.statistic.function.impl.Kurtosis.java
  - dev.sim0n.iridium.math.statistic.function.impl.Max.java
  - dev.sim0n.iridium.math.statistic.function.impl.Mean.java
  - dev.sim0n.iridium.math.statistic.function.impl.Midpoint.java
  - dev.sim0n.iridium.math.statistic.function.impl.Min.java
  - dev.sim0n.iridium.math.statistic.function.impl.Mode.java
  - dev.sim0n.iridium.math.statistic.function.impl.Range.java
  - dev.sim0n.iridium.math.statistic.function.impl.Skewness.java
  - dev.sim0n.iridium.math.statistic.function.impl.StandardDeviation.java
  - dev.sim0n.iridium.math.statistic.function.impl.Sum.java
  - dev.sim0n.iridium.math.statistic.function.impl.Variance.java
  - dev.sim0n.iridium.math.statistic.function.StatisticFunction.java
  - dev.sim0n.iridium.math.statistic.Regression.java
  - dev.sim0n.iridium.math.statistic.regression.linear.AbstractLinearRegression.java
  - dev.sim0n.iridium.math.statistic.regression.linear.impl.LeastSquares.java
  - dev.sim0n.iridium.math.statistic.regression.RegressionResult.java
  - dev.sim0n.iridium.math.statistic.Stats.java
- - codes.som.oof4j.fizzbuzz.enterprise.computation.EnterpriseFizzBuzzComputationFactory.class
  - codes.som.oof4j.fizzbuzz.enterprise.computation.EnterpriseFizzBuzzComputationTask.class
  - codes.som.oof4j.fizzbuzz.enterprise.computation.unit.FizzBuzzComputationUnit.class
  - codes.som.oof4j.fizzbuzz.enterprise.computation.unit.FizzBuzzComputationUnitLookupTableEntry.class
  - codes.som.oof4j.fizzbuzz.enterprise.computation.unit.FizzBuzzRuleApplicator.class
  - codes.som.oof4j.fizzbuzz.enterprise.computation.unit.Flags.class
  - codes.som.oof4j.fizzbuzz.enterprise.EnterpriseFizzBuzzCommandLineResultSubscriber.class
  - codes.som.oof4j.fizzbuzz.enterprise.EnterpriseFizzBuzzExecutionEnvironment.class
  - codes.som.oof4j.fizzbuzz.enterprise.results.internal.AbstractFizzBuzzResultPublisherImpl.class
  - codes.som.oof4j.fizzbuzz.enterprise.results.internal.FizzBuzzResultImpl.class
  - dev.sim0n.app.Application.class
  - dev.sim0n.app.Main.class
  - dev.sim0n.app.test.factory.PartitioningTestRepositoryFactory.class
  - dev.sim0n.app.test.factory.SimpleTestRepositoryFactory.class
  - dev.sim0n.app.test.impl.annotation.AnnotationTest.class
  - dev.sim0n.app.test.impl.crypttest.Blowfish$BlowfishCBC.class
  - dev.sim0n.app.test.impl.crypttest.Blowfish$BlowfishECB.class
  - dev.sim0n.app.test.impl.crypttest.Blowfish.class
  - dev.sim0n.app.test.impl.crypttest.BlowfishTest.class
  - dev.sim0n.app.test.impl.enumtest.EnumConstant.class
  - dev.sim0n.app.test.impl.enumtest.EnumConstantsTest.class
  - dev.sim0n.app.test.impl.evaluation.Evaluation.class
  - dev.sim0n.app.test.impl.evaluation.EvaluationTest.class
  - dev.sim0n.app.test.impl.evaluation.operation.IntMathOperation$1.class
  - dev.sim0n.app.test.impl.evaluation.operation.IntMathOperation$2.class
  - dev.sim0n.app.test.impl.evaluation.operation.IntMathOperation$3.class
  - dev.sim0n.app.test.impl.evaluation.operation.IntMathOperation$4.class
  - dev.sim0n.app.test.impl.evaluation.operation.IntMathOperation$5.class
  - dev.sim0n.app.test.impl.evaluation.operation.IntMathOperation$6.class
  - dev.sim0n.app.test.impl.evaluation.operation.IntMathOperation.class
  - dev.sim0n.app.test.impl.fizzbuzz.FizzBuzzTest.class
  - dev.sim0n.app.test.impl.flow.AES.class
  - dev.sim0n.app.test.impl.flow.OpaqueConditionTest.class
  - dev.sim0n.app.test.impl.flow.WeirdLoopTest.class
  - dev.sim0n.app.test.impl.inheritance.ClassB.class
  - dev.sim0n.app.test.impl.inheritance.InheritanceTest.class
  - dev.sim0n.app.test.impl.interfaceoverlap.InterfaceOverlap.class
  - dev.sim0n.app.test.impl.interfaceoverlap.InterfaceOverlapTest.class
  - dev.sim0n.app.test.impl.numbers.NumberComparisonTest.class
  - dev.sim0n.app.test.impl.trycatch.TryCatchTest.class
  - dev.sim0n.app.test.impl.visitor.AppVisitor.class
  - dev.sim0n.app.test.impl.visitor.VisitableApp.class
  - dev.sim0n.app.test.impl.visitor.VisitorTest.class
  - dev.sim0n.app.test.TestRepository.class
  - dev.sim0n.iridium.collection.map.ClassToInstanceMapBuilder.class
  - dev.sim0n.iridium.math.GCD.class
  - dev.sim0n.iridium.math.helper.CommonMathFunctions.class
  - dev.sim0n.iridium.math.statistic.function.AbstractStatisticFunction.class
  - dev.sim0n.iridium.math.statistic.function.impl.Entropy.class
  - dev.sim0n.iridium.math.statistic.function.impl.Kurtosis.class
  - dev.sim0n.iridium.math.statistic.function.impl.Max.class
  - dev.sim0n.iridium.math.statistic.function.impl.Mean.class
  - dev.sim0n.iridium.math.statistic.function.impl.Midpoint.class
  - dev.sim0n.iridium.math.statistic.function.impl.Min.class
  - dev.sim0n.iridium.math.statistic.function.impl.Mode.class
  - dev.sim0n.iridium.math.statistic.function.impl.Range.class
  - dev.sim0n.iridium.math.statistic.function.impl.Skewness.class
  - dev.sim0n.iridium.math.statistic.function.impl.StandardDeviation.class
  - dev.sim0n.iridium.math.statistic.function.impl.Sum.class
  - dev.sim0n.iridium.math.statistic.function.impl.Variance.class
  - dev.sim0n.iridium.math.statistic.function.StatisticFunction.class
  - dev.sim0n.iridium.math.statistic.Regression.class
  - dev.sim0n.iridium.math.statistic.regression.linear.AbstractLinearRegression.class
  - dev.sim0n.iridium.math.statistic.regression.linear.impl.LeastSquares.class
  - dev.sim0n.iridium.math.statistic.regression.RegressionResult.class
  - dev.sim0n.iridium.math.statistic.Stats.class
- obf-test-1.0-SNAPSHOT-obf.jar
- lift_sample.py
- test_midpoint.py
.gitignore
pyproject.toml
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Static research notes and tooling for lifting the qProtect 2.0.0 Java virtualizer.

qProtect is a commercial Java obfuscator from qTechnologies. Its public product pages describe a protection stack that includes bytecode virtualization, control flow mangling, string encryption, reference encryption, number encryption, and related bytecode transforms.

Useful links:

- qProtect 2.0 product page: https://qtechnologies.dev/products/1
- qTechnologies overview: https://qtechnologies.dev/
- qProtect discord: https://qtechnologies.dev/discord

This repository focuses on the virtualizer. The sample under `samples/` is the jar used for this study. It contains qProtect runtime classes, native VM libraries, encrypted `.vm` payloads, and Java class stubs that dispatch into the VM. qProtect has continued to evolve. Real targets often combine virtualization with other transforms, while this sample isolates the virtualization module. qProtect has already updated their product!

## What Was Recovered

The virtualizer moves method bodies out of normal JVM bytecode and into encrypted VM payloads.

Before lifting:

```text
Java call site
  |
  v
stub method
  |
  v
dev.mdma.qprotect.runtime.VM.run(key, args, self)
  |
  v
native VM dispatcher
  |
  v
encrypted .vm payload
```

After lifting:

```text
encrypted .vm payload
  |
  v
decrypt and parse method records
  |
  v
decode constants and VM instructions
  |
  v
emit JVM bytecode
  |
  v
decompile recovered class
```

The included lifter rebuilds JVM bytecode for the virtualized methods in the sample. The recovered Java output is in `results/decompiled/`. The lifted class files are in `results/lifted-classes/`.

## How the VM works

The protected jar still has normal Java classes, but the method bodies are mostly replaced by launch stubs. The real work moves into a small custom instruction set that is interpreted by qProtect runtime code.

At a high level, each protected class has three pieces:

```text
protected class
  |
  +-- Java stub methods
  |
  +-- encrypted class_name.vm payload
  |
  +-- call into dev.mdma.qprotect.runtime.VM
```

The native library provides the loader and the interpreter. The Java side is mainly a bridge.

### Runtime flow

When a protected method is called, the stub does not execute the original logic. It builds a call into the VM runtime.

```text
caller
  |
  v
protected method stub
  |
  +-- push method key
  +-- pack arguments into Object[]
  +-- pass this for instance methods
  |
  v
VM.run(key, args, self)
  |
  v
native dispatcher
```

The method key selects one virtualized method from the decrypted payload. The key is a string shaped like this:

```text
fully.qualified.ClassName/randomMethodName
```

The class name selects the payload cache entry. The random method name selects a method record inside that payload.

### Loading A Payload

Each `.vm` file is encrypted on disk. During normal execution the VM runtime loads it, decrypts it, parses it, and stores the result in a native cache.

```text
class_name.vm
  |
  v
decrypt with per-class seed
  |
  v
parse method table
  |
  v
cache by class name
```

The parsed cache entry contains:

```text
method name
instruction slots
constant array
extra integer array
enabled flag
```

The important part is that the VM does not read Java bytecode. It reads its own integer instruction stream and its own constant array.

### Payload Layout

Once decrypted, the payload has a compact binary layout:

```text
u32 method_count

method record:
  u16 method_name_length
  bytes method_name
  u32 instruction_count
  u32 instruction[instruction_count]
  u32 constant_count
  constant[constant_count]
  u32 extra_count
  u32 extra[extra_count]
```

Each method record is independent. That makes lifting practical because the tool can work method by method.

### Instruction Slots

The VM instruction stream is an array of four byte slots.

```text
slot bytes:

The low byte is the VM opcode for this build. The other bytes are used for small operands. Larger operands are stored in following slots.

For example:

```text
[ opcode ]
[ opcode, constant_index ]
[ opcode, branch_target ]
[ opcode, local_slot ]
```

The interpreter keeps its own program counter. Most handlers advance to the next slot. Branch handlers replace the program counter with a target slot.

### Operand Stack And Locals

The VM behaves like a small stack machine. It has the same broad shape as JVM bytecode:

```text
locals[]       operand_stack[]
  |                  |
  +-- load_local --> +-- push value
                     |
  +-- store_local <--+-- pop value
```

This is why lifting is possible. Many VM instructions map naturally back to JVM operations:

```text
VM load local       -> JVM iload, aload, dload, ...
VM store local      -> JVM istore, astore, dstore, ...
VM invoke           -> JVM invokevirtual, invokestatic, invokespecial
VM new              -> JVM new
VM branch           -> JVM ifeq, if_icmpge, goto, ...
VM return           -> JVM ireturn, areturn, dreturn, return
```

The hard part is type recovery. The VM uses fewer instruction forms than the JVM. The lifter tracks an abstract stack so it can choose the correct typed JVM instruction when it writes bytecode back out.

### Constants

The VM constant array contains both direct values and encoded JVM references.

```text
constant
  |
  +-- int
  +-- long
  +-- float
  +-- double
  +-- descriptor
  +-- encoded reference string
```

The encoded reference strings are structured records. They describe things like:

```text
class owner
field name
field descriptor
method name
method descriptor
invoke kind
bootstrap method data
```

The lifter decodes those records and creates normal JVM constant pool entries. That step is what turns an opaque VM call into a normal Java method invocation again.

### Opcode Scrambling

The VM opcode byte values are build specific. A byte that means `new` in one protected jar may mean something else in another jar from the same product line.

```text
logical opcode index
  |
  v
scrambled byte for this build
  |
  v
handler address in native dispatcher
```

The dispatcher table in the native library maps the scrambled byte to a handler. The lifter uses the recovered handler table in `artifacts/opcode_handlers.json` and confirmed behavior from the sample to decide what each opcode family means.

The useful idea is not the numeric byte itself. The useful idea is the handler behavior.

### Branches

VM branches target instruction slot indexes. JVM branches target byte offsets. The lifter first emits bytecode with labels, then resolves those labels into byte offsets.

```text
VM branch target
  |
  v
slot index
  |
  v
JVM label
  |
  v
bytecode offset
```

This matters because JVM instructions are not all the same size. A single VM slot can become one byte, three bytes, five bytes, or a larger switch body in JVM bytecode.

### Method Reconstruction

The lifter uses the original class file as a shell:

```text
original class
  |
  +-- keep class name
  +-- keep fields
  +-- keep method descriptors
  +-- keep inheritance
  +-- replace VM stubs with lifted Code attributes
```

That avoids guessing the class shape. The tool only has to rebuild the method bodies that qProtect moved into the VM.

### Why This Works

Virtualization hides code by changing the representation. It does not remove the program.

The interpreter still needs:

```text
method selection
instruction decoding
constant decoding
stack behavior
locals behavior
branch behavior
call behavior
return behavior
```

Once those parts are identified, lifting becomes a translation problem:

```text
qProtect VM instruction stream
  |
  v
typed intermediate behavior
  |
  v
JVM bytecode
```

The result is not source code from the original project. It is rebuilt bytecode that decompilers can read again.

## Process

### 1. Identify the VM boundary

The protected classes keep small Java stubs. Those stubs load a string key and call `VM.run`. The original method body is no longer present as ordinary bytecode.

```text
class method
  |
  +-- load method key
  +-- pack arguments
  +-- call VM.run
```

The jar also carries one `.vm` file beside each virtualized class. That gave us the first split:

- `.class` files contain the public class shape and dispatch stubs
- `.vm` files contain encrypted virtualized method bodies
- native libraries contain the VM loader, decoder, and dispatcher

### 2. Recover the payload format

The native loader reads each decrypted `.vm` file as a compact binary format:

```text
u32 method_count

method:
  u16 name_length
  bytes name
  u32 instruction_count
  u32[instruction_count] instruction_slots
  u32 constant_count
  constants
  u32 extra_count
  u32[extra_count] extra
```

Each instruction slot is a four byte value. The low byte is the scrambled VM opcode. The remaining bytes carry small operands.

### 3. Recover the encryption

The payloads are encrypted with a byte stream derived from `java.util.Random`. Once the per-class seed is known, decryption is simple and fully offline.

```text
encrypted .vm
  |
  +-- seed from VM metadata
  |
  v
java.util.Random byte stream
  |
  v
plain VM method table
```

The seed list used for this sample is stored in `data/seeds.json`.

### 4. Decode constants

The VM constants are typed. Some are direct values such as integers, longs, floats, and doubles. Others are structured strings that encode JVM references.

Examples of recovered shapes:

```text
class reference
field reference
method reference
string literal
method type
invoke dynamic bootstrap data
```

This lets the lifter rebuild normal constant pool entries instead of leaving opaque VM strings behind.

### 5. Map VM opcodes back to JVM operations

qProtect shuffles opcode byte values for the build. The dispatcher table in the native library reveals the active mapping for this sample.

```text
scrambled byte
  |
  v
handler address
  |
  v
operation family
  |
  v
JVM instruction emission
```

The recovered handler summary is stored in `artifacts/opcode_handlers.json`. The lifter combines that table with confirmed opcode behavior from the sample.

### 6. Emit class files again

The lifter uses the original class as a shell. It replaces each VM dispatch stub with freshly emitted JVM bytecode, preserves the class structure, and writes a normal class file.

```text
original class shell
  |
  +-- fields
  +-- methods
  +-- descriptors
  +-- constant pool base
  |
  v
lifted method bodies installed
```

The result can be inspected with `javap` or passed to a Java decompiler.

## Running The Lifter

Lift the full sample:

```bash
python scripts/lift_sample.py
```

Lift one class:

```bash
python scripts/lift_sample.py --class-name dev.sim0n.iridium.math.statistic.function.impl.Midpoint
```

Generated files are written to `build/`:

```text
build/
  decrypted/
  lifted/
  lift_summary.json
```

## Running Tests

Install pytest if needed:

```bash
python -m pip install pytest
```

Run the test suite:

```bash
python -m pytest
```

The included test decrypts and lifts the `Midpoint` class from the sample jar, parses the lifted class file, and checks the recovered JVM instruction shape.

## Current Scope

This is not a generic Java deobfuscator. It is a focused record of the qProtect 2.0.0 virtualizer work for the included sample.

What is included:

- Static `.vm` decryption for the sample
- VM payload parsing
- Constant decoding
- Opcode family mapping
- JVM bytecode emission
- Recovered Java output

What is not included:

- Runtime instrumentation
- A deobfuscator for every qProtect transform
- Support guarantees for unrelated qProtect builds

## Responsible Use

This repository is intended for reverse engineering research, interoperability work, and defensive analysis. Use it only on software you own, have permission to study, or are otherwise allowed to inspect.

qprotect-research

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README