tls-map 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83caecd8dd0a4d170d686c141a7b39860f99f29f2bc4e436418eca7b877807ff
-  data.tar.gz: 7a3a245f86067d8c9d59fb8f75b207e320c09d11b701624adf86842da27afc4e
+  metadata.gz: 41d9e4f95a9edfc3fbb1e8c72e3e15ab6d20c40621576b7829ce75c057141329
+  data.tar.gz: 71add869718efbad2b14e3da7ace2d5967013455daee5d310b89443d1a5d5a70
 SHA512:
-  metadata.gz: fa1240ae951c33a26838ee04f15b55e03ec452cd9b03790394ebee99a142acc91b0bda3074f95bf97f495d3b553ef8363c17221d2c519772690ca5573954a80d
-  data.tar.gz: cd72c3ff9281bfe37a7f866a33fc73340dbd70f37ee370cfd3a01a1742760d3f0f110a778ded5b03aca8b01873832f66ca24ebeef51ba3cab09d57c3e81b5377
+  metadata.gz: d03f9a2d71f71290c75bd5c2f8a296c7af7ab571f5ecc7cc1da7351ba65edf57a44b14aa697079b784ec0ed0df4df95a15be8a0bc9a6ec5d1f757a995809cd2c
+  data.tar.gz: 440522feebc7dbd057ec8abb9e1ad75b44567c861b97b2871f67e6836f7482db4d9ff5d4a4cf9ac081a51fe176a0b0ecbe2e818ccf40e1459fad6c60f3f17172

data/bin/tls-map

@@ -11,26 +11,31 @@ require 'docopt'
 require 'paint'
 
 doc = <<~DOCOPT
-  TLS map
+  TLS map #{TLSmap::VERSION}
 
   Usage:
     tls-map search <critera> <term> [-o <output> --force -e -a] [--no-color --debug]
     tls-map export <filename> <format> [--force] [--debug]
+    tls-map extract <filename> <format> [--no-color --debug]
     tls-map update [--debug]
     tls-map -h | --help
     tls-map --version
 
-  Search options: (offline)
+  Search options: (offline) search and translate cipher names between SSL/TLS libraries
     <critera>               The type of term. Accepted values: codepoint, iana, openssl, gnutls, nss.
     <term>                  The cipher algorithm name.
     -o, --output <output>   Displayed fields. Accepted values: all, codepoint, iana, openssl, gnutls, nss. [default: all]
     -e, --extended          (Online) Display additional information about the cipher (requires output = all or iana)
     -a, --acronym           (Online) Display full acronym name (requires -e / --extended option)
 
-  Export options: (offline)
+  Export options: (offline) export the list of all ciphers (mapping) in various formats
     <filename>              The output file name to write to.
     <format>                Supported formats: markdown (a markdown table), json_pretty (expanded JSON), json_compact (minified JSON), marshal (Ruby marshalized hash).
 
+  Extract options: (offline) extract ciphers from external tools output file
+    <filename>              The external tool output file
+    <format>                Supported formats: sslyze, sslscan2, testssl, ssllabs-scan (check the documentation for the expected file format)
+
   Update options: (online) DANGEROUS, will break database integrity, force option will be required
 
   Other options:
@@ -79,6 +84,13 @@ begin
     cli = TLSmap::CLI.new(args['--force'])
     cli.export(args['<filename>'], args['<format>'].to_sym)
     puts "#{args['<filename>']} exported"
+  elsif args['extract']
+    extractor = TLSmap::App::Extractor.new
+    ciphers = extractor.parse(args['<format>'], args['<filename>'])
+    ciphers.each do |k, v|
+      puts Paint[k, :blue] unless v.empty?
+      puts Paint[v.join("\n"), :white] unless v.empty?
+    end
   elsif args['update']
     cli = TLSmap::CLI.new
     cli.update

data/lib/tls_map.rb

@@ -11,6 +11,7 @@ require 'tls_map/gnutls'
 require 'tls_map/nss'
 require 'tls_map/output'
 require 'tls_map/ciphersuiteinfo'
+require 'tls_map/extractor'
 
 # TLS map module
 module TLSmap
@@ -36,13 +37,13 @@ module TLSmap
     end
 
     # Search for corresponding cipher algorithms in other libraries
-    # @param critera [Symbol] The type of +term+.
-    #   Accepted values: +:codepoint+, +:iana+, +:openssl+, +:gnutls+, +:nss+.
+    # @param critera [Symbol] The type of `term`.
+    #   Accepted values: `:codepoint`, `:iana`, `:openssl`, `:gnutls`, `:nss`.
     # @param term [String] The cipher algorithm name.
     # @param output [Symbol] The corresponding type to be included in the return value.
-    #   Accepted values: +:all+ (default), +:codepoint+, +:iana+, +:openssl+,
-    #   +:gnutls+, +:nss+.
-    # @return [Hash] The corresponding type matching +term+.
+    #   Accepted values: `:all` (default), `:codepoint`, `:iana`, `:openssl`,
+    #   `:gnutls`, `:nss`.
+    # @return [Hash] The corresponding type matching `term`.
     def search(critera, term, output = :all)
       @tls_map.each do |alg|
         term = term.upcase if critera == :codepoint

data/lib/tls_map/ciphersuiteinfo.rb

@@ -10,11 +10,13 @@ require 'yaml'
 module TLSmap
   class App
     # Partial wrapper around ciphersuite.info API to get extra info about a cipher
+    #
     # Documentation:
-    #   - https://ciphersuite.info/blog/2019/04/05/how-to-use-our-api/
-    #   - https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md
-    #   - https://ciphersuite.info/api/
-    #   - https://github.com/hcrudolph/ciphersuite.info
+    #
+    # - https://ciphersuite.info/blog/2019/04/05/how-to-use-our-api/
+    # - https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md
+    # - https://ciphersuite.info/api/
+    # - https://github.com/hcrudolph/ciphersuite.info
     class Extended
       # Root URL of Cipher Suite Info
       ROOT = 'https://ciphersuite.info/'
@@ -57,8 +59,8 @@ module TLSmap
       # Retrieve advanced about a cipher on Cipher Suite Info API and enhanced it
       # @param iana_name [String] IANA cipher name
       # @return [Hash] Hash containing advanced information. The keys are the same as {DICO}. All valeus are string
-      #   except +vulns+ which is an array of hashes containing two keys: +:severity+ (integer) and +:description+
-      #   (string). Each hash in +vulns+ correspond to a vulnerability.
+      #   except `vulns` which is an array of hashes containing two keys: `:severity` (integer) and `:description`
+      #   (string). Each hash in `vulns` correspond to a vulnerability.
       def extend(iana_name) # rubocop:disable Metrics/MethodLength
         obj = Net::HTTP.get(URI("#{API_ROOT}cs/#{iana_name}/"))
         out = JSON.parse(obj)[iana_name]
@@ -99,7 +101,7 @@ module TLSmap
 
       # Translate cipher related acronyms
       # @param term [String] Acronym, eg. DSS
-      # @return [String] The long name of the acronym, eg. Digital Signature Standard or +nil+ if it's not found
+      # @return [String] The long name of the acronym, eg. Digital Signature Standard or `nil` if it's not found
       def translate_acronym(term)
         return @tech[term][:long_name] unless @tech[term].nil?
 
@@ -108,7 +110,7 @@ module TLSmap
 
       # Find vulnerabilities related to a technology
       # @param tech [String] The technology acronym, eg. CBC
-      # @return [Array<Hash>] Array of vulnerabilities as described for {extend} return value in the +vulns+ key.
+      # @return [Array<Hash>] Array of vulnerabilities as described for {extend} return value in the `vulns` key.
       def find_vuln(tech)
         return @tech[tech][:vulnerabilities].map { |vuln| @vuln[vuln] } unless @tech[tech][:vulnerabilities].nil?
 

data/lib/tls_map/cli.rb

@@ -9,7 +9,7 @@ module TLSmap
   class CLI < App
     INTEGRITY = '42e44f89550365da2bc8d33d87f88b65d85d6474e90f9edb65e0ea6c78f61a53' # sha2-256
 
