ContextQMD
Back to Wazuh

Test tools

docs/ref/modules/vulnerability-scanner/test-tools.md

4.14.522.1 KB
Original Source

Test tools

Below is a quick overview of the usage of the vulnerability scanner command line tools that serve the purpose of debugging and testing.

These tools ease the task of mocking and replicating a real environment where we can validate that new changes do not affect in an undesired way the current capabilities of the module.

Compilation

Command line test tools are intended for development purposes and they are not delivered in the Wazuh manager packages. To use them, it is required to compile the project by sources.

console
cd wazuh/src
make deps 
make -j$(nproc) TARGET=server

Vulnerability Scanner tool

Location path

console
src/build/wazuh_modules/vulnerability_scanner/testtool/scanner/vd_scanner_testtool

Note: execute the cli with --help to display the available options.

Database creation

Command

console
src/build/wazuh_modules/vulnerability_scanner/testtool/scanner/vd_scanner_testtool -c config.json -d

Configuration file

json
{
  "vulnerability-detection": {
    "enabled": "yes",
    "index-status": "no",
    "cti-url": "https://cti.wazuh.com/api/v1/catalog/contexts/vd_1.0.0/consumers/vd_4.8.0"
  },
  "clusterName": "cluster01",
  "clusterEnabled": false
}
  • The -d flag performs a snapshot download from CTI and processes the content to create a local CVE database.
  • In a real Wazuh Manager installation, clusterName is the hostname for a single node deployment, or the cluster name for a cluster setup.
  • The outcome of this command is a RocksDB CVE database queue in the current directory.
  • The process will take some minutes until the snapshot file is processed.

Note: It's possible to follow the process with the logs printed by the tool. Optionally, with the -l argument, the logs can be dumped to a file.

console
...
wazuh-modulesd:vulnerability-scanner:databaseFeedManager.hpp:254 processMessage : Processing line: 180001
wazuh-modulesd:vulnerability-scanner:databaseFeedManager.hpp:254 processMessage : Processing line: 181001
wazuh-modulesd:vulnerability-scanner:databaseFeedManager.hpp:254 processMessage : Processing line: 182001
wazuh-modulesd:vulnerability-scanner:databaseFeedManager.hpp:254 processMessage : Processing line: 183001
wazuh-modulesd:vulnerability-scanner:databaseFeedManager.hpp:254 processMessage : Processing line: 184001
wazuh-modulesd:vulnerability-scanner:databaseFeedManager.hpp:254 processMessage : Processing line: 185001
wazuh-modulesd:vulnerability-scanner:databaseFeedManager.hpp:254 processMessage : Processing line: 186001
wazuh-modulesd:vulnerability-scanner:databaseFeedManager.hpp:254 processMessage : Processing line: 187001
...
wazuh-modulesd:vulnerability-scanner:databaseFeedManager.hpp:254 processMessage : Processing line: 292001
wazuh-modulesd:vulnerability-scanner:databaseFeedManager.hpp:369 operator() : Feed update process completed.
Only download content flag is set. Stopping the scanner...

Note: Starting the vulnerability scanner tool without the -d option will update the CVE database with new data not present in the snapshot.

console
wazuh-modulesd:vulnerability-scanner:databaseFeedManager.hpp:355 operator() : Initiating update feed process.
wazuh-modulesd:vulnerability-scanner:databaseFeedManager.hpp:188 processMessage : Processing file: queue/vd_updater/tmp/contents/1906695-api_file.json
wazuh-modulesd:vulnerability-scanner:databaseFeedManager.hpp:188 processMessage : Processing file: queue/vd_updater/tmp/contents/1907695-api_file.json
...
wazuh-modulesd:vulnerability-scanner:databaseFeedManager.hpp:369 operator() : Feed update process completed.

Detection

For details about event format please refer to Events

Command

console
src/build/wazuh_modules/vulnerability_scanner/testtool/scanner/vd_scanner_testtool -c config.json -u -i os.json,package.json
  • The command will detect vulnerabilities and fill the indexer databases.

Note: It is possible to connect an instance of the Wazuh-Indexer and index the result of the vulnerability scan by adding the Indexer Connector configuration (more details Configuration).

console
src/build/wazuh_modules/vulnerability_scanner/testtool/scanner/vd_scanner_testtool -c config.json -t index-template.json -u -i os_event.json,package_event.json

Expanded configuration options for indexing

