|Classes of Caleb||>||PHP Mussel||>||_docs/readme.en.md||>||Download|
Documentation for phpMussel (English).
Note regarding translations: In the event of errors (e.g., discrepancies between translations, typos, etc), the English version of the README is considered the original and authoritative version. If you find any errors, your assistance in correcting them would be welcomed.
1. <a name="SECTION1"></a>PREAMBLE
Thank you for using phpMussel, a PHP script designed to detect trojans, viruses, malware, and other threats within files uploaded to your system wherever the script is hooked, based on the signatures of ClamAV and others.
This script is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This script is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details, located in the
Special thanks to ClamAV both for project inspiration and for the signatures that this script utilises, without which, the script would likely not exist, or at best, would have very limited value.
Special thanks to SourceForge, Bitbucket, and GitHub for hosting the project files, and to the additional sources of a number of the signatures utilised by phpMussel: PhishTank, NLNetLabs, Malware.Expert and others, and special thanks to all those supporting the project, to anyone else that I may have otherwise forgotten to mention, and to you, for using the script.
2. <a name="SECTION2"></a>HOW TO INSTALL
2.0 INSTALLING MANUALLY (FOR WEB SERVERS)
1) By your reading this, I'm assuming you've already downloaded an archived copy of the script, decompressed its contents and have it sitting somewhere on your local machine. From here, you'll want to work out where on your host or CMS you want to place those contents. A directory such as
3) Upload the contents (phpMussel and its files) to the directory you'd decided on earlier (you don't need to include the
4) CHMOD the
5) Install any signatures that you'll need. See: INSTALLING SIGNATURES.
6) Next, you'll need to "hook" phpMussel to your system or CMS. There are several different ways you can "hook" scripts such as phpMussel to your system or CMS, but the easiest is to simply include the script at the beginning of a core file of your system or CMS (one that'll generally always be loaded when someone accesses any page across your website) using a
Save file, close, reupload.
-- OR ALTERNATIVELY --
If you're using an Apache webserver and if you have access to
Or this in the
7) At this point, you're done! However, you should probably test it out to make sure it's working properly. To test out file upload protections, attempt to upload the testing files included in the package under
2.1 INSTALLING MANUALLY (FOR CLI)
1) By your reading this, I'm assuming you've already downloaded an archived copy of the script, decompressed its contents and have it sitting somewhere on your local machine. When you've determined that you're happy with the location chosen for phpMussel, continue.
2) phpMussel requires PHP to be installed on the host machine in order to execute. If you don't have PHP installed on your machine, please install PHP on your machine, following any instructions supplied by the PHP installer.
3) Optionally (strongly recommended for advanced users, but not recommended for beginners or for the inexperienced), open
4) Optionally, you can make using phpMussel in CLI mode easier for yourself by creating a batch file to automatically load PHP and phpMussel. To do this, open a plain text editor such as Notepad or Notepad++, type the complete path to the
5) Install any signatures that you'll need. See: INSTALLING SIGNATURES.
6) At this point, you're done! However, you should probably test it out to make sure it's working properly. To test phpMussel, run phpMussel and try scanning the
2.2 INSTALLING WITH COMPOSER
phpMussel is registered with Packagist, and so, if you're familiar with Composer, you can use Composer to install phpMussel (you'll still need to prepare the configuration, permissions, signatures and hooks though; see "installing manually (for web servers)" steps 2, 4, 5, and 6).
2.3 <a name="INSTALLING_SIGNATURES"></a>INSTALLING SIGNATURES
Since v1.0.0, signatures aren't included in the phpMussel package. Signatures are required by phpMussel for detecting specific threats. There are 3 main methods to install signatures:
2.3.1 Install automatically using the front-end updates page.
Firstly, you'll need to make sure that the front-end is enabled. See: FRONT-END MANAGEMENT.
Then, all you'll need to do is go to the front-end updates page, find the necessary signature files, and using the options provided on the page, install them, and activate them.
2.3.2 Generate signatures using "SigTool" and install manually.
See: SigTool documentation.
2.3.3 Download signatures from "phpMussel/Signatures" and install manually.
Firstly, go to phpMussel/Signatures. The repository contains various GZ-compressed signature files. Download the files that you need, decompress them, and copy the decompressed files to the
3. <a name="SECTION3"></a>HOW TO USE
3.0 HOW TO USE (FOR WEB SERVERS)
phpMussel should be able to operate correctly with minimal requirements on your part: After installing it, it should work immediately and be immediately usable.
File upload scanning is automated and enabled by default, so nothing is required on your behalf for this particular functionality.
However, you're also able to instruct phpMussel to scan specific files, directories and/or archives. To do this, firstly, you'll need to ensure that the appropriate configuration is set in the
| Results | Description | |---|---| | -4 | Indicates that data couldn't be scanned due to encryption. | | -3 | Indicates that problems were encountered with the phpMussel signatures files. | | -2 | Indicates that corrupt data was detected during the scan and thus the scan failed to complete. | | -1 | Indicates that extensions or addons required by PHP to execute the scan were missing and thus the scan failed to complete. | | 0 | Indicates that the scan target doesn't exist and thus there was nothing to scan. | | 1 | Indicates that the target was successfully scanned and no problems were detected. | | 2 | Indicates that the target was successfully scanned and problems were detected. |
Returns something like this (as a string):
For a full break-down of what sort of signatures phpMussel uses during its scans and how it handles these signatures, refer to the SIGNATURE FORMAT section of this README file.
If you encounter any false positives, if you encounter something new that you think should be blocked, or for anything else regarding signatures, please contact me about it so that I may make the necessary changes, which, if you do not contact me, I may not necessarily be aware of. (See: What is a "false positive"?).
To disable specific signatures included with phpMussel (such as, if you're experiencing a false positive specific to your purposes that shouldn't normally be removed from mainline), add the names of the specific signature to be disabled to the signatures greylist file (
3.1 HOW TO USE (FOR CLI)
Please refer to the "INSTALLING MANUALLY (FOR CLI)" section of this README file.
Also be aware that phpMussel is an on-demand scanner; It is NOT an on-access scanner (other than for file uploads, at the time of upload), and unlike conventional anti-virus suites, doesn't monitor active memory! It'll only detect viruses contained by file uploads, and by those specific files that you explicitly tell it to scan.
4. <a name="SECTION4"></a>FRONT-END MANAGEMENT
4.0 WHAT IS THE FRONT-END.
The front-end provides a convenient and easy way to maintain, manage, and update your phpMussel installation. You can view, share, and download logfiles via the logs page, you can modify configuration via the configuration page, you can install and uninstall components via the updates page, and you can upload, download, and modify files in your vault via the file manager.
The front-end is disabled by default in order to prevent unauthorised access (unauthorised access could have significant consequences for your website and its security). Instructions for enabling it are included below this paragraph.
4.1 HOW TO ENABLE THE FRONT-END.
1) Locate the
3) Log in with the default username and password (admin/password).
Note: After you've logged in for the first time, in order to prevent unauthorised access to the front-end, you should immediately change your username and password! This is very important, because it's possible to upload arbitrary PHP code to your website via the front-end.
Also, for optimal security, enabling "two-factor authentication" for all front-end accounts is strongly recommended (instructions provided below).
4.2 HOW TO USE THE FRONT-END.
Instructions are provided on each page of the front-end, to explain the correct way to use it and its intended purpose. If you need further explanation or any special assistance, please contact support. Alternatively, there are some videos available on YouTube which could help by way of demonstration.
4.3 TWO-FACTOR AUTHENTICATION
It's possible to make the front-end more secure by enabling two-factor authentication ("2FA"). When logging into a 2FA-enabled account, an email is sent to the email address associated with that account. This email contains a "2FA code", which the user must then enter, in addition to the username and password, in order to be able to log in using that account. This means that obtaining an account password would not be enough for any hacker or potential attacker to be able to log into that account, as they would also need to already have access to the email address associated with that account in order to be able to receive and utilise the 2FA code associated with the session, thus making the front-end more secure.
Firstly, to enable two-factor authentication, using the front-end updates page, install the PHPMailer component. phpMussel utilises PHPMailer for sending emails. It should be noted that although phpMussel, by itself, is compatible with PHP >= 5.4.0, PHPMailer requires PHP >= 5.5.0, therefore meaning that enabling two-factor authentication for the phpMussel front-end won't be possible for PHP 5.4 users.
After you've installed PHPMailer, you'll need to populate the configuration directives for PHPMailer via the phpMussel configuration page or configuration file. More information about these configuration directives is included in the configuration section of this document. After you've populated the PHPMailer configuration directives, set
Next, you'll need to associate an email address with an account, so that phpMussel knows where to send 2FA codes when logging in with that account. To do this, use the email address as the username for the account (like
Note: Protecting your vault against unauthorised access (e.g., by hardening your server's security and public access permissions), is particularly important here, due to that unauthorised access to your configuration file (which is stored in your vault), could risk exposing your outbound SMTP settings (including SMTP username and password). You should ensure that your vault is properly secured before enabling two-factor authentication. If you're unable to do this, then at least, you should create a new email account, dedicated for this purpose, as such to reduce the risks associated with exposed SMTP settings.
5. <a name="SECTION5"></a>CLI (COMMAND LINE INTERFACE)
phpMussel can be run as an interactive file scanner in CLI mode under Windows-based systems. Refer to the "HOW TO INSTALL (FOR CLI)" section of this README file for more details.
For a list of available CLI commands, at the CLI prompt, type 'c', and press Enter.
Additionally, for those interested, a video tutorial for how to use phpMussel in CLI mode is available here: - <https://youtu.be/H-Pa740-utc>
6. <a name="SECTION6"></a>FILES INCLUDED IN THIS PACKAGE
The following is a list of all of the files that should have been included in the archived copy of this script when you downloaded it, any files that may be potentially created as a result of your using this script, along with a short description of what all these files are for.
This information applies to the most recent v1 release, and mightn't be so relevant for other versions or releases.
File | Description
/_docs/ | Documentation directory (contains various files).
/_docs/readme.ar.md | Arabic documentation.
/_docs/readme.de.md | German documentation.
/_docs/readme.en.md | English documentation.
/_docs/readme.es.md | Spanish documentation.
/_docs/readme.fr.md | French documentation.
/_docs/readme.id.md | Indonesian documentation.
/_docs/readme.it.md | Italian documentation.
/_docs/readme.ja.md | Japanese documentation.
/_docs/readme.ko.md | Korean documentation.
/_docs/readme.nl.md | Dutch documentation.
/_docs/readme.pt.md | Portuguese documentation.
/_docs/readme.ru.md | Russian documentation.
/_docs/readme.ur.md | Urdu documentation.
/_docs/readme.vi.md | Vietnamese documentation.
/_docs/readme.zh-TW.md | Chinese (traditional) documentation.
/_docs/readme.zh.md | Chinese (simplified) documentation.
/_testfiles/ | Test files directory (contains various files). All contained files are test files for testing if phpMussel was correctly installed on your system, and you don't need to upload this directory or any of its files except when doing such testing.
/_testfiles/ascii_standard_testfile.txt | Test file for testing phpMussel normalised ASCII signatures.
/_testfiles/coex_testfile.rtf | Test file for testing phpMussel Complex Extended signatures.
/_testfiles/exe_standard_testfile.exe | Test file for testing phpMussel PE signatures.
/_testfiles/general_standard_testfile.txt | Test file for testing phpMussel general signatures.
/_testfiles/graphics_standard_testfile.gif | Test file for testing phpMussel graphics signatures.
/_testfiles/html_standard_testfile.html | Test file for testing phpMussel normalised HTML signatures.
/_testfiles/md5_testfile.txt | Test file for testing phpMussel MD5 signatures.
/_testfiles/ole_testfile.ole | Test file for testing phpMussel OLE signatures.
/_testfiles/pdf_standard_testfile.pdf | Test file for testing phpMussel PDF signatures.
/_testfiles/pe_sectional_testfile.exe | Test file for testing phpMussel PE Sectional signatures.
/_testfiles/swf_standard_testfile.swf | Test file for testing phpMussel SWF signatures.
/vault/ | Vault directory (contains various files).
/vault/cache/ | Cache directory (for temporary data).
/vault/cache/.htaccess | A hypertext access file (in this instance, to protect sensitive files belonging to the script from being accessed by non-authorised sources).
/vault/classes/ | Classes directory. Contains various classes used by phpMussel.
/vault/classes/Maikuolan/ | Classes directory. Contains various classes used by phpMussel.
/vault/classes/Maikuolan/Cache.php | A simple, unified cache handler.
/vault/classes/Maikuolan/ComplexStringHandler.php | Complex string handler.
/vault/classes/Maikuolan/L10N.php | L10N handler.
/vault/classes/Maikuolan/YAML.php | YAML handler.
/vault/classes/.htaccess | A hypertext access file (in this instance, to protect sensitive files belonging to the script from being accessed by non-authorised sources).
/vault/classes/ArchiveHandler.php | Responsible for handling archives.
/vault/classes/CompressionHandler.php | Responsible for handling file compression.
/vault/classes/TemporaryFileHandler.php | Responsible for creating and handling temporary files.
/vault/fe_assets/ | Front-end assets.
/vault/fe_assets/.htaccess | A hypertext access file (in this instance, to protect sensitive files belonging to the script from being accessed by non-authorised sources).
/vault/fe_assets/_2fa.html | An HTML template used when asking the user for a 2FA code.
/vault/fe_assets/_accounts.html | An HTML template for the front-end accounts page.
/vault/fe_assets/_accounts_row.html | An HTML template for the front-end accounts page.
/vault/fe_assets/_cache.html | An HTML template for the front-end cache data page.
/vault/fe_assets/_config.html | An HTML template for the front-end configuration page.
/vault/fe_assets/_config_row.html | An HTML template for the front-end configuration page.
/vault/fe_assets/_files.html | An HTML template for the file manager.
/vault/fe_assets/_files_edit.html | An HTML template for the file manager.
/vault/fe_assets/_files_rename.html | An HTML template for the file manager.
/vault/fe_assets/_files_row.html | An HTML template for the file manager.
/vault/fe_assets/_home.html | An HTML template for the front-end homepage.
/vault/fe_assets/_login.html | An HTML template for the front-end login.
/vault/fe_assets/_logs.html | An HTML template for the front-end logs page.
/vault/fe_assets/_nav_complete_access.html | An HTML template for the front-end navigation links, for those with complete access.
/vault/fe_assets/_nav_logs_access_only.html | An HTML template for the front-end navigation links, for those with logs access only.
/vault/fe_assets/_quarantine.html | An HTML template for the front-end quarantine page.
/vault/fe_assets/_quarantine_row.html | An HTML template for the front-end quarantine page.
/vault/fe_assets/_siginfo.html | An HTML template for the front-end signature information page.
/vault/fe_assets/_siginfo_row.html | An HTML template for the front-end signature information page.
/vault/fe_assets/_statistics.html | An HTML template for the front-end statistics page.
/vault/fe_assets/_updates.html | An HTML template for the front-end updates page.
/vault/fe_assets/_updates_row.html | An HTML template for the front-end updates page.
/vault/fe_assets/_upload_test.html | An HTML template for the upload test page.
/vault/fe_assets/frontend.css | CSS style-sheet for the front-end.
/vault/fe_assets/frontend.dat | Database for the front-end (contains account and session information; only generated if the front-end is enabled and used).
/vault/fe_assets/frontend.dat.safety | Generated as a safety mechanism when needed.
/vault/fe_assets/frontend.html | The main HTML template file for the front-end.
/vault/fe_assets/icons.php | Icons handler (used by the front-end file manager).
/vault/fe_assets/pips.php | Pips handler (used by the front-end file manager).
/vault/lang/ | Contains phpMussel language data.
/vault/lang/.htaccess | A hypertext access file (in this instance, to protect sensitive files belonging to the script from being accessed by non-authorised sources).
/vault/lang/lang.ar.fe.php | Arabic language data for the front-end.
/vault/lang/lang.ar.php | Arabic language data.
/vault/lang/lang.bn.fe.php | Bangla language data for the front-end.
/vault/lang/lang.bn.php | Bangla language data.
/vault/lang/lang.de.fe.php | German language data for the front-end.
/vault/lang/lang.de.php | German language data.
/vault/lang/lang.en.fe.php | English language data for the front-end.
/vault/lang/lang.en.php | English language data.
/vault/lang/lang.es.fe.php | Spanish language data for the front-end.
/vault/lang/lang.es.php | Spanish language data.
/vault/lang/lang.fr.fe.php | French language data for the front-end.
/vault/lang/lang.fr.php | French language data.
/vault/lang/lang.hi.fe.php | Hindi language data for the front-end.
/vault/lang/lang.hi.php | Hindi language data.
/vault/lang/lang.id.fe.php | Indonesian language data for the front-end.
/vault/lang/lang.id.php | Indonesian language data.
/vault/lang/lang.it.fe.php | Italian language data for the front-end.
/vault/lang/lang.it.php | Italian language data.
/vault/lang/lang.ja.fe.php | Japanese language data for the front-end.
/vault/lang/lang.ja.php | Japanese language data.
/vault/lang/lang.ko.fe.php | Korean language data for the front-end.
/vault/lang/lang.ko.php | Korean language data.
/vault/lang/lang.nl.fe.php | Dutch language data for the front-end.
/vault/lang/lang.nl.php | Dutch language data.
/vault/lang/lang.pt.fe.php | Portuguese language data for the front-end.
/vault/lang/lang.pt.php | Portuguese language data.
/vault/lang/lang.ru.fe.php | Russian language data for the front-end.
/vault/lang/lang.ru.php | Russian language data.
/vault/lang/lang.th.fe.php | Thai language data for the front-end.
/vault/lang/lang.th.php | Thai language data.
/vault/lang/lang.tr.fe.php | Turkish language data for the front-end.
/vault/lang/lang.tr.php | Turkish language data.
/vault/lang/lang.ur.fe.php | Urdu language data for the front-end.
/vault/lang/lang.ur.php | Urdu language data.
/vault/lang/lang.vi.fe.php | Vietnamese language data for the front-end.
/vault/lang/lang.vi.php | Vietnamese language data.
/vault/lang/lang.zh-tw.fe.php | Chinese (traditional) language data for the front-end.
/vault/lang/lang.zh-tw.php | Chinese (traditional) language data.
/vault/lang/lang.zh.fe.php | Chinese (simplified) language data for the front-end.
/vault/lang/lang.zh.php | Chinese (simplified) language data.
/vault/quarantine/ | Quarantine directory (contains quarantined files).
/vault/quarantine/.htaccess | A hypertext access file (in this instance, to protect sensitive files belonging to the script from being accessed by non-authorised sources).
/vault/signatures/ | Signatures directory (contains signature files).
/vault/signatures/.htaccess | A hypertext access file (in this instance, to protect sensitive files belonging to the script from being accessed by non-authorised sources).
/vault/signatures/switch.dat | Controls and sets certain variables.
/vault/.htaccess | A hypertext access file (in this instance, to protect sensitive files belonging to the script from being accessed by non-authorised sources).
/vault/.travis.php | Used by Travis CI for testing (not required for proper function of the script).
/vault/.travis.yml | Used by Travis CI for testing (not required for proper function of the script).
/vault/cli.php | CLI handler.
/vault/components.dat | Components metadata file; Used by the front-end updates page.
/vault/config.ini.RenameMe | Configuration file; Contains all the configuration options of phpMussel, telling it what to do and how to operate correctly (rename to activate).
/vault/config.php | Configuration handler.
/vault/config.yaml | Configuration defaults file; Contains default configuration values for phpMussel.
/vault/frontend.php | Front-end handler.
/vault/frontend_functions.php | Front-end functions file.
/vault/functions.php | Functions file (essential).
/vault/greylist.csv | CSV of greylisted signatures indicating to phpMussel which signatures it should be ignoring (file automatically recreated if deleted).
/vault/lang.php | Language handler.
/vault/php5.4.x.php | Polyfills for PHP 5.4.X (required for PHP 5.4.X backwards compatibility; safe to delete for newer PHP versions).
/vault/plugins.dat | Plugins metadata file; Used by the front-end updates page.
? /vault/scan_kills.txt | A record of every file upload blocked/killed by phpMussel.
? /vault/scan_log.txt | A record of everything scanned by phpMussel.
? /vault/scan_log_serialized.txt | A record of everything scanned by phpMussel.
/vault/shorthand.yaml | Contains various signature identifiers to be processed by phpMussel when interpreting signature shorthand during a scan, and when accessing signature information via the front-end.
/vault/signatures.dat | Signatures metadata file; Used by the front-end updates page.
/vault/template_custom.html | Template file; Template for HTML output produced by phpMussel for its blocked file upload message (the message seen by the uploader).
/vault/template_default.html | Template file; Template for HTML output produced by phpMussel for its blocked file upload message (the message seen by the uploader).
/vault/themes.dat | Themes metadata file; Used by the front-end updates page.
/vault/upload.php | Upload handler.
/.gitattributes | A GitHub project file (not required for proper function of script).
/.gitignore | A GitHub project file (not required for proper function of script).
/Changelog-v1.txt | A record of changes made to the script between different versions (not required for proper function of script).
/composer.json | Composer/Packagist information (not required for proper function of script).
/CONTRIBUTING.md | Information about how to contribute to the project.
/LICENSE.txt | A copy of the GNU/GPLv2 license (not required for proper function of script).
/loader.php | The loader. This is what you're supposed to be hooking into (essential)!
/PEOPLE.md | Information about the people involved in the project.
/README.md | Project summary information.
/web.config | An ASP.NET configuration file (in this instance, to protect the
? Filename may differ based on configuration stipulations (in
7. <a name="SECTION7"></a>CONFIGURATION OPTIONS
The following is a list of variables found in the
general | signatures | files | attack_specific :--|:--|:--|:-- cleanup<br />scan_log<br />scan_log_serialized<br />scan_kills<br />truncate<br />log_rotation_limit<br />log_rotation_action<br />timezone<br />timeOffset<br />timeFormat<br />ipaddr<br />enable_plugins<br />forbid_on_block<br />delete_on_sight<br />lang<br />numbers<br />quarantine_key<br />quarantine_max_filesize<br />quarantine_max_usage<br />quarantine_max_files<br />honeypot_mode<br />scan_cache_expiry<br />disable_cli<br />disable_frontend<br />max_login_attempts<br />FrontEndLog<br />disable_webfonts<br />maintenance_mode<br />default_algo<br />statistics<br /> | Active<br />fail_silently<br />fail_extensions_silently<br />detect_adware<br />detect_joke_hoax<br />detect_pua_pup<br />detect_packer_packed<br />detect_shell<br />detect_deface<br />detect_encryption<br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /> | max_uploads<br />filesize_limit<br />filesize_response<br />filetype_whitelist<br />filetype_blacklist<br />filetype_greylist<br />check_archives<br />filesize_archives<br />filetype_archives<br />max_recursion<br />block_encrypted_archives<br />max_files_in_archives<br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /> | chameleon_from_php<br />can_contain_php_file_extensions<br />chameleon_from_exe<br />chameleon_to_archive<br />chameleon_to_doc<br />chameleon_to_img<br />chameleon_to_pdf<br />archive_file_extensions<br />block_control_characters<br />corrupted_exe<br />decode_threshold<br />scannable_threshold<br />allow_leading_trailing_dots<br />block_macros<br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /> compatibility | heuristic | virustotal | urlscanner ignore_upload_errors<br />only_allow_images<br /><br /><br /><br /> | threshold<br /><br /><br /><br /><br /> | vt_public_api_key<br />vt_suspicion_level<br />vt_weighting<br />vt_quota_rate<br />vt_quota_time<br /> | lookup_hphosts<br />google_api_key<br />maximum_api_lookups<br />maximum_api_lookups_response<br />cache_time<br /> legal | template_data | PHPMailer | supplementary_cache_options pseudonymise_ip_addresses<br />privacy_policy<br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /> | theme<br />Magnification<br />css_url<br /><br /><br /><br /><br /><br /><br /><br /><br /><br /><br /> | EventLog<br />SkipAuthProcess<br />Enable2FA<br />Host<br />Port<br />SMTPSecure<br />SMTPAuth<br />Username<br />Password<br />setFromAddress<br />setFromName<br />addReplyToAddress<br />addReplyToName<br /> | enable_apcu<br />enable_memcached<br />enable_redis<br />enable_pdo<br />memcached_host<br />memcached_port<br />redis_host<br />redis_port<br />redis_timeout<br />pdo_dsn<br />pdo_username<br />pdo_password<br /><br />
General phpMussel configuration.
Useful tip: If you want, you can append date/time information to the names of your logfiles by including these in the name:
Technical clarification: In this context, "oldest" means least recently modified.
Recommended values for "ipaddr":
Value | Using
Currently supported values:
Value | Produces | Description
Note: These values aren't standardised anywhere, and probably won't be relevant beyond the package. Also, supported values may change in the future.
Note: - Signature files must firstly be installed, before you can activate them. - For the test files to work correctly, the signature files must be installed and activated. - The value of this directive is cached. After changing it, for changes to take effect, you may need to delete the cache.
File handling configuration.
"filetype_whitelist", "filetype_blacklist", "filetype_greylist"
Format | Can read | Can read recursively | Can detect encryption | Notes ---|---|---|---|--- Zip | ?? | ?? | ?? | Requires libzip (normally bundled with PHP anyway). Also supported (uses the zip format): ?? OLE object detection. ?? Office macro detection. Tar | ?? | ?? | ? | No special requirements. Format doesn't support encryption. Rar | ?? | ?? | ?? | Requires the rar extension (when this extension isn't installed, phpMussel can't read rar files). 7zip | ? | ? | ? | Still currently investigating how to read 7zip files in phpMussel. Phar | ? | ? | ? | Support for reading phar files was removed in v1.6.0, and won't be added again, due to security concerns.
If anyone is able and willing to help implement support for reading other archive formats, such help would be welcomed.
Chameleon attack detection: False = Off; True = On.
Compatibility directives for phpMussel.
Note: If scanning files using the Virus Total API is disabled, you won't need to review any of the directives in this category (
Note: Regardless of suspicion level, any files that are either blacklisted or whitelisted by phpMussel won't be scanned using the Virus Total API, because those such files would've already been declared as either malicious or benign by phpMussel by the time that they would've otherwise been scanned by the Virus Total API, and therefore, additional scanning wouldn't be required. The ability of phpMussel to scan files using the Virus Total API is intended to build further confidence for whether a file is malicious or benign in those circumstances where phpMussel itself isn't entirely certain as to whether a file is malicious or benign.
"vt_quota_rate" and "vt_quota_time"
A URL scanner in included with phpMussel, capable of detecting malicious URLs from within any data or files scanned.
Note: If the URL scanner is disabled, you won't need to review any of the directives in this category (
URL scanner API lookup configuration.
Configuration relating to legal requirements.
For more information about legal requirements and how this could affect your configuration requirements, please refer to the "LEGAL INFORMATION" section of the documentation.
Directives/Variables for templates and themes.
Template data relates to the HTML output used to generate the "Upload Denied" message displayed to users upon a file upload being blocked. If you're using custom themes for phpMussel, HTML output is sourced from the
Currently, phpMussel uses PHPMailer only for front-end two-factor authentication. If you don't use the front-end, or if you don't use two-factor authentication for the front-end, you can ignore these directives.
Supplementary cache options.
Currently, this is extremely experimental, and mightn't behave as expected! For the moment, I recommend ignoring it.
8. <a name="SECTION8"></a>SIGNATURE FORMAT
See also: - What is a "signature"?
The first 9 bytes
Type | Byte | Description
The next byte
Each non-empty line thereafter is a signature or rule. Each signature or rule occupies one line. The signature formats supported are described below.
All filename signatures follow the format:
Where NAME is the name to cite for that signature and FNRX is the regex pattern to match filenames (unencoded) against.
All hash signatures follow the format:
Where HASH is the hash (usually MD5) of an entire file, FILESIZE is the total size of that file and NAME is the name to cite for that signature.
PE SECTIONAL SIGNATURES
All PE Sectional signatures follow the format:
Where HASH is the MD5 hash of a section of a PE file, SIZE is the total size of that section and NAME is the name to cite for that signature.
PE EXTENDED SIGNATURES
All PE extended signatures follow the format:
Where $VAR is the name of the PE variable to match against, HASH is the MD5 hash of that variable, SIZE is the total size of that variable and NAME is the name to cite for that signature.
COMPLEX EXTENDED SIGNATURES
Complex Extended signatures are rather different to the other types of signatures possible with phpMussel, in that what they are matching against is specified by the signatures themselves and they can match against multiple criteria. The match criteria are delimited by ";" and the match type and match data of each match criteria is delimited by ":" as so that format for these signatures tends to look a bit like:
All other signatures follow the format:
Where NAME is the name to cite for that signature and HEX is a hexadecimal-encoded segment of the file intended to be matched by the given signature. FROM and TO are optional parameters, indicating from which and to which positions in the source data to check against.
REGEX (REGULAR EXPRESSIONS)
Any form of regex understood and correctly processed by PHP should also be correctly understood and processed by phpMussel and its signatures. However, I'd suggest taking extreme caution when writing new regex based signatures, because, if you're not entirely sure what you're doing, there can be highly irregular and/or unexpected results. Take a look at the phpMussel source-code if you're not entirely sure about the context in which regex statements are parsed. Also, remember that all patterns (with exception to filename, archive metadata and MD5 patterns) must be hexadecimally encoded (foregoing pattern syntax, of course)!
9. <a name="SECTION9"></a>KNOWN COMPATIBILITY PROBLEMS
PHP and PCRE
ANTI-VIRUS SOFTWARE COMPATIBILITY
For the most part, phpMussel should be fairly compatible with most other virus scanning software. However, conflicts have been reported by a number of users in the past. This information below is from VirusTotal.com, and it describes a number of false positives reported by various anti-virus programs against phpMussel. Although this information isn't an absolute guarantee of whether or not you will encounter compatibility problems between phpMussel and your anti-virus software, if your anti-virus software is noted as flagging against phpMussel, you should either consider disabling it prior to working with phpMussel or should consider alternative options to either your anti-virus software or phpMussel.
This information was last updated 2018.10.09 and is current for all phpMussel releases of the two most recent minor versions (v1.5.0-v1.6.0) at the time of writing this.
This information only applies to the main package. Results may vary based on installed signature files, plugins, and other peripheral components.
| Scanner | Results | |---|---| | Bkav | Reports "VEX.Webshell" |
10. <a name="SECTION10"></a>FREQUENTLY ASKED QUESTIONS (FAQ)
<a name="WHAT_IS_A_SIGNATURE"></a>What is a "signature"?
In the context of phpMussel, a "signature" refers to data that acts as an indicator/identifier for something specific that we're looking for, usually in the form of some very small, distinct, innocuous segment of something larger and otherwise harmful, like a virus or trojan, or in the form of a file checksum, hash, or other similarly identifying indicator, and usually includes a label, and some other data to help provide additional context that can be used by phpMussel to determine the best way to proceed when it encounters what we're looking for.
<a name="WHAT_IS_A_FALSE_POSITIVE"></a>What is a "false positive"?
The term "false positive" (alternatively: "false positive error"; "false alarm"), described very simply, and in a generalised context, is used when testing for a condition, to refer to the results of that test, when the results are positive (i.e., the condition is determined to be "positive", or "true"), but are expected to be (or should have been) negative (i.e., the condition, in reality, is "negative", or "false"). A "false positive" could be considered analogous to "crying wolf" (wherein the condition being tested is whether there's a wolf near the herd, the condition is "false" in that there's no wolf near the herd, and the condition is reported as "positive" by the shepherd by way of calling "wolf, wolf"), or analogous to situations in medical testing wherein a patient is diagnosed as having some illness or disease, when in reality, they have no such illness or disease.
Related outcomes when testing for a condition can be described using the terms "true positive", "true negative" and "false negative". A "true positive" refers to when the results of the test and the actual state of the condition are both true (or "positive"), and a "true negative" refers to when the results of the test and the actual state of the condition are both false (or "negative"); A "true positive" or a "true negative" is considered to be a "correct inference". The antithesis of a "false positive" is a "false negative"; A "false negative" refers to when the results of the test are negative (i.e., the condition is determined to be "negative", or "false"), but are expected to be (or should have been) positive (i.e., the condition, in reality, is "positive", or "true").
In the context of phpMussel, these terms refer to the signatures of phpMussel and the files that they block. When phpMussel blocks a file due to bad, outdated or incorrect signatures, but shouldn't have done so, or when it does so for the wrong reasons, we refer to this event as a "false positive". When phpMussel fails to block a file that should have been blocked, due to unforeseen threats, missing signatures or shortfalls in its signatures, we refer to this event as a "missed detection" (which is analogous to a "false negative").
This can be summarised by the table below:
| phpMussel should NOT block a file | phpMussel SHOULD block a file ---|---|--- phpMussel does NOT block a file | True negative (correct inference) | Missed detection (analogous to false negative) phpMussel DOES block a file | __False positive__ | True positive (correct inference)
<a name="SIGNATURE_UPDATE_FREQUENCY"></a>How frequently are signatures updated?
Update frequency varies depending on the signature files in question. All maintainers for phpMussel signature files generally try to keep their signatures as up-to-date as is possible, but as all of us have various other commitments, our lives outside the project, and as none of us are financially compensated (i.e., paid) for our efforts on the project, a precise update schedule can't be guaranteed. Generally, signatures are updated whenever there's enough time to update them. Assistance is always appreciated if you're willing to offer any.
<a name="ENCOUNTERED_PROBLEM_WHAT_TO_DO"></a>I've encountered a problem while using phpMussel and I don't know what to do about it! Please help!
<a name="MINIMUM_PHP_VERSION"></a>I want to use phpMussel (prior to v2) with a PHP version older than 5.4.0; Can you help?
No. PHP >= 5.4.0 is a minimum requirement for phpMussel < v2.
<a name="MINIMUM_PHP_VERSION_V2"></a>I want to use phpMussel (v2) with a PHP version older than 7.2.0; Can you help?
No. PHP >= 7.2.0 is a minimum requirement for phpMussel v2.
See also: Compatibility Charts.
<a name="PROTECT_MULTIPLE_DOMAINS"></a>Can I use a single phpMussel installation to protect multiple domains?
Yes. phpMussel installations are not naturally locked to specific domains, and can therefore be used to protect multiple domains. Generally, we refer to phpMussel installations protecting only one domain as "single-domain installations", and we refer to phpMussel installations protecting multiple domains and/or sub-domains as "multi-domain installations". If you operate a multi-domain installation and need to use different sets of signature files for different domains, or need phpMussel to be configured differently for different domains, it's possible to do this. After loading the configuration file (
<a name="PAY_YOU_TO_DO_IT"></a>I don't want to mess around with installing this and getting it to work with my website; Can I just pay you to do it all for me?
Maybe. This is considered on a case-by-case basis. Let us know what you need, what you're offering, and we'll let you know whether we can help.
<a name="HIRE_FOR_PRIVATE_WORK"></a>Can I hire you or any of the developers of this project for private work?
<a name="SPECIALIST_MODIFICATIONS"></a>I need specialist modifications, customisations, etc; Can you help?
<a name="ACCEPT_OR_OFFER_WORK"></a>I'm a developer, website designer, or programmer. Can I accept or offer work relating to this project?
Yes. Our license does not prohibit this.
<a name="WANT_TO_CONTRIBUTE"></a>I want to contribute to the project; Can I do this?
Yes. Contributions to the project are very welcome. Please see "CONTRIBUTING.md" for more information.
<a name="SCAN_DEBUGGING"></a>How to access specific details about files when they are scanned?
You can access specific details about files when they are scanned by assigning an array to use for this purpose prior to instructing phpMussel to scan them.
In the example below,
The array is a multidimensional array consisting of elements representing each file being scanned and sub-elements representing the details about these files. These sub-elements are as follows:
? - Not provided with cached results (only provided for new scan results).
? - Only provided when scanning PE files.
Optionally, this array can be destroyed by using the following:
<a name="CRON_TO_UPDATE_AUTOMATICALLY"></a>Can I use cron to update automatically?
Yes. An API is built into the front-end for interacting with the updates page via external scripts. A separate script, "Cronable", is available, and can be used by your cron manager or cron scheduler to update this and other supported packages automatically (this script provides its own documentation).
<a name="SCAN_NON_ANSI"></a>Can phpMussel scan files with non-ANSI names?
Let's say there's a directory you want to scan. In this directory, you have some files with non-ANSI names.
Let's assume that you're either using CLI mode or the phpMussel API to scan.
When using PHP < 7.1.0, on some systems, phpMussel won't see these files when attempting to scan the directory, and so, won't be able to scan these files. You'll likely see the same results as if you were to scan an empty directory:
Additionally, when using PHP < 7.1.0, scanning the files individually produces results like these:
This is because of the way that PHP handled non-ANSI filenames prior to PHP 7.1.0. If you experience this problem, the solution is to update your PHP installation to 7.1.0 or newer. In PHP >= 7.1.0, non-ANSI filenames are handled better, and phpMussel should be able to scan the files properly.
For comparison, the results when attempting to scan the directory using PHP >= 7.1.0:
And attempting to scan the files individually:
<a name="BLACK_WHITE_GREY"></a>Blacklists ? Whitelists ? Greylists ? What are they, and how do I use them?
The terms convey different meanings in different contexts. In phpMussel, there are three contexts where these terms are used: Filesize response, filetype response, and the signature greylist.
In order to achieve a desired outcome at minimal cost to processing, there are some simple things that phpMussel can check prior to actually scanning files, such as a file's size, name, and extension. For example; If a file is too large, or if its extension indicates a type of file that we don't want to allow onto our websites anyway, we can flag the file immediately, and don't need to scan it.
Filesize response is the way that phpMussel responds when a file exceeds a specified limit. Though no actual lists are involved, a file may be considered effectively blacklisted, whitelisted, or greylisted, based on its size. Two separate, optional configuration directives exist to specify a limit and desired response respectively.
Filetype response is the way that phpMussel responds to file's extension. Three separate, optional configuration directives exist to explicitly specify which extensions should be blacklisted, whitelisted, or greylisted. A file may be considered effectively blacklisted, whitelisted, or greylisted if its extension matches any of the specified extensions respectively.
In these two contexts, being whitelisted means that it shouldn't be scanned or flagged; being blacklisted means that it should be flagged (and therefore don't need to scan it); and being greylisted means further analysis is required to determine whether we should flag it (i.e., it should be scanned).
The signature greylist is a list of signatures that should essentially be ignored (this is briefly mentioned earlier in the documentation). When a signature on the signature greylist is triggered, phpMussel continues working through its signatures and takes no particular action in regards to the greylisted signature. There's no signature blacklist, because the implied behaviour is normal behaviour for triggered signatures anyway, and there's no signature whitelist, because the implied behaviour wouldn't really make sense in consideration of how phpMussel normal works and the capabilities it already has.
The signature greylist is useful if you need to resolve problems caused by a particular signature without disabling or uninstalling the entire signature file.
<a name="CHANGE_COMPONENT_SORT_ORDER"></a>When I activate or deactivate signature files via the updates page, it sorts them alphanumerically in the configuration. Can I change the way that they get sorted?
Yes. If you need to force some files to execute in a specific order, you can add some arbitrary data before their names in the configuration directive where they're listed, separated by a colon. When the updates page subsequently sorts the files again, this added arbitrary data will affect the sort order, causing them consequently to execute in the order that you want, without needing to rename any of them.
For example, assuming a configuration directive with files listed as follows:
If you wanted
Then, if a new file,
Same situation when a file is deactivated. Conversely, if you wanted the file to execute last, you could add something like
11. <a name="SECTION11"></a>LEGAL INFORMATION
11.0 SECTION PREAMBLE
This section of the documentation is intended to describe possible legal considerations regarding the use and implementation of the package, and to provide some basic related information. This may be important for some users as a means to ensure compliancy with any legal requirements that may exist in the countries that they operate in, and some users may need to adjust their website policies in accordance with this information.
First and foremost, please realise that I (the package author) am not a lawyer, nor a qualified legal professional of any kind. Therefore, I am not legally qualified to provide legal advice. Also, in some cases, exact legal requirements may vary between different countries and jurisdictions, and these varying legal requirements may sometimes conflict (such as, for example, in the case of countries that favour privacy rights and the right to be forgotten, versus countries that favour extended data retention). Consider also that access to the package is not restricted to specific countries or jurisdictions, and therefore, the package userbase is likely to the geographically diverse. These points considered, I'm not in a position to state what it means to be "legally compliant" for all users, in all regards. However, I hope that the information herein will help you to come to a decision yourself regarding what you must do in order to remain legally compliant in the context of the package. If you have any doubts or concerns regarding the information herein, or if you need additional help and advice from a legal perspective, I would recommend consulting a qualified legal professional.
11.1 LIABILITY AND RESPONSIBILITY
As per already stated by the package license, the package is provided without any warranty. This includes (but is not limited to) all scope of liability. The package is provided to you for your convenience, in the hope that it will be useful, and that it will provide some benefit for you. However, whether you use or implement the package, is your own choice. You are not forced to use or implement the package, but when you do so, you are responsible for that decision. Neither I, nor any other contributors to the package, are legally responsible for the consequences of the decisions that you make, regardless of whether direct, indirect, implied, or otherwise.
11.2 THIRD PARTIES
Depending on its exact configuration and implementation, the package may communicate and share information with third parties in some cases. This information may be defined as "personally identifiable information" (PII) in some contexts, by some jurisdictions.
How this information may be used by these third parties, is subject to the various policies set forth by these third parties, and is outside the scope of this documentation. However, in all such cases, sharing of information with these third parties can be disabled. In all such cases, if you choose to enable it, it is your responsibility to research any concerns that you may have regarding the privacy, security, and usage of PII by these third parties. If any doubts exist, or if you're unsatisfied with the conduct of these third parties in regards to PII, it may be best to disable all sharing of information with these third parties.
For the purpose of transparency, the type of information shared, and with whom, is described below.
Some custom themes, as well as the the standard UI ("user interface") for the phpMussel front-end and the "Upload Denied" page, may use webfonts for aesthetic reasons. Webfonts are disabled by default, but when enabled, direct communication between the user's browser and the service hosting the webfonts occurs. This may potentially involve communicating information such as the user's IP address, user agent, operating system, and other details available to the request. Most of these webfonts are hosted by the Google Fonts service.
Relevant configuration directives:
11.2.1 URL SCANNER
URLs found within file uploads may be shared with the hpHosts API or the Google Safe Browsing API, depending on how the package is configured. In the case of the hpHosts API, this behaviour is enabled by default. The Google Safe Browsing API requires API keys in order to work correctly, and is therefore disabled by default.
Relevant configuration directives:
11.2.2 VIRUS TOTAL
When phpMussel scans a file upload, the hashes of those files may be shared with the Virus Total API, depending on how the package is configured. There are plans to be able to share entire files at some point in the future too, but this feature isn't supported by the package at this time. The Virus Total API requires an API key in order to work correctly, and is therefore disabled by default.
Relevant configuration directives:
Logging is an important part of phpMussel for a number of reasons. Without logging, it may be difficult to diagnose false positives, to ascertain exactly how performant phpMussel is in any particular context, and to determine where its shortfalls may be, and what changes may be required to its configuration or signatures accordingly, in order for it to continue functioning as intended. Regardless, logging mightn't be desirable for all users, and remains entirely optional. In phpMussel, logging is disabled by default. To enable it, phpMussel must be configured accordingly.
Additionally, whether logging is legally permissible, and to the extent that it is legally permissible (e.g., the types of information that may be logged, for how long, and under what circumstances), may vary, depending on jurisdiction and on the context where phpMussel is implemented (e.g., whether you're operating as an individual, as a corporate entity, and whether on a commercial or non-commercial basis). It may therefore be useful for you to read through this section carefully.
There are multiple types of logging that phpMussel can perform. Different types of logging involves different types of information, for different reasons.
11.3.0 SCAN LOGS
When enabled in the package configuration, phpMussel keeps logs of the files it scans. This type of logging is available in two different formats: - Human readable logfiles. - Serialised logfiles.
Entries to a human readable logfile typically look something like this (as an example):
A scan log entry typically includes the following information: - The date and time that the file was scanned. - The name of the file scanned. - CRC32b hashes of the name and contents of the file. - What was detected in the file (if anything was detected).
Relevant configuration directives:
When these directives are left empty, this type of logging will remain disabled.
11.3.1 SCAN KILLS
When enabled in the package configuration, phpMussel keeps logs of the uploads that have been blocked.
Entries to a "scan kills" logfile typically look something like this (as an example):
A "scan kills" entry typically includes the following information: - The date and time that the upload was blocked. - The IP address where the upload originated from. - The reason why the file was blocked (what was detected). - The name of the file blocked. - An MD5 and the size of the file blocked. - Whether the file was quarantined, and under what internal name.
Relevant configuration directives:
11.3.2 FRONT-END LOGGING
This type of logging relates front-end login attempts, and occurs only when a user attempts to log into the front-end (assuming front-end access is enabled).
A front-end log entry contains the IP address of the user attempting to log in, the date and time that the attempt occurred, and the results of the attempt (successfully logged in, or failed to log in). A front-end log entry typically looks something like this (as an example):
Relevant configuration directives:
11.3.3 LOG ROTATION
You may want to purge logs after a period of time, or may be required to do so by law (i.e., the amount of time that it's legally permissible for you to retain logs may be limited by law). You can achieve this by including date/time markers in the names of your logfiles as per specified by your package configuration (e.g.,
For example: If I was legally required to delete logs after 30 days, I could specify
Conversely, if you're required to retain logs for an extended period of time, you could either not use log rotation at all, or you could set the value of
Relevant configuration directives:
11.3.4 LOG TRUNCATION
It's also possible to truncate individual logfiles when they exceed a certain size, if this is something you might need or want to do.
Relevant configuration directives:
11.3.5 IP ADDRESS PSEUDONYMISATION
Firstly, if you're not familiar with the term, "pseudonymisation" refers to the processing of personal data as such that it can't be identified to any specific data subject anymore without supplementary information, and provided that such supplementary information is maintained separately and subject to technical and organisational measures to ensure that personal data can't be identified to any natural person.
The following resources can help to explain it in more detail: - [[trust-hub.com] What is pseudonymisation?](https://www.trust-hub.com/news/what-is-pseudonymisation/) - [[dataprotection.ie] Anonymisation and pseudonymisation](https://www.dataprotection.ie/docs/Anonymisation-and-pseudonymisation/1594.htm) - [[Wikipedia] Pseudonymization](https://en.wikipedia.org/wiki/Pseudonymization)
In some circumstances, you may be legally required to anonymise or pseudonymise any PII collected, processed, or stored. Although this concept has existed for quite some time now, GDPR/DSGVO notably mentions, and specifically encourages "pseudonymisation".
phpMussel is able to pseudonymise IP addresses when logging them, if this is something you might need or want to do. When phpMussel pseudonymises IP addresses, when logged, the final octet of IPv4 addresses, and everything after the second part of IPv6 addresses is represented by an "x" (effectively rounding IPv4 addresses to the initial address of the 24th subnet they factor into, and IPv6 addresses to the initial address of the 32nd subnet they factor into).
Relevant configuration directives:
phpMussel is optionally able to track statistics such as the total number of files scanned and blocked since some particular point in time. This feature is disabled by default, but can be enabled via the package configuration. The type of information tracked shouldn't be regarded as PII.
Relevant configuration directives:
phpMussel doesn't encrypt its cache or any log information. Cache and log encryption may be introduced in the future, but there aren't any specific plans for it currently. If you're concerned about unauthorised third parties gaining access to parts of phpMussel that may contain PII or sensitive information such as its cache or logs, I would recommend that phpMussel not be installed at a publicly accessible location (e.g., install phpMussel outside the standard
When a user successfully logs into the front-end, phpMussel sets a cookie in order to be able to remember the user for subsequent requests (i.e., cookies are used to authenticate the user to a login session). On the login page, a cookie warning is displayed prominently, warning the user that a cookie will be set if they engage in the relevant action. Cookies aren't set at any other points in the codebase.
Relevant configuration directives:
11.5 MARKETING AND ADVERTISING
phpMussel doesn't collect or process any information for marketing or advertising purposes, and neither sells nor profits from any collected or logged information. phpMussel is not a commercial enterprise, nor is related to any commercial interests, so doing these things wouldn't make any sense. This has been the case since the beginning of the project, and continues to be the case today. Additionally, doing these things would be counter-productive to the spirit and intended purpose of the project as a whole, and for as long as I continue to maintain the project, will never happen.
Relevant configuration directives:
The General Data Protection Regulation (GDPR) is a regulation of the European Union, which comes into effect as of May 25, 2018. The primary goal of the regulation is to give control to EU citizens and residents regarding their own personal data, and to unify regulation within the EU concerning privacy and personal data.
The regulation contains specific provisions pertaining to the processing of "personally identifiable information" (PII) of any "data subjects" (any identified or identifiable natural person) either from or within the EU. To be compliant with the regulation, "enterprises" (as per defined by the regulation), and any relevant systems and processes must implement "privacy by design" by default, must use the highest possible privacy settings, must implement necessary safeguards for any stored or processed information (including, but not limited to, the implementation of pseudonymisation or full anonymisation of data), must clearly and unambiguously declare the types of data they collect, how they process it, for what reasons, for how long they retain it, and whether they share this data with any third parties, the types of data shared with third parties, how, why, and so on.
Data may not be processed unless there's a lawful basis for doing so, as per defined by the regulation. Generally, this means that in order to process a data subject's data on a lawful basis, it must be done in compliance with legal obligations, or done only after explicit, well-informed, unambiguous consent has been obtained from the data subject.
Because aspects of the regulation may evolve in time, in order to avoid the propagation of outdated information, it may be better to learn about the regulation from an authoritative source, as opposed to simply including the relevant information here in the package documentation (which may eventually become outdated as the regulation evolves).
EUR-Lex (a part of the official website of the European Union that provides information about EU law) provides extensive information about GDPR/DSGVO, available in 24 different languages (at the time of writing this), and available for download in PDF format. I would definitely recommend reading the information that they provide, in order to learn more about GDPR/DSGVO: - REGULATION (EU) 2016/679 OF THE EUROPEAN PARLIAMENT AND OF THE COUNCIL
Intersoft Consulting also provides extensive information about GDPR/DSGVO, available in German and English, which could be useful to learn more about GDPR/DSGVO: - General Data Protection Regulation (GDPR) ? Final text neatly arranged
Alternatively, there's a brief (non-authoritative) overview of GDPR/DSGVO available at Wikipedia: - General Data Protection Regulation
Last Updated: 7 April 2019 (2019.04.07).