### Install python3-nmap and Nmap

Source: https://github.com/nmmapper/python3-nmap/blob/main/README.md

Follow these steps to install the library and its primary dependency, Nmap. Ensure Nmap is installed on your system.

```sh
$ git clone https://github.com/wangoloj/python3-nmap.git

$ pip3 install -r requirements.txt

# Install nmap online

$ apt-get install nmap
```

--------------------------------

### Install python3-nmap

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Install the library using pip or from source. Ensure Nmap is installed on your system.

```bash
pip install python3-nmap
```

```bash
git clone https://github.com/wangoloj/python3-nmap.git
pip3 install -r requirements.txt
```

```bash
apt-get install nmap  # Linux
brew install nmap     # macOS
```

--------------------------------

### Get Nmap Version

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Retrieve the installed Nmap version and build information using the Nmap class.

```python
import nmap3

nmap = nmap3.Nmap()
version_info = nmap.nmap_version()

# Example output:
# {
#     'nmap': (7, 80),
#     'compiled_with': ('liblua-5.3.6', 'openssl-1.1.1f', ...),
#     'compiled_without': ('libpcre', ...),
#     'nsock_engines': ('epoll', 'poll', 'select')
# }
print(version_info)
```

--------------------------------

### Specify Custom Nmap Installation Path

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Allows specifying a custom Nmap installation path if it's not in the system's PATH environment variable. This ensures the library can locate and execute Nmap.

```python
import nmap3

# Specify custom nmap path
nmap = nmap3.Nmap(path="/opt/nmap/bin/nmap")
nmap_techniques = nmap3.NmapScanTechniques(path="/usr/local/bin/nmap")
nmap_discovery = nmap3.NmapHostDiscovery(path="/custom/path/nmap")

results = nmap.scan_top_ports("192.168.1.1")
print(results)
```

--------------------------------

### Nmap Class - nmap_version

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Retrieves the installed Nmap version and build information.

```APIDOC
## GET Nmap Version

### Description
Returns the installed Nmap version and build information.

### Method
GET

### Endpoint
/nmap_version

### Parameters
None

### Request Example
```python
import nmap3

nmap = nmap3.Nmap()
version_info = nmap.nmap_version()
print(version_info)
```

### Response
#### Success Response (200)
- **nmap** (tuple) - Nmap version numbers.
- **compiled_with** (list) - List of libraries Nmap was compiled with.
- **compiled_without** (list) - List of libraries Nmap was compiled without.
- **nsock_engines** (list) - Available nsock engines.

#### Response Example
```json
{
    "nmap": [7, 80],
    "compiled_with": ["liblua-5.3.6", "openssl-1.1.1f"],
    "compiled_without": ["libpcre"],
    "nsock_engines": ["epoll", "poll", "select"]
}
```
```

--------------------------------

### Get Nmap Version Details

Source: https://github.com/nmmapper/python3-nmap/blob/main/README.md

Retrieve detailed version information about the Nmap installation. This function is useful for checking Nmap's capabilities and configuration.

```python
import nmap3
nmap = nmap3.Nmap()
results = nmap.nmap_version()
```

--------------------------------

### Scan Top Ports with Version Detection

Source: https://github.com/nmmapper/python3-nmap/blob/main/README.md

Use this function to scan the top ports of a host and perform version detection. Ensure the nmap3 library is installed.

```python
import nmap3
nmap = nmap3.Nmap()
results = nmap.scan_top_ports("host", args="-sV")
```

--------------------------------

### Identify Vulnerabilities with Vulners Script

Source: https://github.com/nmmapper/python3-nmap/blob/main/README.md

Scan a target IP with version detection and the vulners script to identify CVEs. Requires Nmap to be installed with the vulners script.

```python
import nmap3
nmap = nmap3.Nmap()
results = nmap.nmap_version_detection("host", args="--script vulners --script-args mincvss+5.0")
```

--------------------------------

### Display Nmap Option Summary

Source: https://github.com/nmmapper/python3-nmap/blob/main/docs/nmap.md

Run Nmap without any arguments to display a summary of available command-line options. Useful for quick reference.

```bash
$ nmap
```

--------------------------------

### Custom Nmap Arguments for Scanning

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Demonstrates using the `args` parameter to pass custom Nmap options for various scan types. Supports combining options like service version detection, timing templates, specific scripts, port specification, and output to file.

```python
import nmap3

nmap = nmap3.Nmap()

# Combine top ports with version detection
results = nmap.scan_top_ports("192.168.1.1", args="-sV")

# Add timing template for faster scans
results = nmap.scan_top_ports("192.168.1.1", args="-T4 -sV")

# Use specific scripts
results = nmap.nmap_version_detection(
    "192.168.1.1",
    args="--script vulners,http-enum --script-args mincvss+5.0"
)

# Specify ports explicitly
results = nmap.scan_top_ports("192.168.1.1", args="-p 22,80,443,8080")

# Output to file while also getting results
results = nmap.scan_top_ports("192.168.1.1", args="-oN scan_output.txt")

print(results)
```

--------------------------------

### TCP connect() Scan (-sT)

Source: https://github.com/nmmapper/python3-nmap/blob/main/docs/index.md

Executes a TCP connect() scan, which completes the full TCP connection. This method does not require root privileges.

```python
import nmap3
nmap = nmap3.NmapScanTechniques()
results = nmap.nmap_tcp_scan()
```

--------------------------------

### Service and Version Detection

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Perform service and version detection on a target host. Can be combined with scripts like 'vulners' for vulnerability scanning.

```python
import nmap3

nmap = nmap3.Nmap()
services = nmap.nmap_version_detection("192.168.1.1")

# With vulnerability scanning using vulners script
vuln_results = nmap.nmap_version_detection(
    "192.168.1.1",
    args="--script vulners --script-args mincvss+5.0"
)

# Example output:
# {
#     "192.168.1.1": {
#         "ports": [
#             {
#                 "portid": "80",
#                 "protocol": "tcp",
#                 "state": "open",
#                 "service": {
#                     "name": "http",
#                     "product": "nginx",
#                     "version": "1.14.0",
#                     "ostype": "Linux",
#                     "extrainfo": "Ubuntu"
#                 },
#                 "cpe": [{"cpe": "cpe:/o:linux:linux_kernel"}]
#             }
#         ]
#     }
# }
print(services)
```

--------------------------------

### Using Custom Nmap Command Line Arguments

Source: https://github.com/nmmapper/python3-nmap/blob/main/docs/index.md

Demonstrates how to pass custom Nmap command-line arguments to scan functions.

```APIDOC
## Using Custom Nmap Command Line Arguments

### Description
Allows users to pass custom Nmap command-line arguments to extend scanning capabilities, such as combining top port scans with version detection.

### Method
`scan_top_ports(host, args=None)`

### Endpoint
N/A (This is a library function, not a web endpoint)

### Parameters
- **host** (string) - Required - The target host to scan.
- **args** (string) - Required - Custom Nmap arguments (e.g., "-sV" for version detection).

### Request Example
```python
import nmap3
nmap = nmap3.Namp() # Note: The example shows nmap3.Namp() but the method is scan_top_ports
results = nmap3.scan_top_ports("host", args="-sV")
```

### Response
#### Success Response (200)
- **results** (list) - A list of dictionaries containing scan results with custom arguments applied.

#### Response Example
(Response structure depends on the scan and arguments used)
```

--------------------------------

### Basic Nmap Scan

Source: https://github.com/nmmapper/python3-nmap/blob/main/docs/nmap.md

A sample Nmap command to perform an aggressive scan with OS detection and version detection enabled. Use for comprehensive network auditing.

```bash
$ nmap -A -T4 scanme.nmap.org
```

--------------------------------

### Configure Root Privileges

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Configures the scanner to prepend sudo to nmap commands for privileged operations. Subsequent privileged scans will work.

```python
import nmap3

nmap = nmap3.Nmap()
nmap.require_root(True)  # Will use sudo for subsequent commands

# Now privileged scans will work
os_results = nmap.nmap_os_detection("192.168.1.1")
print(os_results)
```

--------------------------------

### Asynchronous Version Detection Scan

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Performs asynchronous version detection scan. Useful for identifying services and their versions running on hosts.

```python
import asyncio
import nmap3

async def async_version_scan():
    nmap = nmap3.NmapAsync()
    services = await nmap.nmap_version_detection("scanme.nmap.org")
    return services

result = asyncio.run(async_version_scan())
print(result)
```

--------------------------------

### Nmap Host Discovery Techniques

Source: https://github.com/nmmapper/python3-nmap/blob/main/README.md

Supports Nmap host discovery techniques.

```APIDOC
## Nmap Host Discovery Techniques

### Description
This section details the Nmap host discovery techniques supported by the library.

### Methods

- **Port Scan Only (`nmap_portscan_only`)**
  Performs a port scan without host discovery (-Pn).
  ```python
  import nmap3
  nmap = nmap3.NmapHostDiscovery()
  results = nmap.nmap_portscan_only("your-host")
  ```

- **No Port Scan (`nmap_no_portscan`)**
  Performs only host discovery without a port scan (-sn).
  ```python
  import nmap3
  nmap = nmap3.NmapHostDiscovery()
  results = nmap.nmap_no_portscan("your-host")
  ```

- **ARP Discovery (`nmap_arp_discovery`)**
  Performs ARP discovery on a local network (-PR).
  ```python
  import nmap3
  nmap = nmap3.NmapHostDiscovery()
  results = nmap.nmap_arp_discovery("your-host")
  ```

- **Disable DNS Resolution (`nmap_disable_dns`)**
  Disables DNS resolution during host discovery (-n).
  ```python
  import nmap3
  nmap = nmap3.NmapHostDiscovery()
  results = nmap.nmap_disable_dns("your-host")
  ```

### Parameters for each method
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example (General)
```python
import nmap3
nmap = nmap3.NmapHostDiscovery()
# Example for nmap_portscan_only
results = nmap.nmap_portscan_only("your-host")
```

### Response (General)
#### Success Response (200)
- **results** (dict) - A dictionary containing the host discovery results.

#### Response Example (General)
(Example response structure depends on the specific discovery technique and nmap output)
```

--------------------------------

### Asynchronous DNS Brute-Force Script

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Performs asynchronous DNS brute-force enumeration to find subdomains. Requires a domain name as input.

