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];