Merge pull request #580 from nabla-c0d3/dev

5.0.6

api_sample.py

@@ -1,4 +1,6 @@
+from datetime import datetime
 from pathlib import Path
+from typing import List
 
 from sslyze import (
     Scanner,
@@ -7,6 +9,8 @@
     ServerNetworkLocation,
     ScanCommandAttemptStatusEnum,
     ServerScanStatusEnum,
+    ServerScanResult,
+    ServerScanResultAsJson,
 )
 from sslyze.errors import ServerHostnameCouldNotBeResolved
 from sslyze.scanner.scan_command_attempt import ScanCommandAttempt
@@ -20,6 +24,9 @@ def _print_failed_scan_command_attempt(scan_command_attempt: ScanCommandAttempt)
 
 
 def main() -> None:
+    print("=> Starting the scans")
+    date_scans_started = datetime.utcnow()
+
     # First create the scan requests for each server that we want to scan
     try:
         all_scan_requests = [
@@ -36,7 +43,9 @@ def main() -> None:
     scanner.queue_scans(all_scan_requests)
 
     # And retrieve and process the results for each server
+    all_server_scan_results = []
     for server_scan_result in scanner.get_results():
+        all_server_scan_results.append(server_scan_result)
         print(f"\n\n****Results for {server_scan_result.server_location.hostname}****")
 
         # Were we able to connect to the server and run the scan?
@@ -92,10 +101,34 @@ def main() -> None:
 
         # etc... Other scan command results to process are in server_scan_result.scan_result
 
+    # Lastly, save the all the results to a JSON file
+    json_file_out = Path("api_sample_results.json")
+    print(f"\n\n=> Saving scan results to {json_file_out}")
+    example_json_result_output(json_file_out, all_server_scan_results, date_scans_started, datetime.utcnow())
+
+    # And ensure we are able to parse them
+    print(f"\n\n=> Parsing scan results from {json_file_out}")
+    example_json_result_parsing(json_file_out)
+
+
+def example_json_result_output(
+    json_file_out: Path,
+    all_server_scan_results: List[ServerScanResult],
+    date_scans_started: datetime,
+    date_scans_completed: datetime,
+) -> None:
+    json_output = SslyzeOutputAsJson(
+        server_scan_results=[ServerScanResultAsJson.from_orm(result) for result in all_server_scan_results],
+        invalid_server_strings=[],  # Not needed here - specific to the CLI interface
+        date_scans_started=date_scans_started,
+        date_scans_completed=date_scans_completed,
+    )
+    json_output_as_str = json_output.json(sort_keys=True, indent=4, ensure_ascii=True)
+    json_file_out.write_text(json_output_as_str)
+
 
-def example_json_result_parsing() -> None:
+def example_json_result_parsing(results_as_json_file: Path) -> None:
     # SSLyze scan results serialized to JSON were saved to this file using --json_out
-    results_as_json_file = Path(__file__).parent / "tests" / "json_tests" / "sslyze_output.json"
     results_as_json = results_as_json_file.read_text()
 
     # These results can be parsed

docs/documentation/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 97b3451be6c04378175579402a82d6be
+config: 710e1f17bd6b1026352fe79ab79c95d4
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/documentation/_static/documentation_options.js

@@ -1,6 +1,6 @@
 var DOCUMENTATION_OPTIONS = {
     URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
-    VERSION: '5.0.3',
+    VERSION: '5.0.6',
     LANGUAGE: 'None',
     COLLAPSE_INDEX: false,
     BUILDER: 'html',

docs/documentation/available-scan-commands.html

@@ -6,7 +6,7 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
 
-    <title>Appendix: Scan Commands &#8212; SSLyze 5.0.3 documentation</title>
+    <title>Appendix: Scan Commands &#8212; SSLyze 5.0.6 documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
     <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
@@ -525,7 +525,7 @@ <h3>Result class<a class="headerlink" href="#result-class" title="Permalink to t
 
 <dl class="py attribute">
 <dt class="sig sig-object py" id="sslyze.TrustStore.ev_oids">
-<span class="sig-name descname"><span class="pre">ev_oids</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">Optional</span><span class="p"><span class="pre">[</span></span><span class="pre">List</span><span class="p"><span class="pre">[</span></span><span class="pre">cryptography.hazmat._oid.ObjectIdentifier</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span></em><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">None</span></em><a class="headerlink" href="#sslyze.TrustStore.ev_oids" title="Permalink to this definition">¶</a></dt>
+<span class="sig-name descname"><span class="pre">ev_oids</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">Optional</span><span class="p"><span class="pre">[</span></span><span class="pre">List</span><span class="p"><span class="pre">[</span></span><span class="pre">ObjectIdentifier</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span></em><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">None</span></em><a class="headerlink" href="#sslyze.TrustStore.ev_oids" title="Permalink to this definition">¶</a></dt>
 <dd></dd></dl>
 
 <dl class="py method">
@@ -1441,7 +1441,7 @@ <h3 id="searchlabel">Quick search</h3>
       <div class="clearer"></div>
     </div>
     <div class="footer">
-      &copy;Copyright 2021 Alban Diquet.
+      &copy;Copyright 2022 Alban Diquet.
 
       |
       Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a>

docs/documentation/genindex.html

@@ -5,7 +5,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Index &#8212; SSLyze 5.0.3 documentation</title>
+    <title>Index &#8212; SSLyze 5.0.6 documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
     <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
@@ -640,7 +640,7 @@ <h3 id="searchlabel">Quick search</h3>
       <div class="clearer"></div>
     </div>
     <div class="footer">
-      &copy;Copyright 2021 Alban Diquet.
+      &copy;Copyright 2022 Alban Diquet.
 
       |
       Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a>

docs/documentation/index.html

@@ -6,7 +6,7 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
 
-    <title>SSLyze &#8212; SSLyze 5.0.3 documentation</title>
+    <title>SSLyze &#8212; SSLyze 5.0.6 documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
     <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
@@ -34,7 +34,7 @@
 
   <section id="sslyze">
 <h1><a class="toc-backref" href="#id1">SSLyze</a><a class="headerlink" href="#sslyze" title="Permalink to this headline">¶</a></h1>
-<p>Release 5.0.3</p>
+<p>Release 5.0.6</p>
 <a class="reference external image-reference" href="https://pepy.tech/project/sslyze"><img alt="https://pepy.tech/badge/sslyze" src="https://pepy.tech/badge/sslyze" /></a>
 <a class="reference external image-reference" href="https://pypi.org/project/sslyze/"><img alt="https://img.shields.io/pypi/l/sslyze.svg" src="https://img.shields.io/pypi/l/sslyze.svg" /></a>
 <a class="reference external image-reference" href="https://pypi.org/project/sslyze/"><img alt="https://img.shields.io/pypi/pyversions/sslyze.svg" src="https://img.shields.io/pypi/pyversions/sslyze.svg" /></a>
@@ -85,7 +85,9 @@ <h2><a class="toc-backref" href="#id4">Exporting and processing scan results in
 <div class="toctree-wrapper compound">
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="json-output.html">Exporting and processing scan results in JSON</a><ul>
-<li class="toctree-l2"><a class="reference internal" href="json-output.html#json-output-when-using-the-cli">JSON output when using the CLI</a></li>
+<li class="toctree-l2"><a class="reference internal" href="json-output.html#exporting-results-to-json-when-using-the-cli">Exporting results to JSON when using the CLI</a></li>
+<li class="toctree-l2"><a class="reference internal" href="json-output.html#exporting-results-to-json-when-using-the-api">Exporting results to JSON when using the API</a></li>
+<li class="toctree-l2"><a class="reference internal" href="json-output.html#parsing-the-json-output">Parsing the JSON output</a></li>
 </ul>
 </li>
 </ul>
@@ -181,7 +183,7 @@ <h3 id="searchlabel">Quick search</h3>
       <div class="clearer"></div>
     </div>
     <div class="footer">
-      &copy;Copyright 2021 Alban Diquet.
+      &copy;Copyright 2022 Alban Diquet.
 
       |
       Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a>

docs/documentation/json-output.html

@@ -6,7 +6,7 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
 
-    <title>Exporting and processing scan results in JSON &#8212; SSLyze 5.0.3 documentation</title>
+    <title>Exporting and processing scan results in JSON &#8212; SSLyze 5.0.6 documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
     <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
@@ -39,16 +39,39 @@ <h1>Exporting and processing scan results in JSON<a class="headerlink" href="#ex
 parse JSON scan results; it can be used to process the results of SSLyze scans in a separate Python program.</p>
 <p>A schema of the JSON output is available in the code repository at
 <a class="reference external" href="https://github.com/nabla-c0d3/sslyze/blob/release/json_output_schema.json">./json_output_schema.json</a>.</p>
-<section id="json-output-when-using-the-cli">
-<h2>JSON output when using the CLI<a class="headerlink" href="#json-output-when-using-the-cli" title="Permalink to this headline">¶</a></h2>
+<section id="exporting-results-to-json-when-using-the-cli">
+<h2>Exporting results to JSON when using the CLI<a class="headerlink" href="#exporting-results-to-json-when-using-the-cli" title="Permalink to this headline">¶</a></h2>
 <p>When using the CLI, the scan results can be exported to a JSON file using the <code class="docutils literal notranslate"><span class="pre">--json_out</span></code> option:</p>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ python -m sslyze www.google.com www.facebook.com --json_out=result.json
 </pre></div>
 </div>
-<p>The generated JSON file can then be parsed using the <code class="docutils literal notranslate"><span class="pre">SslyzeOutputAsJson.from_file()</span></code> method:</p>
-<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">example_json_result_parsing</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
+<p>The generated JSON file can then be parsed, as described in the “Parsing the JSON output” section.</p>
+</section>
+<section id="exporting-results-to-json-when-using-the-api">
+<h2>Exporting results to JSON when using the API<a class="headerlink" href="#exporting-results-to-json-when-using-the-api" title="Permalink to this headline">¶</a></h2>
+<p>When using the API, the scan results can be exported to a JSON file using the <code class="docutils literal notranslate"><span class="pre">SslyzeOutputAsJson.from_orm()</span></code> method:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">example_json_result_output</span><span class="p">(</span>
+    <span class="n">json_file_out</span><span class="p">:</span> <span class="n">Path</span><span class="p">,</span>
+    <span class="n">all_server_scan_results</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="n">ServerScanResult</span><span class="p">],</span>
+    <span class="n">date_scans_started</span><span class="p">:</span> <span class="n">datetime</span><span class="p">,</span>
+    <span class="n">date_scans_completed</span><span class="p">:</span> <span class="n">datetime</span><span class="p">,</span>
+<span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
+    <span class="n">json_output</span> <span class="o">=</span> <span class="n">SslyzeOutputAsJson</span><span class="p">(</span>
+        <span class="n">server_scan_results</span><span class="o">=</span><span class="p">[</span><span class="n">ServerScanResultAsJson</span><span class="o">.</span><span class="n">from_orm</span><span class="p">(</span><span class="n">result</span><span class="p">)</span> <span class="k">for</span> <span class="n">result</span> <span class="ow">in</span> <span class="n">all_server_scan_results</span><span class="p">],</span>
+        <span class="n">invalid_server_strings</span><span class="o">=</span><span class="p">[],</span>  <span class="c1"># Not needed here - specific to the CLI interface</span>
+        <span class="n">date_scans_started</span><span class="o">=</span><span class="n">date_scans_started</span><span class="p">,</span>
+        <span class="n">date_scans_completed</span><span class="o">=</span><span class="n">date_scans_completed</span><span class="p">,</span>
+    <span class="p">)</span>
+    <span class="n">json_output_as_str</span> <span class="o">=</span> <span class="n">json_output</span><span class="o">.</span><span class="n">json</span><span class="p">(</span><span class="n">sort_keys</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">indent</span><span class="o">=</span><span class="mi">4</span><span class="p">,</span> <span class="n">ensure_ascii</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
+    <span class="n">json_file_out</span><span class="o">.</span><span class="n">write_text</span><span class="p">(</span><span class="n">json_output_as_str</span><span class="p">)</span>
+</pre></div>
+</div>
+</section>
+<section id="parsing-the-json-output">
+<h2>Parsing the JSON output<a class="headerlink" href="#parsing-the-json-output" title="Permalink to this headline">¶</a></h2>
+<p>A JSON results file generated by SSLyze can then be parsed using the <code class="docutils literal notranslate"><span class="pre">SslyzeOutputAsJson.from_file()</span></code> method:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">example_json_result_parsing</span><span class="p">(</span><span class="n">results_as_json_file</span><span class="p">:</span> <span class="n">Path</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
     <span class="c1"># SSLyze scan results serialized to JSON were saved to this file using --json_out</span>
-    <span class="n">results_as_json_file</span> <span class="o">=</span> <span class="n">Path</span><span class="p">(</span><span class="vm">__file__</span><span class="p">)</span><span class="o">.</span><span class="n">parent</span> <span class="o">/</span> <span class="s2">&quot;tests&quot;</span> <span class="o">/</span> <span class="s2">&quot;json_tests&quot;</span> <span class="o">/</span> <span class="s2">&quot;sslyze_output.json&quot;</span>
     <span class="n">results_as_json</span> <span class="o">=</span> <span class="n">results_as_json_file</span><span class="o">.</span><span class="n">read_text</span><span class="p">()</span>
 
     <span class="c1"># These results can be parsed</span>
@@ -102,7 +125,9 @@ <h3>Navigation</h3>
 </ul>
 <ul class="current">
 <li class="toctree-l1 current"><a class="current reference internal" href="#">Exporting and processing scan results in JSON</a><ul>
-<li class="toctree-l2"><a class="reference internal" href="#json-output-when-using-the-cli">JSON output when using the CLI</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#exporting-results-to-json-when-using-the-cli">Exporting results to JSON when using the CLI</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#exporting-results-to-json-when-using-the-api">Exporting results to JSON when using the API</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#parsing-the-json-output">Parsing the JSON output</a></li>
 </ul>
 </li>
 </ul>
@@ -142,7 +167,7 @@ <h3 id="searchlabel">Quick search</h3>
       <div class="clearer"></div>
     </div>
     <div class="footer">
-      &copy;Copyright 2021 Alban Diquet.
+      &copy;Copyright 2022 Alban Diquet.
 
       |
       Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a>

docs/documentation/py-modindex.html

@@ -5,7 +5,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Python Module Index &#8212; SSLyze 5.0.3 documentation</title>
+    <title>Python Module Index &#8212; SSLyze 5.0.6 documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
     <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
@@ -112,7 +112,7 @@ <h3 id="searchlabel">Quick search</h3>
       <div class="clearer"></div>
     </div>
     <div class="footer">
-      &copy;Copyright 2021 Alban Diquet.
+      &copy;Copyright 2022 Alban Diquet.
 
       |
       Powered by <a href="http://sphinx-doc.org/">Sphinx 4.4.0</a>