(Module) Audit Log Development

staticsyphon · February 5, 2026, 6:15pm

Working on an Audit Log module for FreePBX to show changes made through the UI portal (and maybe file diff too, but starting with UI database changes)

Any thoughts/comments on this? Any ideas about existing functionality for this already in FreePBX?

penguinpbx · February 5, 2026, 6:49pm

Howdy! Welcome back to the forums.

There’s quite a few logs tracking user interaction, such as Apache logs and FreePBX specific logs. Improving what gets stored in those logs is one approach.

For the database changes, you might consider TRIGGER statements that capture table modifications row-by-row into another “audit” table sharing the same column structure but with additional columns for audit_timestamp, audit_user, audit_operation, etc. More details on TRIGGERs:

As for files, the Debian-native etckeeper package is pretty slick for automating configuration file version control.

Another idea regarding where to insert this work… if it sits in between all write operations and the underlying database/file system, then you could put yourself on the path to an Undo History in addition to the Audit Log.

Related, security-wise, logging the details of everything, e.g. passwords, is not good either.

staticsyphon · February 5, 2026, 7:40pm

These are all really good points, thank you for taking the time to share!

I’ll consolidate your thoughts and what I’ve thought so far below.

Change sources for tracking:

FreePBX UI Database
AstDB - Asterisk database
File system logs

Tracking methods:

FreePBX Database (MariaDB): TRIGGER statements to track table modifications
AstDB - May have functionality similar to TRIGGERs? Alternative: crude snapshot dump + diff on interval (not very “audit”-y, more tracking at interval)
Diff on any new log entries since last read

(Consolidation) Outputs:

Simple: Plaintext log with single line entries like log file, human-friendly and quickly reviewable
NoSQL/Structured: JSON log with machine-friendly event objects
Database: Report-friendly rows with columns for data helpful in reporting

penguinpbx · February 5, 2026, 8:59pm

Regarding AstDB, snapshots could be a challenge on larger systems, in part because there is so much Asterisk SIP state tracked there completely outside of the confines of the FreePBX GUI. When the GUI does manipulate the AstDB, it is probably going through the plumbing to reach commands like database put here:

github.com/FreePBX/framework

amp_conf/htdocs/admin/libraries/php-asmanager.php

ec80591a8


      
          				}
          				$this->memAstDB[$keyUsed] = $value;
          				$write_through = true;
          			}
          			$this->memAstDBArray = array();
          		} else {
          			$write_through = true;
          		}
          		if ($write_through) {
          			$value = freepbx_str_replace('"','\\"',$value);
          			$r = $this->command("database put ".freepbx_str_replace(" ","/",$family)." ".freepbx_str_replace(" ","/",$key)." \"".$value."\"");
          			return (bool)strstr($r["data"] ?? '', "success");
          		}
          		return true;
          	}
          
          	/** Get an entry from the asterisk database
          	 * @param string $family	The family name to use
          	 * @param string $key		The key name to use
          	 * @return mixed Value of the key, or false if error
          	 */

And here:

github.com/FreePBX/firewall

phar/src/asmanager.php

7e63811ca


      
          			if (!isset($this->memAstDB[$keyUsed]) || $this->memAstDB[$keyUsed] != $value) {
          				$this->memAstDB[$keyUsed] = $value;
          				$write_through = true;
          			}
          			$this->memAstDBArray = array();
          		} else {
          			$write_through = true;
          		}
          		if ($write_through) {
          			$value = str_replace('"','\\"',$value);
          			$r = $this->command("database put ".str_replace(" ","/",$family)." ".str_replace(" ","/",$key)." \"".$value."\"");
          			return (bool)strstr($r["data"], "success");
          		}
          		return true;
          	}
          
          	/** Get an entry from the asterisk database
          	 * @param string $family	The family name to use
          	 * @param string $key		The key name to use
          	 * @return mixed Value of the key, or false if error
          	 */

And here:

github.com/FreePBX/voicemail

functions.inc.php

b1afb16de


      
          						if (isset($args[$id]) && !empty($args[$id]) && $args[$id] != "undefined") {
          							$options[$key] = $args[$id];
          						}
          					}
          					/* Remove call me num from options - that is set in ast db */
          					unset($options["callmenum"]);
          					/* New account values to vmconf */
          					$vmconf[$context][$extension] = ["mailbox"	=> $extension, "pwd" 		=> $pwd, "name" 		=> $name, "email" 	=> $email, "pager" 	=> $pager, "options" 	=> $options];
          					$callmenum = (isset($args["acct__callmenum"]) && !empty($args["acct__callmenum"]))?$args["acct__callmenum"]:$extension;
          					// Save call me num.
          					$cmd = "database put AMPUSER $extension/callmenum $callmenum";
          					if($astman->connected()) {
          						$astman->send_request("Command", ["Command" => $cmd]);
          					}
          				}
          				break;
          			case "bsettings":
          				if (!empty($extension)) {
          					/* Get user's old settings, since we are only replacing the basic settings. */
          					$vmbox = voicemail_mailbox_get($extension);
          					/* Delete user's old settings. */

And here:

github.com/FreePBX/voicemail

functions.inc.php

b1afb16de


      
          						} else if ($args[$id] == "undefined") {
          							unset($options[$basic_opt]);
          						}
          					}
          					/* Remove call me num from options - that is set in ast db. Should not be here anyway, since options are coming from the old settings... */
          					unset($options["callmenum"]);
          					/* New account values to vmconf */
          					$vmconf[$context][$extension] = ["mailbox"	=> $extension, "pwd" 		=> $pwd, "name" 		=> $name, "email" 	=> $email, "pager" 	=> $pager, "options" 	=> $options];
          					$callmenum = (isset($args["acct__callmenum"]) && !empty($args["acct__callmenum"]))?$args["acct__callmenum"]:$extension;
          					// Save call me num.
          					$cmd = "database put AMPUSER $extension/callmenum $callmenum";
          					if($astman->connected()) {
          						$astman->send_request("Command", ["Command" => $cmd]);
          					}
          				}
          				break;
          			default:
          				return false;
          		}
          		if(!empty($vmconf)) {
          			$vmconf['general']['charset'] = "UTF-8";

And maybe more… but (hopefully not) here:

github.com/FreePBX/framework

amp_conf/agi-bin/phpagi-asmanager.php

ec80591a8


      
          		}
          		return $db;
          	}
          
          	/** Add an entry to the asterisk database
          	 * @param string $family	The family name to use
          	 * @param string $key		The key name to use
          	 * @param mixed $value		The value to add
          	 * @return bool True if successful
          	 */
          	function database_put($family, $key, $value) {
          		$value = (trim($value ?? ' ') == '')?'"'.$value.'"':$value;
          		$r = $this->command("database put ".str_replace(" ","/",$family)." ".str_replace(" ","/",$key)." ".$value);
          		if (!empty($this->memAstDB)){
          			$keyUsed="/".str_replace(" ","/",$family)."/".str_replace(" ","/",$key);
          			$this->memAstDB[$keyUsed] = $value;
          		}
          		return (bool)strstr($r["data"], "success");
          	}
          
          	/** Get an entry from the asterisk database

Slightly aside, probably should add some upgrades from the generic command to more direct AMI commands in to the v18 milestone, so we can do nice things like DBPut and stuff… here is the GH issue.

staticsyphon · February 6, 2026, 2:37am

Awesome, I’ll review those instances.

I might also have a converged/timeline view which compiles events/changes from all sources and shows in one combined view (also hiding extra instances when an event results in entries in all the sources.)