json
{
  "vulnerability-detection": {
    "enabled": "yes",
    "index-status": "yes",
    "cti-url": "https://cti.wazuh.com/api/v1/catalog/contexts/vd_1.0.0/consumers/vd_4.8.0"
  },
  "indexer": {
    "enabled": "yes",
    "hosts": [
      "https://0.0.0.0:9200"
    ],
    "username": "admin",
    "password": "admin",
    "ssl": {
      "certificate_authorities": [
        "/PATH/root-ca.pem"
      ],
      "certificate": "/PATH/node-1.pem",
      "key": "/PATH/node-1-key.pem"
    },
    "update_mappings_path": ""
  },
  "clusterName": "cluster01",
  "clusterEnabled": false
}

Note: It is important to modify accordingly the following fields:

  • hosts
  • certificate
  • key
  • certificate_authorities
  • username
  • password

Also, a template is required to create the mapping in the Wazuh Indexer.

<details><summary>Expand</summary>
json
{
  "index_patterns": [
    "wazuh-states-vulnerabilities-*"
  ],
  "priority": 1,
  "template": {
    "settings": {
      "index": {
        "codec": "best_compression",
        "mapping": {
          "total_fields": {
            "limit": 1000
          }
        },
        "number_of_replicas": "0",
        "number_of_shards": "1",
        "query.default_field": [
          "agent.id",
          "host.os.family",
          "host.os.full",
          "host.os.version",
          "package.name",
          "package.version",
          "vulnerability.id",
          "vulnerability.description",
          "vulnerability.severity",
          "wazuh.cluster.name"
        ],
        "refresh_interval": "2s"
      }
    },
    "mappings": {
      "date_detection": false,
      "dynamic": "strict",
      "properties": {
        "agent": {
          "properties": {
            "build": {
              "properties": {
                "original": {
                  "ignore_above": 1024,
                  "type": "keyword"
                }
              }
            },
            "ephemeral_id": {
              "ignore_above": 1024,
              "type": "keyword"
            },
            "id": {
              "ignore_above": 1024,
              "type": "keyword"
            },
            "name": {
              "ignore_above": 1024,
              "type": "keyword"
            },
            "type": {
              "ignore_above": 1024,
              "type": "keyword"
            },
            "version": {
              "ignore_above": 1024,
              "type": "keyword"
            }
          }
        },
        "host": {
          "properties": {
            "os": {
              "properties": {
                "full": {
                  "ignore_above": 1024,
                  "type": "keyword"
                },
                "kernel": {
                  "ignore_above": 1024,
                  "type": "keyword"
                },
                "name": {
                  "ignore_above": 1024,
                  "type": "keyword"
                },
                "platform": {
                  "ignore_above": 1024,
                  "type": "keyword"
                },
                "type": {
                  "ignore_above": 1024,
                  "type": "keyword"
                },
                "version": {
                  "ignore_above": 1024,
                  "type": "keyword"
                }
              }
            }
          }
        },
        "package": {
          "properties": {
            "architecture": {
              "ignore_above": 1024,
              "type": "keyword"
            },
            "build_version": {
              "ignore_above": 1024,
              "type": "keyword"
            },
            "checksum": {
              "ignore_above": 1024,
              "type": "keyword"
            },
            "description": {
              "ignore_above": 1024,
              "type": "keyword"
            },
            "install_scope": {
              "ignore_above": 1024,
              "type": "keyword"
            },
            "installed": {
              "type": "date"
            },
            "license": {
              "ignore_above": 1024,
              "type": "keyword"
            },
            "name": {
              "ignore_above": 1024,
              "type": "keyword"
            },
            "path": {
              "ignore_above": 1024,
              "type": "keyword"
            },
            "reference": {
              "ignore_above": 1024,
              "type": "keyword"
            },
            "size": {
              "type": "long"
            },
            "type": {
              "ignore_above": 1024,
              "type": "keyword"
            },
            "version": {
              "ignore_above": 1024,
              "type": "keyword"
            }
          }
        },
        "vulnerability": {
          "properties": {
            "category": {
              "ignore_above": 1024,
              "type": "keyword"
            },
            "classification": {
              "ignore_above": 1024,
              "type": "keyword"
            },
            "description": {
              "ignore_above": 1024,
              "type": "keyword"
            },
            "detected_at": {
              "type": "date"
            },
            "enumeration": {
              "ignore_above": 1024,
              "type": "keyword"
            },
            "id": {
              "ignore_above": 1024,
              "type": "keyword"
            },
            "published_at": {
              "type": "date"
            },
            "reference": {
              "ignore_above": 1024,
              "type": "keyword"
            },
            "report_id": {
              "ignore_above": 1024,
              "type": "keyword"
            },
            "scanner": {
              "properties": {
                "vendor": {
                  "ignore_above": 1024,
                  "type": "keyword"
                },
                "source": {
                  "ignore_above": 1024,
                  "type": "keyword"
                }
              }
            },
            "score": {
              "properties": {
                "base": {
                  "type": "float"
                },
                "environmental": {
                  "type": "float"
                },
                "temporal": {
                  "type": "float"
                },
                "version": {
                  "ignore_above": 1024,
                  "type": "keyword"
                }
              }
            },
            "severity": {
              "ignore_above": 1024,
              "type": "keyword"
            },
            "under_evaluation": {
              "type": "boolean"
            }
          }
        },
        "wazuh": {
          "properties": {
            "cluster": {
              "properties": {
                "name": {
                  "ignore_above": 1024,
                  "type": "keyword"
                },
                "node": {
                  "ignore_above": 1024,
                  "type": "keyword"
                }
              }
            },
            "schema": {
              "properties": {
                "version": {
                  "ignore_above": 1024,
                  "type": "keyword"
                }
              }
            }
          }
        }
      }
    }
  }
}
</details>

