Skip to content

Commit

Permalink
Documentation improvements.
Browse files Browse the repository at this point in the history
  • Loading branch information
@mark-unwin
mark-unwin committed Jul 17, 2024
1 parent 1498751 commit 632c9ab
Show file tree
Hide file tree
Showing 43 changed files with 770 additions and 160 deletions.
2 changes: 1 addition & 1 deletion app/Controllers/Help.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -152,7 +152,7 @@ public function faq()
{
#$request = \Config\Services::request();
$name = $this->request->getGet('name');
$valid_names = array('Creating a Query', 'Running Open-AudIT Apache Service Under Windows', 'Google Maps API Key');
$valid_names = array('Bulk Editing Device Attributes', 'Creating a Query', 'Credentials for Amazon AWS used in Cloud Discovery', 'Credentials for Microsoft Azure used in Cloud Discovery', 'FAQ', 'Google Maps API Key', 'Running Open-AudIT Apache Service Under Windows', 'Troubleshooting LDAP Logins');
if (!in_array($name, $valid_names)) {
redirect('home');
}
Expand Down
2 changes: 1 addition & 1 deletion app/Models/CloudsModel.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -408,7 +408,7 @@ public function dictionary(): object

$dictionary->sentence = 'Open-AudIT can discover and audit your cloud-based virtual machines. You provide the credentials and Open-AudIT will query the Amazon or Microsoft APIs to determine what devices you have, their state, any associated networks and locations and then run discovery upon each cloud instance. You get all the regular Open-AudIT details, but now you also get cloud-specific details like size.';

$dictionary->about = '<p>This endpoint enables you to add your cloud infrastructure details. Open-AudIT will then reach out to your clouds using their native API and return your servers, just like any other device in Open-AudIT.<br /><br /><em>NOTE</em> - To use this feature, we <em>must</em> enable the configuration items match_mac (for AWS) and match_hostname (for Azure). This will be done automatically the first time a cloud discovery is executed.<br /><br />' . $instance->dictionary->link . '<br /><br /></p>';
$dictionary->about = '<p>This endpoint enables you to add your cloud infrastructure details. Open-AudIT will then reach out to your clouds using their native API and return your servers, just like any other device in Open-AudIT.<br /><br /><em>NOTE</em> - To use this feature, we <em>must</em> enable the configuration items match_mac (for AWS) and match_hostname (for Azure). This will be done automatically the first time a cloud discovery is executed.<br /><br />' . $instance->dictionary->link . '<br /><br />Credentials for your cloud (<a href="' . url_to('helpFAQ') . '?name=Credentials for Microsoft Azure used in Cloud Discovery">Azure</a> or <a href="' . url_to('helpFAQ') . '?name=Credentials for Amazon AWS used in Cloud Discovery">AWS</a>) are required.<br><br></p>';

$dictionary->notes = "<p>If you intend to completely audit your cloud machines, don't forget you will also need those credentials saved in Open-AudIT.</p><p>Make sure you allow the correct ports if you are using Microsoft Azure (22 for SSH, etc). Check your Virtual Machine -> Networking rules.<br /><br /></p>";

Expand Down
12 changes: 7 additions & 5 deletions app/Views/collectionHelp.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -54,8 +54,12 @@

<?php if ($meta->collection !== 'components') { ?>
<h2><?= __('Creating') ?></h2>
<?php if ($meta->collection !== 'collectors') { ?>
<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>
<?php } else { ?>
<p>You can turn any server into a collector by going to menu -> Admin -> Collectors -> Make this install a Collector. You will need credentials to log on to the server this install will report in to.<br></p>
<?php } ?>
<br>
<?php if ($execute) { ?>
<h2><?= __('Executing') ?></h2>
Expand All @@ -77,7 +81,7 @@
<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 } ?>

<?php if ($meta->collection !== 'reports') { ?>
<h2><?= __('Database Definition') ?></h2>
<div class="table-responsive">
<table class="table <?= $GLOBALS['table'] ?> table-striped table-hover">
Expand Down Expand Up @@ -126,6 +130,7 @@
</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 } ?>
<?php } ?>
</div>
</div>
</div>
Expand All @@ -136,11 +141,8 @@
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-body">
<p><img class="helpImage" src="<?= base_url() . '/images/' . $meta->collection ?>.png"></p>
<p><img class="helpImage" src="<?= base_url() . 'images/' . $meta->collection ?>.png"></p>
</div>
</div>
</div>
</div>



2 changes: 1 addition & 1 deletion app/Views/errors/html/production.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@

<!-- <p class="lead"><?= lang('Errors.weHitASnag') ?></p> -->

<p class="lead">Please <a href="mailto:support@opmantek.com">email</a> the file <?= $logfile ?> and (if you can access) the result of the <a href="<?= $meta->baseurl ?>index.php/support?format=json_data" target="_blank">Support Output<a> along with a description of what you were doing at the time of this error to FirstWave.</p>
<p class="lead">Please <a href="mailto:support@firstwave.com">email</a> the file <?= $logfile ?> and (if you can access) the result of the <a href="<?= base_url() ?>support?format=json_data" target="_blank">Support Output<a> along with a description of what you were doing at the time of this error to FirstWave.</p>

</div>

Expand Down
45 changes: 45 additions & 0 deletions app/Views/faq/Bulk Editing Device Attributes.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

$title = __('Bulk Editing Device Attributes');

$intro = '<p>Open-AudIT makes it easy to edit the attributes of multiple devices at once.<br>
<br>
The steps below outline the process.<br>
<br>
View the <a href="' . url_to('devicesCollection') . '">devices</a> list.<br>
<br>
You will need a <a href="' . url_to('rolesCollection') . '">role</a> with Devices update permission.<br>
<br>
You can select individual devices by clicking their check-boxes on the right side or selecting all devices clicking the checkbox on the top right of the table (underneath the Edit button that looks like a pencil).<br>
<br>
Once you have chosen your devices to edit, click the pencil button on the top right of the table.
</p>
<br>
<img src="' . base_url() . 'images/faq_05.png" alt="Devices Collection" style="width:50%;">
';

$body = '<p><br><br>This will show you the Bulk Edit form. Any attributes you set on this form will be applied to all selected devices. You can set multiple attributes at once.</p>
<br>
<img src="' . base_url() . 'images/faq_06.png" alt="Bulk Edit Form" style="width:50%;">
<p>
<br>
Click the icon to the right of the field you wish to edit. Change the field and click the green icon to submit.<br>
<br>
You can also see at the bottom of the page a table showing the devices the changes will be applied to.<br>
<br>
That\'s it! You have just edited the attributes of as many devices as you need to.<br>
<br>
There is absolutely no need to manually edit each individual device.<br>
<br>
<strong>NOTE</strong>: Bulk edit selections won\'t stay selected after clicking next page.<br>
<br>
If this occurs then the issue you\'re seeing is related to the table control being used on the webpage. It only stores in memory the state of the check boxes for the current page being viewed. If you make selections, then page forward/back those selections will be lost. You can, however, accomplish what you want by expanding the number of devices shown on each page. In the top-left corner is a drop-down labeled “records per page”; use this to expand the number of entries displayed until you see all you want to select for Bulk Edit.<br></p>
<img src="' . base_url() . 'images/faq_07.png" alt="Select All Devices" style="width:20%;">
';
25 changes: 25 additions & 0 deletions app/Views/faq/Credentials for Amazon AWS used in Cloud Discovery.php
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
<?php
# Copyright © 2023 FirstWave. All Rights Reserved.
# SPDX-License-Identifier: AGPL-3.0-or-later

$title = __('Credentials for Amazon AWS used in Cloud Discovery');

$intro = '<p>When you are using Clouds to discover your Amazon AWS instances, you will need two credential items - key and secret key.
Your key should already be known to you and your secret key as well. Of note is that you cannot retrieve your secret key using the AWS Console provided by Amazon. If you have misplaced it, you will need to generate a new one.<br>
<br>
</p>
<h2>Retrieving or Creating</h2>
<p>To retrieve your key, log in to the AWS Console and select your username, then My Security Credentials.<br><br></p>
<img src="' . base_url() . 'images/faq_09.png" alt="AWS Credentials">
<p><br>On the next page you will be able to select Access Keys and see your key or create a new key.<br><br></p>
<img src="' . base_url() . 'images/faq_10.png" alt="AWS Credentials">
<p><br><br></p>
<h2>Required AWS user permissions</h2>
<p>The only required permission / policy name (in our testing) is AmazonEC2ReadOnlyAccess.</p>
<h2>Using</h2>
<p>Once you have those items, in Open-AudIT Enterprise you can go to menu -> Discover -> Clouds -> Create Clouds, select the "Amazon AWS" type and paste them in. Done.<br><br></p>
<img src="' . base_url() . 'images/faq_11.png" alt="AWS Credentials">
';

$body = '';
53 changes: 53 additions & 0 deletions app/Views/faq/Credentials for Microsoft Azure used in Cloud Discovery.php
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
<?php
# Copyright © 2023 FirstWave. All Rights Reserved.
# SPDX-License-Identifier: AGPL-3.0-or-later

$title = __('Credentials for Microsoft Azure used in Cloud Discovery');

$intro = '<p>When you are using Clouds to discover your Microsoft Azure instances, you will need four credential items - subscription id, tenant id, client id and client secret.<br><br></p>
<h2>Retrieving or Creating</h2>
<p>In order to use the Azure Rest API, you will need to create an Azure Active Directory Application that is used for authentication.<br></p>
<h2>Tenant ID</h2>
<p>To retrieve the Tenant ID. Open the Azure portal click on Azure Active Directory, Properties and the Tenant ID is displayed as your Directory ID (don\'t blame me for the name mismatch, that\'s how Microsoft roll!).<br></p>
<img src="' . base_url() . 'images/faq_13.png" alt="Azure Credentials">
<p>&nbsp;<br></p>
<img src="' . base_url() . 'images/faq_14.png" alt="Azure Credentials">
<p>&nbsp;<br></p>
<h2>Client ID and Secret</h2>
<p>The client ID is the ID of an Azure Active Directory application. The client secret is the key that you give that application.<br>
<br>
Click on App Registrations to create a new Application, then click New Application Registration. Give it a name (I used Open-AudIT), select Web app / API as the type and provide any URL (the URL is not important) and now click Create.<br><br></p>
<img src="' . base_url() . 'images/faq_15.png" alt="Azure Credentials">
<p>&nbsp;<br></p>
<img src="' . base_url() . 'images/faq_16.png" alt="Azure Credentials">
<p>&nbsp;<br></p>
<p>Click on the application you just created. The Application ID displayed is the Client ID.<br>
<br>
To create the client secret, click Settings, then Keys. Provide a key name and select an appropriate expiry date, then click Save.<br>
<br>
The value will be populated for you - this is the Client Secret.<br><br></p>
<img src="' . base_url() . 'images/faq_17.png" alt="Azure Credentials">
<p>&nbsp;<br></p>
<img src="' . base_url() . 'images/faq_18.png" alt="Azure Credentials">
<p>&nbsp;<br></p>
<p>Now we need to provide the Azure Active Directory application access to your subscription.<br>
<br>
Click on Resource Groups and then the resource group you would like your Azure Active Directory Application to have access to.<br>
<br>
Click Add. The role should be Contributor and then search for the app (Open-AudIT). Then click Save.<br>
<br>
Now the application has access to the subscription, so we can make API calls. The API calls will be requested on behalf of the application, not your user.<br><br></p>
<img src="' . base_url() . 'images/faq_19.png" alt="Azure Credentials">
<p>&nbsp;<br></p>
<h2>Subscription ID</h2>
<p>Now for the Subscription ID, click All Services, Subscriptions and copy it.<br><br></p>
<img src="' . base_url() . 'images/faq_20.png" alt="Azure Credentials">
<p>&nbsp;<br></p>
<img src="' . base_url() . 'images/faq_21.png" alt="Azure Credentials">
<p>&nbsp;<br></p>
<h2>Using</h2>
<p>Once you have those items, in Open-AudIT Enterprise you can go to menu -> Discover -> Clouds -> Create Clouds, select the "Microsoft Azure" type and paste them in. Done.<br><br></p>
<img src="' . base_url() . 'images/faq_12.png" alt="Azure Credentials">
';

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

$title = __('Help and Frequently Asked Questions');

$intro = '<p>
<a href="' . url_to('helpFAQ') . '?name=Bulk Editing Device Attributes">Bulk Editing Device Attributes</a><br>
<a href="' . url_to('helpFAQ') . '?name=Creating a Query">Creating a Query</a><br>
<a href="' . url_to('helpFAQ') . '?name=Credentials for Amazon AWS used in Cloud Discovery">Credentials for Amazon AWS used in Cloud Discovery</a><br>
<a href="' . url_to('helpFAQ') . '?name=Credentials for Microsoft Azure used in Cloud Discovery">Credentials for Microsoft Azure used in Cloud Discovery</a><br>
<a href="' . url_to('helpFAQ') . '?name=Google Maps API Key">Google Maps API Key</a><br>
<a href="' . url_to('helpFAQ') . '?name=Running Open-AudIT Apache Service Under Windows">Running Open-AudIT Apache Service Under Windows</a><br>
<a href="' . url_to('helpFAQ') . '?name=Troubleshooting LDAP Logins">Troubleshooting LDAP Logins</a><br>
<br>
<h2>Opening a Support Ticket?</h2>
<p>If you are a supported customer and open a support ticket with FirstWave, please attach these files.<br>
<br>
<strong>Install Support</strong>: It is available at Menu -> Help -> <a href="' . url_to('supportCollection') . '">Support</a>. This is to be used as the first point of call when troubleshooting Open-AudIT issues. You can click the Export button on the top right to retrieve this as a JSON file (to be added to the support ticket / email.<br>
<br>
<strong>Discovery Support</strong>: When investigating a Discovery, support will request the Exported Discovery Logs. To retrieve these, go to menu -> Discoveries -> <a href="' . url_to('discoveriesCollection') . '">List Discoveries</a>. View the discovery in question, then click the Support button in the top right toolbar. This will provide the discovery settings, config items, the discovery device list as well as the logs for this particular discovery.<br><br></p>
<h2>My AntiVirus is prompting me to deny/allow things</h2>
<p>If you have Anti-Virus software running, allowing the services of Opmantek (omkd), Apache (apache2.2) and MySQL (mysql) to auto start and run is essential. These services are used by Open-AudIT. You should only need to do this once. If your Anti-Virus program keeps prompting you about Open-AudIT, please post to the forums or send an email to support with the name and version of your Anti-Virus software.<br><br></p>
<h2>Discovery has stopped working</h2>
<p>If you are running a RedHat or Centos system and you have upgraded Nmap, please reset the SUID on the binary by:<br>
<pre>chmod u+s /usr/bin/nmap</pre><br><br></p>
<h2>My time is off in Open-AudIT</h2>
<p>This is likely due to MySQL time being off. MySQL typically uses the host devices time. You can check this by:<br>
<strong>Linux</strong><br>
<code>mysql -u openaudit -popenauditpassword -e "SELECT NOW() as `timestamp`;"</code><br>
<strong>Windows</strong><br>
<code>c:\xampp\mysql\bin\mysql.exe -u openaudit -popenauditpassword -e "SELECT NOW() as `timestamp`;"</code><br>
<br></p>
<h2>I cannot start the Apache service on Windows</h2>
<p>Have you checked that another program is not already using port 80? If you start a command prompt as an Administrator and type:<br>
<code>netstat -abn</code><br>
You should get an output similar to:<br></p>
<pre>C:\>netstat -abnp tcp
Active Connections
Proto Local Address Foreign Address State
TCP 0.0.0.0:80 0.0.0.0:0 LISTENING
[httpd.exe]
TCP 0.0.0.0:135 0.0.0.0:0 LISTENING
RpcSs
[svchost.exe]</pre>
<p>Look for a program using port 80. In this case, note the output <br></p>
<pre>TCP 0.0.0.0:80 0.0.0.0:0 LISTENING
[httpd.exe]</pre>
<br>
<p>
That indicates port 80 is being used by the executable httpd.exe (in this case, Apache). You should not see any entries using :80. If there is another program using port 80 either stop and remove it, change it\'s port (if possible) or install Open-AudIT on another machine.<br>
<br>
Skype uses port 80 by default. If it gets in first it prevents Apache using port 80. Completely exit Skype (on a Windows 7 machine you need to go to the taskbar and right click/quit the Skype icon) and then start the Apache service. You can then restart Skype and it will use another port. Alternatively force Skype to not use port 80 and 443: In Skype | options | advanced | connection untick the "use port 80 and 443 as alternatives for incoming connections". This should also solve the problem.<br><br>
</p>
<h2>I Still cannot start the Apache service on Windows</h2>
<p>You may need to download and install the MS Visual C++ redistributable. You can find it here <a href="https://support.microsoft.com/en-au/help/2977003/the-latest-supported-visual-c-downloads">https://support.microsoft.com/en-au/help/2977003/the-latest-supported-visual-c-downloads</a><br><br></p>
';

$body = '';
Loading

0 comments on commit 632c9ab

Please sign in to comment.