nvd-json_feeds 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bd4659807e5869138f57f659f9e910b664ae957404e5c02d51637db8b66d206d
+  data.tar.gz: 211b9c2e6dd6a12a7ce4af222598b78e9320a8e0620f28123fe340d88596b43e
+SHA512:
+  metadata.gz: e7872a3817bc270911fce04eb11b61ed2ae1b9aa5a7473dd685eb61ec925630a367d72a9b8155a203b621d1717f9223d75260071c88ffc7fbe865141bfabc521
+  data.tar.gz: 6393801ec6a605b09446e87a71aac5146a09e08d62898c48ab15050ddd4f3c0ff532fb05f979e993430c53b396ef8e32c65422a4bc29c1ec2f59d4d2b4ddcf1d

data/.document

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

data/.github/workflows/ruby.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on: [ push, pull_request ]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          # - 2.4
+          # - 2.5
+          # - 2.6
+          - 2.7
+          - 3.0
+          # TODO: uncomment when jruby supports ruby >= 2.7
+          # - jruby
+    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,9 @@
+/.bundle
+/.yardoc/
+/Gemfile.lock
+/doc/
+/pkg/
+/spec/fixtures/downloads/
+/spec/fixtures/gz_feed_file/*.json
+/spec/fixtures/zip_feed_file/*.json
+/vendor/cache/*.gem

data/.rspec

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

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --title "nvd-json_feeds Documentation" --protected

data/ChangeLog.md

@@ -0,0 +1,25 @@
+### 0.1.0 / 2021-01-20
+
+* Initial release:
+  * Supports [NVD JSON 1.1 Schema].
+  * [ruby] >= 2.7.0
+  * Added {NVD::JSONFeeds::FeedURI}.
+  * Added {NVD::JSONFeeds::MetaFeedURI}.
+  * Added {NVD::JSONFeeds::Meta}.
+  * Added {NVD::JSONFeeds::GzFeedURI}.
+  * Added {NVD::JSONFeeds::ZipFeedURI}.
+  * Added {NVD::JSONFeeds::FeedFile}.
+  * Added {NVD::JSONFeeds::GzFeedFile}.
+  * Added {NVD::JSONFeeds::ZipFeedFile}.
+  * Added {NVD::JSONFeeds::JSONFeedFile}.
+  * Added {NVD::JSONFeeds::Schema::Configurations}.
+  * Added {NVD::JSONFeeds::Schema::CPE::Name}.
+  * Added {NVD::JSONFeeds::Schema::CPE::Match}.
+  * Added {NVD::JSONFeeds::Schema::CVEFeed}.
+  * Added {NVD::JSONFeeds::Schema::CVEItem}.
+  * Added {NVD::JSONFeeds::Schema::CVSSv2}.
+  * Added {NVD::JSONFeeds::Schema::CVSSv3}.
+  * Added {NVD::JSONFeeds::Schema::Impact}.
+
+[NVD JSON 1.1 Schema]: https://csrc.nist.gov/schema/nvd/feed/1.1/nvd_cve_feed_json_1.1.schema
+[ruby]: https://www.ruby-lang.org/

data/Gemfile

@@ -0,0 +1,13 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'rake'
+  gem 'rubygems-tasks', '~> 0.2'
+
+  gem 'rspec', '~> 3.0'
+
+  gem 'kramdown'
+  gem 'yard', '~> 0.9'
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2021 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,136 @@
+# nvd-json_feeds
+
+* [Homepage](https://github.com/postmodern/nvd-json_feeds.rb#readme)
+* [Issues](https://github.com/postmodern/nvd-json_feeds.rb/issues)
+* [Documentation](http://rubydoc.info/gems/nvd-json_feeds/frames)
+* [Email](mailto:postmodern.mod3 at gmail.com)
+
+## Description
+
+Provides a Ruby API to [NVD JSON Feeds].
+
+## Features
+
+* Supports [NVD JSON 1.1 Schema].
+* Supports recent, modified, and Year number `.gz`/`.zip` JSON feed files.
+* Supports parsing META feed files.
+* Supports downloading `.gz`/`.zip` JSON feed files.
+* Supports reading `.gz`/`.zip` JSON feed files, without extracting them.
+* Supports extracting `.gz`/`.zip` JSON feed files.
+* Supports parsing extracted JSON feed files.
+
+## Examples
+
+    require 'nvd/json_feeds'
+
+Access the Modified CVEs feed:
+
+    NVD::JSONFeeds[:modified]
+    # => #<NVD::JSONFeeds::Feed:0x0000556b4db58660
+    #  @gz=
+    #   #<NVD::JSONFeeds::GzFeedURI: https://nvd.nist.gov/feeds/json/cve/1.1/nvdcve-1.1-modified.json.gz>,
+    #  @meta=
+    #   #<NVD::JSONFeeds::MetaFeedURI: https://nvd.nist.gov/feeds/json/cve/1.1/nvdcve-1.1-modified.meta>,
+    #  @name=:modified,
+    #  @zip=
+    #   #<NVD::JSONFeeds::ZipFeedURI: https://nvd.nist.gov/feeds/json/cve/1.1/nvdcve-1.1-modified.json.zip>>
+
+Access the Recent CVEs feed:
+
+    NVD::JSONFeeds[:recent]
+    # => #<NVD::JSONFeeds::Feed:0x0000556b4da14c68
+    #  @gz=
+    #   #<NVD::JSONFeeds::GzFeedURI: https://nvd.nist.gov/feeds/json/cve/1.1/nvdcve-1.1-recent.json.gz>,
+    #  @meta=
+    #   #<NVD::JSONFeeds::MetaFeedURI: https://nvd.nist.gov/feeds/json/cve/1.1/nvdcve-1.1-recent.meta>,
+    #  @name=:recent,
+    #  @zip=
+    #   #<NVD::JSONFeeds::ZipFeedURI: https://nvd.nist.gov/feeds/json/cve/1.1/nvdcve-1.1-recent.json.zip>>
+
+Access the year 2020 CVEs feed:
+
+    NVD::JSONFeeds[2020]
+    # => #<NVD::JSONFeeds::Feed:0x0000556b4d55da80
+    #  @gz=
+    #   #<NVD::JSONFeeds::GzFeedURI: https://nvd.nist.gov/feeds/json/cve/1.1/nvdcve-1.1-2020.json.gz>,
+    #  @meta=
+    #   #<NVD::JSONFeeds::MetaFeedURI: https://nvd.nist.gov/feeds/json/cve/1.1/nvdcve-1.1-2020.meta>,
+    #  @name=2020,
+    #  @zip=
+    #   #<NVD::JSONFeeds::ZipFeedURI: https://nvd.nist.gov/feeds/json/cve/1.1/nvdcve-1.1-2020.json.zip>>
+
+Read the `.meta` feed file:
+
+    meta = NVD::JSONFeeds[2020].meta.parse
+    # => #<NVD::JSONFeeds::Meta:0x0000556b4e6f4960
+    meta.last_modified_date
+    # => #<DateTime: 2021-01-17T03:17:48-05:00 ((2459232j,29868s,0n),-18000s,2299161j)>
+    meta.size
+    # => 67524038
+    meta.zip_size
+    # => 3777141
+    meta.gz_size
+    # => 3777005
+    meta.sha256
+    # => "9288B92370FC4D6E92ACB6FFDDDA378C4B9F1B3B5257105BD6D92535DA46BD55"
+
+Download the `.zip`/`.gz` feed file:
+
+    zip_feed = NVD::JSONFeeds[2020].zip.download(dest)
+    # => #<NVD::JSONFeeds::ZipFeedFile: ...>
+    gz_feed = NVD::JSONFeeds[2020].gz.download(dest)
+    # => #<NVD::JSONFeeds::GzFeedFile: ...>
+
+Access a pre-downloaded `.zip`/`.gz` feed file:
+
+    zip_feed = NVD::JSONFeeds::ZipFeedFile.new('path/to/nvdcve-1.1-2020.json.zip')
+    # => #<NVD::JSONFeeds::ZipFeedFile: ...>
+    gz_feed = NVD::JSONFeeds::GzFeedFile.new('path/to/nvdcve-1.1-2020.json.gz')
+    # => #<NVD::JSONFeeds::GzFeedFile: ...>
+
+Parse a `.zip`/`.gz` feed file (without extracting it):
+
+    cve_feed = zip_feed.parse
+    # => #<NVD::JSONFeeds::Schema::CVEFeed: ...>
+    cve_feed = gz_feed.parse
+    # => #<NVD::JSONFeeds::Schema::CVEFeed: ...>
+
+Extracts a `.zip`/`.gz` feed file:
+
+    json_feed = zip_feed.extract(dest_dir)
+    # => #<NVD::JSONFeeds::JSONFeedFile: ...>
+    json_feed = gz_feed.extract
+    # => #<NVD::JSONFeeds::JSONFeedFile: ...>
+
+Access a pre-extracted `.json` feed file:
+
+    json_feed = NVD::JSONFeeds::JSONFeed.new('path/to/nvdcve-1.1-2020.json')
+    # => #<NVD::JSONFeeds::JSONFeedFile: ...>
+    cve_feed = json_feed.parse
+    # => #<NVD::JSONFeeds::Schema::CVEFeed: ...>
+
+## Requirements
+
+* [ruby] >= 2.7.0
+* [multi_json] ~> 1.0
+* [cve_schema] ~> 0.1
+
+## Install
+
+    $ gem install nvd-json_feeds
+
+### Gemfile
+
+    gem 'nvd-json_feeds', '~> 0.1'
+
+## Copyright
+
+Copyright (c) 2021 Hal Brodigan
+
+See {file:LICENSE.txt} for details.
+
+[NVD JSON Feeds]: https://nvd.nist.gov/vuln/data-feeds#JSON_FEEDS
+[NVD JSON 1.1 Schema]: https://csrc.nist.gov/schema/nvd/feed/1.1/nvd_cve_feed_json_1.1.schema
+
+[multi_json]: https://github.com/intridea/multi_json#readme
+[cve_schema]: https://github.com/postmodern/cve_schema.rb#readme

data/Rakefile

@@ -0,0 +1,31 @@
+# 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
+
+namespace :spec do
+  RSpec::Core::RakeTask.new(:integration) do |t|
+    t.rspec_opts = '--tag integration'
+  end
+end
+
+task :test    => [:spec, 'spec:integration']
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new  
+task :doc => :yard

data/gemspec.yml

@@ -0,0 +1,22 @@
+name: nvd-json_feeds
+summary: A Ruby API to NVD JSON Feeds
+description: Provides a Ruby API to NVD JSON Feeds.
+license: MIT
+authors: Postmodern
+email: postmodern.mod3@gmail.com
+homepage: https://github.com/postmodern/nvd-json_feeds#readme
+
+metadata:
+  documentation_uri: https://rubydoc.info/gems/nvd-json_feeds
+  source_code_uri:   https://github.com/postmodern/nvd-json_feeds.rb
+  bug_tracker_uri:   https://github.com/postmodern/nvd-json_feeds.rb/issues
+  changelog_uri:     https://github.com/postmodern/nvd-json_feeds.rb/blob/main/ChangeLog.md
+
+required_ruby_version: ">= 2.7.0"
+
+dependencies:
+  multi_json: ~> 1.0
+  cve_schema: ~> 0.1
+
+development_dependencies:
+  bundler: ~> 2.0

data/lib/nvd/json_feeds.rb

@@ -0,0 +1,25 @@
+require 'nvd/json_feeds/feed'
+require 'nvd/json_feeds/version'
+
+require 'date'
+
+module NVD
+  module JSONFeeds
+    FEEDS =  Hash[[:modified, :recent, *(2002 .. Date.today.year)].map { |name|
+      [name, Feed.new(name)]
+    }]
+
+    #
+    # Accesses a feed with the given name or year number.
+    #
+    # @param [:modified, :recent, Integer] name
+    #   The feed name or year number.
+    #
+    # @return [Feed, nil]
+    #   The feed.
+    #
+    def self.[](name)
+      FEEDS[name]
+    end
+  end
+end

data/lib/nvd/json_feeds/exceptions.rb

@@ -0,0 +1,15 @@
+module NVD
+  module JSONFeeds
+    class MetaParseError < RuntimeError
+    end
+
+    class FeedFileError < RuntimeError
+    end
+
+    class ReadFailed < FeedFileError
+    end
+
+    class ExtractFailed < FeedFileError
+    end
+  end
+end

data/lib/nvd/json_feeds/feed.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'nvd/json_feeds/meta_feed_uri'
+require 'nvd/json_feeds/gz_feed_uri'
+require 'nvd/json_feeds/zip_feed_uri'
+
+module NVD
+  module JSONFeeds
+    #
+    # Represents a feed and it's various downloads.
+    #
+    class Feed
+
+      # The feed name or year number.
+      #
+      # @return [:modified, :recent, Integer]
+      attr_reader :name
+
+      # The "meta" feed URI.
+      #
+      # @return [MetaFeedURI]
+      attr_reader :meta
+
+      # The ".gz" feed URI.
+      #
+      # @return [GzFeedURI]
+      attr_reader :gz
+
+      # The ".zip" feed URI.
+      #
+      # @return [ZipFeedURI]
+      attr_reader :zip
+
+      #
+      # Initializes the feed.
+      #
+      # @param [:modified, :recent, Integer] name
+      #   The feed name or year number.
+      #
+      def initialize(name)
+        @name = name
+
+        @meta = MetaFeedURI.new(@name,'.meta')
+        @gz   = GzFeedURI.new(@name,'.json.gz')
+        @zip  = ZipFeedURI.new(@name,'.json.zip')
+      end
+
+    end
+  end
+end

data/lib/nvd/json_feeds/feed_file.rb

@@ -0,0 +1,95 @@
+require 'nvd/json_feeds/schema/cve_feed'
+
+require 'multi_json'
+require 'digest/sha2'
+
+module NVD
+  module JSONFeeds
+    class FeedFile
+
+      # The path to the feed file.
+      #
+      # @return [String]
+      attr_reader :path
+
+      #
+      # Initializes the feed file.
+      #
+      # @param [String] path
+      #   The path to the feed file.
+      #
+      def initialize(path)
+        @path = File.expand_path(path)
+      end
+
+      #
+      # @see #parse
+      #
+      def self.parse(path)
+        new(path).parse
+      end
+
+      #
+      # Calculates the SHA256 checksum of the feed file.
+      #
+      # @return [String]
+      #
+      # @note NVD uses all upper-case SHA256 checksums.
+      #
+      def sha256
+        Digest::SHA256.hexdigest(read).upcase
+      end
+
+      #
+      # Reads the feed file.
+      #
+      # @return [String]
+      #
+      # @abstract
+      #
+      def read
+        raise(NotImplementedError,"#{self.class}#read not implemented")
+      end
+
+      #
+      # Parses the JSON.
+      #
+      # @return [Hash{String => Object}]
+      #   The parsed JSON.
+      #
+      def json
+        MultiJson.load(read)
+      end
+
+      #
+      # Loads the CVE data from the feed file.
+      #
+      # @return [CVEFeed]
+      #   The CVE feed data.
+      #
+      def parse
+        Schema::CVEFeed.load(json)
+      end
+
+      #
+      # Converts the feed file to a String.
+      #
+      # @return [String]
+      #   The feed file path.
+      #
+      def to_s
+        @path
+      end
+
+      #
+      # Inspects the feed file.
+      #
+      # @return [String]
+      #
+      def inspect
+        "#<#{self.class}: #{self}>"
+      end
+
+    end
+  end
+end