Skip to content

Commit

Permalink
Fix the help pages for devices and components.
Browse files Browse the repository at this point in the history
  • Loading branch information
@mark-unwin
mark-unwin committed Jul 8, 2024
1 parent 8080646 commit ce3e245
Show file tree
Hide file tree
Showing 3 changed files with 156 additions and 42 deletions.
89 changes: 47 additions & 42 deletions app/Views/collectionHelp.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@

<?= @$body ?>

<?php if ($meta->collection !== 'components') { ?>
<h2><?= __('Creating') ?></h2>
<p>An entry can be created using the web interface if the current user logged in has a role that contains the <?= $meta->collection ?>::create permission.<br><br>
Go to menu: <?= $menu ?> -> <?= $title ?> -> <a href="<?= url_to($meta->collection . 'CreateForm') ?>">Create <?= $title ?></a>. Also can be created from the Attributes View, using the "Create" button.</p>
Expand All @@ -78,49 +79,53 @@
<?php } ?>

<h2><?= __('Database Definition') ?></h2>
<div class="table-responsive">
<table class="table <?= $GLOBALS['table'] ?> table-striped table-hover">
<thead>
<tr>
<td><?= __('Name') ?></td>
<td><?= __('Type') ?></td>
<td><?= __('Default') ?></td>
<td><?= __('Max Length') ?></td>
<td><?= __('Primary Key') ?></td>
<td><?= __('Valid Values') ?></td>
<td class="text-center"><?= __('Required') ?> <span style="color: #dc3545;">*</span></td>
<td><?= __('Description') ?></td>
</tr>
</thead>
<tbody>
<?php foreach ($data[0]->attributes->columns as $column) { ?>
<tr>
<td><?= $column->name ?></td>
<td><?= $column->type ?></td>
<td><?= $column->default ?></td>
<td><?= $column->max_length ?></td>
<td><?= $column->primary_key ?></td>
<td><?php
if (!empty($column->values)) {
(str_replace("','", "', '", $column->values));
} ?></td>
<td class="text-center">
<?php if (in_array($column->name, $dictionary->attributes->create)) { ?>
<span class="fa fa-check text-success"></span>
<div class="table-responsive">
<table class="table <?= $GLOBALS['table'] ?> table-striped table-hover">
<thead>
<tr>
<td><?= __('Name') ?></td>
<td><?= __('Type') ?></td>
<td><?= __('Default') ?></td>
<td><?= __('Max Length') ?></td>
<td><?= __('Primary Key') ?></td>
<td><?= __('Valid Values') ?></td>
<td class="text-center"><?= __('Required') ?> <span style="color: #dc3545;">*</span></td>
<td><?= __('Description') ?></td>
</tr>
</thead>
<tbody>
<?php foreach ($data[0]->attributes->columns as $column) { ?>
<tr>
<td><?= $column->name ?></td>
<td><?= $column->type ?></td>
<td><?= $column->default ?></td>
<td><?= $column->max_length ?></td>
<td><?= $column->primary_key ?></td>
<td><?php
if (!empty($column->values)) {
(str_replace("','", "', '", $column->values));
} ?></td>
<td class="text-center">
<?php if (in_array($column->name, $dictionary->attributes->create)) { ?>
<span class="fa fa-check text-success"></span>
<?php } ?>
</td>
<?php if (!empty($dictionary->columns->{$column->name})) { ?>
<?php if (is_string($dictionary->columns->{$column->name})) { ?>
<td><?= $dictionary->columns->{$column->name} ?></td>
<?php } else { ?>
<td><pre><?= json_encode($dictionary->columns->{$column->name}) ?></td>
<?php } ?>
<?php } else { ?>
<td></td>
<?php } ?>
</tr>
<?php } ?>
</td>
<?php if (is_string($dictionary->columns->{$column->name})) { ?>
<td><?= $dictionary->columns->{$column->name} ?></td>
<?php } else { ?>
<td><pre><?= json_encode($dictionary->columns->{$column->name}) ?></td>
<?php } ?>
</tr>
<?php } ?>
</tbody>
</table>
</div>
<p><br><span style="color: #dc3545;">*</span>&nbsp;<?= __('Note') ?> - <?= __('This column is required by Open-AudIT to create an item of this type') ?></p>

</tbody>
</table>
</div>
<p><br><span style="color: #dc3545;">*</span>&nbsp;<?= __('Note') ?> - <?= __('This column is required by Open-AudIT to create an item of this type') ?></p>
<?php } ?>
</div>
</div>
</div>
Expand Down
64 changes: 64 additions & 0 deletions app/Views/help/components.php
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
<?php
# Copyright © 2023 FirstWave. All Rights Reserved.
# SPDX-License-Identifier: AGPL-3.0-or-later

