Smarty Security Policy

From WHMCS Documentation

We added this feature in WHMCS 7.0.

In WHMCS 7.0 and later, WHMCS uses Smarty Security Policies, which are security hardening measures that protect the system.

Security Policies in WHMCS

WHMCS applies a system policy for system-wide use and a mail policy for stored and dynamic email-based templates.

The System Policy

By default, WHMCS does not define any PHP functionality restrictions for the system policy other than honoring the preexisting php tag setting in the Security tab at Configuration () > System Settings > General Settings, or, prior to WHMCS 8.0, Setup > General Settings.

  • All template files that use the system policy are file-based (for example, system themes and order form templates) and require file-level access. Because of this, they are automatically implicitly trusted.
  • Custom system themes are much more likely to have additional PHP-oriented logic, and so any restrictions on them from WHMCS could result in website rendering issues. It is completely within your discretion to determine whether implicit trust at the file level is invalid. You may make any appropriate restrictions for this system policy.

The Mail Policy

The mail policy restricts the PHP functionality that email-based templates can use. The default mail policy will limit the use of variable modifiers to:

  • escape
  • count
  • urlencode
  • ucfirst
  • date_format

The default mail policy restricts the use of native PHP functions to:

  • isset
  • empty
  • count
  • sizeof
  • in_array
  • is_array
  • time
  • nl2br

Finally, the default mail policy blocks these Smarty tags:

  • block
  • function
  • include

The default mail policy will not allow any calls to static classes, fetching any data from PHP streams, or accessing any super global variables.

Redefining Security Policies

If you want to redefine either the system or mail policies, add a $smarty_security_policy setting to the configuration.php file.

This example limits email templates by modifying the mail policy to only allow the native ucwords PHP function. It does not change the default restrictions on variable modifiers:

// Smarty custom email based template policy:
$smarty_security_policy = [
    'mail' => [
        'php_functions' => [
            'ucwords',
        ],
    ],
];

The example below would restrict the use of variable modifiers to only permit the strpos variable modifier in an email template without changing the default restrictions on PHP functions:

// Smarty custom email based template policy:
$smarty_security_policy = [
    'mail' => [
        'php_modifiers' => [
            'strpos',
        ],
    ],
];

Using {include_php} Syntax

Smarty has deprecated the {include_php} syntax, but WHMCS currently supports this behavior in policies. If your template file invokes and includes a PHP script by using the Smarty {include_php} syntax, you must whitelist the full path to the script's directory in the trusted_dir setting for your policy.

// Smarty custom email based template policy:
$smarty_security_policy = [
    'system' => [
        'trusted_dir' => [
            '/path/to/folder',
        ],
    ],
];

For a list of possible settings and their behavior with arrays and Boolean values, see Smarty documentation.

Supported Policy Settings and Values

The settings that a WHMCS Smarty Security Policy enforces are the same as the settings that the Smarty library itself defines. For more information, see the Smarty documentation.

In WHMCS version 8.0 and later, WHMCS doesn't honour Smarty's disabled_special_smarty_vars parameter. Instead, policies should use the enabled_special_smarty_vars parameter. This change in behaviour is an "only allow" paradigm to the most sensitive parts of the Smarty engine implementation. It establishes a stronger security posture at present and for any future engine implementations.

// Smarty enable special variables policy:
$smarty_security_policy = [
        'system' => [
            'enabled_special_smarty_vars' => [
                'cookies',
            ],
        ],
];

The enabled_special_smarty_vars value must be an array using Smarty's options. The follow values are enabled in the WHMCS system policy for compatibility with older templates. Your current or future WHMCS templates may not require them:

'foreach',
'section',
'block',
'capture',
'now',
'get',
'post',
'server',
'request',
'template',
'const',

Defining your own Smarty Security Policy requires you to include all of the variables that client and admin templates use, including the ones that WHMCS otherwise enables by default (as above).