fa 0.1__tar.gz

fa-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 1.2
+Name: fa
+Version: 0.1.0
+Summary: FA Plugin
+Home-page: https://github.com/doronz88/fa
+Author: DoronZ
+Author-email: doron88@gmail.com
+License: UNKNOWN
+Description: UNKNOWN
+Platform: UNKNOWN
+Requires-Python: >=2.7

fa-0.1.0/README.md

@@ -0,0 +1,418 @@
+![Python application](https://github.com/doronz88/fa/workflows/Python%20application/badge.svg)
+
+# FA
+
+## What is it?
+
+FA stands for Firmware Analysis and intended **For Humans**.
+
+FA allows one to easily perform code exploration, symbol searching and 
+other functionality with ease.
+
+Usually such tasks would require you to understand complicated APIs,
+write machine-dependant code and perform other tedious tasks.
+FA is meant to replace the steps one usually performs like a robot 
+(find X string, goto xref, find the next call function, ...) in 
+a much friendlier and maintainable manner. 
+
+The current codebase is very IDA-plugin-oriented. In the future I'll
+consider adding compatibility for other disassemblers such as:
+Ghidra, Radare and etc...
+
+
+Pull Requests are of course more than welcome :smirk:.
+
+## Requirements
+
+Supported IDA 7.x.
+
+In your IDA's python directory, run:
+
+```sh
+python -m pip install -r requirements.txt
+```
+
+And for testing:
+```sh
+python -m pip install -r requirements_testing.txt
+```
+
+## I wanna start using, but where do I start?
+
+Before using, you should understand the terminology for: 
+Projects, SIG files and Loaders.
+
+So, grab a cup of coffee, listen to some [nice music](https://www.youtube.com/watch?v=5rrIx7yrxwQ), and please devote 
+a few minutes of your time into reading this README.
+
+### Projects
+
+The "project" is kind of the namespace for different signatures.
+For example, either: linux, linux_x86, linux_arm etc... are good 
+project names that can be specified if you are working on either 
+platforms. 
+
+By dividing the signatures into such projects, Windows symbols for 
+example won't be searched for Linux projects, which will result 
+in a better directory organization layout, better performance and
+less rate for false-positives. 
+
+The signatures are located by default in the `signatures` directory.
+If one wishes to use a different location, you may create `config.ini`
+at FA's root with the following contents:
+
+```ini
+[global]
+signatures_root = /a/b/c
+```
+
+### SIG format
+
+The SIG format is a core feature of FA regarding symbol searching. Each
+SIG file is residing within the project directory and is automatically searched
+when requested to generate the project's symbol list.
+
+The format is Hjson-based and is used to describe what you, 
+**as a human**, would do in order to perform the given task (symbol searching
+or binary exploration).
+
+SIG syntax (single):
+```hjson
+{
+    type: function/global/number # doesn't really have meaning
+    name: name
+    instructions : [
+        # Available commands are listed below
+        command1
+        command2
+    ]
+}
+```
+
+Each line in the `instructions` list behaves like a shell
+command-line that gets the previous results as the input 
+and outputs the next results
+to the next line.
+
+Confused? That's alright :grinning:. [Just look at the examples below](#examples)
+
+User may also use his own python script files to perform 
+the search. Just create a new `.py` file in your project 
+directory and implement the `run(**kwargs)` method. Also, the project's
+path is appended to python's `sys.path` so you may import
+your scripts from one another.
+
+To view the list of available commands, [view the list below](#available-commands)
+
+### Examples
+
+#### Finding a global struct
+
+```hjson
+{
+    type: global,
+    name: g_awsome_global,
+    instructions: [
+            # find the byte sequence '11 22 33 44'
+            find-bytes --or '11 22 33 44'
+
+            # advance offset by 20
+            offset 20
+
+            # verify the current bytes are 'aa bb cc dd'
+            verify-bytes 'aa bb cc dd'
+
+            # go back by 20 bytes offset
+            offset -20
+
+            # set global name
+            set-name g_awsome_global
+	]
+}
+```
+
+#### Find function by reference to string
+
+```hjson
+{
+    type: function
+    name: free
+    instructions: [
+            # search the string "free"
+            find-str --or 'free' --null-terminated
+
+            # goto xref
+            xref
+
+            # goto function's prolog
+            function-start
+
+            # reduce to the singletone with most xrefs to
+            max-xrefs
+
+            # set name and type
+            set-name free
+            set-type 'void free(void *block)'
+	]
+}
+```
+
+#### Performing code exploration
+
+```hjson
+{
+    type: function-list
+    name: arm-explorer
+    instructions: [
+            # search for some potential function prologs
+            arm-find-all 'push {r4, lr}'
+            arm-find-all 'push {r4, r5, lr}'
+            thumb-find-all 'push {r4, lr}'
+            thumb-find-all 'push {r4, r5, lr}'
+
+            # convert into functions
+            make-function
+	]
+}
+```
+
+#### Performing string exploration
+
+```hjson
+{
+    type: explorer
+    name: arm-string-explorer
+    instructions: [
+            # goto printf
+            locate printf
+
+            # iterate every xref
+            xref
+
+            # and for each, go word-word backwards
+            add-offset-range 0 -40 -4
+
+            # if ldr to r0
+            verify-operand ldr --op0 r0
+
+            # go to the global string
+            goto-ref --data
+
+            # and make it literal
+            make-literal
+	]
+}
+```
+
+#### Finding several functions in a row
+
+```hjson
+{
+    type: function
+    name: cool_functions
+    instructions: [
+            # find string
+            find-str --or 'init_stuff' --null-terminated
+
+            # goto to xref
+            xref
+    
+            # goto function start
+            function-start
+
+            # verify only one single result
+            unique
+
+            # iterating every 4-byte opcode            
+            add-offset-range 0 80 4
+
+            # if mnemonic is bl
+            verify-operand bl
+
+            # sort results
+            sort
+
+            # mark resultset checkpoint
+            checkpoint BLs
+
+            # set first bl to malloc function
+            single 0
+            goto-ref --code 
+            set-name malloc
+            set-type 'void *malloc(unsigned int size)'
+
+            # go back to the results from 4 commands ago 
+            # (the sort results)
+            back-to-checkpoint BLs
+
+            # rename next symbol :)
+            single 1
+            goto-ref --code
+            set-name free
+            set-type 'void free(void *block)'
+	]
+}
+```
+
+#### Python script to find a list of symbols
+
+```python
+from fa.commands.find_str import find_str 
+from fa.commands.set_name import set_name
+from fa.commands.unique import unique
+from fa import context
+
+def run(**kwargs):
+    # throw an exception if not running within ida context
+    context.verify_ida('script-name')
+
+    # locate the global string, verify it's unique, and set it's 
+    # name within the idb 
+    results = set_name(unique(find_str('hello world', null_terminated=True)),
+                       'g_hello_world_string')
+
+    if len(results) != 1:
+        # no results
+        return {}
+    
+    # return a dictionary of the found symbols
+    return {'g_hello_world_string': results[0]}
+```
+
+#### Python script to automate SIG files interpreter
+
+```python
+TEMPLATE = '''
+find-str --or '{unique_string}'
+xref
+function-start
+unique
+set-name '{function_name}'
+'''
+
+def run(**kwargs):
+    results = {}
+    interp = kwargs['interpreter']
+
+    for function_name in ['func1', 'func2', 'func3']:
+        instructions = TEMPLATE.format(unique_string=function_name, 
+                                       function_name=function_name).split('\n')
+        
+        results[function_name] = interp.find_from_instructions_list(instructions)
+
+    return results
+```
+
+#### Python script to dynamically add structs
+
+```python
+from fa.commands.set_type import set_type
+from fa import fa_types
+
+TEMPLATE = '''
+find-str --or '{unique_string}'
+xref
+'''
+
+def run(**kwargs):
+    interp = kwargs['interpreter']
+
+    fa_types.add_const('CONST7', 7)
+    fa_types.add_const('CONST8', 8)
+
+    foo_e = fa_types.FaEnum('foo_e')
+    foo_e.add_value('val2', 2)
+    foo_e.add_value('val1', 1)
+    foo_e.update_idb()
+
+    special_struct_t = fa_types.FaStruct('special_struct_t')
+    special_struct_t.add_field('member1', 'const char *', size=4)
+    special_struct_t.add_field('member2', 'const char *', size=4, offset=0x20)
+    special_struct_t.update_idb()
+
+    for function_name in ['unique_magic1', 'unique_magic2']:
+        instructions = TEMPLATE.format(unique_string=function_name, 
+                                       function_name=function_name).split('\n')
+        
+        results = interp.find_from_instructions_list(instructions)
+        for ea in results:
+            # the set_type can receive either a string, FaStruct
+            # or FaEnum :-)
+            set_type(ea, special_struct_t)
+
+    return {}
+```
+
+### Aliases
+
+Each command can be "alias"ed using the file 
+found in `fa/commands/alias` or in `<project_root>/alias`
+
+Syntax for each line is as follows: `alias_command = command`
+For example:
+```
+ppc32-verify = keystone-verify-opcodes --bele KS_ARCH_PPC KS_MODE_PPC32
+```
+
+Project aliases have higher priority.
+
+### Loaders
+
+Loaders are the entry point into running FA. 
+In the future we'll possibly add Ghidra and other tools.
+
+Please first install the package as follows:
+
+Clone the repository and install locally:
+
+```sh
+# clone
+git clone git@github.com:doronz88/fa.git
+cd fa
+
+# install
+python -m pip install -e .
+```
+
+#### IDA
+
+Within IDA Python run:
+
+```python
+from fa import ida_plugin
+ida_plugin.install()
+```
+
+You should get a nice prompt inside the output window welcoming you
+into using FA. Also, a quick usage guide will also be printed so you 
+don't have to memorize everything.
+
+Also, an additional `FA Toolbar` will be added with quick functions that
+are also available under the newly created `FA` menu.
+
+![FA Menu](https://github.com/doronz88/fa/raw/master/fa/res/screenshots/menu.png "FA Menu")
+
+A QuickStart Tip:
+
+`Ctrl+6` to select your project, then `Ctrl+7` to find all its defined symbols.
+
+
+You can also run IDA in script mode just to extract symbols using:
+
+```sh
+ida -S"fa/ida_plugin.py <signatures-root> --project-name <project-name> --symbols-file=/tmp/symbols.txt" foo.idb
+```
+
+
+#### ELF
+
+In order to use FA on a RAW ELF file, simply use the following command-line:
+
+```sh
+python elf_loader.py <elf-file> <signatures_root> <project>
+```
+
+### Available commands
+
+See [commands.md](commands.md)
+

fa-0.1.0/fa/commands/add_offset_range.py

@@ -0,0 +1,33 @@
+from argparse import RawTextHelpFormatter
+from fa import utils
+
+
+DESCRIPTION = '''adds a python-range to resultset
+
+EXAMPLE:
+    result = [0, 0x200]
+    -> add-offset-range 0 4 8
+    result = [0, 4, 8, 0x200, 0x204, 0x208]
+'''
+
+
+def get_parser():
+    p = utils.ArgumentParserNoExit('add-offset-range',
+                                   description=DESCRIPTION,
+                                   formatter_class=RawTextHelpFormatter)
+    p.add_argument('start', type=int)
+    p.add_argument('end', type=int)
+    p.add_argument('step', type=int)
+    return p
+
+
+@utils.yield_unique
+def add_offset_range(addresses, start, end, step):
+    for ea in addresses:
+        for i in range(start, end, step):
+            yield ea + i
+
+
+def run(segments, args, addresses, interpreter=None, **kwargs):
+    gen = add_offset_range(addresses, args.start, args.end, args.step)
+    return list(gen)

fa-0.1.0/fa/commands/alias

@@ -0,0 +1,8 @@
+ppc32-big-find-all = keystone-find-opcodes --or KS_ARCH_PPC KS_MODE_BIG_ENDIAN|KS_MODE_PPC32
+ppc32-find-all = keystone-find-opcodes --bele --or KS_ARCH_PPC KS_MODE_PPC32
+ppc32-big-verify = keystone-verify-opcodes KS_ARCH_PPC KS_MODE_BIG_ENDIAN|KS_MODE_PPC32
+ppc32-verify = keystone-verify-opcodes --bele KS_ARCH_PPC KS_MODE_PPC32
+arm-find-all = keystone-find-opcodes --bele --or KS_ARCH_ARM KS_MODE_ARM
+thumb-find-all = keystone-find-opcodes --bele --or KS_ARCH_ARM KS_MODE_THUMB
+arm-verify = keystone-verify-opcodes --bele KS_ARCH_ARM KS_MODE_ARM
+find-imm = find-immediate

fa-0.1.0/fa/commands/align.py

@@ -0,0 +1,26 @@
+from argparse import RawTextHelpFormatter
+from fa import utils
+
+DESCRIPTION = '''align results to given base (round-up)
+
+EXAMPLE:
+    results = [0, 2, 4, 6, 8]
+    -> align 4
+    results = [0, 4, 4, 8, 8]
+'''
+
+
+def get_parser():
+    p = utils.ArgumentParserNoExit('align',
+                                   description=DESCRIPTION,
+                                   formatter_class=RawTextHelpFormatter)
+    p.add_argument('value', type=int)
+    return p
+
+
+def align(addresses, value):
+    return [((ea + (value - 1)) // value) * value for ea in addresses]
+
+
+def run(segments, args, addresses, interpreter=None, **kwargs):
+    return list(align(addresses, args.value))

fa-0.1.0/fa/commands/back.py

@@ -0,0 +1,29 @@
+from argparse import RawTextHelpFormatter
+from fa import utils
+
+
+DESCRIPTION = '''go back to previous result-set
+
+EXAMPLE:
+    find-bytes --or 01 02 03 04
+    results = [0, 0x100, 0x200]
+
+    find-bytes --or 05 06 07 08
+    results = [0, 0x100, 0x200, 0x300, 0x400]
+
+    -> back -3
+    results = [0, 0x100, 0x200]
+'''
+
+
+def get_parser():
+    p = utils.ArgumentParserNoExit('back',
+                                   description=DESCRIPTION,
+                                   formatter_class=RawTextHelpFormatter)
+    p.add_argument('amount', type=int,
+                   help='amount of command results to go back by')
+    return p
+
+
+def run(segments, args, addresses, interpreter=None, **kwargs):
+    return interpreter.history[-args.amount]

fa-0.1.0/fa/commands/back_to_checkpoint.py

@@ -0,0 +1,28 @@
+from argparse import RawTextHelpFormatter
+from fa import utils
+
+DESCRIPTION = '''go back to previous result-set saved by 'checkpoint' command.
+
+EXAMPLE:
+    results = [0, 4, 8]
+    checkpoint foo
+
+    find-bytes --or 12345678
+    results = [0, 4, 8, 10, 20]
+
+    -> back-to-checkpoint foo
+    results = [0, 4, 8]
+'''
+
+
+def get_parser():
+    p = utils.ArgumentParserNoExit('back-to-checkpoint',
+                                   description=DESCRIPTION,
+                                   formatter_class=RawTextHelpFormatter)
+    p.add_argument('name', help='name of checkpoint in history to go back '
+                                'to')
+    return p
+
+
+def run(segments, args, addresses, interpreter=None, **kwargs):
+    return interpreter.checkpoints[args.name]

fa-0.1.0/fa/commands/checkpoint.py

@@ -0,0 +1,29 @@
+from argparse import RawTextHelpFormatter
+from fa import utils
+
+DESCRIPTION = '''save current result-set as a checkpoint.
+You can later restore the result-set using 'back-to-checkpoint'
+
+EXAMPLE:
+    results = [0, 4, 8]
+    -> checkpoint foo
+
+    find-bytes --or 12345678
+    results = [0, 4, 8, 10, 20]
+
+    back-to-checkpoint foo
+    results = [0, 4, 8]
+'''
+
+
+def get_parser():
+    p = utils.ArgumentParserNoExit('checkpoint',
+                                   description=DESCRIPTION,
+                                   formatter_class=RawTextHelpFormatter)
+    p.add_argument('name', help='name of checkpoint to use')
+    return p
+
+
+def run(segments, args, addresses, interpreter=None, **kwargs):
+    interpreter.checkpoints[args.name] = addresses
+    return addresses

fa-0.1.0/fa/commands/clear.py

@@ -0,0 +1,21 @@
+from argparse import RawTextHelpFormatter
+from fa import utils
+
+DESCRIPTION = '''clears the current result-set
+
+EXAMPLE:
+    results = [0, 4, 8]
+    -> clear
+    results = []
+'''
+
+
+def get_parser():
+    p = utils.ArgumentParserNoExit('clear',
+                                   description=DESCRIPTION,
+                                   formatter_class=RawTextHelpFormatter)
+    return p
+
+
+def run(segments, args, addresses, interpreter=None, **kwargs):
+    return []

fa-0.1.0/fa/commands/find_bytes.py

@@ -0,0 +1,46 @@
+from argparse import RawTextHelpFormatter
+from collections import OrderedDict
+import binascii
+
+from fa import utils
+
+DESCRIPTION = '''expands the result-set with the occurrences of the given bytes
+
+EXAMPLE:
+    0x00000000: 01 02 03 04
+    0x00000004: 05 06 07 08
+
+    results = []
+    -> find-bytes --or 01020304
+    result = [0]
+
+    -> find-bytes --or 05060708
+    results = [0, 4]
+'''
+
+
+def get_parser():
+    p = utils.ArgumentParserNoExit('find-bytes',
+                                   description=DESCRIPTION,
+                                   formatter_class=RawTextHelpFormatter)
+    p.add_argument('--or', action='store_true')
+    p.add_argument('hex_str')
+    return p
+
+
+@utils.yield_unique
+def find_bytes(hex_str, segments=None):
+    needle = binascii.unhexlify(''.join(hex_str.split(' ')))
+    return utils.find_raw(needle, segments=segments)
+
+
+def run(segments, args, addresses, interpreter=None, **kwargs):
+    results = list(find_bytes(args.hex_str, segments=segments))
+
+    retval = set(addresses)
+    if getattr(args, 'or'):
+        retval.update(results)
+    else:
+        raise ValueError("must specify --or option")
+
+    return list(OrderedDict.fromkeys(retval))

fa-0.1.0/fa/commands/find_bytes_ida.py

@@ -0,0 +1,47 @@
+from argparse import RawTextHelpFormatter
+from collections import OrderedDict
+
+from fa import utils, context
+
+DESCRIPTION = '''expands the result-set with the occurrences of the given bytes
+expression in "ida bytes syntax"
+
+EXAMPLE:
+    0x00000000: 01 02 03 04
+    0x00000004: 05 06 07 08
+
+    results = []
+    -> find-bytes-ida --or '01 02 03 04'
+    result = [0]
+
+    -> find-bytes-ida --or '05 06 ?? 08'
+    results = [0, 4]
+'''
+
+
+def get_parser():
+    p = utils.ArgumentParserNoExit('find-bytes-ida',
+                                   description=DESCRIPTION,
+                                   formatter_class=RawTextHelpFormatter)
+    p.add_argument('--or', action='store_true')
+    p.add_argument('expression')
+    return p
+
+
+@context.ida_context
+@utils.yield_unique
+def find_bytes_ida(expression, segments=None):
+    for address in utils.ida_find_all(expression):
+        yield address
+
+
+def run(segments, args, addresses, interpreter=None, **kwargs):
+    results = find_bytes_ida(args.expression)
+
+    retval = set(addresses)
+    if getattr(args, 'or'):
+        retval.update(results)
+    else:
+        raise ValueError("must specify --or option")
+
+    return list(OrderedDict.fromkeys(retval))