RFC: Improve API with a new V2 for packages

[pombredanne]

I suggest we simplify and evolve the API to a version 2 that would return this data shape, when querying the packages/ endpoint for one or more PURLs.

We would enable filters based on PURL components and whole PURLs, as well as "affected by" or "fixing" VCID. This would replace all the packages/ endpoints, and would privilege the primary use case: lookup by PURL.

purls:
    - purl: pkg:apache/httpd@1.3.0
      affected_by_vulnerabilities:
        - VCID-2spt-jvsb-aaak
        - VCID-je6z-ydc6-aaap
        - VCID-z4hk-71j3-aaar
      fixing_vulnerabilities: []
      next_non_vulnerable_purl: 
      latest_non_vulnerable_purl: 

    - purl: pkg:apache/httpd@1.3.1
      affected_by_vulnerabilities:
        - VCID-2spt-jvsb-aaak
        - VCID-2wjk-ntty-aaab
        - VCID-9qha-2aq6-aaap
      fixing_vulnerabilities:
        - VCID-2spt-jvsb-aaak
        - VCID-2wjk-ntty-aaab
      next_non_vulnerable_purl: 
      latest_non_vulnerable_purl: 

vulnerabilities:
  - vulnerability_id: VCID-18z2-2yw1-aaaj
    aliases:
      - CVE-2010-2263
    summary: Vulnerabilities with Windows file default stream
    severities: []
    weaknesses: []
    references:
      - url: https://nvd.nist.gov/vuln/detail/CVE-2010-2263
        reference_type:
        reference_id: CVE-2010-2263

  - vulnerability_id: VCID-1dsf-ryt7-aaan
    aliases:
      - CVE-2000-0913
    summary: 'The Rewrite module, mod_rewrite, can allow access to any file on the web server. The
      vulnerability occurs only with certain specific cases of using regular expression references
      in RewriteRule directives: If the destination of a RewriteRule contains regular expression
      references then an attacker will be able to access any file on the server.'
    severities:
      - score: important
        scoring_system: apache_httpd
        scoring_elements:
        published_at:
        reference:
          url: https://httpd.apache.org/security/json/CVE-2000-0913.json
          reference_type:
          reference_id: CVE-2000-0913
    weaknesses: []
    references:
      - url: https://httpd.apache.org/security/json/CVE-2000-0913.json
        reference_type:
        reference_id: CVE-2000-0913

When querying the vulnerabilities/ endpoint for one or more VCID, we would return the "vulnerabilities" section above. We could enable a filter based on an exact alias value, like a CPE or keep it as a separate endpoint. This would otherwise replace all endpoints on vulnerabilities/ as the main endpoint is packages/

[pombredanne]

@TG1999 @tdruez @keshav-space input welcomed!

[pombredanne]

The benefits is that a simple API call will return all the needed data, but there are no complex inlining or nesting of the data.

[tdruez]

@pombredanne The new structure looks fine. I would suggest that we introduce a new endpoint for now instead of a full API v2. Also, the vulnerabilities should be a mapping by VCID to make it easier on the client to consume the data.

[pombredanne]

We could get the vulnerabilities section this way then:

vulnerabilities_by_id:
  VCID-18z2-2yw1-aaaj:
    vulnerability_id: VCID-18z2-2yw1-aaaj
    aliases:
      - CVE-2010-2263
    summary: Vulnerabilities with Windows file default stream
    severities: []
    weaknesses: []
    references:
      - url: https://nvd.nist.gov/vuln/detail/CVE-2010-2263
        reference_type:
        reference_id: CVE-2010-2263
  VCID-1dsf-ryt7-aaan:
    vulnerability_id: VCID-1dsf-ryt7-aaan
    aliases:
      - CVE-2000-0913
    summary: 'The Rewrite module, mod_rewrite, can allow access to any file on the web server.
      The vulnerability occurs only with certain specific cases of using regular expression
      references in RewriteRule directives: If the destination of a RewriteRule contains regular
      expression references then an attacker will be able to access any file on the server.'
    severities:
      - score: important
        scoring_system: apache_httpd
        scoring_elements:
        published_at:
        reference:
          url: https://httpd.apache.org/security/json/CVE-2000-0913.json
          reference_type:
          reference_id: CVE-2000-0913
    weaknesses: []
    references:
      - url: https://httpd.apache.org/security/json/CVE-2000-0913.json
        reference_type:
        reference_id: CVE-2000-0913

[tdruez]

I've noticed that the weaknesses data is available in the /api/vulnerabilities/ details endpoint but not in the packages one. This is problematic for data collection through the API. Make sure to include it in this new endpoint implementation.