Interpret policy results against a standard with IoT OWASP Top 10 exa…

…mple (#35)

* Add support for interpreting policy results against a standard with IoT OWASP Top 10 example

centrifuge_cli/policy.py

@@ -100,6 +100,7 @@ def __init__(self,
         self.sbom_json = sbom_json
         self.info_json = info_json
         self.verbose = verbose
+        self.yaml_config = None
 
     def verboseprint(self, *args):
         """
@@ -316,9 +317,9 @@ def checkSBOMRule(self, value):
         sbom = self.sbom_json
         prohibitedComponents = value.get("prohibitedComponents")
         prohibitedLicenses = []
-        for r in value.get("licenses", {}).get("prohibitedLicenses", []):
+        for r in value.get("licenses", {}).get("prohibitedLicenses", []) or []:
             prohibitedLicenses.append(re.compile(r))
-        exceptedLicenseComponents = value.get("licenses", {}).get("exceptions", [])
+        exceptedLicenseComponents = value.get("licenses", {}).get("exceptions", []) or []
         if sbom.get("count") > 0:
             for component in sbom.get("results"):
                 if component.get("name") in prohibitedComponents:
@@ -388,6 +389,36 @@ def build_json(self):
             }
             final_result.update({"reasons": policy_detail.get("reasons")})
             final_result_dict.get("results").append(final_result)
+
+        if "standard" in self.yaml_config:
+            standard = self.yaml_config["standard"]
+            sr = {
+                "name": standard["name"],
+                "description": standard["description"],
+                "compliant": "Pass",
+                "items": []
+            }
+            for mapping in standard["mappings"] or []:
+                item = {
+                    "item": mapping["item"],
+                    "title": mapping["title"],
+                    "description": mapping["description"],
+                    "compliant": "Pass",
+                    "results": []
+                }
+                for policy in mapping["policies"] or []:
+                    # Check if policy passed or failed
+                    if policy in POLICY_DETAIL_MAPPING:
+                        compliant = POLICY_DETAIL_MAPPING[policy].get("status")
+                        item.get("results").append({
+                            "policy": POLICY_DETAIL_MAPPING[policy].get("name"),
+                            "compliant": compliant
+                        })
+                        if compliant != "Pass":
+                            item["compliant"] = "Fail"
+                            sr["compliant"] = "Fail"
+                sr.get("items").append(item)
+            final_result_dict["standard"] = sr
         return final_result_dict
 
     def generate_json(self):
@@ -402,10 +433,10 @@ def generate_report(self, report_template):
     def check_rules(self, config_file):
         with open(config_file, 'r') as stream:
             try:
-                res = yaml.safe_load(stream)
+                self.yaml_config = yaml.safe_load(stream)
                 for _, rule in enumerate(POLICY_DETAIL_MAPPING):
-                    if rule in res['rules']:
-                        self.checkRule(rule, res['rules'][rule])
+                    if rule in self.yaml_config['rules']:
+                        self.checkRule(rule, self.yaml_config['rules'][rule])
                     else:
                         POLICY_DETAIL_MAPPING.get(rule).update({"status": "No Policy Specified"})
             except yaml.YAMLError as exc:

docs/IoT-OWASP-Top10-policy.mustache

@@ -0,0 +1,51 @@
+<style>
+  #Pass {
+    color:green;
+  }
+  #Fail {
+    color:red;
+  }
+</style>
+<h1>Centrifuge Standard Compliance Report</h1>
+<b>Standard: </b>{{standard.name}}<br/>
+<b>Description: </b>{{standard.description}}<br/>
+<br/>
+<b>Vendor: </b>{{info.vendor}}<br/>
+<b>Device: </b>{{info.device}}<br/>
+<b>Version: </b>{{info.version}}<br/>
+
+<h2>Overall: <span id="{{standard.compliant}}">{{standard.compliant}}</span></h2>
+
+<h3><b>Standard Compliance Detail</b></h3>
+<ul>
+  {{#standard.items}}
+  <li>
+    <h3>{{title}} : <span id="{{compliant}}">{{compliant}}</span></h3>
+    {{description}}
+    <br/>
+    <ul>
+      {{#results}}
+      <li>
+        {{policy}} : <span id="{{compliant}}">{{compliant}}</span>
+      </li>
+      {{/results}}
+    </ul>
+  </li>
+  {{/standard.items}}
+</ul>
+
+<br/>
+<h3><b>Centrifuge Policy Compliance</b></h3>
+<ul>
+  {{#results}}
+  <li>
+    <h3>{{name}} : <span id="{{compliant}}">{{compliant}}</span></h3>
+    <ul>
+      {{#reasons}}
+        <li>{{.}}</li>
+      {{/reasons}}
+      <br/>
+    </ul>
+  </li>
+  {{/results}}
+</ul>

docs/IoT-OWASP-Top10-policy.yml

@@ -0,0 +1,164 @@
+# version of the policy specification
+policyVersion: 1.0
+
+# This policy file maps the IoT OWASP Top 10 (https://owasp.org/www-project-internet-of-things/)
+# to the security analysis provided by Centrifuge. In some areas where OWASP is not specific
+# we provide our interpretation (for example, the definition of "out of date components").
+
+# Standard files have two sections: 
+#   rules: which define the policy for individual Centrifuge analyzers to pass or fail
+#   standard: which defines the standard and maps items in the standard to applicable rules
+
+# For rules where you have confirmed there is not an issue you can add the item as an exception
+# (for example private keys) 
+
+rules:
+
+  # Expired certificates can lead to insecure network services (I2) and
+  # insecure Data Transfer and Storage (I7)
+  certificates:
+    expired:
+      allowed: false
+
+      # also check for certificates expiring in upcoming period
+      prevent_expiring: in 6 months
+
+    # optional list of files that are omitted from this rule
+    exceptions: 
+
+  # Use of private keys could results in compromised public keys or 
+  # insecure storage of user data. Impacts Insecure Network Services (I2),
+  # Insecure Data Transfer and Storage (I7)
+  privateKeys:
+    allowed: false
+    # optional list of files that are omitted from this rule
+    exceptions:
+      - /usr/*
+
+  # Presence of hardcoded accounts and/or weak / guessable passwords (I1)
+  passwordHashes:
+    # whether defined user accounts are allowed or not
+    allowUserAccounts: false
+
+    # any hashes with the following algorithms will fail the policy check
+    weakAlgorithms:
+      - des
+      - md5
+
+  # Presence of critical flaws (potential 0-days) potentially create
+  # Insecure Network Services (I2), as well as Insecure or Outadated Components (I5)
+  code:
+    flaws:
+      # allow any potential flaws
+      allowed: true
+
+      # allow critical (emulated) flaws
+      allowCritical: false
+
+    # optional list of files that are omitted from this rule
+    exceptions:
+
+  # Evaluation of 3rd party components for Insecure or Outdated Components (I5)
+  # Interpreting Insecure as CVSS >= 7.0, and outdated is components with CVEs > 2 years
+  guardian:
+    # any CVEs found at or above this threshold will cause the policy check to fail
+    cvssScoreThreshold: 7.0
+
+    # any CVEs from this year or older will cause the policy check to fail
+    # either put year (i.e., 2017) or # years (i.e., 2 would fail 2018 or earlier CVEs in 2020)
+    cveAgeThreshold: 2
+
+    # optional list of files that are omitted from this rule
+    exceptions:
+
+  # Binary hardening is recommended best practice to provide secure network services and components (I2, I5)
+  # enabling this will be enforce binary hardening on all executables in the firmware. Optionally use
+  # incldue directive to whitelist check on specific directories
+  binaryHardening:
+    # a list of hardening features required for ELF binaries
+    # supported features: NX, PIE, RELRO, CANARY, STRIPPED
+    requiredFeatures:
+      - NX
+      - PIE
+      - RELRO
+      - CANARY
+      - STRIPPED
+    # optional whitelist of binaries to check for above features.
+    # if omitted, all binaries will be checked
+    include:
+
+  # Detection of known backdoors, exploits and malware results in Insecure Network Services (I2)
+  securityChecklist:
+    # any security checklist results should result in failure in most policies
+    allowed: false
+
+  # Debug / network sniffing components should not be included in production firmware as best practice
+  # relates to Insecure Components (I5)
+  sbom:
+    # components that are not allowed in firmware
+    prohibitedComponents:
+      - tcpdump
+      - libpcap
+      - gdbserver
+
+    # Licensing is not part of OWASP standard 
+    licenses:
+      # use SPDX license identifiers (https://spdx.org/licenses/)
+      # can use regex
+      prohibitedLicenses:
+
+      # components approved to use prohibited licenses
+      exceptions:
+
+standard:
+  name: IoT OWASP Top 10
+
+  description: >
+    The OWASP Foundation publishes a list of the Top 10 things to
+    avoid when building, deploying or managing IoT systems 
+    (https://owasp.org/www-project-internet-of-things/). Centrifuge
+    security policies map to a subset of the Top 10 rules.
+  
+  mappings:
+    - item: I1
+      title: I1 - Weak, Guessable, or Hardcoded Passwords
+      description: >
+        Centrifuge detects hard coded accounts and weak passwords.
+      policies:
+        - passwordHashes
+
+    - item: I2
+      title: I2 - Insecure Network Services
+      description: >
+        Centrifuge detects a number of issues which can be a source
+        of insecure networking services, including expired certificates,
+        use of private keys, poor code, lack of binary hardening, or
+        known backdoors and exploits. 
+      policies:
+        - certificates
+        - privateKeys
+        - code
+        - binaryHardening
+        - securityChecklist
+
+    - item: I5
+      title: I5 - Use of Insecure or Outdated Components
+      description: >
+        Centrifuge detects components with known vulnerabilities,
+        poor code, lack of binary hardening and components that
+        should not be included in production firmware.
+      policies:
+        - code
+        - guardian
+        - binaryHardening
+        - sbom
+
+    - item: I7
+      title: I7 - Insecure Data Transfer and Storage
+      description: >
+        Centrifuge detects the presence of expired certificates and
+        private keys which, unless excepted after manual review could
+        result in insecure data transfer and storage.
+      policies:
+        - certificates
+        - privateKeys

docs/POLICY.md

@@ -4,6 +4,9 @@ The `policy` subcommand is a tool that enables users to apply their own policy r
 
 This command line tool takes a policy file that defines the policy rules that you want to apply. It gathers report data via the Centrifuge REST API, for which you have to supply your Centrifuge API authentication token, and generates an output file containing the results of the policy as it applies to the given Centrifuge report.
 
+Optionally, the policy rules can be mapped against a standard such as the OWASP IoT Top 10. See the section below
+on defining a standard for more details
+
 ## Prerequisites
 
 Before you begin, ensure you have met the following requirements:
@@ -93,7 +96,7 @@ Firmware images with reported SSL certificates that are expired will fail this p
       # also check for certificates expiring in upcoming period
       prevent_expiring: in 6 months
 
-      # optional list of files exempt from this rule (i.e. expired certificates in /etc/ssl are ok). 
+      # optional list of files exempt from this rule (i.e. expired certificates in /etc/ssl are ok).
       exceptions:
         - /etc/ssl/*
 ```
@@ -206,7 +209,7 @@ like GPL, but define exceptions for specific components that have been approved
       - libpcap
       - gdbserver
 
-    # components using prohibited licenses 
+    # components using prohibited licenses
     licenses:
       # use SPDX license identifiers (https://spdx.org/licenses/)
       # can use regex
@@ -219,3 +222,45 @@ like GPL, but define exceptions for specific components that have been approved
         - busybox
         - dnsmasq
 ```
+
+### Mapping policy results to a standard
+
+Policy results can be mapped to a security standard. Each element of a standard that relates to a Centrifuge
+analysis result can be defined, and then the policy rules that apply to that standard are listed. If the
+policy rule fails, then the element of the standard also fails.
+
+This is optional - standard mapping is only performed if the `standard` tag is present.
+
+Here is an example mapping the two of the elements of the OWASP IoT Top 10 to Centrifuge policy results:
+```
+standard:
+  name: IoT OWASP Top 10
+
+  description: >
+    The OWASP Foundation publishes a list of the Top 10 things to
+    avoid when building, deploying or managing IoT systems 
+    (https://owasp.org/www-project-internet-of-things/). Centrifuge
+    security policies map to a subset of the Top 10 rules.
+  
+  mappings:
+    - item: I1
+      title: I1 - Weak, Guessable, or Hardcoded Passwords
+      description: >
+        Centrifuge detects hard coded accounts and weak passwords.
+      policies:
+        - passwordHashes
+
+    - item: I2
+      title: I2 - Insecure Network Services
+      description: >
+        Centrifuge detects a number of issues which can be a source
+        of insecure networking services, including expired certificates,
+        use of private keys, poor code, lack of binary hardening, or
+        known backdoors and exploits. 
+      policies:
+        - certificates
+        - privateKeys
+        - code
+        - binaryHardening
+        - securityChecklist
+```