{"id":13843403,"url":"https://github.com/f-froehlich/nmap-scan","last_synced_at":"2025-12-26T22:41:33.860Z","repository":{"id":157369509,"uuid":"320384285","full_name":"f-froehlich/nmap-scan","owner":"f-froehlich","description":"Nmap wrapper for python with full Nmap DTD support, parallel scans and threaded callback methods support for faster analytics.","archived":false,"fork":false,"pushed_at":"2023-05-03T14:11:44.000Z","size":276,"stargazers_count":11,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-20T02:23:33.269Z","etag":null,"topics":["network-scanner","nmap","os-identifier","portscan","portscanner","portscanning","scanner","scanning","security","security-tools","serverstatus","service-detection","service-discovery"],"latest_commit_sha":null,"homepage":"https://nmap-scan.de","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/f-froehlich.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-10T20:38:37.000Z","updated_at":"2024-09-28T06:01:26.000Z","dependencies_parsed_at":null,"dependency_job_id":"010a859b-7ca5-4906-b063-a54f3e60867c","html_url":"https://github.com/f-froehlich/nmap-scan","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/f-froehlich/nmap-scan","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f-froehlich%2Fnmap-scan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f-froehlich%2Fnmap-scan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f-froehlich%2Fnmap-scan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f-froehlich%2Fnmap-scan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/f-froehlich","download_url":"https://codeload.github.com/f-froehlich/nmap-scan/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f-froehlich%2Fnmap-scan/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264870411,"owners_count":23676223,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["network-scanner","nmap","os-identifier","portscan","portscanner","portscanning","scanner","scanning","security","security-tools","serverstatus","service-detection","service-discovery"],"created_at":"2024-08-04T17:02:06.974Z","updated_at":"2025-12-26T22:41:33.814Z","avatar_url":"https://github.com/f-froehlich.png","language":"Python","funding_links":[],"categories":["Python (1887)","Python"],"sub_categories":[],"readme":"Nmap scan\n=========\nNmap wrapper for python with ***full Nmap DTD support***, parallel scans and threaded callback methods support for faster analytics. You can also save your report to xml, json and html.\n\nCopyright (c) 2020 Fabian Fröhlich \u003cmail@nmap-scan.de\u003e [https://nmap-scan.de](https://nmap-scan.de)\n\nFull License Information see  [LICENSE](https://github.com/f-froehlich/nmap-scan/blob/master/LICENSE) file in root directory of this source code and License section of this File.\n\n# Donate\nThis project needs donations. Please check out [https://nmap-scan.de/Donate](https://nmap-scan.de/Donate) for details.\n\n\n# Quick setup\nSee our [documentation](https://nmap-scan.de) for details.\n\n## Required\n* install python 3.7 (other versions may also work)\n* install python3-pip\n* install [Nmap](https://github.com/nmap/nmap) \n* `pip3 install nmap-scan`\n\n## Basic usage\nSimple script to scan a network with parallel TCP and UDP scan and save the report into a file. Note that the `callback_method` is called asynchronous in the scanning thread of each scan method. If you don't need a callback on report finishing just remove the function call argument.\n```python\nfrom nmap_scan.NmapArgs import NmapArgs\nfrom nmap_scan.NmapScanMethods import NmapScanMethods\nfrom nmap_scan.Scanner import Scanner\n\nargs = NmapArgs(['192.168.0.1/24'])\nscanner = Scanner(args)\n\ndef callback_method(report, scan_method):\n    filename = {\n        NmapScanMethods.TCP: 'tcp',\n        NmapScanMethods.UDP: 'udp',\n    }\n\n    report.save('reports/scan-' + filename.get(scan_method) + '.xml')\n    report.save_html('reports/scan-' + filename.get(scan_method) + '.html')\n    report.save_json('reports/scan-' + filename.get(scan_method) + '.json')\n\n\nscanner.scan_udp_background(callback_method)\nscanner.scan_tcp_background(callback_method)\n\n# Do other stuff here\n\nscanner.wait_all()\n\n```\n\n## Advanced usage\nSimple script to scan multiple networks with different configurations. Each configuration is executed parallel and also each host will be scanned parallel. You can set up the maximum parallel threads per configuration (default 32) so in the following example it will execute nmap within 64 threads. To do so we first will create for each configuration a ping scan with your given hosts and even set `pn` from your `args` but all other arguments are ignored for the ping scan. Afterwords for each host it will create a scan thread with your `args` but update the hosts to the ip of the host resulted by the ping scan. You even can choose, if you want to scan every ip from the host or only the first (default). Of each executed scan (except the ping scan) we will call the `callback_method` asynchronous as in the **simple usage** mentored. If you don't need a callback on report finishing just remove the argument in the `MultiScannerConfiguration`. You can simply get all reports after execution with `get_reports()`it will automatically wait until the complete scan is finished.\n\n```python\nfrom nmap_scan.MultiScanner import MultiScanner\nfrom nmap_scan.MultiScannerConfiguration import MultiScannerConfiguration\nfrom nmap_scan.NmapArgs import NmapArgs\nfrom nmap_scan.NmapScanMethods import NmapScanMethods\n\nargs = NmapArgs(['192.168.0.0/24'])\nargs2 = NmapArgs(['192.168.1.0/24'])\n\ndef callback_method(ip, report, scan_method):\n    filename = {\n        NmapScanMethods.TCP: 'tcp',\n        NmapScanMethods.UDP: 'udp',\n    }\n    report.save('reports/' + ip + '_' + filename.get(scan_method) + '.xml')\n    report.save_html('reports/' + ip + '_' + filename.get(scan_method) + '.html')\n    report.save_json('reports/' + ip + '_' + filename.get(scan_method) + '.json')\n\n\nconfigs = [\n    MultiScannerConfiguration(nmap_args=args, scan_methods=[NmapScanMethods.TCP, NmapScanMethods.UDP], callback_method=callback_method),\n    MultiScannerConfiguration(nmap_args=args2, scan_methods=[NmapScanMethods.TCP], callback_method=callback_method),\n]\nscanner = MultiScanner(configs)\nscanner.scan_background()\n\n# Do other stuff here\n\nreports = scanner.get_reports()\n\n```\n\n## Debugging\n\n```python\nimport logging\n\nlogging.basicConfig(level=logging.DEBUG, filename='debug.log')\n```\n\n## Hints\nWe decided to make a few changes in the nmap DTD and also in our script to avoid errors during parsing. We changed the script attribute \"output\" from required to optional, because not all scipts of nmap set this attribute. Here are the changes:\n\n```shell script\n  \u003c!ATTLIST script\n  id    CDATA    #REQUIRED\n- output    CDATA    #REQUIRED\n+ output    CDATA    #IMPLIED\n  \u003e\n\n```\n\n# License\nThis section contains the additional terms of the AGPLv3 license agreement, a copy of the AGPLv3 is included in the [LICENSE](https://github.com/f-froehlich/nmap-scan/blob/master/LICENSE) file.\n\n1. Security analytic / \"White had\" use only.\n2. You are only allowed to use this tool, if you don't act against a law of your Country and if you don't planning a cyber attack on the scanned servers.\n3. You are only allowed to scan your own Servers and those, where you have the permission to do so.\n4. Adaptation of the [README.md](https://github.com/f-froehlich/nmap-scan/blob/master/README.md) is prohibited. The file must also be included with each copy without any modification. \n\n5. Adjustments of any kind must be listed in the attached [CHANGELOG.md](https://github.com/f-froehlich/monitoring-utils/blob/master/CHANGELOG.md) file. It is sufficient to name the change and the reason for the change here and to give appropriate references to the processing in the source code at the appropriate place.\n\n6. All edited copies must be made available on [github](https://github.com). You have to fork the original repository or use a fork from the original repository.\n\n7. You have to place the following link on your Homepage in a suitable place, if you using this software in a commercial way:\n\n    ```html\n    We using server scan tools from \u003ca href=\"https://nmap-scan.de\"\u003eFabian Fr\u0026ouml;hlich\u003c/a\u003e\n   ```\n\n    The wording is decisive here, so another language may be used. Attributes of the link may also be adjusted, but the link must be followable by web crawlers (e.g. Googlebot).\n\n    Furthermore, the imprint has to include a clear reference to the original github repository [https://github.com/f-froehlich/nmap-scan](https://github.com/f-froehlich/nmap-scan) as well as the link mentioned above in the body text.\n    \n8. You are not allowed to earn money with this tool.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ff-froehlich%2Fnmap-scan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ff-froehlich%2Fnmap-scan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ff-froehlich%2Fnmap-scan/lists"}