update documentation

README.md

@@ -227,6 +227,11 @@ For this to match, the function must:
 If only one of these features is found in a function, the rule will not match.
 
 
+## limitations
+### circular rule dependencies
+While capa supports [matching on prior rule matches](#matching-prior-rule-matches) users should ensure that their rules do not introduce circular dependencies between rules.
+
+
 # extracted features
 
 ## function features
@@ -249,10 +254,14 @@ though possibly a local function (like `malloc`) extracted via FLIRT.
 
 The parameter is a string describing the function name, specified like `module.functionname` or `functionname`.
 
+Windows API functions that take string arguments come in two API versions. For example `CreateProcessA` takes ANSI strings and `CreateProcessW` takes Unicode strings. capa extracts these API features both with and without the suffix character `A` or `W`. That means you can write a rule to match on both APIs using the base name. If you want to match a specific API version, you can include the suffix.
+
 Example:
 
-    api: kernel32.CreateFileA
-    api: CreateFileA
+    api: kernel32.CreateFile  # matches both Ansi (CreateFileA) and Unicode (CreateFileW) versions
+    api: CreateFile
+    api: GetEnvironmentVariableW  # only matches on Unicode version
+
 
 ### number
 A number used by the logic of the program.

capa/main.py

@@ -640,15 +640,15 @@ def main(argv=None):
             logger.error("-" * 80)
             logger.error(" Input file does not appear to be a PE file.")
             logger.error(" ")
-            logger.error(" Today, capa currently only supports analyzing PE files (or shellcode, when using --format sc32|sc64).")
+            logger.error(" capa currently only supports analyzing PE files (or shellcode, when using --format sc32|sc64).")
             logger.error(" If you don't know the input file type, you can try using the `file` utility to guess it.")
             logger.error("-" * 80)
             return -1
         except UnsupportedRuntimeError:
             logger.error("-" * 80)
             logger.error(" Unsupported runtime or Python interpreter.")
             logger.error(" ")
-            logger.error(" Today, capa supports running under Python 2.7 using Vivisect for binary analysis.")
+            logger.error(" capa supports running under Python 2.7 using Vivisect for binary analysis.")
             logger.error(" It can also run within IDA Pro, using either Python 2.7 or 3.5+.")
             logger.error(" ")
             logger.error(" If you're seeing this message on the command line, please ensure you're running Python 2.7.")
@@ -679,7 +679,7 @@ def main(argv=None):
         logger.warning(" ")
         logger.warning(" .NET is a cross-platform framework for running managed applications.")
         logger.warning(
-            " Today, capa cannot handle non-native files. This means that the results may be misleading or incomplete.")
+            " capa cannot handle non-native files. This means that the results may be misleading or incomplete.")
         logger.warning(" You may have to analyze the file manually, using a tool like the .NET decompiler dnSpy.")
         logger.warning(" ")
         logger.warning(" Use -v or -vv if you really want to see the capabilities identified by capa.")
@@ -698,7 +698,7 @@ def main(argv=None):
         logger.warning(" ")
         logger.warning(" AutoIt is a freeware BASIC-like scripting language designed for automating the Windows GUI.")
         logger.warning(
-            " Today, capa cannot handle AutoIt scripts. This means that the results will be misleading or incomplete.")
+            " capa cannot handle AutoIt scripts. This means that the results will be misleading or incomplete.")
         logger.warning(" You may have to analyze the file manually, using a tool like the AutoIt decompiler MyAut2Exe.")
         logger.warning(" ")
         logger.warning(" Use -v or -vv if you really want to see the capabilities identified by capa.")

tests/test_viv_features.py

@@ -62,6 +62,7 @@ def test_api_features(mimikatz):
 def test_api_features_64_bit(sample_a198216798ca38f280dc413f8c57f2c2):
     features = extract_function_features(viv_utils.Function(sample_a198216798ca38f280dc413f8c57f2c2.vw, 0x4011B0))
     assert capa.features.insn.API('kernel32.GetStringTypeA') in features
+    assert capa.features.insn.API('kernel32.GetStringTypeW') not in features
     assert capa.features.insn.API('kernel32.GetStringType') in features
     assert capa.features.insn.API('GetStringTypeA') in features
     assert capa.features.insn.API('GetStringType') in features