feat(server): DNS Reverse Lookup for IP Address'

!13 closes #4

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

@@ -54,7 +54,7 @@ The following features are available or planned to be implmented:
 
 - Remote Network Scanning
 
-- [**ToDo** Resolve DNS names](https://gitlab.com/nofusscomputing/projects/ansible/collections/phpipam_scan_agent/-/issues/4)
+- [Resolve DNS names](index.md#Resolve-dns-names)
 
 - [Timezone Normalization](server.md#timezone-normalization)
 
@@ -79,6 +79,16 @@ When this setting is enabled, the scanner will scan the entire subnet that has b
 This is displayed within the subnet interface next to the `Discover new hosts` field. Whenever a scan report is received by the server this filed is updated to reflect the last scan time.
 
 
+### Resolve DNS names
+
+- Location `Subnet -> Resolve DNS names`
+
+When this setting is enabled, DNS resolution for the hostname for any IP found will be conducted. If you have setup nameservers (`Administration -> Nameservers`) and assigned them to the subnet, they will be used for name resolution. If no nameservers are configured for the subnet, the host's nameservers where the scanner is running from will be used. BY default within phpIPAM, DNS Resolution is turned off for a subnet and as such the scanner will not resolve IP address DNS names.
+
+!!! info
+    The FQDN for an IP that is retured is not used as the hostname. **Only** the first octet. i.e. if the reverse DNS lookup returns a FQDN of `my_hostname.domainname.tld`, the hostname for the IP address will be set to `my_hostname`
+
+
 ### Scan Agent
 
 - Location `Administration -> Scan agents [Last access]`

playbooks/agent.yaml

@@ -82,3 +82,4 @@
     api_address: addresses
     api_subnets: subnets
     api_scanagents: tools/scanagents
+    api_nameservers: tools/nameservers

playbooks/tasks/scan_subnet.yaml

@@ -1,12 +1,5 @@
 ---
 
-- name: Scan subnet - {{ subnet.address }}
-  ansible.builtin.command:
-    cmd: nmap -sn "{{ subnet.address }}" -oX -
-  become: true
-  register: nmap_scan
-
-
 - name: Get subnets Address'
   ansible.builtin.include_tasks:
     file: tasks/api_call.yaml
@@ -17,15 +10,72 @@
     api_query_string: "filter_by=subnetId&filter_value={{ subnet.id }}"
 
 
-- name: Load Subnet - {{ subnet.address }}
+- name: Register Subnet API Call
   ansible.builtin.set_fact:
-    cached_subnet: "{{ lookup('file', cache_filepath) }}"
+    cacheable: false
+    subnet_api_call: "{{ api_call }}"
+    subnet_cache_filepath: "{{ cache_filepath }}"
+    api_call: ''
+
+
+- name: Get subnet Name Servers
+  ansible.builtin.include_tasks:
+    file: tasks/api_call.yaml
+  vars:
+    api_client_name: "{{ nofusscomputing_phpipam_scan_agent.client_name }}"
+    api_token: "{{ nofusscomputing_phpipam_scan_agent.client_token }}"
+    api_path: "{{ api_nameservers }}"
+    api_query_string: "filter_by=id&filter_value={{ subnet.nameserverId }}"
+  when: >
+    subnet.nameserverId is defined
+      and
+    subnet.resolveDNS | int == 1
+
+
+- name: Load Nameservers - {{ subnet.address }}
+  ansible.builtin.set_fact:
+    subnet_name_servers: "{{ lookup('file', cache_filepath) }}"
     cacheable: false
   no_log: true
   when: >
+    subnet.nameserverId is defined
+      and
+    subnet.resolveDNS | int == 1
+      and
     api_call.status | default(0) | int != 404
 
 
+- name: Scan subnet - {{ subnet.address }}
+  ansible.builtin.command:
+    cmd: >
+      nmap -sn "{{ subnet.address }}" {% if
+        subnet_name_servers is defined
+          and
+        subnet.resolveDNS | int == 1
+      -%}
+      --dns-servers {% for nameserver in subnet_name_servers -%}
+        {% for name_server in nameserver.namesrv1 | split(';') %}
+          {{ name_server }},
+        {%- endfor -%}
+      {%- endfor -%}
+      {%- elif subnet.resolveDNS | int == 1 -%}
+        --system-dns
+      {%- else -%}
+        -n
+      {%- endif %} -oX -
+  become: true
+  register: nmap_scan
+
+
+- name: Load Subnet - {{ subnet.address }}
+  ansible.builtin.set_fact:
+    cached_subnet: "{{ lookup('file', subnet_cache_filepath) }}"
+    cacheable: false
+  no_log: true
+  when: >
+    subnet_api_call.status | default(0) | int != 404
+
+
 - name: Process Scan Results - {{ subnet.address }}
   ansible.builtin.set_fact:
     subnet_scan_results: |-

playbooks/tasks/subnets.yaml

@@ -23,7 +23,9 @@
       ansible.builtin.set_fact:
         nfc_c_scan_agent_subnets: "{{ nfc_c_scan_agent_subnets + [{
             'id': network.id,
-            'address': network.subnet + '/' + network.mask
+            'address': network.subnet + '/' + network.mask,
+            'nameserverId': network.nameserverId,
+            'resolveDNS': network.resolveDNS 
           }] }}"
       loop: "{{ lookup('file', cache_filepath) | default ([]) }}"
       loop_control: