nmap inventory plugin: Add sudo nmap (#4506)

* nmap.py: Add sudo nmap

* Update plugins/inventory/nmap.py

Change description of new plugin option adding version_added

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update plugins/inventory/nmap.py

Change boolean values of sudo option in example

Co-authored-by: Felix Fontein <felix@fontein.de>

* Create 4506-sudo-in-nmap-inv-plugin.yaml

* Fix typo in yaml format

* Update changelogs/fragments/4506-sudo-in-nmap-inv-plugin.yaml

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>

* Update changelogs/fragments/4506-sudo-in-nmap-inv-plugin.yaml

Co-authored-by: Felix Fontein <felix@fontein.de>

* Document default as false.

Co-authored-by: Felix Fontein <felix@fontein.de>
Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>

changelogs/fragments/4506-sudo-in-nmap-inv-plugin.yaml

@@ -0,0 +1,2 @@
+minor_changes:
+- nmap inventory plugin - add ``sudo`` option in plugin in order to execute ``sudo nmap`` so that ``nmap`` runs with elevated privileges (https://github.com/ansible-collections/community.general/pull/4506).

plugins/inventory/nmap.py

@@ -21,6 +21,11 @@ DOCUMENTATION = '''
             description: token that ensures this is a source file for the 'nmap' plugin.
             required: True
             choices: ['nmap', 'community.general.nmap']
+        sudo:
+            description: Set to C(true) to execute a C(sudo nmap) plugin scan.
+            version_added: 4.8.0
+            default: false
+            type: boolean
         address:
             description: Network IP or range of IPs to scan, you can use a simple range (10.2.2.15-25) or CIDR notation.
             required: True
@@ -49,6 +54,13 @@ EXAMPLES = '''
 plugin: community.general.nmap
 strict: False
 address: 192.168.0.0/24
+
+
+# a sudo nmap scan to fully use nmap scan power.
+plugin: community.general.nmap
+sudo: true
+strict: False
+address: 192.168.0.0/24
 '''
 
 import os
@@ -135,6 +147,10 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
         if not user_cache_setting or cache_needs_update:
             # setup command
             cmd = [self._nmap]
+
+            if self._options['sudo']:
+                cmd.insert(0, 'sudo')
+
             if not self._options['ports']:
                 cmd.append('-sP')