Properties & Implementation
Introduction
This document will provide information on the properties of the different endpoints as part of the API of the vulnerability database and will also provide an example on a potential integration to match the result set against WordPress software.
These examples will be shown using PHP, but can easily be implemented using any programming language. If you have any questions, feel free to send an email to dave.jong@patchstack.com.
Data Structure
Some of the JSON properties as part of the result set can be null so it is important to handle these properties accordingly. Note that we may speak of “product” in the result set, which is essentially the same as a “component”.
This is JSON example for 1 plugin, 1 theme and 1 WordPress core vulnerability.
- id → integer
- Holds the unique numeric identifier of the vulnerability
- product_id → integer
- Holds the unique numeric identifier of the product
- title → string
- The title of the vulnerability, including the product name, version, and vulnerability type
- description → string
- A short description about the vulnerability
- disclosure_date → datetime → YYYY-MM-DD HH:MM:SS
- Date of when the vulnerability was publicly disclosed
- disclosed_at → datetime → ISO 8601 format
- Date of when the vulnerability was publicly disclosed
- created_at → datetime → ISO 8601 format
- Date of when the vulnerability was created and added to the database
- url → string
- The slug of the vulnerability which is used for the URL
- product_slug → string
- The slug of the product
- The slug will be in lowercase, so make sure to convert your own slugs to lowercase before doing any comparison to this property
- product_name → string
- The title / name of the product
- product_name_premium → string → nullable
- The title / name of the product
- This is used in rare scenarios where a developer of a plugin has 2 versions of their plugin but with the same slug but different product names.
- product_type → string
- The type of the product. Can be Plugin, Theme or WordPress
- vuln_type → string
- The vulnerability type, some examples are SQL Injection and Cross Site Scripting
- cvss_score → decimal → nullable
- The CVSS score of the vulnerability, between 1 and 10. Can be null, the older vulnerabilities in the database have not been classified yet.
- cve → array of strings → can be an empty array
- Contains an array of CVE ID’s bound to the vulnerability. One vulnerability could have multiple CVE ID’s. There are also vulnerabilities without CVE ID’s.
- affected_in → string
- The versions which are affected by this vulnerability.
- Formats:
- <= x.x.x (affecting versions up to and including)
- < x.x.x (affecting versions up to)
- x.x.x-x.x.x (affecting a specific range of versions, inclusive)
- x.x.x,x.x.x (affecting specific versions)
- x.x.x (affecting one version)
- WordPress does not force plugin developers to stick to a certain versioning format. There are versions out there in an unusual format which is out of our control. Some plugins use a version in the form of a date such as 20220202, some use letters such as 2.0.2a, some just keep adding a number to the version e.g. 4.0000002. However, for the most part it’s in the usual format of x.x.x or x.x or x.x.xx
- fixed_in → string → can be empty
- The oldest version which has the vulnerability fixed
- This can be empty, which implies that we have not recorded a fixed version for this vulnerability yet
- patched_in_ranges → array of strings → can be an empty array
- In case the WordPress core, plugin or theme have patched sub-versions, this will hold an array of versions in the format of:
- from_version → string
- Starting version, inclusive
- to_version → string
- Ending version, inclusive
- fixed_in → string
- The version which has the patch applied
- from_version → string
- You see this often in WordPress core vulnerabilities as they still support older versions such as 5.1, 5.2, 5.3, etc. Bigger plugins such as WooCommerce and Ninja Forms also do this.
- In case the WordPress core, plugin or theme have patched sub-versions, this will hold an array of versions in the format of:
- direct_url → string
- The direct URL of the vulnerability hosted at the Patchstack database frontend.
- is_exploited → boolean
- Whether or not the vulnerability is known to be exploited by Patchstack
- patch_priority → integer → nullable
- The patch priority value of the vulnerability which implies how soon the developer needs to patch the vulnerability and how soon the customers need to be protected.
- NULL = unknown
- 1 = Low → patch within 30 days
- 2 = Medium → patch within 7 days
- 3 or higher = High → patch immediately
- The patch priority value of the vulnerability which implies how soon the developer needs to patch the vulnerability and how soon the customers need to be protected.
Implementation
Since some of these properties must be kept in mind while determining if a component is vulnerable or not, we have an example PHP script below which will explain the flow. In particular, the following properties must be used: product_slug, product_name_premium, affected_in, patched_in_ranges.
Note that it is an example implementation and should not be copied 1:1 for internal use, you’ll likely want to call the /all API endpoint using a different HTTP library and store the JSON response somewhere else (such as a memory based cache). The example will utilize Laravel’s collect function and Guzzle. The composer.json file which was used for this example is also included below.
Running this script with the proper PSKey injected on line 147 should result in the following response: