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.
- inspectra/__init__.py +6 -0
- inspectra/__main__.py +6 -0
- inspectra/analysis/__init__.py +1 -0
- inspectra/analysis/recommendations.py +40 -0
- inspectra/analysis/risk.py +61 -0
- inspectra/baseline.py +94 -0
- inspectra/checks/__init__.py +79 -0
- inspectra/checks/context.py +29 -0
- inspectra/checks/directories.py +126 -0
- inspectra/checks/dns.py +141 -0
- inspectra/checks/fingerprint.py +102 -0
- inspectra/checks/headers.py +90 -0
- inspectra/checks/http.py +301 -0
- inspectra/checks/ports.py +179 -0
- inspectra/checks/robots.py +120 -0
- inspectra/checks/tls.py +212 -0
- inspectra/cli.py +413 -0
- inspectra/data/directory_wordlist.txt +170 -0
- inspectra/data/fingerprints.json +156 -0
- inspectra/data/header_rules.json +77 -0
- inspectra/models.py +138 -0
- inspectra/network.py +113 -0
- inspectra/orchestrator.py +145 -0
- inspectra/py.typed +0 -0
- inspectra/redact.py +92 -0
- inspectra/replay.py +195 -0
- inspectra/report/__init__.py +1 -0
- inspectra/report/html_report.py +69 -0
- inspectra/report/json_report.py +75 -0
- inspectra/report/markdown_report.py +86 -0
- inspectra/report/sarif_report.py +136 -0
- inspectra/report/templates/report.html.j2 +145 -0
- inspectra/safety.py +217 -0
- inspectra/utils.py +116 -0
- inspectra_cli-2.0.0.dist-info/METADATA +468 -0
- inspectra_cli-2.0.0.dist-info/RECORD +39 -0
- inspectra_cli-2.0.0.dist-info/WHEEL +4 -0
- inspectra_cli-2.0.0.dist-info/entry_points.txt +3 -0
- inspectra_cli-2.0.0.dist-info/licenses/LICENSE +21 -0
|
@@ -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
|
+
)
|
inspectra/checks/http.py
ADDED
|
@@ -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}"
|