fix(csrf): distinct error codes, audit log on non-POST, honest lint header

- Distinct raise_message IDs per failure mode (syslog_method_error,
  syslog_csrf_error, syslog_csrf_unavailable) so log triage can
  differentiate non-POST, invalid token, and missing-helper paths
- Add cacti_log entry on the non-POST rejection path so the audit
  trail is symmetric with the other two fail-closed branches
- Document csrf_check($fatal=false) arg semantics inline so future
  readers see the helper contract
- Rename the regression test comment block to call out explicitly
  that it is a source-scan lint, not a behavioral test; flag follow-up
  for real behavioral coverage once a DB-backed test harness exists

Signed-off-by: Thomas Vincent <thomasvincent@gmail.com>

Author: somethingwithproof

setup.php

@@ -1609,20 +1609,25 @@ function syslog_utilities_action($action) {
 
 	if ($action == 'purge_syslog_hosts') {
 		if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
-			raise_message('syslog_error', __('Invalid request. This action requires a CSRF protected POST.', 'syslog'), MESSAGE_LEVEL_ERROR);
+			cacti_log('WARNING: syslog purge blocked -- non-POST request', false, 'SYSLOG');
+			raise_message('syslog_method_error', __('Invalid request. This action requires a CSRF protected POST.', 'syslog'), MESSAGE_LEVEL_ERROR);
 			header('Location: utilities.php');
 			exit;
 		}
 
+		// csrf_check($fatal) returns bool; $fatal=false tells the helper not to
+		// die/exit on failure so we can log and redirect with a user-visible
+		// message ourselves.
 		if (function_exists('csrf_check')) {
 			if (!csrf_check(false)) {
-				raise_message('syslog_error', __('Invalid request. This action requires a CSRF protected POST.', 'syslog'), MESSAGE_LEVEL_ERROR);
+				cacti_log('WARNING: syslog purge blocked -- CSRF token validation failed', false, 'SYSLOG');
+				raise_message('syslog_csrf_error', __('Invalid request. This action requires a CSRF protected POST.', 'syslog'), MESSAGE_LEVEL_ERROR);
 				header('Location: utilities.php');
 				exit;
 			}
 		} else {
 			cacti_log('WARNING: syslog purge blocked -- CSRF validation unavailable', false, 'SYSLOG');
-			raise_message('syslog_error', __('Invalid request. Please try again.', 'syslog'), MESSAGE_LEVEL_ERROR);
+			raise_message('syslog_csrf_unavailable', __('Invalid request. Please try again.', 'syslog'), MESSAGE_LEVEL_ERROR);
 			header('Location: utilities.php');
 			exit;
 		}

tests/regression/issue259_csrf_purge_test.php

@@ -1,4 +1,18 @@
 <?php
+/*
+ * Source-scan lint for the #259 purge-syslog-hosts CSRF hardening.
+ *
+ * This is a lint, NOT a behavioral test. It asserts that the expected
+ * CSRF-enforcement snippets exist in setup.php so regressions that
+ * silently delete the POST/csrf_check/JS-post-flow are caught at CI
+ * time. A full behavioral test would require bootstrapping Cacti's
+ * session, CSRF token, and database, which this plugin's regression
+ * harness cannot currently provide.
+ *
+ * If the guard is refactored in a way that preserves the strings but
+ * breaks the logic, this lint will NOT catch it — follow-up issue for
+ * real behavioral coverage once a DB-backed test harness exists.
+ */
 
 $setup = file_get_contents(dirname(__DIR__, 2) . '/setup.php');
 
@@ -79,8 +93,8 @@
 	exit(1);
 }
 
-// Verify user-facing message does not expose CSRF internals (log message may use "CSRF")
-if (strpos($setup, "raise_message('syslog_error', __('CSRF") !== false) {
+// Verify user-facing messages do not expose CSRF internals (log messages may use "CSRF")
+if (preg_match("/raise_message\\('syslog_[a-z_]*', __\\('CSRF/", $setup)) {
 	fwrite(STDERR, "User-facing raise_message must not expose CSRF internals to end users.\n");
 	exit(1);
 }
@@ -92,7 +106,7 @@
 }
 
 // Verify fail-closed raise_message uses MESSAGE_LEVEL_ERROR severity
-if (strpos($setup, "raise_message('syslog_error', __('Invalid request. Please try again.', 'syslog'), MESSAGE_LEVEL_ERROR)") === false) {
+if (strpos($setup, "raise_message('syslog_csrf_unavailable', __('Invalid request. Please try again.', 'syslog'), MESSAGE_LEVEL_ERROR)") === false) {
 	fwrite(STDERR, "Fail-closed branch raise_message must use MESSAGE_LEVEL_ERROR severity.\n");
 	exit(1);
 }