HookMesh & CDR 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 CDR sanitization) 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.

  3. Download Sanitized File: Once the processing is done, download the sanitized file if available(CDR has been successfully ran).

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

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

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": "6731ed402266ca5d56e95a7f",
        "moduleName": "CDR",
        "startTime": "17 December 2024 14:20:49",
        "endTime": "17 December 2024 14:20:53",
        "moduleData": {
          "link": "https://<IP_OR_DOMAIN>/public-api/download/module_result?moduleId=6731ed402266ca5d56e95a7f&uuid=541c5d79-86b3-423f-b320-7a4bda1ed2f1"
        },
        "links": [
          {
            "link": "https://<IP_OR_DOMAIN>/public-api/download/module_file?id=676188c5efb6046f975337a7&uuid=541c5d79-86b3-423f-b320-7a4bda1ed2f1",
            "linkName": "HookMesh_Docs_sanitized.pdf"
          }
        ]
      }
    ],
    "sanitizationInfo": {
      "enabled": true,
      "startDate": "17 December 2024 14:20:49",
      "finished": true,
      "finishDate": "17 December 2024 14:20:53",
      "success": true,
      "downloadLink": "https://<IP_OR_DOMAIN>/public-api/download/module_file?id=676188c5efb6046f975337a7&uuid=541c5d79-86b3-423f-b320-7a4bda1ed2f1",
      "changed": true
    },
    "uuid": "541c5d79-86b3-423f-b320-7a4bda1ed2f1",
    "filename": "HookMesh_Docs.pdf",
    "fileSize": 63970,
    "source": "<IP_OR_DOMAIN>",
    "status": {
      "statusID": 3,
      "statusString": "Completed"
    },
    "level": "Not Measured",
    "sanitized": true,
    "submissionDate": "17 December 2024 14:20:49",
    "startDate": "17 December 2024 14:20:49",
    "endDate": "17 December 2024 14:20:53",
    "createdAt": "17 December 2024 14:20:49",
    "updatedAt": "17 December 2024 14:20:53",
    "hashes": {
      "md5": "e74f9fdc64e4890e23fca50f3bbf9e4b",
      "sha1": "b0a6a46a985c6abf5b570cadb68978a7511585e6",
      "sha256": "c2ae040166d35ddc5546129b0b9e9ea70d8ea1504639d891b030f40ee5365ca7"
    }
  }
}

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

Sanitization Info Details

  • enabled : Indicates that sanitization was enabled for this submission.

  • startDate : The date and time when the sanitization process started.

  • finished : Shows that the sanitization process has completed.

  • finishDate : The date and time when the sanitization process finished.

  • success : Indicates that the sanitization completed successfully without errors.

  • downloadLink : A direct link to download the sanitized file.

  • changed : Shows that the sanitization process modified the file (e.g., removed risky elements).

Download Sanitized File

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>' \
--output sanitized_file.pdf

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

  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.

Example Webhook Payload

// same as listen request's response, but here is the example
{
    "result": [
      {
        "moduleId": "6731ed402266ca5d56e95a7f",
        "moduleName": "CDR",
        "startTime": "17 December 2024 14:20:49",
        "endTime": "17 December 2024 14:20:53",
        "moduleData": {
          "link": "https://<IP_OR_DOMAIN>/public-api/download/module_result?moduleId=6731ed402266ca5d56e95a7f&uuid=541c5d79-86b3-423f-b320-7a4bda1ed2f1"
        },
        "links": [
          {
            "link": "https://<IP_OR_DOMAIN>/public-api/download/module_file?id=676188c5efb6046f975337a7&uuid=541c5d79-86b3-423f-b320-7a4bda1ed2f1",
            "linkName": "HookMesh_Docs_sanitized.pdf"
          }
        ]
      }
    ],
    "sanitizationInfo": {
      "enabled": true,
      "startDate": "17 December 2024 14:20:49",
      "finished": true,
      "finishDate": "17 December 2024 14:20:53",
      "success": true,
      "downloadLink": "https://<IP_OR_DOMAIN>/public-api/download/module_file?id=676188c5efb6046f975337a7&uuid=541c5d79-86b3-423f-b320-7a4bda1ed2f1",
      "changed": true
    },
    "uuid": "541c5d79-86b3-423f-b320-7a4bda1ed2f1",
    "filename": "HookMesh_Docs.pdf",
    "fileSize": 63970,
    "source": "<IP_OR_DOMAIN>",
    "status": {
      "statusID": 3,
      "statusString": "Completed"
    },
    "level": "Not Measured",
    "sanitized": true,
    "submissionDate": "17 December 2024 14:20:49",
    "startDate": "17 December 2024 14:20:49",
    "endDate": "17 December 2024 14:20:53",
    "createdAt": "17 December 2024 14:20:49",
    "updatedAt": "17 December 2024 14:20:53",
    "hashes": {
      "md5": "e74f9fdc64e4890e23fca50f3bbf9e4b",
      "sha1": "b0a6a46a985c6abf5b570cadb68978a7511585e6",
      "sha256": "c2ae040166d35ddc5546129b0b9e9ea70d8ea1504639d891b030f40ee5365ca7"
    }
}

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

PreviousHookMesh & ThreatZone IntegrationNextHookMesh & CDR Integration Document Legacy Version(s)

Last updated