Detecting known malicious files with a custom hash blocklist

In this use case, you create a custom integration that detects files whose SHA256 hash is in a custom blocklist. It uses a KVDB to store the hashes, a decoder that looks up the hash of every file the Wazuh File Integrity Monitoring (FIM) module reports, and a detection rule that generates a finding when the hash is in the blocklist.

Note

Findings from custom integrations appear in the Threat Hunting dashboard. The Malware Detection dashboard shows findings enriched with Wazuh CTI IOCs.

Configure the Linux endpoint

This use case uses a harmless test file as a stand-in for a malware sample. Perform the following steps on an Ubuntu 24.04 endpoint.

  1. Get the SHA256 hash of the test file content. Add this hash to the blocklist in the next section:

    $ echo "Wazuh custom malware hash test" | sha256sum
    

    The command output looks similar to this:

    20027df32310861b6deaab6cc5cd41ded2980b2462296131353c0b98f8bccb4c  -
    
  2. Add the following configuration to the Wazuh agent /var/ossec/etc/ossec.conf file to monitor the /home/ubuntu/Downloads directory in real time:

    <ossec_config>
      <syscheck>
        <directories check_all="yes" realtime="yes">/home/ubuntu/Downloads</directories>
      </syscheck>
    </ossec_config>
    
  3. Restart the Wazuh agent to apply the changes:

    $ sudo systemctl restart wazuh-agent
    

Configure the Wazuh dashboard

Perform the following steps on the Wazuh dashboard to create the custom integration. Make sure the space selector reads Draft.

  1. Go to Ruleset management → Overview → Integrations → Actions → Create, enter the following values, and click Create integration:

    • Title: fim-hash-blocklist

    • Category: System Activity

    • Author: Security Team

  2. Go to Ruleset management → Normalization → KVDBs → Actions → Create, select the fim-hash-blocklist integration, and enter the following values. Click Create KVDB.

    • Title: malware_hashes. The decoder refers to the KVDB by this title.

    • Author: Security Team

    • Content: key 20027df32310861b6deaab6cc5cd41ded2980b2462296131353c0b98f8bccb4c, value Custom malware hash test file. Add one entry for each hash you want to detect.

    KVDB details of malware_hashes showing the test file hash as the key and Custom malware hash test file as the value
  3. Go to Ruleset management → Normalization → Decoders → Actions → Create, select the fim-hash-blocklist integration, paste the following root decoder in the YAML Editor, and click Create decoder. Skip this step if your custom space already has the decoder/core-wazuh-message/0 root decoder.

    name: "decoder/core-wazuh-message/0"
    metadata:
      author: "Wazuh, Inc."
      description: "Base decoder to process Wazuh message format, parses location part\
        \ and enriches the events that comes from a Wazuh agent with the host information."
      documentation: ""
      references:
      - "https://documentation.wazuh.com/"
      supports: []
      title: "Wazuh message decoder"
    normalize:
    - map:
      - _tmp_json: "parse_json($event.original)"
    enabled: true
    
  4. Create a second decoder in the same integration with the following content. It decodes FIM events and, when the file hash is a key in the malware_hashes KVDB, adds the threat.feed fields.

    name: "decoder/fim-hash-blocklist/0"
    metadata:
      title: "FIM hash blocklist decoder"
      author: "Security Team"
      description: "Decodes Wazuh FIM events and flags files whose SHA256 hash is in the malware_hashes KVDB."
      references: []
      documentation: ""
      supports: []
    parents:
    - "decoder/core-wazuh-message/0"
    check: "$_tmp_json.module == \"fim\""
    normalize:
    - map:
      - event.kind: "event"
      - event.category: "array_append_unique(file)"
      - event.dataset: "wazuh.fim"
      - file.path: "$_tmp_json.data.file.path"
      - file.hash.sha256: "$_tmp_json.data.file.hash.sha256"
    - check:
      - file.hash.sha256: "kvdb_match('malware_hashes')"
      map:
      - threat.feed.name: "malware_hashes"
      - threat.feed.description: "kvdb_get('malware_hashes', $file.hash.sha256)"
    - map:
      - _tmp_json: "delete()"
    enabled: true
    
    Decoder details of decoder/fim-hash-blocklist/0 in the YAML view
  5. Go to Ruleset management → Overview → Actions → Edit, confirm the status is Enabled, select decoder/core-wazuh-message/0 under Root decoder, and click Save.

  6. Go to Ruleset management → Detection → Rules → Actions → Create, select YAML Editor, choose the fim-hash-blocklist integration, paste the following rule, and click Create rule:

    logsource:
      product: fim-hash-blocklist
    level: high
    status: experimental
    enabled: true
    detection:
      condition: selection
      selection:
        event.dataset: wazuh.fim
        threat.feed.name: malware_hashes
    metadata:
      title: Known malicious file detected - {{file.path}}
      author: Security Team
      description: Detects a file whose SHA256 hash is listed in the malware_hashes KVDB.
      references: []
      documentation: ''
      supports: []
    mitre:
      tactic:
        id:
          - TA0002
        name:
          - Execution
      technique:
        id:
          - T1204
        name:
          - User Execution
    
    Rule details of Known malicious file detected in the YAML view
  7. Go to Ruleset management → Overview, click Actions → Promote, type the confirmation message, and click Promote to promote the content from Draft to Test. Switch the space selector to Test and repeat to promote the content to Custom. In the Custom space, the overview shows the fim-hash-blocklist integration and the root decoder:

    Ruleset management overview of the Custom space showing the fim-hash-blocklist integration and the core Wazuh message root decoder
  8. Go to Ruleset management → Detection → Detectors → Create detector, enter the following values, and click Create detector:

    • Name: fim-hash-blocklist-detector

    • Select indexes/aliases: wazuh-events-v5-system-activity

    • Space: Custom

    • Integration: fim-hash-blocklist

    • Run every: 1 minute

    Detector details of fim-hash-blocklist-detector showing its integration, data source, schedule, and active rule

    Note

    The Wazuh manager loads the custom space content periodically. Wait about two minutes after promoting the content to the Custom space before you test the configuration.

Test the configuration

Create the test file in the monitored directory of the Linux endpoint:

$ echo "Wazuh custom malware hash test" > /home/ubuntu/Downloads/malware_test.txt

Visualize the findings

Navigate to Threat intelligence → Threat Hunting and select the Findings tab. A Known malicious file detected - /home/ubuntu/Downloads/malware_test.txt finding appears with level high. Add the filter wazuh.integration.name: fim-hash-blocklist to show only the findings of this integration.

Threat Hunting dashboard Findings tab listing two Known malicious file detected findings filtered by the fim-hash-blocklist integration

Expand the finding to see the file hash, the file path, and the threat.feed.name and threat.feed.description values from the KVDB entry.

Document Details of a Known malicious file detected finding showing the file hash, the file path, and the threat feed fields