Use as script

Besides being used as plugins, oregami can be used also to write your own scripts!

For this, you should first install using included setup.py file. Meaning that you should call:
‘python setup.py develop’, and from then on you may use the internal classes and functions.
Note that we recommend using ‘develop’ and not ‘install’, so that if you pull a new version of oregami, it will work out of the box.

For example:
— script.py —

Scanning the usage frame

Let’s assume the following sequence of opcodes:

ROM:01000010                    e_lis     r10, 0x4004 # 0x40040000              # Load Immediate Shifted

ROM:01000014                    e_add16i  r10, r10, 0x1337 # 0x40041337         # Add Immediate

ROM:01000020                    se_mr     r30, r31                              # Move Register

ROM:01000022                    cmplw     r11, r10                              # Compare Logical Word

ROM:01000026                    se_bge    loc_1000036                           # Branch if greater than or equal

ROM:01000028

ROM:01000028    loc_1000028:                                                    # CODE XREF: sub_0100000+144↓j

ROM:01000028                    e_stmw    r30, 0(r11)                           # Store Multiple Word

ROM:0100002C                    e_add16i  r11, r11, 8                           # Add Immediate

ROM:01000030                    cmplw     r11, r10                              # Compare Logical Word

ROM:01000034                    se_blt    loc_1000028                           # Branch if less than

ROM:01000036

ROM:01000036    loc_1000036:                                                    # CODE XREF: sub_0100000+136↑j

ROM:01000036                    e_add16i r10, r10, 8                            # Add Immediate

ROM:0100003A                    e_li      r11, 0                                # Load Immediate

If we scan the usage frame of the r10 register, starting from the address 01000022, we will find three types of usages included in the usage frame.

1. Init

This will include the instructions which initialize the value of the register.
We may want to include only the last instruction that changed the register value (address 01000014 in the example), or a sequence of operations used to set the initial value of the register (addresses 01000010 and 01000014 in the example).
The sequence of operations used in the register initialization may be called an “init stage”.
You may choose to support an init stage, or not, depending on the parameter init_stage_bool in the RegFrame initialization.

2. Pure

This will include the instructions which use the value of the register, and do not change it in any way. These correspond to lines 01000022 and 01000030 in the example.

3. Break

This will include the instructions which use the value of the register, but then change it’s value. These instructions may be seen as included in two distinct usage frames – the one leading to them, and the one originating from them.
This corresponds to line 01000036.

4. Out Break

When scanning the usage register, getting to an init operation, or a break operation will cause us to stop scanning in a certain direction.
But, we may also stop the scan because of instructions outside the usage frame. For example, scanning the usage frame of the r11 register starting from the address 01000030 will stop on line 0100003A.

Classes and Functions

RegFrame

This is the basic class used in oregami. By initializing it on an address and specific register, it will scan the usage frame of the register, and will create an UFIntruction for all the relevant instructions.
get_instruction – get the instruction from the given address
get_instructions – a generator, returning the instructions in the usage frame.

You may also ask for specific subsets of the used instructions:
get_init_instructions – get only instructions of the init type
get_pure_instructions – get only instructions of the pure type
get_break_instructions – get only instructions of the break type
get_nobreak_instructions – get only instructions which are not of the break type (ie. init + pure)
get_noinit_instructions – get only instructions which are not of the init type (ie. pure + break)
get_outbreak_instructions – get only instructions of the out break type

By default this class will cache the results of the scan, and prevent itself from rescanning the same usage frame. This means that requesting the RegFrame of any instruction that was a part of the usage frame (specifically of the init + pure types. Not breaks, because starting a scan on them should return the usage frame originating from them) will return the same pre-calculated RegFrame instance. In order to force a rescan, use the force flag when initializing the class.

RFInstruction

This is the class returned by the RegFrame, representing an instruction in the usage frame.

This class inherits from the sark Instruction class, and as such supports the same methods.
One main difference is that instead of containing an operands array of sark Operand class, it will contain an array of UFOperand class.

This class also contains methods to understand the instruction type (init, pure, break, outbreak), and the operations bits (read, write, explicit, and different types of implicit)

RFOperand

This is the class in the operands array inside a specific UFInstruction.

This class inherits from the sark Instruction class, and as such supports the same methods.

In additions to the sark operations, it contains methods to get the operation bits (read, write, explicit, and different types of implicit), and to know if the operand is actually part of the usage frame (useful to know which operand in a break type instruction is part of the usage frame)

RegInstruction

This is a class used to analyze a specific instruction, to know it’s usage regarding registers.
It does so using knowledge from IDA, textual analysis, and specific details specific to the processor. The reason for this class, is that the basic IDA analysis tends to lie about the set of the registers used, the way they are used in many opcodes.

This class inherits from the sark Instruction class, and as such supports the same methods.
One main difference is that instead of containing an operands array of sark Operand class, it will contain an array of RegOperand class.

RegOperand

This is a class used to analyze a specific operand, to know it’s usage regarding registers.
It does so using knowledge from IDA, textual analysis, and specific details specific to the processor. The reason for this class, is that the basic IDA analysis tends to lie about the set of the registers used, the way they are used in many opcodes.

This class inherits from the sark Operand class, and as such supports the same methods.

Install

Copyright (c) 2020 Matan Ziv