mactrack_actions.php

<?php
/*
 +-------------------------------------------------------------------------+
 | Copyright (C) 2004-2026 The Cacti Group                                 |
 |                                                                         |
 | This program is free software; you can redistribute it and/or           |
 | modify it under the terms of the GNU General Public License             |
 | as published by the Free Software Foundation; either version 2          |
 | of the License, or (at your option) any later version.                  |
 |                                                                         |
 | This program is distributed in the hope that it will be useful,         |
 | but WITHOUT ANY WARRANTY; without even the implied warranty of          |
 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the           |
 | GNU General Public License for more details.                            |
 +-------------------------------------------------------------------------+
 | Cacti: The Complete RRDTool-based Graphing Solution                     |
 +-------------------------------------------------------------------------+
 | This code is designed, written, and maintained by the Cacti Group. See  |
 | about.php and/or the AUTHORS file for specific developer information.   |
 +-------------------------------------------------------------------------+
 | http://www.cacti.net/                                                   |
 +-------------------------------------------------------------------------+
*/

/**
 * Validates and saves a MacTrack device record's fields, then triggers
 * a one-way sync of the saved device data back to its linked Cacti
 * device (when configured to do so). Cacti hook/API function invoked
 * when saving a device via the MacTrack device edit form or API.
 *
 * @param int    $device_id            The MacTrack device id (0 for a
 *                                     new device).
 * @param int    $host_id              The linked Cacti host id.
 * @param int    $site_id              The MacTrack site id this device
 *                                     belongs to.
 * @param string $hostname             The device's hostname/IP.
 * @param string $device_name          The device's display name.
 * @param string $scan_type            The scan type to use for this
 *                                     device.
 * @param string $snmp_options         SNMP scan options bitmask.
 * @param string $snmp_readstring      SNMP v1/v2 read community
 *                                     string.
 * @param string $snmp_version         SNMP protocol version.
 * @param string $snmp_username        SNMP v3 username.
 * @param string $snmp_password        SNMP v3 password.
 * @param string $snmp_auth_protocol   SNMP v3 authentication protocol.
 * @param string $snmp_priv_passphrase SNMP v3 privacy passphrase.
 * @param string $snmp_priv_protocol   SNMP v3 privacy protocol.
 * @param string $snmp_context         SNMP v3 context.
 * @param string $snmp_engine_id       SNMP v3 engine id.
 * @param string $snmp_port            SNMP port number.
 * @param string $snmp_timeout         SNMP timeout in milliseconds.
 * @param string $snmp_retries         SNMP retry count.
 * @param string $max_oids             Max OIDs per SNMP get-bulk
 *                                     request.
 * @param string $ignorePorts          Ports to ignore during scanning.
 * @param string $notes                Free-form notes for the device.
 * @param string $user_name            Optional CLI/telnet username for
 *                                     supplemental data collection.
 * @param string $user_password        Optional CLI/telnet password.
 * @param string $term_type            Optional terminal type for CLI
 *                                     collection.
 * @param string $private_key_path     Optional SSH private key path
 *                                     for CLI collection.
 * @param string $disabled             Whether the device is disabled.
 * @param string $scan_trunk_port      Whether to scan trunk ports.
 * @param string $device_type_id       The MacTrack device type id.
 *
 * @return int The saved device_id, or 0 if validation/save failed.
 *
 * @global array $config Cacti global configuration array; used to
 *                       locate the MacTrack library to include.
 */
