inspectra-cli 2.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,102 @@
1
+ """Technology fingerprinting check.
2
+
3
+ Signatures live in ``data/fingerprints.json`` and match against response
4
+ headers, cookies, the HTML ``<meta name="generator">`` tag, and body content.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import re
10
+ from typing import Any
11
+
12
+ import httpx
13
+
14
+ from inspectra.checks.context import ScanContext
15
+ from inspectra.models import Confidence, Finding, Severity, Target
16
+ from inspectra.utils import load_json
17
+
18
+ GENERATOR_RE = re.compile(
19
+ r'<meta[^>]*name=["\']generator["\'][^>]*content=["\']([^"\']+)',
20
+ re.IGNORECASE,
21
+ )
22
+ VERSION_RE = re.compile(r"\d+(?:\.\d+){1,2}")
23
+ MAX_EVIDENCE = 12
24
+
25
+
26
+ def run(target: Target, context: ScanContext) -> list[Finding]:
27
+ """Identify technologies from the cached HTTP response."""
28
+ if context.http_response is None:
29
+ return []
30
+ response = context.http_response
31
+ detected: list[tuple[dict[str, Any], list[str]]] = []
32
+ for signature in load_json("fingerprints.json"):
33
+ evidence = _matches(signature, response)
34
+ if evidence:
35
+ detected.append((signature, evidence))
36
+ if not detected:
37
+ return []
38
+
39
+ labels = [
40
+ f"{signature['name']}{_version_suffix(evidence, signature)}"
41
+ for signature, evidence in detected
42
+ ]
43
+ evidence = [line for _, lines in detected for line in lines][:MAX_EVIDENCE]
44
+ return [
45
+ Finding(
46
+ rule_id="FPR-001",
47
+ title="Technologies identified",
48
+ category="fingerprinting",
49
+ severity=Severity.INFO,
50
+ confidence=Confidence.MEDIUM,
51
+ description=(
52
+ f"Identified the following technologies on {target.hostname}: {', '.join(labels)}."
53
+ ),
54
+ why_it_matters=(
55
+ "Known technologies help prioritize patching and reveal the stack "
56
+ "an attacker would study first."
57
+ ),
58
+ recommendation=(
59
+ "Keep all identified components patched and disable version "
60
+ "disclosure where possible."
61
+ ),
62
+ evidence=evidence,
63
+ )
64
+ ]
65
+
66
+
67
+ def _matches(signature: dict[str, Any], response: httpx.Response) -> list[str]:
68
+ evidence: list[str] = []
69
+ for pattern in signature["patterns"]:
70
+ pattern_type = pattern["type"]
71
+ if pattern_type == "header":
72
+ value = response.headers.get(pattern.get("name", ""))
73
+ if value and re.search(pattern["pattern"], value, re.IGNORECASE):
74
+ evidence.append(f"{pattern['name']}: {value}")
75
+ elif pattern_type == "cookie":
76
+ for cookie in response.headers.get_list("set-cookie"):
77
+ if re.search(pattern["pattern"], cookie, re.IGNORECASE):
78
+ evidence.append(f"Set-Cookie: {cookie}")
79
+ elif pattern_type == "generator":
80
+ match = GENERATOR_RE.search(response.text)
81
+ if match and re.search(pattern["pattern"], match.group(1), re.IGNORECASE):
82
+ evidence.append(f'<meta name="generator" content="{match.group(1)}">')
83
+ elif pattern_type == "body" and re.search(pattern["pattern"], response.text, re.IGNORECASE):
84
+ evidence.append(f"body: /{pattern['pattern']}/")
85
+ return evidence
86
+
87
+
88
+ def _version_suffix(evidence: list[str], signature: dict[str, Any]) -> str:
89
+ """Best-effort version extraction: the first dotted number *after a match*.
90
+
91
+ Evidence lines can merge values (e.g. a combined ``Server`` header), so
92
+ the search starts after the position matched by the signature's own
93
+ pattern to avoid borrowing another component's version.
94
+ """
95
+ for line in evidence:
96
+ for pattern in signature["patterns"]:
97
+ matched = re.search(pattern["pattern"], line, re.IGNORECASE)
98
+ if matched:
99
+ version = VERSION_RE.search(line[matched.end() :])
100
+ if version:
101
+ return f" {version.group(0)}"
102
+ return ""
@@ -0,0 +1,90 @@
1
+ """Security header assessment check.
2
+
3
+ The rules live in ``data/header_rules.json`` (versioned, reviewable, and easy
4
+ to extend without touching code). Rules support three outcomes:
5
+
6
+ * missing — the header is absent and should be present
7
+ * weak — the header is present but its value does not meet the rule pattern
8
+ * present — the header is present but should not be (e.g. X-Powered-By)
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import re
14
+ from typing import Any
15
+
16
+ import httpx
17
+
18
+ from inspectra.analysis.recommendations import remove_header
19
+ from inspectra.checks.context import ScanContext
20
+ from inspectra.models import Confidence, Finding, Severity, Target
21
+ from inspectra.utils import load_json
22
+
23
+
24
+ def run(target: Target, context: ScanContext) -> list[Finding]:
25
+ """Evaluate the security headers of the cached HTTP response."""
26
+ if context.http_response is None:
27
+ return []
28
+ findings: list[Finding] = []
29
+ for rule in load_json("header_rules.json"):
30
+ findings.extend(_evaluate_rule(rule, context.http_response.headers, target.hostname))
31
+ return findings
32
+
33
+
34
+ def _evaluate_rule(rule: dict[str, Any], headers: httpx.Headers, hostname: str) -> list[Finding]:
35
+ name = rule["name"]
36
+ value = headers.get(name)
37
+ if value is None:
38
+ if rule.get("severity_when_missing"):
39
+ return [_missing(rule, hostname)]
40
+ return []
41
+ if rule.get("severity_when_present"):
42
+ return [_present(rule, value, hostname)]
43
+ if rule.get("pattern") and not re.search(rule["pattern"], value, re.IGNORECASE):
44
+ return [_weak(rule, value, hostname)]
45
+ return []
46
+
47
+
48
+ def _missing(rule: dict[str, Any], hostname: str) -> Finding:
49
+ return Finding(
50
+ rule_id=rule["id"],
51
+ title=f"Missing security header: {rule['name']}",
52
+ category="security_headers",
53
+ severity=Severity(rule["severity_when_missing"]),
54
+ confidence=Confidence.MEDIUM,
55
+ description=f"The {rule['name']} response header was not present on {hostname}.",
56
+ why_it_matters=rule["explanation"],
57
+ recommendation=rule["recommendation"],
58
+ evidence=["Header not present in the HTTP response"],
59
+ )
60
+
61
+
62
+ def _weak(rule: dict[str, Any], value: str, hostname: str) -> Finding:
63
+ return Finding(
64
+ rule_id=rule["id"],
65
+ title=f"Weak security header value: {rule['name']}",
66
+ category="security_headers",
67
+ severity=Severity(rule.get("severity_when_weak", "low")),
68
+ confidence=Confidence.MEDIUM,
69
+ description=(
70
+ f"The {rule['name']} header on {hostname} is present but its value "
71
+ "does not meet the recommended configuration."
72
+ ),
73
+ why_it_matters=rule["explanation"],
74
+ recommendation=rule["recommendation"],
75
+ evidence=[f"{rule['name']}: {value}"],
76
+ )
77
+
78
+
79
+ def _present(rule: dict[str, Any], value: str, hostname: str) -> Finding:
80
+ return Finding(
81
+ rule_id=rule["id"],
82
+ title=f"Header should be removed: {rule['name']}",
83
+ category="security_headers",
84
+ severity=Severity(rule["severity_when_present"]),
85
+ confidence=Confidence.HIGH,
86
+ description=f"The {rule['name']} header is present on {hostname}.",
87
+ why_it_matters=rule["explanation"],
88
+ recommendation=remove_header(rule["name"]),
89
+ evidence=[f"{rule['name']}: {value}"],
90
+ )
@@ -0,0 +1,301 @@
1
+ """HTTP analysis check: fetches the primary page and robots.txt.
2
+
3
+ All connections are IP-pinned: the target hostname is resolved once via
4
+ ``safety.validate_target`` and every subsequent request connects to that IP
5
+ with the original hostname sent as the ``Host`` header and as the TLS SNI
6
+ name. This prevents DNS rebinding between validation and connect. Every
7
+ redirect hop is re-resolved and re-pinned the same way.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import re
13
+ from urllib.parse import urljoin, urlparse
14
+
15
+ import httpx
16
+
17
+ from inspectra.analysis.recommendations import remove_header
18
+ from inspectra.checks import CheckError
19
+ from inspectra.checks.context import ScanContext
20
+ from inspectra.models import Confidence, Finding, Severity, Target
21
+ from inspectra.network import build_client
22
+ from inspectra.safety import validate_redirect, validate_target
23
+
24
+ SERVER_VERSION_RE = re.compile(r"\d+(?:\.\d+)+")
25
+ MAX_REDIRECT_EVIDENCE = 6
26
+ MAX_REDIRECT_HOPS = 5
27
+
28
+
29
+ def _pinned_url(
30
+ pinned_ip: str,
31
+ scheme: str,
32
+ port: int | None,
33
+ path: str = "/",
34
+ ) -> str:
35
+ """Build a URL that connects to ``pinned_ip``; the caller sets Host/SNI."""
36
+ port_part = f":{port}" if port else ""
37
+ path_part = path if path else "/"
38
+ return f"{scheme}://{pinned_ip}{port_part}{path_part}"
39
+
40
+
41
+ def _pinned_get(
42
+ client: httpx.Client,
43
+ url: str,
44
+ hostname: str,
45
+ pinned_ip: str,
46
+ ) -> httpx.Response:
47
+ """GET ``url`` connecting to ``pinned_ip`` with Host + SNI set to ``hostname``.
48
+
49
+ SNI is only set for HTTPS URLs; for HTTP we set the Host header and let
50
+ httpx use plain TCP (avoiding spurious TLS handshakes on HTTP servers).
51
+ The query string is preserved and the Host header keeps any non-default port.
52
+ """
53
+ parsed = urlparse(url)
54
+ path = f"{parsed.path or '/'}?{parsed.query}" if parsed.query else (parsed.path or "/")
55
+ pinned = _pinned_url(pinned_ip, parsed.scheme, parsed.port, path)
56
+ host_header = parsed.netloc.rsplit("@", 1)[-1]
57
+ kwargs: dict = {"headers": {"Host": host_header}}
58
+ if parsed.scheme == "https":
59
+ kwargs["extensions"] = {"sni_hostname": hostname}
60
+ return client.get(pinned, **kwargs)
61
+
62
+
63
+ def run(target: Target, context: ScanContext) -> list[Finding]:
64
+ """Fetch the target over HTTP(S), store responses, and report observations."""
65
+ client = context.client or build_client()
66
+ allow_private = context.options.allow_private if context.options else False
67
+ authorized = context.options.authorized if context.options else False
68
+ replay_dir = context.options.replay_dir if context.options else None
69
+ response, scheme = _fetch_primary(client, target, allow_private, authorized, replay_dir)
70
+ context.http_response = response
71
+ target.scheme = scheme
72
+
73
+ findings: list[Finding] = []
74
+ if scheme == "https":
75
+ findings.extend(
76
+ _check_https_redirect(client, target, allow_private, authorized, replay_dir)
77
+ )
78
+ findings.extend(_transport_findings(response))
79
+ server = response.headers.get("server")
80
+ if server:
81
+ findings.append(_server_header(server))
82
+ _fetch_robots(client, target, context, allow_private, authorized, replay_dir)
83
+ return findings
84
+
85
+
86
+ def _fetch_primary(
87
+ client: httpx.Client,
88
+ target: Target,
89
+ allow_private: bool = False,
90
+ authorized: bool = False,
91
+ replay_dir: str | None = None,
92
+ ) -> tuple[httpx.Response, str]:
93
+ """Fetch the target, trying the preferred scheme first and the other as fallback.
94
+
95
+ Validates the initial target for SSRF safety (unless in replay mode),
96
+ then manually follows redirects with per-hop validation.
97
+ """
98
+ schemes = [target.scheme]
99
+ other = "http" if target.scheme == "https" else "https"
100
+ schemes.append(other)
101
+ last_error: Exception | None = None
102
+ for scheme in schemes:
103
+ url = _url_for(target, scheme)
104
+ try:
105
+ # Validate initial target for SSRF safety; get pinned IP.
106
+ # Skip validation in replay mode (no DNS lookups allowed).
107
+ if replay_dir:
108
+ pinned_ip = target.hostname # use hostname directly in replay
109
+ else:
110
+ pinned_ip = validate_target(target.hostname, allow_private, authorized)
111
+ response = _follow_redirects(
112
+ client, url, target.hostname, pinned_ip, allow_private, authorized, replay_dir
113
+ )
114
+ return response, scheme
115
+ except httpx.RequestError as exc:
116
+ last_error = exc
117
+ raise CheckError(f"Could not reach {target.hostname} over HTTP or HTTPS: {last_error}")
118
+
119
+
120
+ def _url_for(target: Target, scheme: str) -> str:
121
+ port = f":{target.port}" if target.port else ""
122
+ return f"{scheme}://{target.hostname}{port}"
123
+
124
+
125
+ def _follow_redirects(
126
+ client: httpx.Client,
127
+ url: str,
128
+ hostname: str,
129
+ pinned_ip: str,
130
+ allow_private: bool,
131
+ authorized: bool,
132
+ replay_dir: str | None = None,
133
+ max_hops: int = MAX_REDIRECT_HOPS,
134
+ ) -> httpx.Response:
135
+ """Manually follow HTTP redirects with per-hop SSRF validation and re-pinning.
136
+
137
+ httpx is configured with follow_redirects=False, so we handle redirects
138
+ ourselves. Each hop is re-resolved and re-pinned via safety.validate_target
139
+ to prevent DNS rebinding across hops.
140
+ """
141
+ current_url = url
142
+ current_hostname = hostname
143
+ current_ip = pinned_ip
144
+ for hop in range(1, max_hops + 1):
145
+ response = _pinned_get(client, current_url, current_hostname, current_ip)
146
+ if response.is_redirect:
147
+ location = response.headers.get("location")
148
+ if not location:
149
+ return response
150
+ next_url = urljoin(current_url, location)
151
+ # Validate this redirect hop before following it.
152
+ next_url = validate_redirect(
153
+ next_url, current_url.split("://")[0], allow_private, authorized, hop, max_hops
154
+ )
155
+ next_parsed = urlparse(next_url)
156
+ next_hostname = next_parsed.hostname or current_hostname
157
+ # Re-resolve and re-pin the redirect target's IP.
158
+ # Skip validation in replay mode.
159
+ if replay_dir:
160
+ current_ip = next_hostname
161
+ else:
162
+ current_ip = validate_target(next_hostname, allow_private, authorized)
163
+ current_hostname = next_hostname
164
+ current_url = next_url
165
+ else:
166
+ return response
167
+ # If we exhausted max hops, return the last response (may still be a redirect).
168
+ return _pinned_get(client, current_url, current_hostname, current_ip)
169
+
170
+
171
+ def _check_https_redirect(
172
+ client: httpx.Client,
173
+ target: Target,
174
+ allow_private: bool = False,
175
+ authorized: bool = False,
176
+ replay_dir: str | None = None,
177
+ ) -> list[Finding]:
178
+ """Verify that plain HTTP redirects to HTTPS when HTTPS is available."""
179
+ try:
180
+ if replay_dir:
181
+ pinned_ip = target.hostname
182
+ else:
183
+ pinned_ip = validate_target(target.hostname, allow_private, authorized)
184
+ response = _pinned_get(client, _url_for(target, "http"), target.hostname, pinned_ip)
185
+ except httpx.RequestError:
186
+ return [] # plain HTTP unavailable; nothing to redirect
187
+ if response.url.scheme == "https":
188
+ return []
189
+ return [
190
+ Finding(
191
+ rule_id="HTP-001",
192
+ title="Plain HTTP does not redirect to HTTPS",
193
+ category="http",
194
+ severity=Severity.MEDIUM,
195
+ confidence=Confidence.MEDIUM,
196
+ description=(
197
+ f"Requesting http://{target.hostname} returned status "
198
+ f"{response.status_code} without redirecting to HTTPS."
199
+ ),
200
+ why_it_matters=(
201
+ "Users and links that use plain HTTP can be intercepted or modified "
202
+ "(downgrade attack) unless traffic is redirected to TLS."
203
+ ),
204
+ recommendation=(
205
+ "Configure the web server to issue a 301 redirect from HTTP to "
206
+ "HTTPS for all resources."
207
+ ),
208
+ evidence=[f"GET http://{target.hostname} -> {response.status_code} {response.url}"],
209
+ )
210
+ ]
211
+
212
+
213
+ def _transport_findings(response: httpx.Response) -> list[Finding]:
214
+ findings: list[Finding] = []
215
+ if response.history:
216
+ chain = [
217
+ f"{hop.status_code} {hop.headers.get('location', hop.url)}" for hop in response.history
218
+ ]
219
+ chain.append(f"{response.status_code} {response.url}")
220
+ findings.append(
221
+ Finding(
222
+ rule_id="HTP-002",
223
+ title="Redirect chain detected",
224
+ category="http",
225
+ severity=Severity.INFO,
226
+ confidence=Confidence.HIGH,
227
+ description=(
228
+ f"The initial request followed {len(response.history)} redirect(s) "
229
+ "before reaching the final resource."
230
+ ),
231
+ why_it_matters=(
232
+ "Long or mixed-scheme redirect chains can leak information and slow "
233
+ "users down; verify each hop is intentional."
234
+ ),
235
+ recommendation="Minimize redirect hops and ensure every hop uses HTTPS.",
236
+ evidence=chain[:MAX_REDIRECT_EVIDENCE],
237
+ )
238
+ )
239
+ if response.status_code >= 400:
240
+ findings.append(
241
+ Finding(
242
+ rule_id="HTP-004",
243
+ title="Root path returned an error status",
244
+ category="http",
245
+ severity=Severity.LOW,
246
+ confidence=Confidence.MEDIUM,
247
+ description=f"GET {response.url} returned HTTP {response.status_code}.",
248
+ why_it_matters=(
249
+ "An error status on the root path may indicate misconfiguration or "
250
+ "that the service is not intended for direct access."
251
+ ),
252
+ recommendation=(
253
+ "Verify the application serves its intended content on the root path."
254
+ ),
255
+ evidence=[f"GET {response.url} -> {response.status_code}"],
256
+ )
257
+ )
258
+ return findings
259
+
260
+
261
+ def _server_header(server: str) -> Finding:
262
+ versioned = bool(SERVER_VERSION_RE.search(server))
263
+ return Finding(
264
+ rule_id="HTP-003",
265
+ title="Web server software disclosed" + (" (with version)" if versioned else ""),
266
+ category="http",
267
+ severity=Severity.INFO,
268
+ confidence=Confidence.HIGH,
269
+ description=f"The server disclosed its software via the Server header: {server!r}.",
270
+ why_it_matters=(
271
+ "Version numbers help attackers identify known vulnerabilities. Even "
272
+ "without a version, the software name narrows the attack surface."
273
+ ),
274
+ recommendation=remove_header("Server"),
275
+ evidence=[f"Server: {server}"],
276
+ )
277
+
278
+
279
+ def _fetch_robots(
280
+ client: httpx.Client,
281
+ target: Target,
282
+ context: ScanContext,
283
+ allow_private: bool = False,
284
+ authorized: bool = False,
285
+ replay_dir: str | None = None,
286
+ ) -> None:
287
+ """Fetch robots.txt so the robots check can analyze it without re-fetching."""
288
+ try:
289
+ if replay_dir:
290
+ pinned_ip = target.hostname
291
+ else:
292
+ pinned_ip = validate_target(target.hostname, allow_private, authorized)
293
+ response = _pinned_get(
294
+ client,
295
+ f"{_url_for(target, target.scheme)}/robots.txt",
296
+ target.hostname,
297
+ pinned_ip,
298
+ )
299
+ context.robots_response = response
300
+ except httpx.RequestError:
301
+ context.robots_response = None
@@ -0,0 +1,179 @@
1
+ """Port discovery check: wraps Nmap for safe, passive TCP scanning."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import shutil
6
+ from dataclasses import dataclass
7
+
8
+ from inspectra.analysis.recommendations import restrict_service
9
+ from inspectra.checks import CheckError, FatalCheckError
10
+ from inspectra.checks.context import ScanContext
11
+ from inspectra.models import Confidence, Finding, Severity, Target
12
+
13
+ SENSITIVE_SERVICES = {
14
+ "ftp": Severity.MEDIUM,
15
+ "telnet": Severity.HIGH,
16
+ "rlogin": Severity.HIGH,
17
+ "rsh": Severity.HIGH,
18
+ "vnc": Severity.MEDIUM,
19
+ "rdp": Severity.MEDIUM,
20
+ "smb": Severity.MEDIUM,
21
+ "snmp": Severity.MEDIUM,
22
+ "tftp": Severity.MEDIUM,
23
+ "nfs": Severity.MEDIUM,
24
+ "smtp": Severity.LOW,
25
+ "pop3": Severity.LOW,
26
+ "imap": Severity.LOW,
27
+ }
28
+
29
+ HOST_TIMEOUT = "90s"
30
+
31
+
32
+ @dataclass(slots=True)
33
+ class OpenPort:
34
+ """A single open TCP port reported by Nmap."""
35
+
36
+ number: int
37
+ service: str
38
+ product: str = ""
39
+ version: str = ""
40
+
41
+
42
+ def run(target: Target, context: ScanContext) -> list[Finding]:
43
+ """Scan open TCP ports with Nmap and report the results."""
44
+ if context.options is not None and context.options.skip_ports:
45
+ return []
46
+ if shutil.which("nmap") is None:
47
+ raise FatalCheckError(
48
+ "Nmap is required for port discovery but was not found on PATH. "
49
+ "Install it (see docs/usage.md) or re-run with --skip-ports."
50
+ )
51
+ try:
52
+ import nmap
53
+ except ImportError as exc:
54
+ raise FatalCheckError(
55
+ "The python-nmap package is not installed. Reinstall Inspectra with "
56
+ "its dependencies (pip install -e .)."
57
+ ) from exc
58
+
59
+ return _scan(target, context, nmap.PortScanner())
60
+
61
+
62
+ def _scan(target: Target, context: ScanContext, scanner: object) -> list[Finding]:
63
+ """Run the scan with the given scanner (injected so tests can pass a fake)."""
64
+ try:
65
+ scanner.scan( # type: ignore[attr-defined]
66
+ hosts=target.hostname,
67
+ ports=_port_spec(context),
68
+ arguments=_arguments(context),
69
+ )
70
+ except Exception as exc: # python-nmap raises broad exceptions on scan failure
71
+ raise CheckError(f"Nmap scan failed for {target.hostname}: {exc}") from exc
72
+
73
+ open_ports = _collect_open_ports(scanner, target.hostname)
74
+ if not open_ports:
75
+ return [_no_open_ports(target, context)]
76
+ findings = [_open_ports_summary(target, open_ports)]
77
+ for port in open_ports:
78
+ if port.service in SENSITIVE_SERVICES:
79
+ findings.append(_sensitive_service(port))
80
+ return findings
81
+
82
+
83
+ def _port_spec(context: ScanContext) -> str | None:
84
+ if context.options is not None and context.options.ports:
85
+ return context.options.ports
86
+ return None
87
+
88
+
89
+ def _arguments(context: ScanContext) -> str:
90
+ arguments = f"-sV --host-timeout {HOST_TIMEOUT}"
91
+ if _port_spec(context) is None:
92
+ top_ports = context.options.top_ports if context.options is not None else 1000
93
+ arguments += f" --top-ports {top_ports}"
94
+ return arguments
95
+
96
+
97
+ def _collect_open_ports(scanner: object, hostname: str) -> list[OpenPort]:
98
+ """Extract open ports from a python-nmap scanner (duck-typed for tests)."""
99
+ try:
100
+ hosts = scanner.all_hosts() # type: ignore[attr-defined]
101
+ except Exception:
102
+ return []
103
+ if hostname not in hosts:
104
+ return []
105
+ ports: list[OpenPort] = []
106
+ host_result = scanner[hostname] # type: ignore[index]
107
+ for proto in host_result.all_protocols():
108
+ for number, info in host_result[proto].items():
109
+ if info.get("state") == "open":
110
+ ports.append(
111
+ OpenPort(
112
+ number=number,
113
+ service=info.get("name", "unknown"),
114
+ product=info.get("product", ""),
115
+ version=info.get("version", ""),
116
+ )
117
+ )
118
+ return sorted(ports, key=lambda port: port.number)
119
+
120
+
121
+ def _no_open_ports(target: Target, context: ScanContext) -> Finding:
122
+ return Finding(
123
+ rule_id="PRT-001",
124
+ title="No open TCP ports detected",
125
+ category="ports",
126
+ severity=Severity.INFO,
127
+ confidence=Confidence.MEDIUM,
128
+ description=f"Nmap found no open TCP ports on {target.hostname} within the scanned range.",
129
+ why_it_matters=(
130
+ "A host with no open ports has a small attack surface, but firewalls "
131
+ "may be hiding services from the scanner."
132
+ ),
133
+ recommendation=(
134
+ "If services are expected, verify firewall rules and re-scan a wider port range."
135
+ ),
136
+ evidence=[f"nmap {target.hostname} {_arguments(context)}"],
137
+ )
138
+
139
+
140
+ def _open_ports_summary(target: Target, open_ports: list[OpenPort]) -> Finding:
141
+ return Finding(
142
+ rule_id="PRT-002",
143
+ title=f"{len(open_ports)} open TCP port(s) detected",
144
+ category="ports",
145
+ severity=Severity.INFO,
146
+ confidence=Confidence.HIGH,
147
+ description=f"Nmap identified {len(open_ports)} open TCP port(s) on {target.hostname}.",
148
+ why_it_matters=(
149
+ "Every open port is a potential entry point. Review each service for "
150
+ "exposure and keep them patched."
151
+ ),
152
+ recommendation="Close ports that are not needed and restrict the rest with firewall rules.",
153
+ evidence=[_format_port(port) for port in open_ports],
154
+ )
155
+
156
+
157
+ def _sensitive_service(port: OpenPort) -> Finding:
158
+ return Finding(
159
+ rule_id="PRT-003",
160
+ title=f"Sensitive service exposed: {port.service} (port {port.number})",
161
+ category="ports",
162
+ severity=SENSITIVE_SERVICES[port.service],
163
+ confidence=Confidence.MEDIUM,
164
+ description=(
165
+ f"Port {port.number} runs {port.service}, a service that is frequently "
166
+ "targeted when exposed."
167
+ ),
168
+ why_it_matters=(
169
+ "Services like FTP, Telnet, RDP and SMB transmit credentials insecurely "
170
+ "or are common attack targets when reachable from the internet."
171
+ ),
172
+ recommendation=restrict_service(port.service, port.number),
173
+ evidence=[_format_port(port)],
174
+ )
175
+
176
+
177
+ def _format_port(port: OpenPort) -> str:
178
+ product = f" ({port.product} {port.version})".rstrip() if port.product else ""
179
+ return f"{port.number}/tcp {port.service}{product}"