HookMesh & ThreatZone Integration
You can find all of the integration process below, if there is a confusion, please send email to: [email protected]. This integration document is valid for HookMesh version>=2.1.4
DISCLAIMER
This document contains the result types that will be added to Malwation HookMesh v2.1.4, which will be in the production after 27.12.2024
Documentation
The system provides a way to run files through a specific flow (e.g., for ThreatZone Dynamic Analysis) and then retrieve the analysis results once processing is complete. The workflow is as follows:
POST File to Flow: Submit a file to a specified flow for processing.
Check Submission Status:
Poll the system until the file processing is complete, through /listen/{uuid} request.
Alternatively, send webhook through the start request and receive notifications in two main cases:
When submission finishes,
When the submission sanitization process has been finished.
Authentication
All requests to the public API endpoints require an Authorization header containing a Bearer token:
Authorization: Bearer <hookmesh api token>Replace <hookmesh api token> with your valid token.
Endpoints
Run Flow
Endpoint:
POST /public-api/runFlow/{flowId}Description: This endpoint takes in a file, processes it through the specified flow, and returns a UUID representing the submission. Use this UUID to check the status and retrieve results.
Path Parameters:
flowId(string, required): The ID or Alias of the flow.
Query Parameters (optional):
webhookUrl(string): The Webhook URL to which the system can send results automatically.Example:
https://webhook.com/myendpoint
Headers:
Authorization: Bearer <hookmesh api token>
Request (multipart/form-data):
file: The file to be analyzed/sanitized. Provide the file from your local system.
cURL Example:
curl --location 'https://<IP_OR_DOMAIN>/public-api/runFlow/{flowId}?webhook=https://webhook.com/myendpoint' \
--header 'Authorization: Bearer <hookmesh api token>' \
--form 'file=@"/path/to/yourfile.pdf"'Success Response Example:
{
"uuid": "fc10193b-eb5c-4c8c-be09-d9b325bf3cca",
"message": "Successfully ran the flow, you can check your submission by sending GET request to /listen/:uuid."
}Notes:
If the
webhookUrlis provided, the system will send a POST request with the submission results to the given URL upon completion.If it is not provided, you will need to periodically query the
/listen/{uuid}endpoint to check the submission status.
Listen for Submission Results
Endpoint:
GET /public-api/listen/{uuid}Description: Check the status of a previously submitted file. Once processing is complete, details about the sanitized file and other metadata are returned.
Path Parameters:
uuid(string, required): The UUID returned from therunFlowrequest.
Headers:
Authorization: Bearer <hookmesh api token>
cURL Example:
curl --location 'https://<IP_OR_DOMAIN>/public-api/listen/541c5d79-86b3-423f-b320-7a4bda1ed2f1' \
--header 'Authorization: Bearer <hookmesh api token>'Example Successful Response
{
"submission": {
"result": [
{
"moduleId": "677bb67dd073d63c64f18ce9",
"moduleName": "ThreatZone Dynamic Scan - LpsChain",
"startTime": "6 January 2025 11:39:52",
"endTime": "6 January 2025 11:42:36",
"moduleData": {
"link": "https://<IP_OR_DOMAIN>/public-api/download/module_result?moduleId=677bb67dd073d63c64f18ce9&uuid=faa9c2f8-7e66-4496-89b3-3b2ff9e921ee"
},
"links": []
}
],
"uuid": "faa9c2f8-7e66-4496-89b3-3b2ff9e921ee",
"filename": "winrar-x64-701tr.exe",
"fileSize": 3992072,
"source": "<IP_OR_EMAIL_ADDRESS>",
"status": {
"statusID": 3,
"statusString": "Completed"
},
"level": "Malicious",
"sanitized": false,
"flow": {},
"submissionDate": "6 January 2025 11:39:52",
"startDate": "6 January 2025 11:39:52",
"endDate": "6 January 2025 11:42:37",
"createdAt": "6 January 2025 11:39:52",
"updatedAt": "6 January 2025 11:42:37",
"hashes": {
"md5": "0cbdfaacd5fefb4acb67efb8253e5e3f",
"sha1": "da7175d0d2a49e3e86a85538f18799c7cf17e486",
"sha256": "7821f9d85301d59f8d4354fa4d8f203d53300579f1314bd2f0ef09fc18d69ae6"
}
}
}
Response Details
submission.status.statusIDindicates the current status of processing:1or2: Processing or pending.3: Completed (File has been analyzed and sanitized).
submission.hashesincludes hash values (MD5, SHA1, SHA256) for the submitted file.submission.levelindicates the risk or maliciousness level of the file if available.Not Measured
Informative
Suspicious
Malicious
Download ThreatZone Analysis Report
Endpoint:
GET /public-api/download/module_file?id={moduleId}&uuid={uuid}PS: Since this link will be provided in both Webhook & Listen Request you don't need to build this URL in your own, just use the URL provided to you in sanitizationInfo.downloadLink .
Query Parameters:
id(string, required): The module ID retrieved from the listen response.uuid(string, required): The UUID retrieved from the original submission.
Headers:
Authorization: Bearer <hookmesh api token>
cURL Example:
curl --location 'https://<IP_OR_DOMAIN>/public-api/download/module_file?id=676188c5efb6046f975337a7&uuid=541c5d79-86b3-423f-b320-7a4bda1ed2f1' \
--header 'Authorization: Bearer <hookmesh api token>' \{
"reportUrl": "https://app.threat.zone//submission/b7a16a66-f902-43eb-a8a9-f34683826176",
"_id": "677bc10ab52ffa95321f4b8a",
"uuid": "b7a16a66-f902-43eb-a8a9-f34683826176",
"private": false,
"environment": "w7_x64",
"level": 3,
"fileInfo": {
"name": "winrar-x64-701tr.exe",
"entrypoint": "winrar-x64-701tr.exe",
"extension": "exe",
"realExtension": "exe",
"size": 3992072,
"hashes": {
"md5": "0cbdfaacd5fefb4acb67efb8253e5e3f",
"sha1": "da7175d0d2a49e3e86a85538f18799c7cf17e486",
"sha256": "7821f9d85301d59f8d4354fa4d8f203d53300579f1314bd2f0ef09fc18d69ae6",
"_id": "677bc10ab52ffa95321f4b8c"
},
"source": "upload",
"_id": "677bc10ab52ffa95321f4b8b"
},
"reports": {
"dynamic": {
"enabled": true,
"level": 3,
"status": 5,
"metafields": {
"environment": "w7_x64",
"raw_logs": false,
"private": false,
"internet_connection": false,
"work_path": "desktop",
"snapshot": false,
"https_inspection": false,
"timeout": 60,
"mouse_simulation": true,
"sleep_evasion": false,
"smart_tracing": true,
"dump_collector": false,
"open_in_browser": true
},
"_id": "677bc10ab52ffa95321f4b8e",
"additionalFiles": [
{
"id": "92e7e6e3-dbd9-4f0e-835e-7ca7e90b6011",
"path": "b7a16a66-f902-43eb-a8a9-f34683826176/dynamic/additionalFiles/rawnetwork.pcap",
"name": "rawnetwork.pcap",
"_id": "677bc1a79c1218355d72200f"
}
],
"media": [
{
"id": "2418b735-8226-4a31-8600-630eeb7d3184",
"path": "b7a16a66-f902-43eb-a8a9-f34683826176/dynamic/overview/media/video.mp4",
"_id": "677bc1a79c1218355d72200e"
}
],
"indicators": [
{
"author": "Malwation",
"name": "Debugger check",
"description": "Target checks debugger present PIDs:[1900]",
"score": 5,
"level": "Suspicious",
"category": "Debugger",
"events": [
579,
578,
1494,
1493,
1492,
1491
],
"attackCodes": [
"T1622"
],
"_id": "677bc1a79c1218355d721ff7"
}
],
"advancedNetworkAnalysisURL": "https://network.threat.zone/webshark/#b7a16a66-f902-43eb-a8a9-f34683826176.pcap",
"behaviours": [
{
"analysis": "basic",
"pid": 1900,
"process_name": "winrar-x64-701tr.exe",
"eventid": 559,
"eventcount": 2,
"operation": "create",
"handle": "0x1cebf8",
"mutex": "0x0",
"type": "mutex"
}
]
},
"cdr": {
"enabled": false,
"sanitized": [],
"removed": [],
"_id": "677bc10ab52ffa95321f4b90"
},
"_id": "677bc10ab52ffa95321f4b8d",
"static": {
"enabled": true,
"level": 2,
"score": 6,
"status": 5,
"analysis_time": "6.19201 seconds",
"characteristics": {
"file_characteristics": {
"characteristics": "0x22",
"readable_characteristics": [
"IMAGE_FILE_EXECUTABLE_IMAGE",
"IMAGE_FILE_LARGE_ADDRESS_AWARE"
],
"_id": "677bc114b7d5710e7acef5f4"
},
"dll_characteristics": {
"characteristics": "0xc160",
"readable_characteristics": [
"IMAGE_DLLCHARACTERISTICS_HIGH_ENTROPY_VA",
"IMAGE_DLLCHARACTERISTICS_DYNAMIC_BASE",
"IMAGE_DLLCHARACTERISTICS_NX_COMPAT",
"IMAGE_DLLCHARACTERISTICS_GUARD_CF",
"IMAGE_DLLCHARACTERISTICS_TERMINAL_SERVER_AWARE"
],
"_id": "677bc114b7d5710e7acef5f5"
},
"_id": "677bc114b7d5710e7acef5f3"
},
"config": [],
"debug_info": [
{
"time_date_stamp": "May 12 2024 10:17:26",
"major_version": 0,
"minor_version": 0,
"size": 87,
"address_of_rawdata": 326376,
"pointer_to_rawdata": 319720,
"type": "IMAGE_DEBUG_TYPE_CODEVIEW",
"pdb_file_name": "D:\\Projects\\WinRAR\\sfx\\setup\\build\\sfxrar64\\Release\\sfxrar.pdb",
"_id": "677bc114b7d5710e7acef5cf"
}
],
"die_result": [
{
"name": "Windows",
"string": "Operation system: Windows(Vista)[AMD64, 64-bit, GUI]",
"type": "operation_system",
"version": "Vista",
"_id": "677bc114b7d5710e7acef5fe"
}
],
"exports": [],
"file_header": {
"machine": "IMAGE_FILE_MACHINE_AMD64",
"image_base": "0x140000000",
"entrypoint_name": ".text",
"number_of_sections": 8,
"time_date_stamp": "May 12 2024 10:17:26",
"pointer_to_symbol_table": 0,
"number_of_symbols": 0,
"size_of_optional_header": "240 bytes",
"compiler_flags": {
"is_aslr": true,
"is_nxcompat": true,
"is_seh": false,
"is_cfg": true,
"is_gs": true,
"_id": "677bc114b7d5710e7acef5f7"
},
"_id": "677bc114b7d5710e7acef5f6"
},
"file_info": {
"realFilename": null,
"realSha256": null,
"filesize": "3.81 MB",
"md5": "0cbdfaacd5fefb4acb67efb8253e5e3f",
"sha1": "da7175d0d2a49e3e86a85538f18799c7cf17e486",
"sha256": "7821f9d85301d59f8d4354fa4d8f203d53300579f1314bd2f0ef09fc18d69ae6",
"ssdeep": "98304:aNRBOBfKOmopDmbQgr/t+F5V6woCAQYcr4LMRFt/hJf3NF2:MR/OmWDeMF5sCPv4LMF3NQ",
"mime_type": "application/x-dosexec",
"file_type": "PE32+ executable (GUI) x86-64, for MS Windows",
"entropy": 7.95,
"_id": "677bc114b7d5710e7acef6a4"
},
"imports": {
"entries": [
{
"address": "0x140044000",
"name": "GetLastError",
"blacklist": false,
"filename": "kernel32.dll",
"_id": "677bc114b7d5710e7acef602"
}
],
"files": [
"kernel32.dll",
"oleaut32.dll",
"gdiplus.dll"
]
},
"ioc": {
"ip": [],
"url": [
"http://crl3.digicert.com/DigiCertTrustedG4RSA4096SHA256TimeStampingCA.crl0",
],
"domain": [
"crl3.digicert.com",
],
"email": [],
"irc": [],
"http_requests": [],
"ssdp_requests": [],
"possible_payload": [],
"_id": "677bc114b7d5710e7acef6a2"
},
"matched_yara_rules": {
"malware": [],
"suspicious": [
"WMI_strings",
"win_token"
],
"info": [
"anti_dbg",
"INFO_DelayedImport_ADVAPI32_Registry",
"CRC32b_poly_Constant",
"RIPEMD160_Constants",
"SHA1_Constants",
"SHA2_BLAKE2_IVs",
"RijnDael_AES_CHAR",
"WmiQuery",
"IsPacked",
"HasOverlay",
"msvc_general_x64",
"SelfExtractingRAR"
],
"_id": "677bc114b7d5710e7acef6a3"
},
"report_info": {
"checksum": true,
"has_overlay": true,
"overlay_entropy": 8,
"imphash": "39da3cace27ab9503fa46001ce968ea6",
"packed": true,
"packer": null
},
"resources": [
{
"rtype": "PNG",
"name": null,
"id": "1384",
"size": "12.77 KB",
"offset": "0x0006c5cc",
"resource_magic": "PNG image data, 256 x 64, 8-bit/color RGBA, non-interlaced",
"lang": "LANG_ENGLISH",
"sublang": "SUBLANG_ENGLISH_US",
"sha256": "053c14d6c38ddb7a95e79794802b26a11548569be8246efaf42b571ec42f608c",
"entropy": 7.97,
"_id": "677bc114b7d5710e7acef5d2"
}
],
"rich_header": {
"rich_header_hash": "262f20b5a927c31626237bbcbea152eb103c9afcbd9818ca25ff313bde198077",
"checksum": "0xb375c2ca",
"comp_information": [
{
"comp_id": 65536,
"resource_count": 291,
"linker": "[---] Unmarked objects",
"_id": "677bc114b7d5710e7acef5f9"
}
],
"key": "ysJ1sw==",
"raw_data": "jqMb4MrCdbPKwnWzysJ1s4G6drLCwnWzgbpwslDCdbNKuYizyMJ1s0q5cbLYwnWzSrl2ssDCdbNKuXCy8cJ1s4G6cbLewnWzgbpzssvCdbOBunSyzcJ1s8rCdLPpw3WzRLl8svjCdbNEuXWyy8J1s0S5irPLwnWzRLl3ssvCdbM=",
"clear_data": "RGFuUwAAAAAAAAAAAAAAAEt4AwEIAAAAS3gFAZoAAACAe/0AAgAAAIB7BAESAAAAgHsDAQoAAACAewUBOwAAAEt4BAEUAAAAS3gGAQEAAABLeAEBBwAAAAAAAQAjAQAAjnsJATIAAACOewABAQAAAI57/wABAAAAjnsCAQEAAAA=",
"_id": "677bc114b7d5710e7acef5f8"
},
"scanType": "EXE",
"sections": [
{
"name": ".text",
"virtual_address": "0x1000",
"virtual_size": "0x4217e",
"raw_size": "0x42200",
"entropy": 6.47,
"md5": "3b541339cc9e14f15b888d0479b3133f",
"characteristics": "0x60000020",
"readable_characteristics": [
"IMAGE_SCN_CNT_CODE",
"IMAGE_SCN_MEM_EXECUTE",
"IMAGE_SCN_MEM_READ"
],
"_id": "677bc114b7d5710e7acef5eb"
}
]
}
},
"tags": [
{
"type": "scan",
"value": "dynamic",
"_id": "677bc10ab52ffa95321f4b91"
},
{
"type": "scan",
"value": "static",
"_id": "677bc10ab52ffa95321f4b92"
},
{
"type": "module",
"value": "csi",
"_id": "677bc10ab52ffa95321f4b93"
},
{
"type": "family",
"value": "Win.Trojan.Generic-9947715-0",
"_id": "677bc1a79c1218355d721f20"
}
],
"modules": []
}Using Webhooks
Instead of polling the /listen/{uuid} endpoint, you can provide a webhookUrl as a query parameter during your initial POST /runFlow/{flowId} request. When the submission completes, the system will automatically send a POST request to the given webhookUrl with the submission’s final JSON structure.
How Webhooks Work
You start the flow by sending a POST request with
?webhookUrl=<YOUR_WEBHOOK_ENDPOINT>.Once the file is processed, the system sends an HTTP POST request to your specified URL containing the same JSON structure you would normally retrieve from the
GET /listen/{uuid}endpoint.On receiving this callback, you can parse the JSON, check the
statusID, and then directly download the sanitized file if needed.
Example Webhook Payload
// same as listen request's response, but here is the example
{
"submission": {
"result": [
{
"moduleId": "677bb67dd073d63c64f18ce9",
"moduleName": "ThreatZone Dynamic Scan - LpsChain",
"startTime": "6 January 2025 11:39:52",
"endTime": "6 January 2025 11:42:36",
"moduleData": {
"link": "https://<IP_OR_DOMAIN>/public-api/download/module_result?moduleId=677bb67dd073d63c64f18ce9&uuid=faa9c2f8-7e66-4496-89b3-3b2ff9e921ee"
},
"links": []
}
],
"uuid": "faa9c2f8-7e66-4496-89b3-3b2ff9e921ee",
"filename": "winrar-x64-701tr.exe",
"fileSize": 3992072,
"source": "<IP_OR_EMAIL_ADDRESS>",
"status": {
"statusID": 3,
"statusString": "Completed"
},
"level": "Malicious",
"sanitized": false,
"flow": {},
"submissionDate": "6 January 2025 11:39:52",
"startDate": "6 January 2025 11:39:52",
"endDate": "6 January 2025 11:42:37",
"createdAt": "6 January 2025 11:39:52",
"updatedAt": "6 January 2025 11:42:37",
"hashes": {
"md5": "0cbdfaacd5fefb4acb67efb8253e5e3f",
"sha1": "da7175d0d2a49e3e86a85538f18799c7cf17e486",
"sha256": "7821f9d85301d59f8d4354fa4d8f203d53300579f1314bd2f0ef09fc18d69ae6"
}
}
}Implementing the Webhook:
Set up an endpoint on your server (e.g.,
https://example.com/my-webhook).Include the URL as a query parameter when calling
runFlow:curl --location 'https://<IP_OR_DOMAIN>/public-api/runFlow/{flowId}?webhookUrl=https://example.com/my-webhook' \ --header 'Authorization: Bearer <hookmesh api token>' \ --form 'file=@"/path/to/yourfile.pdf"'Your endpoint must accept POST requests and should be prepared to handle the JSON payload.
Once you receive the callback from the system, you can parse the data and proceed with further actions such as downloading the sanitized file.
Troubleshooting
401 Unauthorized: Ensure your
Authorizationheader and token are correct.404 Not Found: Check if you used the correct
uuidormoduleId.Timeouts: The sanitization process can take time. If no webhook is used, continue polling until completion.
If you checked this document and still the issue persists, send email to [email protected]
Last updated