search

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

hashtag
DISCLAIMER

triangle-exclamation

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

hashtag
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:

  1. POST File to Flow: Submit a file to a specified flow for processing.

  2. Check Submission Status:

    1. Poll the system until the file processing is complete, through /listen/{uuid} request.

    2. Alternatively, send webhook through the start request and receive notifications in two main cases:

      1. When submission finishes,

      2. When the submission sanitization process has been finished.

hashtag
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.

hashtag
Endpoints

hashtag
Run Flow

Endpoint:

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:

Success Response Example:

Notes:

  • If the webhookUrl is 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.

hashtag
Listen for Submission Results

Endpoint:

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 the runFlow request.

Headers:

  • Authorization: Bearer <hookmesh api token>

cURL Example:

Example Successful Response

Response Details

  • submission.status.statusID indicates the current status of processing:

    • 1 or 2: Processing or pending.

    • 3: Completed (File has been analyzed and sanitized).

  • submission.hashes includes hash values (MD5, SHA1, SHA256) for the submitted file.

  • submission.level indicates the risk or maliciousness level of the file if available.

    • Not Measured

    • Informative

    • Suspicious

    • Malicious

hashtag
Download ThreatZone Analysis Report

Endpoint:

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:

hashtag
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.

hashtag
How Webhooks Work

  1. You start the flow by sending a POST request with ?webhookUrl=<YOUR_WEBHOOK_ENDPOINT>.

  2. 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.

  3. On receiving this callback, you can parse the JSON, check the statusID, and then directly download the sanitized file if needed.

hashtag
Example Webhook Payload

hashtag
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:

  • 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.

hashtag
Troubleshooting

  • 401 Unauthorized: Ensure your Authorization header and token are correct.

  • 404 Not Found: Check if you used the correct uuid or moduleId.

  • 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]

PreviousIntroductionNextHookMesh & CDR Integration

Last updated