From d2d1f26e7b8b795fa195a7a469b2b613b675e676 Mon Sep 17 00:00:00 2001
From: Moritz Raabe <moritz.raabe@fireeye.com>
Date: Wed, 24 Jun 2020 12:55:35 +0200
Subject: [PATCH] update documentation

---
 README.md                  | 13 +++++++++++--
 capa/main.py               |  8 ++++----
 rules                      |  2 +-
 tests/test_viv_features.py |  1 +
 4 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 934ead30c..daf87eee1 100644
--- a/README.md
+++ b/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.
diff --git a/capa/main.py b/capa/main.py
index f040e6469..edaa9e9c9 100644
--- a/capa/main.py
+++ b/capa/main.py
@@ -640,7 +640,7 @@ 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
@@ -648,7 +648,7 @@ def main(argv=None):
             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.")
diff --git a/rules b/rules
index eaae0e89a..d34acf7bb 160000
--- a/rules
+++ b/rules
@@ -1 +1 @@
-Subproject commit eaae0e89a75eae6d564873287ae55afb30f8970b
+Subproject commit d34acf7bbd5a2132740bcce00703f657a39dfcdd
diff --git a/tests/test_viv_features.py b/tests/test_viv_features.py
index a76de67cb..78314765a 100644
--- a/tests/test_viv_features.py
+++ b/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