cisa-kev 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8791f5387d34ee20d6ac2f885be06187c122fab8de2f87c2bbcd6985f5495089
+  data.tar.gz: 3fd6e839977a257810c59e139319bc72974cd1f5ee52e834fffd1bb6afda4aba
+SHA512:
+  metadata.gz: b710ad6d6f7aeaf9753967f004947af5cac07531390acf22377a56d3f0934d77ca7c9ada076e593b610ed519d3a8d54677352641e4da4b472ef753a712a59b38
+  data.tar.gz: 05a11854d20b358c6eda0053007bf8311cce1a52f9e94d3160aebf9d35dff708a2a95ec7cabad19566e1a6e3fb65e04bf69b16fc2bcfa7aba610cc6085e77b2a

data/.document

@@ -0,0 +1,3 @@
+- 
+ChangeLog.md
+LICENSE.txt

data/.github/workflows/ruby.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on: [ push, pull_request ]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - '3.0'
+          - '3.1'
+          - '3.2'
+          - '3.3'
+          - jruby
+          - truffleruby
+    name: Ruby ${{ matrix.ruby }}
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: Install dependencies
+        run: bundle install --jobs 4 --retry 3
+      - name: Run tests
+        run: bundle exec rake test

data/.gitignore

@@ -0,0 +1,7 @@
+/.bundle
+/.yardoc/
+/Gemfile.lock
+/coverage/
+/doc/
+/pkg/
+/vendor/cache/*.gem

data/.rspec

@@ -0,0 +1 @@
+--colour --format documentation

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --title "CISA::KEV Documentation" --protected

data/ChangeLog.md

@@ -0,0 +1,6 @@
+### 0.1.0 / 2024-05-13
+
+* Initial release:
+  * Supports requesting the CISA KEV catalog via HTTP(s).
+  * Supports parsing previously downloaded JSON files.
+

data/Gemfile

@@ -0,0 +1,18 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'rake'
+  gem 'rubygems-tasks', '~> 0.2'
+
+  gem 'json'
+  gem 'rspec', '~> 3.0'
+  gem 'webmock', '~> 3.0'
+  gem 'simplecov', '~> 0.20', require: false
+
+  gem 'kramdown'
+  gem 'redcarpet', platform: :mri
+  gem 'yard', '~> 0.9'
+  gem 'yard-spellcheck', require: false
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2024 Hal Brodigan
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,66 @@
+# cisa-kev
+
+[![CI](https://github.com/postmodern/cisa-kev.rb/actions/workflows/ruby.yml/badge.svg)](https://github.com/postmodern/cisa-kev.rb/actions/workflows/ruby.yml)
+[![Code Climate](https://codeclimate.com/github/postmodern/cisa-kev.rb.svg)](https://codeclimate.com/github/postmodern/cisa-kev.rb)
+
+* [Homepage](https://github.com/postmodern/cisa-kev.rb#readme)
+* [Issues](https://github.com/postmodern/cisa-kev.rb/issues)
+* [Documentation](http://rubydoc.info/gems/cisa-kev/frames)
+
+## Description
+
+A simple Ruby library for fetching and parsing the [CISA KEV] catalog.
+
+## Features
+
+* Supports requesting the CISA KEV catalog via HTTP(s).
+* Supports parsing previously downloaded JSON files.
+
+## Examples
+
+```ruby
+require 'cisa/kev'
+
+catalog = CISA::KEV::Catalog.load
+catalog.select(&:known_ransomware_campaign_use).sort_by(&:date_added)
+# =>
+# [
+#   ...
+#  #<CISA::KEV::Vulnerability:0x00007fc0a6e715f8
+#   @cve_id="CVE-2023-24955",
+#   @date_added=#<Date: 2024-03-26 ((2460396j,0s,0n),+0s,2299161j)>,
+#   @due_date=#<Date: 2024-04-16 ((2460417j,0s,0n),+0s,2299161j)>,
+#   @known_ransomware_campaign_use=true,
+#   @notes="https://msrc.microsoft.com/update-guide/vulnerability/CVE-2023-24955",
+#   @product="SharePoint Server",
+#   @required_action=
+#    "Apply mitigations per vendor instructions or discontinue use of the product if mitigations are unavailable.",
+#   @short_description=
+#    "Microsoft SharePoint Server contains a code injection vulnerability that allows an authenticated attacker with Site Owner privileges to execute code remotely.",
+#   @vendor_project="Microsoft",
+#   @vulnerability_name="Microsoft SharePoint Server Code Injection Vulnerability">]
+```
+
+## Requirements
+
+* [ruby] >= 3.0.0
+
+## Install
+
+```shell
+gem install cisa-kev
+```
+
+### Gemfile
+
+```ruby
+gem 'cisa-kev', '~> 0.1'
+```
+## Copyright
+
+Copyright (c) 2024 Hal Brodigan
+
+See {file:LICENSE.txt} for details.
+
+[CISA KEV]: https://www.cisa.gov/known-exploited-vulnerabilities-catalog
+[ruby]: https://www.ruby-lang.org/

data/Rakefile

@@ -0,0 +1,23 @@
+# encoding: utf-8
+
+require 'rubygems'
+
+begin
+  require 'bundler/setup'
+rescue LoadError => e
+  abort e.message
+end
+
+require 'rake'
+require 'rubygems/tasks'
+Gem::Tasks.new
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+
+task :test    => :spec
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new
+task :doc => :yard

data/cisa-kev.gemspec

@@ -0,0 +1,61 @@
+# encoding: utf-8
+
+require 'yaml'
+
+Gem::Specification.new do |gem|
+  gemspec = YAML.load_file('gemspec.yml')
+
+  gem.name    = gemspec.fetch('name')
+  gem.version = gemspec.fetch('version') do
+                  lib_dir = File.join(File.dirname(__FILE__),'lib')
+                  $LOAD_PATH << lib_dir unless $LOAD_PATH.include?(lib_dir)
+
+                  require 'cisa/kev/version'
+                  CISA::KEV::VERSION
+                end
+
+  gem.summary     = gemspec['summary']
+  gem.description = gemspec['description']
+  gem.licenses    = Array(gemspec['license'])
+  gem.authors     = Array(gemspec['authors'])
+  gem.email       = gemspec['email']
+  gem.homepage    = gemspec['homepage']
+  gem.metadata    = gemspec['metadata'] if gemspec['metadata']
+
+  glob = lambda { |patterns| gem.files & Dir[*patterns] }
+
+  gem.files = `git ls-files`.split($/)
+  gem.files = glob[gemspec['files']] if gemspec['files']
+
+  gem.executables = gemspec.fetch('executables') do
+    glob['bin/*'].map { |path| File.basename(path) }
+  end
+  gem.default_executable = gem.executables.first if Gem::VERSION < '1.7.'
+
+  gem.extensions       = glob[gemspec['extensions'] || 'ext/**/extconf.rb']
+  gem.test_files       = glob[gemspec['test_files'] || '{test/{**/}*_test.rb']
+  gem.extra_rdoc_files = glob[gemspec['extra_doc_files'] || '*.{txt,md}']
+
+  gem.require_paths = Array(gemspec.fetch('require_paths') {
+    %w[ext lib].select { |dir| File.directory?(dir) }
+  })
+
+  gem.requirements              = Array(gemspec['requirements'])
+  gem.required_ruby_version     = gemspec['required_ruby_version']
+  gem.required_rubygems_version = gemspec['required_rubygems_version']
+  gem.post_install_message      = gemspec['post_install_message']
+
+  split = lambda { |string| string.split(/,\s*/) }
+
+  if gemspec['dependencies']
+    gemspec['dependencies'].each do |name,versions|
+      gem.add_dependency(name,split[versions])
+    end
+  end
+
+  if gemspec['development_dependencies']
+    gemspec['development_dependencies'].each do |name,versions|
+      gem.add_development_dependency(name,split[versions])
+    end
+  end
+end