$intro = "<p>Open-AudIT has a powerful change detection engine. Any device attributes that are added, removed or changed will be detected and stored. These changes can be reported upon and the relevant data confirmed as to what was expected from your company change and release process.<br>
<br>
When a device is audited, attributes are divided into sections which correspond to tables in the database.<br>
<br>
Each device (computer, router, printer, et al) has an entry in the <code>devices</code> table. Each entry in the devices table has an <code>id</code> column. This value is unique - it is an auto-incrementing id.<br>
<br>
When the audit result is processed, each item in each section has its audit result compared to what is in the database.<br>
<br>
For each section, if the key columns (see below table) contain the identical values, it is considered already installed and has its <code>last_seen</code> attribute updated. No change_log entry is created.<br>
<br>
If any of the key columns do not match, it is considered a new attribute and is inserted. A <code>change_log</code> entry is created if the device had other attributes already present in the table.<br>
<br>
At the completion of the audit processing, any database items that have not been updated (or inserted) are considered to not be present. The <code>current</code> attribute for this item is set to 'n' and a change_log entry is generated.<br>
<br>
So, we can determine if something is currently installed - the current column is 'y'.<br>
<br>
We can determine when something was initially detected - the 'first_seen'.<br>
<br>
We can determine if something was installed after the initial audit - first seen will be different in the component and device tables.<br>
<br>
We can determine if something is not currently installed, but previously was - current = 'n'.<br>
<br>
We can determine the last time we detected an item - last_seen.<br>
<br>
At any given point, we can determine what was on a system - by using the audit_log table and selecting the relevant components based on first_seen and last_seen.<br>
<br>
Each section and its matching key columns are below.<br>
<br>
NOTE - There are some exceptions as detailed below.<br>
<br>
*1 - For network cards, if the computer is a VMware Esx machine it also uses the net_index and connection columns.<br>
<br>
*2 - For partitions, f the computer is an AIX machine, we use the partition name.<br></p>";

$components = array('bios', 'certificate', 'disk', 'dns', 'executable', 'file', 'log', 'memory', 'module', 'monitor', 'motherboard', 'netstat', 'network', 'nmap', 'ip', 'optical', 'pagefile', 'partition', 'policy', 'print_queue', 'processor', 'radio', 'route', 'san', 'scsi', 'server', 'server_item', 'service', 'share', 'software', 'software_key', 'sound', 'task', 'usb', 'user', 'user_group', 'variable', 'video', 'vm', 'windows');
$table = '';
foreach ($components as $component) {
$table .= '<tr><td><strong>' . $component . '</strong></td>';
$columns = match_columns($component);
foreach ($columns as $column) {
$table .= '<td>' . $column . '</td>';
}
$table .= "</tr>\n";
}

$body = '<br><br><table class="table">
<thead>
<tr>
<th>Table</th>
<th>Attribute #1</th>
<th>Attribute #2</th>
<th>Attribute #3</th>
<th>Attribute #4</th>
<th>Attribute #5</th>
</tr>
</thead>
<tbody>' . $table . '
</tbody>
</table>
<br>';
45 changes: 45 additions & 0 deletions app/Views/help/devices.php
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
<?php
# Copyright © 2023 FirstWave. All Rights Reserved.
# SPDX-License-Identifier: AGPL-3.0-or-later

$intro = '<p>Devices and their configuration are what Open-AudIT is all about.</p>
<br>
<h2>Match Process</h2>
<p>When Open-AudIT receives data about a device, either by discovering the device during an audit run or by the user importing the device, it must determine if this discovered device matches a device that already exists within its database, or if it is a new device that should be added. Open-AudIT uses a series of twelve property matches to determine this. The Match Rules work as OR comparisons, not AND. This means the first rule that matches a field in the discovered device to one in the dB resolves as an existing device. All Matching Rules have to fail in order for a device to be new and result in a new record being created.</p>
<br>
<h2>Duplicate Devices / Missing Devices</h2>
<p>It is important to note that when Open-AudIT determines a match any properties set to \'y\' must match exactly (and not be blank) in order for Open-AudIT to determine that the discovered device matches a device already in the database. If none of the properties marked \'y\' match, then a new device entry will be created, which could result in duplicate device entries. In situations where properties are duplicated, for example a dbus_id is copied during a VM clone, then an existing device may incorrectly get overwritten/updated rather then a new entry being created resulting in missing devices.</p>
<br>
<p>Devices will not be matched if their status is set to "deleted". Any other status will allow a match to occur.</p>
<br>
<h2>Matching Linux Devices</h2>
<p>When matching a Linux based device, we prefer to use the Dbus id concatenated with the hostname. We can also use other options as per the below table, but we can retrieve the Dbus ID without root. To retrieve the UUID (from the motherboard), we need to run dmidecode, which does require root. Unfortunately, when you clone an ESXi guest, the Dbus ID does not get recreated - hence our concatenating this with the hostname. There is a good article linked here that details the why\'s of hardware IDs. <a href="http://0pointer.de/blog/projects/ids.html">http://0pointer.de/blog/projects/ids.html</a>.</p>
<br>
<h2>Match Order</h2>
<p>The logic for device matching is contained in the devices_helper.php file, which on a Linux install can be found here: /usr/local/open-audit/app/Helpers<br>
<br>
Matching is conducted in the following order:<br>
<ol>
<li>Match the Opmantek UUID (not configurable)</li>
<li>Match the Google Cloud ID (not configurable)</li>
<li>match_hostname_uuid</li>
<li>match_hostname_dbus</li>
<li>match_hostname_serial</li>
<li>match_dbus</li>
<li>match_dns_fqdn</li>
<li>match_dns_hostname</li>
<li>match_fqdn</li>
<li>match_serial_type</li>
<li>match_serial</li>
<li>match_sysname_serial</li>
<li>match_sysname</li>
<li>match_mac (ip table)</li>
<li>match_mac (network table)</li>
<li>match_mac (addresses)</li>
<li>match_ip</li>
<li>match_hostname</li>
<li>match_ip_no_data</li>
</ol></p>
';

$body = '<br>';

0 comments on commit ce3e245

Please sign in to comment.