explorer: updating support documentation and runtime checks

CHANGELOG.md

@@ -4,9 +4,6 @@
 
 ### New Features
 
-- explorer: allow user to add specified number of bytes when adding a Bytes feature in the Rule Generator #689 @mike-hunhoff
-- explorer: enforce max column width Features and Editor panes #691 @mike-hunhoff
-- explorer: add option to limit features to currently selected disassembly address #692 @mike-hunhoff
 - all: add support for ELF files #700 @Adir-Shemesh @TcM1911
 - rule format: add feature `format: ` for file format, like `format: pe` #723 @williballenthin
 - rule format: add feature `arch: ` for architecture, like `arch: amd64` #723 @williballenthin
@@ -59,6 +56,10 @@
 - explorer: add additional filter logic when displaying matches by function #686 @mike-hunhoff
 - explorer: remove duplicate check when saving file #687 @mike-hunhoff
 - explorer: update IDA extractor to use non-canon mnemonics #688 @mike-hunhoff
+- explorer: allow user to add specified number of bytes when adding a Bytes feature in the Rule Generator #689 @mike-hunhoff
+- explorer: enforce max column width Features and Editor panes #691 @mike-hunhoff
+- explorer: add option to limit features to currently selected disassembly address #692 @mike-hunhoff
+- explorer: update support documentation and runtime checks #741 @mike-hunhoff
 
 ### Development
 

capa/ida/helpers.py

@@ -21,22 +21,23 @@ import capa.features.common
 
 logger = logging.getLogger("capa")
 
-SUPPORTED_IDA_VERSIONS = [
-    "7.1",
-    "7.2",
-    "7.3",
+# IDA version as returned by idaapi.get_kernel_version()
+SUPPORTED_IDA_VERSIONS = (
     "7.4",
     "7.5",
     "7.6",
-]
+)
 
-# file type names as returned by idainfo.file_type
-SUPPORTED_FILE_TYPES = [
+# file type as returned by idainfo.file_type
+SUPPORTED_FILE_TYPES = (
     idaapi.f_PE,
     idaapi.f_ELF,
-    # idaapi.f_MACHO,
     idaapi.f_BIN,
-]
+    # idaapi.f_MACHO,
+)
+
+# arch type as returned by idainfo.procname
+SUPPORTED_ARCH_TYPES = ("metapc",)
 
 
 def inform_user_ida_ui(message):
@@ -62,7 +63,7 @@ def is_supported_file_type():
         logger.error(" Input file does not appear to be a supported file type.")
         logger.error(" ")
         logger.error(
-            " capa currently only supports analyzing PE files (or binary files containing x86/AMD64 shellcode) with IDA."
+            " capa currently only supports analyzing PE, ELF files, or binary files containing x86 (32- and 64-bit) shellcode."
         )
         logger.error(" If you don't know the input file type, you can try using the `file` utility to guess it.")
         logger.error("-" * 80)
@@ -70,6 +71,18 @@ def is_supported_file_type():
     return True
 
 
+def is_supported_arch_type():
+    file_info = idaapi.get_inf_structure()
+    if file_info.procname not in SUPPORTED_ARCH_TYPES or not any((file_info.is_32bit(), file_info.is_64bit())):
+        logger.error("-" * 80)
+        logger.error(" Input file does not appear to target a supported architecture.")
+        logger.error(" ")
+        logger.error(" capa currently only supports analyzing x86 (32- and 64-bit).")
+        logger.error("-" * 80)
+        return False
+    return True
+
+
 def get_disasm_line(va):
     """ """
     return idc.generate_disasm_line(va, idc.GENDSM_FORCE_CODE)

capa/ida/plugin/README.md

@@ -34,12 +34,26 @@ For more information on the FLARE team's open-source framework, capa, check out
 
 ### Requirements
 
-capa explorer supports Python >= 3.6 and the following IDA Pro versions:
+capa explorer supports Python versions >= 3.6.x and the following IDA Pro versions:
 
 * IDA 7.4
 * IDA 7.5
 * IDA 7.6 (caveat below)
 
+capa explorer is however limited to the Python versions supported by your IDA installation (which may not be all Python versions >= 3.6.x). Based on our testing the following matrix shows the Python versions supported
+by each supported IDA version:
+
+| | IDA 7.4 | IDA 7.5 | IDA 7.6 |
+| --- | --- | --- | --- |
+| Python 3.6.x | Yes | Yes | Yes |
+| Python 3.7.x | Yes | Yes | Yes |
+| Python 3.8.x | Partial (see below) | Yes | Yes |
+| Python 3.9.x | No | Partial (see below) | Yes |
+
+To use capa explorer with IDA 7.4 and Python 3.8.x you must follow the instructions provided by hex-rays [here](https://hex-rays.com/blog/ida-7-4-and-python-3-8/).
+
+To use capa explorer with IDA 7.5 and Python 3.9.x you must follow the instructions provided by hex-rays [here](https://hex-rays.com/blog/python-3-9-support-for-ida-7-5/).
+
 If you encounter issues with your specific setup, please open a new [Issue](https://github.com/fireeye/capa/issues).
 
 #### IDA 7.6 caveat: IDA 7.6sp1 or patch required
@@ -61,8 +75,8 @@ Therefore, in order to use capa under IDA 7.6 you need the [Service Pack 1 for I
 
 capa explorer is limited to the file types supported by capa, which include:
 
-* Windows 32-bit and 64-bit PE files
-* Windows 32-bit and 64-bit shellcode
+* Windows x86 (32- and 64-bit) PE and ELF files
+* Windows x86 (32- and 64-bit) shellcode
 
 ### Installation
 

capa/ida/plugin/__init__.py

@@ -47,6 +47,8 @@ class CapaExplorerPlugin(idaapi.plugin_t):
             return idaapi.PLUGIN_SKIP
         if not capa.ida.helpers.is_supported_file_type():
             return idaapi.PLUGIN_SKIP
+        if not capa.ida.helpers.is_supported_arch_type():
+            return idaapi.PLUGIN_SKIP
         return idaapi.PLUGIN_OK
 
     def term(self):