purl 1.5.2 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02f6f258696c085108708cd45f9424357176d9efb2edecac7dac70e85bb2b98a
-  data.tar.gz: 14e4f7a9ad77af4f4ea3d3a6a26041db433271515db710b94129f46af90318c3
+  metadata.gz: 02a4895e51ce7c9ace65a53d97fd8d4c5d288d7137daa71c9e8b8a778595e6cb
+  data.tar.gz: 55d348a442e23a0ffddc2b236bc1be22c9cf29d8eac0ce3ff289ce637e1ba6f5
 SHA512:
-  metadata.gz: 623efd5ec3004f5a8ba188a067a894fd2a666ce2607de4c0243151342504446a551e081834e1692d5c52d24db8aaa37b2aa70c80a22969caf8235205661aa3cb
-  data.tar.gz: 7fa445d38884d3df2537da649fcdcde0ea5a6c57b504d446f2e9c17b8544f160637ea8c8deb1da3879387954ef7384a36a85fbcfd51223f330955ba3ae46ab08
+  metadata.gz: 4f8ff4ff13c1184c4b1adf6950fc1d04acedb8ce2cbbf4d62f2430455567e98f8b153b5493732919e1921a55132a2f3f51b61157b6eba85e207e6675d8675771
+  data.tar.gz: 9f203b73ef705fe70a27de5aae3b85558bd34204a2362a7429c441dc7f66d4a5ae403741fcb36471ab33e972868e4d31e6121a5eeaf23fb88832e3d38fec1e9c

data/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.7.0] - 2026-01-02
+
+### Added
+- Download URL generation for 18 package ecosystems
+  - `download_url` instance method on `PackageURL` for getting artifact download URLs
+  - `supports_download_url?` method to check if download URL generation is supported
+  - `Purl.download_supported_types` to list all types with download URL support
+  - `download` command in CLI for getting download URLs from PURLs
+- Supported types: bioconductor, bitbucket, cargo, clojars, cran, elm, gem, github, gitlab, golang, hackage, hex, luarocks, maven, npm, nuget, pub, swift
+- Support for `repository_url` qualifier to use custom registries for downloads
+- Support for custom base URLs via parameter override
+
+## [1.6.0] - 2025-10-24
+
+### Added
+- `advisories` command to CLI for looking up security advisories from advisories.ecosyste.ms API
+- `advisories` instance method on `PackageURL` for programmatic advisory retrieval
+
+### Changed
+- Updated to PURL specification v1.1
+
 ## [1.5.2] - 2025-08-06
 
 ### Fixed

data/README.md

@@ -16,10 +16,13 @@ This library features comprehensive error handling with namespaced error types,
 
 ## Features
 
-- **Command-line interface** with parse, validate, convert, generate, and info commands plus JSON output
+- **Command-line interface** with parse, validate, convert, download, generate, info, lookup, and advisories commands plus JSON output
 - **Comprehensive PURL parsing and validation** with 37 package types (32 official + 5 additional ecosystems)
 - **Better error handling** with namespaced error classes and contextual information
 - **Bidirectional registry URL conversion** - generate registry URLs from PURLs and parse PURLs from registry URLs
+- **Download URL generation** for 18 package ecosystems (gem, npm, cargo, maven, etc.)
+- **Security advisory lookup** - query security advisories from advisories.ecosyste.ms
+- **Package information lookup** - query package metadata from ecosyste.ms
 - **Type-specific validation** for conan, cran, and swift packages
 - **Registry URL generation** for 20 package ecosystems (npm, gem, maven, pypi, etc.)
 - **Rails-style route patterns** for registry URL templates
@@ -67,8 +70,11 @@ purl parse <purl-string>              # Parse and display PURL components
 purl validate <purl-string>           # Validate a PURL (exit code indicates success)
 purl convert <registry-url>           # Convert registry URL to PURL
 purl url <purl-string>                # Convert PURL to registry URL
+purl download <purl-string>           # Get download URL for package version
 purl generate [options]               # Generate PURL from components
 purl info [type]                      # Show information about PURL types
+purl lookup <purl-string>             # Look up package information from ecosyste.ms
+purl advisories <purl-string>         # Look up security advisories from advisories.ecosyste.ms
 ```
 
 ### JSON Output
@@ -78,6 +84,8 @@ All commands support JSON output with the `--json` flag:
 ```bash
 purl --json parse "pkg:gem/rails@7.0.0"
 purl --json info gem
