cacti/docs/security/settings-validation.md

Settings Validation

Why this exists

Cacti settings are written from several places: the web UI (settings.php), CLI utilities under cli/, and (planned) JSON-RPC endpoints. Each of those paths previously carried its own ad-hoc checks for the same setting, and the checks drifted apart as code was added. The intent of CactiSettings::validate() is to put the constraint definition next to the setting itself so every write path uses the same rules.

A setting in include/global_settings.php declares its constraints alongside the existing keys (method, default, max_length, ...). The validator runs the entire posted set in one pass and returns a {name => message} map. An empty map means the input is valid.

Why constraints are declared as closures

include/global_settings.php is loaded from include/global.php before include/vendor/autoload.php. Eagerly instantiating new Assert\NotBlank() inside the array literal would fatal at file-load time because the Symfony Validator classes are not yet loadable. Wrapping each constraint in an arrow function (fn() => new Assert\NotBlank()) defers the instantiation until CactiSettings::validate() runs the closures. The use Symfony\Component\Validator\Constraints as Assert; import at the top of the file is a compile-time alias and does not trigger autoloading.

How CactiSettings::validate is used in settings.php

save_settings() builds a snapshot of posted values via Cacti's request-var helpers (gnrv) and calls the validator before writing any rows:

require_once(CACTI_PATH_LIBRARY . '/CactiSettings.php');

$snapshot = [];
foreach ($settings[grv('tab')] as $field_name => $field_array) {
    $snapshot[$field_name] = gnrv($field_name);
}

$violations = CactiSettings::validate($snapshot, $settings);

if (cacti_sizeof($violations) > 0) {
    foreach ($violations as $name => $message) {
        $_SESSION['sess_error_fields'][$name] = $name;
        $_SESSION['sess_field_values'][$name] = $snapshot[$name] ?? '';
        raise_message('cacti_settings_' . $name, ..., MESSAGE_LEVEL_ERROR);
    }
    header('Location: settings.php?tab=...');
    exit;
}

When violations are present the request is rejected before any REPLACE INTO settings runs. The user is redirected back to the same tab with the error highlighted.

How to add constraints to a setting

1. Open include/global_settings.php and find the setting definition.
2. Add a 'constraints' key holding an array of closures, each returning a Symfony constraint instance.
3. The use Symfony\Component\Validator\Constraints as Assert; alias is already imported at the top of the file, so constraints read as fn() => new Assert\Range(...).
4. Wrap any custom message: argument in __() so the message participates in Cacti i18n.

Example:

'snmp_timeout' => [
    'friendly_name' => __('Timeout'),
    'method'        => 'textbox',
    'default'       => '500',
    'max_length'    => '10',
    'constraints'   => [
        fn() => new Assert\Regex(pattern: '/^\d+$/', message: __('must be a positive integer (milliseconds).')),
        fn() => new Assert\Range(min: 1, max: 600000),
    ],
],

When a Choice list duplicates a canonical array from global_arrays.php, derive the choices from that array inside the closure rather than restating the values:

'constraints' => [
    fn() => new Assert\Choice(choices: array_merge(
        array_keys($GLOBALS['poller_intervals']),
        array_map('strval', array_keys($GLOBALS['poller_intervals']))
    )),
],

Both string and integer forms of the keys are accepted because $_POST values arrive as strings while the canonical keys are integers.

Constraint types used in the pilot

See the Symfony Validator reference for the full catalog. The pilot uses:

• Assert\NotBlank -- value is present and non-empty.
• Assert\Length -- string length within min/max.
• Assert\Range -- numeric value within min/max.
• Assert\Choice -- value is one of an enumerated list. Use this for any setting that is rendered as a drop_array.
• Assert\Regex -- value matches a pattern. Useful for "is this an integer string" since $_POST values arrive as strings.
• Assert\Positive -- value is strictly greater than zero.

Migration template for the next batch

For each setting you want to constrain:

1. Identify the setting's existing implicit rule (e.g. method is drop_array with a fixed key set, or max_length is '255').
2. Translate that rule to a constraint object. drop_array becomes Assert\Choice over the array keys. max_length becomes Assert\Length. Numeric textboxes typically need Assert\Regex plus Assert\Range.
3. Add a unit test in tests/Unit/Security/InputValidation/CactiSettingsTest.php that exercises the new constraint with a synthetic definition (do not depend on include/global_settings.php from the test).
4. Run composer test and confirm the new case passes.

Translator wiring (known limitation)

CactiSettings::validator() builds the validator with Validation::createValidator() and does not pass a TranslatorInterface. Symfony's default English messages render regardless of the active Cacti locale. Custom messages declared in global_settings.php should be wrapped in __() so the operator-facing text is translatable through Cacti's own i18n stack. Wiring a TranslatorInterface so that the framework's built-in constraint messages also translate is a planned follow-up.

Defense in depth

The constraint layer supplements existing checks rather than replacing them.

• The form-render method (drop_array, dirpath, filepath, textbox_password) still enforces its implicit rules in save_settings(). For example, dirpath continues to verify the directory exists before storing.
• Any post-save handler (cache-clear, poller restart, log rotation) keeps whatever validation it already performs.
• The constraint check runs first and short-circuits the write, so downstream handlers see only values that already cleared the declared rules.