```python
import asyncio
import nmap3

async def find_subdomains():
    nmap = nmap3.NmapAsync()
    subdomains = await nmap.nmap_dns_brute_script("example.com")
    return subdomains

results = asyncio.run(find_subsubdomains())
print(results)
```

--------------------------------

### TCP connect() Scan (-sT)

Source: https://github.com/nmmapper/python3-nmap/blob/main/docs/index.md

Performs a TCP connect() scan, which completes the full TCP connection.

```APIDOC
## TCP connect() Scan (-sT)

### Description
Performs a TCP connect() scan. This method completes the TCP connection handshake.

### Method
`nmap_tcp_scan()`

### Endpoint
N/A (This is a library function, not a web endpoint)

### Parameters
None

### Request Example
```python
import nmap3
nmap = nmap3.NmapScanTechniques()
results = nmap.nmap_tcp_scan()
```

### Response
#### Success Response (200)
- **results** (list) - A list of dictionaries containing scan results.

#### Response Example
(Response structure similar to TCP SYN Scan, depending on scan results)
```

--------------------------------

### Execute Nmap Ping Scan

Source: https://github.com/nmmapper/python3-nmap/blob/main/README.md

Perform a ping scan to discover live hosts on the network. This is a fundamental host discovery technique.

```python
import nmap3
nmap = nmap3.NmapScanTechniques()
result = nmap.nmap_ping_scan("192.168.178.1")
```

--------------------------------

### Identify Service Version with Nmap

Source: https://github.com/nmmapper/python3-nmap/blob/main/README.md

Use this command to identify service versions on a target host. The Python script equivalent initializes the Nmap object and calls the nmap_version_detection method.

```sh
$ nmap 192.168.178.1  -sV
```

```python
import nmap3
nmap = nmap3.Nmap()
version_result = nmap.nmap_version_detection("your-host.com")
```

--------------------------------

### Perform ARP Discovery

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Performs ARP discovery (-PR) on a local network to find hosts.

```python
import nmap3

nmap = nmap3.NmapHostDiscovery()

```

--------------------------------

### Nmap Host Discovery Techniques

Source: https://github.com/nmmapper/python3-nmap/blob/main/docs/nmap.md

A collection of Nmap commands for host discovery. These options help identify active hosts on a network using various ping and scan methods.

```bash
$ nmap  -sL # (List Scan)
```

```bash
$ nmap  -sn # (No port scan)
```

```bash
$ nmap  -Pn # (No ping)
```

```bash
$ nmap  -PS <port list> # (TCP SYN Ping)
```

```bash
$ nmap -PA <port list> # (TCP ACK Ping)
```

```bash
$ nmap  -PU <port list> # (UDP Ping)
```

```bash
$ nmap  -PY <port list> # (SCTP INIT Ping)
```

```bash
$ nmap  -PE; -PP; -PM # (ICMP Ping Types)
```

```bash
$ nmap  -PO <protocol list> # (IP Protocol Ping)
```

```bash
$ nmap  --disable-arp-ping # (No ARP or ND Ping)
```

```bash
$ nmap  --traceroute # (Trace path to host)
```

```bash
$ nmap  -n # (No DNS resolution)
```

```bash
$ nmap  -R # (DNS resolution for all targets)
```

```bash
$ nmap  --resolve-all # (Scan each resolved address)
```

```bash
$ nmap  --system-dns # (Use system DNS resolver)
```

```bash
$ nmap  --dns-servers <server1>[,<server2>[,...]] # (Servers to use for reverse DNS queries)
```

--------------------------------

### Perform Nmap Host Discovery (No Port Scan)

Source: https://github.com/nmmapper/python3-nmap/blob/main/README.md

Perform host discovery without scanning ports. This is useful for quickly identifying live hosts on a network.

```python
import nmap3
nmap = nmap3.NmapHostDiscovery()
results = nmap.nmap_no_portscan("your-host")
```

--------------------------------

### Detect Firewall Rules

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Attempts to detect firewall rules using ACK scan. Requires root privileges.

```python
import nmap3

nmap = nmap3.Nmap()
# Must be run as root
firewall_info = nmap.nmap_detect_firewall("192.168.1.1")

# Results show filtered vs unfiltered ports indicating firewall presence
print(firewall_info)
```

--------------------------------

### Perform FIN Scan

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Performs a FIN scan (-sF) which can bypass some firewalls. Requires root privileges. FIN scans are useful for firewall evasion.

```python
import nmap3

nmap = nmap3.NmapScanTechniques()
# Must be run as root
fin_results = nmap.nmap_fin_scan("192.168.1.1")

# FIN scans are useful for firewall evasion
print(fin_results)
```

--------------------------------

### Nmap Version Detection with Python3-nmap

Source: https://github.com/nmmapper/python3-nmap/blob/main/docs/index.md

Use the `nmap_version_detection` method to perform Nmap's version detection. This is equivalent to running `nmap -sV <target>`.

```python
import nmap3
nmap = nmap3.Nmap()

result = nmap.nmap_version_detection("nmmapper.com")

# This is equivalent to nmap's
# nmap  nmmapper.com  -sV
# Except we add 'oX' to be /usr/bin/nmap  -oX  -  nmmapper.com  -sV
#
# result Output
[
{
    "cpe": [
        {
            "cpe": "cpe:/o:linux:linux_kernel"
        }
    ],
    "port": "80",
    "protocol": "tcp",
    "service": {
        "conf": "10",
        "extrainfo": "Ubuntu",
        "method": "probed",
        "name": "http",
        "ostype": "Linux",
        "product": "nginx",
        "version": "1.14.0"
    }
},
{
    "cpe": [
        {
            "cpe": "cpe:/o:linux:linux_kernel"
        }
    ],
    "port": "443",
    "protocol": "tcp",
    "service": {
        "conf": "10",
        "extrainfo": "Ubuntu",
        "method": "probed",
        "name": "http",
        "ostype": "Linux",
        "product": "nginx",
        "tunnel": "ssl",
        "version": "1.14.0"
    }
},
{
    "cpe": [
        {
            "cpe": "cpe:/o:linux:linux_kernel"
        }
    ],
    "port": "2000",
    "protocol": "tcp",
    "service": {
        "conf": "10",
        "extrainfo": "Ubuntu Linux; protocol 2.0",
        "method": "probed",
        "name": "ssh",
        "ostype": "Linux",
        "product": "OpenSSH",
        "version": "7.6p1 Ubuntu 4ubuntu0.3"
    }
}
]
```

--------------------------------

### Ping Scan (-sP)

Source: https://github.com/nmmapper/python3-nmap/blob/main/docs/index.md

Performs a Ping scan to discover live hosts.

```APIDOC
## Ping Scan (-sP)

### Description
Performs a Ping scan to determine which hosts are online.

### Method
`nmap_ping_scan()`

### Endpoint
N/A (This is a library function, not a web endpoint)

### Parameters
None

### Request Example
```python
import nmap3
nmap = nmap3.NmapScanTechniques()
results = nmap.nmap_ping_scan()
```

### Response
#### Success Response (200)
- **results** (list) - A list of dictionaries indicating live hosts.

#### Response Example
(Response structure depends on scan results)
```

--------------------------------

### Service Version Detection

Source: https://github.com/nmmapper/python3-nmap/blob/main/README.md

Performs service version detection on a specified host. This is equivalent to the `nmap -sV` command.

```APIDOC
## Service Version Detection

### Description
Performs service version detection on a specified host to identify running services and their versions.

### Method
`nmap_version_detection(self, host, args=None)`

### Endpoint
N/A (This is a library function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import nmap3
nmap = nmap3.Nmap()
version_result = nmap.nmap_version_detection("your-host.com")
```

### Response
#### Success Response (200)
- **version_result** (dict) - A dictionary containing the version detection results for each port.

#### Response Example
```json
[
    {
        "cpe": [
            {
                "cpe": "cpe:/o:linux:linux_kernel"
            }
        ],
        "port": "80",
        "protocol": "tcp",
        "service": {
            "conf": "10",
            "extrainfo": "Ubuntu",
            "method": "probed",
            "name": "http",
            "ostype": "Linux",
            "product": "nginx",
            "version": "1.14.0"
        }
    }
]
```
```

--------------------------------

### Execute Nmap TCP Scan

Source: https://github.com/nmmapper/python3-nmap/blob/main/README.md

Perform a standard TCP SYN scan. This is a common and effective method for port scanning.

```python
import nmap3
nmap = nmap3.NmapScanTechniques()
result = nmap.nmap_tcp_scan("192.168.178.1")
```

--------------------------------

### Operating System Detection

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Perform operating system detection on a target host. This function requires root privileges to run.

```python
import nmap3

nmap = nmap3.Nmap()
# Must be run as root/administrator
os_results = nmap.nmap_os_detection("192.168.1.1")

# Example output:
# {
#     "192.168.1.1": {
#         "osmatch": [
#             {
#                 "name": "Linux 3.13",
#                 "accuracy": "100",
#                 "line": "60884",
#                 "osclass": {
#                     "osfamily": "Linux",
#                     "osgen": "3.X",
#                     "type": "general purpose",
#                     "vendor": "Linux",
#                     "accuracy": "100"
#                 },
#                 "cpe": "cpe:/o:linux:linux_kernel:3.13"
#             }
#         ],
#         "ports": [...],
#         "hostname": [],
#         "macaddress": null
#     }
# }
print(os_results)
```

--------------------------------

### DNS Brute-Force Subdomain Discovery

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Utilize the dns-brute NSE script to discover subdomains of a given domain.

```python
import nmap3

nmap = nmap3.Nmap()
subdomains = nmap.nmap_dns_brute_script("example.com")

# Example output:
# [
#     {"address": "mail.example.com", "hostname": "68.65.122.10"},
#     {"address": "www.example.com", "hostname": "5.189.129.43"},
#     {"address": "ftp.example.com", "hostname": "192.168.1.50"}
# ]
print(subdomains)
```

--------------------------------

### Perform UDP Scan

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Performs a UDP scan (-sU) to discover UDP services. Requires root privileges. UDP scans are slower than TCP scans. Can be run with port specification.

```python
import nmap3

nmap = nmap3.NmapScanTechniques()
# Must be run as root - UDP scans are slower than TCP
udp_results = nmap.nmap_udp_scan("192.168.1.1")

# With port specification
udp_results = nmap.nmap_udp_scan("192.168.1.1", args="-p 53,123,161")

print(udp_results)
```

--------------------------------

### Identify OS with python3-nmap (Requires Root)

Source: https://github.com/nmmapper/python3-nmap/blob/main/README.md

Use this function to identify the operating system of a target host. This operation requires root privileges to run correctly.

```python
import nmap3
nmap = nmap3.Nmap()
os_results = nmap.nmap_os_detection("192.168.178.2") # MOST BE ROOT
```

--------------------------------

### Perform DNS Brute Script Scan with python3-nmap

Source: https://github.com/nmmapper/python3-nmap/blob/main/README.md

Execute the 'dns-brute.nse' script to perform DNS brute-forcing on a target. The results are returned in JSON format.

```python
import nmap3
nmap = nmap3.Nmap()
results = nmap.nmap_dns_brute_script("your-host.com")
```

--------------------------------

### Nmap Class - nmap_dns_brute_script

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Uses the dns-brute NSE script to discover subdomains through DNS brute-force enumeration.

```APIDOC
## POST DNS Brute Script

### Description
Enumerates subdomains of a given domain using the Nmap Scripting Engine's 'dns-brute' script.

### Method
POST

### Endpoint
/nmap_dns_brute_script

### Parameters
#### Query Parameters
- **domain** (string) - Required - The domain to perform subdomain enumeration on (e.g., "example.com").

### Request Example
```python
import nmap3

nmap = nmap3.Nmap()
subdomains = nmap.nmap_dns_brute_script("example.com")
print(subdomains)
```

### Response
#### Success Response (200)
- **subdomains** (list) - A list of discovered subdomains, each with an address and hostname.

#### Response Example
```json
[
    {"address": "mail.example.com", "hostname": "68.65.122.10"},
    {"address": "www.example.com", "hostname": "5.189.129.43"},
    {"address": "ftp.example.com", "hostname": "192.168.1.50"}
]
```
```

--------------------------------

### Nmap OS Detection

Source: https://github.com/nmmapper/python3-nmap/blob/main/README.md

Performs Nmap OS detection on a target host.

```APIDOC
## Nmap OS Detection

### Description
Attempts to detect the operating system of a target host using Nmap's OS detection capabilities.

### Method
`nmap_os_detection(self, host, args=None)`

