Harden authentication and session audit ingestion

[somethingwithproof]

Summary

• Supersedes conflicted PR Feature/auth session audit #64 with its original commits rebased onto the current develop branch.
• Captures authentication, authorization-denied, and completed-logout events using native Cacti plugin APIs.
• Adds fail-closed durable user_log ingestion with deterministic event identity, bounded retries, terminal dropped-row evidence, and database-clock activation.
• Makes authentication auditing opt-in and requires explicit admin CLI setup for local user_log indexes.
• Adds replay-safe, rate-proportional marker cleanup and idempotent external-file delivery.
• Protects the audit master switch, retention, external-file, authentication, and Syslog settings with Audit Log Admin.
• Bumps the plugin to 1.6 and removes obsolete compatibility helpers in favor of PHP 8.1+ idioms.

Validation

• Authentication/session executable-line coverage: 100% (343/343).
• Security, controller, Syslog queue, setup-default, and index-ownership tests pass.
• PHP syntax, PHP-CS-Fixer, and actionlint pass.
• Real-MySQL integration runs in the full Cacti CI workflow, including user_log timestamp and primary-key contract checks.
• Mandatory pre-push critical/high/medium review: PASS with no missing tests.

Operator note

Before enabling authentication auditing, run php plugins/audit/audit_auth_indexes.php. This keeps core-table DDL out of checkbox and poller paths.

[Copilot]

🟡 Changes recommended

plugin_audit_uninstall() can remove plugin tables/settings even when core-table index removal fails, risking a broken partial-uninstall while still returning failure.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR hardens and expands the Cacti Audit plugin to capture authentication/session security events (login outcomes, authorization denials, logout completion) with durable, replay-safe ingestion from Cacti’s user_log, while tightening admin controls around audit configuration and improving CI/test coverage for the new behavior.

Changes:

• Add poller-driven user_log ingestion with a durable deduplication table, deterministic event UUIDs, bounded retries, and replay-safe cleanup.
• Gate authentication auditing behind explicit opt-in (admin-only UI controls + CLI index setup) and add new hooks for denied/teardown events.
• Bump plugin version to 1.6 and expand unit/integration tests + CI workflows to validate the new auth ingestion and lifecycle behavior.

File summaries

File	Description
tests/syslog_queue_test.php	Updates syslog queue test stubs to account for audit_log availability gating.
tests/setup_index_test.php	Adds behavioral tests for plugin-owned user_log index create/repair/remove flows.
tests/setup_defaults_test.php	Adds tests ensuring install/upgrade defaults for auth auditing are safe and non-destructive.
tests/security_functions_test.php	Adds coverage ensuring already-delivered external events are not re-appended.
tests/controller_security_test.php	Extends static guard assertions for v1.6 upgrade path, hooks, and admin-only settings exposure.
tests/auth_sql_integration_test.php	Adds live-DB integration test for auth ingestion SQL + identity/index prerequisites.
tests/auth_audit_test.php	Adds extensive behavioral tests for auth/session ingestion, retries, dedupe, and denied/logout hooks.
tests/auth_audit_coverage_test.php	Adds a phpdbg-based gate to enforce 100% executable-line coverage for auth auditing code paths.
setup.php	Registers new hooks, adds auth defaults + upgrade steps, adds user_log state/index helpers, tightens admin settings exposure, and adjusts uninstall cleanup.
README.md	Documents the new auth ingestion model, event taxonomy, dedupe guarantees, and operational setup steps.
phpstan/stubs/cacti.stubs.php	Updates stubs with phpstan impurity annotations for DB/log side-effect functions.
phpstan-baseline.neon	Updates baseline counts and adds suppressions for new test code patterns.
INFO	Bumps plugin version to 1.6.
CHANGELOG.md	Adds a 1.6 release section describing the new authentication/session auditing and related hardening.
audit.php	Hardens event lookup and syslog details rendering against false/empty DB returns.
audit_syslog.php	Gates syslog enqueue/processing on audit_log table availability to tolerate uninstall/lifecycle edges.
audit_functions.php	Adds audit_log_table_available(), makes external/syslog delivery idempotent, adds deterministic UUID support, and implements auth ingestion + denied/logout hook handlers.
audit_auth_indexes.php	Adds a CLI helper to verify identity contract and create the required user_log indexes.
.github/workflows/plugin-ci-workflow.yml	Expands integration coverage across Cacti branches and exercises auth ingestion end-to-end, including uninstall cleanup.
.github/workflows/code-quality.yml	Updates the PHP matrix and runs the new auth/setup test suites in the quality workflow.

Review details

• Files reviewed: 20/20 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.