Scanning Windows applications using CPE Helper
The Vulnerability Detector relies on the National Vulnerability Database to report vulnerabilities that affect the applications installed on Windows endpoints. The Vulnerability Detector uses an auxiliary dictionary to translate the gathered application names into the NVD format called CPE (Common Platform Enumeration).
Users must add the applications installed on Windows endpoints to this dictionary to enable the Vulnerability Detector module to scan the applications.
CPE Helper Schema
The CPE helper dictionary is located at /var/ossec/queue/vulnerabilities/dictionaries/cpe_helper.json
and has the following basic fields:
version: The version of the CPE helper.
version_format: The version of the CPE helper format. If it differs from the CPE helper version, you must upgrade the Wazuh central components to the latest version to process the dictionary.
update_date: The date the dictionary was updated.
dictionary: Dictionary containing the translation entries.
license: License of the dictionary.
You can see a sample of the dictionary below:
{
"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 to describe the application that the user wants to add:
target: Operating system of the application you want to add. Currently, Wazuh only uses the CPE helper dictionary for applications installed on Windows endpoints.
source: Parameters of the application you want to translate. The allowed sections are the following:
vendor: Array of one or more vendor fields that match the dictionary entry. You can use a regular expression. For example, ^Oracle.
product: Array of one or more product fields that match the dictionary entry. You can use a regular expression. For example, ^Oracle.*VirtualBox [0-9].
version (optional): Array of one or more version fields that match the dictionary entry. You can also define a pattern to match the software version using regular expressions. For example ^Microsoft Office.*([0-9]{4}).
target_hw (optional): This field defines the target hardware of the application. It can also be a regular expression. For example, ^Python [0-9]+.*[0-9].*[0-9] (([6432]{2}-bit))**.
translation: Section to specify the CPE translation. The allowed sections are the following:
vendor: Array of one or more vendor fields that match the CPE translation of the dictionary entry.
product: Array of one or more product fields that match the CPE translation of the application you want to add to the dictionary.
version (optional): Array of one or more version fields that match the CPE translation of the application you want to add to the dictionary.
msu_name (optional): This field is for Microsoft products. You can find the name of the application in the Microsoft Security Guide. You can also use variables to complete this string. For example, Microsoft Office $(VERSION).
action: Array of actions to apply on the entry.
You can find a template for a dictionary entry below:
{
"target": "target OS",
"source": {
"vendor": [
"..."
],
"product": [
"..."
],
"version": [
"..."
],
"target_hw": [
"..."
]
},
"translation": {
"vendor": [
"..."
],
"product": [
"..."
],
"version": [
"..."
],
"sw_edition": [
"..."
],
"msu_name": [
"..."
]
},
"action": [
"..."
]
}
Translation types
The Vulnerability Detector module converts the dictionary entries to the CPE format based on the flags used in the action section. The possible flags 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 for a dictionary entry. It uses a vendor that is similar to the one matching the pattern. |
replace_product_if_matches |
Used when there is more than one product for a dictionary entry. It uses a product that is similar to the one that matches the pattern. |
set_version_if_matches |
Sets the application version to the version extracted from the version field pattern if the pattern matches successfully. |
replace_sw_edition_if_product_matches |
Used with the sections |
check_hotfix |
Used to indicate those software products where the vulnerability range is unknown, and there is a 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 |
set_version_if_product_matches |
Sets the software version if the Vulnerability Detector can find the product name using the regular expression expressed in the version section. |
set_targethw_if_product_matches |
Sets the software architecture if the Vulnerability Detector can find the product name using the regular expression expressed in the |
set_version_only_if_product_matches |
Sets the software version if the Vulnerability Detector can find the product name using the regular expression expressed in the version section. The Vulnerability Detector will not generate the CPE if there is no match. |
set_targethw_only_if_product_matches |
Sets the software architecture if the Vulnerability Detector can find the product name using the regular expression expressed in the target_hw section. The Vulnerability Detector will not generate the CPE if there is no match. |
How to translate a Windows program to CPE format
To include a Windows program in the CPE helper dictionary, it's necessary to know the vendor, product name, and program version present in the Wazuh software inventory. After this, it's necessary to look for the CPE that is suitable for the program to configure the dictionary entry with the appropriate values.
Get the agent programs.
You can get a list of the programs installed on an agent by 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, you configure the CPE for Wireshark. The output below is the data returned by Syscollector for an endpoint with Wireshark:
{ "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 translation of the program, you can use NVD's CPEs search engine.
Select the least generic CPE. In this case, take the first one.
You're only interested in the vendor and product fields of this CPE since the version that comes from the agent inventory is valid. You 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 need to use the
replace_vendor
andreplace_product
actions. Take into account that the source patterns are regular expressions. The table below summarizes the goals you need to achieve using the CPE helper: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
Therefore, we can add the following entry to the CPE helper dictionary at
/var/ossec/queue/vulnerabilities/dictionaries/cpe_helper.json
:{ "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
An application can have several CPEs associated depending on its vendor, version, or the syntax of its name. This section will explain how to create an entry to include all possible translations of a program collected by Syscollector.
In this guide, we generate dictionary entries for Skype and Skype for Business as an example.
Get the agent programs.
You can get a list of the programs installed on the agent by 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 you have Skype and Skype for Business installed, you get the result shown below:
{ "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 translation of the program, use NVD's CPEs search engine.
There are various combinations of vendor and product fields for the products in the search results. This use case doesn’t include Skype for Business Server in this use case, but users can translate the program using the same techniques described in this section.
Like the example in the previous section, you're interested in the vendor and product fields of this CPE. You can find out by checking if it follows the same format as the CPEs we found (8.42 ~= 8.35).
Therefore, you need to add an entry to replace the vendor and product of the two applications, so use the actions
replace_vendor_if_match
andreplace_product_if_match
. The table below summarizes the goals you need to achieve using the CPE helper: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
Therefore, you can add the following dictionary entry to the CPE helper dictionary at
/var/ossec/queue/vulnerabilities/dictionaries/cpe_helper.json
:{ "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 both
^Skype for Business
and^Skype
patterns. However, the Vulnerability Detector uses the first because it sorts the entries by priority from top to bottom.
Products whose version does not change between updates
For some software products, generally from Microsoft, users cannot confirm vulnerabilities by consulting the National Vulnerability Database. These products do not change their visible version between updates, so the Vulnerability Detector cannot tell when the products are no longer vulnerable.
For example, if you consult the CVE-2019-0671 vulnerability for Microsoft Office 2016 in the National Vulnerability Database, you find the following:
As seen in the output, the CPEs only specify that the vulnerability affects the 2016 version. This information is not enough because your program may not be affected by the vulnerability if you have applied the patch that fixes it.
In this case, you can check the Microsoft Security Update Guide to verify if Microsoft Office 2016 fixes the vulnerability in any update.
The Vulnerability Detector can automate this search using the CPE Helper and the check_hotfix
action. To illustrate the process, follow the same procedure as in the previous use cases.
Get the agent programs.
You can get a list of the programs installed on the agent by 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 you have Microsoft Office 2016 and Office 16 Click-to-Run installed, you get results similar to the following:
{ "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.
Use the information obtained earlier on the CPEs affected by CVE-2019-0671 to extract the CPEs from the program. From that source, you can see the CPEs that the vulnerability directly affects. These are:
cpe:2.3:a:microsoft:office:2016:*:*:*:*:*:*:*
cpe:2.3:a:microsoft:office:2016:*:*:*:click-to-run:*:*:*
The two target programs only differ in the field sw_edition (click-to-run). If the sw_edition field was present in this case, you might use the
replace_sw_edition_if_product_match
option to add the sw_edition field. However, the vulnerabilities in Microsoft Office do not include this parameter.The package version that Syscollector has (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, use the
set_version_only_if_product_matches
option, which does not generate the CPE if the Vulnerability Detector cannot decode the version.Finally, 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. To evaluate the hotfixes installed on a Windows computer, 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, which also includes 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" } }