Additional logs will be printed related to the vulnerabilities indexed.

console
indexer-connector:indexerConnector.cpp:606 operator() : Added document for insertion with id: 001_f21aca719022f009d80bbf9224741d79029b31f2_CVE-2024-28835.
indexer-connector:indexerConnector.cpp:606 operator() : Added document for insertion with id: 001_f21aca719022f009d80bbf9224741d79029b31f2_CVE-2024-28834.
indexer-connector:indexerConnector.cpp:606 operator() : Added document for insertion with id: 001_f21aca719022f009d80bbf9224741d79029b31f2_CVE-2024-12243.
indexer-connector:indexerConnector.cpp:606 operator() : Added document for insertion with id: 001_f21aca719022f009d80bbf9224741d79029b31f2_CVE-2024-28835.
indexer-connector:indexerConnector.cpp:606 operator() : Added document for insertion with id: 001_f21aca719022f009d80bbf9224741d79029b31f2_CVE-2024-28834.
indexer-connector:indexerConnector.cpp:606 operator() : Added document for insertion with id: 001_f21aca719022f009d80bbf9224741d79029b31f2_CVE-2024-12243.
indexer-connector:indexerConnector.cpp:606 operator() : Added document for insertion with id: 001_f21aca719022f009d80bbf9224741d79029b31f2_CVE-2024-28835.
indexer-connector:indexerConnector.cpp:606 operator() : Added document for insertion with id: 001_f21aca719022f009d80bbf9224741d79029b31f2_CVE-2024-28834.
indexer-connector:indexerConnector.cpp:606 operator() : Added document for insertion with id: 001_f21aca719022f009d80bbf9224741d79029b31f2_CVE-2024-12243.

Note: To request the information please refer to the Opensearch API

Note: The -u option disables the Content Updater module, so it won't process any snapshots or offsets, and it will directly process incoming events looking for vulnerabilities.

Note: A package event needs an OS event; if we send a package event without the OS event, the tool may hang even if we later use the right command with the OS event. To overcome this, remove the queue/vd/event or use the -b option explained below.

Mocking Wazuh-DB information

As previously mentioned, the scanner requires OS and hotfixes information for detection. That could be mocked using the options -h for hotfixes and -b for OS.

Example mocked hotfix data

json
{
  "001": [
      { "hotfix":"KB2468871" },
      { "hotfix":"KB2478063" },
      { "hotfix":"KB2533523" },
      { "hotfix":"KB2544514" },
      { "hotfix":"KB2600211" },
      { "hotfix":"KB2600217" },
      { "hotfix":"KB4502496" },
      { "hotfix":"KB4512577" },
      { "hotfix":"KB4512578" },
      { "hotfix":"KB4514366" },
      { "hotfix":"KB4535680" },
      { "hotfix":"KB4535684" },
      { "hotfix":"KB4535685" },
      { "hotfix":"KB4577586" },
      { "hotfix":"KB4580325" },
      { "hotfix":"KB4589208" },
      { "hotfix":"KB4601558" },
      { "hotfix":"KB5003171" },
      { "hotfix":"KB5003243" },
      { "hotfix":"KB5034619" },
      { "hotfix":"KB5034768" },
      { "hotfix":"KB5034863" },
      { "hotfix":"KB5012649"}
  ]
}

