Merge pull request #120 from fireeye/fix/comment-out-block-description

comment out description blocks for statements

anti-analysis/anti-debugging/debugger-detection/check-for-trap-flag-exception.yml

@@ -23,12 +23,12 @@ rule:
         - and:
           - mnemonic: pushfq
           - mnemonic: popfq
-        description: read/write EFLAGS register
+        # description: read/write EFLAGS register
       - or:
         - and:
           - mnemonic: or
           - number: 0x100
         - and:
           - mnemonic: bts
           - number: 0x8
-        description: set trap flag
+        # description: set trap flag

anti-analysis/anti-vm/vm-detection/check-for-sandbox-username.yml

@@ -13,11 +13,11 @@ rule:
       - api: GetUserName
       - or:
         - string: /MALTEST/i
-          description: Betabot Username Check  
+          description: Betabot Username Check
         - string: /TEQUILABOOMBOOM/i
           description: VirusTotal Sandbox
         - string: /SANDBOX/i
-          description: Gookit Username Check 
+          description: Gookit Username Check
         - string: /^VIRUS/i
           description: Satan Username Check
         - string: /MALWARE/i
@@ -27,36 +27,36 @@ rule:
         - string: /Test\sUser/i
           description: Betabot Username Check
         - string: /CurrentUser/i
-          description: Gookit Username Check 
+          description: Gookit Username Check
         - string: /7SILVIA/i
-          description: Gookit Username Check 
+          description: Gookit Username Check
         - string: /FORTINET/i
           description: Shifu Username Check
         - string: /John\sDoe/i
           description: Emotet Username Check
         - string: /Emily/i
-          description: Trickbot Downloader Username Check 
+          description: Trickbot Downloader Username Check
         - string: /HANSPETER\-PC/i
-          description: Trickbot Downloader Username Check 
+          description: Trickbot Downloader Username Check
         - string: /HAPUBWS/i
-          description: Trickbot Downloader Username Check 
+          description: Trickbot Downloader Username Check
         - string: /Hong\sLee/i
-          description: Trickbot Downloader Username Check 
+          description: Trickbot Downloader Username Check
         - string: /IT\-ADMIN/i
-          description: Trickbot Downloader Username Check 
+          description: Trickbot Downloader Username Check
         - string: /JOHN\-PC/i
           description: Trickbot Downloader Username Check
         - string: /Johnson/i
-          description: Trickbot Downloader Username Check 
+          description: Trickbot Downloader Username Check
         - string: /Miller/i
-          description: Trickbot Downloader Username Check 
+          description: Trickbot Downloader Username Check
         - string: /MUELLER\-PC/i
-          description: Trickbot Downloader Username Check 
+          description: Trickbot Downloader Username Check
         - string: /Peter\sWilson/i
           description: Trickbot Downloader Username Check
         - string: /SystemIT/i
-          description: Trickbot Downloader Username Check 
+          description: Trickbot Downloader Username Check
         - string: /Timmy/i
-          description: Trickbot Downloader Username Check 
+          description: Trickbot Downloader Username Check
         - string: /WIN7\-TRAPS/i
-          description: Trickbot Downloader Username Check 
+          description: Trickbot Downloader Username Check

data-manipulation/compression/decompress-data-using-quicklz.yml

@@ -27,7 +27,7 @@ rule:
             - or:
               - offset: 0x4000
               - offset: 0x8000
-            description: Mode 1 decompression
+            # description: Mode 1 decompression
         - basic block:
           - and:
             - mnemonic: shr
@@ -36,7 +36,7 @@ rule:
             - number: 0x5
             - number: 0x1
             - number: 0x7FF
-          description: Mode 2 decompression
+          # description: Mode 2 decompression
         - and:
           - basic block:
             - and:
@@ -51,4 +51,4 @@ rule:
               - mnemonic: shr
               - mnemonic: and
               - number: 0x3FF
-          description: Mode 3 decompression
+          # description: Mode 3 decompression

data-manipulation/encryption/des/encrypt-data-using-des.yml

@@ -30,4 +30,4 @@ rule:
         - characteristic: nzxor
         - count(mnemonic(shr)): 8 or more 
         - mnemonic: ror
