{"id":16668890,"url":"https://github.com/doronz88/fa","last_synced_at":"2025-04-04T21:09:42.214Z","repository":{"id":57427998,"uuid":"256209924","full_name":"doronz88/fa","owner":"doronz88","description":"Automation tool for locating symbols \u0026 structs in binary (primary IDA focused)","archived":false,"fork":false,"pushed_at":"2025-02-19T15:58:53.000Z","size":1355,"stargazers_count":85,"open_issues_count":0,"forks_count":9,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-02T23:07:35.570Z","etag":null,"topics":["firmware","hjson","ida","ida-plugin","ida-python","python","python-script","research-tool","reverse-engineering","sig","sig-files","sig-format","signatures","symbols"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/doronz88.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-16T12:35:00.000Z","updated_at":"2025-02-20T06:50:57.000Z","dependencies_parsed_at":"2024-10-25T18:32:52.281Z","dependency_job_id":"33104f88-acd8-4d4b-af73-9b821daa7a12","html_url":"https://github.com/doronz88/fa","commit_stats":{"total_commits":315,"total_committers":3,"mean_commits":105.0,"dds":0.04761904761904767,"last_synced_commit":"cfdceb6ac4ee446f95bdb55987bfa932790cb2d5"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doronz88%2Ffa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doronz88%2Ffa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doronz88%2Ffa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doronz88%2Ffa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/doronz88","download_url":"https://codeload.github.com/doronz88/fa/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247249530,"owners_count":20908212,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["firmware","hjson","ida","ida-plugin","ida-python","python","python-script","research-tool","reverse-engineering","sig","sig-files","sig-format","signatures","symbols"],"created_at":"2024-10-12T11:27:55.738Z","updated_at":"2025-04-04T21:09:42.190Z","avatar_url":"https://github.com/doronz88.png","language":"Python","readme":"![Python application](https://github.com/doronz88/fa/workflows/Python%20application/badge.svg)\n\n# FA\n\n## What is it?\n\nFA stands for Firmware Analysis and intended **For Humans**.\n\nFA allows one to easily perform code exploration, symbol searching and \nother functionality with ease.\n\nUsually such tasks would require you to understand complicated APIs,\nwrite machine-dependant code and perform other tedious tasks.\nFA is meant to replace the steps one usually performs like a robot \n(find X string, goto xref, find the next call function, ...) in \na much friendlier and maintainable manner. \n\nThe current codebase is very IDA-plugin-oriented. In the future I'll\nconsider adding compatibility for other disassemblers such as:\nGhidra, Radare and etc...\n\n\nPull Requests are of course more than welcome :smirk:.\n\n## Requirements\n\nSupported IDA 8.0+.\n\nIn your IDA's python directory, run:\n\n```sh\npython -m pip install -r requirements.txt\n```\n\nAnd for testing:\n```sh\npython -m pip install -r requirements_testing.txt\n```\n\n## Where to start?\n\nBefore using, you should understand the terminology for: \nProjects, SIG files and Loaders.\n\nSo, grab a cup of coffee, listen to some [nice music](https://www.youtube.com/watch?v=5rrIx7yrxwQ), and please devote \na few minutes of your time into reading this README.\n\n### Projects\n\nThe \"project\" is kind of the namespace for different signatures.\nFor example, either: linux, linux_x86, linux_arm etc... are good \nproject names that can be specified if you are working on either \nplatforms. \n\nBy dividing the signatures into such projects, Windows symbols for \nexample won't be searched for Linux projects, which will result \nin a better directory organization layout, better performance and\nless rate for false-positives. \n\nThe signatures are located by default in the `signatures` directory.\nIf you wish to use a different location, you may create `config.ini`\nat FA's root with the following contents:\n\n```ini\n[global]\nsignatures_root = /a/b/c\n```\n\n### SIG format\n\nThe SIG format is a core feature of FA regarding symbol searching. Each\nSIG file is residing within the project directory and is automatically searched\nwhen requested to generate the project's symbol list.\n\nThe format is Hjson-based and is used to describe what you, \n**as a human**, would do in order to perform the given task (symbol searching\nor binary exploration).\n\nSIG syntax (single):\n```hjson\n{\n    name: name  \n    instructions : [\n        # Available commands are listed below\n        command1\n        command2\n    ]\n}\n```\n\nEach line in the `instructions` list behaves like a shell\ncommand-line that gets the previous results as the input \nand outputs the next results\nto the next line.\n\nConfused? That's alright :grinning:. [Just look at the examples below](#examples)\n\nUser may also use his own python script files to perform \nthe search. Just create a new `.py` file in your project \ndirectory and implement the `run(interpreter)` method. \nAlso, the project's path is appended to python's `sys.path` \nso you may import your scripts from one another.\n\nTo view the list of available commands, [view the list below](#available-commands)\n\n### Examples\n\n#### Finding a global struct\n\n```hjson\n{\n    name: g_awsome_global,\n    instructions: [\n            # find the byte sequence '11 22 33 44'\n            find-bytes '11 22 33 44'\n\n            # advance offset by 20\n            offset 20\n\n            # verify the current bytes are 'aa bb cc dd'\n            verify-bytes 'aa bb cc dd'\n\n            # go back by 20 bytes offset\n            offset -20\n\n            # set global name\n            set-name g_awsome_global\n\t]\n}\n```\n\n#### Find function by reference to string\n\n```hjson\n{\n    name: free\n    instructions: [\n            # search the string \"free\"\n            find-str 'free' --null-terminated\n\n            # goto xref\n            xref\n\n            # goto function's prolog\n            function-start\n\n            # reduce to the singletone with most xrefs to\n            max-xrefs\n\n            # set name and type\n            set-name free\n            set-type 'void free(void *block)'\n\t]\n}\n```\n\n#### Performing code exploration\n\n```hjson\n{\n    name: arm-explorer\n    instructions: [\n            # search for some potential function prologs\n            arm-find-all 'push {r4, lr}'\n            arm-find-all 'push {r4, r5, lr}'\n            thumb-find-all 'push {r4, lr}'\n            thumb-find-all 'push {r4, r5, lr}'\n\n            # convert into functions\n            make-function\n\t]\n}\n```\n\n#### Performing string exploration\n\n```hjson\n{\n    name: arm-string-explorer\n    instructions: [\n            # goto printf\n            locate printf\n\n            # iterate every xref\n            xref\n\n            # and for each, go word-word backwards\n            add-offset-range 0 -40 -4\n\n            # if ldr to r0\n            verify-operand ldr --op0 r0\n\n            # go to the global string\n            goto-ref --data\n\n            # and make it literal\n            make-literal\n\t]\n}\n```\n\n#### Finding enums and constants \n\n```hjson\n{\n    name: consts-finder\n    instructions: [\n            # goto printf\n            locate printf\n\n            # iterate all its function lines\n            function-lines\n\n            # save this result\n            store printf-lines\n            \n            # look for: li r7, ???\n            verify-operand li --op0 7\n\n            # extract second operand\n            operand 1\n\n            # define the constant\n            set-const IMPORTANT_OFFSET\n\n            # load previous results\n            load printf-lines\n            \n            # look for: li r7, ???\n            verify-operand li --op0 8\n\n            # get second operand\n            operand 1\n\n            # set this enum value\n            set-enum important_enum_t some_enum_key\n\t]\n}\n```\n\n#### Adding struct member offsets \n\n```hjson\n{\n    name: structs-finder\n    instructions: [\n            # add hard-coded '0' into resultset\n            add 0\n\n            # add a first member at offset 0\n            set-struct-member struct_t member_at_0 'unsigned int'\n\n            # advance offset by 4\n            offset 4            \n\n            # add a second member\n            set-struct-member struct_t member_at_4 'const char *'\n\n            # goto function printf\n            locate printf\n\n            # iterate its function lines \n            function-lines\n\n            # look for the specific mov opcode (MOV R8, ???)\n            verify-operand mov --op0 8\n            \n            # extract the offset\n            operand 1\n\n            # define this offset into the struct\n            set-struct-member struct_t member_at_r8_offset 'const char *'\n\t]\n}\n```\n\n#### Finding several functions in a row\n\n```hjson\n{\n    name: cool_functions\n    instructions: [\n            # find string\n            find-str 'init_stuff' --null-terminated\n\n            # goto to xref\n            xref\n    \n            # goto function start\n            function-start\n\n            # verify only one single result\n            unique\n\n            # iterating every 4-byte opcode            \n            add-offset-range 0 80 4\n\n            # if mnemonic is bl\n            verify-operand bl\n\n            # sort results\n            sort\n\n            # store resultset in 'BLs'\n            store BLs\n\n            # set first bl to malloc function\n            single 0\n            goto-ref --code \n            set-name malloc\n            set-type 'void *malloc(unsigned int size)'\n\n            # go back to the results from 4 commands ago \n            # (the sort results)\n            load BLs\n\n            # rename next symbol :)\n            single 1\n            goto-ref --code\n            set-name free\n            set-type 'void free(void *block)'\n\t]\n}\n```\n\n#### Conditional branches\n\n```hjson\n{\n    name: set_opcode_const\n    instructions: [\n        # goto printf function\n        locate printf\n\n        # goto 'case_opcode_bl' if current opcode is bl\n        if 'verify-operand bl' case_opcode_bl\n\n            # make: #define is_bl (0)\n            clear\n            add 0\n            set-const is_bl\n    \n            # finish script by jumping to end\n            b end\n\n        # mark as 'case_opcode_bl' label\n        label case_opcode_bl\n\n            # make: #define is_bl (1)\n            clear\n            add 1\n            set-const is_bl\n\n        # mark script end\n        label end\n    ]\n}\n```\n\n#### Python script to find a list of symbols\n\n```python\nfrom fa.commands.find_str import find_str\nfrom fa.commands.set_name import set_name\nfrom fa import context\n\ndef run(interpreter):\n    # throw an exception if not running within ida context\n    context.verify_ida('script-name')\n\n    # locate the global string\n    set_name(find_str('hello world', null_terminated=True),\n             'g_hello_world', interpreter)\n```\n\n#### Python script to automate SIG files interpreter\n\n```python\nTEMPLATE = '''\nfind-str '{unique_string}'\nxref\nfunction-start\nunique\nset-name '{function_name}'\n'''\n\ndef run(interpreter):\n    for function_name in ['func1', 'func2', 'func3']:\n        instructions = TEMPLATE.format(unique_string=function_name, \n                                       function_name=function_name).split('\\n')\n        \n        interpreter.find_from_instructions_list(instructions)\n```\n\n#### Python script to dynamically add structs\n\n```python\nfrom fa.commands.set_type import set_type\nfrom fa import fa_types\n\nTEMPLATE = '''\nfind-str '{unique_string}'\nxref\n'''\n\ndef run(interpreter):\n    fa_types.add_const('CONST7', 7)\n    fa_types.add_const('CONST8', 8)\n\n    foo_e = fa_types.FaEnum('foo_e')\n    foo_e.add_value('val2', 2)\n    foo_e.add_value('val1', 1)\n    foo_e.update_idb()\n\n    special_struct_t = fa_types.FaStruct('special_struct_t')\n    special_struct_t.add_field('member1', 'const char *')\n    special_struct_t.add_field('member2', 'const char *', offset=0x20)\n    special_struct_t.update_idb()\n\n    for function_name in ['unique_magic1', 'unique_magic2']:\n        instructions = TEMPLATE.format(unique_string=function_name, \n                                       function_name=function_name).split('\\n')\n        \n        results = interpreter.find_from_instructions_list(instructions)\n        for ea in results:\n            # the set_type can receive either a string, FaStruct\n            # or FaEnum :-)\n            set_type(ea, special_struct_t)\n```\n\n### Aliases\n\nEach command can be \"alias\"ed using the file \nfound in `fa/commands/alias` or in `\u003cproject_root\u003e/alias`\n\nSyntax for each line is as follows: `alias_command = command`\nFor example:\n```\nppc32-verify = keystone-verify-opcodes --bele KS_ARCH_PPC KS_MODE_PPC32\n```\n\nProject aliases have higher priority.\n\n### Loaders\n\nLoaders are the entry point into running FA. \nIn the future we'll possibly add Ghidra and other tools.\n\nPlease first install the package as follows:\n\nClone the repository and install locally:\n\n```sh\n# clone\ngit clone git@github.com:doronz88/fa.git\ncd fa\n\n# install\npython -m pip install -e .\n```\n\n#### IDA\n\nWithin IDA Python run:\n\n```python\nfrom fa import ida_plugin\nida_plugin.install()\n```\n\nYou should get a nice prompt inside the output window welcoming you\ninto using FA. Also, a quick usage guide will also be printed so you \ndon't have to memorize everything.\n\nAlso, an additional `FA Toolbar` will be added with quick functions that\nare also available under the newly created `FA` menu.\n\n![FA Menu](https://github.com/doronz88/fa/raw/master/fa/res/screenshots/menu.png \"FA Menu\")\n\nA QuickStart Tip:\n\n`Ctrl+6` to select your project, then `Ctrl+7` to find all its defined symbols.\n\n\nYou can also run IDA in script mode just to extract symbols using:\n\n```sh\nida -S\"fa/ida_plugin.py \u003csignatures-root\u003e --project-name \u003cproject-name\u003e --symbols-file=/tmp/symbols.txt\" foo.idb\n```\n\n\n#### ELF\n\nIn order to use FA on a RAW ELF file, simply use the following command-line:\n\n```sh\npython elf_loader.py \u003celf-file\u003e \u003csignatures_root\u003e \u003cproject\u003e\n```\n\n### Available commands\n\nSee [commands.md](commands.md)\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdoronz88%2Ffa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdoronz88%2Ffa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdoronz88%2Ffa/lists"}