├── LICENSE ├── README.md └── referee.py /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright 2011 James Koppel 190 | Modifications copyright 2015 Joseph Leong 191 | 192 | Licensed under the Apache License, Version 2.0 (the "License"); 193 | you may not use this file except in compliance with the License. 194 | You may obtain a copy of the License at 195 | 196 | http://www.apache.org/licenses/LICENSE-2.0 197 | 198 | Unless required by applicable law or agreed to in writing, software 199 | distributed under the License is distributed on an "AS IS" BASIS, 200 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 201 | See the License for the specific language governing permissions and 202 | limitations under the License. 203 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Referee 2 | 3 | This is a python port of James Koppel's Referee IDA plugin with some updates: 4 | https://github.com/jkoppel/project-ironfist/tree/master/tools/Revitalize/Referee 5 | 6 | 7 | ## What it is 8 | 9 | It's much easier to reverse-engineer a structure when you can find every place its members are used. If you wish to reengineer the binary and modify a structure, finding every use is essential. Referee makes both of these tasks easier by marking accesses of structures in decompiled functions. 10 | 11 | ## Requirements 12 | 13 | * IDA 7.0 or higher 14 | * Hex-Rays Decompiler 1.6 or higher 15 | 16 | ## Installation 17 | 18 | Copy the plugin into the IDA "plugins" folder 19 | 20 | ## Usage 21 | 22 | Referee will automatically run whenever a function is decompiled. It is recommended that you decompile the entire binary for maximum information. This can be done by going to `File > Produce file > Create C file...` and letting it complete. You can see the cross-references that Referee adds by opening a structure in the Structures window, highlighting a field of a structure, and pressing "X." 23 | 24 | Referee does not do type inference; you will still need to give types to your functions for it to find structure uses. 25 | 26 | ## Notes 27 | 28 | * If you annotate a function to remove a struct-member usage, decompiling the function again will remove the corresponding xrefs. 29 | * Referee only tracks accesses to structure members, not pointer-passing. 30 | * Configuring debug output: `logging.getLogger('referee').setLevel(logging.DEBUG)` 31 | 32 | ## Related 33 | - http://reverseengineering.stackexchange.com/questions/2139/is-it-possible-to-create-data-xrefs-manually 34 | -------------------------------------------------------------------------------- /referee.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | """ 3 | Referee creates struct xrefs for decompiled functions 4 | """ 5 | import logging 6 | import traceback 7 | 8 | import idaapi 9 | 10 | logging.basicConfig(level=logging.WARN) 11 | log = logging.getLogger("referee") 12 | 13 | 14 | NETNODE_NAME = '$ referee-xrefs' 15 | NETNODE_TAG = 'X' 16 | 17 | 18 | def is_assn(t): 19 | return ( 20 | t == idaapi.cot_asg or 21 | t == idaapi.cot_asgbor or 22 | t == idaapi.cot_asgxor or 23 | t == idaapi.cot_asgband or 24 | t == idaapi.cot_asgsub or 25 | t == idaapi.cot_asgmul or 26 | t == idaapi.cot_asgsshr or 27 | t == idaapi.cot_asgushr or 28 | t == idaapi.cot_asgsdiv or 29 | t == idaapi.cot_asgudiv or 30 | t == idaapi.cot_asgsmod or 31 | t == idaapi.cot_asgumod) 32 | 33 | 34 | def is_incdec(t): 35 | return ( 36 | t == idaapi.cot_postinc or # = 53, ///< x++ 37 | t == idaapi.cot_postdec or # = 54, ///< x-- 38 | t == idaapi.cot_preinc or # = 55, ///< ++x 39 | t == idaapi.cot_predec) # = 56, ///< --x 40 | 41 | 42 | def add_struct_xrefs(cfunc): 43 | class xref_adder_t(idaapi.ctree_visitor_t): 44 | def __init__(self, cfunc): 45 | idaapi.ctree_visitor_t.__init__(self, idaapi.CV_PARENTS) 46 | self.cfunc = cfunc 47 | self.node = idaapi.netnode() 48 | self.clear_struct_xrefs() 49 | self.xrefs = {} 50 | 51 | def load(self): 52 | try: 53 | data = self.node.getblob_ea(self.cfunc.entry_ea, NETNODE_TAG) 54 | if data: 55 | xrefs = eval(data) 56 | log.debug('Loaded {} xrefs'.format(len(xrefs))) 57 | return xrefs 58 | except: 59 | log.error('Failed to load xrefs from netnode') 60 | traceback.print_exc() 61 | return {} 62 | 63 | def save(self): 64 | try: 65 | self.node.setblob_ea(repr(self.xrefs).encode(), 66 | self.cfunc.entry_ea, 67 | NETNODE_TAG) 68 | except: 69 | log.error('Failed to save xrefs to netnode') 70 | traceback.print_exc() 71 | 72 | def clear_struct_xrefs(self): 73 | if not self.node.create(NETNODE_NAME): 74 | xrefs = self.load() 75 | for (ea, struct_id, member_id) in xrefs.keys(): 76 | if member_id is None: 77 | idaapi.del_dref(ea, struct_id) 78 | else: 79 | idaapi.del_dref(ea, member_id) 80 | self.xrefs = {} 81 | self.save() 82 | log.debug('Cleared {} xrefs'.format(len(xrefs))) 83 | 84 | def find_addr(self, e): 85 | if e.ea != idaapi.BADADDR: 86 | ea = e.ea 87 | else: 88 | while True: 89 | e = self.cfunc.body.find_parent_of(e) 90 | if e is None: 91 | ea = self.cfunc.entry_ea 92 | break 93 | if e.ea != idaapi.BADADDR: 94 | ea = e.ea 95 | break 96 | return ea 97 | 98 | def add_dref(self, ea, struct_id, flags, member_id=None): 99 | if ((ea, struct_id, member_id) not in self.xrefs or 100 | flags < self.xrefs[(ea, struct_id, member_id)]): 101 | self.xrefs[(ea, struct_id, member_id)] = flags 102 | strname = idaapi.get_struc_name(struct_id) 103 | if member_id is None: 104 | idaapi.add_dref(ea, struct_id, flags) 105 | log.debug((" 0x{:X} \t" 106 | "struct {} \t" 107 | "{}").format( 108 | ea, strname, flags_to_str(flags))) 109 | else: 110 | idaapi.add_dref(ea, member_id, flags) 111 | log.debug((" 0x{:X} \t" 112 | "member {}.{} \t" 113 | "{}").format( 114 | ea, strname, 115 | idaapi.get_member_name(member_id), 116 | flags_to_str(flags))) 117 | self.save() 118 | 119 | def visit_expr(self, e): 120 | dr = idaapi.dr_R | idaapi.XREF_USER 121 | ea = self.find_addr(e) 122 | 123 | # We wish to know what context a struct usage occurs in 124 | # so we can determine what kind of xref to create. Unfortunately, 125 | # a post-order traversal makes this difficult. 126 | 127 | # For assignments, we visit the left, instead 128 | # Note that immediate lvalues will be visited twice, 129 | # and will be eronneously marked with a read dref. 130 | # However, it is safer to overapproximate than underapproximate 131 | if is_assn(e.op) or is_incdec(e.op): 132 | e = e.x 133 | dr = idaapi.dr_W | idaapi.XREF_USER 134 | 135 | # &x 136 | if e.op == idaapi.cot_ref: 137 | e = e.x 138 | dr = idaapi.dr_O | idaapi.XREF_USER 139 | 140 | # x.m, x->m 141 | if (e.op == idaapi.cot_memref or e.op == idaapi.cot_memptr): 142 | moff = e.m 143 | 144 | # The only way I could figure out how 145 | # to get the structure/member associated with its use 146 | typ = e.x.type 147 | 148 | if e.op == idaapi.cot_memptr: 149 | typ.remove_ptr_or_array() 150 | 151 | strname = typ.dstr() 152 | if strname.startswith("struct "): 153 | strname = strname[len("struct "):] 154 | if strname.startswith("const "): 155 | strname = strname[len("const "):] 156 | 157 | stid = idaapi.get_struc_id(strname) 158 | struc = idaapi.get_struc(stid) 159 | mem = idaapi.get_member(struc, moff) 160 | 161 | if struc is not None: 162 | self.add_dref(ea, stid, dr) 163 | if mem is not None: 164 | self.add_dref(ea, stid, dr, mem.id) 165 | 166 | else: 167 | log.error(("failure from 0x{:X} " 168 | "on struct {} (id: 0x{:X}) {}").format( 169 | ea, strname, stid, flags_to_str(dr))) 170 | 171 | elif idaapi.is_lvalue(e.op) and e.type.is_struct(): 172 | strname = e.type.dstr() 173 | if strname.startswith("struct "): 174 | strname = strname[len("struct "):] 175 | if strname.startswith("const "): 176 | strname = strname[len("const "):] 177 | 178 | stid = idaapi.get_struc_id(strname) 179 | struc = idaapi.get_struc(stid) 180 | 181 | if struc is not None: 182 | self.add_dref(ea, stid, dr) 183 | 184 | return 0 185 | 186 | adder = xref_adder_t(cfunc) 187 | adder.apply_to_exprs(cfunc.body, None) 188 | 189 | 190 | def callback(*args): 191 | if args[0] == idaapi.hxe_maturity: 192 | cfunc = args[1] 193 | mat = args[2] 194 | if mat == idaapi.CMAT_FINAL: 195 | log.debug("analyzing function at 0x{:X}".format( 196 | cfunc.entry_ea)) 197 | add_struct_xrefs(cfunc) 198 | return 0 199 | 200 | 201 | class Referee(idaapi.plugin_t): 202 | flags = idaapi.PLUGIN_HIDE 203 | comment = "Adds struct xref info from decompilation" 204 | help = "" 205 | 206 | wanted_name = "Referee" 207 | wanted_hotkey = "" 208 | 209 | def init(self): 210 | if not idaapi.init_hexrays_plugin(): 211 | return idaapi.PLUGIN_SKIP 212 | 213 | idaapi.install_hexrays_callback(callback) 214 | log.info(("Hex-Rays version {} has been detected; " 215 | "{} is ready to use").format( 216 | idaapi.get_hexrays_version(), self.wanted_name)) 217 | self.inited = True 218 | return idaapi.PLUGIN_KEEP 219 | 220 | def run(self, arg): 221 | # never called 222 | pass 223 | 224 | def term(self): 225 | if self.inited: 226 | idaapi.remove_hexrays_callback(callback) 227 | idaapi.term_hexrays_plugin() 228 | 229 | 230 | def PLUGIN_ENTRY(): 231 | return Referee() 232 | 233 | 234 | def flags_to_str(num): 235 | match = [] 236 | if num & idaapi.dr_R == idaapi.dr_R: 237 | match.append('dr_R') 238 | num ^= idaapi.dr_R 239 | if num & idaapi.dr_O == idaapi.dr_O: 240 | match.append('dr_O') 241 | num ^= idaapi.dr_O 242 | if num & idaapi.dr_W == idaapi.dr_W: 243 | match.append('dr_W') 244 | num ^= idaapi.dr_W 245 | if num & idaapi.dr_I == idaapi.dr_I: 246 | match.append('dr_I') 247 | num ^= idaapi.dr_I 248 | if num & idaapi.dr_T == idaapi.dr_T: 249 | match.append('dr_T') 250 | num ^= idaapi.dr_T 251 | if num & idaapi.XREF_USER == idaapi.XREF_USER: 252 | match.append('XREF_USER') 253 | num ^= idaapi.XREF_USER 254 | if num & idaapi.XREF_DATA == idaapi.XREF_DATA: 255 | match.append('XREF_DATA') 256 | num ^= idaapi.XREF_DATA 257 | res = ' | '.join(match) 258 | if num: 259 | res += ' unknown: 0x{:X}'.format(num) 260 | return res 261 | 262 | 263 | def clear_output_window(): 264 | idaapi.process_ui_action('msglist:Clear') 265 | --------------------------------------------------------------------------------