@teevee98/synapse-hub 4.1.4 → 4.2.1
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.
- package/.agents/rules/git-push-protocol.md +2 -2
- package/.agents/skills/01-web-automation/auth-session-and-cookie-manager/SKILL.md +52 -3
- package/.agents/skills/01-web-automation/bats-testing-patterns/SKILL.md +55 -5
- package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +62 -67
- package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +54 -4
- package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +62 -12
- package/.agents/skills/01-web-automation/lam-script-generator/SKILL.md +55 -8
- package/.agents/skills/01-web-automation/mobile-appium-som/SKILL.md +60 -12
- package/.agents/skills/01-web-automation/mobile-appium-som/examples/BaseScreen.java +2 -2
- package/.agents/skills/01-web-automation/mobile-appium-som/examples/LoginScreen.java +2 -2
- package/.agents/skills/01-web-automation/mobile-appium-som/examples/TC_MobileLogin.java +2 -2
- package/.agents/skills/01-web-automation/playwright-live-interaction/SKILL.md +54 -91
- package/.agents/skills/01-web-automation/playwright-webapp-testing/SKILL.md +59 -11
- package/.agents/skills/01-web-automation/web-agent-gym-benchmarking/SKILL.md +50 -4
- package/.agents/skills/02-test-design/architecture-decision-records/SKILL.md +55 -9
- package/.agents/skills/02-test-design/gherkin-to-suite/SKILL.md +55 -9
- package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +55 -8
- package/.agents/skills/02-test-design/review-spec/SKILL.md +50 -6
- package/.agents/skills/02-test-design/tot-exploratory-testing/SKILL.md +50 -4
- package/.agents/skills/03-api-and-contracts/api-network-mocking-interception/SKILL.md +56 -5
- package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +53 -7
- package/.agents/skills/03-api-and-contracts/consumer-driven-contract-testing/SKILL.md +86 -36
- package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +54 -6
- package/.agents/skills/04-performance-and-load/lean-impact-scoreboard/SKILL.md +50 -6
- package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +50 -3
- package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +63 -14
- package/.agents/skills/05-security-and-compliance/skillspector-security-guard/SKILL.md +51 -5
- package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +54 -4
- package/.agents/skills/06-healing-and-resilience/agentless-qa-repair/SKILL.md +51 -5
- package/.agents/skills/06-healing-and-resilience/antigravity-test-sentinel/SKILL.md +53 -6
- package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +54 -8
- package/.agents/skills/06-healing-and-resilience/flaky-test-sentinel-and-quarantine/SKILL.md +60 -24
- package/.agents/skills/06-healing-and-resilience/self-healing-locator/SKILL.md +52 -6
- package/.agents/skills/06-healing-and-resilience/systematic-debugging/SKILL.md +56 -10
- package/.agents/skills/06-healing-and-resilience/test-driven-development/SKILL.md +58 -12
- package/.agents/skills/06-healing-and-resilience/verification-before-completion/SKILL.md +58 -12
- package/.agents/skills/06-healing-and-resilience/visual-regression-sentinel/SKILL.md +53 -5
- package/.agents/skills/07-data-and-state/db-state-verifier-and-seeder/SKILL.md +56 -5
- package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +53 -4
- package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +58 -5
- package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/SKILL.md +57 -11
- package/.agents/skills/08-code-quality/graphify-impact-analyzer/SKILL.md +83 -34
- package/.agents/skills/08-code-quality/graphify-impact-analyzer/examples/dependency_blast_radius.json +3 -4
- package/.agents/skills/08-code-quality/lean-code-ladder/SKILL.md +55 -10
- package/.agents/skills/08-code-quality/repo-quality-audit/SKILL.md +49 -6
- package/.agents/skills/08-code-quality/senior-code-review/SKILL.md +52 -7
- package/.agents/skills/08-code-quality/surgical-coding-principles/SKILL.md +55 -10
- package/.agents/skills/08-code-quality/technical-debt-harvester/SKILL.md +51 -5
- package/.agents/skills/09-ci-and-devops/github-actions-templates/SKILL.md +54 -17
- package/.agents/skills/09-ci-and-devops/github-actions-templates/examples/matrix_test_pipeline.yml +2 -1
- package/.agents/skills/10-agent-orchestration/actor-qa-swarm/SKILL.md +50 -4
- package/.agents/skills/10-agent-orchestration/agent-orchestration-multi-agent-optimize/SKILL.md +53 -7
- package/.agents/skills/10-agent-orchestration/event-stream-qa-orchestrator/SKILL.md +50 -4
- package/.agents/skills/10-agent-orchestration/persistent-planning-files/SKILL.md +58 -13
- package/.agents/skills/10-agent-orchestration/qa-memory-os/SKILL.md +51 -5
- package/.agents/skills/11-ai-and-prompting/meta-prompt-crafter/SKILL.md +57 -10
- package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +50 -4
- package/.agents/skills/11-ai-and-prompting/qa-aci-interface/SKILL.md +50 -4
- package/.agents/skills/11-ai-and-prompting/token-and-context-optimizer/SKILL.md +55 -9
- package/.cursor/rules/synapse-qa.mdc +20 -7
- package/.cursorrules +19 -5
- package/.windsurfrules +18 -3
- package/AGENTS.md +51 -59
- package/CLAUDE.md +38 -24
- package/LICENSE +5 -5
- package/NOTICE +1 -1
- package/README.en.md +4 -4
- package/README.md +4 -4
- package/agentskills.json +1 -1
- package/docs/ARCHITECTURE.en.md +2 -2
- package/docs/ARCHITECTURE.md +11 -2
- package/docs/CLIENT_SUPPORT_MATRIX.md +44 -0
- package/docs/CLI_REFERENCE.en.md +6 -4
- package/docs/CLI_REFERENCE.md +1 -1
- package/docs/CONTRIBUTING.en.md +1 -1
- package/docs/CONTRIBUTING.md +2 -2
- package/docs/SIDE_EFFECTING_TOOLS_INVENTORY.md +233 -0
- package/docs/TOOL_CATALOG.md +6 -2
- package/docs/research/agent_skill_training_analysis.md +1 -1
- package/package.json +1 -1
- package/plugin.json +1 -1
- package/skills_manifest.json +320 -55
- package/synapse.config.json +1 -1
- package/templates/ai_bridges/CLAUDE.md +29 -26
- package/templates/ai_bridges/copilot-instructions.md +14 -5
- package/templates/ai_bridges/cursor_synapse_qa.mdc +16 -7
- package/templates/ai_bridges/windsurfrules +14 -3
- package/templates/ui/index.html +2 -2
- package/tools/TOOLS_RUNBOOK.md +1 -1
- package/tools/TOOL_CATALOG.json +63 -3
- package/tools/__init__.py +1 -1
- package/tools/api_fuzzer.py +447 -132
- package/tools/author_integrity.py +121 -11
- package/tools/benchmark_swarm_context.py +130 -22
- package/tools/break_ui_generator.py +233 -0
- package/tools/browser_helpers.js +2 -2
- package/tools/check_version_sync.py +18 -50
- package/tools/cli.py +110 -19
- package/tools/core/bm25_retriever.py +218 -0
- package/tools/core/i18n.py +5 -5
- package/tools/core/provider_usage_adapter.py +383 -0
- package/tools/core/token_estimator.py +81 -15
- package/tools/count_tokens.py +7 -2
- package/tools/coverage_reporter.py +245 -0
- package/tools/dashboard_generator.py +8 -8
- package/tools/db_sandbox.py +290 -9
- package/tools/distill_log.py +1 -1
- package/tools/distill_skill.py +206 -0
- package/tools/git_pre_commit_guard.py +202 -1
- package/tools/humanize_linter.py +3 -0
- package/tools/mcp_docx_server.py +1 -1
- package/tools/mcp_excel_server.py +1 -1
- package/tools/mcp_server.py +104 -16
- package/tools/micro_mutator.py +114 -15
- package/tools/pentest_scope_guard.py +674 -58
- package/tools/perf/benchmark_perf_runner.py +42 -0
- package/tools/project_state.py +29 -5
- package/tools/reversible_sandbox.py +58 -13
- package/tools/rules_router.py +473 -60
- package/tools/security_scanner.py +80 -0
- package/tools/senior_code_review.py +14 -0
- package/tools/skill_canonical_digest.py +302 -0
- package/tools/skill_profiles.py +77 -7
- package/tools/slide_deck_exporter.py +477 -0
- package/tools/sync_agent_rules.py +187 -61
- package/tools/sync_skills_manifest.py +166 -0
- package/tools/task_memory_manager.py +275 -0
- package/tools/ui_server.py +3 -1
- package/tools/update_sentinel.py +3 -3
- package/tools/validate_host_interop.py +485 -0
- package/tools/validate_skills_schema.py +575 -0
- package/tools/verify_all.py +668 -44
- package/tools/welcome_page.py +2 -2
|
@@ -30,8 +30,16 @@ import json
|
|
|
30
30
|
import socket
|
|
31
31
|
import ipaddress
|
|
32
32
|
import urllib.parse
|
|
33
|
+
import urllib.request
|
|
34
|
+
import urllib.error
|
|
35
|
+
import http.client
|
|
36
|
+
import ssl
|
|
37
|
+
import uuid
|
|
38
|
+
import secrets
|
|
39
|
+
import fnmatch
|
|
40
|
+
from dataclasses import dataclass
|
|
33
41
|
from datetime import datetime, timezone
|
|
34
|
-
from typing import List, Tuple, Optional
|
|
42
|
+
from typing import List, Tuple, Optional, Set, Any, Dict
|
|
35
43
|
|
|
36
44
|
# Enforce UTF-8 stdout encoding for Windows console compatibility
|
|
37
45
|
if hasattr(sys.stdout, "reconfigure"):
|
|
@@ -44,6 +52,51 @@ if hasattr(sys.stdout, "reconfigure"):
|
|
|
44
52
|
REPO_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
|
|
45
53
|
DEFAULT_AUDIT_LOG = os.path.join(REPO_ROOT, ".synapse", "pentest_audit.log")
|
|
46
54
|
|
|
55
|
+
# Sensitive infrastructure ports that must NEVER be targeted (SSRF prevention)
|
|
56
|
+
SENSITIVE_INFRASTRUCTURE_PORTS: Set[int] = {
|
|
57
|
+
20, 21, # FTP
|
|
58
|
+
22, # SSH
|
|
59
|
+
23, # Telnet
|
|
60
|
+
25, # SMTP
|
|
61
|
+
53, # DNS
|
|
62
|
+
69, # TFTP
|
|
63
|
+
79, # Finger
|
|
64
|
+
110, # POP3
|
|
65
|
+
137, 138, 139, # NetBIOS
|
|
66
|
+
143, # IMAP
|
|
67
|
+
445, # SMB
|
|
68
|
+
3306, # MySQL
|
|
69
|
+
3389, # RDP
|
|
70
|
+
5432, # PostgreSQL
|
|
71
|
+
6379, # Redis
|
|
72
|
+
11211, # Memcached
|
|
73
|
+
27017, # MongoDB
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
ALLOWED_SCHEMES: Set[str] = {"http", "https"}
|
|
77
|
+
|
|
78
|
+
# Regex patterns for masking credentials, tokens, and authorization secrets
|
|
79
|
+
SECRET_PARAM_PATTERNS = [
|
|
80
|
+
# Basic auth passwords in URLs: http://user:pass@host -> http://user:***REDACTED***@host
|
|
81
|
+
(re.compile(r"(://[^:]+:)([^@]+)(@)"), r"\g<1>***REDACTED***\g<3>"),
|
|
82
|
+
# Sensitive query parameters: token, key, secret, password, bearer, auth, etc.
|
|
83
|
+
(re.compile(r"([?&](?:token|key|api_key|apikey|secret|password|passwd|pwd|bearer|auth|sessionid|access_token)=)[^&]*", re.IGNORECASE), r"\g<1>***REDACTED***"),
|
|
84
|
+
# Authorization header Bearer tokens: Bearer xyz -> Bearer ***REDACTED***
|
|
85
|
+
(re.compile(r"(Bearer\s+)[A-Za-z0-9_\-\.]+", re.IGNORECASE), r"\g<1>***REDACTED***"),
|
|
86
|
+
# JSON / key-value fields: "password": "...", "token": "..."
|
|
87
|
+
(re.compile(r'("?(?:password|token|secret|apiKey|api_key|access_token)"?\s*[:=]\s*)"[^"]*"', re.IGNORECASE), r'\g<1>"***REDACTED***"'),
|
|
88
|
+
]
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def mask_secrets(text: str) -> str:
|
|
92
|
+
"""Redacts passwords, tokens, API keys, and sensitive auth data using regex."""
|
|
93
|
+
if not text or not isinstance(text, str):
|
|
94
|
+
return text
|
|
95
|
+
masked = text
|
|
96
|
+
for pattern, replacement in SECRET_PARAM_PATTERNS:
|
|
97
|
+
masked = pattern.sub(replacement, masked)
|
|
98
|
+
return masked
|
|
99
|
+
|
|
47
100
|
# Keywords in hostnames strictly treated as production targets
|
|
48
101
|
PRODUCTION_HOST_PATTERNS = [
|
|
49
102
|
r"^prod\.",
|
|
@@ -65,6 +118,264 @@ class PentestScopeError(RuntimeError):
|
|
|
65
118
|
pass
|
|
66
119
|
|
|
67
120
|
|
|
121
|
+
class PathContainmentError(PentestScopeError):
|
|
122
|
+
"""Raised when an operation escapes designated sandbox path containment boundaries."""
|
|
123
|
+
pass
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
@dataclass(frozen=True)
|
|
127
|
+
class ConsentGrant:
|
|
128
|
+
"""
|
|
129
|
+
Granular, single-purpose cryptographic consent grant binding:
|
|
130
|
+
- action: e.g. "http:fuzz", "db:restore", "db:purge", "fs:mutate", "fs:undo"
|
|
131
|
+
- target: canonical URL, host:port, or normalized path
|
|
132
|
+
- caller_session: session or agent conversation ID
|
|
133
|
+
- nonce: cryptographic single-use nonce
|
|
134
|
+
- expiry: Unix timestamp
|
|
135
|
+
- method: optional HTTP method if applicable ("GET", "POST", etc.)
|
|
136
|
+
- path_pattern: optional URL path pattern (e.g. "/api/*")
|
|
137
|
+
- db_identity: optional canonical DB file path or connection string
|
|
138
|
+
"""
|
|
139
|
+
action: str
|
|
140
|
+
target: str
|
|
141
|
+
caller_session: str
|
|
142
|
+
nonce: str
|
|
143
|
+
expiry: float
|
|
144
|
+
method: Optional[str] = None
|
|
145
|
+
path_pattern: Optional[str] = None
|
|
146
|
+
db_identity: Optional[str] = None
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
_GLOBAL_CONSUMED_NONCES: Set[str] = set()
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
def clear_consumed_nonces() -> None:
|
|
153
|
+
"""Clears the consumed nonces registry (used primarily in test fixtures)."""
|
|
154
|
+
_GLOBAL_CONSUMED_NONCES.clear()
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
def create_consent_grant(
|
|
158
|
+
action: str,
|
|
159
|
+
target: str,
|
|
160
|
+
caller_session: str,
|
|
161
|
+
ttl_seconds: int = 300,
|
|
162
|
+
method: Optional[str] = None,
|
|
163
|
+
path_pattern: Optional[str] = None,
|
|
164
|
+
db_identity: Optional[str] = None,
|
|
165
|
+
nonce: Optional[str] = None
|
|
166
|
+
) -> ConsentGrant:
|
|
167
|
+
"""
|
|
168
|
+
Creates a granular ConsentGrant bound to specific action, target, session, and TTL.
|
|
169
|
+
Generates a cryptographically strong 128-bit hex nonce if none is provided.
|
|
170
|
+
"""
|
|
171
|
+
if not action or not str(action).strip():
|
|
172
|
+
raise ValueError("ConsentGrant requires a non-empty 'action'")
|
|
173
|
+
if not target or not str(target).strip():
|
|
174
|
+
raise ValueError("ConsentGrant requires a non-empty 'target'")
|
|
175
|
+
if not caller_session or not str(caller_session).strip():
|
|
176
|
+
raise ValueError("ConsentGrant requires a non-empty 'caller_session'")
|
|
177
|
+
|
|
178
|
+
clean_target = str(target).strip()
|
|
179
|
+
clean_action = str(action).strip().lower()
|
|
180
|
+
clean_method = str(method).strip().upper() if method else None
|
|
181
|
+
assigned_nonce = nonce.strip() if nonce and str(nonce).strip() else secrets.token_hex(16)
|
|
182
|
+
expiry_ts = time.time() + float(ttl_seconds)
|
|
183
|
+
|
|
184
|
+
return ConsentGrant(
|
|
185
|
+
action=clean_action,
|
|
186
|
+
target=clean_target,
|
|
187
|
+
caller_session=str(caller_session).strip(),
|
|
188
|
+
nonce=assigned_nonce,
|
|
189
|
+
expiry=expiry_ts,
|
|
190
|
+
method=clean_method,
|
|
191
|
+
path_pattern=str(path_pattern).strip() if path_pattern else None,
|
|
192
|
+
db_identity=str(db_identity).strip() if db_identity else None
|
|
193
|
+
)
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
def resolve_contained_path(sandbox_root: str, target_path: str) -> str:
|
|
197
|
+
"""
|
|
198
|
+
Normalizes target_path and verifies that it strictly resides within sandbox_root.
|
|
199
|
+
Rejects parent traversal '..', absolute paths outside sandbox root, symlink escapes, and null bytes.
|
|
200
|
+
Returns normalized canonical path.
|
|
201
|
+
Raises PathContainmentError if target escapes sandbox root.
|
|
202
|
+
"""
|
|
203
|
+
if not sandbox_root or not str(sandbox_root).strip():
|
|
204
|
+
raise PathContainmentError("Sandbox root cannot be empty.")
|
|
205
|
+
if not target_path or not str(target_path).strip():
|
|
206
|
+
raise PathContainmentError("Target path cannot be empty.")
|
|
207
|
+
|
|
208
|
+
raw_target = str(target_path).strip()
|
|
209
|
+
if "\0" in raw_target:
|
|
210
|
+
raise PathContainmentError("Path containment violation: Null bytes detected in target path.")
|
|
211
|
+
|
|
212
|
+
# Cross-platform normalization of directory separators (replace backslashes with forward slashes)
|
|
213
|
+
norm_target = raw_target.replace("\\", "/")
|
|
214
|
+
|
|
215
|
+
clean_root = os.path.realpath(os.path.abspath(str(sandbox_root).strip()))
|
|
216
|
+
|
|
217
|
+
if os.path.isabs(norm_target):
|
|
218
|
+
resolved = os.path.realpath(os.path.abspath(norm_target))
|
|
219
|
+
else:
|
|
220
|
+
resolved = os.path.realpath(os.path.abspath(os.path.join(clean_root, norm_target)))
|
|
221
|
+
|
|
222
|
+
root_boundary = clean_root if clean_root.endswith(os.sep) else clean_root + os.sep
|
|
223
|
+
if resolved != clean_root and not resolved.startswith(root_boundary):
|
|
224
|
+
raise PathContainmentError(
|
|
225
|
+
f"Path containment violation: '{raw_target}' resolves to '{resolved}', "
|
|
226
|
+
f"which escapes sandbox root '{clean_root}'."
|
|
227
|
+
)
|
|
228
|
+
|
|
229
|
+
return resolved
|
|
230
|
+
|
|
231
|
+
|
|
232
|
+
def is_consent_grant(obj: Any) -> bool:
|
|
233
|
+
"""Checks whether an object is a ConsentGrant instance across dual module import paths."""
|
|
234
|
+
if obj is None or isinstance(obj, bool):
|
|
235
|
+
return False
|
|
236
|
+
return (
|
|
237
|
+
isinstance(obj, ConsentGrant)
|
|
238
|
+
or type(obj).__name__ == "ConsentGrant"
|
|
239
|
+
or (hasattr(obj, "action") and hasattr(obj, "target") and hasattr(obj, "nonce") and hasattr(obj, "expiry"))
|
|
240
|
+
)
|
|
241
|
+
|
|
242
|
+
|
|
243
|
+
def verify_granular_grant(
|
|
244
|
+
grant: Any,
|
|
245
|
+
expected_action: str,
|
|
246
|
+
expected_target: str,
|
|
247
|
+
caller_session: Optional[str] = None,
|
|
248
|
+
method: Optional[str] = None,
|
|
249
|
+
path: Optional[str] = None,
|
|
250
|
+
db_identity: Optional[str] = None,
|
|
251
|
+
consumed_nonces: Optional[Set[str]] = None,
|
|
252
|
+
mark_consumed: bool = True
|
|
253
|
+
) -> bool:
|
|
254
|
+
"""
|
|
255
|
+
Verifies that grant is a valid, unexpired, un-replayed ConsentGrant matching
|
|
256
|
+
expected action, target, session, and optional method/path/db_identity.
|
|
257
|
+
Rejects generic boolean flags (consent=True) and default-denies on any mismatch.
|
|
258
|
+
"""
|
|
259
|
+
if grant is None or isinstance(grant, bool):
|
|
260
|
+
return False
|
|
261
|
+
|
|
262
|
+
nonce_registry = consumed_nonces if consumed_nonces is not None else _GLOBAL_CONSUMED_NONCES
|
|
263
|
+
|
|
264
|
+
# Extract grant attributes from ConsentGrant or dictionary representation
|
|
265
|
+
if is_consent_grant(grant):
|
|
266
|
+
g_action = grant.action
|
|
267
|
+
g_target = grant.target
|
|
268
|
+
g_session = grant.caller_session
|
|
269
|
+
g_nonce = grant.nonce
|
|
270
|
+
g_expiry = grant.expiry
|
|
271
|
+
g_method = grant.method
|
|
272
|
+
g_path = grant.path_pattern
|
|
273
|
+
g_db = grant.db_identity
|
|
274
|
+
elif isinstance(grant, dict):
|
|
275
|
+
g_action = grant.get("action") or grant.get("operation")
|
|
276
|
+
g_target = grant.get("target") or grant.get("target_sandbox") or grant.get("target_db") or grant.get("base_url")
|
|
277
|
+
g_session = grant.get("caller_session") or grant.get("session") or grant.get("session_id")
|
|
278
|
+
g_nonce = grant.get("nonce")
|
|
279
|
+
g_expiry = grant.get("expiry")
|
|
280
|
+
g_method = grant.get("method")
|
|
281
|
+
g_path = grant.get("path_pattern") or grant.get("path")
|
|
282
|
+
g_db = grant.get("db_identity") or grant.get("target_sandbox") or grant.get("target_db")
|
|
283
|
+
else:
|
|
284
|
+
return False
|
|
285
|
+
|
|
286
|
+
# 1. Mandatory grant fields validation (Fail-closed: action, target, caller_session, nonce, expiry)
|
|
287
|
+
if not g_action or not str(g_action).strip():
|
|
288
|
+
return False
|
|
289
|
+
if not g_target or not str(g_target).strip():
|
|
290
|
+
return False
|
|
291
|
+
if not g_session or not str(g_session).strip():
|
|
292
|
+
return False
|
|
293
|
+
if not g_nonce or not str(g_nonce).strip():
|
|
294
|
+
return False
|
|
295
|
+
if g_expiry is None:
|
|
296
|
+
return False
|
|
297
|
+
|
|
298
|
+
# 2. Action check (Fail-closed)
|
|
299
|
+
norm_expected_action = str(expected_action).strip().lower()
|
|
300
|
+
norm_g_action = str(g_action).strip().lower()
|
|
301
|
+
action_aliases = {
|
|
302
|
+
"http:fuzz": {"http:fuzz", "api:fuzz", "fuzz"},
|
|
303
|
+
"db:restore": {"db:restore", "restore"},
|
|
304
|
+
"db:purge": {"db:purge", "purge", "audit_and_purge"},
|
|
305
|
+
"fs:mutate": {"fs:mutate", "mutate"},
|
|
306
|
+
"fs:undo": {"fs:undo", "undo", "fs:delete"}
|
|
307
|
+
}
|
|
308
|
+
allowed_aliases = action_aliases.get(norm_expected_action, {norm_expected_action})
|
|
309
|
+
if norm_g_action not in allowed_aliases and norm_g_action != norm_expected_action:
|
|
310
|
+
return False
|
|
311
|
+
|
|
312
|
+
# 3. Expiry check
|
|
313
|
+
try:
|
|
314
|
+
if time.time() > float(g_expiry):
|
|
315
|
+
return False # Expired
|
|
316
|
+
except (ValueError, TypeError):
|
|
317
|
+
return False
|
|
318
|
+
|
|
319
|
+
# 4. Cryptographic Nonce & Replay check (validated before session/target, but only consumed on success)
|
|
320
|
+
s_nonce = str(g_nonce).strip()
|
|
321
|
+
if s_nonce in nonce_registry:
|
|
322
|
+
return False # Replay attack blocked
|
|
323
|
+
|
|
324
|
+
# 5. Caller Session check
|
|
325
|
+
if caller_session:
|
|
326
|
+
if str(caller_session).strip() != str(g_session).strip():
|
|
327
|
+
return False
|
|
328
|
+
|
|
329
|
+
# 6. Canonical Target check
|
|
330
|
+
if not expected_target or not str(expected_target).strip():
|
|
331
|
+
return False
|
|
332
|
+
norm_gt = str(g_target).strip().rstrip("/")
|
|
333
|
+
norm_et = str(expected_target).strip().rstrip("/")
|
|
334
|
+
# URL target matching: check prefix or equality
|
|
335
|
+
if norm_gt.startswith(("http://", "https://")) or norm_et.startswith(("http://", "https://")):
|
|
336
|
+
if not (norm_et == norm_gt or norm_et.startswith(norm_gt + "/")):
|
|
337
|
+
return False
|
|
338
|
+
else:
|
|
339
|
+
# Filesystem / DB path target matching: check canonical path
|
|
340
|
+
try:
|
|
341
|
+
real_gt = os.path.realpath(os.path.abspath(norm_gt)).lower()
|
|
342
|
+
real_et = os.path.realpath(os.path.abspath(norm_et)).lower()
|
|
343
|
+
if real_gt != real_et and not real_et.startswith(real_gt + os.sep):
|
|
344
|
+
return False
|
|
345
|
+
except Exception:
|
|
346
|
+
if norm_gt != norm_et:
|
|
347
|
+
return False
|
|
348
|
+
|
|
349
|
+
# 7. HTTP Method check (if specified)
|
|
350
|
+
if method and g_method:
|
|
351
|
+
if str(method).strip().upper() != str(g_method).strip().upper():
|
|
352
|
+
return False
|
|
353
|
+
|
|
354
|
+
# 8. URL Path check (if specified)
|
|
355
|
+
if path and g_path:
|
|
356
|
+
norm_p = str(path).strip()
|
|
357
|
+
norm_gp = str(g_path).strip()
|
|
358
|
+
if norm_p != norm_gp and not fnmatch.fnmatch(norm_p, norm_gp):
|
|
359
|
+
return False
|
|
360
|
+
|
|
361
|
+
# 9. DB Identity check (if specified)
|
|
362
|
+
if db_identity and g_db:
|
|
363
|
+
try:
|
|
364
|
+
real_db = os.path.realpath(os.path.abspath(str(db_identity).strip())).lower()
|
|
365
|
+
real_gdb = os.path.realpath(os.path.abspath(str(g_db).strip())).lower()
|
|
366
|
+
if real_db != real_gdb:
|
|
367
|
+
return False
|
|
368
|
+
except Exception:
|
|
369
|
+
if str(db_identity).strip() != str(g_db).strip():
|
|
370
|
+
return False
|
|
371
|
+
|
|
372
|
+
# 10. Atomically register consumed nonce only after ALL authorization attributes pass
|
|
373
|
+
if mark_consumed:
|
|
374
|
+
nonce_registry.add(s_nonce)
|
|
375
|
+
|
|
376
|
+
return True
|
|
377
|
+
|
|
378
|
+
|
|
68
379
|
class PentestRateLimiter:
|
|
69
380
|
"""Enforces max requests/second, concurrency cap, and 5xx/429 circuit breaking."""
|
|
70
381
|
|
|
@@ -110,6 +421,140 @@ class PentestRateLimiter:
|
|
|
110
421
|
self.consecutive_errors = 0
|
|
111
422
|
|
|
112
423
|
|
|
424
|
+
class SafeRedirectHandler(urllib.request.HTTPRedirectHandler):
|
|
425
|
+
"""
|
|
426
|
+
Subclass of urllib.request.HTTPRedirectHandler that intercepts 301, 302, 303, 307, 308
|
|
427
|
+
redirects and verifies redirect targets with PentestScopeGuard before following.
|
|
428
|
+
Blocks SSRF, loop escapes, and redirects to cloud metadata / restricted IP subnets.
|
|
429
|
+
"""
|
|
430
|
+
|
|
431
|
+
def __init__(self, scope_guard: Optional[PentestScopeGuard] = None, max_redirects: int = 5):
|
|
432
|
+
super().__init__()
|
|
433
|
+
self.scope_guard = scope_guard or PentestScopeGuard()
|
|
434
|
+
self.max_redirects = max_redirects
|
|
435
|
+
|
|
436
|
+
def redirect_request(self, req, fp, code, msg, headers, newurl):
|
|
437
|
+
count = getattr(req, "_safe_redirect_count", 0) + 1
|
|
438
|
+
if count > self.max_redirects:
|
|
439
|
+
raise PentestScopeError(
|
|
440
|
+
f"MAX_REDIRECTS_EXCEEDED: Exceeded maximum allowed redirects ({self.max_redirects})."
|
|
441
|
+
)
|
|
442
|
+
|
|
443
|
+
origin_url = req.full_url
|
|
444
|
+
absolute_target = urllib.parse.urljoin(origin_url, newurl)
|
|
445
|
+
|
|
446
|
+
is_valid, reason = self.scope_guard.validate_redirect(origin_url, absolute_target)
|
|
447
|
+
if not is_valid:
|
|
448
|
+
raise PentestScopeError(f"DANGEROUS_REDIRECT_BLOCKED: {reason}")
|
|
449
|
+
|
|
450
|
+
new_req = super().redirect_request(req, fp, code, msg, headers, absolute_target)
|
|
451
|
+
if new_req is not None:
|
|
452
|
+
new_req._safe_redirect_count = count
|
|
453
|
+
return new_req
|
|
454
|
+
|
|
455
|
+
def http_error_301(self, req, fp, code, msg, headers):
|
|
456
|
+
return super().http_error_301(req, fp, code, msg, headers)
|
|
457
|
+
|
|
458
|
+
def http_error_302(self, req, fp, code, msg, headers):
|
|
459
|
+
return super().http_error_302(req, fp, code, msg, headers)
|
|
460
|
+
|
|
461
|
+
def http_error_303(self, req, fp, code, msg, headers):
|
|
462
|
+
return super().http_error_303(req, fp, code, msg, headers)
|
|
463
|
+
|
|
464
|
+
def http_error_307(self, req, fp, code, msg, headers):
|
|
465
|
+
return super().http_error_307(req, fp, code, msg, headers)
|
|
466
|
+
|
|
467
|
+
def http_error_308(self, req, fp, code, msg, headers):
|
|
468
|
+
return super().http_error_308(req, fp, code, msg, headers)
|
|
469
|
+
|
|
470
|
+
|
|
471
|
+
class PinnedHTTPConnection(http.client.HTTPConnection):
|
|
472
|
+
"""HTTPConnection that connects strictly to the validated IP to defeat DNS rebinding TOCTOU."""
|
|
473
|
+
|
|
474
|
+
def __init__(self, host: str, port: Optional[int] = None, pinned_ip: Optional[str] = None, **kwargs):
|
|
475
|
+
super().__init__(host, port, **kwargs)
|
|
476
|
+
self._pinned_ip = pinned_ip
|
|
477
|
+
|
|
478
|
+
def connect(self) -> None:
|
|
479
|
+
target_addr = self._pinned_ip if self._pinned_ip else self.host
|
|
480
|
+
self.sock = socket.create_connection(
|
|
481
|
+
(target_addr, self.port),
|
|
482
|
+
self.timeout,
|
|
483
|
+
self.source_address
|
|
484
|
+
)
|
|
485
|
+
|
|
486
|
+
|
|
487
|
+
class PinnedHTTPSConnection(http.client.HTTPSConnection):
|
|
488
|
+
"""HTTPSConnection that connects strictly to the validated IP while preserving SNI / host headers."""
|
|
489
|
+
|
|
490
|
+
def __init__(self, host: str, port: Optional[int] = None, pinned_ip: Optional[str] = None, **kwargs):
|
|
491
|
+
super().__init__(host, port, **kwargs)
|
|
492
|
+
self._pinned_ip = pinned_ip
|
|
493
|
+
|
|
494
|
+
def connect(self) -> None:
|
|
495
|
+
target_addr = self._pinned_ip if self._pinned_ip else self.host
|
|
496
|
+
sock = socket.create_connection(
|
|
497
|
+
(target_addr, self.port),
|
|
498
|
+
self.timeout,
|
|
499
|
+
self.source_address
|
|
500
|
+
)
|
|
501
|
+
server_hostname = self.host.split(":")[0] if self.host else target_addr
|
|
502
|
+
if self._context:
|
|
503
|
+
self.sock = self._context.wrap_socket(sock, server_hostname=server_hostname)
|
|
504
|
+
else:
|
|
505
|
+
self.sock = sock
|
|
506
|
+
|
|
507
|
+
|
|
508
|
+
class PinnedHTTPHandler(urllib.request.HTTPHandler):
|
|
509
|
+
"""Urllib HTTP handler enforcing socket-level connection to pre-validated pinned IPs."""
|
|
510
|
+
|
|
511
|
+
def __init__(self, scope_guard: Optional[PentestScopeGuard] = None):
|
|
512
|
+
super().__init__()
|
|
513
|
+
self.scope_guard = scope_guard
|
|
514
|
+
|
|
515
|
+
def http_open(self, req: urllib.request.Request):
|
|
516
|
+
def connection_factory(host: str, **kwargs):
|
|
517
|
+
clean_host = host.split(":")[0]
|
|
518
|
+
pinned_ip = self.scope_guard.get_pinned_ip(clean_host) if self.scope_guard else None
|
|
519
|
+
return PinnedHTTPConnection(host, pinned_ip=pinned_ip, **kwargs)
|
|
520
|
+
return self.do_open(connection_factory, req)
|
|
521
|
+
|
|
522
|
+
|
|
523
|
+
class PinnedHTTPSHandler(urllib.request.HTTPSHandler):
|
|
524
|
+
"""Urllib HTTPS handler enforcing socket-level connection to pre-validated pinned IPs."""
|
|
525
|
+
|
|
526
|
+
def __init__(self, scope_guard: Optional[PentestScopeGuard] = None, context: Optional[ssl.SSLContext] = None):
|
|
527
|
+
super().__init__(context=context)
|
|
528
|
+
self.scope_guard = scope_guard
|
|
529
|
+
|
|
530
|
+
def https_open(self, req: urllib.request.Request):
|
|
531
|
+
def connection_factory(host: str, **kwargs):
|
|
532
|
+
clean_host = host.split(":")[0]
|
|
533
|
+
pinned_ip = self.scope_guard.get_pinned_ip(clean_host) if self.scope_guard else None
|
|
534
|
+
if self._context:
|
|
535
|
+
kwargs["context"] = self._context
|
|
536
|
+
return PinnedHTTPSConnection(host, pinned_ip=pinned_ip, **kwargs)
|
|
537
|
+
return self.do_open(connection_factory, req)
|
|
538
|
+
|
|
539
|
+
|
|
540
|
+
def create_safe_opener(
|
|
541
|
+
scope_guard: Optional[PentestScopeGuard] = None,
|
|
542
|
+
timeout_sec: float = 10.0,
|
|
543
|
+
ssl_context: Optional[ssl.SSLContext] = None,
|
|
544
|
+
max_redirects: int = 5
|
|
545
|
+
) -> urllib.request.OpenerDirector:
|
|
546
|
+
"""Creates a urllib OpenerDirector hardened with SafeRedirectHandler and PinnedConnection handlers."""
|
|
547
|
+
guard = scope_guard or PentestScopeGuard()
|
|
548
|
+
redirect_handler = SafeRedirectHandler(scope_guard=guard, max_redirects=max_redirects)
|
|
549
|
+
handlers: List[Any] = [
|
|
550
|
+
redirect_handler,
|
|
551
|
+
PinnedHTTPHandler(scope_guard=guard),
|
|
552
|
+
PinnedHTTPSHandler(scope_guard=guard, context=ssl_context),
|
|
553
|
+
]
|
|
554
|
+
opener = urllib.request.build_opener(*handlers)
|
|
555
|
+
return opener
|
|
556
|
+
|
|
557
|
+
|
|
113
558
|
class PentestScopeGuard:
|
|
114
559
|
"""
|
|
115
560
|
Enforces Layer 1 & 2 security invariants on all active pentest/DAST commands.
|
|
@@ -119,26 +564,44 @@ class PentestScopeGuard:
|
|
|
119
564
|
self,
|
|
120
565
|
allowed_hosts: Optional[List[str]] = None,
|
|
121
566
|
allow_internal: bool = False,
|
|
567
|
+
allow_loopback: Optional[bool] = None,
|
|
568
|
+
allow_private_subnets: bool = False,
|
|
122
569
|
audit_log_path: Optional[str] = None,
|
|
123
570
|
rate_limiter: Optional[PentestRateLimiter] = None
|
|
124
571
|
):
|
|
125
572
|
self.allow_internal = allow_internal
|
|
573
|
+
# Narrow opt-in: loopback (localhost / 127.0.0.1 / ::1) is permitted when allow_loopback=True or allow_internal=True
|
|
574
|
+
self.allow_loopback = allow_loopback if allow_loopback is not None else allow_internal
|
|
575
|
+
# RFC1918 Private subnets require explicit authorization policy (SYNAPSE_ALLOW_PRIVATE_SUBNETS=1 or allow_private_subnets=True)
|
|
576
|
+
self.allow_private_subnets = allow_private_subnets or (
|
|
577
|
+
os.environ.get("SYNAPSE_ALLOW_PRIVATE_SUBNETS", "").strip().lower() in ("1", "true", "yes")
|
|
578
|
+
)
|
|
126
579
|
self.audit_log_path = audit_log_path or DEFAULT_AUDIT_LOG
|
|
127
580
|
self.rate_limiter = rate_limiter or PentestRateLimiter()
|
|
581
|
+
self._pinned_ips: Dict[str, str] = {}
|
|
582
|
+
self.consumed_nonces: Set[str] = set()
|
|
128
583
|
|
|
129
|
-
# Parse allowlist from parameter or environment
|
|
130
584
|
hosts = set()
|
|
131
|
-
if allowed_hosts:
|
|
132
|
-
hosts.update([h.strip().lower() for h in allowed_hosts if h.strip()])
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
585
|
+
if allowed_hosts is not None:
|
|
586
|
+
hosts.update([h.strip().lower().strip("[]") for h in allowed_hosts if h.strip()])
|
|
587
|
+
else:
|
|
588
|
+
for env_var in ("ALLOWED_PENTEST_HOSTS", "SYNAPSE_ALLOWED_HOSTS"):
|
|
589
|
+
env_allowed = os.environ.get(env_var, "").strip()
|
|
590
|
+
if env_allowed:
|
|
591
|
+
hosts.update([h.strip().lower().strip("[]") for h in env_allowed.split(",") if h.strip()])
|
|
592
|
+
cfg_hosts = self._load_config_allowed_hosts()
|
|
593
|
+
hosts.update(cfg_hosts)
|
|
139
594
|
|
|
140
595
|
self.allowed_hosts = hosts
|
|
141
596
|
|
|
597
|
+
def get_pinned_ip(self, hostname: str) -> Optional[str]:
|
|
598
|
+
"""Returns the pre-validated pinned IP for hostname to prevent DNS rebinding TOCTOU."""
|
|
599
|
+
return self._pinned_ips.get(hostname.lower().strip().strip("[]"))
|
|
600
|
+
|
|
601
|
+
def pin_ip(self, hostname: str, ip: str) -> None:
|
|
602
|
+
"""Explicitly pins a validated IP for a hostname."""
|
|
603
|
+
self._pinned_ips[hostname.lower().strip().strip("[]")] = ip
|
|
604
|
+
|
|
142
605
|
def _load_config_allowed_hosts(self) -> List[str]:
|
|
143
606
|
cfg_path = os.path.join(REPO_ROOT, "synapse.config.json")
|
|
144
607
|
if not os.path.isfile(cfg_path):
|
|
@@ -146,22 +609,51 @@ class PentestScopeGuard:
|
|
|
146
609
|
try:
|
|
147
610
|
with open(cfg_path, "r", encoding="utf-8") as f:
|
|
148
611
|
data = json.load(f)
|
|
149
|
-
return [h.strip().lower() for h in data.get("security", {}).get("allowed_pentest_hosts", []) if h.strip()]
|
|
612
|
+
return [h.strip().lower().strip("[]") for h in data.get("security", {}).get("allowed_pentest_hosts", []) if h.strip()]
|
|
150
613
|
except Exception:
|
|
151
614
|
return []
|
|
152
615
|
|
|
153
|
-
def _is_ip_private_or_restricted(
|
|
616
|
+
def _is_ip_private_or_restricted(
|
|
617
|
+
self,
|
|
618
|
+
ip_str: str,
|
|
619
|
+
allow_internal: Optional[bool] = None,
|
|
620
|
+
allow_loopback: Optional[bool] = None,
|
|
621
|
+
allow_private_subnets: Optional[bool] = None
|
|
622
|
+
) -> Tuple[bool, str]:
|
|
154
623
|
"""Checks if IP belongs to private, loopback, link-local, or cloud metadata."""
|
|
624
|
+
effective_internal = self.allow_internal if allow_internal is None else allow_internal
|
|
625
|
+
effective_loopback = self.allow_loopback if allow_loopback is None else allow_loopback
|
|
626
|
+
if effective_internal:
|
|
627
|
+
effective_loopback = True
|
|
628
|
+
|
|
629
|
+
effective_private = self.allow_private_subnets if allow_private_subnets is None else allow_private_subnets
|
|
630
|
+
|
|
631
|
+
clean_ip = ip_str.strip().lower().strip("[]")
|
|
155
632
|
try:
|
|
156
|
-
ip_obj = ipaddress.ip_address(
|
|
157
|
-
|
|
158
|
-
|
|
633
|
+
ip_obj = ipaddress.ip_address(clean_ip)
|
|
634
|
+
# Unwrap IPv4-mapped IPv6 address (e.g. ::ffff:169.254.169.254)
|
|
635
|
+
if isinstance(ip_obj, ipaddress.IPv6Address) and ip_obj.ipv4_mapped:
|
|
636
|
+
ip_obj = ip_obj.ipv4_mapped
|
|
637
|
+
|
|
638
|
+
# Cloud Instance Metadata Service (AWS/GCP/Azure IMDS IPv4 & IPv6)
|
|
639
|
+
is_cloud_metadata = (
|
|
640
|
+
clean_ip in ("169.254.169.254", "fd00:ec2::254")
|
|
641
|
+
or (isinstance(ip_obj, ipaddress.IPv4Address) and ip_obj in ipaddress.ip_network("169.254.0.0/16"))
|
|
642
|
+
or (isinstance(ip_obj, ipaddress.IPv6Address) and str(ip_obj).lower().startswith("fd00:ec2::254"))
|
|
643
|
+
)
|
|
644
|
+
if is_cloud_metadata:
|
|
645
|
+
return True, f"AWS/Cloud Instance Metadata Service ({clean_ip})"
|
|
646
|
+
|
|
647
|
+
if ip_obj.is_link_local:
|
|
648
|
+
return True, f"Link-local subnet ({clean_ip})"
|
|
649
|
+
|
|
159
650
|
if ip_obj.is_loopback:
|
|
160
|
-
return not
|
|
651
|
+
return not effective_loopback, f"Loopback interface ({clean_ip})"
|
|
652
|
+
|
|
653
|
+
# RFC1918 Private subnet (narrow opt-in: blocked unless allow_private_subnets is explicitly enabled)
|
|
161
654
|
if ip_obj.is_private:
|
|
162
|
-
return not
|
|
163
|
-
|
|
164
|
-
return True, f"Link-local subnet ({ip_str})"
|
|
655
|
+
return not effective_private, f"RFC1918 Private subnet ({clean_ip})"
|
|
656
|
+
|
|
165
657
|
return False, "Public IP"
|
|
166
658
|
except ValueError:
|
|
167
659
|
return True, f"Malformed IP address: {ip_str}"
|
|
@@ -174,48 +666,85 @@ class PentestScopeGuard:
|
|
|
174
666
|
return True
|
|
175
667
|
return False
|
|
176
668
|
|
|
177
|
-
def validate_target(
|
|
669
|
+
def validate_target(
|
|
670
|
+
self,
|
|
671
|
+
target_url: str,
|
|
672
|
+
allow_internal: Optional[bool] = None,
|
|
673
|
+
actor: Optional[str] = None,
|
|
674
|
+
request_id: Optional[str] = None
|
|
675
|
+
) -> Tuple[bool, str]:
|
|
178
676
|
"""
|
|
179
|
-
Validates target URL against scope allowlist, production blocklist,
|
|
677
|
+
Validates target URL against scope allowlist, production blocklist, scheme/port,
|
|
678
|
+
and IP subnet rules with DNS rebinding protection.
|
|
180
679
|
Fail-Closed: Defaults to False on any error or missing allowlist.
|
|
181
680
|
"""
|
|
681
|
+
req_id = request_id or str(uuid.uuid4())
|
|
682
|
+
act = actor or os.environ.get("SYNAPSE_AUDIT_ACTOR", "agent_executor")
|
|
683
|
+
effective_internal = self.allow_internal if allow_internal is None else allow_internal
|
|
684
|
+
|
|
182
685
|
if not target_url or not target_url.strip():
|
|
183
686
|
reason = "Target URL is empty or missing (Fail-closed default deny)."
|
|
184
|
-
self._write_audit(target_url or "EMPTY", "N/A", False, reason)
|
|
687
|
+
self._write_audit(target_url or "EMPTY", "N/A", False, reason, actor=act, request_id=req_id)
|
|
185
688
|
return False, reason
|
|
186
689
|
|
|
187
690
|
clean_url = target_url.strip()
|
|
188
|
-
|
|
691
|
+
has_scheme = "://" in clean_url
|
|
692
|
+
if not has_scheme:
|
|
189
693
|
clean_url = f"http://{clean_url}"
|
|
190
694
|
|
|
191
695
|
try:
|
|
192
696
|
parsed = urllib.parse.urlparse(clean_url)
|
|
193
697
|
except Exception as e:
|
|
194
698
|
reason = f"Malformed target URL '{target_url}': {e}"
|
|
195
|
-
self._write_audit(target_url, "N/A", False, reason)
|
|
699
|
+
self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
|
|
700
|
+
return False, reason
|
|
701
|
+
|
|
702
|
+
# Scheme validation: Only http and https permitted
|
|
703
|
+
scheme = (parsed.scheme or "").lower()
|
|
704
|
+
if scheme not in ALLOWED_SCHEMES:
|
|
705
|
+
reason = f"DISALLOWED SCHEME: Scheme '{parsed.scheme}' is not permitted. Only 'http' and 'https' are allowed."
|
|
706
|
+
self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
|
|
196
707
|
return False, reason
|
|
197
708
|
|
|
198
|
-
|
|
709
|
+
# Port validation: Reject sensitive infrastructure ports
|
|
710
|
+
try:
|
|
711
|
+
port = parsed.port
|
|
712
|
+
except ValueError as pe:
|
|
713
|
+
reason = f"INVALID PORT: {pe}"
|
|
714
|
+
self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
|
|
715
|
+
return False, reason
|
|
716
|
+
|
|
717
|
+
if port is not None:
|
|
718
|
+
if port in SENSITIVE_INFRASTRUCTURE_PORTS:
|
|
719
|
+
reason = f"DISALLOWED PORT: Port {port} is a sensitive infrastructure port and cannot be targeted."
|
|
720
|
+
self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
|
|
721
|
+
return False, reason
|
|
722
|
+
if port <= 0 or port > 65535:
|
|
723
|
+
reason = f"INVALID PORT: Port {port} is outside valid range (1-65535)."
|
|
724
|
+
self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
|
|
725
|
+
return False, reason
|
|
726
|
+
|
|
727
|
+
hostname = (parsed.hostname or "").lower().strip().strip("[]")
|
|
199
728
|
if not hostname:
|
|
200
729
|
reason = f"Could not extract hostname from '{target_url}' (Fail-closed)."
|
|
201
|
-
self._write_audit(target_url, "N/A", False, reason)
|
|
730
|
+
self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
|
|
202
731
|
return False, reason
|
|
203
732
|
|
|
204
733
|
# 1. Production pattern check
|
|
205
734
|
if self.is_production_host(hostname) and hostname not in self.allowed_hosts:
|
|
206
735
|
reason = f"CRITICAL PRODUCTION BLOCK: Target host '{hostname}' matches production naming pattern and is not explicitly in ALLOWED_PENTEST_HOSTS."
|
|
207
|
-
self._write_audit(target_url, "N/A", False, reason)
|
|
736
|
+
self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
|
|
208
737
|
return False, reason
|
|
209
738
|
|
|
210
739
|
# 2. Allowlist containment check
|
|
211
740
|
is_allowed = False
|
|
212
741
|
if not self.allowed_hosts:
|
|
213
742
|
# If no hosts allowlisted at all, only localhost is permitted if allow_internal is True
|
|
214
|
-
if
|
|
743
|
+
if effective_internal and hostname in ("localhost", "127.0.0.1", "::1"):
|
|
215
744
|
is_allowed = True
|
|
216
745
|
else:
|
|
217
746
|
reason = "ALLOWED_PENTEST_HOSTS is empty. All active pentest scans are disabled by default (Fail-closed)."
|
|
218
|
-
self._write_audit(target_url, "N/A", False, reason)
|
|
747
|
+
self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
|
|
219
748
|
return False, reason
|
|
220
749
|
else:
|
|
221
750
|
if hostname in self.allowed_hosts:
|
|
@@ -223,31 +752,68 @@ class PentestScopeGuard:
|
|
|
223
752
|
else:
|
|
224
753
|
# Check wildcard e.g. *.example.com
|
|
225
754
|
for allowed in self.allowed_hosts:
|
|
226
|
-
if allowed.startswith("*.") and hostname.endswith(allowed[1:]):
|
|
755
|
+
if allowed.startswith("*.") and (hostname.endswith(allowed[1:]) or hostname == allowed[2:]):
|
|
227
756
|
is_allowed = True
|
|
228
757
|
break
|
|
229
758
|
|
|
230
759
|
if not is_allowed:
|
|
231
|
-
reason = f"SCOPE REJECTED: Host '{hostname}' is not authorized in ALLOWED_PENTEST_HOSTS: {list(self.allowed_hosts)}."
|
|
232
|
-
self._write_audit(target_url, "N/A", False, reason)
|
|
760
|
+
reason = f"SCOPE REJECTED: Host '{hostname}' is not authorized in ALLOWED_PENTEST_HOSTS: {sorted(list(self.allowed_hosts))}."
|
|
761
|
+
self._write_audit(target_url, "N/A", False, reason, actor=act, request_id=req_id)
|
|
233
762
|
return False, reason
|
|
234
763
|
|
|
235
|
-
# 3. DNS resolution & IP subnet safety check
|
|
764
|
+
# 3. DNS resolution & IP subnet safety check (anti-SSRF and DNS rebinding)
|
|
765
|
+
resolved_ips: List[str] = []
|
|
236
766
|
try:
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
767
|
+
ipaddress.ip_address(hostname)
|
|
768
|
+
resolved_ips = [hostname]
|
|
769
|
+
except ValueError:
|
|
770
|
+
# Domain name: query socket.gethostbyname first (compatible with unit test mocks)
|
|
771
|
+
try:
|
|
772
|
+
primary_ip = socket.gethostbyname(hostname)
|
|
773
|
+
resolved_ips.append(primary_ip)
|
|
774
|
+
except (socket.error, OSError) as e:
|
|
775
|
+
reason = f"DNS resolution failed for '{hostname}': {e} (Fail-closed)."
|
|
776
|
+
self._write_audit(target_url, "UNRESOLVED", False, reason, actor=act, request_id=req_id)
|
|
777
|
+
return False, reason
|
|
242
778
|
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
779
|
+
# Fail immediately if primary IP is restricted
|
|
780
|
+
restricted, ip_reason = self._is_ip_private_or_restricted(primary_ip, allow_internal=effective_internal)
|
|
781
|
+
if restricted:
|
|
782
|
+
reason = f"IP SAFETY REJECTED: Host '{hostname}' resolved to restricted IP {primary_ip} ({ip_reason})."
|
|
783
|
+
self._write_audit(target_url, primary_ip, False, reason, actor=act, request_id=req_id)
|
|
784
|
+
return False, reason
|
|
785
|
+
|
|
786
|
+
# For public hosts, verify other addresses via getaddrinfo (anti-DNS-rebinding and multi-IP checks)
|
|
787
|
+
# If getaddrinfo is explicitly mocked, or if gethostbyname is unmocked (live environment),
|
|
788
|
+
# inspect all secondary IP addresses returned by getaddrinfo.
|
|
789
|
+
gethost_mocked = hasattr(socket.gethostbyname, "mock_calls") or hasattr(socket.gethostbyname, "_mock_return_value") or hasattr(socket.gethostbyname, "assert_called")
|
|
790
|
+
getaddr_mocked = hasattr(socket.getaddrinfo, "mock_calls") or hasattr(socket.getaddrinfo, "_mock_return_value") or hasattr(socket.getaddrinfo, "assert_called")
|
|
791
|
+
|
|
792
|
+
should_check_secondary = getaddr_mocked or (
|
|
793
|
+
not gethost_mocked
|
|
794
|
+
and not (hostname.endswith(".local") or hostname.endswith(".test") or hostname.endswith(".internal"))
|
|
795
|
+
)
|
|
796
|
+
if should_check_secondary:
|
|
797
|
+
try:
|
|
798
|
+
addr_info = socket.getaddrinfo(hostname, None, socket.AF_UNSPEC, socket.SOCK_STREAM)
|
|
799
|
+
for info in addr_info:
|
|
800
|
+
resolved_ips.append(info[4][0])
|
|
801
|
+
except (socket.gaierror, OSError) as addr_err:
|
|
802
|
+
sys.stderr.write(f"[PentestScopeGuard] Notice: Secondary DNS resolution failed for '{hostname}': {addr_err}\n")
|
|
803
|
+
|
|
804
|
+
unique_ips = list(dict.fromkeys(resolved_ips))
|
|
805
|
+
for resolved_ip in unique_ips:
|
|
806
|
+
restricted, ip_reason = self._is_ip_private_or_restricted(resolved_ip, allow_internal=effective_internal)
|
|
807
|
+
if restricted:
|
|
808
|
+
reason = f"IP SAFETY REJECTED: Host '{hostname}' resolved to restricted IP {resolved_ip} ({ip_reason})."
|
|
809
|
+
self._write_audit(target_url, resolved_ip, False, reason, actor=act, request_id=req_id)
|
|
810
|
+
return False, reason
|
|
248
811
|
|
|
249
|
-
|
|
250
|
-
|
|
812
|
+
primary_resolved = unique_ips[0] if unique_ips else "UNKNOWN"
|
|
813
|
+
if primary_resolved != "UNKNOWN":
|
|
814
|
+
self.pin_ip(hostname, primary_resolved)
|
|
815
|
+
success_msg = f"Target '{hostname}' ({primary_resolved}) is authorized within pentest scope."
|
|
816
|
+
self._write_audit(target_url, primary_resolved, True, success_msg, actor=act, request_id=req_id)
|
|
251
817
|
return True, success_msg
|
|
252
818
|
|
|
253
819
|
def validate_redirect(self, original_url: str, redirect_url: str) -> Tuple[bool, str]:
|
|
@@ -259,25 +825,74 @@ class PentestScopeGuard:
|
|
|
259
825
|
return False, reason
|
|
260
826
|
return True, f"Redirect to '{redirect_url}' is within authorized scope."
|
|
261
827
|
|
|
262
|
-
def verify_consent(
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
828
|
+
def verify_consent(
|
|
829
|
+
self,
|
|
830
|
+
consent_flag: Any = False,
|
|
831
|
+
impact_summary: str = "",
|
|
832
|
+
expected_action: str = "http:fuzz",
|
|
833
|
+
expected_target: str = "",
|
|
834
|
+
caller_session: Optional[str] = None,
|
|
835
|
+
mark_consumed: bool = True
|
|
836
|
+
) -> bool:
|
|
837
|
+
"""
|
|
838
|
+
Verifies that explicit granular consent has been granted for active operations.
|
|
839
|
+
Eliminates generic boolean flags (consent_flag=True) and unauthenticated
|
|
840
|
+
shared environment variables (PENTEST_CONSENT_ACKNOWLEDGED).
|
|
841
|
+
Requires a valid ConsentGrant (or granular grant dict).
|
|
842
|
+
"""
|
|
843
|
+
if consent_flag is None or isinstance(consent_flag, bool):
|
|
844
|
+
return False
|
|
845
|
+
if is_consent_grant(consent_flag) or isinstance(consent_flag, dict):
|
|
846
|
+
action = expected_action or "http:fuzz"
|
|
847
|
+
target = expected_target or ""
|
|
848
|
+
return verify_granular_grant(
|
|
849
|
+
grant=consent_flag,
|
|
850
|
+
expected_action=action,
|
|
851
|
+
expected_target=target,
|
|
852
|
+
caller_session=caller_session,
|
|
853
|
+
consumed_nonces=self.consumed_nonces,
|
|
854
|
+
mark_consumed=mark_consumed
|
|
855
|
+
)
|
|
268
856
|
return False
|
|
269
857
|
|
|
270
|
-
def
|
|
271
|
-
|
|
858
|
+
def create_safe_opener(
|
|
859
|
+
self,
|
|
860
|
+
timeout_sec: float = 10.0,
|
|
861
|
+
ssl_context: Optional[ssl.SSLContext] = None,
|
|
862
|
+
max_redirects: int = 5
|
|
863
|
+
) -> urllib.request.OpenerDirector:
|
|
864
|
+
"""Creates an OpenerDirector configured with SafeRedirectHandler using this guard."""
|
|
865
|
+
return create_safe_opener(
|
|
866
|
+
scope_guard=self,
|
|
867
|
+
timeout_sec=timeout_sec,
|
|
868
|
+
ssl_context=ssl_context,
|
|
869
|
+
max_redirects=max_redirects
|
|
870
|
+
)
|
|
871
|
+
|
|
872
|
+
def _write_audit(
|
|
873
|
+
self,
|
|
874
|
+
target: str,
|
|
875
|
+
ip: str,
|
|
876
|
+
allowed: bool,
|
|
877
|
+
reason: str,
|
|
878
|
+
actor: Optional[str] = None,
|
|
879
|
+
request_id: Optional[str] = None
|
|
880
|
+
) -> None:
|
|
881
|
+
"""Appends audit event to tamper-evident audit log with regex secret masking."""
|
|
272
882
|
try:
|
|
273
883
|
os.makedirs(os.path.dirname(self.audit_log_path), exist_ok=True)
|
|
884
|
+
masked_target = mask_secrets(target)
|
|
885
|
+
masked_reason = mask_secrets(reason)
|
|
274
886
|
entry = {
|
|
275
887
|
"timestamp": datetime.now(timezone.utc).isoformat(),
|
|
276
|
-
"
|
|
888
|
+
"request_id": request_id or str(uuid.uuid4()),
|
|
889
|
+
"actor": actor or os.environ.get("SYNAPSE_AUDIT_ACTOR", "pentest_scope_guard"),
|
|
890
|
+
"target": masked_target,
|
|
277
891
|
"resolved_ip": ip,
|
|
278
|
-
"
|
|
892
|
+
"decision": "AUTHORIZED" if allowed else "BLOCKED",
|
|
279
893
|
"status": "AUTHORIZED" if allowed else "BLOCKED",
|
|
280
|
-
"
|
|
894
|
+
"rationale": masked_reason,
|
|
895
|
+
"reason": masked_reason,
|
|
281
896
|
"caller_pid": os.getpid(),
|
|
282
897
|
}
|
|
283
898
|
with open(self.audit_log_path, "a", encoding="utf-8") as f:
|
|
@@ -293,6 +908,7 @@ def main() -> int:
|
|
|
293
908
|
parser.add_argument("--validate-url", type=str, help="Validate whether a URL is authorized for pentesting")
|
|
294
909
|
parser.add_argument("--allowed-hosts", type=str, help="Comma-separated list of allowed hosts")
|
|
295
910
|
parser.add_argument("--allow-internal", action="store_true", help="Allow loopback and RFC1918 internal subnets")
|
|
911
|
+
parser.add_argument("--confirm-pentest-scope", action="store_true", help="Explicit consent acknowledgement flag")
|
|
296
912
|
parser.add_argument("--audit-log", action="store_true", help="Display recent audit log entries")
|
|
297
913
|
parser.add_argument("--json", action="store_true", help="Output validation result in JSON format")
|
|
298
914
|
args = parser.parse_args()
|
|
@@ -314,10 +930,10 @@ def main() -> int:
|
|
|
314
930
|
if args.validate_url:
|
|
315
931
|
ok, msg = guard.validate_target(args.validate_url)
|
|
316
932
|
if args.json:
|
|
317
|
-
print(json.dumps({"url": args.validate_url, "allowed": ok, "message": msg}, indent=2))
|
|
933
|
+
print(json.dumps({"url": mask_secrets(args.validate_url), "allowed": ok, "message": mask_secrets(msg)}, indent=2))
|
|
318
934
|
else:
|
|
319
935
|
status_tag = "[AUTHORIZED]" if ok else "[BLOCKED]"
|
|
320
|
-
print(f"{status_tag} {msg}")
|
|
936
|
+
print(f"{status_tag} {mask_secrets(msg)}")
|
|
321
937
|
return 0 if ok else 1
|
|
322
938
|
|
|
323
939
|
parser.print_help()
|