CPE Helper
Since Wazuh 3.11.0, Vulnerability Detector relies on the National Vulnerability Database to analyze vulnerabilities on Windows agents. In a future release, this integration is attempted to be extended to the rest of operating systems.
The package inventory of agents is stored in Wazuh DB and used by Vulnerability Detector directly. This inventory is contrasted against vulnerability feeds, generating alerts if vulnerabilities are detected. However, program names submitted by Syscollector from Windows agents are not valid to look for vulnerabilities in the feed of the National Vulnerability Database.
For this reason, an auxiliary dictionary has been created, that could convert the software inventory of Windows agents to the standard format used by this provider: CPE (Common Platform Enumeration).
CPE Helper Schema
The CPE helper has the following fields:
version: Version of the CPE helper.
version_format: Version of the CPE helper format. If it changes the major, you will need to upgrade Wazuh to the latest version to process it.
update_date: Date the dictionary was updated for last time.
dictionary: Dictionary containing the translation entries.
license: License of the dictionary.
{ "version": "1.0", "version_format": "1.0", "update_date": "2019-05-14T00:00Z", "dictionary": [ "..." ], "license": { "title": "Dictionary of CPEs to analyze system vulnerabilities.", "copyright": "Copyright (C) 2015-2019, Wazuh Inc.", "date": "March 6, 2019.", "type" : "GPLv2" } }
Dictionary schema
Each dictionary entry has the following fields:
target: Operating system affected by this entry. At the moment, only Windows is available.
source: Parameters of the program to be translated. Allowed sections:
vendor: Array of one or more vendor fields that can match this entry. You can use a regular expression. Example: ^Oracle.
product: Array of one or more product fields that can match this entry. You can use a regular expression. Example ^Oracle.*VirtualBox [0-9].
version (optional): Array of one or more version fields that can match this entry. You can also define a pattern to extract the version of the software using regular expressions. Example ^Microsoft Office.*([0-9]{4}).
target_hw (optional): Defines a pattern to extract the
target_hw
field. Example ^Python [0-9]+\.*[0-9]\.*[0-9]* \(([6432]{2}-bit)\)*.
translation: Section to specify the CPE translation. Allowed sections:
vendor: Array of one or more vendor fields that can form the CPE of the input program.
product: Array of one or more product fields that can form the CPE of the input program.
version (optional): Array of one or more version fields that can form the CPE of the input program.
msu_name (optional): For Microsoft products, the name of the programs in the Microsoft Security Guide. You can also use variables to complete this string. Example: Microsoft Office $(VERSION).
action: Array of actions to apply on the entry.
{ "target": "target OS", "source": { "vendor": [ "..." ], "product": [ "..." ], "version": [ "..." ], "target_hw": [ "..." ] }, "translation": { "vendor": [ "..." ], "product": [ "..." ], "version": [ "..." ], "sw_edition": [ "..." ], "msu_name": [ "..." ] }, "action": [ "..." ] }
Translation types
The conversion of the program to CPE format will be done according to the flags used in the action section. These are:
Option |
Description |
---|---|
ignore |
Ignore the dictionary entry. |
replace_vendor |
Convert the vendor to the indicated one if the pattern matches. |
replace_product |
Convert the product to the indicated one if the pattern matches. |
replace_vendor_if_matches |
Used when there is more than one vendor at the same dictionary entry, it uses the vendor parallel to the one that matches the pattern. |
replace_product_if_matches |
Used when there is more than one product at the same dictionary entry, it uses the product parallel to the one that matches the pattern. |
set_version_if_matches |
Sets the version of the program that was extracted from the version field pattern if it was successful. |
replace_sw_edition_if_product_matches |
Used with the sections |
check_hotfix |
Used to indicate those software products where the vulnerability range is not known and need to validate a hotfix. These are usually Microsoft products. |
replace_msu_name_if_version_matches |
Used with the sections |
replace_msu_name |
Used with the sections |
set_version_if_product_matches |
Sets the software version if it can be found in the product name through a regular expression expressed in the version section. |
set_targethw_if_product_matches |
Sets the software architecture if it can be found in the product name through a regular expression expressed in the target_hw section. |
set_version_only_if_product_matches |
Sets the software version if it can be found in the product name through a regular expression expressed in the version section. If it does not match, the CPE will not be generated. |
set_targethw_only_if_product_matches |
Sets the software architecture if it can be found in the product name through a regular expression expressed in the target_hw section. If it does not match, the CPE will not be generated. |
How to translate a Windows program to CPE format
To include a Windows program in the CPE Helper dictionary, in order to be able to look for vulnerabilities for it, it is necessary to know the vendor, name of product and version that the package inventory provides. After this, it is necessary to look for the CPE that better adapts to this program to end up configuring the dictionary entry with the opportune actions.
Get the agent's programs.
The programs installed in the agent can be consulted using the Wazuh API endpoint GET /syscollector/{agent_id}/packages:
curl -k -X GET "https://localhost:55000/syscollector/001/packages?pretty=true&offset=10&sort=-name" -H "Authorization: Bearer $TOKEN"
In this use case, we are going to translate CPE of the next node:
{ "data": { "affected_items": [ { "scan": {"id": 27266015, "time": "2019/05/21 16:25:21"}, "version": "2.4.5", "name": "Wireshark 2.4.5 64-bit", "format": "win", "vendor": "The Wireshark developer community, https://www.wireshark.org", "location": "C:\\Program Files\\Wireshark", "architecture": "i686", "agent_id": "001", } ], "total_affected_items": 1, "total_failed_items": 0, "failed_items": [], }, "message": "All specified syscollector information was returned", "error": 0, }
Find the CPE program.
To find the CPE to which the program is translated, we can use the NVD's CPEs search engine.
We select the least generic CPE. In this case, we will take the first one.
We are interested only in the fields vendor and product of this CPE, since the version that comes from the agent inventory is valid. We can find out by checking if it follows the same format as the CPEs we found (2.4.5 ~= 0.99.2).
The entry only has to replace a vendor and a product, so we only need to use the
replace_vendor
andreplace_product
actions. Take into account that the source patterns are regular expressions. The rule we are going to use is:
CPE part
Syscollector name
Source pattern
Translation
Action
Vendor
The Wireshark developer community, https://www.wireshark.org
www.wireshark.org
wireshark
replace_vendor
Product name
Wireshark 2.4.5 64-bit
Wireshark
wireshark
replace_product
Finally, the resulting dictionary entry:
{ "target": "windows", "source": { "vendor": [ "www\\.wireshark\\.org" ], "product": [ "Wireshark" ], "version": [] }, "translation": { "vendor": [ "wireshark" ], "product": [ "wireshark" ], "version": [] }, "action": [ "replace_vendor", "replace_product" ] }
Combine several programs in a dictionary entry
A software product can have several CPEs associated depending on its vendor, version, or the syntax with which its name was defined. This section will explain how to create an entry to include all possible translations of a program collected by Syscollector.
For the guide, the generation of the dictionary entry for Skype and Skype for Business will be used as use case.
Get the agent's programs.
The programs installed in the agent can be consulted using the Wazuh API endpoint GET /syscollector/{agent_id}/packages:
curl -k -X GET "https://localhost:55000/syscollector/001/packages?pretty=true&offset=10&sort=-name" -H "Authorization: Bearer $TOKEN"
If we have Skype and Skype for Business installed, we will get 2 nodes as follows:
{ "data": { "affected_items": [ { "scan": {"id": 908227078, "time": "2019/05/22 10:05:24"}, "format": "win", "version": "16.0.11425.20244", "location": "C:\\Program Files (x86)\\Microsoft Office", "name": "Skype for Business Basic 2016 - en-us", "vendor": "Microsoft Corporation", "architecture": "x86_64", "agent_id": "001", }, { "scan": {"id": 908227078, "time": "2019/05/22 10:05:24"}, "format": "win", "version": "8.42", "install_time": "20190329", "location": "C:\\Program Files (x86)\\Microsoft\\Skype for Desktop\\", "name": "Skype version 8.42", "vendor": "Skype Technologies S.A.", "architecture": "i686", "agent_id": "001", }, ], "total_affected_items": 2, "total_failed_items": 0, "failed_items": [], }, "message": "All specified syscollector information was returned", "error": 0, }
Find the CPE program.
To find the CPE to which the program is translated, we can use the NVD's CPEs search engine.
We can observe various combinations of vendor and product fields for the products we are looking for. Skype for Business Server is not included in this use case, but it could be included in the same way.
Again, we are interested only in the fields vendor and product of this CPE. We can find out by checking if it follows the same format as the CPEs we found (8.42 ~= 8.35).
The entry will have to replace the vendor and the product between 2 combinations each, so we will use the actions
replace_vendor_if_match
andreplace_product_if_match
. The rule we are going to use is:
Generated input
Syscollector name
Source pattern
Translation
Action
Vendor
Microsoft Corporation
^Microsoft
microsoft
replace_vendor_if_matches
Skype Technologies S.A.
^Skype
skype
Product name
Skype for Business Basic 2016 - en-us
^Microsoft
skype_for_business
replace_product_if_matches
Skype version 8.42
^Skype
skype
Finally, the resulting dictionary entry:
{ "target": "windows", "source": { "vendor": [ "^Skype", "^Microsoft" ], "product": [ "^Skype for Business", "^Skype" ], "version": [] }, "translation": { "vendor": [ "skype", "microsoft" ], "product": [ "skype_for_business", "skype" ], "version": [] }, "action": [ "replace_vendor_if_matches", "replace_product_if_matches" ] }
Note
The product Skype for Business Basic 2016 - en-us matches the ^Skype for Business
and ^Skype
patterns,
but will use the first one because they are sorted by priority.
Products whose version does not change between updates
There are some software products, generally from Microsoft, whose vulnerabilities cannot be confirmed by consulting the National Vulnerability Database. These products do not change their visible version between updates, so we cannot know when they are no longer vulnerable.
For example, if we consult the CVE-2019-0671 vulnerability for Microsoft Office 2016 in the National Vulnerability Database, we will find the following.
As we can see, the CPEs only specify that the vulnerability affects the 2016 version, which is not enough because our program may not be affected by the vulnerability if the patch that fixes it has been applied.
In this case, we should check the Microsoft Security Update Guide to verify if Microsoft Office 2016 fix the vulnerability in any update.
Vulnerability Detector can automate this search using the CPE Helper and the check_hotfix
action.
To illustrate the process, we will follow the same procedure as in the previous use cases.
Get the agent's programs.
The programs installed in the agent can be consulted using the Wazuh API endpoint GET /syscollector/{agent_id}/packages:
curl -k -X GET "https://localhost:55000/syscollector/001/packages?pretty=true&offset=10&sort=-name" -H "Authorization: Bearer $TOKEN"
If we have Microsoft Office 2016 and Office 16 Click-to-Run installed, we will get 2 nodes as follows:
{ "data": { "affected_items": [ { "scan": {"id": 214307089, "time": "2019/05/22 11:53:07"}, "vendor": "Microsoft Corporation", "name": "Office 16 Click-to-Run Extensibility Component 64-bit Registration", "install_time": "20190429", "architecture": "x86_64", "format": "win", "version": "16.0.11425.20244", "agent_id": "001", }, { "scan": {"id": 214307089, "time": "2019/05/22 11:53:07"}, "version": "16.0.11425.20244", "location": "C:\\Program Files (x86)\\Microsoft Office", "vendor": "Microsoft Corporation", "architecture": "x86_64", "format": "win", "name": "Microsoft Office Professional Plus 2016 - en-us", "agent_id": "001", }, ], "total_affected_items": 2, "total_failed_items": 0, "failed_items": [], }, "message": "All specified syscollector information was returned", "error": 0, }
Find the CPE program.
To extract the CPEs from the program, we can use the information previously consulted on the CPEs affected by CVE-2019-0671. From that source we can see exactly which CPEs are checked to confirm vulnerability. These are:
cpe:2.3:a:microsoft:office:2016:*:*:*:*:*:*:*
cpe:2.3:a:microsoft:office:2016:*:*:*:click-to-run:*:*:*
We can see that the two target programs only differ in the field sw_edition (click-to-run). We could used the
replace_sw_edition_if_product_match
option to add the sw_edition field if it appears, but the vulnerabilities on Microsoft Office do not include this parameter.We have to take into account that the package version that Syscollector extracted (16.0.11425.20244) is not valid for this use case, so we need to extract the version from the product name to create the CPE. To do this, we must use the
set_version_only_if_product_matches
option, which aborts the generation of the CPE if the version cannot be decoded.Finally, we will indicate the name of these programs in the Microsoft Security Update Guide using their version variable as a reference. To do this, use the
replace_msu_name
action and themsu_name
section. Do not forget that to perform an evaluation through the hotfixes installed on a Windows computer we must also include the actioncheck_hotfixes
.
Generated input
Syscollector name
Source pattern
Translation
Action
Vendor
Microsoft Corporation
^Microsoft Corporation
microsoft
replace_vendor
Product name
Microsoft Office Professional Plus 2016 - en-us
^Microsoft Office
office
replace_product
Office 16 Click-to-Run Extensibility Component 64-bit Registration
Office % Click-to-Run Extensibility Component%
Version
16.0.11425.20244
^Microsoft Office.*([0-9]{4})
2016
set_version_only_if_product_matches
MSU name
Microsoft Office $(VERSION)
Microsoft Office 2016
replace_msu_name
The resulting dictionary entry, including more versions of Microsoft Office:
{ "target": "windows", "source": { "vendor": [ "^Microsoft Corporation" ], "product": [ "^Microsoft Office" ], "version": [ "^Microsoft Office.*([0-9]{4})" ] }, "translation": { "vendor": [ "microsoft" ], "product": [ "office" ], "version": [], "msu_name": [ "Microsoft Office $(VERSION)" ] }, "action": [ "replace_vendor", "replace_product", "set_version_only_if_product_matches", "replace_msu_name", "check_hotfix" ] }Alert example using this dictionary entry:
{ "vulnerability":{ "cve":"CVE-2019-0671", "title":"A remote code execution vulnerability exists when the Microsoft Office Access Connectivity Engine improperly handles objects in memory, aka 'Microsoft Office Access Connectivity Engine Remote Code Execution Vulnerability'. This CVE ID is unique from CVE-2019-0672, CVE-2019-0673, CVE-2019-0674, CVE-2019-0675.", "severity":"High", "published":"2019-03-05T23:29Z", "updated":"2019-03-06T15:53Z", "state":"Fixed", "cvss":{ "cvss2":{ "vector":{ "attack_vector":"network", "access_complexity":"medium ", "authentication":"none", "integrity_impact":"complete", "availability":"complete" }, "base_score":"9.300000" }, "cvss3":{ "vector":{ "attack_vector":"local", "access_complexity":"low", "confidentiality_impact":"low", "availability":"high", "privileges_required":"none", "user_interaction":"required ", "scope":"unchanged" }, "base_score":"7.800000" } }, "package":{ "name":"Microsoft Office Professional Plus 2016 - en-us", "version":"16.0.11425.20244", "generated_cpe":"a:microsoft:office:2016::::::x86_64:", "architecture":"x86_64" }, "condition":"4018294 patch is not installed.", "cwe_reference":"CWE-119", "reference":"http://www.securityfocus.com/bid/106928" } }