-    # Load and parse data from marshalized hash (+data/mapping.marshal+).
+    # Load and parse data from marshalized hash (`data/mapping.marshal`).
     # It must match the integrity check for security purpose.
     # @param force [Boolean] Force parsing even if intigrity check failed (DANGEROUS,
     #   may result in command execution vulnerability)
@@ -31,7 +31,7 @@ module TLSmap
     end
 
     # Check if the password database exists
-    # @return [Boolean] +true+ if the file exists
+    # @return [Boolean] `true` if the file exists
     def database_exists?
       exists = File.file?(@database_path)
       raise "Database does not exist: #{@database_path}" unless exists

data/lib/tls_map/extractor.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+# Ruby internal
+require 'json'
+# Project internal
+require 'tls_map/cli'
+# External
+require 'rexml/document'
+
+module TLSmap
+  class App
+    # External tools output data extractor
+    #
+    # Output files from [SSLyze][1] (JSON), [sslscan2][2] (XML), [testssl.sh][3] (JSON), [ssllabs-scan][4] (JSON)
+    #
+    # [1]:https://github.com/nabla-c0d3/sslyze
+    # [2]:https://github.com/rbsec/sslscan
+    # [3]:https://github.com/drwetter/testssl.sh
+    # [4]:https://github.com/ssllabs/ssllabs-scan
+    #
+    # Example of commands:
+    #
+    # - `sslyze --json_out=example.org.json example.org`
+    # - `sslscan2 --show-cipher-ids --xml=example.org.xml example.org`
+    #   - `--show-cipher-ids` is mandatory else ciphers are not saved to the output
+    # - `testssl --jsonfile-pretty example.org.json --mapping no-openssl --cipher-per-proto example.org`
+    #   - json-pretty is the only supported format, default json or csv, html won't work
+    # - `ssllabs-scan --quiet example.org > example.org.json`
+    #   - The default output is the only supported format, using `-json-flat` won't work
+    class Extractor
+      # Get the list of ciphers extracted from the tool output file
+      # @return [Array<String>] Cipher array (IANA names)
+      attr_reader :ciphers
+
+      # Initialize {TLSmap::App::Extractor} instance
+      def initialize
+        @ciphers = []
+      end
+
+      # Return only the SSL 2.0 ciphers
+      # @return [Array<String>] Cipher array (IANA names)
+      def ssl20
+        @ciphers['SSL2.0']
+      end
+
+      # Return only the SSL 3.0 ciphers
+      # @return [Array<String>] Cipher array (IANA names)
+      def ssl30
+        @ciphers['SSL3.0']
+      end
+
+      # Return only the TLS 1.0 ciphers
+      # @return [Array<String>] Cipher array (IANA names)
+      def tls10
+        @ciphers['TLS1.0']
+      end
+
+      # Return only the TLS 1.1 ciphers
+      # @return [Array<String>] Cipher array (IANA names)
+      def tls11
+        @ciphers['TLS1.1']
+      end
+
+      # Return only the TLS 1.2 ciphers
+      # @return [Array<String>] Cipher array (IANA names)
+      def tls12
+        @ciphers['TLS1.2']
+      end
+
+      # Return only the TLS 1.3 ciphers
+      # @return [Array<String>] Cipher array (IANA names)
+      def tls13
+        @ciphers['TLS1.3']
+      end
+
+      # Extract the ciphers from the tool output file
+      # @param tool [String] Possible values: `sslyze`, `sslscan2`, `testssl`, `ssllabs-scan`
+      # @param file [String] Path of the tool output file, beware of the format expected. See {TLSmap::App::Extractor}
+      # @return [Array<String>] Cipher array (IANA names)
+      def parse(tool, file)
+        # Convert string to class
+        @ciphers = Object.const_get("TLSmap::App::Extractor::#{normalize(tool)}").parse(file)
+      end
+
+      # Convert cmdline tool name to Class name
+      def normalize(tool)
+        tool.split('-').map(&:capitalize).join
+      end
+
+      protected :normalize
+
+      # Parsing SSLyze
+      class Sslyze
+        class << self
+          # Extract the ciphers from the sslyze output file
+          # @param file [String] Path of the sslyze output file, beware of the format expected.
+          #   See {TLSmap::App::Extractor}
+          # @return [Array<String>] Cipher array (IANA names)
+          def parse(file)
+            data = JSON.load_file(file)
+            extract_cipher(data)
+          end
+
+          # Extract the ciphers from the sslyze output file
+          # @param json_data [Hash] Ruby hash of the parsed JSON
+          # @return [Array<String>] Cipher array (IANA names)
+          def extract_cipher(json_data)
+            ciphers = json_data['server_scan_results'][0]['scan_commands_results']
+            raw = {
+              'SSL2.0' => ciphers['ssl_2_0_cipher_suites']['accepted_cipher_suites'],
+              'SSL3.0' => ciphers['ssl_3_0_cipher_suites']['accepted_cipher_suites'],
+              'TLS1.0' => ciphers['tls_1_0_cipher_suites']['accepted_cipher_suites'],
+              'TLS1.1' => ciphers['tls_1_1_cipher_suites']['accepted_cipher_suites'],
+              'TLS1.2' => ciphers['tls_1_2_cipher_suites']['accepted_cipher_suites'],
+              'TLS1.3' => ciphers['tls_1_3_cipher_suites']['accepted_cipher_suites']
+            }
+            raw.transform_values { |v| v.empty? ? v : v.map { |x| x['cipher_suite']['name'] } }
+          end
+
+          protected :extract_cipher
+        end
+      end
+
+      # Parsing sslscan2
+      class Sslscan2
+        class << self
+          # Extract the ciphers from the sslscan2 output file
+          # @param file [String] Path of the sslscan2 output file, beware of the format expected.
+          #   See {TLSmap::App::Extractor}
+          # @return [Array<String>] Cipher array (IANA names)
+          def parse(file, online = false)
+            doc = REXML::Document.new(File.new(file))
+            extract_cipher(doc, online)
+          end
+
+          # Extract the ciphers from the sslscan2 output file
+          # @param xml_doc [REXML::Document] XML document as returned by `REXML::Document`
+          # @param online By default use the offline mode with {TLSmap::CLI} for better performance.
+          #   Online mode will use {TLSmap::App} and fetch upstream resources to get latest updates but is a lot slower.
+          # @return [Array<String>] Cipher array (IANA names)
+          def extract_cipher(xml_doc, online = false) # rubocop:disable Metrics/MethodLength
+            raw = {
+              'SSL2.0' => [], 'SSL3.0' => [],
+              'TLS1.0' => [], 'TLS1.1' => [], 'TLS1.2' => [], 'TLS1.3' => []
+            }
+            tm = online ? TLSmap::App.new : TLSmap::CLI.new
+            xml_doc.root.each_element('//cipher') do |node|
+              sslv = node.attributes['sslversion'].gsub('v', '')
+              cipher = tm.search(:codepoint, node.attributes['id'][2..], :iana)[:iana]
+              raw[sslv].push(cipher)
+            end
+            raw
+          end
+
+          protected :extract_cipher
+        end
+      end
+
+      # Parsing testssl.sh
+      class Testssl
+        class << self
+          # Extract the ciphers from the testssl output file
+          # @param file [String] Path of the testssl output file, beware of the format expected.
+          #   See {TLSmap::App::Extractor}
+          # @return [Array<String>] Cipher array (IANA names)
+          def parse(file)
+            data = JSON.load_file(file)
+            extract_cipher(data)
+          end
+
+          # Extract the ciphers from the testssl output file
+          # @param json_data [Hash] Ruby hash of the parsed JSON
+          # @return [Array<String>] Cipher array (IANA names)
+          def extract_cipher(json_data)
+            cipher = json_data['scanResult'][0]['cipherTests']
+            raw = {
+              'SSL2.0' => [], 'SSL3.0' => [],
+              'TLS1.0' => [], 'TLS1.1' => [], 'TLS1.2' => [], 'TLS1.3' => []
+            }
+            cipher.each do |node|
+              raw[id2prot(node['id'])].push(finding2cipher(node['finding']))
+            end
+            raw
+          end
+
+          # Convert testssl protocol id to protocol name in TLSmap format
+          # @param id [String] testssl protocol id
+          # @return [String] protocol name in TLSmap format
+          def id2prot(id)
+            prot = {
+              'ssl2' => 'SSL2.0', 'ssl3' => 'SSL3.0', 'tls1' => 'TLS1.0',
+              'tls1_1' => 'TLS1.1', 'tls1_2' => 'TLS1.2', 'tls1_3' => 'TLS1.3'
+            }
+            protv = id.match(/cipher-(\w+)_x\w+/).captures[0]
+            prot[protv]
+          end
+
+          # Extract the cipher name from testssl finding
+          # @param finding [String] testssl finding
+          # @return [String] cipher name (IANA names)
+          def finding2cipher(finding)
+            /\s(\w+_\w+)\s/.match(finding).captures[0]
+          end
+
+          protected :extract_cipher, :id2prot, :finding2cipher
+        end
+      end
+
+      # Parsing ssllabs-scan
+      class SsllabsScan
+        class << self
+          # Extract the ciphers from the ssllabs-scan output file
+          # @param file [String] Path of the ssllabs-scan output file, beware of the format expected.
+          #   See {TLSmap::App::Extractor}
+          # @return [Array<String>] Cipher array (IANA names)
+          def parse(file)
+            data = JSON.load_file(file)
+            extract_cipher(data)
+          end
+
+          # Extract the ciphers from the ssllabs-scan output file
+          # @param json_data [Hash] Ruby hash of the parsed JSON
+          # @return [Array<String>] Cipher array (IANA names)
+          def extract_cipher(json_data) # rubocop:disable Metrics/MethodLength
+            raw = {
+              'SSL2.0' => [], 'SSL3.0' => [],
+              'TLS1.0' => [], 'TLS1.1' => [], 'TLS1.2' => [], 'TLS1.3' => []
+            }
+            json_data[0]['endpoints'].each do |endpoint|
+              endpoint['details']['suites'].each do |suite|
+                suite['list'].each do |cipher|
+                  raw[id2prot(suite['protocol'])].push(cipher['name'])
+                end
+              end
+            end
+            raw.transform_values(&:uniq)
+          end
+
+          # Convert ssllabs-scan protocol id to protocol name in TLSmap format
+          # @param id [String] ssllabs-scan protocol id
+          # @return [String] protocol name in TLSmap format
+          def id2prot(id)
+            prot = {
+              512 => 'SSL2.0', 768 => 'SSL3.0', 769 => 'TLS1.0',
+              770 => 'TLS1.1', 771 => 'TLS1.2', 772 => 'TLS1.3'
+            }
+            prot[id]
+          end
+
+          protected :extract_cipher, :id2prot
+        end
+      end
+    end
+  end
+end