+purl --json lookup "pkg:cargo/rand"
+purl --json advisories "pkg:npm/lodash@4.17.19"
 ```
 
 ### Command Examples
@@ -144,6 +152,26 @@ $ purl --json url "pkg:gem/rails@7.0.0"
 }
 ```
 
+#### Get Download URL
+```bash
+$ purl download "pkg:gem/rails@7.0.0"
+https://rubygems.org/downloads/rails-7.0.0.gem
+
+$ purl download "pkg:npm/@babel/core@7.20.0"
+https://registry.npmjs.org/@babel/core/-/core-7.20.0.tgz
+
+$ purl download "pkg:cargo/serde@1.0.152"
+https://static.crates.io/crates/serde/serde-1.0.152.crate
+
+$ purl --json download "pkg:maven/org.apache.commons/commons-lang3@3.12.0"
+{
+  "success": true,
+  "purl": "pkg:maven/org.apache.commons/commons-lang3@3.12.0",
+  "download_url": "https://repo.maven.apache.org/maven2/org/apache/commons/commons-lang3/3.12.0/commons-lang3-3.12.0.jar",
+  "type": "maven"
+}
+```
+
 #### Generate a PURL
 ```bash
 $ purl generate --type gem --name rails --version 7.0.0
@@ -182,6 +210,104 @@ Total types: 37
 Registry supported: 20
 ```
 
+#### Look Up Package Information
+```bash
+$ purl lookup "pkg:cargo/rand"
+Package: rand (cargo)
+Description: Random number generators and other randomness functionality.
+Homepage: https://rust-random.github.io/book
+Repository: https://github.com/rust-random/rand
+License: MIT OR Apache-2.0
+Downloads: 145,678,901
+Latest Version: 0.8.5
+Published: 2023-01-13T17:47:01.870Z
+
+$ purl --json lookup "pkg:cargo/rand@0.8.5"
+{
+  "success": true,
+  "purl": "pkg:cargo/rand@0.8.5",
+  "package": {
+    "name": "rand",
+    "ecosystem": "cargo",
+    "description": "Random number generators and other randomness functionality.",
+    "homepage": "https://rust-random.github.io/book",
+    "repository_url": "https://github.com/rust-random/rand",
+    "registry_url": "https://crates.io/crates/rand",
+    "licenses": "MIT OR Apache-2.0",
+    "latest_version": "0.8.5",
+    "latest_version_published_at": "2023-01-13T17:47:01.870Z",
+    "versions_count": 89,
+    "maintainers": [
+      {
+        "login": "dhardy",
+        "name": "Diggory Hardy"
+      }
+    ]
+  },
+  "version": {
+    "number": "0.8.5",
+    "published_at": "2023-01-13T17:47:01.870Z",
+    "registry_url": "https://crates.io/crates/rand/0.8.5",
+    "downloads": 5678901,
+    "size": 102400
+  }
+}
+```
+
+#### Look Up Security Advisories
+```bash
+$ purl advisories "pkg:npm/lodash@4.17.19"
+Security Advisories for pkg:npm/lodash@4.17.19
+================================================================================
+
+Advisory #1: Regular Expression Denial of Service (ReDoS) in lodash
+Identifiers: GHSA-x5rq-j2xg-h7qm, CVE-2019-1010266
+Severity: MODERATE
+
+Description:
+  lodash prior to 4.7.11 is affected by: CWE-400: Uncontrolled Resource
+  Consumption. The impact is: Denial of service. The component is: Date
+  handler. The attack vector is: Attacker provides very long strings, which
+  the library attempts to match using a regular expression. The fixed version
+  is: 4.7.11.
+
+Affected Packages:
+  Package: npm/lodash
+  Vulnerable: >= 4.7.0, < 4.17.11
+  Patched: 4.17.11
+
+Source: github | Origin: UNSPECIFIED | Published: 2019-07-19T16:13:07.000Z
+Advisory URL: https://github.com/advisories/GHSA-x5rq-j2xg-h7qm
+
+Total advisories found: 3
+
+$ purl --json advisories "pkg:npm/lodash@4.17.19"
+{
+  "success": true,
+  "purl": "pkg:npm/lodash@4.17.19",
+  "advisories": [
+    {
+      "id": "MDE2OlNlY3VyaXR5QWR2aXNvcnlHSFNBLXg1cnEtajJ4Zy1oN3Ft",
+      "title": "Regular Expression Denial of Service (ReDoS) in lodash",
+      "description": "lodash prior to 4.7.11 is affected by...",
+      "severity": "MODERATE",
+      "url": "https://github.com/advisories/GHSA-x5rq-j2xg-h7qm",
+      "published_at": "2019-07-19T16:13:07.000Z",
+      "affected_packages": [
+        {
+          "ecosystem": "npm",
+          "name": "lodash",
+          "vulnerable_version_range": ">= 4.7.0, < 4.17.11",
+          "first_patched_version": "4.17.11"
+        }
+      ],
+      "identifiers": ["GHSA-x5rq-j2xg-h7qm", "CVE-2019-1010266"]
+    }
+  ],
+  "count": 3
+}
+```
+
 ### Generate Options
 
 The `generate` command supports all PURL components:
