feat(server): scanner identity confirmation

!11 #1

docs/projects/ansible/collection/phpipam_scan_agent/index.md

@@ -50,7 +50,7 @@ The following features are available or planned to be implmented:
     !!! info
         It's only possible to obtain a MAC Address if the scanner is on the same L2 network (Broadcast Domain). Within the docs you will find the different methods available to achieve this.
 
-- [**ToDo** Remote Network Scanning](https://gitlab.com/nofusscomputing/projects/ansible/collections/phpipam_scan_agent/-/issues/1)
+- Remote Network Scanning
 
 - [**ToDo** Resolve DNS names](https://gitlab.com/nofusscomputing/projects/ansible/collections/phpipam_scan_agent/-/issues/4)
 

docs/projects/ansible/collection/phpipam_scan_agent/scanner.md

@@ -38,6 +38,7 @@ nofusscomputing_phpipam_scan_agent:
 
   http_port: 5000                    # Optional, Integer. http port to connect to the server.
   http_server: http://127.0.0.1      # Optional, Integer. url with protocol of the Scan Server to connect to.
+  auth_token:                 # Optional, String. The Scan-Agent server authentication token.
 
   cache_expire_time: 1800            # Optional, Integer. Time in seconds to expire the phpIPAM cache.
   epoch_time_offset: 0               # optional, int. Value in seconds to offset the time
@@ -93,3 +94,11 @@ The scanner component has the following workflow:
     1. upload scan report to configured Server.
 
 1. workflow complete.
+
+
+## Remote network Scannning
+
+Once the [server component](server.md#remote%20network%20scannning) has been setup, the client can be installed/used from any network. Even a network that is isolated from the server. Only caveat is that the client can communicate with the server. To ensure that the client can connect to the server set the `auth_token` to match that of the server.
+
+!!! danger "Security"
+    Failing to secure the server component communication with TLS will allow anyone with direct access to the line of communication to view the `auth_token`. Anyone who has the `auth_token` will be able to upload data to the server.

docs/projects/ansible/collection/phpipam_scan_agent/server.md

@@ -37,6 +37,7 @@ nofusscomputing_phpipam_scan_server:
 
   # Server Component Variables
   http_port: 5000     # Optional, Integer. The port for the Server component to listen for connections.
+  auth_token:         # Optional, String. Token used to authentication Agents.
 
 ```
 
@@ -56,3 +57,13 @@ The Server componet has the following workflow:
     - _if no results found, no further processing occurs_
 
 1. Update the phpIPAM MariaDB/MySQL database directly
+
+
+## Remote network Scannning
+
+Remote network scanning is possible with the Scan-Agent. The server must be setup and have connectivity to the phpIPAM MariaDB/MySQL database. Currently the server does not perform secure communication. As such you are strongly encouraged to setup the server component behind a reverse proxy that conducts the TLS termination.
+
+The [scan](scanner.md#remote%20network%20scannning) and server component must be setup with the same `auth_token`. It is this token that provides a means to ensure that what the server is receiving, is from an authorized client.
+
+!!! danger "Security"
+    Failing to secure the server component communication with TLS will allow anyone with direct access to the line of communication to view the `auth_token`. Anyone who has the `auth_token` will be able to upload data to the server.

extensions/eda/rulebooks/agent_receive.yml

@@ -6,6 +6,7 @@
       ansible.eda.webhook:
         host: 0.0.0.0
         port: "{{ nofusscomputing_phpipam_scan_server.http_port | default(5000) | int }}"
+        token: "{{ nofusscomputing_phpipam_scan_server.auth_token | default('no-token-set') }}"
 
   rules:
 

includes/etc/phpipam/scan_agent.yaml

@@ -16,3 +16,5 @@ nofusscomputing_phpipam_scan_agent:
   client_token:                      # Mandatory, String client api token to connect to phpIPAM API [client_token]
   client_name:                       # Mandatory, String. The scanner name as set in phpIPAM interface [client_name]
   scanagent_code:                    # Mandatory, String. Scan Agent Code as set in phpIPAM interface [scanagent_code]
+
+  # auth_token:                        # Optional, String. The Scan-Agent server authentication token.

includes/etc/phpipam/scan_server.yaml

@@ -11,3 +11,5 @@ nofusscomputing_phpipam_scan_server:
 
 # Server Component Variables
 # http_port: 5000     # Optional, Integer. The port for the Server component to listen for connections.
+
+# auth_token:         # Optional, String. Token used to authentication Agents.

playbooks/tasks/scan_subnet.yaml

@@ -67,6 +67,8 @@
 
 - name: Upload Scan Results - {{ subnet.address }}
   ansible.builtin.uri:
+    headers:
+      Authorization: "Bearer {{ nofusscomputing_phpipam_scan_agent.auth_token | default('no-token-set') }}"
     url: "{{
       nofusscomputing_phpipam_scan_agent.http_server | default(nfc_c_http_server)
       }}:{{ nofusscomputing_phpipam_scan_agent.http_port | default(nfc_c_http_port) }}/"