From 0e98cd5630ea8d51f507579d937444eee2aa21fd Mon Sep 17 00:00:00 2001 From: Alexandre Dulaunoy Date: Thu, 29 Oct 2026 18:08:29 +0100 Subject: [PATCH 1/2] feat: [cape_sandbox] add sample submission and report enrichment --- documentation/expansion/cape_sandbox.md | 11 + .../modules/expansion/cape_sandbox.py | 259 ++++++++++++++++++ tests/test_cape_sandbox.py | 121 ++++++++ 3 files changed, 391 insertions(+) create mode 100644 documentation/expansion/cape_sandbox.md create mode 100644 misp_modules/modules/expansion/cape_sandbox.py create mode 100644 tests/test_cape_sandbox.py diff --git a/documentation/expansion/cape_sandbox.md b/documentation/expansion/cape_sandbox.md new file mode 100644 index 00000000..e16e5249 --- /dev/null +++ b/documentation/expansion/cape_sandbox.md @@ -0,0 +1,11 @@ +# CAPE Sandbox Enrichment + +Submit supplied samples to CAPEv2 or retrieve a completed JSON report by numeric task ID. Set api_url to the API v2 base, for example https://cape.example/apiv2. api_key is optional when the server permits unauthenticated requests. submit_samples defaults to false. max_size_mb defaults to 25 (1–100). Submission returns task IDs; use a text attribute containing a task ID for a later report lookup. Completed reports yield file hashes, network pivots and extracted configurations. + +Input: text, attachment, malware-sample. + +Configuration: api_url, api_key, submit_samples, max_size_mb, max_results. Required: api_url. + +max_results defaults to 25 and accepts 1–100. New attributes use `to_ids=false`; the source UUID, detection flag and metadata are preserved. Objects reference the source attribute. Requests verify TLS, reject redirects and use connection/read timeouts of 5/30 seconds. API errors do not echo credentials. No automatic submission retries or background polling occur. + +Reference: https://capev2.readthedocs.io/en/latest/usage/api.html diff --git a/misp_modules/modules/expansion/cape_sandbox.py b/misp_modules/modules/expansion/cape_sandbox.py new file mode 100644 index 00000000..0a62419f --- /dev/null +++ b/misp_modules/modules/expansion/cape_sandbox.py @@ -0,0 +1,259 @@ +import base64 +import hashlib +import io +import ipaddress +import json +import re +import zipfile +from urllib.parse import urlsplit +from uuid import UUID +import requests +from pymisp import MISPEvent, MISPObject +from pymisp.exceptions import PyMISPError + + +class ModuleError(ValueError): + """A diagnostic safe to show to the analyst.""" + + +def _integer(config, key, default, maximum=100): + value = config.get(key) + if value is None or value == "": + return default + if isinstance(value, bool) or not str(value).isdigit() or (not 1 <= int(value) <= maximum): + raise ModuleError(f"{key} must be an integer between 1 and {maximum}.") + return int(value) + + +def _enabled(config, key, default=False): + value = config.get(key) + if value is None or value == "": + return default + if isinstance(value, bool): + return value + if str(value).lower() not in ("true", "false", "1", "0"): + raise ModuleError(f"{key} must be true or false.") + return str(value).lower() in ("true", "1") + + +def _url(value): + if not isinstance(value, str) or any(ord(c) <= 32 or ord(c) == 127 for c in value): + raise ModuleError("Invalid HTTPS URL.") + parsed = urlsplit(value) + if parsed.scheme != "https" or not parsed.hostname or parsed.username or parsed.password or parsed.fragment: + raise ModuleError("An HTTPS URL without credentials or fragment is required.") + parsed.port + return value.rstrip("/") + + +def _origin(config): + value = _url(config.get("api_url", "")) + if urlsplit(value).query: + raise ModuleError("api_url cannot contain a query string.") + return value + + +def _normalise(kind, value): + if not isinstance(value, str) or not value.strip() or any(ord(c) < 32 for c in value): + raise ModuleError("A nonempty string value is required.") + value = value.strip() + if kind in ("md5", "sha1", "sha256", "x509-fingerprint-sha256"): + length = {"md5": 32, "sha1": 40}.get(kind, 64) + if not re.fullmatch("[a-fA-F0-9]{%d}" % length, value): + raise ModuleError("Invalid hash.") + return value.lower() + if kind in ("ip-src", "ip-dst"): + return str(ipaddress.ip_address(value)) + if kind in ("domain", "hostname"): + value = value.rstrip(".").encode("idna").decode("ascii").lower() + if len(value) > 253 or not all( + re.fullmatch("[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?", p) for p in value.split(".") + ): + raise ModuleError("Invalid DNS name.") + if kind == "vulnerability": + value = value.upper() + if not re.fullmatch("CVE-[0-9]{4}-[0-9]{4,}", value): + raise ModuleError("A CVE identifier is required.") + return value + + +def _call(method, url, **kwargs): + try: + response = requests.request(method, url, timeout=(5, 30), verify=True, allow_redirects=False, **kwargs) + except requests.RequestException: + raise ModuleError( + "The service request failed or timed out; check the service before repeating a submission." + ) from None + if response.status_code in (204, 404) and method == "GET": + return None + if response.status_code not in (200, 201, 202): + raise ModuleError(f"The service returned HTTP {response.status_code}.") + try: + return response.json() + except ValueError: + raise ModuleError("The service returned invalid JSON.") from None + + +def _object(event, attribute, name): + obj = MISPObject(name) + obj.add_reference(attribute["uuid"], "describes") + event.add_object(obj) + return obj + + +def _annotation(event, attribute, title, data): + obj = _object(event, attribute, "annotation") + obj.comment = title + obj.add_attribute("text", value=json.dumps(data, sort_keys=True), to_ids=False, disable_correlation=True) + return obj + + +def _pivot(event, attribute, kind, value): + value = _normalise(kind, value) + if kind == attribute["type"] and value == attribute["value"]: + return + obj = _object(event, attribute, "file" if kind in ("md5", "sha1", "sha256") else "domain-ip") + relation = "ip" if kind in ("ip-src", "ip-dst") else kind + obj.add_attribute(relation, value=value, to_ids=False) + + +def _sandbox(event, attribute, payload, link=None): + obj = _object(event, attribute, "sandbox-report") + obj.add_attribute("sandbox-type", value=moduleinfo["name"], to_ids=False) + obj.add_attribute("results", value=json.dumps(payload, sort_keys=True), to_ids=False, disable_correlation=True) + if link: + obj.add_attribute("permalink", value=link, to_ids=False) + return obj + + +def _binary(attribute, config): + limit = _integer(config, "max_size_mb", 25, 100) * 1024 * 1024 + encoded = attribute.get("data") + if not isinstance(encoded, str) or len(encoded) > 2 * limit: + raise ModuleError("Missing or oversized base64 sample data.") + content = base64.b64decode(encoded, validate=True) + filename = attribute["value"].split("|", 1)[0].replace("\\", "/").rsplit("/", 1)[-1] + if attribute["type"] == "malware-sample": + with zipfile.ZipFile(io.BytesIO(content)) as archive: + entries = [entry for entry in archive.infolist() if not entry.is_dir()] + if len(entries) != 1 or entries[0].file_size > limit: + raise ModuleError("A malware-sample archive must contain one file within max_size_mb.") + content = archive.read(entries[0], pwd=b"infected") + if not filename or not content or len(content) > limit: + raise ModuleError("The sample is empty or exceeds max_size_mb.") + return (filename, content, hashlib.sha256(content).hexdigest()) + + +def handler(q=False): + if q is False: + return False + try: + request = json.loads(q) + if not isinstance(request, dict) or not isinstance(request.get("attribute"), dict): + raise ModuleError("An attribute containing type, value and uuid is required.") + attribute = request["attribute"] + UUID(attribute["uuid"]) + if attribute["type"] not in mispattributes["input"]: + raise ModuleError("Unsupported attribute type.") + value = _normalise(attribute["type"], attribute["value"]) + config = request.get("config") or {} + if not isinstance(config, dict): + raise ModuleError("The config must be an object.") + for key in REQUIRED: + if not isinstance(config.get(key), str) or not config[key].strip(): + raise ModuleError(f"Missing {key} configuration.") + limit = _integer(config, "max_results", 25) + event = MISPEvent() + event.add_attribute(**attribute) + _expand(event, attribute, value, config, limit) + result = json.loads(event.to_json()) + return {"results": {key: result.get(key, []) for key in ("Attribute", "Object")}} + except ModuleError as exc: + return {"error": str(exc)} + except ( + ValueError, + TypeError, + KeyError, + AttributeError, + IndexError, + OSError, + RuntimeError, + zipfile.BadZipFile, + PyMISPError, + ): + return {"error": "Invalid request or service response."} + + +def introspection(): + return mispattributes + + +def version(): + return dict(moduleinfo, config=moduleconfig) + + +moduleinfo = { + "version": "1.0", + "author": "MISP Project", + "name": "CAPE Sandbox Enrichment", + "description": ( + "Submit supplied samples to CAPEv2 or retrieve a completed JSON report by numeric task ID. Set api_url to the" + " API v2 base, for example https://cape.example/apiv2. api_key is optional when the server permits" + " unauthenticated requests. submit_samples defaults to false. max_size_mb defaults to 25 (1–100). Submission" + " returns task IDs; use a text attribute containing a task ID for a later report lookup. Completed reports" + " yield file hashes, network pivots and extracted configurations." + ), + "module-type": ["expansion"], + "data-source": "external", + "logo": "", + "requirements": ["requests", "pymisp"], + "features": ( + "Submit supplied samples to CAPEv2 or retrieve a completed JSON report by numeric task ID. Set api_url to the" + " API v2 base, for example https://cape.example/apiv2. api_key is optional when the server permits" + " unauthenticated requests. submit_samples defaults to false. max_size_mb defaults to 25 (1–100). Submission" + " returns task IDs; use a text attribute containing a task ID for a later report lookup. Completed reports" + " yield file hashes, network pivots and extracted configurations." + ), + "references": ["https://capev2.readthedocs.io/en/latest/usage/api.html"], + "input": "text, attachment, malware-sample", + "output": "MISP objects linked to the original attribute.", +} +mispattributes = {"input": ["text", "attachment", "malware-sample"], "format": "misp_standard"} +moduleconfig = ["api_url", "api_key", "submit_samples", "max_size_mb", "max_results"] +REQUIRED = ["api_url"] + + +def _expand(event, attribute, value, config, limit): + base = _origin(config) + headers = {"Authorization": "Token " + config["api_key"]} if config.get("api_key") else {} + if attribute["type"] in ("attachment", "malware-sample"): + if not _enabled(config, "submit_samples"): + raise ModuleError("Set submit_samples=true to submit a sample to CAPE.") + filename, content, digest = _binary(attribute, config) + data = _call("POST", base + "/tasks/create/file/", headers=headers, files={"file": (filename, content)}) + if not isinstance(data, dict) or data.get("error") or (not data.get("data", {}).get("task_ids")): + raise ModuleError("CAPE did not acknowledge a submission; check the service before retrying.") + _annotation( + event, attribute, "CAPE submission receipt", {"task_ids": data["data"]["task_ids"], "sha256": digest} + ) + return + if not re.fullmatch("[0-9]+", value): + raise ModuleError("text input must contain a numeric CAPE task ID.") + data = _call("GET", base + "/tasks/get/report/" + value + "/json/", headers=headers) + if data is None: + return + if not isinstance(data, dict) or data.get("error"): + raise ModuleError("CAPE report is unavailable or the task is not complete.") + _sandbox(event, attribute, data) + file_data = data.get("target", {}).get("file", {}) + for kind in ("md5", "sha1", "sha256"): + if file_data.get(kind): + _pivot(event, attribute, kind, file_data[kind]) + network = data.get("network", {}) + for host in network.get("hosts", [])[:limit]: + _pivot(event, attribute, "ip-dst", host["ip"] if isinstance(host, dict) else host) + for record in network.get("dns", [])[:limit]: + if record.get("request"): + _pivot(event, attribute, "domain", record["request"]) + if data.get("CAPE", {}).get("configs"): + _annotation(event, attribute, "CAPE extracted configurations", data["CAPE"]["configs"][:limit]) diff --git a/tests/test_cape_sandbox.py b/tests/test_cape_sandbox.py new file mode 100644 index 00000000..e7921c67 --- /dev/null +++ b/tests/test_cape_sandbox.py @@ -0,0 +1,121 @@ +import json +from unittest.mock import Mock, patch + +import pytest +import requests + +from misp_modules.modules.expansion import cape_sandbox as module + +UUID = "32876e4a-916d-4935-9e51-7b69a76718f8" +SECRET = "test-service-secret" + + +def query(kind=None, value="example.com", config=None, **attribute_fields): + attribute = { + "type": kind or module.mispattributes["input"][0], + "value": value, + "uuid": UUID, + "to_ids": True, + "comment": "source context", + **attribute_fields, + } + return json.dumps( + {"attribute": attribute, "config": config if config is not None else {k: SECRET for k in module.REQUIRED}} + ) + + +def reply(payload=None, status=200): + return Mock(status_code=status, headers={}, json=Mock(return_value=payload)) + + +def assert_source(result): + assert "results" in result, result + source = next(a for a in result["results"]["Attribute"] if a["uuid"] == UUID) + assert source["to_ids"] is True + assert source["comment"] == "source context" + for obj in result["results"]["Object"]: + assert any(r["referenced_uuid"] == UUID for r in obj["ObjectReference"]) + assert all(a["to_ids"] is False for a in obj["Attribute"]) + + +def objects(result, name): + return [obj for obj in result["results"]["Object"] if obj["name"] == name] + + +def values(obj, relation): + return [a["value"] for a in obj["Attribute"] if a["object_relation"] == relation] + + +def test_discovery(): + assert module.handler(False) is False + assert module.introspection()["format"] == "misp_standard" + assert module.version()["config"] == module.moduleconfig + + +@pytest.mark.parametrize("raw", ["{", "[]", "null", "{}", '{"attribute": []}']) +def test_invalid_envelope(raw): + with patch.object(module.requests, "request") as request: + assert "error" in module.handler(raw) + request.assert_not_called() + + +@pytest.mark.parametrize("status", [301, 401, 403, 429, 503]) +def test_http_errors_are_sanitized(status): + with patch.object(module.requests, "request", return_value=reply({"error": SECRET}, status)): + with pytest.raises(module.ModuleError) as failure: + module._call("GET", "https://service.example/report") + assert str(status) in str(failure.value) + assert SECRET not in str(failure.value) + + +def test_timeout_is_bounded_and_sanitized(): + with patch.object(module.requests, "request", side_effect=requests.Timeout(SECRET)) as request: + with pytest.raises(module.ModuleError) as failure: + module._call("POST", "https://service.example/submit") + assert SECRET not in str(failure.value) + assert request.call_count == 1 + assert request.call_args.kwargs["verify"] is True + assert request.call_args.kwargs["allow_redirects"] is False + assert request.call_args.kwargs["timeout"] == (5, 30) + + +@pytest.mark.parametrize("raw", [0, -1, True, "bad", 101]) +def test_invalid_result_limit(raw): + with pytest.raises(module.ModuleError): + module._integer({"max_results": raw}, "max_results", 25) + + +def test_completed_report_yields_hashes_network_and_configuration(): + data = { + "target": {"file": {"sha256": "a" * 64}}, + "network": {"hosts": [{"ip": "192.0.2.2"}], "dns": [{"request": "bad.example"}]}, + "CAPE": {"configs": [{"family": "example"}]}, + } + with patch.object(module.requests, "request", return_value=reply(data)) as request: + result = module.handler(query(kind="text", value="42", config={"api_url": "https://cape.example/apiv2"})) + assert_source(result) + assert request.call_args.args[1].endswith("/tasks/get/report/42/json/") + assert len(objects(result, "domain-ip")) == 2 + assert objects(result, "file") and objects(result, "sandbox-report") + + +def test_sample_requires_explicit_submission_and_is_sent_once(): + import base64 + + config = {"api_url": "https://cape.example/apiv2", "submit_samples": True} + with patch.object( + module.requests, "request", return_value=reply({"error": False, "data": {"task_ids": [42]}}) + ) as request: + result = module.handler( + query(kind="attachment", value="sample.bin", config=config, data=base64.b64encode(b"sample").decode()) + ) + assert_source(result) + assert request.call_count == 1 + assert request.call_args.kwargs["files"]["file"] == ("sample.bin", b"sample") + with patch.object(module.requests, "request") as request: + assert "error" in module.handler( + query( + kind="attachment", value="sample.bin", config={"api_url": "https://cape.example/apiv2"}, data="c2FtcGxl" + ) + ) + request.assert_not_called() From eaeef649a2d6f6ee503a620247858f29cbf675be Mon Sep 17 00:00:00 2001 From: Alexandre Dulaunoy Date: Thu, 29 Oct 2026 23:24:07 +0100 Subject: [PATCH 2/2] fix: [cape_sandbox] address review findings --- .../modules/expansion/cape_sandbox.py | 25 +++++++--- tests/test_cape_sandbox.py | 49 +++++++++++++++++++ 2 files changed, 67 insertions(+), 7 deletions(-) diff --git a/misp_modules/modules/expansion/cape_sandbox.py b/misp_modules/modules/expansion/cape_sandbox.py index 0a62419f..3553d074 100644 --- a/misp_modules/modules/expansion/cape_sandbox.py +++ b/misp_modules/modules/expansion/cape_sandbox.py @@ -110,16 +110,19 @@ def _annotation(event, attribute, title, data): def _pivot(event, attribute, kind, value): value = _normalise(kind, value) - if kind == attribute["type"] and value == attribute["value"]: + if kind == attribute["type"] and value == _normalise(attribute["type"], attribute["value"]): return - obj = _object(event, attribute, "file" if kind in ("md5", "sha1", "sha256") else "domain-ip") + obj = _object( + event, attribute, "file" if kind in ("md5", "sha1", "sha256") else ("url" if kind == "url" else "domain-ip") + ) relation = "ip" if kind in ("ip-src", "ip-dst") else kind obj.add_attribute(relation, value=value, to_ids=False) def _sandbox(event, attribute, payload, link=None): obj = _object(event, attribute, "sandbox-report") - obj.add_attribute("sandbox-type", value=moduleinfo["name"], to_ids=False) + obj.add_attribute("sandbox-type", value="on-premise", to_ids=False) + obj.add_attribute("on-premise-sandbox", value="cape", to_ids=False) obj.add_attribute("results", value=json.dumps(payload, sort_keys=True), to_ids=False, disable_correlation=True) if link: obj.add_attribute("permalink", value=link, to_ids=False) @@ -132,16 +135,24 @@ def _binary(attribute, config): if not isinstance(encoded, str) or len(encoded) > 2 * limit: raise ModuleError("Missing or oversized base64 sample data.") content = base64.b64decode(encoded, validate=True) - filename = attribute["value"].split("|", 1)[0].replace("\\", "/").rsplit("/", 1)[-1] + filename = attribute["value"] if attribute["type"] == "malware-sample": + filename, separator, digest = filename.rpartition("|") + if not separator or not re.fullmatch(r"[a-fA-F0-9]{32}", digest): + raise ModuleError("A malware-sample value must contain filename|md5.") with zipfile.ZipFile(io.BytesIO(content)) as archive: - entries = [entry for entry in archive.infolist() if not entry.is_dir()] + entries = [ + e for e in archive.infolist() if not e.is_dir() and e.filename != digest.lower() + ".filename.txt" + ] if len(entries) != 1 or entries[0].file_size > limit: - raise ModuleError("A malware-sample archive must contain one file within max_size_mb.") + raise ModuleError("A malware-sample archive must contain one payload within max_size_mb.") content = archive.read(entries[0], pwd=b"infected") + if hashlib.md5(content).hexdigest() != digest.lower(): + raise ModuleError("The unpacked sample does not match the declared MD5.") + filename = filename.replace("\\", "/").rsplit("/", 1)[-1] if not filename or not content or len(content) > limit: raise ModuleError("The sample is empty or exceeds max_size_mb.") - return (filename, content, hashlib.sha256(content).hexdigest()) + return filename, content, hashlib.sha256(content).hexdigest() def handler(q=False): diff --git a/tests/test_cape_sandbox.py b/tests/test_cape_sandbox.py index e7921c67..f90e449a 100644 --- a/tests/test_cape_sandbox.py +++ b/tests/test_cape_sandbox.py @@ -119,3 +119,52 @@ def test_sample_requires_explicit_submission_and_is_sent_once(): ) ) request.assert_not_called() + + +def test_current_sample_zip_metadata_digest_and_pipe_filename(): + import base64, hashlib, io, zipfile + + payload = b"actual sample" + digest = hashlib.md5(payload).hexdigest() + output = io.BytesIO() + with zipfile.ZipFile(output, "w") as archive: + archive.writestr(digest, payload) + archive.writestr(digest + ".filename.txt", "sample|name.exe") + attribute = { + "type": "malware-sample", + "value": "sample|name.exe|" + digest, + "data": base64.b64encode(output.getvalue()).decode(), + } + assert module._binary(attribute, {})[:2] == ("sample|name.exe", payload) + attribute["value"] = "sample|name.exe|" + "0" * 32 + with pytest.raises(module.ModuleError): + module._binary(attribute, {}) + assert ( + module._binary({"type": "attachment", "value": "sample|name.exe", "data": "c2FtcGxl"}, {})[0] + == "sample|name.exe" + ) + + +def test_pivots_normalize_source_and_use_the_url_template(): + from pymisp import MISPEvent + + event = MISPEvent() + attribute = {"type": "sha256", "value": "A" * 64, "uuid": UUID} + module._pivot(event, attribute, "sha256", "a" * 64) + assert not event.objects + module._pivot(event, attribute, "url", "https://example.com/path") + assert event.objects[0].name == "url" + assert event.objects[0].attributes[0].object_relation == "url" + + +def test_sandbox_classification_matches_template_contract(): + from pymisp import MISPEvent + + event = MISPEvent() + attribute = {"uuid": UUID} + obj = module._sandbox(event, attribute, {"score": 0}) + fields = {a.object_relation: a.value for a in obj.attributes} + assert fields["sandbox-type"] == "on-premise" + assert fields["on-premise-sandbox"] == "cape" + assert set(obj._definition.get("required", [])) <= set(fields) + assert set(obj._definition["requiredOneOf"]) & set(fields)