@@ -304,6 +430,42 @@ purl = Purl.parse("pkg:npm/@babel/core@7.0.0")
 puts purl.registry_url                # => "https://www.npmjs.com/package/@babel/core"
 ```
 
+### Download URL Generation
+
+Generate direct download URLs for package artifacts:
+
+```ruby
+# Generate download URLs from PURLs
+purl = Purl.parse("pkg:gem/rails@7.0.0")
+puts purl.download_url  # => "https://rubygems.org/downloads/rails-7.0.0.gem"
+
+# Check if download URL generation is supported
+puts purl.supports_download_url?  # => true
+
+# NPM with scoped packages
+purl = Purl.parse("pkg:npm/@babel/core@7.20.0")
+puts purl.download_url  # => "https://registry.npmjs.org/@babel/core/-/core-7.20.0.tgz"
+
+# Maven packages
+purl = Purl.parse("pkg:maven/org.apache.commons/commons-lang3@3.12.0")
+puts purl.download_url  # => "https://repo.maven.apache.org/maven2/org/apache/commons/commons-lang3/3.12.0/commons-lang3-3.12.0.jar"
+
+# Custom registry via repository_url qualifier
+purl = Purl.parse("pkg:npm/lodash@4.17.21?repository_url=https://npm.mycompany.com")
+puts purl.download_url  # => "https://npm.mycompany.com/lodash/-/lodash-4.17.21.tgz"
+
+# Custom registry via parameter
+purl = Purl.parse("pkg:gem/rails@7.0.0")
+puts purl.download_url(base_url: "https://gems.internal.com/downloads")
+# => "https://gems.internal.com/downloads/rails-7.0.0.gem"
+
+# Get list of supported types
+puts Purl.download_supported_types
+# => ["bioconductor", "bitbucket", "cargo", "clojars", "cran", "elm", "gem",
+#     "github", "gitlab", "golang", "hackage", "hex", "luarocks", "maven",
+#     "npm", "nuget", "pub", "swift"]
+```
+
 ### Reverse Parsing: Registry URLs to PURLs
 
 ```ruby
@@ -397,6 +559,7 @@ puts Purl.known_types.include?("gem") # => true
 puts Purl.known_type?("gem")                    # => true
 puts Purl.registry_supported_types              # => ["cargo", "gem", "maven", "npm", ...]
 puts Purl.reverse_parsing_supported_types       # => ["bioconductor", "cargo", "clojars", ...]
+puts Purl.download_supported_types              # => ["cargo", "gem", "maven", "npm", ...]
 
 # Get default registry for a type
 puts Purl.default_registry("gem")               # => "https://rubygems.org"
@@ -416,9 +579,46 @@ puts info[:default_registry]          # => "https://rubygems.org"
 puts info[:examples]                  # => ["pkg:gem/rails@7.0.4", ...]
 puts info[:registry_url_generation]   # => true
 puts info[:reverse_parsing]           # => true