function api_mactrack_device_save($device_id, $host_id, $site_id, $hostname,
	$device_name, $scan_type, $snmp_options, $snmp_readstring,
	$snmp_version, $snmp_username, $snmp_password, $snmp_auth_protocol,
	$snmp_priv_passphrase, $snmp_priv_protocol, $snmp_context,
	$snmp_engine_id, $snmp_port, $snmp_timeout, $snmp_retries, $max_oids,
	$ignorePorts, $notes, $user_name, $user_password, $term_type,
	$private_key_path, $disabled, $scan_trunk_port, $device_type_id): int {
	global $config;

	require_once($config['base_path'] . '/plugins/mactrack/lib/mactrack_functions.php');

	$save['device_id']            = $device_id;
	$save['host_id']              = $host_id;
	$save['site_id']              = $site_id;
	$save['hostname']             = form_input_validate($hostname, 'hostname', '', false, 3);
	$save['device_name']          = form_input_validate($device_name, 'device_name', '', false, 3);
	$save['notes']                = form_input_validate($notes, 'notes', '', true, 3);
	$save['scan_type']            = form_input_validate($scan_type, 'scan_type', '', false, 3);
	$save['snmp_options']         = form_input_validate($snmp_options, 'snmp_options', '^[0-9]+$', true, 3);
	$save['snmp_readstring']      = form_input_validate($snmp_readstring, 'snmp_readstring', '', true, 3); // for SNMP V3, this is optional
	$save['snmp_version']         = form_input_validate($snmp_version, 'snmp_version', '', false, 3);
	$save['snmp_username']        = form_input_validate($snmp_username, 'snmp_username', '', true, 3);
	$save['snmp_password']        = form_input_validate($snmp_password, 'snmp_password', '', true, 3);
	$save['snmp_auth_protocol']   = form_input_validate($snmp_auth_protocol, 'snmp_auth_protocol', '', true, 3);
	$save['snmp_priv_passphrase'] = form_input_validate($snmp_priv_passphrase, 'snmp_priv_passphrase', '', true, 3);
	$save['snmp_priv_protocol']   = form_input_validate($snmp_priv_protocol, 'snmp_priv_protocol', '', true, 3);
	$save['snmp_context']         = form_input_validate($snmp_context, 'snmp_context', '', true, 3);
	$save['snmp_engine_id']       = form_input_validate($snmp_engine_id, 'snmp_engine_id', '', true, 3);
	$save['snmp_port']            = form_input_validate($snmp_port, 'snmp_port', '^[0-9]+$', false, 3);
	$save['snmp_timeout']         = form_input_validate($snmp_timeout, 'snmp_timeout', '^[0-9]+$', false, 3);
	$save['snmp_retries']         = form_input_validate($snmp_retries, 'snmp_retries', '^[0-9]+$', false, 3);
	$save['max_oids']             = form_input_validate($max_oids, 'max_oids', '^[0-9]+$', false, 3);
	$save['user_name']            = form_input_validate($user_name, 'user_name', '', true, 3);
	$save['user_password']        = form_input_validate($user_password, 'user_password', '', true, 3);
	$save['ignorePorts']          = form_input_validate($ignorePorts, 'ignorePorts', '', true, 3);
	$save['term_type']            = form_input_validate($term_type, 'term_type', '', true, 3);
	$save['private_key_path']     = form_input_validate($private_key_path, 'private_key_path', '', true, 3);
	$save['disabled']             = form_input_validate($disabled, 'disabled', '', true, 3);
	$save['scan_trunk_port']      = form_input_validate($scan_trunk_port, 'scan_trunk_port', '', true, 3);
	$save['device_type_id']       = form_input_validate($device_type_id, 'device_type_id', '', true, 3);

	$device_id = 0;

	if (!is_error_message()) {
		$device_id = sql_save($save, 'mac_track_devices', 'device_id');

		if ($device_id) {
			raise_message(1);
			sync_mactrack_to_cacti($save);
		} else {
			raise_message(2);
			mactrack_debug('ERROR: Cacti Device: (' . (is_scalar($device_id) ? (string) $device_id : '') . "/$host_id): $hostname, error on save: " . serialize($save));
		}
	} else {
		mactrack_debug("ERROR: Cacti Device: ($device_id/$host_id): $hostname, error on verify: " . serialize($save));
	}

	return $device_id;
}

/**
 * Deletes a MacTrack device and all of its dependent records (ports,
 * interfaces, IPs, aggregated ports, processes, temp ports, VLANs, and
 * interface graphs) from the database.
 *
 * @param int $device_id The MacTrack device id to remove.
 *
 * @return void
 */
function api_mactrack_device_remove($device_id): void {
	db_execute('DELETE FROM mac_track_devices WHERE device_id=' . $device_id);
	db_execute('DELETE FROM mac_track_aggregated_ports WHERE device_id=' . $device_id);
	db_execute('DELETE FROM mac_track_interfaces WHERE device_id=' . $device_id);
	db_execute('DELETE FROM mac_track_ips WHERE device_id=' . $device_id);
	db_execute('DELETE FROM mac_track_ports WHERE device_id=' . $device_id);
	db_execute('DELETE FROM mac_track_processes WHERE device_id=' . $device_id);
	db_execute('DELETE FROM mac_track_processes WHERE device_id=' . $device_id);
	db_execute('DELETE FROM mac_track_temp_ports WHERE device_id=' . $device_id);
	db_execute('DELETE FROM mac_track_vlans WHERE device_id=' . $device_id);
	db_execute('DELETE FROM mac_track_interface_graphs WHERE device_id=' . $device_id);
}