-        description: DES RawProcessBlock 
+        # description: DES RawProcessBlock

data-manipulation/encryption/rc4/encrypt-data-using-rc4-ksa.yml

@@ -23,16 +23,16 @@ rule:
             - or:
               - number: 0xFF
               - number: 0x100
-          description: initialize S
+          # description: initialize S
         - or:
           - match: calculate modulo 256 via x86 assembly
           # compiler may do this via zero-extended mov from 8-bit register
           - count(mnemonic(movzx)): 2 or more
-          description: modulo 256
+          # description: modulo 256
         - or:
           - mnemonic: div
           - mnemonic: idiv
-          description: modulo key length
+          # description: modulo key length
       # optimized, writes DWORDs instead of bytes
       - and:
         - or:

data-manipulation/encryption/rc4/encrypt-data-using-rc4-prga.yml

@@ -19,7 +19,7 @@ rule:
         - match: calculate modulo 256 via x86 assembly
         # compiler may do this via zero-extended mov from 8-bit register
         - count(mnemonic(movzx)): 4 or more
-        description: modulo 256
+        # description: modulo 256
       # should not call (many) functions
       - count(characteristic(calls from)): (0, 4)
       # should not be too simple

data-manipulation/hashing/murmur/hash-data-using-murmur3.yml

@@ -34,18 +34,17 @@ rule:
           - number: 13
           - optional:
             - count(characteristic(nzxor)): 3 or more
-          description: 'hash >> 16; hash >> 13; hash >> 16'
+          # description: 'hash >> 16; hash >> 13; hash >> 16'
       - and:
         # Group this two blocks under an `and` as on their own they are not
         # unique enough and would cause false positives
         - basic block:
           - and:
             - mnemonic: rol
             - number: 15 = r1
-            description: k ROL r1
+            # description: k ROL r1
         - basic block:
           - and:
             - mnemonic: rol
             - number: 13 = r2
-            description: hash ROL r2
-
+            # description: hash ROL r2

data-manipulation/hashing/tiger/hash-data-using-tiger.yml

@@ -21,4 +21,4 @@ rule:
           - count(mnemonic(shr)) : 2 or more
           - count(mnemonic(shl)) : 2 or more
           - characteristic: nzxor
-          description: tiger key schedule
+          # description: tiger key schedule

doc/format.md

@@ -225,9 +225,6 @@ There are five structural expressions that may be nested:
   - `N or more` - match at least `N` or more of the children
     - `optional` is an alias for `0 or more`, which is useful for documenting related features. See [write-file.yml](/rules/machine-access-control/file-manipulation/write-file.yml) for an example.
 
-To add context to a statement, you can use the two-line syntax `description: DESCRIPTION STRING` shown below.
-Check the [description section](#descriptions) for more details.
-
 For example, consider the following rule:
 
 ```
@@ -236,7 +233,6 @@ For example, consider the following rule:
         - number: 0xEDB88320
         - number: 8
         - characteristic: nzxor
-        description: If one of this features is not found, the rule will not match
       - api: RtlComputeCrc32
 ```
 
@@ -313,8 +309,8 @@ Regexes should be surrounded with `/` characters.
 By default, capa uses case-sensitive matching and assumes leading and trailing wildcards.
 To perform case-insensitive matching append an `i`. To anchor the regex at the start or end of a string, use `^` and/or `$`.
 
-To add context to a string, use the two-line syntax `...description: DESCRIPTION STRING` shown below because the inline syntax is not supported here.
-Check the [description section](#descriptions) for more details.
+To add context to a string, use the two-line syntax `...description: DESCRIPTION STRING` shown below. The inline syntax is not supported here.
+See the [description section](#descriptions) for more details.
 
 Examples:
 
@@ -508,7 +504,7 @@ When no active rules depend on a library rule, these the library rules will not
 
 ## descriptions
 
-All features and statements support an optional description which helps with documenting rules and provides context in capa's output.
+All features support an optional description which helps with documenting rules and provides context in capa's output.
 
 For all features except for [strings](#string), the description can be specified inline preceded by ` = `: ` = DESCRIPTION STRING`.
 For example:
@@ -518,7 +514,7 @@ For example:
 ```
 
 The inline syntax is preferred.
-For [strings](#string), [statements](#features-block) or if the description is long or contains newlines, use the two-line syntax.
+For [strings](#string) or if the description is long or contains newlines, use the two-line syntax.
 It uses the `description` tag in the following way: `description: DESCRIPTION STRING`.
 For example:
 
@@ -531,10 +527,7 @@ For example:
   - and:
     - offset: 0x50 = IMAGE_NT_HEADERS.OptionalHeader.SizeOfImage
     - offset: 0x34 = IMAGE_NT_HEADERS.OptionalHeader.ImageBase
-    description: 32-bits
   - and:
     - offset: 0x50 = IMAGE_NT_HEADERS64.OptionalHeader.SizeOfImage
     - offset: 0x30 = IMAGE_NT_HEADERS64.OptionalHeader.ImageBase
-    description: 64-bits
-  description: PE file signatures
 ```

lib/validate-credit-card-number-using-luhn-algorithm-with-lookup-table.yml

@@ -26,7 +26,7 @@ rule:
             - number: 0x5
             - number: 0x7
             - number: 0x9
-            description: Digital root lookup table
+            # description: Digital root lookup table
           - 8 or more:
             - number: 0x0
             - number: 0x1
@@ -37,17 +37,17 @@ rule:
             - number: 0xfffffffd
             - number: 0xfffffffe
             - number: 0xffffffff
-            description: Digital root lookup table via neg numbers
+            # description: Digital root lookup table via neg numbers
       - basic block:
         - or:
           - and:
             - number: 0x30
             - mnemonic: sub
-            description: Conversion of chr to int (SUB 0x30) 
+            # description: Conversion of chr to int (SUB 0x30)
           - and:
             - mnemonic: lea
             - offset: -0x30
-            description: Conversion of chr to int (LEA REG,[REG+ -0x30])
+            # description: Conversion of chr to int (LEA REG,[REG+ -0x30])
       - basic block:
         - or:
           - and:
@@ -56,7 +56,7 @@ rule:
             - number: 0xa
             - optional : 
               - mnemonic: neg
-            description: Final section returning checkum % 10
+            # description: Final section returning checkum % 10
           - and:
             - mnemonic: shr
             - mnemonic: imul
@@ -65,4 +65,4 @@ rule:
             - number: 0x2
             - optional : 
               - mnemonic: neg
-            description: Compiler optimized returning checkum % 10 
+            # description: Compiler optimized returning checkum % 10

lib/validate-credit-card-number-using-luhn-algorithm-with-no-lookup-table.yml

@@ -23,30 +23,30 @@ rule:
                 - number: 0x1 
             - mnemonic: cmp
             - number: 0x9
-            description: Digital Root check number*2 < 0x9 
+            # description: Digital Root check number*2 < 0x9
         - and:
           - basic block:
             - and:
               - mnemonic: cmp
               - number: 0x9
-              description: Compare number to 0x9 for Digital Root
+              # description: Compare number to 0x9 for Digital Root
           - basic block:
             - or:
               - mnemonic: add
               - and:
                 - mnemonic: shl
                 - number: 0x1
-              description: 2*Number for Digital Root
+              # description: 2*Number for Digital Root
       - basic block:
         - or:
           - and:
             - number: 0x30
             - mnemonic: sub
-            description: Conversion of chr to int (SUB 0x30) 
+            # description: Conversion of chr to int (SUB 0x30)
           - and:
             - mnemonic: lea
             - offset: -0x30
-            description: Conversion of chr to int (LEA REG,[REG+ -0x30])
+            # description: Conversion of chr to int (LEA REG,[REG+ -0x30])
       - basic block:
         - or:
           - and:
@@ -55,7 +55,7 @@ rule:
             - number: 0xa
             - optional : 
               - mnemonic: neg
-            description: Final section returning checkum % 10 
+            # description: Final section returning checkum % 10
           - and:
             - mnemonic: shr
             - mnemonic: imul
@@ -64,4 +64,4 @@ rule:
             - number: 0x2
             - optional : 
               - mnemonic: neg
-            description: Compiler optimized returning checkum % 10 
+            # description: Compiler optimized returning checkum % 10