data/gemspec.yml

@@ -0,0 +1,20 @@
+name: cisa-kev
+summary: A simple library for parsing the CISA KEV catalog
+description: |
+  A simple Ruby library for parsing the CISA KEV (Known Exploited
+  Vulnerabilities) catalog
+license: MIT
+authors: Postmodern
+email: postmodern.mod3@gmail.com
+homepage: https://github.com/postmodern/cisa-kev.rb#readme
+
+metadata:
+  documentation_uri: https://rubydoc.info/gems/cisa-kev
+  source_code_uri:   https://github.com/postmodern/cisa-kev.rb
+  bug_tracker_uri:   https://github.com/postmodern/cisa-kev.rb/issues
+  changelog_uri:     https://github.com/postmodern/cisa-kev.rb/blob/main/ChangeLog.md
+
+required_ruby_version: ">= 3.0.0"
+
+development_dependencies:
+  bundler: ~> 2.0

data/lib/cisa/kev/catalog.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require_relative 'vulnerability'
+
+require 'net/https'
+require 'json'
+require 'time'
+
+module CISA
+  module KEV
+    #
+    # Represents the parsed [CISA KEV] catalog.
+    #
+    # [CISA KEV]: https://www.cisa.gov/known-exploited-vulnerabilities-catalog
+    #
+    # ## Example
+    #
+    #     catalog = CISA::KEV::Catalog.load
+    #     catalog.select(&:known_ransomware_campaign_use).sort_by(&:date_added)
+    #     # =>
+    #     # [
+    #     #   ...
+    #     #  #<CISA::KEV::Vulnerability:0x00007fc0a6e715f8
+    #     #   @cve_id="CVE-2023-24955",
+    #     #   @date_added=#<Date: 2024-03-26 ((2460396j,0s,0n),+0s,2299161j)>,
+    #     #   @due_date=#<Date: 2024-04-16 ((2460417j,0s,0n),+0s,2299161j)>,
+    #     #   @known_ransomware_campaign_use=true,
+    #     #   @notes="https://msrc.microsoft.com/update-guide/vulnerability/CVE-2023-24955",
+    #     #   @product="SharePoint Server",
+    #     #   @required_action=
+    #     #    "Apply mitigations per vendor instructions or discontinue use of the product if mitigations are unavailable.",
+    #     #   @short_description=
+    #     #    "Microsoft SharePoint Server contains a code injection vulnerability that allows an authenticated attacker with Site Owner privileges to execute code remotely.",
+    #     #   @vendor_project="Microsoft",
+    #     #   @vulnerability_name="Microsoft SharePoint Server Code Injection Vulnerability">]
+    #
+    class Catalog
+
+      include Enumerable
+
+      # Catalog title attribute.
+      #
+      # @return [String]
+      attr_reader :title
+
+      # Catalog version string.
+      #
+      # @return [String]
+      attr_reader :catalog_version
+      alias version catalog_version
+
+      # Time that the catalog was last updated.
+      #
+      # @return [Time]
+      attr_reader :date_released
+
+      # Number of vulnerabilities current in the catalog.
+      #
+      # @return [Integer]
+      attr_reader :count
+      alias size count
+      alias length count
+
+      # Vulnerabilities in the catalog.
+      #
+      # @return [Array<Vulnerability>]
+      attr_reader :vulnerabilities
+      alias vulns vulnerabilities
+
+      #
+      # Initializes the CISA KEV catalog.
+      #
+      # @param [String] title
+      #   The catalog title attribute.
+      #
+      # @param [String] catalog_version
+      #   The catalog version string.
+      #
+      # @param [Time] date_released
+      #   The time that the catalog was last updated.
+      #
+      # @param [Integer] count
+      #   The number of vulnerabilities in the catalog.
+      #
+      # @param [Array<Vulnerability>] vulnerabilities
+      #   The parsed vulnerabilities.
+      #
+      # @api private
+      #
+      def initialize(title:           ,
+                     catalog_version: ,
+                     date_released:   ,
+                     count:           ,
+                     vulnerabilities: )
+        @title           = title
+        @catalog_version = catalog_version
+        @date_released   = date_released
+        @count           = count
+
+        @vulnerabilities = vulnerabilities
+      end
+
+      # The CISA KEV catalog in JSON format.
+      URL = URI.parse('https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json')
+
+      #
+      # Performs an HTTP request for the CISA KEV catalog JSON file.
+      #
+      # @return [String]
+      #   The response body containing the CISA KEV catalog JSON.
+      #
+      # @api public
+      #
+      def self.request
+        Net::HTTP.get(URL)
+      end
+
+      #
+      # Loads the CISA KEV list.
+      #
+      # @return [Catalog]
+      #   The loaded catalog.
+      #
+      # @api public
+      #
+      # @note This method will perform a HTTP request to {URL}.
+      #
+      def self.load
+        parse(request)
+      end
+
+      #
+      # Parses a previously downloaded CISA KEV catalog.
+      #
+      # @param [String] path
+      #   The file to parse.
+      #
+      # @return [Catalog]
+      #   The parsed catalog.
+      #
+      # @api public
+      #
+      def self.open(path)
+        parse(File.open(path).read)
+      end
+
+      #
+      # Parses the CISA KEV JSON contents.
+      #
+      # @param [String] contents
+      #
+      # @return [Catalog]
+      #
+      # @api private
+      #
+      def self.parse(contents)
+        json = JSON.parse(contents)
+
+        title           = json.fetch('title')
+        catalog_version = json.fetch('catalogVersion')
+        date_released   = Time.parse(json.fetch('dateReleased'))
+        count           = json.fetch('count').to_i
+
+        vulnerabilities = json.fetch('vulnerabilities').map do |attributes|
+          Vulnerability.from_json(attributes)
+        end
+
+        return new(
+          title:           title,
+          catalog_version: catalog_version,
+          date_released:   date_released,
+          count:           count,
+          vulnerabilities: vulnerabilities
+        )
+      end
+
+      #
+      # Enumerates over each vulnerability in the CISA KEV list.
+      #
+      # @yield [vuln]
+      #   If a block is given, it will be passed every vulnerability in the
+      #   catalog.
+      #
+      # @yieldparam [Vulnerability] vuln
+      #   A parsed vulnerability in the catalog.
+      #
+      # @return [Enumerator]
+      #
+      def each(&block)
+        @vulnerabilities.each(&block)
+      end
+
+      #
+      # Converts the list to a String.
+      #
+      # @return [String]
+      #   The string containing the title and date released attributes.
+      #
+      def to_s
+        "#{@title} (#{@date_released})"
+      end
+
+    end
+  end
+end

data/lib/cisa/kev/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module CISA
+  module KEV
+    # `cisa-kev` version
+    VERSION = '0.1.0'
+  end
+end

data/lib/cisa/kev/vulnerability.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module CISA
+  module KEV
+    #
+    # Represents a parsed vulnerability in the [CISA KEV] catalog.
+    #
+    # [CISA KEV]: https://www.cisa.gov/known-exploited-vulnerabilities-catalog
+    #
+    class Vulnerability
+
+      # The CVE ID of the vulnerability.
+      #
+      # @return [String]
+      attr_reader :cve_id
+      alias cve cve_id
+
+      # The vendor project.
+      #
+      # @return [String]
+      attr_reader :vendor_project
+
+      # The vendor's product.
+      #
+      # @return [String]
+      attr_reader :product
+
+      # The vulnerability name or title.
+      #
+      # @return [String]
+      attr_reader :vulnerability_name
+      alias name vulnerability_name
+
+      # The date the vulnerability was added to the CISA KEV catalog.
+      #
+      # @return [Date]
+      attr_reader :date_added
+
+      # A short description of the vulnerability.
+      #
+      # @return [String]
+      attr_reader :short_description
+      alias description short_description
+
+      # The required action to resolve the vulnerability.
+      #
+      # @return [String]
+      attr_reader :required_action
+
+      # The due date.
+      #
+      # @return [Date]
+      attr_reader :due_date
+
+      # Whether the vulnerability is currently being used in ransomware
+      # campaigns.
+      #
+      # @return [Boolean]
+      attr_reader :known_ransomware_campaign_use
+      alias known_ransomware_campaign_use? known_ransomware_campaign_use
+
+      # Any additional notes for the vulnerability.
+      #
+      # @return [String, nil]
+      attr_reader :notes
+
+      #
+      # Initializes the vulnerability.
+      #
+      # @param [String] cve_id
+      #   The CVE ID of the vulnerability.
+      #
+      # @param [String] vendor_project
+      #   The vendor project.
+      #
+      # @param [String] product
+      #   The vendor's product.
+      #
+      # @param [String] vulnerability_name
+      #   The vulnerability name or title.
+      #
+      # @param [Date] date_added
+      #   The date the vulnerability was added to the CISA KEV catalog.
+      #
+      # @param [String] short_description
+      #   A short description of the vulnerability.
+      #
+      # @param [String] required_action
+      #   The required action to resolve the vulnerability.
+      #
+      # @param [Date] due_date
+      #   The due date.
+      #
+      # @param [Boolean] known_ransomware_campaign_use
+      #   Indicates whether the vulnerability is currently being used in
+      #   ransomware campaigns.
+      #
+      # @param [String, nil] notes
+      #   Additional notes.
+      #
+      # @api private
+      #
+      def initialize(cve_id: ,
+                     vendor_project: , 
+                     product: ,
+                     vulnerability_name: ,
+                     date_added: ,
+                     short_description: ,
+                     required_action: ,
+                     due_date: ,
+                     known_ransomware_campaign_use: false,
+                     notes: nil)
+        @cve_id             = cve_id
+        @vendor_project     = vendor_project
+        @product            = product
+        @vulnerability_name = vulnerability_name
+        @date_added         = date_added
+        @short_description  = short_description
+        @required_action    = required_action
+        @due_date           = due_date
+
+        @known_ransomware_campaign_use = known_ransomware_campaign_use
+        @notes = notes
+      end
+
+      #
+      # Loads the vulnerability from a parsed JSON hash.
+      #
+      # @param [Hash{String => String}] json
+      #   The parsed JSON hash.
+      #
+      # @return [Vulnerability]
+      #
+      # @api private
+      #
+      def self.from_json(json)
+        new(
+          cve_id:             json.fetch('cveID'),
+          vendor_project:     json.fetch('vendorProject'),
+          product:            json.fetch('product'),
+          vulnerability_name: json.fetch('vulnerabilityName'),
+          date_added:         Date.parse(json.fetch('dateAdded')),
+          short_description:  json.fetch('shortDescription'),
+          required_action:    json.fetch('requiredAction'),
+          due_date:           Date.parse(json.fetch('dueDate')),
+
+          known_ransomware_campaign_use: (json['knownRansomwareCampaignUse'] == 'Known'),
+          notes: if (notes = json['notes']) && !notes.empty?
+                   notes
+                 end
+        )
+      end
+
+      #
+      # Converts the vulnerability to a String.
+      #
+      # @return [String]
+      #   The {#vulnerability_name}.
+      #
+      def to_s
+        @vulnerability_name
+      end
+
+    end
+  end
+end

data/lib/cisa/kev.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require 'cisa/kev/catalog'
+require 'cisa/kev/version'