/**
 * Validates and saves a MacTrack site record's fields.
 *
 * @param int    $site_id            The site id (0 for a new site).
 * @param string $site_name          The site's display name.
 * @param string $customer_contact   Customer contact info for the
 *                                  site.
 * @param string $netops_contact     Network operations contact info.
 * @param string $facilities_contact Facilities contact info.
 * @param string $site_info          Free-form site notes.
 * @param string $skip_vlans         VLANs to skip during scanning.
 * @param string $scan_vlans         VLANs to scan.
 *
 * @return int The saved site_id, or 0 if validation/save failed.
 */
function api_mactrack_site_save($site_id, $site_name, $customer_contact, $netops_contact, $facilities_contact, $site_info, $skip_vlans, $scan_vlans): int {
	$save['site_id']            = $site_id;
	$save['site_name']          = form_input_validate($site_name, 'site_name', '', false, 3);
	$save['site_info']          = form_input_validate($site_info, 'site_info', '', true, 3);
	$save['customer_contact']   = form_input_validate($customer_contact, 'customer_contact', '', true, 3);
	$save['netops_contact']     = form_input_validate($netops_contact, 'netops_contact', '', true, 3);
	$save['facilities_contact'] = form_input_validate($facilities_contact, 'facilities_contact', '', true, 3);
	$save['skip_vlans']         = form_input_validate($skip_vlans, 'skip_vlans', '', true, 3);
	$save['scan_vlans']         = form_input_validate($scan_vlans, 'scan_vlans', '', true, 3);

	$site_id = 0;

	if (!is_error_message()) {
		$site_id = sql_save($save, 'mac_track_sites', 'site_id');

		if ($site_id) {
			raise_message(1);
		} else {
			raise_message(2);
		}
	}

	return $site_id;
}

/**
 * Deletes a MacTrack site and all of its dependent records (devices,
 * aggregated ports, interfaces, IPs, IP ranges, ports, temp ports, and
 * VLANs) from the database.
 *
 * @param int $site_id The MacTrack site id to remove.
 *
 * @return void
 */
function api_mactrack_site_remove($site_id): void {
	db_execute('DELETE FROM mac_track_sites WHERE site_id=' . $site_id);
	db_execute('DELETE FROM mac_track_devices WHERE site_id=' . $site_id);
	db_execute('DELETE FROM mac_track_aggregated_ports WHERE site_id=' . $site_id);
	db_execute('DELETE FROM mac_track_interfaces WHERE site_id=' . $site_id);
	db_execute('DELETE FROM mac_track_ips WHERE site_id=' . $site_id);
	db_execute('DELETE FROM mac_track_ip_ranges WHERE site_id=' . $site_id);
	db_execute('DELETE FROM mac_track_ports WHERE site_id=' . $site_id);
	db_execute('DELETE FROM mac_track_temp_ports WHERE site_id=' . $site_id);
	db_execute('DELETE FROM mac_track_vlans WHERE site_id=' . $site_id);
}

/**
 * Pushes a MacTrack device's SNMP and connection settings to its
 * linked Cacti device record via api_device_save(), when the
 * mt_update_policy setting is configured to sync MacTrack-to-Cacti and
 * the device has a valid linked host_id.
 *
 * @param array $mt_device The MacTrack device record providing the
 *                        settings to sync.
 *
 * @return void
 *
 * @global array $config Cacti global configuration array; used to
 *                       locate library files to include.
 */
