wraithwall-sdk 0.1.0__tar.gz

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.

Potentially problematic release.


This version of wraithwall-sdk might be problematic. Click here for more details.

@@ -0,0 +1,67 @@
1
+ Metadata-Version: 2.4
2
+ Name: wraithwall-sdk
3
+ Version: 0.1.0
4
+ Summary: Official WraithWall HTTP API client SDK (preview) — separate from the wraithwall platform package
5
+ Author: WraithWall
6
+ License: MIT
7
+ Project-URL: Homepage, https://wraithwall.online/developers
8
+ Project-URL: Documentation, https://wraithwall.online/developers#/sdks
9
+ Project-URL: Repository, https://github.com/niffyhunt/wraithwall
10
+ Keywords: security,threat-intelligence,wraithwall,api,sdk
11
+ Requires-Python: >=3.9
12
+ Description-Content-Type: text/markdown
13
+ Requires-Dist: requests>=2.28.0
14
+
15
+ # wraithwall-sdk (Python)
16
+
17
+ Official **HTTP API client** for [WraithWall](https://wraithwall.online/developers) — preview `0.1.0`.
18
+
19
+ > **Name note:** PyPI already has the **`wraithwall`** platform package. This client
20
+ > will publish as **`wraithwall-sdk`** so it does not collide. Import module:
21
+ > `wraithwall_sdk`.
22
+
23
+ ## Install (from monorepo — not published yet)
24
+
25
+ ```bash
26
+ pip install -e ./sdks/python
27
+ # after publish:
28
+ # pip install wraithwall-sdk
29
+ ```
30
+
31
+ ## Quick start
32
+
33
+ ```python
34
+ import os
35
+ from wraithwall_sdk import WraithWallClient
36
+
37
+ client = WraithWallClient(
38
+ api_key=os.environ["WRAITHWALL_API_KEY"],
39
+ api_secret=os.environ["WRAITHWALL_API_SECRET"],
40
+ )
41
+
42
+ print(client.link_status())
43
+ print(client.scan_url("https://example.com"))
44
+ ```
45
+
46
+ ## Features
47
+
48
+ - `Authorization: Bearer key:secret` helper
49
+ - Typed errors (`AuthenticationError`, `RateLimitError`, `PaymentRequiredError`, …)
50
+ - Exponential backoff with jitter on `429` / `5xx`
51
+ - Offset/limit pagination helper
52
+ - Helpers: scan, intel, cowrie stats, webhooks
53
+
54
+ ## Related published packages
55
+
56
+ | Package | Role | PyPI |
57
+ |---------|------|------|
58
+ | `wraithwall` | Platform / OSS distribution | [pypi.org/project/wraithwall](https://pypi.org/project/wraithwall/) |
59
+ | `ravenscan` | Engineering intelligence CLI (`raven`) | [pypi.org/project/ravenscan](https://pypi.org/project/ravenscan/) |
60
+ | `canary-kit` | Supply-chain canary tokens | [pypi.org/project/canary-kit](https://pypi.org/project/canary-kit/) |
61
+ | `honeypot-mitre` | Cowrie → MITRE mapping | [pypi.org/project/honeypot-mitre](https://pypi.org/project/honeypot-mitre/) |
62
+ | `dml-spec` | Deception Markup Language | **Not published yet** |
63
+ | `wraithwall-sdk` | This HTTP API client | **Building — publish later** |
64
+
65
+ ## Status
66
+
67
+ Preview — keep building; **do not publish** until product is ready.
@@ -0,0 +1,53 @@
1
+ # wraithwall-sdk (Python)
2
+
3
+ Official **HTTP API client** for [WraithWall](https://wraithwall.online/developers) — preview `0.1.0`.
4
+
5
+ > **Name note:** PyPI already has the **`wraithwall`** platform package. This client
6
+ > will publish as **`wraithwall-sdk`** so it does not collide. Import module:
7
+ > `wraithwall_sdk`.
8
+
9
+ ## Install (from monorepo — not published yet)
10
+
11
+ ```bash
12
+ pip install -e ./sdks/python
13
+ # after publish:
14
+ # pip install wraithwall-sdk
15
+ ```
16
+
17
+ ## Quick start
18
+
19
+ ```python
20
+ import os
21
+ from wraithwall_sdk import WraithWallClient
22
+
23
+ client = WraithWallClient(
24
+ api_key=os.environ["WRAITHWALL_API_KEY"],
25
+ api_secret=os.environ["WRAITHWALL_API_SECRET"],
26
+ )
27
+
28
+ print(client.link_status())
29
+ print(client.scan_url("https://example.com"))
30
+ ```
31
+
32
+ ## Features
33
+
34
+ - `Authorization: Bearer key:secret` helper
35
+ - Typed errors (`AuthenticationError`, `RateLimitError`, `PaymentRequiredError`, …)
36
+ - Exponential backoff with jitter on `429` / `5xx`
37
+ - Offset/limit pagination helper
38
+ - Helpers: scan, intel, cowrie stats, webhooks
39
+
40
+ ## Related published packages
41
+
42
+ | Package | Role | PyPI |
43
+ |---------|------|------|
44
+ | `wraithwall` | Platform / OSS distribution | [pypi.org/project/wraithwall](https://pypi.org/project/wraithwall/) |
45
+ | `ravenscan` | Engineering intelligence CLI (`raven`) | [pypi.org/project/ravenscan](https://pypi.org/project/ravenscan/) |
46
+ | `canary-kit` | Supply-chain canary tokens | [pypi.org/project/canary-kit](https://pypi.org/project/canary-kit/) |
47
+ | `honeypot-mitre` | Cowrie → MITRE mapping | [pypi.org/project/honeypot-mitre](https://pypi.org/project/honeypot-mitre/) |
48
+ | `dml-spec` | Deception Markup Language | **Not published yet** |
49
+ | `wraithwall-sdk` | This HTTP API client | **Building — publish later** |
50
+
51
+ ## Status
52
+
53
+ Preview — keep building; **do not publish** until product is ready.
@@ -0,0 +1,24 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "wraithwall-sdk"
7
+ version = "0.1.0"
8
+ description = "Official WraithWall HTTP API client SDK (preview) — separate from the wraithwall platform package"
9
+ readme = "README.md"
10
+ requires-python = ">=3.9"
11
+ license = { text = "MIT" }
12
+ authors = [{ name = "WraithWall" }]
13
+ keywords = ["security", "threat-intelligence", "wraithwall", "api", "sdk"]
14
+ dependencies = [
15
+ "requests>=2.28.0",
16
+ ]
17
+
18
+ [project.urls]
19
+ Homepage = "https://wraithwall.online/developers"
20
+ Documentation = "https://wraithwall.online/developers#/sdks"
21
+ Repository = "https://github.com/niffyhunt/wraithwall"
22
+
23
+ [tool.setuptools.packages.find]
24
+ include = ["wraithwall_sdk*"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,31 @@
1
+ """Official WraithWall HTTP API client (preview).
2
+
3
+ Package name on PyPI will be ``wraithwall-sdk`` (when published).
4
+ Import as ``wraithwall_sdk``.
5
+
6
+ This is distinct from the ``wraithwall`` platform package already on PyPI.
7
+ """
8
+
9
+ from .client import WraithWallClient
10
+ from .errors import (
11
+ WraithWallError,
12
+ AuthenticationError,
13
+ PermissionError,
14
+ RateLimitError,
15
+ PaymentRequiredError,
16
+ NotFoundError,
17
+ APIError,
18
+ )
19
+
20
+ __version__ = "0.1.0"
21
+ __all__ = [
22
+ "WraithWallClient",
23
+ "WraithWallError",
24
+ "AuthenticationError",
25
+ "PermissionError",
26
+ "RateLimitError",
27
+ "PaymentRequiredError",
28
+ "NotFoundError",
29
+ "APIError",
30
+ "__version__",
31
+ ]
@@ -0,0 +1,659 @@
1
+ """WraithWall HTTP client with auth, retries, and pagination helpers."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import random
6
+ import time
7
+ from typing import Any, Dict, Iterator, Optional, Union
8
+ from urllib.parse import urljoin
9
+
10
+ import requests
11
+
12
+ from .errors import (
13
+ APIError,
14
+ AuthenticationError,
15
+ NotFoundError,
16
+ PaymentRequiredError,
17
+ PermissionError,
18
+ RateLimitError,
19
+ WraithWallError,
20
+ )
21
+
22
+ DEFAULT_BASE = "https://wraithwall.online"
23
+ DEFAULT_TIMEOUT = 60.0
24
+ DEFAULT_MAX_RETRIES = 4
25
+
26
+
27
+ class WraithWallClient:
28
+ """
29
+ Official Python client (preview).
30
+
31
+ Example::
32
+
33
+ from wraithwall_sdk import WraithWallClient
34
+
35
+ client = WraithWallClient(api_key="ezm_…", api_secret="…")
36
+ print(client.link_status())
37
+ print(client.scan_url("https://example.com"))
38
+ """
39
+
40
+ def __init__(
41
+ self,
42
+ api_key: Optional[str] = None,
43
+ api_secret: Optional[str] = None,
44
+ *,
45
+ base_url: str = DEFAULT_BASE,
46
+ timeout: float = DEFAULT_TIMEOUT,
47
+ max_retries: int = DEFAULT_MAX_RETRIES,
48
+ session: Optional[requests.Session] = None,
49
+ ):
50
+ self.base_url = base_url.rstrip("/") + "/"
51
+ self.api_key = api_key
52
+ self.api_secret = api_secret
53
+ self.timeout = timeout
54
+ self.max_retries = max_retries
55
+ self._session = session or requests.Session()
56
+
57
+ def _headers(self, extra: Optional[Dict[str, str]] = None) -> Dict[str, str]:
58
+ h = {
59
+ "Accept": "application/json",
60
+ "User-Agent": f"wraithwall-sdk-python/{__import__('wraithwall_sdk').__version__}",
61
+ }
62
+ if self.api_key:
63
+ secret = self.api_secret or ""
64
+ h["Authorization"] = f"Bearer {self.api_key}:{secret}"
65
+ h["X-Requested-With"] = "XMLHttpRequest"
66
+ if extra:
67
+ h.update(extra)
68
+ return h
69
+
70
+ def request(
71
+ self,
72
+ method: str,
73
+ path: str,
74
+ *,
75
+ json: Any = None,
76
+ params: Optional[dict] = None,
77
+ headers: Optional[Dict[str, str]] = None,
78
+ timeout: Optional[float] = None,
79
+ ) -> Any:
80
+ url = urljoin(self.base_url, path.lstrip("/"))
81
+ if path.startswith("/"):
82
+ url = self.base_url.rstrip("/") + path
83
+ last_err: Optional[Exception] = None
84
+ for attempt in range(self.max_retries + 1):
85
+ try:
86
+ resp = self._session.request(
87
+ method.upper(),
88
+ url,
89
+ json=json,
90
+ params=params,
91
+ headers=self._headers(headers),
92
+ timeout=timeout or self.timeout,
93
+ )
94
+ except requests.RequestException as e:
95
+ last_err = e
96
+ if attempt >= self.max_retries:
97
+ raise WraithWallError(str(e)) from e
98
+ self._sleep(attempt)
99
+ continue
100
+
101
+ if resp.status_code == 429 and attempt < self.max_retries:
102
+ ra = resp.headers.get("Retry-After")
103
+ try:
104
+ wait = float(ra) if ra else None
105
+ except ValueError:
106
+ wait = None
107
+ self._sleep(attempt, override=wait)
108
+ continue
109
+
110
+ if resp.status_code >= 500 and attempt < self.max_retries:
111
+ self._sleep(attempt)
112
+ continue
113
+
114
+ return self._handle_response(resp)
115
+
116
+ raise WraithWallError(str(last_err) if last_err else "request failed")
117
+
118
+ def _sleep(self, attempt: int, override: Optional[float] = None) -> None:
119
+ if override is not None:
120
+ time.sleep(min(override, 60.0))
121
+ return
122
+ # exponential backoff with jitter
123
+ time.sleep(min((2**attempt) + random.uniform(0, 0.5), 30.0))
124
+
125
+ def _handle_response(self, resp: requests.Response) -> Any:
126
+ try:
127
+ body = resp.json() if resp.content else None
128
+ except ValueError:
129
+ body = resp.text
130
+
131
+ if 200 <= resp.status_code < 300:
132
+ return body
133
+
134
+ msg = None
135
+ if isinstance(body, dict):
136
+ msg = body.get("error") or body.get("message")
137
+ msg = msg or resp.reason or f"HTTP {resp.status_code}"
138
+ headers = dict(resp.headers)
139
+ kwargs = {"status_code": resp.status_code, "body": body, "headers": headers}
140
+
141
+ if resp.status_code == 401:
142
+ raise AuthenticationError(msg, **kwargs)
143
+ if resp.status_code == 402:
144
+ raise PaymentRequiredError(msg, **kwargs)
145
+ if resp.status_code == 403:
146
+ raise PermissionError(msg, **kwargs)
147
+ if resp.status_code == 404:
148
+ raise NotFoundError(msg, **kwargs)
149
+ if resp.status_code == 429:
150
+ raise RateLimitError(msg, **kwargs)
151
+ raise APIError(msg, **kwargs)
152
+
153
+ def get(self, path: str, **kwargs: Any) -> Any:
154
+ return self.request("GET", path, **kwargs)
155
+
156
+ def post(self, path: str, **kwargs: Any) -> Any:
157
+ return self.request("POST", path, **kwargs)
158
+
159
+ def delete(self, path: str, **kwargs: Any) -> Any:
160
+ return self.request("DELETE", path, **kwargs)
161
+
162
+ def patch(self, path: str, **kwargs: Any) -> Any:
163
+ return self.request("PATCH", path, **kwargs)
164
+
165
+ def paginate(
166
+ self,
167
+ path: str,
168
+ *,
169
+ limit: int = 50,
170
+ offset_param: str = "offset",
171
+ limit_param: str = "limit",
172
+ items_key: str = "items",
173
+ max_pages: int = 100,
174
+ **kwargs: Any,
175
+ ) -> Iterator[Any]:
176
+ """
177
+ Yield items from offset/limit style list endpoints.
178
+
179
+ Adapts to bodies with ``pagination.has_more`` when present.
180
+ """
181
+ offset = 0
182
+ for _ in range(max_pages):
183
+ params = dict(kwargs.pop("params", None) or {})
184
+ params[limit_param] = limit
185
+ params[offset_param] = offset
186
+ data = self.get(path, params=params, **kwargs)
187
+ if not isinstance(data, dict):
188
+ return
189
+ items = data.get(items_key)
190
+ if items is None:
191
+ # common alternates
192
+ for k in ("deliveries", "endpoints", "sessions", "results", "data"):
193
+ if isinstance(data.get(k), list):
194
+ items = data[k]
195
+ break
196
+ if not items:
197
+ return
198
+ for item in items:
199
+ yield item
200
+ pag = data.get("pagination") or {}
201
+ if pag.get("has_more") is False:
202
+ return
203
+ if len(items) < limit:
204
+ return
205
+ offset += limit
206
+
207
+ # ── Scanning & Intel ──────────────────────────────────────────────
208
+
209
+ def link_status(self) -> Any:
210
+ """Check scan subsystem health and daily quota."""
211
+ return self.get("/api/link/status")
212
+
213
+ def scan_url(self, url: str) -> Any:
214
+ """Scan a URL, domain, IP, or hash against threat intel sources."""
215
+ return self.post("/api/link/scan", json={"url": url})
216
+
217
+ def scan_stream(self, url: str) -> Any:
218
+ """SSE stream URL for real-time scan results."""
219
+ return self.get(f"/api/link/scan/stream?url={url}")
220
+
221
+ def detonate_url(self, url: str) -> Any:
222
+ """Detonate a URL in an isolated browser container."""
223
+ return self.post("/api/link/detonate", json={"url": url})
224
+
225
+ def public_stats(self) -> Any:
226
+ """Get public platform statistics."""
227
+ return self.get("/api/public/stats")
228
+
229
+ def ip_intel(self, ip: str) -> Any:
230
+ """Comprehensive IP enrichment."""
231
+ return self.get(f"/api/intel/ip/{ip}")
232
+
233
+ def check_abuseipdb(self, ip: str) -> Any:
234
+ """Check IP abuse reputation."""
235
+ return self.post("/api/abuseipdb-check", json={"ip": ip})
236
+
237
+ # ── Fingerprint Intel ─────────────────────────────────────────────
238
+
239
+ def hassh_lookup(self, hassh: str) -> Any:
240
+ """Look up an SSH fingerprint hash (HASSH)."""
241
+ return self.get(f"/api/intel/hassh/{hassh}")
242
+
243
+ def ja3_lookup(self, ja3: str) -> Any:
244
+ """Look up a TLS fingerprint hash (JA3)."""
245
+ return self.get(f"/api/intel/ja3/{ja3}")
246
+
247
+ def analyze_ua(self, ua: str) -> Any:
248
+ """Analyze a user-agent string."""
249
+ return self.post("/api/intel/ua", json={"ua": ua})
250
+
251
+ def analyze_fingerprint(self, **data) -> Any:
252
+ """Comprehensive fingerprint analysis."""
253
+ return self.post("/api/intel/fingerprint", json=data)
254
+
255
+ # ── Cowrie Honeypot ───────────────────────────────────────────────
256
+
257
+ def cowrie_stats(self) -> Any:
258
+ """Aggregated Cowrie honeypot statistics."""
259
+ return self.get("/api/cowrie/stats")
260
+
261
+ def cowrie_sessions(
262
+ self, *, limit: int = 50, offset: int = 0, **filters
263
+ ) -> Any:
264
+ """List Cowrie sessions with pagination."""
265
+ params = {"limit": limit, "offset": offset, **filters}
266
+ return self.get("/api/cowrie/sessions", params=params)
267
+
268
+ def cowrie_session(self, session_id: str) -> Any:
269
+ """Get detailed Cowrie session info."""
270
+ return self.get(f"/api/cowrie/session/{session_id}")
271
+
272
+ def cowrie_session_timeline(self, session_id: str) -> Any:
273
+ """Get a Cowrie session's event timeline."""
274
+ return self.get(f"/api/cowrie/session/{session_id}/timeline")
275
+
276
+ def cowrie_active_count(self) -> Any:
277
+ """Count of currently active Cowrie sessions."""
278
+ return self.get("/api/cowrie/sessions/active/count")
279
+
280
+ def cowrie_unique_ips(self) -> Any:
281
+ """Unique IPs that connected to the honeypot."""
282
+ return self.get("/api/cowrie/sessions/unique_ips")
283
+
284
+ def cowrie_metrics(self) -> Any:
285
+ """Detailed Cowrie honeypot metrics."""
286
+ return self.get("/api/cowrie/metrics")
287
+
288
+ def cowrie_recent(self) -> Any:
289
+ """Recently active Cowrie sessions."""
290
+ return self.get("/api/cowrie/recent")
291
+
292
+ # ── Campaigns ─────────────────────────────────────────────────────
293
+
294
+ def list_campaigns(self) -> Any:
295
+ """List correlated attack campaigns."""
296
+ return self.get("/api/campaigns")
297
+
298
+ def campaign_detail(self, campaign_id: str) -> Any:
299
+ """Get campaign details."""
300
+ return self.get(f"/api/campaigns/{campaign_id}")
301
+
302
+ def campaign_stats(self) -> Any:
303
+ """Aggregated campaign statistics."""
304
+ return self.get("/api/campaigns/stats")
305
+
306
+ # ── Phase 3 Intelligence Layer ────────────────────────────────────
307
+
308
+ def intelligence_health(self) -> Any:
309
+ """Intelligence worker health and enrichment queue depth."""
310
+ return self.get("/api/intelligence/health")
311
+
312
+ def investigation_brief(self, session_id: str) -> Any:
313
+ """Analyst brief: who/what/why/how/when/what-next for a session."""
314
+ return self.get(f"/api/intelligence/session/{session_id}/brief")
315
+
316
+ def threat_reason(self, session_id: str) -> Any:
317
+ """Evidence-backed threat reasoning (not a chatbot)."""
318
+ return self.get(f"/api/intelligence/session/{session_id}/reason")
319
+
320
+ def adaptive_risk(self, session_id: str) -> Any:
321
+ """Adaptive risk score with evidence, reasoning, and recommendations."""
322
+ return self.get(f"/api/intelligence/session/{session_id}/risk")
323
+
324
+ def predict_attacker(self, session_id: str) -> Any:
325
+ """Predictions: next stage, return, escalation, infra/credential reuse."""
326
+ return self.get(f"/api/intelligence/session/{session_id}/predict")
327
+
328
+ def enrich_session(self, session_id: str, *, sync: bool = False) -> Any:
329
+ """Queue (or sync) intelligence enrichment for a session."""
330
+ params = {"sync": "1"} if sync else None
331
+ return self.post(
332
+ f"/api/intelligence/session/{session_id}/enrich",
333
+ params=params,
334
+ )
335
+
336
+ def attacker_profile(self, actor_id: str, *, full: bool = False) -> Any:
337
+ """Persistent attacker memory profile."""
338
+ params = {"full": "1"} if full else None
339
+ return self.get(f"/api/intelligence/attacker/{actor_id}", params=params)
340
+
341
+ def attacker_by_ip(self, ip: str) -> Any:
342
+ """Resolve attacker memory from source IP."""
343
+ return self.get(f"/api/intelligence/attacker/by-ip/{ip}")
344
+
345
+ def campaign_intelligence_summary(self, campaign_id: str) -> Any:
346
+ """Campaign intelligence summary with MITRE and evidence trail."""
347
+ return self.get(f"/api/intelligence/campaign/{campaign_id}/summary")
348
+
349
+ def campaign_intelligence_graph(self, campaign_id: str, *, depth: int = 2) -> Any:
350
+ """Campaign subgraph for visualization."""
351
+ return self.get(
352
+ f"/api/intelligence/campaign/{campaign_id}/graph",
353
+ params={"depth": depth},
354
+ )
355
+
356
+ def intelligence_graph(
357
+ self, node_type: str, node_id: str, *, depth: int = 2
358
+ ) -> Any:
359
+ """Export intelligence subgraph from any node type."""
360
+ return self.get(
361
+ f"/api/intelligence/graph/{node_type}/{node_id}",
362
+ params={"depth": depth},
363
+ )
364
+
365
+ def correlate_sessions(
366
+ self,
367
+ *,
368
+ session_id_a: str | None = None,
369
+ session_id_b: str | None = None,
370
+ session_a: dict | None = None,
371
+ session_b: dict | None = None,
372
+ ) -> Any:
373
+ """Multi-signal correlation between two sessions."""
374
+ body: dict = {}
375
+ if session_id_a:
376
+ body["session_id_a"] = session_id_a
377
+ if session_id_b:
378
+ body["session_id_b"] = session_id_b
379
+ if session_a is not None:
380
+ body["session_a"] = session_a
381
+ if session_b is not None:
382
+ body["session_b"] = session_b
383
+ return self.post("/api/intelligence/correlate", json=body)
384
+
385
+ def attribute_session(
386
+ self, *, session_id: str | None = None, session: dict | None = None
387
+ ) -> Any:
388
+ """Attribute a session to durable attacker memory."""
389
+ body: dict = {}
390
+ if session_id:
391
+ body["session_id"] = session_id
392
+ if session is not None:
393
+ body["session"] = session
394
+ return self.post("/api/intelligence/attribution", json=body)
395
+
396
+ # ── BGP & ASN ─────────────────────────────────────────────────────
397
+
398
+ def bgp_status(self) -> Any:
399
+ """BGP monitoring system status."""
400
+ return self.get("/api/bgp/status")
401
+
402
+ def bgp_alerts(self) -> Any:
403
+ """BGP routing alerts and anomalies."""
404
+ return self.get("/api/bgp/alerts")
405
+
406
+ def bgp_hijacks(self) -> Any:
407
+ """Active BGP hijack detections."""
408
+ return self.get("/api/bgp/hijacks/active")
409
+
410
+ def bgp_check_ip(self, ip: str) -> Any:
411
+ """Check BGP routing for an IP."""
412
+ return self.get(f"/api/bgp/check-ip/{ip}")
413
+
414
+ def asn_heatmap(self) -> Any:
415
+ """ASN-based threat heatmap."""
416
+ return self.get("/api/intel/asn-heatmap")
417
+
418
+ def submit_abuse_report(self, **data) -> Any:
419
+ """Submit an abuse report for a malicious IP/domain."""
420
+ return self.post("/api/intel/abuse-report", json=data)
421
+
422
+ # ── Webhooks ──────────────────────────────────────────────────────
423
+
424
+ def list_webhook_events(self) -> Any:
425
+ """List deliverable webhook event types."""
426
+ return self.get("/api/webhooks/events")
427
+
428
+ def webhook_event_schema(self, event_type: str) -> Any:
429
+ """JSON Schema for a specific webhook event."""
430
+ return self.get(f"/api/webhooks/events/{event_type}/schema")
431
+
432
+ def webhook_health(self) -> Any:
433
+ """Webhook subsystem health and queue depth."""
434
+ return self.get("/api/webhooks/health")
435
+
436
+ def list_webhooks(self) -> Any:
437
+ """List webhook endpoints for this user."""
438
+ return self.get("/api/webhooks/endpoints")
439
+
440
+ def create_webhook(
441
+ self,
442
+ url: str,
443
+ events: list,
444
+ *,
445
+ description: str = "",
446
+ ) -> Any:
447
+ """Create a webhook endpoint. Secret returned once in response."""
448
+ return self.post(
449
+ "/api/webhooks/endpoints",
450
+ json={"url": url, "events": events, "description": description},
451
+ )
452
+
453
+ def get_webhook(self, endpoint_id: str) -> Any:
454
+ """Get a single webhook endpoint (no secret returned)."""
455
+ return self.get(f"/api/webhooks/endpoints/{endpoint_id}")
456
+
457
+ def update_webhook(self, endpoint_id: str, **data) -> Any:
458
+ """Update webhook URL, events, description, or enabled flag."""
459
+ return self.patch(f"/api/webhooks/endpoints/{endpoint_id}", json=data)
460
+
461
+ def delete_webhook(self, endpoint_id: str) -> Any:
462
+ """Delete a webhook endpoint and its delivery history."""
463
+ return self.delete(f"/api/webhooks/endpoints/{endpoint_id}")
464
+
465
+ def rotate_webhook_secret(self, endpoint_id: str) -> Any:
466
+ """Rotate webhook signing secret. Previous stays valid 24h."""
467
+ return self.post(
468
+ f"/api/webhooks/endpoints/{endpoint_id}/rotate-secret"
469
+ )
470
+
471
+ def list_webhook_deliveries(
472
+ self, endpoint_id: str, *, limit: int = 50, offset: int = 0
473
+ ) -> Any:
474
+ """Paginated delivery history for an endpoint."""
475
+ return self.get(
476
+ f"/api/webhooks/endpoints/{endpoint_id}/deliveries",
477
+ params={"limit": limit, "offset": offset},
478
+ )
479
+
480
+ def replay_webhook_delivery(
481
+ self, endpoint_id: str, delivery_id: str
482
+ ) -> Any:
483
+ """Re-send a prior delivery payload."""
484
+ return self.post(
485
+ f"/api/webhooks/endpoints/{endpoint_id}/deliveries/{delivery_id}/replay"
486
+ )
487
+
488
+ def test_webhook(self, endpoint_id: str) -> Any:
489
+ """Send a synchronous webhook.test event."""
490
+ return self.post(
491
+ f"/api/webhooks/endpoints/{endpoint_id}/test"
492
+ )
493
+
494
+ def verify_signature(
495
+ self, secret: str, signature: str, body: str
496
+ ) -> Any:
497
+ """Validate a t=,v1= signature server-side."""
498
+ return self.post(
499
+ "/api/webhooks/verify-signature",
500
+ json={"secret": secret, "signature": signature, "body": body},
501
+ )
502
+
503
+ # ── Canary / Deception ──────────────────────────────────────────
504
+
505
+ def list_canaries(self) -> Any:
506
+ """List canary tokens for this user."""
507
+ return self.get("/api/canary-service/tokens")
508
+
509
+ def create_canary(self, **data) -> Any:
510
+ """Create a new canary token."""
511
+ return self.post("/api/canary-service/create", json=data)
512
+
513
+ def canary_hits(self, public_id: str) -> Any:
514
+ """Retrieve hit events for a canary token."""
515
+ return self.get(
516
+ f"/api/canary-service/tokens/{public_id}/hits"
517
+ )
518
+
519
+ def deactivate_canary(self, public_id: str) -> Any:
520
+ """Deactivate a canary token."""
521
+ return self.post(
522
+ f"/api/canary-service/tokens/{public_id}/deactivate"
523
+ )
524
+
525
+ def deception_events(self) -> Any:
526
+ """List all deception infrastructure events."""
527
+ return self.get("/api/deception/events")
528
+
529
+ def deception_events_by_ip(self, ip: str) -> Any:
530
+ """Deception events filtered by attacker IP."""
531
+ return self.get(f"/api/deception/events/{ip}")
532
+
533
+ def deception_stats(self) -> Any:
534
+ """Aggregated deception statistics."""
535
+ return self.get("/api/deception/stats")
536
+
537
+ # ── LLM Security ──────────────────────────────────────────────────
538
+
539
+ def llm_firewall_check(self, prompt: str, model: str = "gpt-4") -> Any:
540
+ """Check a prompt for injection, PII, policy violations."""
541
+ return self.post(
542
+ "/api/llm-firewall/check",
543
+ json={"prompt": prompt, "model": model},
544
+ )
545
+
546
+ def llm_firewall_stats(self) -> Any:
547
+ """LLM firewall detection statistics."""
548
+ return self.get("/api/llm-firewall/stats")
549
+
550
+ def llm_firewall_events(self) -> Any:
551
+ """LLM firewall detection events."""
552
+ return self.get("/api/llm-firewall/events")
553
+
554
+ def llm_firewall_test(self, prompt: str) -> Any:
555
+ """Test a prompt against the firewall (no key required, no alerts)."""
556
+ return self.post("/api/llm-firewall/test", json={"prompt": prompt})
557
+
558
+ def llm_firewall_configure_webhook(self, **config) -> Any:
559
+ """Configure alerting webhooks for your LLM firewall key."""
560
+ return self.post("/api/llm-firewall/webhook/configure", json=config)
561
+
562
+ def llm_firewall_test_webhook(self) -> Any:
563
+ """Fire a synthetic block alert to verify webhook integration."""
564
+ return self.post("/api/llm-firewall/webhook/test")
565
+
566
+ def llm_firewall_create_key(self, label: str) -> Any:
567
+ """Create a new LLM firewall API key."""
568
+ return self.post("/api/llm-firewall/api-key/create", json={"label": label})
569
+
570
+ def llm_firewall_health(self) -> Any:
571
+ """LLM firewall service health check."""
572
+ return self.get("/api/llm-firewall/health")
573
+
574
+ # ── LLM Honeypot ──────────────────────────────────────────────────
575
+
576
+ def llm_chat(self, messages: list, model: str = None) -> Any:
577
+ """Send a chat completion to the LLM honeypot (OpenAI-compatible)."""
578
+ body = {"messages": messages}
579
+ if model: body["model"] = model
580
+ return self.post("/api/ai/v1/chat/completions", json=body)
581
+
582
+ def llm_embed(self, text: str) -> Any:
583
+ """Generate fake embedding vector (logs access, no real inference)."""
584
+ return self.post("/api/ai/internal/embed", json={"input": text})
585
+
586
+ def llm_models(self) -> Any:
587
+ """List available model names served by the honeypot."""
588
+ return self.get("/api/ai/v1/models")
589
+
590
+ def llm_corpus(self) -> Any:
591
+ """View collected prompt injection attempts (admin)."""
592
+ return self.get("/api/admin/llm-corpus")
593
+
594
+ def llm_techniques(self) -> Any:
595
+ """Aggregated prompt injection technique statistics."""
596
+ return self.get("/api/intel/llm-techniques")
597
+
598
+ # ── Campaign Correlation ──────────────────────────────────────────
599
+
600
+ def campaign_ingest(self, session_data: dict) -> Any:
601
+ """Ingest a session into the campaign correlation engine."""
602
+ return self.post("/api/campaigns/ingest", json=session_data)
603
+
604
+ # ── Sandbox ───────────────────────────────────────────────────────
605
+
606
+ def sandbox_status(self) -> Any:
607
+ """Check sandbox session status."""
608
+ return self.get("/api/sandbox/status")
609
+
610
+ def sandbox_history(self) -> Any:
611
+ """Historical sandbox session records."""
612
+ return self.get("/api/sandbox/history")
613
+
614
+ def detonation_status(self, job_id: str) -> Any:
615
+ """Check detonation job status."""
616
+ return self.get(f"/api/link/detonate/status/{job_id}")
617
+
618
+ def detonation_report(self, job_id: str) -> Any:
619
+ """Get the full detonation report."""
620
+ return self.get(f"/api/link/detonate/report/{job_id}")
621
+
622
+ # ── Credential Lures ──────────────────────────────────────────────
623
+
624
+ def list_lures(self) -> Any:
625
+ """List planted credential lures."""
626
+ return self.get("/api/lures")
627
+
628
+ def plant_lure(self, **data) -> Any:
629
+ """Deploy a new credential lure."""
630
+ return self.post("/api/lures/plant", json=data)
631
+
632
+ def lure_stats(self) -> Any:
633
+ """Credential lure statistics."""
634
+ return self.get("/api/lures/stats")
635
+
636
+ def delete_lure(self, lure_id) -> Any:
637
+ """Remove a planted credential lure."""
638
+ return self.delete(f"/api/lures/{lure_id}")
639
+
640
+ # ── API Keys ──────────────────────────────────────────────────────
641
+
642
+ def list_api_keys(self) -> Any:
643
+ """List API keys for the authenticated user."""
644
+ return self.get("/api/keys")
645
+
646
+ def create_api_key(self, label: str, permissions: list) -> Any:
647
+ """Create a new API key."""
648
+ return self.post(
649
+ "/api/keys",
650
+ json={"label": label, "permissions": permissions},
651
+ )
652
+
653
+ def revoke_api_key(self, key_id: int) -> Any:
654
+ """Revoke an API key."""
655
+ return self.post(f"/api/keys/{key_id}/revoke")
656
+
657
+ def list_scopes(self) -> Any:
658
+ """List all valid permission scopes."""
659
+ return self.get("/api/keys/scopes")
@@ -0,0 +1,56 @@
1
+ """Typed exception hierarchy for the WraithWall Python SDK."""
2
+
3
+ from __future__ import annotations
4
+ from typing import Any, Optional
5
+
6
+
7
+ class WraithWallError(Exception):
8
+ """Base error for all SDK failures."""
9
+
10
+ def __init__(
11
+ self,
12
+ message: str,
13
+ *,
14
+ status_code: Optional[int] = None,
15
+ body: Any = None,
16
+ headers: Optional[dict] = None,
17
+ ):
18
+ super().__init__(message)
19
+ self.message = message
20
+ self.status_code = status_code
21
+ self.body = body
22
+ self.headers = headers or {}
23
+
24
+
25
+ class AuthenticationError(WraithWallError):
26
+ """401 — invalid or missing credentials."""
27
+
28
+
29
+ class PermissionError(WraithWallError):
30
+ """403 — missing scope or origin gate."""
31
+
32
+
33
+ class PaymentRequiredError(WraithWallError):
34
+ """402 — API key age / plan gate."""
35
+
36
+
37
+ class RateLimitError(WraithWallError):
38
+ """429 — rate limited."""
39
+
40
+ @property
41
+ def retry_after(self) -> Optional[float]:
42
+ raw = self.headers.get("Retry-After") or self.headers.get("retry-after")
43
+ if raw is None:
44
+ return None
45
+ try:
46
+ return float(raw)
47
+ except (TypeError, ValueError):
48
+ return None
49
+
50
+
51
+ class NotFoundError(WraithWallError):
52
+ """404 — missing resource or disabled subsystem."""
53
+
54
+
55
+ class APIError(WraithWallError):
56
+ """Other 4xx/5xx API errors."""
@@ -0,0 +1,67 @@
1
+ Metadata-Version: 2.4
2
+ Name: wraithwall-sdk
3
+ Version: 0.1.0
4
+ Summary: Official WraithWall HTTP API client SDK (preview) — separate from the wraithwall platform package
5
+ Author: WraithWall
6
+ License: MIT
7
+ Project-URL: Homepage, https://wraithwall.online/developers
8
+ Project-URL: Documentation, https://wraithwall.online/developers#/sdks
9
+ Project-URL: Repository, https://github.com/niffyhunt/wraithwall
10
+ Keywords: security,threat-intelligence,wraithwall,api,sdk
11
+ Requires-Python: >=3.9
12
+ Description-Content-Type: text/markdown
13
+ Requires-Dist: requests>=2.28.0
14
+
15
+ # wraithwall-sdk (Python)
16
+
17
+ Official **HTTP API client** for [WraithWall](https://wraithwall.online/developers) — preview `0.1.0`.
18
+
19
+ > **Name note:** PyPI already has the **`wraithwall`** platform package. This client
20
+ > will publish as **`wraithwall-sdk`** so it does not collide. Import module:
21
+ > `wraithwall_sdk`.
22
+
23
+ ## Install (from monorepo — not published yet)
24
+
25
+ ```bash
26
+ pip install -e ./sdks/python
27
+ # after publish:
28
+ # pip install wraithwall-sdk
29
+ ```
30
+
31
+ ## Quick start
32
+
33
+ ```python
34
+ import os
35
+ from wraithwall_sdk import WraithWallClient
36
+
37
+ client = WraithWallClient(
38
+ api_key=os.environ["WRAITHWALL_API_KEY"],
39
+ api_secret=os.environ["WRAITHWALL_API_SECRET"],
40
+ )
41
+
42
+ print(client.link_status())
43
+ print(client.scan_url("https://example.com"))
44
+ ```
45
+
46
+ ## Features
47
+
48
+ - `Authorization: Bearer key:secret` helper
49
+ - Typed errors (`AuthenticationError`, `RateLimitError`, `PaymentRequiredError`, …)
50
+ - Exponential backoff with jitter on `429` / `5xx`
51
+ - Offset/limit pagination helper
52
+ - Helpers: scan, intel, cowrie stats, webhooks
53
+
54
+ ## Related published packages
55
+
56
+ | Package | Role | PyPI |
57
+ |---------|------|------|
58
+ | `wraithwall` | Platform / OSS distribution | [pypi.org/project/wraithwall](https://pypi.org/project/wraithwall/) |
59
+ | `ravenscan` | Engineering intelligence CLI (`raven`) | [pypi.org/project/ravenscan](https://pypi.org/project/ravenscan/) |
60
+ | `canary-kit` | Supply-chain canary tokens | [pypi.org/project/canary-kit](https://pypi.org/project/canary-kit/) |
61
+ | `honeypot-mitre` | Cowrie → MITRE mapping | [pypi.org/project/honeypot-mitre](https://pypi.org/project/honeypot-mitre/) |
62
+ | `dml-spec` | Deception Markup Language | **Not published yet** |
63
+ | `wraithwall-sdk` | This HTTP API client | **Building — publish later** |
64
+
65
+ ## Status
66
+
67
+ Preview — keep building; **do not publish** until product is ready.
@@ -0,0 +1,10 @@
1
+ README.md
2
+ pyproject.toml
3
+ wraithwall_sdk/__init__.py
4
+ wraithwall_sdk/client.py
5
+ wraithwall_sdk/errors.py
6
+ wraithwall_sdk.egg-info/PKG-INFO
7
+ wraithwall_sdk.egg-info/SOURCES.txt
8
+ wraithwall_sdk.egg-info/dependency_links.txt
9
+ wraithwall_sdk.egg-info/requires.txt
10
+ wraithwall_sdk.egg-info/top_level.txt
@@ -0,0 +1 @@
1
+ requests>=2.28.0
@@ -0,0 +1 @@
1
+ wraithwall_sdk