recog 3.0.3 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f61ccb4f953facea4bbf95ccbd3deb144d8f0763d9be1355cba70a6eb4dc9c79
-  data.tar.gz: 8fa728463dfc0f3dd783fd3f535965b70e62f6e47eb8960e269076e6ddf3c43f
+  metadata.gz: ea0370676af55fb1b15cd5161a97c6beb3320d61809faaeb2bcfd51581713459
+  data.tar.gz: 4c6682d29ef90372772d9aea9cd562a69ca0233ec72fccd0eb644049b7faf37b
 SHA512:
-  metadata.gz: 1f2ed5453f4dc800bcf750592ca16ec25f89c2e93ec7528b2a2a71bada7399bd5d3ea149acb1888006826d8fea0b4a6186b3c7ea4a519febebe99e3be8c6efcf
-  data.tar.gz: c515c0183b55cf8a38dd03d2865d7ef208c75930854b00f69ade77494b0fe0f7162d244a5806d9451ec7442675c93c2070d2a59ef25d1355b241f4a0922c5d7a
+  metadata.gz: 2f54060445501ddd5678b3cce4b5d252aebd9dfb605f9ef6bc4454ad9dd9b269d69f4534a554337dfbe9de911f90cabacf5e2f07db90ec6d2b29280940ed833d
+  data.tar.gz: 5302fe685c534a10477d38c1fe9bd81cd6a3f968a98a72fdf0060dbc24dc4b28b7a90fb03245c6ae4a8540a1948d870e6bca006f2efa9bd89e254682ec5daf70

data/README.md

@@ -74,8 +74,6 @@ At least one `example` element should be present, however multiple `example` ele
 
 tests that `RomSShell_4.62` matches the provided regular expression and that the value of `service.version` is 4.62.
 
-The `param` elements contain a `pos` attribute, which indicates what capture field from the `pattern` should be extracted, or `0` for a static string. The `name` attribute is the key that will be reported in the case of a successful match and the `value` will either be a static string for `pos` values of `0` or missing and taken from the captured field.
-
 The `example` string can be base64 encoded to permit the use of unprintable characters.  To signal this to Recog an `_encoding` attribute with the value of `base64` is added to the `example` element.  Based64 encoded text that is longer than 80 characters may be wrapped with newlines as shown below to aid in readability.
 
 ```xml
@@ -102,6 +100,51 @@ They can then be loaded using the `_filename` attribute:
 
 This is useful for long examples.
 
+The `param` elements contain a `pos` attribute, which indicates what capture field
+from the `pattern` should be extracted, or `0` for a static string. The `name` attribute
+is the key that will be reported in the case of a successful match and the `value`
+will either be a static string for `pos` values of `0` or missing and taken from the
+captured field.
+
+The `value` attribute supports interpolation of data from other fields. This is
+often useful when capturing the value for `hw.product` via regex and re-using this
+value in `os.product`.
+
+Here is an example from`http_servers.xml` where `hw.product` is captured and reused.
+
+```xml
+  <fingerprint pattern="^Eltex (TAU-\d+[A-Z]*(?:\.IP)?)$">
+    <description>Eltex TAU model VoIP gateway</description>
+    <example hw.product="TAU-72">Eltex TAU-72</example>
+    <example hw.product="TAU-1.IP">Eltex TAU-1.IP</example>
+    <param pos="0" name="os.vendor" value="Eltex"/>
+    <param pos="0" name="os.product" value="{hw.product} Firmware"/>
+    <param pos="0" name="os.device" value="VoIP Gateway"/>
+    <param pos="0" name="hw.vendor" value="Eltex"/>
+    <param pos="1" name="hw.product"/>
+    <param pos="0" name="hw.device" value="VoIP Gateway"/>
+  </fingerprint>
+```
+
+There is special handling for temporary attributes that have a name starting with
+`_tmp.`. These attributes can be used for interpolation but are not emitted in the
+output. This is useful when a particular product name is inconsistent in various
+banners, vendor marketing, or with NIST values when trying to generate CPEs. In
+these cases the useful parts of the banner can be extracted and a new value
+crafted without cluttering the data emitted by a match.
+
+```xml
+<fingerprint pattern="^foo baz switchThing-(\d{4})$">
+  <description>NetCorp NX series switches</description>
+  <example hw.product="NX8200">foo baz switchThing-8200</example>
+  <param pos="0" name="hw.vendor" value="NetCorp"/>
+  <param pos="0" name="hw.product" value="NX{_tmp.001}"/>
+  <param pos="2" name="_tmp.001"/>
+</fingerprint>
+```
+
+These temporary attributes are not tracked in the `identifiers/fields.txt`.
+
 [^back to top](#recog-ruby-a-recognition-framework)
 
 ## Contributing

data/lib/recog/fingerprint.rb

@@ -136,6 +136,13 @@ class Fingerprint
       end
     end
 
+    # After performing interpolation, remove temporary keys from results
+    result.each_pair do |k, _|
+      if k.start_with?('_tmp.')
+        result.delete(k)
+      end
+    end
+
     return result
   end
 
@@ -230,9 +237,9 @@ class Fingerprint
       end
     end
 
-    # alert on untested parameters
+    # alert on untested parameters unless they are temporary
     capture_group_used.each do |param_name, param_used|
-      if !param_used
+      if !param_used && !param_name.start_with?('_tmp.')
         message = "'#{@name}' is missing an example that checks for parameter '#{param_name}' " +
                   "which is derived from a capture group"
         yield :fail, message

data/lib/recog/version.rb

@@ -1,3 +1,3 @@
 module Recog
-  VERSION = '3.0.3'
+  VERSION = '3.1.0'
 end