Entropy limits.

Changelog excerpt:
- Added entropy limits for signatures that use normalised data,
  configurable via two newly added directives, entropy_limit and
  entropy_filesize_limit. When the entropy limits are exceeded, in order to
  reduce the risk of false positives, some signatures which use normalised
  data will be ignored.

Author: Maikuolan

Changelog.md

@@ -162,3 +162,7 @@ __*Why "v3.0.0" instead of "v1.0.0?"*__ Prior to phpMussel v3, the "phpMussel Co
 #### Other changes.
 - [2024.11.06]: Added PHP 8.4 to workflows.
 - [2024.11.06]: Improved encrypted zip file detection.
+
+### v3.6.0
+
+- [2025.03.21]: Added entropy limits for signatures that use normalised data, configurable via two newly added directives, entropy_limit and entropy_filesize_limit. When the entropy limits are exceeded, in order to reduce the risk of false positives, some signatures which use normalised data will be ignored.

assets/config.yml

@@ -7,7 +7,7 @@
 # License: GNU/GPLv2
 # @see LICENSE.txt
 #
-# This file: Configuration defaults file (last modified: 2024.09.13).
+# This file: Configuration defaults file (last modified: 2025.03.21).
 ##/
 
 core:
@@ -402,6 +402,15 @@ files:
  only_allow_images:
   type: "bool"
   default: false
+ entropy_limit:
+  type: "float"
+  step: "any"
+  default: 7.7
+  experimental: true
+ entropy_filesize_limit:
+  type: "kb"
+  default: "512KB"
+  experimental: true
 quarantine:
  quarantine_key:
   type: "string"

l10n/mr.yml

@@ -7,7 +7,7 @@
 # License: GNU/GPLv2
 # @see LICENSE.txt
 #
-# This file: Marathi language data (last modified: 2024.10.15).
+# This file: Marathi language data (last modified: 2025.03.07).
 #
 # Regarding translations: My native language is English. Because this is a free
 # and open-source hobby project which generates zero income, and translatable
@@ -69,7 +69,7 @@ response:
  Macros aren_t permitted: "मॅक्रोना परवानगी नाही"
  Missing filename: "फाइलनाव गहाळ आहे"
  No problems found: "कोणतीही समस्या आढळली नाही."
- Only image files are permitted: "फक्त इमेज फाइल्सना परवानगी आहे"
+ Only image files are permitted: "फक्त इमेज फायलींना परवानगी आहे"
  Quarantined as: ""%s.qfu" म्हणून अलग ठेवले."
  Recursion depth limit exceeded: "पुनरावृत्ती खोली मर्यादा ओलांडली"
  Signature file missing: "स्वाक्षरी फाइल गहाळ आहे"

src/Loader.php

@@ -8,7 +8,7 @@
  * License: GNU/GPLv2
  * @see LICENSE.txt
  *
- * This file: The loader (last modified: 2025.01.04).
+ * This file: The loader (last modified: 2025.03.21).
  */
 
 namespace phpMussel\Core;
@@ -90,10 +90,15 @@ class Loader
      */
     public $Cache;
 
+    /**
+     * @var \Maikuolan\Common\Demojibakefier Ensure correct data encoding.
+     */
+    public $Demojibakefier;
+
     /**
      * @var string phpMussel version number (SemVer).
      */
-    public $ScriptVersion = '3.5.4';
+    public $ScriptVersion = '3.6.0';
 
     /**
      * @var string phpMussel version identifier (complete notation).
@@ -429,6 +434,9 @@ public function __construct(
             $this->InstanceCache['PendingErrorLogData'] .= $Message . "\n";
             return true;
         });
+
+        /** phpMussel leverages the Demojibakefier's shannonEntropy method to make decisions about certain kinds of files. */
+        $this->Demojibakefier = new \Maikuolan\Common\Demojibakefier();
     }
 
     /**

src/Scanner.php

@@ -8,7 +8,7 @@
  * License: GNU/GPLv2
  * @see LICENSE.txt
  *
- * This file: The scanner (last modified: 2024.11.06).
+ * This file: The scanner (last modified: 2025.03.21).
  */
 
 namespace phpMussel\Core;
@@ -1311,6 +1311,9 @@ private function dataHandler(string $str = '', int $Depth = 0, string $OriginalF
         $str_hex_html = bin2hex($str_html);
         $str_hex_html_len = $str_html_len * 2;
 
+        /** Shannon entropy. */
+        $Entropy = $this->Loader->Demojibakefier->shannonEntropy($str);
+
         /** Look for potential Linux/ELF indicators. */
         $is_elf = ($fourcc === '7f454c46' || $xt === 'elf');
 
@@ -1695,6 +1698,7 @@ private function dataHandler(string $str = '', int $Depth = 0, string $OriginalF
                 'ScanPhase' => $phase,
                 'Container' => $container,
                 'FileSwitch' => $fileswitch,
+                'Entropy' => $Entropy,
                 'Is_ELF' => $is_elf,
                 'Is_Graphics' => $is_graphics,
                 'Is_HTML' => $is_html,
@@ -2202,16 +2206,25 @@ private function dataHandler(string $str = '', int $Depth = 0, string $OriginalF
             }
         }
 
+        /** Whether the entropy limits have been exceeded. */
+        $EntropyLimited = (
+            $Entropy > $this->Loader->Configuration['files']['entropy_limit'] &&
+            $StringLength > $this->Loader->readBytes($this->Loader->Configuration['files']['entropy_filesize_limit'])
+        );
+
         /** Process mappable signatures. */
         foreach ([
-            ['Filename', 'str_hex', 'str_hex_len', 2],
-            ['Standard', 'str_hex', 'str_hex_len', 0],
-            ['Normalised', 'str_hex_norm', 'str_hex_norm_len', 0],
-            ['HTML', 'str_hex_html', 'str_hex_html_len', 0],
-            ['Standard_RegEx', 'str_hex', 'str_hex_len', 1],
-            ['Normalised_RegEx', 'str_hex_norm', 'str_hex_norm_len', 1],
-            ['HTML_RegEx', 'str_hex_html', 'str_hex_html_len', 1]
+            ['Filename', 'str_hex', 'str_hex_len', 2, false],
+            ['Standard', 'str_hex', 'str_hex_len', 0, false],
+            ['Normalised', 'str_hex_norm', 'str_hex_norm_len', 0, $EntropyLimited],
+            ['HTML', 'str_hex_html', 'str_hex_html_len', 0, false],
+            ['Standard_RegEx', 'str_hex', 'str_hex_len', 1, false],
+            ['Normalised_RegEx', 'str_hex_norm', 'str_hex_norm_len', 1, $EntropyLimited],
+            ['HTML_RegEx', 'str_hex_html', 'str_hex_html_len', 1, false]
         ] as $ThisConf) {
+            if ($ThisConf[4]) {
+                continue;
+            }
             $DataSource = $ThisConf[1];
             $DataSourceLen = $ThisConf[2];