data/lib/tls_map/output.rb

@@ -35,9 +35,9 @@ module TLSmap
 
     # Export the mapping to a file, supporting various formats.
     # @param filename [String] The output file name to write to.
-    # @param format [Symbol] Supported formats: +:markdown+ (a markdown table),
-    #   +:json_pretty+ (expanded JSON), +:json_compact+ (minified JSON),
-    #   +:marshal+ (Ruby marshalized hash).
+    # @param format [Symbol] Supported formats: `:markdown` (a markdown table),
+    #   `:json_pretty` (expanded JSON), `:json_compact` (minified JSON),
+    #   `:marshal` (Ruby marshalized hash).
     def export(filename, format)
       case format
       when :markdown      then output_markdown(filename)

data/lib/tls_map/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TLSmap
-  VERSION = '1.1.0'
+  VERSION = '1.2.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tls-map
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Alexandre ZANNI
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-05-25 00:00:00.000000000 Z
+date: 2021-05-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: docopt
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: rexml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -86,6 +100,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.12'
+- !ruby/object:Gem::Dependency
+  name: minitest-skip
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: redcarpet
   requirement: !ruby/object:Gem::Requirement
@@ -147,6 +203,7 @@ files:
 - lib/tls_map.rb
 - lib/tls_map/ciphersuiteinfo.rb
 - lib/tls_map/cli.rb
+- lib/tls_map/extractor.rb
 - lib/tls_map/gnutls.rb
 - lib/tls_map/iana.rb
 - lib/tls_map/nss.rb