Skip to content

Commit

Permalink
Provide better 'About' pages based on the wiki contents.
Browse files Browse the repository at this point in the history
  • Loading branch information
@mark-unwin
mark-unwin committed Feb 13, 2024
1 parent f23715b commit fb317a8
Show file tree
Hide file tree
Showing 73 changed files with 1,750 additions and 11 deletions.
1 change: 1 addition & 0 deletions app/Config/Routes.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,7 @@
$routes->post('graph/reset', 'Collections::reset', ['filter' => \App\Filters\Session::class, 'as' => 'graphReset']);

$routes->get('about', 'Help::about', ['filter' => \App\Filters\Session::class, 'as' => 'about']);
$routes->get('api', 'Help::api', ['filter' => \App\Filters\Session::class, 'as' => 'api']);
$routes->get('help', 'Help::about', ['filter' => \App\Filters\Session::class, 'as' => 'helpCollection']);
$routes->get('features', 'Help::features', ['filter' => \App\Filters\Session::class, 'as' => 'features']);
$routes->get('prereq', 'Help::prereq', ['filter' => \App\Filters\Session::class, 'as' => 'prereq']);
Expand Down
7 changes: 6 additions & 1 deletion app/Controllers/Collections.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -365,6 +365,11 @@ public function dictionary($model)
*/
public function help()
{
$this->baseModel = model('App\Models\BaseModel');
$defaults = $this->baseModel->tableDefaults($this->resp->meta->collection);
$this->databaseModel = model('App\Models\DatabaseModel');
$data = $this->databaseModel->read($this->resp->meta->collection);

$dictionary = $this->{$this->resp->meta->collection.'Model'}->dictionary();
return view('shared/header', [
'config' => $this->config,
Expand All @@ -375,7 +380,7 @@ public function help()
'queries' => filter_response($this->queriesUser),
'roles' => filter_response($this->roles),
'user' => filter_response($this->user)]) .
view('collectionHelp', ['data' => $dictionary])
view('collectionHelp', ['data' => $data, 'dictionary' => $dictionary, 'defaults' => $defaults])
. view('shared/footer', ['license_string' => $this->resp->meta->license_string]);
}

Expand Down
20 changes: 20 additions & 0 deletions app/Controllers/Help.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,26 @@ public function about()
. view('shared/footer', ['license_string' => $this->resp->meta->license_string]);
}

/**
* The API documentation page
*
* @access public
* @return NULL
*/
public function api()
{
return view('shared/header', [
'config' => $this->config,
'dashboards' => filter_response($this->dashboards),
'meta' => filter_response($this->resp->meta),
'orgs' => filter_response($this->orgsUser),
'queries' => filter_response($this->queriesUser),
'roles' => filter_response($this->roles),
'user' => filter_response($this->user)]) .
view('helpApi', [])
. view('shared/footer', ['license_string' => $this->resp->meta->license_string]);
}

