diff --git a/docs/projects/ansible/collection/phpipam_scan_agent/index.md b/docs/projects/ansible/collection/phpipam_scan_agent/index.md index 8a84a18..92a4672 100644 --- a/docs/projects/ansible/collection/phpipam_scan_agent/index.md +++ b/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) diff --git a/docs/projects/ansible/collection/phpipam_scan_agent/scanner.md b/docs/projects/ansible/collection/phpipam_scan_agent/scanner.md index 7a0cb33..12e1063 100644 --- a/docs/projects/ansible/collection/phpipam_scan_agent/scanner.md +++ b/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. diff --git a/docs/projects/ansible/collection/phpipam_scan_agent/server.md b/docs/projects/ansible/collection/phpipam_scan_agent/server.md index 53de719..4895414 100644 --- a/docs/projects/ansible/collection/phpipam_scan_agent/server.md +++ b/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. diff --git a/extensions/eda/rulebooks/agent_receive.yml b/extensions/eda/rulebooks/agent_receive.yml index 35aac33..3bd8b82 100644 --- a/extensions/eda/rulebooks/agent_receive.yml +++ b/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: diff --git a/includes/etc/phpipam/scan_agent.yaml b/includes/etc/phpipam/scan_agent.yaml index 3591368..10bd32c 100644 --- a/includes/etc/phpipam/scan_agent.yaml +++ b/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. diff --git a/includes/etc/phpipam/scan_server.yaml b/includes/etc/phpipam/scan_server.yaml index e8176b6..ccdcc30 100644 --- a/includes/etc/phpipam/scan_server.yaml +++ b/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. \ No newline at end of file diff --git a/playbooks/tasks/scan_subnet.yaml b/playbooks/tasks/scan_subnet.yaml index 4602786..a73e3c5 100644 --- a/playbooks/tasks/scan_subnet.yaml +++ b/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) }}/"