diegods/homelabdspbx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Create more documentation (#7627)

Browse Source 
* Documentation, format class, no modification.
This commit is contained in:
frytimo
2025-11-18 21:33:07 -04:00
committed by GitHub
parent e619c97ce6
commit adfc4cc469
104 changed files with 24461 additions and 21721 deletions
Download Patch File Download Diff File Expand all files Collapse all files
app/event_guard/resources/classes/event_guard.php
+323 -290
View File
@@ -27,303 +27,336 @@
/**
* event_guard_logs class
*/
class event_guard {
class event_guard {
/**
* declare constant variables
*/
const app_name = 'event_guard';
const app_uuid = 'c5b86612-1514-40cb-8e2c-3f01a8f6f637';
/**
* declare constant variables
*/
const app_name = 'event_guard';
const app_uuid = 'c5b86612-1514-40cb-8e2c-3f01a8f6f637';
/**
* Set in the constructor. Must be a database object and cannot be null.
* @var database Database Object
*/
private $database;
/**
* Set in the constructor. Must be a database object and cannot be null.
*
* @var database Database Object
*/
private $database;
/**
* Settings object set in the constructor. Must be a settings object and cannot be null.
* @var settings Settings Object
*/
private $settings;
/**
* Settings object set in the constructor. Must be a settings object and cannot be null.
*
* @var settings Settings Object
*/
private $settings;
/**
* User UUID set in the constructor. This can be passed in through the $settings_array associative array or set in the session global array
* @var string
*/
private $user_uuid;
/**
* User UUID set in the constructor. This can be passed in through the $settings_array associative array or set in
* the session global array
*
* @var string
*/
private $user_uuid;
/**
* Domain UUID set in the constructor. This can be passed in through the $settings_array associative array or set in the session global array
* @var string
*/
private $domain_uuid;
/**
* Domain UUID set in the constructor. This can be passed in through the $settings_array associative array or set
* in the session global array
*
* @var string
*/
private $domain_uuid;
/**
* declare the variables
*/
private $name;
private $table;
private $toggle_field;
private $toggle_values;
private $location;
/**
* declare the variables
*/
private $name;
private $table;
private $toggle_field;
private $toggle_values;
private $location;
/**
* called when the object is created
*/
public function __construct(array $setting_array = []) {
//set domain and user UUIDs
$this->domain_uuid = $setting_array['domain_uuid'] ?? $_SESSION['domain_uuid'] ?? '';
$this->user_uuid = $setting_array['user_uuid'] ?? $_SESSION['user_uuid'] ?? '';
/**
* Initializes the object with setting array.
*
* @param array $setting_array An array containing settings for domain, user, and database connections. Defaults to
* an empty array.
*
* @return void
*/
public function __construct(array $setting_array = []) {
//set domain and user UUIDs
$this->domain_uuid = $setting_array['domain_uuid'] ?? $_SESSION['domain_uuid'] ?? '';
$this->user_uuid = $setting_array['user_uuid'] ?? $_SESSION['user_uuid'] ?? '';
//set objects
$this->database = $setting_array['database'] ?? database::new();
//assign the variables
$this->name = 'event_guard_log';
$this->table = 'event_guard_logs';
$this->toggle_field = '';
$this->toggle_values = ['block','pending'];
$this->location = 'event_guard_logs.php';
}
/**
* delete rows from the database
*/
public function delete($records) {
if (permission_exists($this->name.'_delete')) {
//add multi-lingual support
$language = new text;
$text = $language->get();
//validate the token
$token = new token;
if (!$token->validate($_SERVER['PHP_SELF'])) {
message::add($text['message-invalid_token'],'negative');
header('Location: '.$this->location);
exit;
}
//delete multiple records
if (is_array($records) && @sizeof($records) != 0) {
//build the delete array
$x = 0;
foreach ($records as $record) {
//add to the array
if ($record['checked'] == 'true' && is_uuid($record['event_guard_log_uuid'])) {
$array[$this->table][$x]['event_guard_log_uuid'] = $record['event_guard_log_uuid'];
}
//increment the id
$x++;
}
//delete the checked rows
if (is_array($array) && @sizeof($array) != 0) {
//execute delete
$this->database->delete($array);
unset($array);
//set message
message::add($text['message-delete']);
}
unset($records);
}
}
}
/**
* update rows from the database change status to pending
*/
public function unblock($records) {
if (permission_exists($this->name.'_unblock')) {
//add multi-lingual support
$language = new text;
$text = $language->get();
//validate the token
$token = new token;
if (!$token->validate($_SERVER['PHP_SELF'])) {
message::add($text['message-invalid_token'],'negative');
header('Location: '.$this->location);
exit;
}
//delete multiple records
if (is_array($records) && @sizeof($records) != 0) {
//build the delete array
$x = 0;
foreach ($records as $record) {
//add to the array
if (!empty($record['checked']) && $record['checked'] == 'true' && is_uuid($record['event_guard_log_uuid'])) {
$array[$this->table][$x]['event_guard_log_uuid'] = $record['event_guard_log_uuid'];
$array[$this->table][$x]['log_status'] = 'pending';
}
//increment the id
$x++;
}
//delete the checked rows
if (is_array($array) && @sizeof($array) != 0) {
//execute delete
$this->database->save($array);
unset($array);
//initialize the settings object
$setting = new settings(["category" => 'switch']);
//send unblock event
$cmd = "sendevent CUSTOM\n";
$cmd .= "Event-Name: CUSTOM\n";
$cmd .= "Event-Subclass: event_guard:unblock\n";
$esl = event_socket::create();
$switch_result = event_socket::command($cmd);
//set message
message::add($text['message-delete']);
}
unset($records);
}
}
}
/**
* toggle a field between two values
*/
public function toggle($records) {
if (permission_exists($this->name.'_edit')) {
//add multi-lingual support
$language = new text;
$text = $language->get();
//validate the token
$token = new token;
if (!$token->validate($_SERVER['PHP_SELF'])) {
message::add($text['message-invalid_token'],'negative');
header('Location: '.$this->location);
exit;
}
//toggle the checked records
if (is_array($records) && @sizeof($records) != 0) {
//get current toggle state
foreach($records as $record) {
if (!empty($record['checked']) && $record['checked'] == 'true' && is_uuid($record['event_guard_log_uuid'])) {
$uuids[] = "'".$record['event_guard_log_uuid']."'";
}
}
if (is_array($uuids) && @sizeof($uuids) != 0) {
$sql = "select ".$this->name."_uuid as uuid, ".$this->toggle_field." as toggle from v_".$this->table." ";
$sql .= "where ".$this->name."_uuid in (".implode(', ', $uuids).") ";
$rows = $this->database->select($sql, null, 'all');
if (is_array($rows) && @sizeof($rows) != 0) {
foreach ($rows as $row) {
$states[$row['uuid']] = $row['toggle'];
}
}
unset($sql, $parameters, $rows, $row);
}
//build update array
$x = 0;
foreach($states as $uuid => $state) {
//create the array
$array[$this->table][$x][$this->name.'_uuid'] = $uuid;
$array[$this->table][$x][$this->toggle_field] = $state == $this->toggle_values[0] ? $this->toggle_values[1] : $this->toggle_values[0];
//increment the id
$x++;
}
//save the changes
if (is_array($array) && @sizeof($array) != 0) {
//save the array
$this->database->save($array);
unset($array);
//set message
message::add($text['message-toggle']);
}
unset($records, $states);
}
}
}
/**
* copy rows from the database
*/
public function copy($records) {
if (permission_exists($this->name.'_add')) {
//add multi-lingual support
$language = new text;
$text = $language->get();
//validate the token
$token = new token;
if (!$token->validate($_SERVER['PHP_SELF'])) {
message::add($text['message-invalid_token'],'negative');
header('Location: '.$this->location);
exit;
}
//copy the checked records
if (is_array($records) && @sizeof($records) != 0) {
//get checked records
foreach($records as $record) {
if (!empty($record['checked']) && $record['checked'] == 'true' && is_uuid($record['event_guard_log_uuid'])) {
$uuids[] = "'".$record['event_guard_log_uuid']."'";
}
}
//create the array from existing data
if (is_array($uuids) && @sizeof($uuids) != 0) {
$sql = "select * from v_".$this->table." ";
$sql .= "where event_guard_log_uuid in (".implode(', ', $uuids).") ";
$rows = $this->database->select($sql, null, 'all');
if (is_array($rows) && @sizeof($rows) != 0) {
$x = 0;
foreach ($rows as $row) {
//convert boolean values to a string
foreach($row as $key => $value) {
if (gettype($value) == 'boolean') {
$value = $value ? 'true' : 'false';
$row[$key] = $value;
}
}
//copy data
$array[$this->table][$x] = $row;
//add copy to the description
$array[$this->table][$x]['event_guard_log_uuid'] = uuid();
//increment the id
$x++;
}
}
unset($sql, $parameters, $rows, $row);
}
//save the changes and set the message
if (is_array($array) && @sizeof($array) != 0) {
//save the array
$this->database->save($array);
unset($array);
//set message
message::add($text['message-copy']);
}
unset($records);
}
}
}
//set objects
$this->database = $setting_array['database'] ?? database::new();
//assign the variables
$this->name = 'event_guard_log';
$this->table = 'event_guard_logs';
$this->toggle_field = '';
$this->toggle_values = ['block', 'pending'];
$this->location = 'event_guard_logs.php';
}
/**
* Deletes one or more records.
*
* @param array $records An array of record IDs to delete, where each ID is an associative array
* containing 'uuid' and 'checked' keys. The 'checked' value indicates
* whether the corresponding checkbox was checked for deletion.
*
* @return void No return value; this method modifies the database state and sets a message.
*/
public function delete($records) {
if (permission_exists($this->name . '_delete')) {
//add multi-lingual support
$language = new text;
$text = $language->get();
//validate the token
$token = new token;
if (!$token->validate($_SERVER['PHP_SELF'])) {
message::add($text['message-invalid_token'], 'negative');
header('Location: ' . $this->location);
exit;
}
//delete multiple records
if (is_array($records) && @sizeof($records) != 0) {
//build the delete array
$x = 0;
foreach ($records as $record) {
//add to the array
if ($record['checked'] == 'true' && is_uuid($record['event_guard_log_uuid'])) {
$array[$this->table][$x]['event_guard_log_uuid'] = $record['event_guard_log_uuid'];
}
//increment the id
$x++;
}
//delete the checked rows
if (is_array($array) && @sizeof($array) != 0) {
//execute delete
$this->database->delete($array);
unset($array);
//set message
message::add($text['message-delete']);
}
unset($records);
}
}
}
/**
* Unblocks multiple records.
*
* @param array $records An array of records to unblock, each containing 'event_guard_log_uuid' and 'checked' keys.
*
* @return void
*/
public function unblock($records) {
if (permission_exists($this->name . '_unblock')) {
//add multi-lingual support
$language = new text;
$text = $language->get();
//validate the token
$token = new token;
if (!$token->validate($_SERVER['PHP_SELF'])) {
message::add($text['message-invalid_token'], 'negative');
header('Location: ' . $this->location);
exit;
}
//delete multiple records
if (is_array($records) && @sizeof($records) != 0) {
//build the delete array
$x = 0;
foreach ($records as $record) {
//add to the array
if (!empty($record['checked']) && $record['checked'] == 'true' && is_uuid($record['event_guard_log_uuid'])) {
$array[$this->table][$x]['event_guard_log_uuid'] = $record['event_guard_log_uuid'];
$array[$this->table][$x]['log_status'] = 'pending';
}
//increment the id
$x++;
}
//delete the checked rows
if (is_array($array) && @sizeof($array) != 0) {
//execute delete
$this->database->save($array);
unset($array);
//initialize the settings object
$setting = new settings(["category" => 'switch']);
//send unblock event
$cmd = "sendevent CUSTOM\n";
$cmd .= "Event-Name: CUSTOM\n";
$cmd .= "Event-Subclass: event_guard:unblock\n";
$esl = event_socket::create();
$switch_result = event_socket::command($cmd);
//set message
message::add($text['message-delete']);
}
unset($records);
}
}
}
/**
* Toggles the state of one or more records.
*
* @param array $records An array of record IDs to delete, where each ID is an associative array
* containing 'uuid' and 'checked' keys. The 'checked' value indicates
* whether the corresponding checkbox was checked for deletion.
*
* @return void No return value; this method modifies the database state and sets a message.
*/
public function toggle($records) {
if (permission_exists($this->name . '_edit')) {
//add multi-lingual support
$language = new text;
$text = $language->get();
//validate the token
$token = new token;
if (!$token->validate($_SERVER['PHP_SELF'])) {
message::add($text['message-invalid_token'], 'negative');
header('Location: ' . $this->location);
exit;
}
//toggle the checked records
if (is_array($records) && @sizeof($records) != 0) {
//get current toggle state
foreach ($records as $record) {
if (!empty($record['checked']) && $record['checked'] == 'true' && is_uuid($record['event_guard_log_uuid'])) {
$uuids[] = "'" . $record['event_guard_log_uuid'] . "'";
}
}
if (is_array($uuids) && @sizeof($uuids) != 0) {
$sql = "select " . $this->name . "_uuid as uuid, " . $this->toggle_field . " as toggle from v_" . $this->table . " ";
$sql .= "where " . $this->name . "_uuid in (" . implode(', ', $uuids) . ") ";
$rows = $this->database->select($sql, null, 'all');
if (is_array($rows) && @sizeof($rows) != 0) {
foreach ($rows as $row) {
$states[$row['uuid']] = $row['toggle'];
}
}
unset($sql, $parameters, $rows, $row);
}
//build update array
$x = 0;
foreach ($states as $uuid => $state) {
//create the array
$array[$this->table][$x][$this->name . '_uuid'] = $uuid;
$array[$this->table][$x][$this->toggle_field] = $state == $this->toggle_values[0] ? $this->toggle_values[1] : $this->toggle_values[0];
//increment the id
$x++;
}
//save the changes
if (is_array($array) && @sizeof($array) != 0) {
//save the array
$this->database->save($array);
unset($array);
//set message
message::add($text['message-toggle']);
}
unset($records, $states);
}
}
}
/**
* Copies one or more records
*
* @param array $records An array of record IDs to delete, where each ID is an associative array
* containing 'uuid' and 'checked' keys. The 'checked' value indicates
* whether the corresponding checkbox was checked for deletion.
*
* @return void No return value; this method modifies the database state and sets a message.
*/
public function copy($records) {
if (permission_exists($this->name . '_add')) {
//add multi-lingual support
$language = new text;
$text = $language->get();
//validate the token
$token = new token;
if (!$token->validate($_SERVER['PHP_SELF'])) {
message::add($text['message-invalid_token'], 'negative');
header('Location: ' . $this->location);
exit;
}
//copy the checked records
if (is_array($records) && @sizeof($records) != 0) {
//get checked records
foreach ($records as $record) {
if (!empty($record['checked']) && $record['checked'] == 'true' && is_uuid($record['event_guard_log_uuid'])) {
$uuids[] = "'" . $record['event_guard_log_uuid'] . "'";
}
}
//create the array from existing data
if (is_array($uuids) && @sizeof($uuids) != 0) {
$sql = "select * from v_" . $this->table . " ";
$sql .= "where event_guard_log_uuid in (" . implode(', ', $uuids) . ") ";
$rows = $this->database->select($sql, null, 'all');
if (is_array($rows) && @sizeof($rows) != 0) {
$x = 0;
foreach ($rows as $row) {
//convert boolean values to a string
foreach ($row as $key => $value) {
if (gettype($value) == 'boolean') {
$value = $value ? 'true' : 'false';
$row[$key] = $value;
}
}
//copy data
$array[$this->table][$x] = $row;
//add copy to the description
$array[$this->table][$x]['event_guard_log_uuid'] = uuid();
//increment the id
$x++;
}
}
unset($sql, $parameters, $rows, $row);
}
//save the changes and set the message
if (is_array($array) && @sizeof($array) != 0) {
//save the array
$this->database->save($array);
unset($array);
//set message
message::add($text['message-copy']);
}
unset($records);
}
}
}
}
app/event_guard/resources/service/event_guard.php
+98 -2
View File
@@ -115,6 +115,13 @@
echo "pid_file: ".$pid_file."\n";
//function to check if the process exists
/**
* Checks if a process exists.
*
* @param string $file Path to the file containing the process ID (PID)
*
* @return bool True if the process exists, false otherwise
*/
function process_exists($file) {
//set the default exists to false
@@ -373,6 +380,13 @@
}
//run command and capture standard output
/**
* Execute a shell command and capture its output.
*
* @param string $command The shell command to execute
*
* @return string The output of the executed command
*/
function shell($command) {
ob_start();
$result = system($command);
@@ -381,6 +395,15 @@
}
//block an ip address
/**
* Execute a block command for iptables or pf based on the firewall type.
*
* @param string $ip_address The IP address to block
* @param string $filter The filter name for iptables or pf
* @param array $event The event data containing 'to-user' and 'to-host'
*
* @return boolean True if the block command was executed successfully, false otherwise
*/
function block($ip_address, $filter, $event) {
//define the global variables
global $database, $debug, $firewall_path, $firewall_name;
@@ -434,6 +457,14 @@
}
//unblock the ip address
/**
* Unblock a specified IP address from a firewall.
*
* @param string $ip_address The IP address to unblock.
* @param string $filter The filter name used in the firewall configuration.
*
* @return bool True if the IP address was successfully unblocked, false otherwise.
*/
function unblock($ip_address, $filter) {
//define the global variables
global $debug, $firewall_path, $firewall_name;
@@ -470,6 +501,13 @@
}
//is the ip address blocked
/**
* Check if an IP address is blocked in the configured firewall.
*
* @param string $ip_address The IP address to check
*
* @return bool True if the address is blocked, False otherwise
*/
function is_blocked($ip_address) {
//define the global variables
global $firewall_path, $firewall_name;
@@ -502,6 +540,17 @@
}
//determine if the IP address has been allowed by the access control list node cidr
/**
* Determine if access is allowed for a given IP address.
*
* This method checks the cache, user logs, event guard logs, access controls,
* and registration to determine if access should be granted. If no valid reason
* is found to deny access, it will be automatically allowed.
*
* @param string $ip_address The IP address to check for access.
*
* @return boolean True if access is allowed, false otherwise.
*/
function access_allowed($ip_address) {
//define global variables
global $debug;
@@ -586,6 +635,13 @@
}
//is the ip address registered
/**
* Checks if the given IP address is registered on the network.
*
* @param string $ip_address The IP address to check for registration.
*
* @return bool True if the IP address is registered, false otherwise.
*/
function is_registered($ip_address) {
//invalid ip address
if (!filter_var($ip_address, FILTER_VALIDATE_IP)) {
@@ -609,6 +665,13 @@
}
//determine if the IP address has been allowed by the access control list node cidr
/**
* Checks if the given IP address is authorized by any access control node.
*
* @param string $ip_address The IP address to check for authorization.
*
* @return bool True if the IP address is authorized, false otherwise.
*/
function access_control_allowed($ip_address) {
global $database;
@@ -653,6 +716,13 @@
}
//determine if the IP address has been allowed by a successful authentication
/**
* Determines if a user's IP address is allowed based on their login history.
*
* @param string $ip_address The IP address to check for access.
*
* @return bool True if the IP address is allowed, false otherwise.
*/
function user_log_allowed($ip_address) {
global $database, $debug;
@@ -689,6 +759,13 @@
}
//determine if the IP address has been unblocked in the event guard log
/**
* Determines if an IP address is allowed based on event guard logs.
*
* @param string $ip_address The IP address to check for access.
*
* @return bool True if the IP address is allowed, false otherwise.
*/
function event_guard_log_allowed($ip_address) {
global $database, $debug;
@@ -724,6 +801,13 @@
}
//check if the iptables chain exists
/**
* Determines if a pf table exists in the firewall configuration.
*
* @param string $table The name of the pf table to check for existence.
*
* @return bool True if the pf table exists, false otherwise.
*/
function pf_table_exists($table) {
//define the global variables
global $firewall_path, $firewall_name;
@@ -741,6 +825,13 @@
}
//add IP table chains
/**
* Adds a new IPtables chain and inserts it into the INPUT table.
*
* @param string $chain The name of the IPtables chain to add.
*
* @return bool True if the chain was successfully added, false otherwise.
*/
function iptables_chain_add($chain) {
//define the global variables
global $firewall_path;
@@ -769,6 +860,13 @@
}
//check if the iptables chain exists
/**
* Determines if a specified iptables chain exists.
*
* @param string $chain The name of the iptables chain to check for existence.
*
* @return bool True if the iptables chain exists, false otherwise.
*/
function iptables_chain_exists($chain) {
//define the global variables
global $firewall_path;
@@ -784,5 +882,3 @@
return false;
}
}
?>