feat: add security advisory lookup command

closes #4

Author: andrew

README.md

@@ -16,10 +16,12 @@ 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, 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
+- **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
@@ -70,6 +72,7 @@ purl url <purl-string>                # Convert PURL to registry URL
 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
@@ -80,6 +83,7 @@ All commands support JSON output with the `--json` flag:
 purl --json parse "pkg:gem/[email protected]"
 purl --json info gem
 purl --json lookup "pkg:cargo/rand"
+purl --json advisories "pkg:npm/[email protected]"
 ```
 
 ### Command Examples
@@ -228,6 +232,60 @@ $ purl --json lookup "pkg:cargo/[email protected]"
 }
 ```
 
+#### Look Up Security Advisories
+```bash
+$ purl advisories "pkg:npm/[email protected]"
+Security Advisories for pkg:npm/[email protected]
+================================================================================
+
+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/[email protected]"
+{
+  "success": true,
+  "purl": "pkg:npm/[email protected]",
+  "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:
@@ -465,6 +523,42 @@ puts info[:reverse_parsing]           # => 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/[email protected]")
+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

exe/purl

@@ -44,6 +44,8 @@ class PurlCLI
       info_command(args)
     when "lookup"
       lookup_command(args)
+    when "advisories"
+      advisories_command(args)
     when "--help", "-h", "help"
       puts usage
       exit 0
@@ -64,18 +66,19 @@ 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] 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/[email protected]"
@@ -86,6 +89,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/[email protected]"
     USAGE
   end
 
@@ -430,17 +434,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,7 +457,7 @@ class PurlCLI
           exit 1
         end
       end
-      
+
     rescue Purl::LookupError => e
       output_error("Lookup failed: #{e.message}")
       exit 1
@@ -466,6 +470,43 @@ class PurlCLI
     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("Advisory lookup failed: #{e.message}")
+      exit 1
+    end
+  end
+
   def output_error(message)
     if @json_output
       result = {

lib/purl.rb

@@ -6,6 +6,8 @@
 require_relative "purl/registry_url"
 require_relative "purl/lookup"
 require_relative "purl/lookup_formatter"
+require_relative "purl/advisory"
+require_relative "purl/advisory_formatter"
 
 # The main PURL (Package URL) module providing functionality to parse,
 # validate, and generate package URLs according to the PURL specification.

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/[email protected]")
+    #   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