function sync_mactrack_to_cacti($mt_device): void {
	global $config;

	require_once($config['base_path'] . '/lib/api_device.php');
	require_once($config['base_path'] . '/lib/utility.php');
	require_once($config['base_path'] . '/plugins/mactrack/lib/mactrack_functions.php');

	/* do we want to 'Sync Mactrack Device to Cacti Device'
	 * AND has the device already been assigned a 'valid' host_id
	 * (aka: has the device been saved successfully) */
	if ((read_config_option('mt_update_policy', true) == 3) &&
		($mt_device['host_id'] > 0)) {
		$mt_device['snmp_engine_id'] ??= '';

		// fetch current data for cacti device
		$cacti_device = (array) db_fetch_row_prepared('SELECT * FROM host WHERE id = ?', [$mt_device['host_id']]);

		if (cacti_sizeof($cacti_device)) {
			// update cacti device
			api_device_save($cacti_device['id'], $cacti_device['host_template_id'],
				$cacti_device['description'], $cacti_device['hostname'],
				$mt_device['snmp_readstring'], $mt_device['snmp_version'], $mt_device['snmp_username'],
				$mt_device['snmp_password'], $mt_device['snmp_port'], $mt_device['snmp_timeout'],
				$cacti_device['disabled'], $cacti_device['availability_method'], $cacti_device['ping_method'], $cacti_device['ping_port'],
				$cacti_device['ping_timeout'], $cacti_device['ping_retries'], $cacti_device['notes'],
				$mt_device['snmp_auth_protocol'], $mt_device['snmp_priv_passphrase'], $mt_device['snmp_priv_protocol'],
				$mt_device['snmp_context'], $mt_device['snmp_engine_id'], $mt_device['max_oids']);

			mactrack_debug('Cacti Device: (' . $cacti_device['id'] . ') successfully updated');
		}
	}
}

/**
 * Pushes a Cacti device's SNMP and connection settings to its linked
 * MacTrack device record via api_mactrack_device_save(), when the
 * mt_update_policy setting is configured to sync Cacti-to-MacTrack and
 * a matching MacTrack device record exists. Registered as a Cacti hook
 * called after a Cacti device is saved.
 *
 * @param array $device The Cacti host record that was just saved.
 *
 * @return array The unmodified $device record, for hook chaining.
 *
 * @global array $config Cacti global configuration array; used to
 *                       locate library files to include.
 */
function sync_cacti_to_mactrack($device): array {
	global $config;

	require_once($config['base_path'] . '/plugins/mactrack/lib/mactrack_functions.php');

	/* do we want to 'Sync Cacti Device to Mactrack Device'
	 * AND has the device already been assigned a 'valid' Mactrack device id
	 * (aka: has the device been saved successfully) */
	if ((read_config_option('mt_update_policy', true) == 2) && ($device['id'] > 0)) {
		// $devices holds the whole row from host table
		// now fetch the related device from mac_track_devices, if any
		$mt_device = db_fetch_row_prepared('SELECT * FROM mac_track_devices WHERE host_id = ?', [$device['id']]);

		if (is_array($mt_device) && $mt_device) {
			$mt_device['snmp_engine_id'] ??= '';

			// update mac_track_device
			$device_id = api_mactrack_device_save(
				$mt_device['device_id'], 			// not a host column
				$device['id'],
				$mt_device['site_id'],				// not a host column (wait for 088)
				$device['hostname'],
				$device['description'],
				$mt_device['scan_type'],			// not a host column
				$mt_device['snmp_options'],			// not a host column
				$device['snmp_community'],
				$device['snmp_version'],
				$device['snmp_username'],
				$device['snmp_password'],
				$device['snmp_auth_protocol'],
				$device['snmp_priv_passphrase'],
				$device['snmp_priv_protocol'],
				$device['snmp_context'],
				$device['snmp_engine_id'],
				$device['snmp_port'],
				$device['snmp_timeout'],
				$mt_device['snmp_retries'],
				$device['max_oids'],
				$mt_device['ignorePorts'],			// not a host column
				$device['notes'],
				$mt_device['user_name'], 			// not a host column
				$mt_device['user_password'],		// not a host column
				$mt_device['term_type'],
				$mt_device['private_key_path'],
				($mt_device['disabled'] ?? ''), // not a host column
				$mt_device['scan_trunk_port'],
				$mt_device['device_type_id']
			);

			mactrack_debug(__('Mactrack Device: (%s) successfully updated', $mt_device['device_id'], 'mactrack'));
		}
	}

	// for use with next hook in chain
	return $device;
}

/**
 * Setup the new dropdown action for Device Management
 * @arg $action		actions to be performed from dropdown
 * @param mixed $action
 */
function mactrack_device_action_array($action): array {
	$action['plugin_mactrack_device'] = __('Import into Mactrack Database', 'mactrack');

	return $action;
}

/**
 * Renders the confirmation form fields for the "Import into Mactrack
 * Database" bulk device action, prompting for the MacTrack-specific
 * device settings (site, scan type, SNMP options, etc.) that cannot be
 * inferred from the existing Cacti device record.
 *
 * @param array $save The bulk-action form submission data, including
 *                   'drp_action' and 'host_array' when hosts were
 *                   selected.
 *
 * @return array The $save array, augmented with a rendered host list
 *               when applicable.
 *
 * @global array $config                      Cacti global
 *                                            configuration array
 *                                            (declared but not used
 *                                            directly here).
 * @global array $fields_mactrack_device_edit The MacTrack device edit
 *                                            form's field definitions,
 *                                            used as a template for
 *                                            the prompted fields.
 */
function mactrack_device_action_prepare($save): array {
	global $config, $fields_mactrack_device_edit;

	if (isset($save['drp_action']) && $save['drp_action'] == 'plugin_mactrack_device') {
		// find out which (if any) hosts have been checked, so we can tell the user
		if (isset($save['host_array'])) {
			// list affected hosts
			print '<tr>';
			print "<td colspan='2' class='textArea'>" .
				'<p>' . __('Click \'Continue\' to import the following Device to Mactrack?  Please specify additional Mactrack Device options as given below.', 'mactrack') . '</p>';
			print '</tr>';

			$form_array = [];

			foreach ($fields_mactrack_device_edit as $field_name => $field_array) {
				// show only those fields to the user, that cannot been taken from the device field
				if (preg_match('(site_id|scan_type|snmp_options|snmp_retries|ignorePorts|user_name|user_password|disabled|term_type|private_key_path)', $field_name)) {
					$form_array += [$field_name => $fields_mactrack_device_edit[$field_name]];

					$form_array[$field_name]['value']       = '';
					$form_array[$field_name]['description'] = '';
					$form_array[$field_name]['form_id']     = 0;
				}
			}

			draw_edit_form(
				[
					'config' => ['no_form_tag' => true],
					'fields' => $form_array
				]
			);

			print '<tr>';
			print "<td colspan='2' class='textArea'>" .
				'<p>' . __('We will use these devices SNMP options for the Mactrack Device as well.', 'mactrack') . '</p>' .
				'<ul>' . $save['host_list'] . '</ul></td>';
			print '</tr>';
		}
	}

	return $save;
}

/**
 * perform mactrack_device execute action
 * @arg $action				action to be performed
 * return				-
 * @param mixed $action
 *  */
function mactrack_device_action_execute($action): string {
	global $config;

	if ($action == 'plugin_mactrack_device') {
		// find out which (if any) hosts have been checked, so we can tell the user
		if (isset_request_var('selected_items')) {
			$selected_items = sanitize_unserialize_selected_items(get_nfilter_request_var('selected_items'));

			if ($selected_items != false) {
				// work on all selected hosts
				for ($i = 0; ($i < cacti_sizeof($selected_items)); $i++) {
					// fetch row from host table
					$device = (array) db_fetch_row_prepared('SELECT * from host WHERE id = ?', [$selected_items[$i]]);

					if (cacti_sizeof($device)) {
						// now fetch the related device from mac_track_devices, if any
						$mt_device = db_fetch_row_prepared('SELECT * from mac_track_devices WHERE host_id = ?', [$device['id']]);

						// update mac_track_device
						$device_id = api_mactrack_device_save(
							($mt_device['device_id'] ?? '0'), 	// not a host column
							$device['id'],
							get_request_var('site_id'),         // not a host column (wait for 088)
							$device['hostname'],
							$device['description'],
							get_request_var('scan_type'),       // not a host column
							get_request_var('snmp_options'),    // not a host column
							$device['snmp_community'],
							$device['snmp_version'],
							$device['snmp_username'],
							$device['snmp_password'],
							$device['snmp_auth_protocol'],
							$device['snmp_priv_passphrase'],
							$device['snmp_priv_protocol'],
							$device['snmp_context'],
							$device['snmp_engine_id'],
							$device['snmp_port'],
							$device['snmp_timeout'],
							get_request_var('snmp_retries'),
							$device['max_oids'],
							get_request_var('ignorePorts'),     // not a host column
							$device['notes'],
							get_request_var('user_name'),       // not a host column
							get_request_var('user_password'),   // not a host column
							get_request_var('term_type'),
							get_request_var('private_key_path'),
							(isset_request_var('disabled') ? get_request_var('disabled') : ''),
							($mt_device['scan_trunk_port'] ?? ''),
							($mt_device['device_type_id'] ?? 0)
						);
					}
				}
			}
		}
	}

	return $action;
}