IDAEye - Documentation
[ IDAEye v0.4 - FalconHeavy Build:100318]
[ An IDA Pro Plugin ]
< All Rights Reserved (C) 2014-2018 >
[ An IDA Pro Plugin ]
< All Rights Reserved (C) 2014-2018 >
is an IDA Pro plugin that enables you to perform different operations at the mnemonic level, independent of any particular processor type. These operations are facilitated through a parameterized template, which include the capabilities to de/highlight instructions, gather statistical information about the frequency of each instruction, and search for sequences of mnemonics with support for wildcard, among other features.
IDAEye
[ IDAEye Advantages ]
A. Verbose templates that can be shared among researchers
B. Support for both IDA 32-bit & 64-bit address spaces
C. Self Documenting features
B. Support for both IDA 32-bit & 64-bit address spaces
C. Self Documenting features
[ Installation ]
1. Copy "\IDAEye\32-Bit\IDAEye.dll" to "\IDA\plugins"
2. Copy "\IDAEye\64-Bit\IDAEye64.dll" to "\IDA\plugins"
3. Copy "\IDAEye\Template\IDAEye.iet" to "\IDA\plugins"
Then, add the following 10 lines to "\IDA\plugins\plugins.cfg" config. file:
IDAEye:_HLP->_Current_Function IDAEye Ctrl-Alt-F 1
IDAEye:_HLP->_Selected_Area IDAEye Ctrl-Alt-S 2
IDAEye:_HLP->_Whole_Program IDAEye Ctrl-Alt-W 3
IDAEye:_FSP->_Current_Function IDAEye Ctrl-Shift-F 4
IDAEye:_FSP->_Selected_Area IDAEye Ctrl-Shift-S 5
IDAEye:_FSP->_Whole_Program IDAEye Ctrl-Shift-W 6
IDAEye:_FSP->_Auto-Generate IDAEye Ctrl+Shift+A 7
IDAEye:_MnemStat->_Current_Function IDAEye Alt-F 9
IDAEye:_MnemStat->_Selected_Area IDAEye Alt-Z 10
IDAEye:_MnemStat->_Whole_Program IDAEye Alt-W 11
These are IDAEye's menu items to control it. In addition to these 10 items, a menu item with the name "IDAEye: Quantum", Hotkey: Ctrl+H, is added programmatically.
To test if the plugin is loaded correctly after performing above operations, you should see the message "+ IDAEye v0.4 - FalconHeavy Build:100318 - 2018 (C) - Mohamad F. Mokbel" in IDA's Output window. This message appears after opening a file to disassemble. Moreover, it should appear once more after calling any of IDAEye's menu items.
Note: This version of IDAEye was compiled against IDA SDK v7.0, and thus works only with IDA Pro v7.0 and up. IDAEye builds are available for Windows only.
2. Copy "\IDAEye\64-Bit\IDAEye64.dll" to "\IDA\plugins"
3. Copy "\IDAEye\Template\IDAEye.iet" to "\IDA\plugins"
Then, add the following 10 lines to "\IDA\plugins\plugins.cfg" config. file:
IDAEye:_HLP->_Current_Function IDAEye Ctrl-Alt-F 1
IDAEye:_HLP->_Selected_Area IDAEye Ctrl-Alt-S 2
IDAEye:_HLP->_Whole_Program IDAEye Ctrl-Alt-W 3
IDAEye:_FSP->_Current_Function IDAEye Ctrl-Shift-F 4
IDAEye:_FSP->_Selected_Area IDAEye Ctrl-Shift-S 5
IDAEye:_FSP->_Whole_Program IDAEye Ctrl-Shift-W 6
IDAEye:_FSP->_Auto-Generate IDAEye Ctrl+Shift+A 7
IDAEye:_MnemStat->_Current_Function IDAEye Alt-F 9
IDAEye:_MnemStat->_Selected_Area IDAEye Alt-Z 10
IDAEye:_MnemStat->_Whole_Program IDAEye Alt-W 11
These are IDAEye's menu items to control it. In addition to these 10 items, a menu item with the name "IDAEye: Quantum", Hotkey: Ctrl+H, is added programmatically.
To test if the plugin is loaded correctly after performing above operations, you should see the message "+ IDAEye v0.4 - FalconHeavy Build:100318 - 2018 (C) - Mohamad F. Mokbel" in IDA's Output window. This message appears after opening a file to disassemble. Moreover, it should appear once more after calling any of IDAEye's menu items.
Note: This version of IDAEye was compiled against IDA SDK v7.0, and thus works only with IDA Pro v7.0 and up. IDAEye builds are available for Windows only.
[ Template File Description ]
The template file is the core component of IDAEye. It provides all the necessary elements to interact with the plugin. It supports two instruction patterns.
I. The first instruction pattern deals with de/highlighting, and gathering of
statistical information about a given instruction mnemonic in the disassembly
list. These operations are controlled via the <Option(s)> selector.
INST = [<Mnemonic>:$:<Color in BGR/Hexadecimal>:$:<Option(s)>];
A. " INST = [", opening delimiter for the instruction pattern (note the space at
the beginning)
B. "];", closing delimiter for the instruction pattern; 'anything' can be added
after the closing delimiter (for example, a comment)
C. ":$:", elements separator
D. Each instruction pattern has to start on a new line, with zero or more spaces
and tabs, at the beginning of the line, before and after th equal operator.
E. This instruction pattern is known as HighLight Pattern (HLP)
Following is a description of each element:
1. <Mnemonic>, takes any mnemonic string between 1 and 32 characters. Case
sensitivity is IDA disassembly list dependant.
2. <Color in BGR/Hexadecimal>, the color chosen to de/highlight the instruction
that matches the <mnemonic> in the instruction
pattern. It is a hexadecimal value, in BGR mode.
Format: [0-9a-fA-F]{6}
3. <Option(s)>, instructs the plugin to perform any of the following actions:
I. The first instruction pattern deals with de/highlighting, and gathering of
statistical information about a given instruction mnemonic in the disassembly
list. These operations are controlled via the <Option(s)> selector.
INST = [<Mnemonic>:$:<Color in BGR/Hexadecimal>:$:<Option(s)>];
A. " INST = [", opening delimiter for the instruction pattern (note the space at
the beginning)
B. "];", closing delimiter for the instruction pattern; 'anything' can be added
after the closing delimiter (for example, a comment)
C. ":$:", elements separator
D. Each instruction pattern has to start on a new line, with zero or more spaces
and tabs, at the beginning of the line, before and after th equal operator.
E. This instruction pattern is known as HighLight Pattern (HLP)
Following is a description of each element:
1. <Mnemonic>, takes any mnemonic string between 1 and 32 characters. Case
sensitivity is IDA disassembly list dependant.
2. <Color in BGR/Hexadecimal>, the color chosen to de/highlight the instruction
that matches the <mnemonic> in the instruction
pattern. It is a hexadecimal value, in BGR mode.
Format: [0-9a-fA-F]{6}
3. <Option(s)>, instructs the plugin to perform any of the following actions:
OPTION values [0-4] can be combined together, separated with the delimiter ":".
Statistical information is displayed in the Output window.
The following is an example of how this instruction pattern can be used:
INST = [xor:$:66cc00:$:0:2:3:4];
This instruction pattern searches (search boundary is defined by the chosen menu item) IDA disassembly list for instructions with the mnemonic "xor", and if it is already colored with "66cc00" (green), it de-highlights it (OPTION 0), then it displays the number of time(s) this mnemonic/instruction was found, and the address(es) where it is found (OPTION 2). After that, it highlights only "xor" instructions that have different operands (OPTION 3). And finally, it displays the number of time(s) this mnemonic/instruction of different operands was found, and the address(es) where it is found (OPTION 4).
II. The second instruction pattern is responsible for searching (in linear mode) for sequence of mnemonics, and reporting the address(es) where each sequence is found. Results are displayed in the Output window.
INSTS = [:$:<Mnemonic>
:$:<Mnemonic>
:$:<Mnemonic>
:$:<More Mnemonics>
];
A. This instruction pattern has similar format characteristics to the first one
detailed above. Mnemonics can be written on one line or divided, such that
each mnemonic is placed on a new line (as shown above). Each mnemonic has to
starts with the delimiter ":$:".
B. Number of mnemonics is limited by the number of instructions in the
disassembly list, duh!
C. The search algorithm crosses the boundaries between functions (prologue and
epilogue). Moreover, it skips non-code defined instructions
D. Minimum of two mnemonics have to be put in this instruction pattern.
E. This instruction pattern is known as Find Sequence Pattern (FSP)
The following is an example of how this instruction pattern can be used:
INSTS = [:$:nop:$:call:$:ldarg.0:$:callvirt:$:nop:$:nop:$:ret];
Or, it can be written as follows:
INSTS = [:$:nop
:$:call
:$:ldarg.0
:$:callvirt
:$:nop
:$:nop
:$:ret
];
This instruction pattern searches for sequence(s) of 7 .Net assembly mnemonics.
An example of the output is as follows:
+ Number of FSP patterns: 1
+ 0[1] = { 0x000021 };
First line reports how many Find Sequence Patterns (FSP) are in the template file. The second line, reports the number of the sequence pattern in the template file, followed by how many times this sequence was found between brackets, and then the address(es) where each sequence is found.
IDAEye also provides the option to auto-generate such pattern. This is accomplished via the menu item IDAEye: FSP-> Auto-Generate. This option works by selecting a set of instructions, and calling said menu item. The results are display to the Output window, which contains the auto-generated FSP pattern and the address(es) of any matching sequence found for the whole program.
[ The SKIP(<x>) Keyword ]
The SKIP keyword provides a parametrized wildcard search to the INSTS FSP. IDAEye interprets the SKIP keyword differently, depending on its location in the INSTS FSP.
SKIP keyword syntax: case-sensitive (upper-case), followed by the opening parenthesis "(", an integer value, and the closing parenthesis ")".
The SKIP keyword takes an argument of integer type that dictates how many code or non-code defined instructions to ignore/skip. The SKIP argument takes a value between 0 and total number of code and non-code defined instructions.
For example,
INSTS = [:$:SKIP(10):$:xor:$:SKIP(1):$:SKIP(1):$:mov:$:SKIP(4):$:cmp:$:SKIP(5)];
Note the following key points:
1. Successive SKIP keywords are associative. You can have multiple consecutive SKIP keywords without incurring any additional performance impact. This is because IDAEye coalesces/optimizes such sequences into one. For example, in the sequence shown above, the parser will generate the following optimized INSTS FSP before executing it:
INSTS = [:$:SKIP(10):$:xor:$:SKIP(2):$:mov:$:SKIP(4):$:cmp:$:SKIP(5)];
They are both semantically equivalent.
2. An INSTS FSP that consists of SKIP keywords only is not allowed and will be rejected by IDAEye with a descriptive message printed to the message window.
3. A SKIP keyword with a value of 0 is allowed, as in SKIP(0). This will be ignored, however allowing it is for readability/convenience purpose, used as a placeholder.
4. A SKIP keyword at the beginning of the INSTS FSP is interpreted as an offset from the previous address reference. This is expensive in terms of performance, and it is not recommended. Each skipped valid address is validated as a code instruction, otherwise, it fails.
5. A SKIP keyword between mnemonics validates each valid address as code instruction, otherwise, it fails.
6. A SKIP keyword at the end of the INSTS FSP validates each valid address as either code or non-code defined instruction.
---------------------------------------------------------------------------------
[ Template file "IDAEye.iet" notes ]
Note that following opening and closing delimiters have to always exist in the Template file (in this order):
<BEGIN PROCESS INSTRUCTIONS>
<END PROCESS INSTRUCTIONS>
[ How to invoke the Template file ]
A. To invoke the HLP instruction pattern(s), use either of the following menu
items from the plugin menu:
IDAEye: HLP-> Current Function
IDAEye: HLP-> Selected Area
IDAEye: HLP-> Whole Program
B. To invoke the FSP instruction pattern(s), use either of the following menu
items from the plugin menu:
IDAEye: FSP-> Current Function
IDAEye: FSP-> Selected Area
IDAEye: FSP-> Whole Program
_________________________________________________________________________________
[ IDAEye: Mnemonics Statistics ]
---------------------------------------------------------------------------------
This feature generates a table that shows the frequency of each mnemonic in the disassembly list. This is also processor independent. Generated table is displayed in IDA's Output window.
For example, the output looks like (always in descending order):
[Mnemonic] [Frequency] [Percentage]
---------- ----------- ------------
T: 8 T: 12 T: 100%
---------- ----------- ------------
mov 5 41.6667
xor 1 8.3333
scas 1 8.3333
not 1 8.3333
lea 1 8.3333
jbe 1 8.3333
cmp 1 8.3333
cld 1 8.3333
To invoke this feature, use either of the following menu items from the plugin menu:
IDAEye: MnemStat-> Current Function
IDAEye: MnemStat-> Selected Area
IDAEye: MnemStat-> Whole Program
_________________________________________________________________________________
[ IDAEye: Things To Note ]
---------------------------------------------------------------------------------
Note that every time any of the HLP and FSP menu items is selected, IDAEye reads the Template file and performs requested operations. Nothing is saved to currently open IDB file. This is a design decision.
Regarding the Whole Program selection, IDAEye takes the min_ea and max_ea from IDA "inf" structure.
_________________________________________________________________________________
[ IDAEye: Quantum Menu Item ]
---------------------------------------------------------------------------------
This menu item option allows you to de-highlight and highlight the instruction at the current cursor position. Highlight color is set internally to 0xfffae6 (very light blue). It can be invoked via the hotkey Ctrl+H.
_________________________________________________________________________________
[ Comments | Questions ]
---------------------------------------------------------------------------------
Please feel free to send your comments, or any questions you may have my way.
Moreover, I'd like to receive your IDAEye Templates.
=================================================================================
END OF DOCUMENTATION
=================================================================================
Statistical information is displayed in the Output window.
The following is an example of how this instruction pattern can be used:
INST = [xor:$:66cc00:$:0:2:3:4];
This instruction pattern searches (search boundary is defined by the chosen menu item) IDA disassembly list for instructions with the mnemonic "xor", and if it is already colored with "66cc00" (green), it de-highlights it (OPTION 0), then it displays the number of time(s) this mnemonic/instruction was found, and the address(es) where it is found (OPTION 2). After that, it highlights only "xor" instructions that have different operands (OPTION 3). And finally, it displays the number of time(s) this mnemonic/instruction of different operands was found, and the address(es) where it is found (OPTION 4).
II. The second instruction pattern is responsible for searching (in linear mode) for sequence of mnemonics, and reporting the address(es) where each sequence is found. Results are displayed in the Output window.
INSTS = [:$:<Mnemonic>
:$:<Mnemonic>
:$:<Mnemonic>
:$:<More Mnemonics>
];
A. This instruction pattern has similar format characteristics to the first one
detailed above. Mnemonics can be written on one line or divided, such that
each mnemonic is placed on a new line (as shown above). Each mnemonic has to
starts with the delimiter ":$:".
B. Number of mnemonics is limited by the number of instructions in the
disassembly list, duh!
C. The search algorithm crosses the boundaries between functions (prologue and
epilogue). Moreover, it skips non-code defined instructions
D. Minimum of two mnemonics have to be put in this instruction pattern.
E. This instruction pattern is known as Find Sequence Pattern (FSP)
The following is an example of how this instruction pattern can be used:
INSTS = [:$:nop:$:call:$:ldarg.0:$:callvirt:$:nop:$:nop:$:ret];
Or, it can be written as follows:
INSTS = [:$:nop
:$:call
:$:ldarg.0
:$:callvirt
:$:nop
:$:nop
:$:ret
];
This instruction pattern searches for sequence(s) of 7 .Net assembly mnemonics.
An example of the output is as follows:
+ Number of FSP patterns: 1
+ 0[1] = { 0x000021 };
First line reports how many Find Sequence Patterns (FSP) are in the template file. The second line, reports the number of the sequence pattern in the template file, followed by how many times this sequence was found between brackets, and then the address(es) where each sequence is found.
IDAEye also provides the option to auto-generate such pattern. This is accomplished via the menu item IDAEye: FSP-> Auto-Generate. This option works by selecting a set of instructions, and calling said menu item. The results are display to the Output window, which contains the auto-generated FSP pattern and the address(es) of any matching sequence found for the whole program.
[ The SKIP(<x>) Keyword ]
The SKIP keyword provides a parametrized wildcard search to the INSTS FSP. IDAEye interprets the SKIP keyword differently, depending on its location in the INSTS FSP.
SKIP keyword syntax: case-sensitive (upper-case), followed by the opening parenthesis "(", an integer value, and the closing parenthesis ")".
The SKIP keyword takes an argument of integer type that dictates how many code or non-code defined instructions to ignore/skip. The SKIP argument takes a value between 0 and total number of code and non-code defined instructions.
For example,
INSTS = [:$:SKIP(10):$:xor:$:SKIP(1):$:SKIP(1):$:mov:$:SKIP(4):$:cmp:$:SKIP(5)];
Note the following key points:
1. Successive SKIP keywords are associative. You can have multiple consecutive SKIP keywords without incurring any additional performance impact. This is because IDAEye coalesces/optimizes such sequences into one. For example, in the sequence shown above, the parser will generate the following optimized INSTS FSP before executing it:
INSTS = [:$:SKIP(10):$:xor:$:SKIP(2):$:mov:$:SKIP(4):$:cmp:$:SKIP(5)];
They are both semantically equivalent.
2. An INSTS FSP that consists of SKIP keywords only is not allowed and will be rejected by IDAEye with a descriptive message printed to the message window.
3. A SKIP keyword with a value of 0 is allowed, as in SKIP(0). This will be ignored, however allowing it is for readability/convenience purpose, used as a placeholder.
4. A SKIP keyword at the beginning of the INSTS FSP is interpreted as an offset from the previous address reference. This is expensive in terms of performance, and it is not recommended. Each skipped valid address is validated as a code instruction, otherwise, it fails.
5. A SKIP keyword between mnemonics validates each valid address as code instruction, otherwise, it fails.
6. A SKIP keyword at the end of the INSTS FSP validates each valid address as either code or non-code defined instruction.
---------------------------------------------------------------------------------
[ Template file "IDAEye.iet" notes ]
Note that following opening and closing delimiters have to always exist in the Template file (in this order):
<BEGIN PROCESS INSTRUCTIONS>
<END PROCESS INSTRUCTIONS>
[ How to invoke the Template file ]
A. To invoke the HLP instruction pattern(s), use either of the following menu
items from the plugin menu:
IDAEye: HLP-> Current Function
IDAEye: HLP-> Selected Area
IDAEye: HLP-> Whole Program
B. To invoke the FSP instruction pattern(s), use either of the following menu
items from the plugin menu:
IDAEye: FSP-> Current Function
IDAEye: FSP-> Selected Area
IDAEye: FSP-> Whole Program
_________________________________________________________________________________
[ IDAEye: Mnemonics Statistics ]
---------------------------------------------------------------------------------
This feature generates a table that shows the frequency of each mnemonic in the disassembly list. This is also processor independent. Generated table is displayed in IDA's Output window.
For example, the output looks like (always in descending order):
[Mnemonic] [Frequency] [Percentage]
---------- ----------- ------------
T: 8 T: 12 T: 100%
---------- ----------- ------------
mov 5 41.6667
xor 1 8.3333
scas 1 8.3333
not 1 8.3333
lea 1 8.3333
jbe 1 8.3333
cmp 1 8.3333
cld 1 8.3333
To invoke this feature, use either of the following menu items from the plugin menu:
IDAEye: MnemStat-> Current Function
IDAEye: MnemStat-> Selected Area
IDAEye: MnemStat-> Whole Program
_________________________________________________________________________________
[ IDAEye: Things To Note ]
---------------------------------------------------------------------------------
Note that every time any of the HLP and FSP menu items is selected, IDAEye reads the Template file and performs requested operations. Nothing is saved to currently open IDB file. This is a design decision.
Regarding the Whole Program selection, IDAEye takes the min_ea and max_ea from IDA "inf" structure.
_________________________________________________________________________________
[ IDAEye: Quantum Menu Item ]
---------------------------------------------------------------------------------
This menu item option allows you to de-highlight and highlight the instruction at the current cursor position. Highlight color is set internally to 0xfffae6 (very light blue). It can be invoked via the hotkey Ctrl+H.
_________________________________________________________________________________
[ Comments | Questions ]
---------------------------------------------------------------------------------
Please feel free to send your comments, or any questions you may have my way.
Moreover, I'd like to receive your IDAEye Templates.
=================================================================================
END OF DOCUMENTATION
=================================================================================
| OPTION | DESCRIPTION |
| 0 | De-highlights instruction(s) with the matching color in the pattern |
| 1 | Highlights instruction(s) with the chosen color in the pattern |
| 2 | Displays the number of time(s) this mnemonic was found, and the address(es) where it is found (in an array like format) |
| 3 | Highlights instruction(s) of different operands only with the chosen color. (Compares only the first 2 operands) |
| 4 | Same as "2", but for instruction(s) with different operands |