cmtrl-netscope 1.0.0__py3-none-any.whl
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.
- cmtrl_netscope-1.0.0.dist-info/METADATA +160 -0
- cmtrl_netscope-1.0.0.dist-info/RECORD +11 -0
- cmtrl_netscope-1.0.0.dist-info/WHEEL +5 -0
- cmtrl_netscope-1.0.0.dist-info/entry_points.txt +2 -0
- cmtrl_netscope-1.0.0.dist-info/licenses/LICENSE +21 -0
- cmtrl_netscope-1.0.0.dist-info/top_level.txt +1 -0
- netscope/__init__.py +5 -0
- netscope/__main__.py +6 -0
- netscope/cli.py +220 -0
- netscope/scanner.py +217 -0
- netscope/utils.py +105 -0
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: cmtrl-netscope
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: A Python CLI for checking DNS records, TCP ports, and HTTP headers
|
|
5
|
+
Author: Ayoub Alshammari
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: GitHub profile, https://github.com/cmtrl
|
|
8
|
+
Project-URL: Repository, https://github.com/cmtrl/netscope
|
|
9
|
+
Project-URL: Issues, https://github.com/cmtrl/netscope/issues
|
|
10
|
+
Project-URL: Documentation, https://github.com/cmtrl/netscope/blob/main/docs/REFERENCE.md
|
|
11
|
+
Classifier: Environment :: Console
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Topic :: System :: Networking
|
|
14
|
+
Requires-Python: >=3.10
|
|
15
|
+
Description-Content-Type: text/markdown
|
|
16
|
+
License-File: LICENSE
|
|
17
|
+
Requires-Dist: aiohttp<4.0,>=3.12.14
|
|
18
|
+
Requires-Dist: dnspython<3.0,>=2.7.0
|
|
19
|
+
Requires-Dist: rich<15.0,>=13.9.4
|
|
20
|
+
Dynamic: license-file
|
|
21
|
+
|
|
22
|
+
# NetScope
|
|
23
|
+
|
|
24
|
+
A Python CLI for checking DNS records, common TCP ports, and HTTP headers.
|
|
25
|
+
|
|
26
|
+
By **Ayoub Alshammari** · [@cmtrl](https://github.com/cmtrl)
|
|
27
|
+
|
|
28
|
+
```text
|
|
29
|
+
_ _ _ ____
|
|
30
|
+
| \ | | ___| |_/ ___| ___ ___ _ __ ___
|
|
31
|
+
| \| |/ _ \ __\___ \ / __/ _ \| '_ \ / _ \
|
|
32
|
+
| |\ | __/ |_ ___) | (_| (_) | |_) | __/
|
|
33
|
+
|_| \_|\___|\__|____/ \___\___/| .__/ \___|
|
|
34
|
+
|_|
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
I'm using this project to work on Python networking, async code, and CLI design.
|
|
38
|
+
It's a starting point I plan to keep improving as I learn more about how these
|
|
39
|
+
checks work.
|
|
40
|
+
|
|
41
|
+
## What it does
|
|
42
|
+
|
|
43
|
+
- Looks up A, AAAA, MX, TXT, and NS records concurrently.
|
|
44
|
+
- Checks TCP ports `21`, `22`, `80`, `443`, `8080`, and `8443`.
|
|
45
|
+
- Fetches HTTP and HTTPS response headers.
|
|
46
|
+
- Checks for HSTS, CSP, and X-Frame-Options.
|
|
47
|
+
- Shows technology hints from headers such as `Server` and `X-Powered-By`.
|
|
48
|
+
- Displays results in the terminal and optionally saves them as JSON.
|
|
49
|
+
|
|
50
|
+
The checks run with `asyncio`, `aiohttp`, and `dnspython`. The terminal output
|
|
51
|
+
uses `rich`.
|
|
52
|
+
|
|
53
|
+
The package is being prepared for PyPI as `cmtrl-netscope`. The command stays
|
|
54
|
+
`netscope`. See the [publishing guide](https://github.com/cmtrl/netscope/blob/main/docs/PUBLISHING.md)
|
|
55
|
+
for the release setup.
|
|
56
|
+
|
|
57
|
+
## Setup
|
|
58
|
+
|
|
59
|
+
Requires Python **3.10 or newer**. No root privileges needed.
|
|
60
|
+
|
|
61
|
+
Download the source, open its folder, then run:
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
python -m venv .venv
|
|
65
|
+
source .venv/bin/activate
|
|
66
|
+
python -m pip install -r requirements.txt
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
On Windows PowerShell, activate with `.venv\Scripts\Activate.ps1` instead.
|
|
70
|
+
Use `python3` in place of `python` if that's how Python is installed on your system.
|
|
71
|
+
|
|
72
|
+
## Usage
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
python main.py -t example.com
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Save a JSON report:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
python main.py -t example.com -o json --output-file report.json
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Set a shorter timeout or change the number of concurrent TCP checks:
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
python main.py -t example.com --timeout 3 --concurrency 12
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
IP addresses work too. Forward DNS enumeration is skipped for IP targets:
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
python main.py -t 127.0.0.1
|
|
94
|
+
python main.py -t ::1
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Use a bare hostname or IP address, without `https://`, a path, or a port number.
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
python main.py --help
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
You can also install the command in your virtual environment:
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
python -m pip install .
|
|
107
|
+
netscope -t example.com
|
|
108
|
+
# Or: python -m netscope -t example.com
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
## A few things to know
|
|
112
|
+
|
|
113
|
+
Use this on systems you own or have permission to check.
|
|
114
|
+
|
|
115
|
+
An open port means a TCP connection succeeded. It doesn't confirm which service
|
|
116
|
+
is running. A missing security header isn't automatically a vulnerability, and
|
|
117
|
+
technology headers can be wrong.
|
|
118
|
+
|
|
119
|
+
HTTP checks use ports 80 and 443. Ports 8080 and 8443 get TCP checks only.
|
|
120
|
+
Redirects are shown without being followed, and HTTPS certificate verification
|
|
121
|
+
stays enabled. A failed check doesn't discard results from the other checks.
|
|
122
|
+
|
|
123
|
+
More detail on result states, timeouts, proxies, JSON fields, and exit codes is
|
|
124
|
+
in [docs/REFERENCE.md](https://github.com/cmtrl/netscope/blob/main/docs/REFERENCE.md).
|
|
125
|
+
|
|
126
|
+
## Working on the code
|
|
127
|
+
|
|
128
|
+
```text
|
|
129
|
+
main.py entry point
|
|
130
|
+
netscope/cli.py arguments and terminal output
|
|
131
|
+
netscope/scanner.py DNS, TCP, and HTTP checks
|
|
132
|
+
netscope/utils.py input validation and JSON export
|
|
133
|
+
tests/ tests using local servers and simulated failures
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Run the tests:
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
python -m unittest discover -s tests -v
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Optional development tools:
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
python -m pip install ruff build
|
|
146
|
+
ruff check .
|
|
147
|
+
python -m build
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Some things I'd like to work on next:
|
|
151
|
+
|
|
152
|
+
- Letting the user choose which ports to check.
|
|
153
|
+
- Making the output easier to skim when a host has several IP addresses.
|
|
154
|
+
- Adding more tests as I change the scanner.
|
|
155
|
+
|
|
156
|
+
If you find a bug or have a suggestion, an issue or pull request is welcome.
|
|
157
|
+
|
|
158
|
+
## License
|
|
159
|
+
|
|
160
|
+
[MIT](https://github.com/cmtrl/netscope/blob/main/LICENSE) · Copyright (c) 2026 Ayoub Alshammari (cmtrl).
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
cmtrl_netscope-1.0.0.dist-info/licenses/LICENSE,sha256=oV7JpnW5-irKHj7N592c4kwxqwXvP1__A_D0URl4mbg,1081
|
|
2
|
+
netscope/__init__.py,sha256=I9RmgfD80MA-bR6tVvivZQDCihvhfMd-aHX5Vw0wUgA,117
|
|
3
|
+
netscope/__main__.py,sha256=DSNQfefwmPLDJGKsh47tkhW5_tX6Q-UMOzdJDndFYSI,124
|
|
4
|
+
netscope/cli.py,sha256=qz6rkhiErCzCZBe3cJcI1wyPzzFj1z1v82xSvv9Mmvs,8554
|
|
5
|
+
netscope/scanner.py,sha256=IEPJuWsu94gpgRnF1IDKn2b9HLPF0tMacDPHAWt4URk,9528
|
|
6
|
+
netscope/utils.py,sha256=XUBk4FJmUH3AAm85p7KZ__o-we069lLeRTFfcT-BmOQ,3782
|
|
7
|
+
cmtrl_netscope-1.0.0.dist-info/METADATA,sha256=6LiqKxanW84IjcopdgOafPDYmhQPlPYS4-DZclO-jHI,4670
|
|
8
|
+
cmtrl_netscope-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
9
|
+
cmtrl_netscope-1.0.0.dist-info/entry_points.txt,sha256=RFucLFH8OZfhAErJBby0Wz4rtqUvD12Zq2IKF2JMAcA,47
|
|
10
|
+
cmtrl_netscope-1.0.0.dist-info/top_level.txt,sha256=r8hV7RXslJwUffLsNK4iv98ZRMewe1gN2Xit56pNSco,9
|
|
11
|
+
cmtrl_netscope-1.0.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ayoub Alshammari (cmtrl)
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
netscope
|
netscope/__init__.py
ADDED
netscope/__main__.py
ADDED
netscope/cli.py
ADDED
|
@@ -0,0 +1,220 @@
|
|
|
1
|
+
"""NetScope argument parsing and Rich presentation."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
import asyncio
|
|
7
|
+
from datetime import datetime, timezone
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
import os
|
|
10
|
+
import sys
|
|
11
|
+
from typing import Any
|
|
12
|
+
|
|
13
|
+
from rich.console import Console
|
|
14
|
+
from rich.panel import Panel
|
|
15
|
+
from rich.table import Table
|
|
16
|
+
from rich.text import Text
|
|
17
|
+
|
|
18
|
+
from .scanner import scan_target
|
|
19
|
+
from .utils import VERSION, normalize_target, positive_timeout, terminal_text, write_json
|
|
20
|
+
|
|
21
|
+
BANNER = r""" _ _ _ ____
|
|
22
|
+
| \ | | ___| |_/ ___| ___ ___ _ __ ___
|
|
23
|
+
| \| |/ _ \ __\___ \ / __/ _ \| '_ \ / _ \
|
|
24
|
+
| |\ | __/ |_ ___) | (_| (_) | |_) | __/
|
|
25
|
+
|_| \_|\___|\__|____/ \___\___/| .__/ \___|
|
|
26
|
+
|_|"""
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def validated_target(value: str) -> str:
|
|
30
|
+
try:
|
|
31
|
+
return normalize_target(value)
|
|
32
|
+
except ValueError as exc:
|
|
33
|
+
raise argparse.ArgumentTypeError(str(exc)) from exc
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def timeout_argument(value: str) -> float:
|
|
37
|
+
try:
|
|
38
|
+
return positive_timeout(value)
|
|
39
|
+
except ValueError as exc:
|
|
40
|
+
raise argparse.ArgumentTypeError(str(exc)) from exc
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def concurrency_argument(value: str) -> int:
|
|
44
|
+
try:
|
|
45
|
+
result = int(value)
|
|
46
|
+
except ValueError as exc:
|
|
47
|
+
raise argparse.ArgumentTypeError("concurrency must be an integer") from exc
|
|
48
|
+
if not 1 <= result <= 256:
|
|
49
|
+
raise argparse.ArgumentTypeError("concurrency must be between 1 and 256")
|
|
50
|
+
return result
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def build_parser() -> argparse.ArgumentParser:
|
|
54
|
+
parser = argparse.ArgumentParser(
|
|
55
|
+
prog="netscope",
|
|
56
|
+
description="NetScope — concurrent DNS, TCP, and HTTP reconnaissance.",
|
|
57
|
+
epilog="Example: python main.py -t example.com -o json --output-file report.json",
|
|
58
|
+
)
|
|
59
|
+
parser.add_argument(
|
|
60
|
+
"-t", "--target", required=True, type=validated_target, help="domain or IPv4/IPv6 address (no URL or port)"
|
|
61
|
+
)
|
|
62
|
+
parser.add_argument(
|
|
63
|
+
"--timeout",
|
|
64
|
+
type=timeout_argument,
|
|
65
|
+
default=5.0,
|
|
66
|
+
metavar="SECONDS",
|
|
67
|
+
help="per-operation timeout, 0.1–120 (default: 5)",
|
|
68
|
+
)
|
|
69
|
+
parser.add_argument(
|
|
70
|
+
"--concurrency",
|
|
71
|
+
type=concurrency_argument,
|
|
72
|
+
default=32,
|
|
73
|
+
metavar="N",
|
|
74
|
+
help="maximum concurrent TCP probes, 1–256 (default: 32)",
|
|
75
|
+
)
|
|
76
|
+
parser.add_argument("-o", "--output", choices=("json",), help="export results as JSON")
|
|
77
|
+
parser.add_argument(
|
|
78
|
+
"--output-file", type=Path, help="export destination; requires -o json (existing file is replaced)"
|
|
79
|
+
)
|
|
80
|
+
parser.add_argument("--no-color", action="store_true", help="disable terminal colors")
|
|
81
|
+
parser.add_argument("--version", action="version", version=f"NetScope {VERSION}")
|
|
82
|
+
return parser
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def safe(value: object) -> Text:
|
|
86
|
+
return Text(terminal_text(value))
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def status_text(value: str) -> Text:
|
|
90
|
+
color = {
|
|
91
|
+
"ok": "green",
|
|
92
|
+
"open": "green",
|
|
93
|
+
"present": "green",
|
|
94
|
+
"completed": "green",
|
|
95
|
+
"closed": "dim",
|
|
96
|
+
"skipped": "dim",
|
|
97
|
+
"not_applicable": "dim",
|
|
98
|
+
"no_answer": "dim",
|
|
99
|
+
"partial": "yellow",
|
|
100
|
+
"missing": "yellow",
|
|
101
|
+
"timeout": "yellow",
|
|
102
|
+
}.get(value, "red")
|
|
103
|
+
return Text(value.replace("_", " "), style=color)
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def render_report(console: Console, report: dict[str, Any]) -> None:
|
|
107
|
+
console.print(
|
|
108
|
+
Panel(
|
|
109
|
+
Text.assemble(
|
|
110
|
+
"Target: ",
|
|
111
|
+
safe(report["target"]),
|
|
112
|
+
" Status: ",
|
|
113
|
+
status_text(report["status"]),
|
|
114
|
+
f" Duration: {report['duration_seconds']:.3f}s",
|
|
115
|
+
),
|
|
116
|
+
title="Scan results",
|
|
117
|
+
border_style="cyan",
|
|
118
|
+
)
|
|
119
|
+
)
|
|
120
|
+
dns_result = report["dns"]
|
|
121
|
+
if dns_result["status"] == "skipped":
|
|
122
|
+
console.print(Panel(safe(dns_result["reason"]), title="DNS enumeration", border_style="dim"))
|
|
123
|
+
else:
|
|
124
|
+
table = Table(title="DNS enumeration", header_style="bold cyan", expand=True)
|
|
125
|
+
for column in ("Type", "State", "Records / details"):
|
|
126
|
+
table.add_column(column, overflow="fold")
|
|
127
|
+
for kind, result in dns_result["records"].items():
|
|
128
|
+
table.add_row(
|
|
129
|
+
kind,
|
|
130
|
+
status_text(result["status"]),
|
|
131
|
+
safe("\n".join(result["values"]) or result.get("error", "No records")),
|
|
132
|
+
)
|
|
133
|
+
console.print(table)
|
|
134
|
+
if dns_result.get("error"):
|
|
135
|
+
console.print(safe(dns_result["error"]), style="red")
|
|
136
|
+
|
|
137
|
+
ports = report["ports"]
|
|
138
|
+
table = Table(title="TCP port probe", header_style="bold cyan", expand=True)
|
|
139
|
+
for column in ("Address", "Port", "Service hint", "State", "ms / details"):
|
|
140
|
+
table.add_column(column, overflow="fold")
|
|
141
|
+
for result in ports["results"]:
|
|
142
|
+
table.add_row(
|
|
143
|
+
safe(result["address"]),
|
|
144
|
+
str(result["port"]),
|
|
145
|
+
result["service"],
|
|
146
|
+
status_text(result["status"]),
|
|
147
|
+
safe(f"{result['elapsed_ms']:.2f}" + (f" · {result['error']}" if "error" in result else "")),
|
|
148
|
+
)
|
|
149
|
+
console.print(table)
|
|
150
|
+
if ports["resolution"].get("error"):
|
|
151
|
+
console.print(safe(ports["resolution"]["error"]), style="red")
|
|
152
|
+
if ports["resolution"].get("truncated"):
|
|
153
|
+
console.print("Address limit reached: probing only the first 16 resolved addresses.", style="yellow")
|
|
154
|
+
|
|
155
|
+
for result in report["http"]["results"]:
|
|
156
|
+
console.print(Panel(safe(result["url"]), title="HTTP analysis", border_style="cyan"))
|
|
157
|
+
if result["status"] != "ok":
|
|
158
|
+
console.print(Text.assemble(status_text(result["status"]), ": ", safe(result["error"])))
|
|
159
|
+
continue
|
|
160
|
+
console.print(safe(f"HTTP {result['status_code']} {result['reason'] or ''} · {result['elapsed_ms']:.2f} ms"))
|
|
161
|
+
if result["redirect_location"]:
|
|
162
|
+
console.print(Text.assemble("Redirect (not followed): ", safe(result["redirect_location"])))
|
|
163
|
+
headers = Table(title="Response headers", header_style="bold cyan", expand=True)
|
|
164
|
+
headers.add_column("Header", overflow="fold")
|
|
165
|
+
headers.add_column("Value", overflow="fold")
|
|
166
|
+
for header in result["headers"]:
|
|
167
|
+
headers.add_row(safe(header["name"]), safe(header["value"]))
|
|
168
|
+
console.print(headers)
|
|
169
|
+
security = Table(title="Security header presence", header_style="bold cyan", expand=True)
|
|
170
|
+
security.add_column("Header")
|
|
171
|
+
security.add_column("State")
|
|
172
|
+
for item in result["security_headers"]:
|
|
173
|
+
security.add_row(item["header"], status_text(item["status"]))
|
|
174
|
+
console.print(security)
|
|
175
|
+
hints = "; ".join(f"{item['source']}: {item['value']}" for item in result["technologies"])
|
|
176
|
+
console.print(Text.assemble("Technology hints: ", safe(hints or "none declared")))
|
|
177
|
+
console.print(
|
|
178
|
+
"Service names are port hints; header presence and technology hints are not security verdicts.", style="dim"
|
|
179
|
+
)
|
|
180
|
+
|
|
181
|
+
|
|
182
|
+
def default_output(target: str) -> Path:
|
|
183
|
+
stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
|
|
184
|
+
return Path(f"netscope-{target.replace(':', '_')}-{stamp}.json")
|
|
185
|
+
|
|
186
|
+
|
|
187
|
+
def main(argv: list[str] | None = None) -> int:
|
|
188
|
+
parser = build_parser()
|
|
189
|
+
args = parser.parse_args(argv)
|
|
190
|
+
if args.output_file is not None and args.output is None:
|
|
191
|
+
parser.error("--output-file requires -o json")
|
|
192
|
+
console = Console(no_color=args.no_color)
|
|
193
|
+
error_console = Console(stderr=True, no_color=args.no_color)
|
|
194
|
+
try:
|
|
195
|
+
console.print(
|
|
196
|
+
Panel(
|
|
197
|
+
Text(BANNER, style="bold cyan"), subtitle=f"v{VERSION} · cmtrl · DNS / TCP / HTTP", border_style="cyan"
|
|
198
|
+
)
|
|
199
|
+
)
|
|
200
|
+
|
|
201
|
+
async def run() -> dict[str, Any]:
|
|
202
|
+
with console.status(Text.assemble("Scanning ", safe(args.target), "…"), spinner="dots"):
|
|
203
|
+
return await scan_target(args.target, args.timeout, args.concurrency)
|
|
204
|
+
|
|
205
|
+
report = asyncio.run(run())
|
|
206
|
+
render_report(console, report)
|
|
207
|
+
if args.output == "json":
|
|
208
|
+
destination = write_json(report, args.output_file or default_output(args.target))
|
|
209
|
+
console.print(Text.assemble("JSON saved: ", safe(destination)), style="green")
|
|
210
|
+
return 1 if report["status"] == "failed" else 0
|
|
211
|
+
except KeyboardInterrupt:
|
|
212
|
+
error_console.print("Scan cancelled.", style="yellow")
|
|
213
|
+
return 130
|
|
214
|
+
except BrokenPipeError:
|
|
215
|
+
# Avoid a second flush error when a pipeline consumer (e.g. head) exits.
|
|
216
|
+
sys.stdout = open(os.devnull, "w", encoding="utf-8")
|
|
217
|
+
return 0
|
|
218
|
+
except (OSError, ValueError) as exc:
|
|
219
|
+
error_console.print(Text.assemble("Error: ", safe(exc)), style="red")
|
|
220
|
+
return 1
|
netscope/scanner.py
ADDED
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
"""Bounded, asynchronous DNS, TCP, and HTTP reconnaissance."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import asyncio
|
|
6
|
+
from datetime import datetime, timezone
|
|
7
|
+
import errno
|
|
8
|
+
import ipaddress
|
|
9
|
+
import socket
|
|
10
|
+
import time
|
|
11
|
+
from typing import Any
|
|
12
|
+
|
|
13
|
+
import aiohttp
|
|
14
|
+
import dns.asyncresolver
|
|
15
|
+
import dns.exception
|
|
16
|
+
import dns.resolver
|
|
17
|
+
|
|
18
|
+
from .utils import COMMON_PORTS, SCHEMA_VERSION, SERVICES, VERSION, is_ip, normalize_target, url_host
|
|
19
|
+
|
|
20
|
+
DNS_TYPES = ("A", "AAAA", "MX", "TXT", "NS")
|
|
21
|
+
MAX_ADDRESSES = 16
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def utc_now() -> str:
|
|
25
|
+
return datetime.now(timezone.utc).isoformat(timespec="milliseconds")
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
async def enumerate_dns(target: str, timeout: float) -> dict[str, Any]:
|
|
29
|
+
if is_ip(target):
|
|
30
|
+
return {"status": "skipped", "reason": "IP target; forward DNS enumeration requires a hostname", "records": {}}
|
|
31
|
+
try:
|
|
32
|
+
resolver = dns.asyncresolver.Resolver()
|
|
33
|
+
except dns.exception.DNSException as exc:
|
|
34
|
+
return {"status": "error", "error": str(exc), "records": {}}
|
|
35
|
+
|
|
36
|
+
async def query(record_type: str) -> tuple[str, dict[str, Any]]:
|
|
37
|
+
try:
|
|
38
|
+
answer = await resolver.resolve(target, record_type, lifetime=timeout, search=False)
|
|
39
|
+
result = {"status": "ok", "values": sorted(record.to_text() for record in answer)}
|
|
40
|
+
except dns.resolver.NXDOMAIN:
|
|
41
|
+
result = {"status": "nxdomain", "values": [], "error": "DNS name does not exist"}
|
|
42
|
+
except dns.resolver.NoAnswer:
|
|
43
|
+
result = {"status": "no_answer", "values": []}
|
|
44
|
+
except (dns.exception.Timeout, asyncio.TimeoutError):
|
|
45
|
+
result = {"status": "timeout", "values": [], "error": "DNS query timed out"}
|
|
46
|
+
except (dns.exception.DNSException, OSError) as exc:
|
|
47
|
+
result = {"status": "error", "values": [], "error": str(exc)}
|
|
48
|
+
return record_type, result
|
|
49
|
+
|
|
50
|
+
records = dict(await asyncio.gather(*(query(kind) for kind in DNS_TYPES)))
|
|
51
|
+
statuses = {result["status"] for result in records.values()}
|
|
52
|
+
status = "ok" if statuses <= {"ok", "no_answer"} else "partial" if "ok" in statuses else "error"
|
|
53
|
+
return {"status": status, "records": records}
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
async def resolve_addresses(target: str, timeout: float) -> dict[str, Any]:
|
|
57
|
+
if is_ip(target):
|
|
58
|
+
return {"status": "ok", "addresses": [target], "truncated": False}
|
|
59
|
+
try:
|
|
60
|
+
addresses = await asyncio.wait_for(
|
|
61
|
+
asyncio.get_running_loop().getaddrinfo(target, None, type=socket.SOCK_STREAM),
|
|
62
|
+
timeout=timeout,
|
|
63
|
+
)
|
|
64
|
+
except asyncio.TimeoutError:
|
|
65
|
+
return {"status": "timeout", "addresses": [], "error": "Address resolution timed out"}
|
|
66
|
+
except OSError as exc:
|
|
67
|
+
return {"status": "error", "addresses": [], "error": str(exc)}
|
|
68
|
+
unique = sorted({entry[4][0] for entry in addresses}, key=lambda addr: (ipaddress.ip_address(addr).version, addr))
|
|
69
|
+
if not unique:
|
|
70
|
+
return {"status": "error", "addresses": [], "error": "No IPv4 or IPv6 addresses returned"}
|
|
71
|
+
return {"status": "ok", "addresses": unique[:MAX_ADDRESSES], "truncated": len(unique) > MAX_ADDRESSES}
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
async def probe_port(address: str, port: int, timeout: float, semaphore: asyncio.Semaphore) -> dict[str, Any]:
|
|
75
|
+
result: dict[str, Any] = {"address": address, "port": port, "service": SERVICES.get(port, "unknown")}
|
|
76
|
+
async with semaphore:
|
|
77
|
+
started = time.monotonic()
|
|
78
|
+
try:
|
|
79
|
+
family = socket.AF_INET6 if ":" in address else socket.AF_INET
|
|
80
|
+
with socket.socket(family, socket.SOCK_STREAM) as connection:
|
|
81
|
+
connection.setblocking(False)
|
|
82
|
+
endpoint = (address, port, 0, 0) if family == socket.AF_INET6 else (address, port)
|
|
83
|
+
await asyncio.wait_for(
|
|
84
|
+
asyncio.get_running_loop().sock_connect(connection, endpoint),
|
|
85
|
+
timeout=timeout,
|
|
86
|
+
)
|
|
87
|
+
result["status"] = "open"
|
|
88
|
+
except asyncio.TimeoutError:
|
|
89
|
+
result.update(status="timeout", error="TCP connect timed out; filtered or unreachable")
|
|
90
|
+
except OSError as exc:
|
|
91
|
+
if exc.errno == errno.ECONNREFUSED:
|
|
92
|
+
result["status"] = "closed"
|
|
93
|
+
else:
|
|
94
|
+
result.update(status="error", error=str(exc))
|
|
95
|
+
result["elapsed_ms"] = round((time.monotonic() - started) * 1000, 2)
|
|
96
|
+
return result
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
async def scan_ports(target: str, timeout: float, concurrency: int) -> dict[str, Any]:
|
|
100
|
+
resolution = await resolve_addresses(target, timeout)
|
|
101
|
+
if resolution["status"] != "ok":
|
|
102
|
+
return {"status": "error", "resolution": resolution, "results": []}
|
|
103
|
+
semaphore = asyncio.Semaphore(concurrency)
|
|
104
|
+
results = await asyncio.gather(
|
|
105
|
+
*(probe_port(address, port, timeout, semaphore) for address in resolution["addresses"] for port in COMMON_PORTS)
|
|
106
|
+
)
|
|
107
|
+
return {
|
|
108
|
+
"status": "partial"
|
|
109
|
+
if resolution.get("truncated") or any(result["status"] in {"error", "timeout"} for result in results)
|
|
110
|
+
else "ok",
|
|
111
|
+
"resolution": resolution,
|
|
112
|
+
"results": results,
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def analyze_headers(headers: Any, scheme: str) -> tuple[list[dict[str, Any]], list[dict[str, str]]]:
|
|
117
|
+
"""Presence checks and declared technology hints, not vulnerability claims."""
|
|
118
|
+
security = []
|
|
119
|
+
for name in ("Strict-Transport-Security", "Content-Security-Policy", "X-Frame-Options"):
|
|
120
|
+
values = headers.getall(name, [])
|
|
121
|
+
status = "present" if any(value.strip() for value in values) else "missing"
|
|
122
|
+
if name == "Strict-Transport-Security" and scheme != "https":
|
|
123
|
+
status = "not_applicable"
|
|
124
|
+
security.append({"header": name, "status": status, "values": values})
|
|
125
|
+
technologies = [
|
|
126
|
+
{"source": name, "value": value}
|
|
127
|
+
for name in ("Server", "X-Powered-By", "X-Generator", "Via")
|
|
128
|
+
for value in headers.getall(name, [])
|
|
129
|
+
if value.strip()
|
|
130
|
+
]
|
|
131
|
+
return security, technologies
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
async def fetch_http(session: aiohttp.ClientSession, url: str) -> dict[str, Any]:
|
|
135
|
+
result: dict[str, Any] = {"url": url}
|
|
136
|
+
started = time.monotonic()
|
|
137
|
+
try:
|
|
138
|
+
# GET supports servers that reject HEAD. Stop after headers; do not read a body.
|
|
139
|
+
async with session.get(url, allow_redirects=False) as response:
|
|
140
|
+
security, technologies = analyze_headers(response.headers, response.url.scheme)
|
|
141
|
+
result.update(
|
|
142
|
+
status="ok",
|
|
143
|
+
status_code=response.status,
|
|
144
|
+
reason=response.reason,
|
|
145
|
+
headers=[{"name": name, "value": value} for name, value in response.headers.items()],
|
|
146
|
+
security_headers=security,
|
|
147
|
+
technologies=technologies,
|
|
148
|
+
redirect_location=response.headers.get("Location") if 300 <= response.status < 400 else None,
|
|
149
|
+
)
|
|
150
|
+
response.close()
|
|
151
|
+
except asyncio.TimeoutError:
|
|
152
|
+
result.update(status="timeout", error="HTTP request timed out")
|
|
153
|
+
except aiohttp.ClientSSLError as exc:
|
|
154
|
+
result.update(status="tls_error", error=str(exc))
|
|
155
|
+
except (aiohttp.ClientError, OSError) as exc:
|
|
156
|
+
result.update(status="error", error=str(exc))
|
|
157
|
+
result["elapsed_ms"] = round((time.monotonic() - started) * 1000, 2)
|
|
158
|
+
return result
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
async def scan_http(target: str, timeout: float) -> dict[str, Any]:
|
|
162
|
+
connector = aiohttp.TCPConnector(limit=2, limit_per_host=2)
|
|
163
|
+
async with aiohttp.ClientSession(
|
|
164
|
+
connector=connector,
|
|
165
|
+
timeout=aiohttp.ClientTimeout(total=timeout),
|
|
166
|
+
headers={"User-Agent": f"NetScope/{VERSION}"},
|
|
167
|
+
cookie_jar=aiohttp.DummyCookieJar(),
|
|
168
|
+
trust_env=True,
|
|
169
|
+
auto_decompress=False,
|
|
170
|
+
) as session:
|
|
171
|
+
results = await asyncio.gather(
|
|
172
|
+
*(fetch_http(session, f"{scheme}://{url_host(target)}/") for scheme in ("https", "http"))
|
|
173
|
+
)
|
|
174
|
+
successes = sum(result["status"] == "ok" for result in results)
|
|
175
|
+
return {"status": "ok" if successes == 2 else "partial" if successes else "error", "results": results}
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
async def scan_target(target: str, timeout: float = 5.0, concurrency: int = 32) -> dict[str, Any]:
|
|
179
|
+
"""Scan a single validated target; retain independent failures in the report."""
|
|
180
|
+
target = normalize_target(target)
|
|
181
|
+
if not 0.1 <= timeout <= 120:
|
|
182
|
+
raise ValueError("timeout must be between 0.1 and 120 seconds")
|
|
183
|
+
if not 1 <= concurrency <= 256:
|
|
184
|
+
raise ValueError("concurrency must be between 1 and 256")
|
|
185
|
+
started = time.monotonic()
|
|
186
|
+
started_at = utc_now()
|
|
187
|
+
dns_result, ports, http = await asyncio.gather(
|
|
188
|
+
enumerate_dns(target, timeout),
|
|
189
|
+
scan_ports(target, timeout, concurrency),
|
|
190
|
+
scan_http(target, timeout),
|
|
191
|
+
)
|
|
192
|
+
usable = (
|
|
193
|
+
ports["resolution"]["status"] == "ok"
|
|
194
|
+
or any(record["status"] == "ok" for record in dns_result["records"].values())
|
|
195
|
+
or any(result["status"] == "ok" for result in http["results"])
|
|
196
|
+
)
|
|
197
|
+
status = (
|
|
198
|
+
"failed"
|
|
199
|
+
if not usable
|
|
200
|
+
else "partial"
|
|
201
|
+
if any(section["status"] not in {"ok", "skipped"} for section in (dns_result, ports, http))
|
|
202
|
+
else "completed"
|
|
203
|
+
)
|
|
204
|
+
return {
|
|
205
|
+
"schema_version": SCHEMA_VERSION,
|
|
206
|
+
"tool": {"name": "NetScope", "version": VERSION},
|
|
207
|
+
"target": target,
|
|
208
|
+
"target_type": "ip" if is_ip(target) else "hostname",
|
|
209
|
+
"started_at": started_at,
|
|
210
|
+
"finished_at": utc_now(),
|
|
211
|
+
"duration_seconds": round(time.monotonic() - started, 3),
|
|
212
|
+
"status": status,
|
|
213
|
+
"settings": {"timeout_seconds": timeout, "tcp_concurrency": concurrency, "ports": list(COMMON_PORTS)},
|
|
214
|
+
"dns": dns_result,
|
|
215
|
+
"ports": ports,
|
|
216
|
+
"http": http,
|
|
217
|
+
}
|
netscope/utils.py
ADDED
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
"""Input validation, safe terminal text, and durable JSON output."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import ipaddress
|
|
6
|
+
import json
|
|
7
|
+
import math
|
|
8
|
+
import os
|
|
9
|
+
from pathlib import Path
|
|
10
|
+
import re
|
|
11
|
+
import tempfile
|
|
12
|
+
import unicodedata
|
|
13
|
+
from typing import Any
|
|
14
|
+
|
|
15
|
+
VERSION = "1.0.0"
|
|
16
|
+
SCHEMA_VERSION = "1.0"
|
|
17
|
+
COMMON_PORTS = (21, 22, 80, 443, 8080, 8443)
|
|
18
|
+
SERVICES = {21: "FTP", 22: "SSH", 80: "HTTP", 443: "HTTPS", 8080: "HTTP-alt", 8443: "HTTPS-alt"}
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def normalize_target(value: str) -> str:
|
|
22
|
+
"""Accept one IP literal or DNS hostname; reject URLs, ports, and wildcards."""
|
|
23
|
+
target = value.strip()
|
|
24
|
+
if not target or any(char.isspace() for char in target):
|
|
25
|
+
raise ValueError("target must be one domain or IP address")
|
|
26
|
+
if target.startswith("[") and target.endswith("]"):
|
|
27
|
+
target = target[1:-1]
|
|
28
|
+
try:
|
|
29
|
+
address = ipaddress.IPv6Address(target)
|
|
30
|
+
except ValueError as exc:
|
|
31
|
+
raise ValueError("brackets must contain an IPv6 address") from exc
|
|
32
|
+
if address.scope_id:
|
|
33
|
+
raise ValueError("scoped IPv6 addresses are not supported")
|
|
34
|
+
return address.compressed
|
|
35
|
+
if "%" in target:
|
|
36
|
+
raise ValueError("scoped IPv6 addresses are not supported")
|
|
37
|
+
try:
|
|
38
|
+
return ipaddress.ip_address(target).compressed
|
|
39
|
+
except ValueError:
|
|
40
|
+
pass
|
|
41
|
+
if any(char in target for char in "/:@?#\\[]*"):
|
|
42
|
+
raise ValueError("use a bare domain or IP address, without a URL, port, or path")
|
|
43
|
+
try:
|
|
44
|
+
hostname = target.encode("idna").decode("ascii").lower().removesuffix(".")
|
|
45
|
+
except UnicodeError as exc:
|
|
46
|
+
raise ValueError("target is not a valid internationalized hostname") from exc
|
|
47
|
+
if re.fullmatch(r"[\d.]+", hostname):
|
|
48
|
+
raise ValueError("invalid IPv4 address")
|
|
49
|
+
labels = hostname.split(".")
|
|
50
|
+
if len(hostname) > 253 or any(not re.fullmatch(r"[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?", label) for label in labels):
|
|
51
|
+
raise ValueError("invalid hostname: use DNS labels of 1–63 letters, digits, or hyphens")
|
|
52
|
+
return hostname
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def is_ip(target: str) -> bool:
|
|
56
|
+
try:
|
|
57
|
+
ipaddress.ip_address(target)
|
|
58
|
+
return True
|
|
59
|
+
except ValueError:
|
|
60
|
+
return False
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def url_host(target: str) -> str:
|
|
64
|
+
return f"[{target}]" if ":" in target else target
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def positive_timeout(value: str) -> float:
|
|
68
|
+
try:
|
|
69
|
+
timeout = float(value)
|
|
70
|
+
except ValueError as exc:
|
|
71
|
+
raise ValueError("timeout must be a number") from exc
|
|
72
|
+
if not math.isfinite(timeout) or not 0.1 <= timeout <= 120:
|
|
73
|
+
raise ValueError("timeout must be between 0.1 and 120 seconds")
|
|
74
|
+
return timeout
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def terminal_text(value: object) -> str:
|
|
78
|
+
"""Remove terminal controls, including bidi controls, from untrusted values."""
|
|
79
|
+
return "".join(char if not unicodedata.category(char).startswith("C") else " " for char in str(value))
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def write_json(report: dict[str, Any], destination: Path) -> Path:
|
|
83
|
+
"""Atomically replace a report using a private, same-directory temp file."""
|
|
84
|
+
destination = destination.expanduser().absolute()
|
|
85
|
+
# Parents must exist; a typo should not silently create a directory tree.
|
|
86
|
+
payload = json.dumps(report, indent=2, ensure_ascii=False, allow_nan=False) + "\n"
|
|
87
|
+
temporary: str | None = None
|
|
88
|
+
try:
|
|
89
|
+
with tempfile.NamedTemporaryFile(
|
|
90
|
+
mode="w",
|
|
91
|
+
encoding="utf-8",
|
|
92
|
+
dir=destination.parent,
|
|
93
|
+
prefix=f".{destination.name}.",
|
|
94
|
+
suffix=".tmp",
|
|
95
|
+
delete=False,
|
|
96
|
+
) as stream:
|
|
97
|
+
temporary = stream.name
|
|
98
|
+
stream.write(payload)
|
|
99
|
+
stream.flush()
|
|
100
|
+
os.fsync(stream.fileno())
|
|
101
|
+
os.replace(temporary, destination)
|
|
102
|
+
finally:
|
|
103
|
+
if temporary is not None:
|
|
104
|
+
Path(temporary).unlink(missing_ok=True)
|
|
105
|
+
return destination
|