+puts info[:download_url_generation]   # => true
 puts info[:route_patterns]            # => ["https://rubygems.org/gems/:name", ...]
 ```
 
+### Security Advisory Lookup
+
+Look up security advisories for packages using the advisories.ecosyste.ms API:
+
+```ruby
+# Look up advisories for a package
+purl = Purl.parse("pkg:npm/lodash@4.17.19")
+advisories = purl.advisories
+
+# Display advisory information
+advisories.each do |advisory|
+  puts "Title: #{advisory[:title]}"
+  puts "Severity: #{advisory[:severity]}"
+  puts "Description: #{advisory[:description]}"
+  puts "URL: #{advisory[:url]}"
+
+  # Show affected packages
+  advisory[:affected_packages].each do |pkg|
+    puts "  Package: #{pkg[:ecosystem]}/#{pkg[:name]}"
+    puts "  Vulnerable: #{pkg[:vulnerable_version_range]}"
+    puts "  Patched: #{pkg[:first_patched_version]}" if pkg[:first_patched_version]
+  end
+
+  # Show identifiers (CVE, GHSA, etc.)
+  puts "Identifiers: #{advisory[:identifiers].join(', ')}"
+  puts
+end
+
+# Look up advisories for any version of a package
+purl = Purl.parse("pkg:npm/lodash")
+all_advisories = purl.advisories
+
+# Use custom user agent and timeout
+advisories = purl.advisories(user_agent: "my-app/1.0", timeout: 5)
+```
+
 ### Error Handling
 
 ```ruby
@@ -470,6 +670,26 @@ The library supports 37 package types (32 official + 5 additional ecosystems):
 **Reverse Parsing (20 types):**
 - `bioconductor`, `cargo`, `clojars`, `cocoapods`, `composer`, `conda`, `cpan`, `deno`, `elm`, `gem`, `golang`, `hackage`, `hex`, `homebrew`, `maven`, `npm`, `nuget`, `pub`, `pypi`, `swift`
 
+**Download URL Generation (18 types):**
+- `bioconductor` - bioconductor.org/packages/release/bioc/src/contrib
+- `bitbucket` - bitbucket.org archive downloads
+- `cargo` - static.crates.io/crates
+- `clojars` - repo.clojars.org (Maven-style)
+- `cran` - cran.r-project.org/src/contrib
+- `elm` - GitHub archive downloads
+- `gem` - rubygems.org/downloads
+- `github` - GitHub archive downloads
+- `gitlab` - GitLab archive downloads
+- `golang` - proxy.golang.org
+- `hackage` - hackage.haskell.org/package
+- `hex` - repo.hex.pm/tarballs
+- `luarocks` - luarocks.org/manifests
+- `maven` - repo.maven.apache.org/maven2
+- `npm` - registry.npmjs.org
+- `nuget` - api.nuget.org/v3-flatcontainer
+- `pub` - pub.dev/packages
+- `swift` - GitHub/GitLab/Bitbucket (derived from namespace)
+
 **All 37 Supported Types:**
 `alpm`, `apk`, `bioconductor`, `bitbucket`, `bitnami`, `cargo`, `clojars`, `cocoapods`, `composer`, `conan`, `conda`, `cpan`, `cran`, `deb`, `deno`, `docker`, `elm`, `gem`, `generic`, `github`, `golang`, `hackage`, `hex`, `homebrew`, `huggingface`, `luarocks`, `maven`, `mlflow`, `npm`, `nuget`, `oci`, `pub`, `pypi`, `qpkg`, `rpm`, `swid`, `swift`
 

data/exe/purl

@@ -40,10 +40,14 @@ class PurlCLI
       generate_command(args)
     when "url"
       url_command(args)
+    when "download"
+      download_command(args)
     when "info"
       info_command(args)
     when "lookup"
       lookup_command(args)
+    when "advisories"
+      advisories_command(args)
     when "--help", "-h", "help"
       puts usage
       exit 0
@@ -64,18 +68,20 @@ class PurlCLI
       purl - Parse, validate, convert and generate Package URLs (PURLs)
 
       Usage:
-        purl [--json] parse <purl-string>     Parse and display PURL components
-        purl [--json] validate <purl-string>  Validate a PURL (exit code indicates success)
-        purl [--json] convert <registry-url>  Convert registry URL to PURL
-        purl [--json] url <purl-string>       Convert PURL to registry URL
-        purl [--json] generate [options]      Generate PURL from components
-        purl [--json] info [type]             Show information about PURL types
-        purl [--json] lookup <purl-string>    Look up package information from ecosyste.ms
-        purl --version                        Show version
-        purl --help                           Show this help
+        purl [--json] parse <purl-string>       Parse and display PURL components
+        purl [--json] validate <purl-string>    Validate a PURL (exit code indicates success)
+        purl [--json] convert <registry-url>    Convert registry URL to PURL
+        purl [--json] url <purl-string>         Convert PURL to registry URL
+        purl [--json] download <purl-string>    Get download URL for package version
+        purl [--json] generate [options]        Generate PURL from components
+        purl [--json] info [type]               Show information about PURL types
+        purl [--json] lookup <purl-string>      Look up package information from ecosyste.ms
+        purl [--json] advisories <purl-string>  Look up security advisories from advisories.ecosyste.ms
+        purl --version                          Show version
+        purl --help                             Show this help
 
       Global Options:
-        --json                                Output results in JSON format
+        --json                                  Output results in JSON format
 
       Examples:
         purl parse "pkg:gem/rails@7.0.0"
@@ -86,6 +92,7 @@ class PurlCLI
         purl generate --type gem --name rails --version 7.0.0
         purl --json info gem
         purl lookup "pkg:cargo/rand"
+        purl advisories "pkg:npm/lodash@4.17.20"
     USAGE
   end
 
@@ -273,6 +280,73 @@ class PurlCLI
     end
   end
 
+  def download_command(args)
+    if args.empty?
+      output_error("PURL string required")
+      exit 1
+    end
+
+    purl_string = args[0]
+
+    begin
+      purl = Purl.parse(purl_string)
+
+      unless purl.supports_download_url?
+        if @json_output
+          result = {
+            success: false,
+            purl: purl_string,
+            error: "Download URL generation not supported for type '#{purl.type}'",
+            supported_types: Purl.download_supported_types
+          }
+          puts JSON.pretty_generate(result)
+        else
+          puts "Error: Download URL generation not supported for type '#{purl.type}'"
+          puts "Supported types: #{Purl.download_supported_types.join(', ')}"
+        end
+        exit 1
+      end
+
+      download_url = purl.download_url
+
+      if @json_output
+        result = {
+          success: true,
+          purl: purl.to_s,
+          download_url: download_url,
+          type: purl.type
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts download_url
+      end
+    rescue Purl::MissingVersionError => e
+      if @json_output
+        result = {
+          success: false,
+          purl: purl_string,
+          error: "Version required for download URL"
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts "Error: Version required for download URL"
+      end
+      exit 1
+    rescue Purl::Error => e
+      if @json_output
+        result = {
+          success: false,
+          purl: purl_string,
+          error: e.message
+        }
+        puts JSON.pretty_generate(result)
+      else
+        puts "Error: #{e.message}"
+      end
+      exit 1
+    end
+  end
+
   def generate_command(args)
     options = {}
     OptionParser.new do |opts|
@@ -430,17 +504,17 @@ class PurlCLI
     end
 
     purl_string = args[0]
-    
+
     begin
       # Validate PURL first
       purl = Purl.parse(purl_string)
-      
+
       # Use the library lookup method
       info = purl.lookup(user_agent: "purl-ruby-cli/#{Purl::VERSION}")
-      
+
       # Use formatter to generate output
       formatter = Purl::LookupFormatter.new
-      
+
       if @json_output
         result = formatter.format_json(info, purl)
         puts JSON.pretty_generate(result)
@@ -453,15 +527,52 @@ class PurlCLI
           exit 1
         end
       end
-      
+
+    rescue Purl::LookupError => e
+      output_error("Lookup failed: #{e.message}")
+      exit 1
     rescue Purl::Error => e
       output_error("Invalid PURL: #{e.message}")
       exit 1
-    rescue Purl::LookupError => e
+    rescue StandardError => e
       output_error("Lookup failed: #{e.message}")
       exit 1
+    end
+  end
+
+  def advisories_command(args)
+    if args.empty?
+      output_error("PURL string required")
+      exit 1
+    end
+
+    purl_string = args[0]
+
+    begin
+      # Validate PURL first
+      purl = Purl.parse(purl_string)
+
+      # Use the library advisories method
+      advisories = purl.advisories(user_agent: "purl-ruby-cli/#{Purl::VERSION}")
+
+      # Use formatter to generate output
+      formatter = Purl::AdvisoryFormatter.new
+
+      if @json_output
+        result = formatter.format_json(advisories, purl)
+        puts JSON.pretty_generate(result)
+      else
+        puts formatter.format_text(advisories, purl)
+      end
+
+    rescue Purl::AdvisoryError => e
+      output_error("Advisory lookup failed: #{e.message}")
+      exit 1
+    rescue Purl::Error => e
+      output_error("Invalid PURL: #{e.message}")
+      exit 1
     rescue StandardError => e
-      output_error("Lookup failed: #{e.message}")
+      output_error("Advisory lookup failed: #{e.message}")
       exit 1
     end
   end

data/lib/purl/advisory.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "timeout"
+
+module Purl
+  # Provides advisory lookup functionality for packages using the advisories.ecosyste.ms API
+  class Advisory
+    ADVISORIES_API_BASE = "https://advisories.ecosyste.ms/api/v1"
+
+    # Initialize a new Advisory instance
+    #
+    # @param user_agent [String] User agent string for API requests
+    # @param timeout [Integer] Request timeout in seconds
+    def initialize(user_agent: nil, timeout: 10)
+      @user_agent = user_agent || "purl-ruby/#{Purl::VERSION}"
+      @timeout = timeout
+    end
+
+    # Look up security advisories for a given PURL
+    #
+    # @param purl [String, PackageURL] PURL string or PackageURL object
+    # @return [Array<Hash>, nil] Array of advisory hashes or nil if none found
+    # @raise [AdvisoryError] if the lookup fails due to network or API errors
+    #
+    # @example
+    #   advisory = Purl::Advisory.new
+    #   advisories = advisory.lookup("pkg:npm/lodash@4.17.20")
+    #   advisories.each { |adv| puts adv[:title] }
+    def lookup(purl)
+      purl_obj = purl.is_a?(PackageURL) ? purl : PackageURL.parse(purl.to_s)
+
+      # Query advisories API
+      uri = URI("#{ADVISORIES_API_BASE}/advisories/lookup")
+      uri.query = URI.encode_www_form({ purl: purl_obj.to_s })
+
+      response_data = make_request(uri)
+
+      if response_data.is_a?(Array) && response_data.length > 0
+        advisories = response_data.map { |advisory_data| extract_advisory_info(advisory_data) }
+
+        # Filter by version if specified
+        if purl_obj.version
+          advisories = filter_by_version(advisories, purl_obj.version)
+        end
+
+        return advisories
+      end
+
+      []
+    end
+
+    private
+
+    def make_request(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.read_timeout = @timeout
+      http.open_timeout = @timeout
+
+      request = Net::HTTP::Get.new(uri)
+      request["User-Agent"] = @user_agent
+
+      response = http.request(request)
+
+      case response.code.to_i
+      when 200
+        JSON.parse(response.body)
+      when 404
+        []
+      else
+        raise AdvisoryError, "API request failed with status #{response.code}"
+      end
+    rescue JSON::ParserError => e
+      raise AdvisoryError, "Failed to parse API response: #{e.message}"
+    rescue Timeout::Error, Net::OpenTimeout, Net::ReadTimeout => e
+      raise AdvisoryError, "Request timeout: #{e.message}"
+    rescue StandardError => e
+      raise AdvisoryError, "Advisory lookup failed: #{e.message}"
+    end
+
+    def extract_advisory_info(advisory_data)
+      {
+        id: advisory_data["uuid"],
+        title: advisory_data["title"],
+        description: advisory_data["description"],
+        severity: advisory_data["severity"],
+        cvss_score: advisory_data["cvss_score"],
+        cvss_vector: advisory_data["cvss_vector"],
+        url: advisory_data["url"],
+        repository_url: advisory_data["repository_url"],
+        published_at: advisory_data["published_at"],
+        updated_at: advisory_data["updated_at"],
+        withdrawn_at: advisory_data["withdrawn_at"],
+        source_kind: advisory_data["source_kind"],
+        origin: advisory_data["origin"],
+        classification: advisory_data["classification"],
+        affected_packages: extract_affected_packages(advisory_data["packages"]),
+        references: advisory_data["references"],
+        identifiers: advisory_data["identifiers"]
+      }.compact
+    end
+
+    def extract_affected_packages(packages)
+      return [] unless packages && packages.is_a?(Array)
+
+      packages.map do |pkg|
+        version_info = pkg["versions"]&.first || {}
+        {
+          ecosystem: pkg["ecosystem"],
+          name: pkg["package_name"],
+          purl: pkg["purl"],
+          vulnerable_version_range: version_info["vulnerable_version_range"],
+          first_patched_version: version_info["first_patched_version"]
+        }.compact
+      end
+    end
+
+    def filter_by_version(advisories, version)
+      # For now, return all advisories if version is specified
+      # More sophisticated version range matching could be added later
+      advisories
+    end
+  end
+
+  # Error raised when advisory lookup fails
+  class AdvisoryError < Error
+    def initialize(message)
+      super(message)
+    end
+  end
+end