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 sw_edition and version, it uses the sw_edition field parallel to the matching version.

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 msu_name and version, it indicates the name taken by the program in the Microsoft Security Guide. It needs to be used with check_hotfix and Microsoft products.

replace_msu_name

Used with the sections msu_name, it indicates the name taken by the program in the Microsoft Security Guide. It needs to be used with check_hotfix and Microsoft products.

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.

  1. 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,
}
  1. 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 and replace_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.

  1. 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,
}
  1. 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 and replace_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.

  1. 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,
}
  1. 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 the msu_name section. Do not forget that to perform an evaluation through the hotfixes installed on a Windows computer we must also include the action check_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"
    }
}