euvd 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0ae86924284ac98695e0f9284b8a5ef19ec67aba878c5cfd5c230c1a52a51e96
+  data.tar.gz: 51e187f62bea1dc5d59e42e4992339d9561706dd932f5169360fa1d089be7b3b
+SHA512:
+  metadata.gz: 854e39f4ec23586462d1af360a55a8cbeed2104cf889d6601139216ab7faca15ce2fd03d97cc98e6459b2568d4b13126582508ad76ed2d640e9c8276fe77cc15
+  data.tar.gz: a9881bb353650ba25476686c3d17611ddafc9862cd0225510b0ab1f13c90783946d2b15aad72d19b38dfc237afc601c55bc31c5be3bbd91fca515c94af839779

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 noraj (Alexandre ZANNI)
+
+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,131 @@
+# EUVD Ruby Gem
+
+A Ruby wrapper library for the [European Union Vulnerability Database (EUVD)](https://euvd.enisa.europa.eu/apidoc) API. Uses the [Sawyer](https://github.com/lostisland/sawyer) HTTP agent framework.
+
+All endpoints are **GET-only** and **require no authentication**.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'euvd'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself:
+
+```bash
+$ gem install euvd
+```
+
+## Usage
+
+```ruby
+require 'euvd'
+
+client = EUVD::Client.new
+```
+
+### Vulnerabilities
+
+Returns `Sawyer::Resource` objects (or `Array` of them). Access JSON fields as methods:
+
+```ruby
+results = client.vulnerabilities.latest
+# => Array<Sawyer::Resource>
+#    results.first.id, results.first.description, results.first.baseScore, ...
+
+search = client.vulnerabilities.search(text: 'log4j', size: 10, page: 0)
+# => Sawyer::Resource with .items (Array) and .total (Integer)
+#    search.items.first.id, search.total
+
+client.vulnerabilities.exploited
+client.vulnerabilities.critical
+```
+
+Search filters: `text`, `fromScore` (0-10), `toScore`, `fromEpss` (0-100), `toEpss`, `fromDate` (YYYY-MM-DD), `toDate`, `fromUpdatedDate`, `toUpdatedDate`, `product`, `vendor`, `assigner`, `exploited` (true/false), `page` (starts at 0), `size` (default 10, max 100).
+
+### Records
+
+Returns `Sawyer::Resource` objects:
+
+```ruby
+record = client.records.find('EUVD-2025-20101')
+# => Sawyer::Resource
+#    record.id, record.description, record.baseScore, record.assigner, ...
+
+# Also works with CVE or GHSA IDs
+client.records.find('CVE-2025-47228')
+client.records.find('GHSA-pfxq-29cx-gm9c')
+
+advisory = client.records.advisory('oxas-adv-2024-0002')
+# => Sawyer::Resource
+```
+
+### Downloads
+
+```ruby
+client.downloads.cve_euvd_mapping  # returns CSV String
+client.downloads.kev_dump          # returns raw JSON String
+```
+
+### Meta
+
+```ruby
+client.meta.assigners  # returns Array of assigner names
+client.meta.banner     # returns Sawyer::Resource (enabled, message)
+```
+
+### Observations
+
+```ruby
+client.observations.honeypot_by_cve('CVE-2021-44228')
+client.observations.honeypot_batch(%w[CVE-2021-44228 CVE-2021-45046])
+client.observations.kev_by_cve('CVE-2021-44228')
+client.observations.kev_batch('CVE-2021-44228')
+```
+
+### Error Handling
+
+```ruby
+begin
+  record = client.records.find('EUVD-XXXX-XXXXX')
+rescue EUVD::NotFoundError
+  puts 'Not found'
+rescue EUVD::RateLimitError
+  puts 'Rate limited'
+rescue EUVD::ServerError
+  puts 'Server error'
+rescue EUVD::BadResponseError
+  puts 'Server returned non-JSON (likely down)'
+rescue EUVD::Error => e
+  puts "Error: #{e.message}"
+end
+```
+
+### Configuration
+
+```ruby
+EUVD::Client.new(
+  base_url: 'https://euvdservices.enisa.europa.eu/api'  # default
+)
+```
+
+## Development
+
+Run the tests:
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/euvd/api/downloads.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module EUVD
+  module API
+    # Access to bulk data download endpoints.
+    class Downloads
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /api/dump/cve-euvd-mapping
+      # Downloads the CVE-to-EUVD ID mapping as CSV.
+      #
+      # @return [String] Raw CSV data
+      def cve_euvd_mapping
+        @client.get('dump/cve-euvd-mapping')
+      end
+
+      # GET /api/kev/dump
+      # Downloads the full KEV dump as JSON.
+      #
+      # @return [String] Raw JSON data
+      def kev_dump
+        @client.get('kev/dump')
+      end
+    end
+  end
+end

data/lib/euvd/api/meta.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module EUVD
+  module API
+    # Access to meta/utility endpoints (banner, assigners list).
+    class Meta
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /api/assigners/names
+      # Returns the list of assigner names.
+      #
+      # @return [Array<String>]
+      def assigners
+        @client.get('assigners/names')
+      end
+
+      # GET /api/banner
+      # Returns the banner status (enabled/message).
+      #
+      # @return [Sawyer::Resource]
+      def banner
+        @client.get('banner')
+      end
+    end
+  end
+end

data/lib/euvd/api/observations.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module EUVD
+  module API
+    # Access to honeypot observation and KEV entry endpoints.
+    class Observations
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /api/honeypotObservations?cveId=X
+      # Returns honeypot observations for a specific CVE.
+      #
+      # @param cve_id [String] CVE identifier (e.g. 'CVE-2021-44228')
+      # @return [Array<Sawyer::Resource>]
+      def honeypot_by_cve(cve_id)
+        @client.get('honeypotObservations', cveId: cve_id)
+      end
+
+      # GET /api/honeypotObservations/batch?ids=X,Y
+      # Returns honeypot observations for multiple CVEs.
+      #
+      # @param ids [Array<String>] CVE identifiers
+      # @return [Array<Sawyer::Resource>]
+      def honeypot_batch(ids)
+        ids = ids.join(',') if ids.is_a?(Array)
+        @client.get('honeypotObservations/batch', ids: ids)
+      end
+
+      # GET /api/kevEntries?cveId=X
+      # Returns KEV entries for a specific CVE.
+      #
+      # @param cve_id [String] CVE identifier
+      # @return [Array<Sawyer::Resource>]
+      def kev_by_cve(cve_id)
+        @client.get('kevEntries', cveId: cve_id)
+      end
+
+      # GET /api/kevEntries/batch?ids=X,Y
+      # Returns KEV entries for multiple CVEs.
+      #
+      # @param ids [Array<String>] CVE identifiers
+      # @return [Array<Sawyer::Resource>]
+      def kev_batch(ids)
+        ids = ids.join(',') if ids.is_a?(Array)
+        @client.get('kevEntries/batch', ids: ids)
+      end
+    end
+  end
+end

data/lib/euvd/api/records.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module EUVD
+  module API
+    # Access to specific resource endpoints: EUVD record by ID and advisory by ID.
+    class Records
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /api/enisaid?id=EUVD-XXXX-XXXXX
+      # Returns a single EUVD record by its EUVD ID.
+      #
+      # @param euvd_id [String] EUVD identifier (e.g. 'EUVD-2024-45012')
+      # @return [Sawyer::Resource]
+      def enisaid(euvd_id)
+        @client.get('enisaid', id: euvd_id)
+      end
+
+      # Alias for #enisaid.
+      alias find enisaid
+
+      # GET /api/advisory?id=XXXXX
+      # Returns a single advisory by its ID.
+      #
+      # @param advisory_id [String] Advisory identifier (e.g. 'oxas-adv-2024-0002')
+      # @return [Sawyer::Resource]
+      def advisory(advisory_id)
+        @client.get('advisory', id: advisory_id)
+      end
+    end
+  end
+end

data/lib/euvd/api/vulnerabilities.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module EUVD
+  module API
+    # Access to vulnerability endpoints: latest, critical, exploited, and search.
+    class Vulnerabilities
+      def initialize(client)
+        @client = client
+      end
+
+      # GET /api/lastvulnerabilities
+      # Returns the latest vulnerabilities (maximum 8 records).
+      #
+      # @return [Array<Sawyer::Resource>]
+      def latest
+        @client.get('lastvulnerabilities')
+      end
+
+      # GET /api/exploitedvulnerabilities
+      # Returns the latest exploited vulnerabilities (maximum 8 records).
+      #
+      # @return [Array<Sawyer::Resource>]
+      def exploited
+        @client.get('exploitedvulnerabilities')
+      end
+
+      # GET /api/criticalvulnerabilities
+      # Returns the latest critical vulnerabilities (maximum 8 records).
+      #
+      # @return [Array<Sawyer::Resource>]
+      def critical
+        @client.get('criticalvulnerabilities')
+      end
+
+      # GET /api/search
+      # Query vulnerabilities with flexible filters.
+      #
+      # @param params [Hash] Query parameters
+      # @option params [String] :text Keywords (searches across description, EUVD ID, aliases, product, vendor)
+      # @option params [Float] :fromScore Minimum CVSS score (0-10)
+      # @option params [Float] :toScore Maximum CVSS score (0-10)
+      # @option params [Integer] :fromEpss Minimum EPSS score (0-100)
+      # @option params [Integer] :toEpss Maximum EPSS score (0-100)
+      # @option params [String] :fromDate Minimum published date (YYYY-MM-DD)
+      # @option params [String] :toDate Maximum published date (YYYY-MM-DD)
+      # @option params [String] :fromUpdatedDate Minimum updated date (YYYY-MM-DD)
+      # @option params [String] :toUpdatedDate Maximum updated date (YYYY-MM-DD)
+      # @option params [String] :product Product name
+      # @option params [String] :vendor Vendor name
+      # @option params [String] :assigner Assigner name
+      # @option params [Boolean] :exploited Filter by exploited status
+      # @option params [Integer] :page Page number (starts at 0)
+      # @option params [Integer] :size Page size (default 10, max 100)
+      # @return [Sawyer::Resource] Search results with +.items+ (Array) and +.total+ (Integer)
+      def search(params = {})
+        @client.get('search', params)
+      end
+    end
+  end
+end

data/lib/euvd/client.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'sawyer'
+
+module EUVD
+  # Error base class for all EUVD client errors.
+  class Error < StandardError; end
+
+  # Raised when the API returns a non-JSON response (e.g. HTML error page).
+  class BadResponseError < Error; end
+
+  # Raised when a resource is not found (HTTP 404).
+  class NotFoundError < Error; end
+
+  # Raised when the API rate limit is exceeded (HTTP 429).
+  class RateLimitError < Error; end
+
+  # Raised when the API returns a server error (HTTP 5xx).
+  class ServerError < Error; end
+
+  # Client for the EUVD API.
+  #
+  # All endpoints are GET-only and require no authentication.
+  # JSON responses are returned as rich +Sawyer::Resource+ objects
+  # (or Array of them), so you can access fields as methods
+  # instead of hash keys.
+  class Client
+    BASE_URL = 'https://euvdservices.enisa.europa.eu/api'
+
+    attr_reader :base_url, :agent
+
+    # @param options [Hash]
+    # @option options [String] :base_url API base URL (default: EUVD::Client::BASE_URL)
+    def initialize(options = {})
+      @base_url = options[:base_url] || BASE_URL
+      @agent = build_agent
+    end
+
+    # Make a GET request and return parsed response data.
+    #
+    # @param path [String] API path (e.g. 'lastvulnerabilities')
+    # @param params [Hash] Query parameters
+    # @return [Sawyer::Resource, Array, String] parsed data
+    def get(path, params = {})
+      response = @agent.call(:get, path, nil, query: params)
+      response = handle_status(response)
+      validate_content_type!(response)
+      response.data
+    end
+
+    # @return [EUVD::API::Vulnerabilities]
+    def vulnerabilities
+      API::Vulnerabilities.new(self)
+    end
+
+    # @return [EUVD::API::Records]
+    def records
+      API::Records.new(self)
+    end
+
+    # @return [EUVD::API::Downloads]
+    def downloads
+      API::Downloads.new(self)
+    end
+
+    # @return [EUVD::API::Meta]
+    def meta
+      API::Meta.new(self)
+    end
+
+    # @return [EUVD::API::Observations]
+    def observations
+      API::Observations.new(self)
+    end
+
+    def inspect
+      format('#<%<class_name>s:0x%<object_id>x %<url>s>',
+             class_name: self.class,
+             object_id: object_id * 2,
+             url: @base_url)
+    end
+
+    private
+
+    def build_agent
+      conn = Faraday.new(url: @base_url) do |b|
+        b.request :url_encoded
+        b.adapter Faraday.default_adapter
+      end
+
+      Sawyer::Agent.new(@base_url, faraday: conn) do |http|
+        http.headers['Accept'] = 'application/json'
+        http.headers['User-Agent'] = "euvd-ruby/#{EUVD::VERSION}"
+      end
+    end
+
+    def handle_status(response)
+      case response.status
+      when 200..299
+        response
+      when 404
+        raise NotFoundError, "Resource not found at #{response.env.url}"
+      when 429
+        raise RateLimitError, 'API rate limit exceeded'
+      when 500..599
+        raise ServerError, "Server error (#{response.status})"
+      else
+        raise Error, "Unexpected response (#{response.status})"
+      end
+    end
+
+    def validate_content_type!(response)
+      ct = response.headers['content-type'].to_s
+      allowed = %w[application/json application/problem+json text/csv text/plain]
+      return if allowed.any? { |t| ct.include?(t) }
+
+      snippet = response.body.to_s.gsub(/\s+/, ' ').strip[0..120]
+      raise BadResponseError, "Expected JSON/text but got '#{ct}' (HTTP #{response.status}): #{snippet.inspect}"
+    end
+  end
+end

data/lib/euvd/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module EUVD
+  VERSION = '0.1.0'
+end

data/lib/euvd.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative 'euvd/version'
+require_relative 'euvd/client'
+require_relative 'euvd/api/vulnerabilities'
+require_relative 'euvd/api/records'
+require_relative 'euvd/api/downloads'
+require_relative 'euvd/api/meta'
+require_relative 'euvd/api/observations'

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: euvd
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alexandre ZANNI
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: sawyer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: A Ruby client library for the EUVD (European Union Vulnerability Database)
+  API. Provides a convenient interface to search and retrieve vulnerability information,
+  CVEs, CPEs, CWEs, CAPECs, and advisories.
+email: alexandre.zanni@europe.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/euvd.rb
+- lib/euvd/api/downloads.rb
+- lib/euvd/api/meta.rb
+- lib/euvd/api/observations.rb
+- lib/euvd/api/records.rb
+- lib/euvd/api/vulnerabilities.rb
+- lib/euvd/client.rb
+- lib/euvd/version.rb
+homepage: https://github.com/noraj/euvd
+licenses:
+- MIT
+metadata:
+  yard.run: yard
+  bug_tracker_uri: https://github.com/noraj/euvd/issues
+  changelog_uri: https://github.com/noraj/euvd/releases
+  documentation_uri: https://noraj.github.io/euvd/
+  homepage_uri: https://github.com/noraj/euvd
+  source_code_uri: https://github.com/noraj/euvd/
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: '5.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Ruby wrapper for the European Union Vulnerability Database (EUVD) API
+test_files: []