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.
@@ -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,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ netscope = netscope.cli:main
@@ -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
@@ -0,0 +1,5 @@
1
+ """NetScope network reconnaissance toolkit."""
2
+
3
+ from .utils import VERSION as __version__
4
+
5
+ __all__ = ["__version__"]
netscope/__main__.py ADDED
@@ -0,0 +1,6 @@
1
+ """Run NetScope with python -m netscope."""
2
+
3
+ from .cli import main
4
+
5
+ if __name__ == "__main__":
6
+ raise SystemExit(main())
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