mingping 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (16) hide show
  1. mingping-0.1.0/.github/workflows/workflow.yml +21 -0
  2. mingping-0.1.0/.gitignore +10 -0
  3. mingping-0.1.0/.python-version +1 -0
  4. mingping-0.1.0/PKG-INFO +214 -0
  5. mingping-0.1.0/README.md +194 -0
  6. mingping-0.1.0/main.py +4 -0
  7. mingping-0.1.0/ming/__init__.py +0 -0
  8. mingping-0.1.0/ming/cli.py +375 -0
  9. mingping-0.1.0/ming/display.py +217 -0
  10. mingping-0.1.0/ming/ports.py +1163 -0
  11. mingping-0.1.0/ming/resolve.py +20 -0
  12. mingping-0.1.0/ming/scanner.py +192 -0
  13. mingping-0.1.0/ming/targets.py +78 -0
  14. mingping-0.1.0/prek.toml +8 -0
  15. mingping-0.1.0/pyproject.toml +64 -0
  16. mingping-0.1.0/uv.lock +199 -0
mingping-0.1.0/.github/workflows/workflow.yml ADDED
@@ -0,0 +1,21 @@
1
+ name: Publish to PyPI
2
+
3
+ on:
4
+ release:
5
+ types: [published]
6
+
7
+ permissions:
8
+ id-token: write
9
+
10
+ jobs:
11
+ publish:
12
+ runs-on: ubuntu-latest
13
+ environment: pypi
14
+ steps:
15
+ - uses: actions/checkout@v4
16
+
17
+ - uses: astral-sh/setup-uv@v5
18
+
19
+ - run: uv build
20
+
21
+ - run: uv publish
mingping-0.1.0/.gitignore ADDED
@@ -0,0 +1,10 @@
1
+ # Python-generated files
2
+ __pycache__/
3
+ *.py[oc]
4
+ build/
5
+ dist/
6
+ wheels/
7
+ *.egg-info
8
+
9
+ # Virtual environments
10
+ .venv
mingping-0.1.0/.python-version ADDED
@@ -0,0 +1 @@
1
+ 3.14
mingping-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,214 @@
1
+ Metadata-Version: 2.4
2
+ Name: mingping
3
+ Version: 0.1.0
4
+ Summary: Fast async multi-ping network scanner with a live terminal UI
5
+ Project-URL: Homepage, https://github.com/EliTheCoder/ming
6
+ Project-URL: Repository, https://github.com/EliTheCoder/ming
7
+ Project-URL: Issues, https://github.com/EliTheCoder/ming/issues
8
+ Author-email: Eli Frigo <eli@elifrigo.com>
9
+ License-Expression: MIT
10
+ Keywords: cli,icmp,network,ping,scanner,tcp,udp
11
+ Classifier: Environment :: Console
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Topic :: System :: Networking
14
+ Classifier: Topic :: System :: Systems Administration
15
+ Requires-Python: >=3.11
16
+ Requires-Dist: click>=8.3.1
17
+ Requires-Dist: icmplib>=3.0.4
18
+ Requires-Dist: rich>=14.3.3
19
+ Description-Content-Type: text/markdown
20
+
21
+ # ming
22
+
23
+ A fast, async multi-ping network scanner with a live terminal UI.
24
+
25
+ ```
26
+ ming 192.168.1.x tcp 80,443,8000-8080
27
+ ```
28
+
29
+ ---
30
+
31
+ ## Features
32
+
33
+ - **Three scan modes** — ICMP ping, TCP connect, UDP probe
34
+ - **Flexible targets** — single IPs, CIDR ranges, wildcards, hostnames, domains, comma-separated lists
35
+ - **Flexible port specs** — individual ports, ranges, comma-separated lists, named ports, and group presets
36
+ - **Reverse DNS** — hostname lookup on responding IPs (on by default)
37
+ - **Live display** — results table builds in real time as hosts respond
38
+ - **Structured output** — `--output json` or `--output csv` for scripting
39
+ - **Watch mode** — re-scan on an interval, highlighting new hosts
40
+ - **Fast** — fully async with high concurrency; Ctrl+C exits immediately
41
+
42
+ ---
43
+
44
+ ## Installation
45
+
46
+ Requires Python 3.11+ and [uv](https://github.com/astral-sh/uv).
47
+
48
+ ```sh
49
+ git clone https://github.com/yourname/ming
50
+ cd ming
51
+ uv pip install -e .
52
+ ```
53
+
54
+ Then run with:
55
+
56
+ ```sh
57
+ ming <destination> [method] [ports]
58
+ ```
59
+
60
+ ---
61
+
62
+ ## Usage
63
+
64
+ ```
65
+ ming DESTINATION [METHOD] [PORT_SPEC] [OPTIONS]
66
+ ```
67
+
68
+ ### Destinations
69
+
70
+ | Format | Example | Description |
71
+ |---|---|---|
72
+ | Single IP | `192.168.1.1` | One host |
73
+ | CIDR range | `192.168.1.0/24` | 256 hosts |
74
+ | Wildcard | `192.168.1.x` | Same as `/24` |
75
+ | Wider wildcard | `192.168.x.x` | `/16` — 65,536 hosts |
76
+ | Hostname | `localhost` | Resolved via DNS |
77
+ | Domain | `google.com` | Resolved via DNS |
78
+ | Comma-separated | `10.0.0.1,10.0.1.1` | Multiple targets |
79
+
80
+ Wildcard octets can be written as `x`, `xx`, or `xxx` — they all mean the same thing.
81
+
82
+ ### Methods
83
+
84
+ | Method | Alias | Description |
85
+ |---|---|---|
86
+ | `icmp` | `ping` | ICMP echo request (default) |
87
+ | `tcp` | `syn` | TCP connect scan |
88
+ | `udp` | — | UDP probe |
89
+
90
+ ### Port specs *(TCP and UDP only)*
91
+
92
+ | Spec | Example | Description |
93
+ |---|---|---|
94
+ | Single port | `80` | One port |
95
+ | Range | `8000-8080` | Inclusive range |
96
+ | List | `80,443,8000-8080` | Mix of ports and ranges |
97
+ | `top100` | — | Top 100 most common ports |
98
+ | `top1000` | — | Top 1000 most common ports (default) |
99
+ | Named port | `http`, `ssh`, `postgres` | Single named port |
100
+ | Group preset | `web`, `db`, `remote` | Multiple related ports |
101
+
102
+ **Named ports:** `http`, `https`, `http-alt`, `https-alt`, `ssh`, `telnet`, `rdp`, `vnc`, `ftp`, `ftps`, `tftp`, `rsync`, `nfs`, `smb`, `netbios`, `smtp`, `smtps`, `submission`, `pop3`, `pop3s`, `imap`, `imaps`, `dns`, `snmp`, `ntp`, `ldap`, `ldaps`, `kerberos`, `sip`, `rtsp`, `mysql`, `postgres`, `mssql`, `oracle`, `redis`, `mongodb`, `memcached`, `cassandra`, `elasticsearch`, `docker`, `kubernetes`, `kafka`, `rabbitmq`, `prometheus`, `grafana`, `kibana`, `jenkins`, and more.
103
+
104
+ **Group presets:**
105
+
106
+ | Group | Ports |
107
+ |---|---|
108
+ | `web` | 80, 443, 8080, 8443, 8000, 8888, 8008, 8081, 3000 |
109
+ | `db` | 3306, 5432, 1433, 6379, 27017, 5984, 9200, 9042, 11211, 1521 |
110
+ | `remote` | 22, 23, 3389, 5900, 5901 |
111
+ | `mail` | 25, 110, 143, 465, 587, 993, 995 |
112
+ | `file` | 20, 21, 69, 139, 445, 873, 990, 2049 |
113
+ | `devops` | 2375, 2376, 6443, 9200, 5601, 9090, 9092, 2181, 3000, 8086, 2379 |
114
+
115
+ ### Options
116
+
117
+ | Option | Short | Description |
118
+ |---|---|---|
119
+ | `--resolve` / `--no-resolve` | `-r` / `-R` | Reverse DNS lookup on responding IPs (default: on) |
120
+ | `--quiet` | `-q` | No live display; print one line per responding host |
121
+ | `--output json\|csv` | `-o` | Structured output to stdout, disables live display |
122
+ | `--timeout SECS` | `-t` | Probe timeout in seconds (overrides per-protocol default) |
123
+ | `--concurrency N` | `-c` | Max concurrent probes (overrides per-protocol default) |
124
+ | `--watch` | `-w` | Re-scan repeatedly on `--interval` |
125
+ | `--interval SECS` | `-i` | Seconds between re-scans in watch mode (default: 30) |
126
+
127
+ ---
128
+
129
+ ## Examples
130
+
131
+ ```sh
132
+ # ICMP ping a whole subnet
133
+ ming 192.168.1.x
134
+
135
+ # TCP scan a host on common ports
136
+ ming 192.168.1.1 tcp
137
+
138
+ # TCP scan specific ports
139
+ ming 192.168.1.1 tcp 22,80,443
140
+
141
+ # TCP scan web ports across a subnet
142
+ ming 10.0.0.x tcp web
143
+
144
+ # TCP scan a port range
145
+ ming 10.0.0.x tcp 8000-8999
146
+
147
+ # UDP scan top 100 ports
148
+ ming 192.168.1.1 udp top100
149
+
150
+ # Scan a hostname
151
+ ming localhost tcp ssh,http,https
152
+
153
+ # Scan a domain
154
+ ming google.com tcp 80,443
155
+
156
+ # Scan multiple targets
157
+ ming 10.0.0.1,10.0.1.1 tcp web
158
+
159
+ # Skip hostname resolution
160
+ ming 192.168.1.x --no-resolve
161
+
162
+ # Machine-readable output
163
+ ming 192.168.1.x tcp web --output json
164
+
165
+ # Watch mode — re-scan every 60 seconds
166
+ ming 192.168.1.x --watch --interval 60
167
+ ```
168
+
169
+ ---
170
+
171
+ ## Output
172
+
173
+ Results are displayed as a live table that updates in real time. Only hosts that respond are shown. A summary line prints after the scan completes.
174
+
175
+ **ICMP mode**
176
+ ```
177
+ IP Address Hostname RTT (ms)
178
+ 192.168.1.1 router.local 0.8
179
+ 192.168.1.42 mypc.local 1.2
180
+ 192.168.1.101 nas.local 2.1
181
+
182
+ 3/256 hosts responded (1%) avg RTT 1.4ms — 3.2s
183
+ ```
184
+
185
+ **TCP mode**
186
+ ```
187
+ IP Address Hostname Open Ports
188
+ 192.168.1.1 router.local 80, 443
189
+ 192.168.1.42 mypc.local 22, 3306, 8080
190
+
191
+ 2 host(s) with open ports, 5 open port(s) total 256 hosts × 1000 ports — 8.1s
192
+ ```
193
+
194
+ **UDP mode**
195
+ ```
196
+ IP Address Hostname Reachable Responded Ports
197
+ 192.168.1.1 router.local ✓ 53, 161
198
+ 192.168.1.42 mypc.local ✓
199
+
200
+ 2 reachable host(s), 3 port(s) responded 256 hosts × 1000 ports — 12.4s
201
+ ```
202
+
203
+ > **UDP reachability** (`✓`) means an ICMP port-unreachable response was received — the host is up,
204
+ > but the port is closed. **Responded ports** are ports that sent actual UDP data back.
205
+
206
+ ---
207
+
208
+ ## Notes
209
+
210
+ - ICMP mode uses unprivileged sockets via [icmplib](https://github.com/ValentinBELYN/icmplib) — no root required on Linux/macOS. On Windows, ICMP requires Administrator privileges.
211
+ - TCP mode performs a full connect scan — no raw sockets, no root required.
212
+ - UDP mode uses `connect()` + `send()` and detects reachability from ICMP port-unreachable responses — no root required.
213
+ - Default concurrency limits: ICMP 150 · TCP 500 · UDP 200 simultaneous probes.
214
+ - Ctrl+C stops the scan immediately and prints results found so far.
mingping-0.1.0/README.md ADDED
@@ -0,0 +1,194 @@
1
+ # ming
2
+
3
+ A fast, async multi-ping network scanner with a live terminal UI.
4
+
5
+ ```
6
+ ming 192.168.1.x tcp 80,443,8000-8080
7
+ ```
8
+
9
+ ---
10
+
11
+ ## Features
12
+
13
+ - **Three scan modes** — ICMP ping, TCP connect, UDP probe
14
+ - **Flexible targets** — single IPs, CIDR ranges, wildcards, hostnames, domains, comma-separated lists
15
+ - **Flexible port specs** — individual ports, ranges, comma-separated lists, named ports, and group presets
16
+ - **Reverse DNS** — hostname lookup on responding IPs (on by default)
17
+ - **Live display** — results table builds in real time as hosts respond
18
+ - **Structured output** — `--output json` or `--output csv` for scripting
19
+ - **Watch mode** — re-scan on an interval, highlighting new hosts
20
+ - **Fast** — fully async with high concurrency; Ctrl+C exits immediately
21
+
22
+ ---
23
+
24
+ ## Installation
25
+
26
+ Requires Python 3.11+ and [uv](https://github.com/astral-sh/uv).
27
+
28
+ ```sh
29
+ git clone https://github.com/yourname/ming
30
+ cd ming
31
+ uv pip install -e .
32
+ ```
33
+
34
+ Then run with:
35
+
36
+ ```sh
37
+ ming <destination> [method] [ports]
38
+ ```
39
+
40
+ ---
41
+
42
+ ## Usage
43
+
44
+ ```
45
+ ming DESTINATION [METHOD] [PORT_SPEC] [OPTIONS]
46
+ ```
47
+
48
+ ### Destinations
49
+
50
+ | Format | Example | Description |
51
+ |---|---|---|
52
+ | Single IP | `192.168.1.1` | One host |
53
+ | CIDR range | `192.168.1.0/24` | 256 hosts |
54
+ | Wildcard | `192.168.1.x` | Same as `/24` |
55
+ | Wider wildcard | `192.168.x.x` | `/16` — 65,536 hosts |
56
+ | Hostname | `localhost` | Resolved via DNS |
57
+ | Domain | `google.com` | Resolved via DNS |
58
+ | Comma-separated | `10.0.0.1,10.0.1.1` | Multiple targets |
59
+
60
+ Wildcard octets can be written as `x`, `xx`, or `xxx` — they all mean the same thing.
61
+
62
+ ### Methods
63
+
64
+ | Method | Alias | Description |
65
+ |---|---|---|
66
+ | `icmp` | `ping` | ICMP echo request (default) |
67
+ | `tcp` | `syn` | TCP connect scan |
68
+ | `udp` | — | UDP probe |
69
+
70
+ ### Port specs *(TCP and UDP only)*
71
+
72
+ | Spec | Example | Description |
73
+ |---|---|---|
74
+ | Single port | `80` | One port |
75
+ | Range | `8000-8080` | Inclusive range |
76
+ | List | `80,443,8000-8080` | Mix of ports and ranges |
77
+ | `top100` | — | Top 100 most common ports |
78
+ | `top1000` | — | Top 1000 most common ports (default) |
79
+ | Named port | `http`, `ssh`, `postgres` | Single named port |
80
+ | Group preset | `web`, `db`, `remote` | Multiple related ports |
81
+
82
+ **Named ports:** `http`, `https`, `http-alt`, `https-alt`, `ssh`, `telnet`, `rdp`, `vnc`, `ftp`, `ftps`, `tftp`, `rsync`, `nfs`, `smb`, `netbios`, `smtp`, `smtps`, `submission`, `pop3`, `pop3s`, `imap`, `imaps`, `dns`, `snmp`, `ntp`, `ldap`, `ldaps`, `kerberos`, `sip`, `rtsp`, `mysql`, `postgres`, `mssql`, `oracle`, `redis`, `mongodb`, `memcached`, `cassandra`, `elasticsearch`, `docker`, `kubernetes`, `kafka`, `rabbitmq`, `prometheus`, `grafana`, `kibana`, `jenkins`, and more.
83
+
84
+ **Group presets:**
85
+
86
+ | Group | Ports |
87
+ |---|---|
88
+ | `web` | 80, 443, 8080, 8443, 8000, 8888, 8008, 8081, 3000 |
89
+ | `db` | 3306, 5432, 1433, 6379, 27017, 5984, 9200, 9042, 11211, 1521 |
90
+ | `remote` | 22, 23, 3389, 5900, 5901 |
91
+ | `mail` | 25, 110, 143, 465, 587, 993, 995 |
92
+ | `file` | 20, 21, 69, 139, 445, 873, 990, 2049 |
93
+ | `devops` | 2375, 2376, 6443, 9200, 5601, 9090, 9092, 2181, 3000, 8086, 2379 |
94
+
95
+ ### Options
96
+
97
+ | Option | Short | Description |
98
+ |---|---|---|
99
+ | `--resolve` / `--no-resolve` | `-r` / `-R` | Reverse DNS lookup on responding IPs (default: on) |
100
+ | `--quiet` | `-q` | No live display; print one line per responding host |
101
+ | `--output json\|csv` | `-o` | Structured output to stdout, disables live display |
102
+ | `--timeout SECS` | `-t` | Probe timeout in seconds (overrides per-protocol default) |
103
+ | `--concurrency N` | `-c` | Max concurrent probes (overrides per-protocol default) |
104
+ | `--watch` | `-w` | Re-scan repeatedly on `--interval` |
105
+ | `--interval SECS` | `-i` | Seconds between re-scans in watch mode (default: 30) |
106
+
107
+ ---
108
+
109
+ ## Examples
110
+
111
+ ```sh
112
+ # ICMP ping a whole subnet
113
+ ming 192.168.1.x
114
+
115
+ # TCP scan a host on common ports
116
+ ming 192.168.1.1 tcp
117
+
118
+ # TCP scan specific ports
119
+ ming 192.168.1.1 tcp 22,80,443
120
+
121
+ # TCP scan web ports across a subnet
122
+ ming 10.0.0.x tcp web
123
+
124
+ # TCP scan a port range
125
+ ming 10.0.0.x tcp 8000-8999
126
+
127
+ # UDP scan top 100 ports
128
+ ming 192.168.1.1 udp top100
129
+
130
+ # Scan a hostname
131
+ ming localhost tcp ssh,http,https
132
+
133
+ # Scan a domain
134
+ ming google.com tcp 80,443
135
+
136
+ # Scan multiple targets
137
+ ming 10.0.0.1,10.0.1.1 tcp web
138
+
139
+ # Skip hostname resolution
140
+ ming 192.168.1.x --no-resolve
141
+
142
+ # Machine-readable output
143
+ ming 192.168.1.x tcp web --output json
144
+
145
+ # Watch mode — re-scan every 60 seconds
146
+ ming 192.168.1.x --watch --interval 60
147
+ ```
148
+
149
+ ---
150
+
151
+ ## Output
152
+
153
+ Results are displayed as a live table that updates in real time. Only hosts that respond are shown. A summary line prints after the scan completes.
154
+
155
+ **ICMP mode**
156
+ ```
157
+ IP Address Hostname RTT (ms)
158
+ 192.168.1.1 router.local 0.8
159
+ 192.168.1.42 mypc.local 1.2
160
+ 192.168.1.101 nas.local 2.1
161
+
162
+ 3/256 hosts responded (1%) avg RTT 1.4ms — 3.2s
163
+ ```
164
+
165
+ **TCP mode**
166
+ ```
167
+ IP Address Hostname Open Ports
168
+ 192.168.1.1 router.local 80, 443
169
+ 192.168.1.42 mypc.local 22, 3306, 8080
170
+
171
+ 2 host(s) with open ports, 5 open port(s) total 256 hosts × 1000 ports — 8.1s
172
+ ```
173
+
174
+ **UDP mode**
175
+ ```
176
+ IP Address Hostname Reachable Responded Ports
177
+ 192.168.1.1 router.local ✓ 53, 161
178
+ 192.168.1.42 mypc.local ✓
179
+
180
+ 2 reachable host(s), 3 port(s) responded 256 hosts × 1000 ports — 12.4s
181
+ ```
182
+
183
+ > **UDP reachability** (`✓`) means an ICMP port-unreachable response was received — the host is up,
184
+ > but the port is closed. **Responded ports** are ports that sent actual UDP data back.
185
+
186
+ ---
187
+
188
+ ## Notes
189
+
190
+ - ICMP mode uses unprivileged sockets via [icmplib](https://github.com/ValentinBELYN/icmplib) — no root required on Linux/macOS. On Windows, ICMP requires Administrator privileges.
191
+ - TCP mode performs a full connect scan — no raw sockets, no root required.
192
+ - UDP mode uses `connect()` + `send()` and detects reachability from ICMP port-unreachable responses — no root required.
193
+ - Default concurrency limits: ICMP 150 · TCP 500 · UDP 200 simultaneous probes.
194
+ - Ctrl+C stops the scan immediately and prints results found so far.
mingping-0.1.0/main.py ADDED
@@ -0,0 +1,4 @@
1
+ from ming.cli import main
2
+
3
+ if __name__ == "__main__":
4
+ main()
mingping-0.1.0/ming/__init__.py ADDED
File without changes