wraithwall-sdk 0.1.1__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.
@@ -0,0 +1,51 @@
1
+ # Changelog
2
+
3
+ ## 0.1.1 — 2026-11-17
4
+
5
+ First supported public release. The 2026-10-07 `0.1.0` artifact was uploaded by
6
+ mistake and deleted on 2026-10-12; PyPI does not allow that filename to be
7
+ reused, so the first supported release is `0.1.1`.
8
+
9
+ ## 0.1.0 — 2026-10-07 — deleted, do not use
10
+
11
+ Accidental preview upload; removed from PyPI on 2026-10-12. Its distribution
12
+ filenames cannot be uploaded again.
13
+
14
+ ### Security
15
+
16
+ #### Red-team hardening
17
+
18
+ - Refuse an `https` → `http` redirect instead of silently downgrading TLS.
19
+ - Clamp a negative/malicious `Retry-After` to zero (it previously reached
20
+ `time.sleep()` and raised).
21
+ - Reject control characters in a request path and non-alphabetic methods.
22
+ - Reject a `base_url` that carries a path (only `/` is allowed).
23
+ - `scan_file()` accepts only regular files, refuses devices/FIFOs/sockets, and
24
+ caps the read at `WRAITHWALL_SDK_MAX_UPLOAD_BYTES` (25 MiB default), so
25
+ `/dev/zero` or an untrusted path cannot hang the process or exhaust memory.
26
+ - An empty webhook signing secret is rejected instead of HMAC-verifying with an
27
+ empty key.
28
+ - Pagination ignores a non-list `items` value instead of iterating characters.
29
+
30
+ - `base_url` must be `https://`; `http://` is accepted only for loopback
31
+ (`localhost`, `127.0.0.1`, `::1`). Embedded credentials, query strings and
32
+ fragments are rejected.
33
+ - A caller-supplied path that resolves to a different origin is refused before
34
+ any request is sent, so the `Authorization` header cannot be exfiltrated by
35
+ an absolute URL.
36
+ - TLS verification stays on; cross-host redirects and redirects on non-safe
37
+ methods are refused.
38
+ - POST and PATCH are not retried; safe methods retry with capped backoff and
39
+ honour `Retry-After` (maximum 60 s).
40
+ - `repr()`/`str()` expose only whether a key is set, never its value.
41
+ - `verify_webhook_signature()` uses `hmac.compare_digest` and a 300-second
42
+ timestamp tolerance, with optional alternate secrets for rotation.
43
+
44
+ ### Added
45
+
46
+ - Typed errors (`AuthenticationError`, `PermissionError`,
47
+ `PaymentRequiredError`, `RateLimitError`, `ValidationError`,
48
+ `NotFoundError`, `APIError`).
49
+ - Offset/limit pagination helper.
50
+ - Helpers for scanning, intel, Cowrie, campaigns, webhooks and canaries.
51
+ - 16 offline HTTP tests; no network and no real keys in the suite.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 niffy_hunt
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,2 @@
1
+ include README.md SECURITY.md CHANGELOG.md LICENSE
2
+ recursive-include wraithwall_sdk *.py py.typed
@@ -0,0 +1,128 @@
1
+ Metadata-Version: 2.4
2
+ Name: wraithwall-sdk
3
+ Version: 0.1.1
4
+ Summary: WraithWall HTTP API client — scanning, intel, Cowrie, campaigns, MITRE, BGP, webhooks and streaming
5
+ Author: WraithWall
6
+ License-Expression: 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
+ Project-URL: Changelog, https://github.com/niffyhunt/wraithwall/blob/main/sdks/python/CHANGELOG.md
11
+ Project-URL: Security, https://github.com/niffyhunt/wraithwall/blob/main/sdks/python/SECURITY.md
12
+ Keywords: security,threat-intelligence,wraithwall,api,sdk,bgp,cowrie
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Topic :: Security
20
+ Classifier: Typing :: Typed
21
+ Classifier: Operating System :: OS Independent
22
+ Requires-Python: >=3.11
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Requires-Dist: requests>=2.28.0
26
+ Requires-Dist: certifi>=2026.10.19
27
+ Dynamic: license-file
28
+
29
+ # wraithwall-sdk (Python)
30
+
31
+ Official Python client for the [WraithWall HTTP API](https://wraithwall.online/developers).
32
+
33
+ `0.1.1` · Python 3.11+ · MIT
34
+
35
+ > This is the **client** package. The platform distribution is the separate
36
+ > [`wraithwall`](https://pypi.org/project/wraithwall/) package. An accidental
37
+ > preview of this client was deleted from PyPI on 2026-10-12; `0.1.0` here is
38
+ > the first supported release (0.1.1).
39
+
40
+ ## Install
41
+
42
+ ```bash
43
+ pip install wraithwall-sdk
44
+ ```
45
+
46
+ From a checkout:
47
+
48
+ ```bash
49
+ cd sdks/python
50
+ python -m build
51
+ pip install dist/wraithwall_sdk-0.1.1-py3-none-any.whl
52
+ ```
53
+
54
+ ## Quick start
55
+
56
+ ```python
57
+ import os
58
+ from wraithwall_sdk import WraithWallClient
59
+
60
+ client = WraithWallClient(
61
+ api_key=os.environ["WRAITHWALL_API_KEY"],
62
+ api_secret=os.environ["WRAITHWALL_API_SECRET"],
63
+ )
64
+
65
+ print(client.link_status())
66
+ print(client.scan_url("https://example.com"))
67
+ print(client.mitre_matrix())
68
+ ```
69
+
70
+ Public helpers (WHOIS, URL/IP reputation, public stats) work without a key.
71
+
72
+ ## What is covered
73
+
74
+ Scanning and detonation, fingerprint intel, Cowrie sessions, campaigns,
75
+ intelligence, MITRE ATT&CK, playbooks, analytics/prediction, BGP, webhooks,
76
+ canaries/lures, LLM firewall, AIRS, DML, provenance, Raven and streaming.
77
+ The exact catalogue coverage and the deliberate exclusions (browser auth/2FA,
78
+ admin, proof-of-work gateway, contact forms, canary beacon, sandbox trial) are
79
+ in [`../COVERAGE.md`](../COVERAGE.md).
80
+
81
+ ## Behaviour worth knowing
82
+
83
+ - `Authorization: Bearer <key>:<secret>`; `X-Requested-With: XMLHttpRequest`
84
+ is added on every request (the API's origin gate needs it on public POSTs).
85
+ - TLS verification is always on. `base_url` must be `https://`; `http://` is
86
+ accepted only for loopback development.
87
+ - A caller-supplied path cannot change the destination origin, so the key
88
+ cannot be redirected to another host.
89
+ - GET/HEAD/OPTIONS/PUT/DELETE retry on timeouts, 429 and 5xx with capped
90
+ backoff; **POST and PATCH are never retried**.
91
+ - Cross-host redirects and redirects on non-safe methods are refused.
92
+ - Typed errors: `AuthenticationError`, `PermissionError`,
93
+ `PaymentRequiredError`, `RateLimitError`, `ValidationError`,
94
+ `NotFoundError`, `APIError`.
95
+ - `verify_webhook_signature()` uses constant-time comparison and a 300-second
96
+ timestamp tolerance; an empty secret is rejected.
97
+ - `scan_file()` accepts only regular files and caps the read at 25 MiB.
98
+ - `repr()`/`str()` expose only whether a key is set.
99
+
100
+ ## Pagination
101
+
102
+ ```python
103
+ for session in client.paginate("/api/cowrie/sessions", limit=50):
104
+ print(session["session_id"])
105
+ ```
106
+
107
+ ## Webhooks
108
+
109
+ ```python
110
+ from wraithwall_sdk import verify_webhook_signature
111
+
112
+ ok, reason = verify_webhook_signature(
113
+ os.environ["WRAITHWALL_WEBHOOK_SECRET"],
114
+ request.headers["X-WraithWall-Signature"],
115
+ request.body,
116
+ )
117
+ ```
118
+
119
+ ## Development
120
+
121
+ ```bash
122
+ PYTHONPATH=. pytest -q tests # 46 offline tests, no network, no real keys
123
+ python -m build && twine check dist/*
124
+ ```
125
+
126
+ Security policy: [`SECURITY.md`](./SECURITY.md) · Changes:
127
+ [`CHANGELOG.md`](./CHANGELOG.md) · Release steps:
128
+ [`../../docs/sdk-release-plan.md`](../../docs/sdk-release-plan.md).
@@ -0,0 +1,100 @@
1
+ # wraithwall-sdk (Python)
2
+
3
+ Official Python client for the [WraithWall HTTP API](https://wraithwall.online/developers).
4
+
5
+ `0.1.1` · Python 3.11+ · MIT
6
+
7
+ > This is the **client** package. The platform distribution is the separate
8
+ > [`wraithwall`](https://pypi.org/project/wraithwall/) package. An accidental
9
+ > preview of this client was deleted from PyPI on 2026-10-12; `0.1.0` here is
10
+ > the first supported release (0.1.1).
11
+
12
+ ## Install
13
+
14
+ ```bash
15
+ pip install wraithwall-sdk
16
+ ```
17
+
18
+ From a checkout:
19
+
20
+ ```bash
21
+ cd sdks/python
22
+ python -m build
23
+ pip install dist/wraithwall_sdk-0.1.1-py3-none-any.whl
24
+ ```
25
+
26
+ ## Quick start
27
+
28
+ ```python
29
+ import os
30
+ from wraithwall_sdk import WraithWallClient
31
+
32
+ client = WraithWallClient(
33
+ api_key=os.environ["WRAITHWALL_API_KEY"],
34
+ api_secret=os.environ["WRAITHWALL_API_SECRET"],
35
+ )
36
+
37
+ print(client.link_status())
38
+ print(client.scan_url("https://example.com"))
39
+ print(client.mitre_matrix())
40
+ ```
41
+
42
+ Public helpers (WHOIS, URL/IP reputation, public stats) work without a key.
43
+
44
+ ## What is covered
45
+
46
+ Scanning and detonation, fingerprint intel, Cowrie sessions, campaigns,
47
+ intelligence, MITRE ATT&CK, playbooks, analytics/prediction, BGP, webhooks,
48
+ canaries/lures, LLM firewall, AIRS, DML, provenance, Raven and streaming.
49
+ The exact catalogue coverage and the deliberate exclusions (browser auth/2FA,
50
+ admin, proof-of-work gateway, contact forms, canary beacon, sandbox trial) are
51
+ in [`../COVERAGE.md`](../COVERAGE.md).
52
+
53
+ ## Behaviour worth knowing
54
+
55
+ - `Authorization: Bearer <key>:<secret>`; `X-Requested-With: XMLHttpRequest`
56
+ is added on every request (the API's origin gate needs it on public POSTs).
57
+ - TLS verification is always on. `base_url` must be `https://`; `http://` is
58
+ accepted only for loopback development.
59
+ - A caller-supplied path cannot change the destination origin, so the key
60
+ cannot be redirected to another host.
61
+ - GET/HEAD/OPTIONS/PUT/DELETE retry on timeouts, 429 and 5xx with capped
62
+ backoff; **POST and PATCH are never retried**.
63
+ - Cross-host redirects and redirects on non-safe methods are refused.
64
+ - Typed errors: `AuthenticationError`, `PermissionError`,
65
+ `PaymentRequiredError`, `RateLimitError`, `ValidationError`,
66
+ `NotFoundError`, `APIError`.
67
+ - `verify_webhook_signature()` uses constant-time comparison and a 300-second
68
+ timestamp tolerance; an empty secret is rejected.
69
+ - `scan_file()` accepts only regular files and caps the read at 25 MiB.
70
+ - `repr()`/`str()` expose only whether a key is set.
71
+
72
+ ## Pagination
73
+
74
+ ```python
75
+ for session in client.paginate("/api/cowrie/sessions", limit=50):
76
+ print(session["session_id"])
77
+ ```
78
+
79
+ ## Webhooks
80
+
81
+ ```python
82
+ from wraithwall_sdk import verify_webhook_signature
83
+
84
+ ok, reason = verify_webhook_signature(
85
+ os.environ["WRAITHWALL_WEBHOOK_SECRET"],
86
+ request.headers["X-WraithWall-Signature"],
87
+ request.body,
88
+ )
89
+ ```
90
+
91
+ ## Development
92
+
93
+ ```bash
94
+ PYTHONPATH=. pytest -q tests # 46 offline tests, no network, no real keys
95
+ python -m build && twine check dist/*
96
+ ```
97
+
98
+ Security policy: [`SECURITY.md`](./SECURITY.md) · Changes:
99
+ [`CHANGELOG.md`](./CHANGELOG.md) · Release steps:
100
+ [`../../docs/sdk-release-plan.md`](../../docs/sdk-release-plan.md).
@@ -0,0 +1,41 @@
1
+ # Security policy — WraithWall SDK (Python)
2
+
3
+ ## Status
4
+
5
+ `wraithwall-sdk` is a **local preview**. It is not published on PyPI. Do not
6
+ install a package with this name from any registry: an earlier accidental
7
+ preview was deleted on 2026-10-12 and the name currently returns 404.
8
+
9
+ ## Supported versions
10
+
11
+ | Version | Supported |
12
+ |---|---|
13
+ | 0.1.x (preview, source checkout) | Yes, best effort |
14
+ | Anything from a registry | No — do not use |
15
+
16
+ ## Reporting a vulnerability
17
+
18
+ Email **contact@wraithwall.online** with:
19
+
20
+ - the SDK version and Python version;
21
+ - a minimal reproduction that does not contain real API keys;
22
+ - the impact you believe it has.
23
+
24
+ Do **not** open a public issue for a vulnerability, and do not include live
25
+ `ezm_…` keys or API secrets. Redact them as `ezm_<redacted>`.
26
+
27
+ We will acknowledge receipt and tell you whether the report is in scope. This
28
+ is a preview with no bug-bounty programme; there is no reward.
29
+
30
+ ## Security properties the client intends to keep
31
+
32
+ - TLS verification is always on; `base_url` must be `https://` except for
33
+ loopback development.
34
+ - A caller-supplied path can never change the destination origin, so the
35
+ `Authorization` header cannot be redirected to another host.
36
+ - POST/PATCH are not retried; GET/HEAD/OPTIONS/PUT/DELETE are.
37
+ - Cross-host redirects are refused; redirects on non-safe methods are refused.
38
+ - Credentials are never included in `repr()`/`str()`.
39
+ - Webhook signatures are compared in constant time with a timestamp tolerance.
40
+
41
+ Report a regression in any of these as a security issue.
@@ -0,0 +1,43 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "wraithwall-sdk"
7
+ version = "0.1.1"
8
+ description = "WraithWall HTTP API client — scanning, intel, Cowrie, campaigns, MITRE, BGP, webhooks and streaming"
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ classifiers = [
14
+ "Development Status :: 4 - Beta",
15
+ "Intended Audience :: Developers",
16
+ "Programming Language :: Python :: 3",
17
+ "Programming Language :: Python :: 3.11",
18
+ "Programming Language :: Python :: 3.12",
19
+ "Programming Language :: Python :: 3.13",
20
+ "Topic :: Security",
21
+ "Typing :: Typed",
22
+ "Operating System :: OS Independent",
23
+ ]
24
+ authors = [{ name = "WraithWall" }]
25
+ keywords = ["security", "threat-intelligence", "wraithwall", "api", "sdk", "bgp", "cowrie"]
26
+ dependencies = [
27
+ "requests>=2.28.0",
28
+ # TLS trust floor (eMudhra/emSign compromise, GHSA-6q48-6c7w-9gw2).
29
+ "certifi>=2026.10.19",
30
+ ]
31
+
32
+ [project.urls]
33
+ Homepage = "https://wraithwall.online/developers"
34
+ Documentation = "https://wraithwall.online/developers#/sdks"
35
+ Repository = "https://github.com/niffyhunt/wraithwall"
36
+ Changelog = "https://github.com/niffyhunt/wraithwall/blob/main/sdks/python/CHANGELOG.md"
37
+ Security = "https://github.com/niffyhunt/wraithwall/blob/main/sdks/python/SECURITY.md"
38
+
39
+ [tool.setuptools.packages.find]
40
+ include = ["wraithwall_sdk*"]
41
+
42
+ [tool.setuptools.package-data]
43
+ wraithwall_sdk = ["py.typed"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+