### Endpoint
N/A (This is a library function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import nmap3
nmap = nmap3.Nmap()
results = nmap.nmap_os_detection("your-host")
```

### Response
#### Success Response (200)
- **results** (dict) - A dictionary containing the OS detection results.

#### Response Example
(Example response structure depends on nmap scan output)
```

--------------------------------

### Require Root Configuration

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Configures the scanner to prepend sudo to nmap commands for privileged operations. This is essential for scans requiring root privileges.

```APIDOC
## require_root

### Description
Configures the scanner to prepend sudo to nmap commands for privileged operations. This is essential for scans requiring root privileges.

### Method
`require_root`

### Endpoint
N/A (This is a library function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import nmap3

nmap = nmap3.Nmap()
nmap.require_root(True)  # Will use sudo for subsequent commands

# Now privileged scans will work
os_results = nmap.nmap_os_detection("192.168.1.1")
print(os_results)
```

### Response
#### Success Response (200)
- **os_results** (dict) - The results of the OS detection scan performed after enabling root privileges.

#### Response Example
```json
{
    "192.168.1.1": {
        "osmatch": [
            {"name": "Linux 3.X", "accuracy": "95"}
        ]
    }
}
```
```

--------------------------------

### Perform IP Protocol Scan

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Performs an IP protocol scan (-sO) to determine supported IP protocols on the target. Identifies which IP protocols (TCP, UDP, ICMP, etc.) the target responds to.

```python
import nmap3

nmap = nmap3.NmapScanTechniques()
ip_protocol_results = nmap.nmap_ip_scan("192.168.1.1")

# Identifies which IP protocols (TCP, UDP, ICMP, etc.) the target responds to
print(ip_protocol_results)
```

--------------------------------

### Idle Scan (-sI)

Source: https://github.com/nmmapper/python3-nmap/blob/main/docs/index.md

Performs an Idle scan using a zombie host.

```APIDOC
## Idle Scan (-sI)

### Description
Performs an Idle scan, which leverages a zombie host to perform scans stealthily.

### Method
`nmap_idle_scan()`

### Endpoint
N/A (This is a library function, not a web endpoint)

### Parameters
None

### Request Example
```python
import nmap3
nmap = nmap3.NmapScanTechniques()
results = nmap.nmap_idle_scan()
```

### Response
#### Success Response (200)
- **results** (list) - A list of dictionaries containing scan results.

#### Response Example
(Response structure depends on scan results)
```

--------------------------------

### Idle Scan (-sI)

Source: https://github.com/nmmapper/python3-nmap/blob/main/docs/index.md

Implements an Idle scan, a stealthy technique that uses a zombie host to perform the scan. Requires root privileges and a suitable zombie host.

```python
import nmap3
nmap = nmap3.NmapScanTechniques()
results = nmap.nmap_idle_scan()
```

--------------------------------

### Nmap Class - nmap_os_detection

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Performs operating system detection on the target host. Requires root privileges.

```APIDOC
## POST OS Detection

### Description
Performs operating system detection on a target host. This function typically requires root or administrator privileges to run effectively.

### Method
POST

### Endpoint
/nmap_os_detection

### Parameters
#### Query Parameters
- **host** (string) - Required - The target host to perform OS detection on (e.g., "192.168.1.1").

### Request Example
```python
import nmap3

nmap = nmap3.Nmap()
# Must be run as root/administrator
os_results = nmap.nmap_os_detection("192.168.1.1")
print(os_results)
```

### Response
#### Success Response (200)
- **host_ip** (string) - The IP address of the scanned host.
  - **osmatch** (list) - A list of potential operating system matches.
    - **name** (string) - The name of the matched OS.
    - **accuracy** (string) - The accuracy score for the match.
    - **line** (string) - The line number from Nmap's OS detection database.
    - **osclass** (object) - Detailed OS class information.
      - **osfamily** (string) - The OS family (e.g., "Linux").
      - **osgen** (string) - The OS generation (e.g., "3.X").
      - **type** (string) - The type of OS (e.g., "general purpose").
      - **vendor** (string) - The vendor of the OS.
      - **accuracy** (string) - The accuracy score for the OS class.
    - **cpe** (string) - The Common Platform Enumeration (CPE) string for the OS.
  - **ports** (list) - Information about scanned ports.
  - **hostname** (list) - Hostnames associated with the IP.
  - **macaddress** (string) - MAC address of the host.

#### Response Example
```json
{
    "192.168.1.1": {
        "osmatch": [
            {
                "name": "Linux 3.13",
                "accuracy": "100",
                "line": "60884",
                "osclass": {
                    "osfamily": "Linux",
                    "osgen": "3.X",
                    "type": "general purpose",
                    "vendor": "Linux",
                    "accuracy": "100"
                },
                "cpe": "cpe:/o:linux:linux_kernel:3.13"
            }
        ],
        "ports": [],
        "hostname": [],
        "macaddress": null
    }
}
```
```

--------------------------------

### Perform Nmap Version Detection

Source: https://github.com/nmmapper/python3-nmap/blob/main/README.md

Perform detailed version detection for services running on open ports. This operation requires root privileges.

```python
import nmap3
nmap = nmap3.Nmap()
results = nmap.nmap_version_detection("your-host") # Must be root
```

--------------------------------

### Nmap Version Information

Source: https://github.com/nmmapper/python3-nmap/blob/main/README.md

Retrieves general Nmap version information.

```APIDOC
## Get Nmap Version Details

### Description
Retrieves the version information of the Nmap tool itself.

### Method
`nmap_version(self)`

### Endpoint
N/A (This is a library function)

### Parameters
None

### Request Example
```python
import nmap3
nmap = nmap3.Nmap()
results = nmap.nmap_version()
```

### Response
#### Success Response (200)
- **results** (dict) - A dictionary containing Nmap version details.

#### Response Example
(Example response structure depends on nmap version output)
```

--------------------------------

### Perform TCP Connect Scan

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Performs a TCP connect scan (-sT), useful when SYN scan is not available. Can be run with additional arguments like port specification.

```python
import nmap3

nmap = nmap3.NmapScanTechniques()
tcp_results = nmap.nmap_tcp_scan("192.168.1.1")

# With additional arguments
tcp_results = nmap.nmap_tcp_scan("192.168.1.1", args="-p 1-1000")

# Example output:
# {
#     "192.168.1.1": {
#         "ports": [
#             {"portid": "22", "state": "open", "protocol": "tcp"},
#             {"portid": "80", "state": "open", "protocol": "tcp"}
#         ]
#     }
# }
print(tcp_results)
```

--------------------------------

### Execute Nmap DNS Brute-Script

Source: https://github.com/nmmapper/python3-nmap/blob/main/README.md

Use the DNS brute-script to discover subdomains for a given domain. This can help in mapping out the network infrastructure.

```python
import nmap3
nmap = nmap3.Nmap()
results = nmap.nmap_dns_brute_script("domain")
```

--------------------------------

### NmapHostDiscovery - ARP Discovery

Source: https://github.com/nmmapper/python3-nmap/blob/main/docs/index.md

Performs host discovery using ARP requests.

```APIDOC
## NmapHostDiscovery - ARP Discovery

### Description
Performs host discovery on the local network using ARP requests.

### Method
`nmap_arp_discovery(self, host, args=None)`

### Endpoint
N/A (This is a library function, not a web endpoint)

### Parameters
- **host** (string) - Required - The target host or network to discover.
- **args** (string) - Optional - Additional Nmap arguments.

### Request Example
```python
import nmap3
nmap = nmap3.NmapHostDiscovery()
results = nmap.nmap_arp_discovery("your-host")
```

### Response
#### Success Response (200)
- **results** (list) - A list of dictionaries containing ARP discovery results.

#### Response Example
(Response structure depends on scan results)
```

--------------------------------

### Configure Command Timeout for Scans

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Sets command timeouts in seconds to prevent long-running scans from blocking operations. Includes error handling for timeouts.

```python
import nmap3

nmap = nmap3.Nmap()

# Set timeout in seconds
try:
    results = nmap.scan_top_ports("192.168.1.1", timeout=60)
except Exception as e:
    print(f"Scan timed out: {e}")

# Longer timeout for comprehensive scans
results = nmap.nmap_subnet_scan("192.168.1.0/24", timeout=3600)
print(results)
```

--------------------------------

### Host Discovery: No Port Scan

Source: https://github.com/nmmapper/python3-nmap/blob/main/docs/index.md

Performs host discovery without performing a port scan. This is useful for identifying live hosts on a network.

```python
import nmap3
nmap = nmapp.NmapHostDiscovery()
results = nmap.nmap_no_portscan("your-host")
```

--------------------------------

### Execute Nmap Idle Scan

Source: https://github.com/nmmapper/python3-nmap/blob/main/README.md

Perform an idle scan, which uses a zombie host to perform the scan. This is an advanced technique for stealth.

```python
import nmap3
nmap = nmap3.NmapScanTechniques()
result = nmap.nmap_idle_scan("192.168.178.1")
```

--------------------------------

### Perform ARP Discovery

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Uses ARP discovery for local network segments. ARP is reliable for local network discovery.

```python
import nmap3

nmap = nmap3.NmapHostDiscovery()
arp_results = nmap.nmap_arp_discovery("192.168.1.0/24")

# ARP is very reliable for local network discovery
print(arp_results)
```

--------------------------------

### Nmap Detect Firewall

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Attempts to detect firewall rules using ACK scan. Requires root privileges.

```APIDOC
## nmap_detect_firewall

### Description
Attempts to detect firewall rules using ACK scan. Requires root privileges.

### Method
`nmap_detect_firewall`

### Endpoint
N/A (This is a library function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import nmap3

nmap = nmap3.Nmap()
# Must be run as root
firewall_info = nmap.nmap_detect_firewall("192.168.1.1")
print(firewall_info)
```

### Response
#### Success Response (200)
- **firewall_info** (dict) - A dictionary containing information about detected firewall rules, indicating filtered vs unfiltered ports.

#### Response Example
```json
{
    "192.168.1.1": {
        "ports": [
            {"portid": "22", "state": "filtered", "protocol": "tcp"},
            {"portid": "80", "state": "unfiltered", "protocol": "tcp"}
        ]
    }
}
```
```

--------------------------------

### Basic Nmap Port Scan Output

Source: https://github.com/nmmapper/python3-nmap/blob/main/docs/nmap.md

This output shows a typical result from a basic Nmap scan, detailing the state of scanned ports and services. It highlights common port states like 'open' and 'closed'.

```bash
Not shown: 995 filtered ports
PORT     STATE  SERVICE
80/tcp   open   http
113/tcp  closed ident
443/tcp  open   https
8080/tcp open   http-proxy
8443/tcp open   https-alt

Nmap done: 1 IP address (1 host up) scanned in 18.57 seconds
```

--------------------------------

### Asynchronous Top Ports Scan

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Performs asynchronous top ports scanning for non-blocking operations. Allows running multiple scans concurrently.

```python
import asyncio
import nmap3

async def scan_multiple_hosts():
    nmap = nmap3.NmapAsync()

    # Run multiple scans concurrently
    results = await asyncio.gather(
        nmap.scan_top_ports("192.168.1.1", default=10),
        nmap.scan_top_ports("192.168.1.2", default=10),
        nmap.scan_top_ports("192.168.1.3", default=10)
    )

    for result in results:
        print(result)

    return results

# Run the async function
asyncio.run(scan_multiple_hosts())
```

--------------------------------

### Subnet Scan All Ports

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Scan all ports on a target host using the -p- flag for comprehensive port discovery.

```python
import nmap3

nmap = nmap3.Nmap()

```

--------------------------------

### Ping Scan (-sP)

Source: https://github.com/nmmapper/python3-nmap/blob/main/docs/index.md

Conducts a Ping scan to determine host availability. This is useful for network reconnaissance to identify live hosts.

```python
import nmap3
nmap = nmap3.NmapScanTechniques()
results = nmap.nmap_ping_scan()
```

--------------------------------

### Host Discovery: ARP Discovery

Source: https://github.com/nmmapper/python3-nmap/blob/main/docs/index.md

Utilizes ARP requests for host discovery on local networks. This method is efficient for discovering hosts within the same subnet.

```python
import nmap3
nmap = nmap3.NmapHostDiscovery()
results = nmap.nmap_arp_discovery("your-host")
```

--------------------------------

### Scan Top Ports

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Perform a scan of the most commonly used ports on a target host. Optionally include version detection.

```python
import nmap3

nmap = nmap3.Nmap()
results = nmap.scan_top_ports("scanme.nmap.org", default=10)

# Scan top 20 ports with version detection
results_with_version = nmap.scan_top_ports("192.168.1.1", default=20, args="-sV")

# Example output structure:
# {
#     "192.168.1.1": {
#         "osmatch": {},
#         "ports": [
#             {
#                 "portid": "80",
#                 "protocol": "tcp",
#                 "state": "open",
#                 "reason": "syn-ack",
#                 "service": {"name": "http", "conf": "3", "method": "table"}
#             }
#         ],
#         "hostname": [],
#         "macaddress": null,
#         "state": {"state": "up", "reason": "syn-ack"}
#     },
#     "runtime": {"elapsed": "1.23", "exit": "success"},
#     "stats": {"scanner": "nmap", "version": "7.80"}
# }
print(results)
```

--------------------------------

### Nmap Class - nmap_version_detection

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Performs service and version detection on the target to identify running services.

```APIDOC
## POST Version Detection

### Description
Performs service and version detection on target hosts to identify running services and their versions.

### Method
POST

### Endpoint
/nmap_version_detection

### Parameters
#### Query Parameters
- **host** (string) - Required - The target host to scan (e.g., "192.168.1.1").
- **args** (string) - Optional - Additional Nmap arguments. For example, to use the 'vulners' script with a minimum CVSS score of 5.0, use `--script vulners --script-args mincvss+5.0`.

### Request Example
```python
import nmap3

nmap = nmap3.Nmap()
services = nmap.nmap_version_detection("192.168.1.1")

# With vulnerability scanning using vulners script
vuln_results = nmap.nmap_version_detection(
    "192.168.1.1",
    args="--script vulners --script-args mincvss+5.0"
)
print(services)
```

### Response
#### Success Response (200)
- **host_ip** (string) - The IP address of the scanned host.
  - **ports** (list) - List of scanned ports.
    - **portid** (string) - The port number.
    - **protocol** (string) - The protocol (e.g., "tcp").
    - **state** (string) - The state of the port (e.g., "open").
    - **service** (object) - Information about the detected service.
      - **name** (string) - The name of the service (e.g., "http").
      - **product** (string) - The product name of the service.
      - **version** (string) - The version of the service.
      - **ostype** (string) - The operating system type.
      - **extrainfo** (string) - Additional information about the service.
    - **cpe** (list) - Common Platform Enumeration (CPE) information.

#### Response Example
```json
{
    "192.168.1.1": {
        "ports": [
            {
                "portid": "80",
                "protocol": "tcp",
                "state": "open",
                "service": {
                    "name": "http",
                    "product": "nginx",
                    "version": "1.14.0",
                    "ostype": "Linux",
                    "extrainfo": "Ubuntu"
                },
                "cpe": [{"cpe": "cpe:/o:linux:linux_kernel"}]
            }
        ]
    }
}
```
```

--------------------------------

### Nmap SYN Scan

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Performs a TCP SYN (half-open) scan (-sS). Requires root privileges. This scan is faster and more stealthy than a full TCP connect scan.

```APIDOC
## nmap_syn_scan

### Description
Performs a TCP SYN (half-open) scan (-sS). Requires root privileges. This scan is faster and more stealthy than a full TCP connect scan.

### Method
`nmap_syn_scan`

### Endpoint
N/A (This is a library function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import nmap3

nmap = nmap3.NmapScanTechniques()
# Must be run as root
syn_results = nmap.nmap_syn_scan("192.168.1.1")
print(syn_results)
```

### Response
#### Success Response (200)
- **syn_results** (dict) - A dictionary containing the results of the SYN scan.

#### Response Example
```json
{
    "192.168.1.1": {
        "ports": [
            {"portid": "22", "state": "open", "protocol": "tcp"},
            {"portid": "443", "state": "closed", "protocol": "tcp"}
        ]
    }
}
```
```

--------------------------------

### NmapHostDiscovery - Disable DNS

Source: https://github.com/nmmapper/python3-nmap/blob/main/docs/index.md

Performs host discovery while disabling DNS resolution.

```APIDOC
## NmapHostDiscovery - Disable DNS

### Description
Performs host discovery on a given host, explicitly disabling DNS resolution.

### Method
`nmap_disable_dns(self, host, args=None)`

### Endpoint
N/A (This is a library function, not a web endpoint)

### Parameters
- **host** (string) - Required - The target host to discover.
- **args** (string) - Optional - Additional Nmap arguments.

### Request Example
```python
import nmap3
nmap = nmap3.NmapHostDiscovery()
results = nmap.nmap_disable_dns("your-host")
```

### Response
#### Success Response (200)
- **results** (list) - A list of dictionaries containing host discovery results without DNS resolution.

#### Response Example
(Response structure depends on scan results)
```

--------------------------------

### Perform Idle Scan

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Performs an idle/zombie scan (-sL) for stealthy scanning through a third host.

```python
import nmap3

nmap = nmap3.NmapScanTechniques()
idle_results = nmap.nmap_idle_scan("192.168.1.1")

print(idle_results)
```

--------------------------------

### Asynchronous UDP Scan

Source: https://context7.com/nmmapper/python3-nmap/llms.txt

Performs asynchronous UDP scanning. Useful for discovering UDP services on a target host.

```python
import asyncio
import nmap3

async def async_udp_scan():
    nmap = nmap3.NmapScanTechniquesAsync()
    results = await nmap.nmap_udp_scan("192.168.1.1")
    return results

result = asyncio.run(async_udp_scan())
print(result)
```

--------------------------------

### Custom Nmap Arguments for Scan

Source: https://github.com/nmmapper/python3-nmap/blob/main/docs/index.md

Allows passing custom Nmap command-line arguments to extend scanning capabilities, such as performing version detection alongside top port scans.

```python
import nmap3
nmap = nmap3.Namp()
results = nmap3.scan_top_ports("host", args="-sV")
```

--------------------------------

### Perform Nmap OS Detection

Source: https://github.com/nmmapper/python3-nmap/blob/main/README.md

Attempt to detect the operating system of the target host. This function uses Nmap's OS detection capabilities.

```python
import nmap3
nmap = nmap3.Nmap()
results = nmap.nmap_os_detection("your-host")
```