Change syntax of CWE mapping reports for CWE hierarchies (use "!" for map)

- The old syntax was very confusing.  Now just report
    higher-level/lower-level, with "!" after the CWE that is actually
    the mapping.

flawfinder

@@ -798,7 +798,7 @@ c_ruleset = {
   "char|TCHAR|wchar_t":  # This isn't really a function call, but it works.
      (c_static_array, 2,
       "Statically-sized arrays can be improperly restricted, " +
-      "leading to potential overflows or other issues (CWE-119:CWE-120)",
+      "leading to potential overflows or other issues (CWE-119!/CWE-120)",
       "Perform bounds checking, use functions that limit length, " +
         "or ensure that the size is larger than the maximum possible length",
       "buffer", "", {'extract_lookahead' : 1}),
@@ -887,7 +887,7 @@ c_ruleset = {
   "realpath":
      (normal, 3,
       "This function does not protect against buffer overflows, " +
-        "and some implementations can overflow internally (CWE-120/CWE-785)",
+        "and some implementations can overflow internally (CWE-120/CWE-785!)",
       "Ensure that the destination buffer is at least of size MAXPATHLEN, and" +
         "to protect against implementation problems, the input argument should also " +
         "be checked to ensure it is no larger than MAXPATHLEN",
@@ -924,7 +924,7 @@ c_ruleset = {
       "This usually indicates a security flaw.  If an " +
       "attacker can change anything along the path between the " +
       "call to access() and the file's actual use (e.g., by moving " +
-      "files), the attacker can exploit the race condition (CWE-362/CWE-367)",
+      "files), the attacker can exploit the race condition (CWE-362/CWE-367!)",
       "Set up the correct permissions (e.g., using setuid()) and " +
       "try to open the file directly",
       "race",

flawfinder.1

@@ -758,20 +758,38 @@ The HTML report also includes hypertext links to the CWE definitions
 hosted at MITRE.
 In this way, flawfinder is designed to meet the CWE-Output requirement.
 .PP
-Many of the CWEs reported by flawfinder
+In some cases there are CWE mapping and usage challenges; here is how
-are identified in the CWE/SANS top 25 list 2011 (http://cwe.mitre.org/top25/).
+flawfinder handles them.
-Many people will want to search for CWEs in this list,
+If the same entry maps to multiple CWEs simultaneously,
-such as CWE-120 (classic buffer overflow),
+all the CWE mappings are listed as separated by commas.
-When flawfinder maps to a CWE that is more general than a top 25 item,
+This often occurs with CWE-20, Improper Input Validation;
-it lists it as more-general:more-specific
+thus the report "CWE-676, CWE-120" maps to two CWEs.
-(e.g., CWE-119:CWE-120), where more-general is the actual mapping.
+In addition, flawfinder provides additional information for those who are
-If flawfinder maps to a more specific CWE item that is a specific
+are interested in the CWE/SANS top 25 list 2011 (http://cwe.mitre.org/top25/)
-case of a top 25 item,
+when mappings are not directly to them.
-it is listed in the form top-25/more-specific (e.g., CWE-362/CWE-367),
+Many people will want to search for specific CWEs in this top 25 list,
-where the real mapping is the more specific CWE entry.
+such as CWE-120 (classic buffer overflow).
-If the same entry maps to multiple CWEs, the CWEs are separated by commas
+The challenge is that some flawfinder hits map
-(this often occurs with CWE-20, Improper Input Validation).
+to a more general CWE that would include a top 25 item, while in some
-This simplifies searching for certain CWEs.
+other cases hits map to a more specific vulnerability that is
+only a subset of a top 25 item.
+To resolve this, in some cases flawfinder will list a sequence of CWEs
+in the format "more-general/more-specific", where the CWE actually
+being mapped is followed by a "!".
+This is always done whenever a flaw is not mapped directly to
+a top 25 CWE, but the mapping is related to such a CWE.
+So "CWE-119!/CWE-120" means that the vulnerability is mapped
+to CWE-119 and that CWE-120 is a subset of CWE-119.
+In contrast, "CWE-362/CWE-367!" means that the hit is mapped to
+CWE-367, a subset of CWE-362.
+Note that this is a subtle syntax change from flawfinder version 1.31;
+in flawfinder version 1.31,
+the form "more-general:more-specific" meant what is now listed as
+"more-general!:more-specific", while
+"more-general/more-specific" meant "more-general/more-specific!".
+Tools can handle both the version 1.31 and the current format,
+if they wish, by noting that the older format did not use "!" at all.
+These mapping mechanisms simplify searching for certain CWEs.
 .PP
 CWE version 2.7 (released June 23, 2014) was used for the mapping.
 The current CWE mappings select the most specific CWE the tool can determine.
@@ -811,7 +829,7 @@ CWE-22: Improper Limitation of a Pathname to a Restricted Directory (``Path Trav
 CWE-78: Improper Neutralization of Special Elements used in an OS Command (``OS Command Injection'')*
 .IP \(bu
 CWE-119: Improper Restriction of Operations within the Bounds of a Memory Buffer
-(a parent of CWE-120*, so this is shown as CWE-119:CWE-120)
+(a parent of CWE-120*, so this is shown as CWE-119!/CWE-120)
 .IP \(bu
 CWE-120: Buffer Copy without Checking Size of Input (``Classic Buffer Overflow'')*
 .IP \(bu