{"id":16248540,"url":"https://github.com/pythonhacker/pyscanlogd3","last_synced_at":"2025-04-08T12:22:02.286Z","repository":{"id":254573768,"uuid":"846944154","full_name":"pythonhacker/pyscanlogd3","owner":"pythonhacker","description":"Pyscanlogd3 is a port scan detection tool written in Python3","archived":false,"fork":false,"pushed_at":"2024-09-01T17:40:41.000Z","size":59,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-11T14:42:07.842Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pythonhacker.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2024-08-24T11:58:51.000Z","updated_at":"2024-09-01T17:40:45.000Z","dependencies_parsed_at":"2024-08-24T13:26:04.219Z","dependency_job_id":"b8d3d83d-6759-4a72-8a8c-c4a7c1a00efd","html_url":"https://github.com/pythonhacker/pyscanlogd3","commit_stats":{"total_commits":24,"total_committers":1,"mean_commits":24.0,"dds":0.0,"last_synced_commit":"fdd21d969a3eb6baecdde79c58e5ab1d010f9eed"},"previous_names":["pythonhacker/pyscanlogd3"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pythonhacker%2Fpyscanlogd3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pythonhacker%2Fpyscanlogd3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pythonhacker%2Fpyscanlogd3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pythonhacker%2Fpyscanlogd3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pythonhacker","download_url":"https://codeload.github.com/pythonhacker/pyscanlogd3/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247838443,"owners_count":21004581,"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":[],"created_at":"2024-10-10T14:42:18.227Z","updated_at":"2025-04-08T12:22:02.252Z","avatar_url":"https://github.com/pythonhacker.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# About\npyscanlogd3 (*py-scan-log-dee-three*) is a port scanning detection and logging tool written in Python3.\nIt is derived from the original pyscanlogd - https://github.com/pythonhacker/pyscanlogd which only\nsupports Python2.\n\nThe tool is able to detect vertical port scans. In other words, if any scanning tool performs\nmultiple port scans using TCP/UDP/SCTP techniques on the same host, the tool can detect it.\n\nAt present, it doesn't detect horizontal port scans (single port scanned across multiple hosts)\nor single port scans (single port scanned in single host).\n\n# Capabilities\npyscanlogd3 can detect most port scan techniques available using `nmap` and some by `hping3`. It uses `pypcap` library\nfor packet capturing and `dpkt` library for packet processing.\n\n# Requirements.\n\n1. A *nix (linux or similar) system with Python3 installed with support for sqlite3. The program is tested with Python3.11.\n2. Root (sudo) access\n\nThe program needs root privilges to listen to the network interfaces in promiscious mode.\n\n# Setup\n\n1. Checkout the source code\n2. Create a Python 3 virtualenv - Python 3.11 and higher are suggested.\n3. Inside the virtual env,\n    * pip install -r requirements.txt\n    * python setup.py install\n\nOnce installation is complete, you can run the program using `pyscanlogd3` command.\n\n# Running\n\nJust running the program without any arguments,\n\n\t$ pyscanlogd3\n\tScan logs will be saved to /var/log/pyscanlogd3.log\n\tlistening to [None]\n\tduplicate scans will be logged\n\tconfig =\u003e threshold: 8, timeout: 5s, bufsize: 8192\n\tcreating scan db /root/.config/pyscanlogd3/scan.db ...\n\tscan db created.\n\tlistening on wlp0s20f3:\n\nNOTE: The `pyscanlogd3` is a shell-script which runs with sudo access. It may ask you for your password if required. There is no need to run it with `sudo`.\n\nThe program by default runs in medium threshold mode. Scans are logged to a sqlite3 database and on the console.\n\nFor detailed command line options,\n\n\t$ pyscanlogd3 -h\n\tusage: pyscanlogd3 [-h] [-f LOGFILE] [-l {max,high,medium,low}] [-i [INTERFACE ...]] [-I]\n\n\tpyscanlogd3: Python3 port-scan detection program\n\n\toptions:\n\t  -h, --help            show this help message and exit\n\t  -f LOGFILE, --logfile LOGFILE\n\t\t\t\t\t\t\tFile to save logs to\n\t  -l {max,high,medium,low}, --level {max,high,medium,low}\n\t\t\t\t\t\t\tDefault threshold level for detection\n\t  -i [INTERFACE ...], --interface [INTERFACE ...]\n\t\t\t\t\t\t\tThe network interface(s) to listen to\n\t  -I, --ignore_duplicates\n\t\t\t\t\t\t\tIgnore continued (duplicate) scans\n\t  -q --quiet\n                            Be quiet, no scans are logged to console,\n\t\t\t\t\t\t\tonly to the logfile.\n\t\t\t\t\t\t\t\nTo listen to more than one interface, pass them to the `-i` option.\n\n\t$ pyscanlogd3 -i wlp0s20f3 lo\n\tScan logs will be saved to /var/log/pyscanlogd3.log\n\tlistening to ['wlp0s20f3', 'lo']\n\tduplicate scans will be logged\n\tconfig =\u003e threshold: 8, timeout: 5s, bufsize: 8192\n\tscan db /root/.config/pyscanlogd3/scan.db already exists.\n\tlistening on wlp0s20f3: \n\tlistening on lo: \n\nFor exiting press Ctrl-C. (once per interface).\n\n\tlistening on wlp0s20f3: \n\tlistening on lo: \n\t^CPress Ctrl-C again to exit\n\tstats for network interface: wlp0s20f3\n\n\t1 packets received by filter\n\t0 packets dropped by kernel\n\t^Cstats for network interface: lo\n\n\t2 packets received by filter\n\t0 packets dropped by kernel\n\n# Scan detection and logging (nmap Examples)\n\nWhile the program is running, try an `nmap` scan.\n\n\t$ sudo nmap -sX nmap.org\n\nYou should see the scan detected and logged on the console.\n\n\t[2024-08-25 19:36:14]: TCP Xmas scan (flags:41) from 192.168.1.6 to 50.116.1.184 (ports: [443, 80, 993, 1025, 1723])\n\nAs the scan continues, you will see more log lines like this as `nmap` scans more ports.\n\n\t[2024-08-25 19:36:14]: Continuing TCP Xmas scan (flags:41) from 192.168.1.6 to 50.116.1.184 (ports: [22, 23, 587, 139])\n\t[2024-08-25 19:36:16]: Continuing TCP Xmas scan (flags:41) from 192.168.1.6 to 50.116.1.184 (ports: [443, 8888, 110, 139, 587, 23, 22, 1723, 1025, 993, 1720, 5900, 3306, 3389, 143, 80, 113, 554, 199, 135, 8080, 21, 256])\n\nThe `Continuing` lines show a duplicate scan, i.e the same scan is detected as still running. To avoid detecting duplicate scans, you can pass the `-I` option.\n\nDo another scan, this time an `ACK` scan.\n\n\t$ sudo nmap -sA nmap.org\n\n\t[2024-08-25 19:38:05]: TCP Ack scan (flags:16) from 192.168.1.6 to 50.116.1.184 (ports: [443, 1025, 8888, 113, 143, 111, 8080, 993, 23, 110, 21, 5900, 1723, 3389, 80, 25, 53, 135, 139, 445, 587, 256])\n\nLet us do a UDP scan now.\n\n\t$ sudo nmap -sU nmap.org\n\t\n\t[2024-08-25 19:39:12]: UDP scan (flags:0) from 192.168.1.6 to 50.116.1.184 (ports: [36893, 40708, 5355, 20848, 8000, 43514, 215 68, 1434, 20164, 17824, 20154, 34555, 19017, 1900, 17487, 49158, 20560, 25337, 623, 20004, 997, 51972, 40539, 21333, 20, 45928,  1035, 49194, 177, 19161, 443, 50919, 30656, 43824, 16786, 34570, 33459, 518, 30718])\n\nScans are also logged to the scan db. By default this is created at `/root/.config/pyscanlogd3/scan.db` .\n\nYou can inspect the scans by opening the db.\n\n\t$ sudo sqlite3 /root/.config/pyscanlogd3/scan.db\n\t# Show all detected scans so far\n\tsqlite\u003e select distinct type from scan;\n\tTCP Xmas\n\tTCP Ack\n\tTCP Null\n\tUDP\n\t# Show all distinct scans originating from 192.168.1.6 grouped by scan hash and type\n\tsqlite\u003e select src,dst,type,hash,timestamp,utc_timestamp from scan where src='192.168.1.6' group by hash,type;\n\t192.168.1.6|50.116.1.184|TCP Ack|3654|1724594885.92384|2024-08-25 14:08:05\n\t192.168.1.6|50.116.1.184|TCP Null|3654|1724594941.4765|2024-08-25 14:09:01\n\t192.168.1.6|50.116.1.184|TCP Xmas|3654|1724594774.34435|2024-08-25 14:06:14\n\t192.168.1.6|50.116.1.184|UDP|3654|1724594952.29163|2024-08-25 14:09:12\n\nNOTE: The tool right now ignores scans where src and dst IPs are the same. \n\nScans are also logged to a log file, by default `/var/log/pyscalogd3.log`. You can tail the file to see the logs.\n\n\t$ sudo tail -f /var/log/\n\t[2024-09-01 19:58:36]: TCP Syn scan (flags:2) from 192.168.1.6 to 142.250.183.110 (ports: 80,143,199,443,8888)\n\t[2024-09-01 19:58:36]: Continuing TCP Syn scan (flags:2) from 192.168.1.6 to 142.250.183.110 (ports: 23,110,445,1025,3389)\n\n\n# Slow scan detection\n\nThe tool is able to detect slow scans as well. Use the `-T` option of nmap to try this out.\n\n\t$ sudo nmap -sS -T2  nmap.org\n\t[2024-08-25 19:43:27]: TCP Syn scan (flags:2) from 192.168.1.6 to 50.116.1.184 (ports: [256, 587, 3306, 23, 8080])\n\nParanod (`-T0`) and sneaky (`-T1`) scan types are very slow, so takes a while to detect.\n\n# Known Issues\n\n1. Detects spurious NULL TCP scans sometimes.\n2. Detects spurious NULL UDP scans sometimes.\n3. Slow scan detection is a work in progress.\n\n# Bugs and Suggestions\nFor bugs file issues in the project. For feedback checkout my email in setup.py.\n\n# LICENSE\nThe program is licensed under BSD 3-Clause license. Checkout `LICENSE` for details.\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpythonhacker%2Fpyscanlogd3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpythonhacker%2Fpyscanlogd3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpythonhacker%2Fpyscanlogd3/lists"}