/**
* The Welcome page
*
Expand Down
1 change: 1 addition & 0 deletions app/Models/QueriesModel.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -366,6 +366,7 @@ public function dictionary(): object
$dictionary->columns->description = $instance->dictionary->description;
$dictionary->columns->sql = 'Your SQL to select attributes that will populate this query.';
$dictionary->columns->link = 'Unused.';
$dictionary->columns->advanced = 'Don\'t hold my hand, I know what I\'m doing. No filter and the ability to join custom tables.';
$dictionary->columns->menu_display = 'Should we expose this query in the list of reports under the Report menu in the web interface.';
$dictionary->columns->menu_category = 'Which sub-menu should we display this query in.';
$dictionary->columns->edited_by = $instance->dictionary->edited_by;
Expand Down
127 changes: 118 additions & 9 deletions app/Views/collectionHelp.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,26 +2,135 @@
# Copyright © 2023 FirstWave. All Rights Reserved.
# SPDX-License-Identifier: AGPL-3.0-or-later
include 'shared/collection_functions.php';
@include 'help/'. $meta->collection . '.php';
$title = ucwords(str_replace('_', ' ', $meta->collection));
$menu = 'Manage';
if (in_array($meta->collection, ['clouds','credentials','discoveries','files','scripts'])) {
$menu = 'Discover';
}
if ($meta->collection === 'discovery_scan_options') {
$menu = 'Discover -> Discoveries';
}
$defaults = false;
if (in_array($meta->collection, ['attributes', 'configuration', 'dashboards', 'discovery_scan_options', 'fields', 'groups', 'integrations', 'locations', 'orgs', 'queries', 'roles', 'rules', 'scripts', 'summaries', 'users', 'widgets'])) {
$defaults = true;
}
$execute = false;
if (in_array($meta->collection, ['dashboards', 'discoveries', 'groups', 'integrations', 'queries', 'summaries'])) {
$execute = true;
}
?>
<main class="container-fluid">
<div class="card">
<div class="card-header">
<?= collection_card_header($meta->collection, $meta->icon, $user, 'About ' . ucwords(str_replace('_', ' ', $meta->collection))); ?>
<?= collection_card_header($meta->collection, $meta->icon, $user, 'About ' . $title); ?>
</div>
<div class="card-body text-center">
<div class="card-body">
<div class="row">
<div class="col-8 offset-2 text-center">
<h1><?= ucwords(str_replace('_', ' ', $meta->collection)) ?></h1>
<div class="col-8 offset-2">
<h2><?= __('Introduction') ?></h2>
<br />
<div class="row">
<div class="col-8">
<?= @$intro ?>
</div>
<div class="col-4 text-center">
<?php
if (!empty($config->enterprise_collections[$meta->collection])) { ?>
<button class="btn btn-success"><?= __('Open-AudIT Enterprise') ?></button>
<?php } else if (!empty($config->professional_collections[$meta->collection])) { ?>
<button class="btn btn-primary"><?= __('Open-AudIT Professional') ?></button>
<?php } else { ?>
<button class="btn btn-warning"><?= __('Open-AudIT Community') ?></button>
<?php } ?>
<br /><br />
<img class="img-fluid helpImage" src="<?= base_url() . '/images/' . $meta->collection ?>.png" data-bs-toggle="modal" data-bs-target="#exampleModal">
</div>
</div>

<?= @$body ?>

<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>
<br>
<?= $dictionary->about ?>
</div>
<?php if ($execute) { ?>
<h2><?= __('Executing') ?></h2>
<p><?= $title ?> have the ability to be executed. On the <?= $title ?> collections and details pages is an icon to execute.</p>
<br>
<?php } ?>
<h2><?= __('View Details') ?></h2>
<p>Go to menu: <?= $menu ?> -> <?= $title ?> -> <a href="<?= url_to($meta->collection . 'Collection') ?>">List <?= $title ?></a>.<br><br />
You will see a list of <?= $meta->collection ?>. You can view by clicking on the blue view icon. You can also edit or delete if you have permissions.</p>
<br>
<h2><?= __('Database Schema') ?></h2>
<p>The database schema can be found in the application if the user has database::read permission by going to menu: Admin -> Database -> <a href="<?= url_to('databaseCollection') ?>">List Tables</a>, then clicking on the details button for the table.</p>
<br>
<h2><?= __('API / Web Access') ?></h2>
<p>You can access the collection using the normal Open-AudIT JSON based API. Just like any other collection. Please see <a href="<?= url_to('api') ?>">The Open-AudIT API</a> documentation for further details.</p>
<br>
<?php if ($defaults) { ?>
<h2><?= __('Default Items') ?></h2>
<p>Shipped are a set of default items. These can be found by going to menu: Help → Defaults → <a href="<?= url_to($meta->collection . 'Defaults') ?>"><?= $title ?></a>.</p>
<br>
<?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><?= @(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 (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>

<div class="row">
<div class="col-8 offset-2 text-center">
<img class="img-fluid" src="<?= base_url() . '/images/' . $meta->collection ?>.png" alt="<?= $meta->collection ?>">
</div>
</div>
</div>
</div>
</main>

<div class="modal fade modal-xl" id="exampleModal" tabindex="-1">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-body">
<p><img class="helpImage" src="<?= base_url() . '/images/' . $meta->collection ?>.png"></p>
</div>
</div>
</div>
</div>



12 changes: 12 additions & 0 deletions app/Views/help/applications.php
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
<?php
# Copyright © 2023 FirstWave. All Rights Reserved.
# SPDX-License-Identifier: AGPL-3.0-or-later

$intro = '<p>The Applications endpoint allows you to define an application which you can then associate to a device (or devices).<br><br>
Applications are an Enterprise only feature.<br><br>
Applications are being introduced in Open-AudIT 2.2 with a view to expand on the concept as further development is made.</p>
<br>
<h2>How Does it Work?</h2>
<p>You can define an application and associate a device to this application. A device may be associated to more than one application. An application may be associated to more than one device.</p>';

$body = '<br>';
23 changes: 23 additions & 0 deletions app/Views/help/attributes.php
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
<?php
# Copyright © 2023 FirstWave. All Rights Reserved.
# SPDX-License-Identifier: AGPL-3.0-or-later

$intro = '<p>The Attributes endpoint allows you to add customized values to different attributes in Open-AudIT, at the moment this feature works on the Class, Environment, Status and Type attributes on Devices, the Type attribute for both Locations and Orgs as well as the Menu Category for Queries. If you view an item of one of the prvious types (say view a Lkocation) you will notice the Type attribute must be selected from a drop-down box. This is where those values are stored. Hence, if you would like to add a new Type to be chosen for a Location, add it using the Attributes feature.</p>
<br>
<h2>How Does it Work?</h2>
<p>Attributes are stored for Open-AudIT to use for particular fields, at present all fields are based on the devices, locations, orgs and queries tables. The attributes you can edit are associated with the following columns: Class, Environment, Status & Type.</p>';

$body = '<h2>Notes</h2>
<br>
If you add a device type, to display the associated icon you will have to manually copy the .svg formatted file to the directory:<br>
<pre>
Linux: /usr/local/open-audit/www/open-audit/device_images
Windows: c:\xampp\htdocs\open-audit\device_images
</pre>
<br>
If you add a Location Type, add those icons to:<br>
<pre>
Linux: /usr/local/open-audit/public/images/map_icons
Windows: c:\xampp\htdocs\open-audit\images\map_icons
</pre>
<br>';
27 changes: 27 additions & 0 deletions app/Views/help/baselines.php
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
<?php
# Copyright © 2023 FirstWave. All Rights Reserved.
# SPDX-License-Identifier: AGPL-3.0-or-later

$intro = '<p>Being able to determine which machines are configured in the same way is a major part of systems administration and auditing – and now reporting on that will be made simple and automated. Once you define your baseline it will automatically run against a set of devices on a predetermined schedule. The output of these executed baselines will be available for web viewing, importing into a third party system or even as a printed report.</p>
<br>
<h2>How Does it Work?</h2>
<p>Baselines enable you to combine audit data with a set of attributes you have previously defined (your baseline) to determine compliance of devices.
<br><br>
For example - you might create a baseline from a device running Centos 6 which acts as one of your Apache servers in a cluster. You know this particular server is configured just the way you want it but you\'re unsure if other servers in the cluster are configured exactly the same. Baselines enables you to determine this.
<br><br>
You can create a baseline, run it against a group of devices and view the results, add scheduled execution, add more tables for comparison (currently only software, netstat ports and users are enabled), in place baseline editing, archiving of results and more.
<br><br>
WARNING - When creating a baseline using software policies, at present Centos and RedHat package the kernel using the names \'kernel\' and \'kernel-devel\'. There can be multiple packages with this name and different versions concurrently installed. Debian based distributions use names like \'linux-image-3.13.0-24-generic\', note the version number is included in the package name. Because RedHat based OS\'s use this format and subsequently have multiple identical package names with different versions we currently exclude \'kernel\' and \'kernel-devel\' from software policies. This may be addressed in a future update.</p>';

$body = '<h2>Notes</h2>
Baselines can compare netstat ports, users and software.<br><br>
<h5>Software</h5>
<p>To compare software we check the name and version. Because version numbers are not all standardised in format, when we receive an audit result we create a new attribute called software_padded which we store in the database along with the rest of the software details for each package. For this reason, baselines using software policies will not work when run against a device that has not been audited by 1.10 (at least). Software policies can test against the version being "equal to", "greater than" or "equal to or greater than".</p>
<br/>
<h5>Netstat Ports</h5>
<p>Netstat Ports use a combination of port number, protocol and program. If all are present the policy passes.</p>
<br>
<h5>Users</h5>
<p>Users work similar to Netstat Ports. If a user exists with a matching name, status and password details (changeable, expires, required) then the policy passes.</p>
<br>';
Loading

0 comments on commit fb317a8

Please sign in to comment.