Example mocked OS data for Ubuntu

json
{
    "001": {
        "architecture": "x86_64",
        "checksum": "1704514361693635656",
        "hostname": "ubuntu-jammy",
        "os_codename": "jammy",
        "os_major": "22",
        "os_minor": "04",
        "os_name": "Ubuntu",
        "os_patch": "3",
        "os_platform": "ubuntu",
        "os_version": "22.04.3 LTS (Jammy Jellyfish)",
        "reference": "f22553c945b045bfc0d162cb890344d2f4fa8609",
        "release": "5.15.0-91-generic",
        "scan_id": 0,
        "scan_time": "2024/01/06 04:12:44",
        "sysname": "Linux",
        "version": "#101-Ubuntu SMP Tue Nov 14 13:30:08 UTC 2023"
    }
}

Usage

console
src/build/wazuh_modules/vulnerability_scanner/testtool/scanner/vd_scanner_testtool -c config2.json -t index-template.json -u -i package_event.json -b os_wdb.json

Note: More details about required fields Events.

RocksDB tool

Location path

console
src/build/wazuh_modules/vulnerability_scanner/testtool/rocksDBQuery/rocks_db_query_testtool

Note: execute the cli with --help to display the available options.

Inspect databases

Indexer databases

Commands

console
rocksDBQuery/rocks_db_query_testtool -d queue/indexer/db/wazuh-states-vulnerabilities-<hostname>
rocksDBQuery/rocks_db_query_testtool -d queue/indexer/wazuh-states-vulnerabilities-<hostname>

Example output

console
001_f21aca719022f009d80bbf9224741d79029b31f2_CVE-2024-12243 ==> 
{
  "agent": {
    "id": "001",
    "type": "Wazuh",
    "version": "v4.10.1"
  },
  "host": {
    "os": {
      "full": "CentOS Stream 9",
      "kernel": "5.14.0-391.el9.x86_64",
      "name": "CentOS Stream",
      "platform": "centos",
      "type": "centos",
      "version": "9"
    }
  },
  "package": {
    "architecture": "x86_64",
    "name": "gnutls",
    "size": 0,
    "type": "rpm",
    "version": "3.8.2-1.el9"
  },
  "vulnerability": {
    "category": "Packages",
    "classification": "-",
    "description": "DOCUMENTATION: A flaw was found in GnuTLS, which relies on libtasn1 for ASN.1 data processing. Due to an inefficient algorithm in libtasn1, decoding certain DER-encoded certificate data can take excessive time, leading to increased resource consumption. This flaw allows a remote attacker to send a specially crafted certificate, causing GnuTLS to become unresponsive or slow, resulting in a denial-of-service condition.",
    "detected_at": "2025-04-25T18:49:27.929Z",
    "enumeration": "CVE",
    "id": "CVE-2024-12243",
    "published_at": "2025-02-10T16:15:37Z",
    "reference": "https://access.redhat.com/security/cve/CVE-2024-12243",
    "scanner": {
      "source": "Red Hat CVE Database",
      "vendor": "Wazuh"
    },
    "score": {
      "base": 5.3,
      "version": "3.1"
    },
    "severity": "Medium",
    "under_evaluation": false
  },
  "wazuh": {
    "cluster": {
      "name": "cluster01"
    },
    "schema": {
      "version": "1.0.0"
    }
  }
}

Inventory database

Command

console
rocksDBQuery/rocks_db_query_testtool -d queue/inventory

Example output

console
001_f21aca719022f009d80bbf9224741d79029b31f2 ==> CVE-2024-28835,CVE-2024-28834,CVE-2024-12243

Remove indexed vulnerability and clean databases

It is possible to clean the indexed vulnerabilities and related data using the scanner tool with proper Wazuh-DB events.

Usage

console
src/build/wazuh_modules/vulnerability_scanner/testtool/scanner/vd_scanner_testtool -c config2.json -t index-template.json -u -i deleteAction.json

Delete single agent

json
{
  "agent_info": {
    "agent_id": "001"
  },
  "action": "deleteAgent"
}

Delete all agents

