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,120 @@
1
+ """robots.txt inspection check.
2
+
3
+ The standard library's ``robotparser`` cannot list disallowed paths, so this
4
+ check uses a small purpose-built parser for the subset of the robots.txt
5
+ format that matters for assessment.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from dataclasses import dataclass, field
11
+
12
+ from inspectra.checks.context import ScanContext
13
+ from inspectra.models import Confidence, Finding, Severity, Target
14
+
15
+ MAX_DISALLOWED_EVIDENCE = 15
16
+
17
+
18
+ @dataclass(slots=True)
19
+ class RobotsInfo:
20
+ """Parsed subset of a robots.txt file."""
21
+
22
+ user_agents: list[str] = field(default_factory=list)
23
+ disallowed: list[str] = field(default_factory=list)
24
+ allowed: list[str] = field(default_factory=list)
25
+ sitemaps: list[str] = field(default_factory=list)
26
+
27
+
28
+ def parse_robots(text: str) -> RobotsInfo:
29
+ """Parse the directives that matter for assessment."""
30
+ info = RobotsInfo()
31
+ current_agents: list[str] = []
32
+ for raw_line in text.splitlines():
33
+ line = raw_line.strip()
34
+ if not line or line.startswith("#"):
35
+ continue
36
+ key, _, value = line.partition(":")
37
+ key, value = key.strip().lower(), value.strip()
38
+ if key == "user-agent":
39
+ current_agents = [value] if value else []
40
+ elif key == "disallow" and value:
41
+ info.disallowed.append(value)
42
+ if current_agents and current_agents[0] not in info.user_agents:
43
+ info.user_agents.append(current_agents[0])
44
+ elif key == "allow" and value:
45
+ info.allowed.append(value)
46
+ elif key == "sitemap" and value:
47
+ info.sitemaps.append(value)
48
+ return info
49
+
50
+
51
+ def run(target: Target, context: ScanContext) -> list[Finding]:
52
+ """Analyze the robots.txt response cached by the HTTP check."""
53
+ if context.robots_response is None:
54
+ return []
55
+ response = context.robots_response
56
+ if response.status_code == 404 or not response.text.strip():
57
+ return [_missing(target)]
58
+ info = parse_robots(response.text)
59
+ findings: list[Finding] = []
60
+ if info.disallowed:
61
+ findings.append(_disallowed(target, info))
62
+ if info.sitemaps:
63
+ findings.append(_sitemap(info))
64
+ return findings
65
+
66
+
67
+ def _missing(target: Target) -> Finding:
68
+ return Finding(
69
+ rule_id="ROB-001",
70
+ title="robots.txt not found",
71
+ category="robots",
72
+ severity=Severity.INFO,
73
+ confidence=Confidence.MEDIUM,
74
+ description=f"GET {target.base_url}/robots.txt returned HTTP 404 (not found).",
75
+ why_it_matters=(
76
+ "robots.txt is a courtesy for crawlers; its absence is not a "
77
+ "vulnerability, but it may be intentional or an oversight."
78
+ ),
79
+ recommendation=(
80
+ "Add a robots.txt if you want to control crawler access. "
81
+ "Note that it is not a security control."
82
+ ),
83
+ evidence=["GET /robots.txt -> 404"],
84
+ )
85
+
86
+
87
+ def _disallowed(target: Target, info: RobotsInfo) -> Finding:
88
+ return Finding(
89
+ rule_id="ROB-002",
90
+ title="robots.txt disallows crawler access to paths",
91
+ category="robots",
92
+ severity=Severity.INFO,
93
+ confidence=Confidence.HIGH,
94
+ description=(f"robots.txt disallows {len(info.disallowed)} path(s) from crawlers."),
95
+ why_it_matters=(
96
+ "Disallowed paths are excluded from search engines, not from "
97
+ "attackers. Anything listed here should be reviewed for exposure."
98
+ ),
99
+ recommendation=(
100
+ "Review the disallowed paths: sensitive content should be protected by "
101
+ "authentication, not just robots.txt."
102
+ ),
103
+ evidence=info.disallowed[:MAX_DISALLOWED_EVIDENCE],
104
+ )
105
+
106
+
107
+ def _sitemap(info: RobotsInfo) -> Finding:
108
+ return Finding(
109
+ rule_id="ROB-003",
110
+ title="Sitemap referenced in robots.txt",
111
+ category="robots",
112
+ severity=Severity.INFO,
113
+ confidence=Confidence.HIGH,
114
+ description=f"robots.txt references {len(info.sitemaps)} sitemap location(s).",
115
+ why_it_matters=(
116
+ "Sitemaps expose the site structure to crawlers (and to anyone reading robots.txt)."
117
+ ),
118
+ recommendation="Confirm the sitemap does not list sensitive or unpublished URLs.",
119
+ evidence=info.sitemaps[:MAX_DISALLOWED_EVIDENCE],
120
+ )
@@ -0,0 +1,212 @@
1
+ """TLS verification check: inspects the certificate and protocol version."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import ssl
6
+
7
+ from inspectra.analysis.recommendations import renew_certificate
8
+ from inspectra.checks import CheckError
9
+ from inspectra.checks.context import ScanContext
10
+ from inspectra.models import Confidence, Finding, Severity, Target
11
+ from inspectra.network import TlsInfo, inspect_tls
12
+
13
+ WARN_EXPIRY_DAYS = 30
14
+ CRITICAL_EXPIRY_DAYS = 7
15
+ MIN_TLS_RANK = 1.2 # TLS 1.2
16
+
17
+
18
+ def run(target: Target, context: ScanContext) -> list[Finding]:
19
+ """Perform a TLS handshake and report certificate and protocol findings."""
20
+ port = target.port if target.port not in (None, 80) else 443
21
+ try:
22
+ info = inspect_tls(target.hostname, port)
23
+ except (TimeoutError, ssl.SSLError, ssl.CertificateError, OSError) as exc:
24
+ if target.scheme == "http":
25
+ return [_https_unavailable(target, port, exc)]
26
+ raise CheckError(f"TLS inspection failed for {target.hostname}: {exc}") from exc
27
+
28
+ context.tls = info
29
+ findings: list[Finding] = []
30
+ if info.is_expired:
31
+ findings.append(_expired(info))
32
+ elif info.days_remaining <= CRITICAL_EXPIRY_DAYS:
33
+ findings.append(_expires_soon(info, critical=True))
34
+ elif info.days_remaining <= WARN_EXPIRY_DAYS:
35
+ findings.append(_expires_soon(info, critical=False))
36
+ if info.is_self_signed:
37
+ findings.append(_self_signed(info))
38
+ if not info.hostname_matches:
39
+ findings.append(_hostname_mismatch(info))
40
+ rank = _version_rank(info.version)
41
+ if rank < MIN_TLS_RANK:
42
+ findings.append(_weak_protocol(info))
43
+ elif rank == MIN_TLS_RANK:
44
+ findings.append(_tls12_only(info))
45
+ findings.append(_certificate_summary(info))
46
+ return findings
47
+
48
+
49
+ def _https_unavailable(target: Target, port: int, exc: Exception) -> Finding:
50
+ return Finding(
51
+ rule_id="TLS-001",
52
+ title="HTTPS not available",
53
+ category="tls",
54
+ severity=Severity.MEDIUM,
55
+ confidence=Confidence.HIGH,
56
+ description=(f"Could not establish a TLS connection to {target.hostname}:{port}: {exc}"),
57
+ why_it_matters=(
58
+ "Without HTTPS, all traffic — including credentials — is transmitted in plaintext."
59
+ ),
60
+ recommendation="Enable TLS on the server and redirect HTTP traffic to HTTPS.",
61
+ evidence=[f"TLS handshake to {target.hostname}:{port} failed"],
62
+ )
63
+
64
+
65
+ def _expired(info: TlsInfo) -> Finding:
66
+ return Finding(
67
+ rule_id="TLS-002",
68
+ title="TLS certificate is expired",
69
+ category="tls",
70
+ severity=Severity.HIGH,
71
+ confidence=Confidence.HIGH,
72
+ description=(
73
+ f"The certificate for this host expired on "
74
+ f"{info.not_valid_after:%Y-%m-%d} and is no longer trusted by clients."
75
+ ),
76
+ why_it_matters=(
77
+ "Expired certificates break encryption for users and can indicate "
78
+ "neglected infrastructure."
79
+ ),
80
+ recommendation=renew_certificate(0),
81
+ evidence=[f"Not valid after: {info.not_valid_after:%Y-%m-%d}"],
82
+ )
83
+
84
+
85
+ def _expires_soon(info: TlsInfo, critical: bool) -> Finding:
86
+ severity = Severity.HIGH if critical else Severity.MEDIUM
87
+ return Finding(
88
+ rule_id="TLS-003",
89
+ title=f"TLS certificate expires soon ({info.days_remaining} days)",
90
+ category="tls",
91
+ severity=severity,
92
+ confidence=Confidence.HIGH,
93
+ description=(
94
+ f"The certificate expires on {info.not_valid_after:%Y-%m-%d} "
95
+ f"({info.days_remaining} days from now)."
96
+ ),
97
+ why_it_matters="Certificates that expire cause service outages and break trust for users.",
98
+ recommendation=renew_certificate(info.days_remaining),
99
+ evidence=[f"Not valid after: {info.not_valid_after:%Y-%m-%d}"],
100
+ )
101
+
102
+
103
+ def _self_signed(info: TlsInfo) -> Finding:
104
+ return Finding(
105
+ rule_id="TLS-004",
106
+ title="TLS certificate is self-signed",
107
+ category="tls",
108
+ severity=Severity.HIGH,
109
+ confidence=Confidence.MEDIUM,
110
+ description="The presented certificate is self-signed and not issued by a trusted CA.",
111
+ why_it_matters=(
112
+ "Self-signed certificates do not protect against man-in-the-middle "
113
+ "attacks unless clients are configured to pin them."
114
+ ),
115
+ recommendation=(
116
+ "Obtain a certificate from a public CA (e.g. Let's Encrypt) or pin "
117
+ "the certificate on all clients."
118
+ ),
119
+ evidence=[f"Issuer: {info.issuer}", f"Subject: {info.subject_cn}"],
120
+ )
121
+
122
+
123
+ def _hostname_mismatch(info: TlsInfo) -> Finding:
124
+ return Finding(
125
+ rule_id="TLS-005",
126
+ title="TLS certificate hostname mismatch",
127
+ category="tls",
128
+ severity=Severity.HIGH,
129
+ confidence=Confidence.MEDIUM,
130
+ description=(
131
+ "The certificate does not cover the hostname being scanned "
132
+ f"(SANs: {', '.join(info.san_dns) or 'none'})."
133
+ ),
134
+ why_it_matters=(
135
+ "A certificate for the wrong hostname triggers browser warnings and can "
136
+ "signal a misconfigured or intercepted connection."
137
+ ),
138
+ recommendation="Issue a certificate that includes the scanned hostname in its SANs.",
139
+ evidence=[
140
+ f"Subject CN: {info.subject_cn}",
141
+ f"SANs: {', '.join(info.san_dns) or 'none'}",
142
+ ],
143
+ )
144
+
145
+
146
+ def _weak_protocol(info: TlsInfo) -> Finding:
147
+ return Finding(
148
+ rule_id="TLS-006",
149
+ title="Weak TLS protocol version in use",
150
+ category="tls",
151
+ severity=Severity.HIGH,
152
+ confidence=Confidence.HIGH,
153
+ description=f"The server negotiated {info.version}, which is below TLS 1.2.",
154
+ why_it_matters=(
155
+ "TLS 1.0 and 1.1 have known protocol weaknesses and are deprecated; "
156
+ "modern clients may refuse to connect."
157
+ ),
158
+ recommendation="Disable TLS 1.0/1.1 and require TLS 1.2 or newer.",
159
+ evidence=[f"Negotiated protocol: {info.version}"],
160
+ )
161
+
162
+
163
+ def _tls12_only(info: TlsInfo) -> Finding:
164
+ return Finding(
165
+ rule_id="TLS-007",
166
+ title="TLS 1.2 in use; TLS 1.3 recommended",
167
+ category="tls",
168
+ severity=Severity.INFO,
169
+ confidence=Confidence.HIGH,
170
+ description=f"The server negotiated {info.version}. TLS 1.3 is preferred where supported.",
171
+ why_it_matters=(
172
+ "TLS 1.3 removes legacy algorithms and improves handshake security and performance."
173
+ ),
174
+ recommendation="Enable TLS 1.3 in addition to TLS 1.2.",
175
+ evidence=[f"Negotiated protocol: {info.version}"],
176
+ )
177
+
178
+
179
+ def _certificate_summary(info: TlsInfo) -> Finding:
180
+ return Finding(
181
+ rule_id="TLS-008",
182
+ title="TLS certificate details",
183
+ category="tls",
184
+ severity=Severity.INFO,
185
+ confidence=Confidence.HIGH,
186
+ description="Summary of the certificate presented during the TLS handshake.",
187
+ why_it_matters="Certificate details help confirm the identity and health of the service.",
188
+ recommendation="None required; informational.",
189
+ evidence=[
190
+ f"Protocol: {info.version}",
191
+ f"Cipher: {info.cipher}",
192
+ f"Subject CN: {info.subject_cn}",
193
+ f"Issuer: {info.issuer}",
194
+ f"Valid from: {info.not_valid_before:%Y-%m-%d}",
195
+ f"Valid until: {info.not_valid_after:%Y-%m-%d}",
196
+ f"SANs: {', '.join(info.san_dns) or 'none'}",
197
+ ],
198
+ )
199
+
200
+
201
+ def _version_rank(version: str) -> float:
202
+ """Turn a protocol string like 'TLSv1.3' into a comparable number."""
203
+ if version.startswith("SSLv"):
204
+ return 0.0
205
+ digits = version.removeprefix("TLSv")
206
+ try:
207
+ numbers = [int(part) for part in digits.split(".")]
208
+ except ValueError:
209
+ return 0.0
210
+ if len(numbers) >= 2:
211
+ return float(f"{numbers[0]}.{numbers[1]}")
212
+ return float(numbers[0])