json
{
  "action": "cleanup"
}

Delete package

json
{
  "agent_info": {
    "agent_id": "001"
  },
  "action": "deletePackage",
  "data": {
    "name": "name",
    "version": "version",
    "architecture": "architecture",
    "format": "format",
    "location": "location",
    "item_id": "item_id"
  }
}

Delete hotfix

json
{
  "agent_info": {
    "agent_id": "001"
  },
  "action": "deleteHotfix",
  "data": {
    "hotfix": "hotfix_ID"
  }
}

Output examples

Clean all agents

console
wazuh-modulesd:vulnerability-scanner:scanOrchestrator.hpp:319 run : Clean-up all data event received. Cleaning up data for all agents
wazuh-modulesd:vulnerability-scanner:resultIndexer.hpp:60 handleRequest : Processing and publish key: 001_f21aca719022f009d80bbf9224741d79029b31f2_CVE-2024-28835
wazuh-modulesd:vulnerability-scanner:resultIndexer.hpp:60 handleRequest : Processing and publish key: 001_f21aca719022f009d80bbf9224741d79029b31f2_CVE-2024-28834
wazuh-modulesd:vulnerability-scanner:resultIndexer.hpp:60 handleRequest : Processing and publish key: 001_f21aca719022f009d80bbf9224741d79029b31f2_CVE-2024-12243
wazuh-modulesd:vulnerability-scanner:cleanInventory.hpp:89 operator() : Deleting all entries for key prefix: 001_f21aca719022f009d80bbf9224741d79029b31f2
wazuh-modulesd:vulnerability-scanner:scanOrchestrator.hpp:339 run : Event type: 9 processed
indexer-connector:indexerConnector.cpp:584 operator() : Added document for deletion with id: 001_f21aca719022f009d80bbf9224741d79029b31f2_CVE-2024-28835.
indexer-connector:indexerConnector.cpp:584 operator() : Added document for deletion with id: 001_f21aca719022f009d80bbf9224741d79029b31f2_CVE-2024-28834.
indexer-connector:indexerConnector.cpp:584 operator() : Added document for deletion with id: 001_f21aca719022f009d80bbf9224741d79029b31f2_CVE-2024-12243.

Clean single agent

console
wazuh-modulesd:vulnerability-scanner:scanOrchestrator.hpp:324 run : Processing 'CleanupSingleAgentData' event for agent '001'
wazuh-modulesd:vulnerability-scanner:cleanAgentInventory.hpp:81 operator() : Deleting package agent vulnerabilities key: 001_f21aca719022f009d80bbf9224741d79029b31f2
wazuh-modulesd:vulnerability-scanner:resultIndexer.hpp:60 handleRequest : Processing and publish key: DeleteByQuery request

databaseFeedManager Tool

Location Path

console
src/build/wazuh_modules/vulnerability_scanner/testtool/databaseFeedManager/database_feed_manager_testtool

Note: execute the cli with --help to display the available options.

Inject CVEs into the Vulnerability Scanner Database

Command

console
src/build/wazuh_modules/vulnerability_scanner/testtool/databaseFeedManager/database_feed_manager_testtool -c config.json -F <CVE5.fbs_PATH> -r <LIST_CVE> -o <OFFSET>

Configuration file

json
{
  "vulnerability-detection": {
    "enabled": "yes",
    "index-status": "no",
    "cti-url": "https://cti.wazuh.com/api/v1/catalog/contexts/vd_1.0.0/consumers/vd_4.8.0"
  },
  "clusterName": "cluster01",
  "clusterEnabled": false
}
  • Database Requirement: A decompressed database must exist in the current directory before running the command. You can generate it using the -d flag with the vd_scanner_testtool utility.
  • -F flag: Path to the CVE5.fbs file, the FlatBuffers schema used to parse CVE data.
  • -c flag: Path to the configuration file, which should match the configuration used by the actual vulnerability scanner.
  • -r flag: Injects new CVE entries into the database. The input must be a JSON array of CVE objects.
  • -o flag: Specifies the offset number to use when processing the CVE entries. If not specified or it's a negative number, the default offset of 99999 will be used.

Output example

console
Error deleting directory ./queue/vd #Ignore this
Replacing information for CVE: CVE-1999-0103
Process complete for CVE: CVE-1999-0103
Replacing information for CVE: CVE-2023-36617
Process complete for CVE: CVE-2023-36617
Press enter to stop the tool...