Skip to content

Generate memory dump

POST/endpoints/{endpointId}/memory-dumps

Endpoint API · Memory Dump

Instructs the target device to generate a memory dump of the specified process or the kernel. The dump is then uploaded to a customer-specified Amazon S3 bucket.

Required permissionendpoint-diagnose:create

Parameters

Name In Type Required Description
X-Tenant-ID header string (uuid) Yes Tenant ID.
endpointId path string (uuid) Yes Endpoint ID.

Request body

Content type: application/json

Request body fields

modestringrequired
Supported memory dump modes.
Must be one of: process, kernel.
pidinteger
Process ID of the process for which a memory dump is required. If mode is 'process', then either PID or image name is required. This parameter is ignored for kernel memory dumps.
Must be ≥ 0.
imageNamestring
The image name of the process for which a memory dump is required. If mode is 'process', then either PID or image name is required. This parameter is ignored for kernel memory dumps or if PID is supplied.
expiresstringrequired
Maximum duration (in ISO 8601 format) for which the action is valid. This must be no less than 5 minutes and no more than 7 days. We recommend a duration of minutes or hours only. Express the duration only in terms of days, hours, minutes, and seconds (not in weeks or milliseconds).
passwordstring
Password to use to encrypt the file to upload. Blank if the archive file is not password protected. The supported encryption is AES-256 ZIP.

Request samples

curl -X POST "https://api-<data-region>.central.sophos.com/endpoint/v1/endpoints/<endpointId>/memory-dumps" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>" -H "Content-Type: application/json" -d "{
  \"mode\": \"process\",
  \"pid\": 1234,
  \"expires\": \"PT4H\"
}"


import requests

response = requests.post(
    "https://api-<data-region>.central.sophos.com/endpoint/v1/endpoints/<endpointId>/memory-dumps",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
        "Content-Type": "application/json",
    },
    json={'mode': 'process', 'pid': 1234, 'expires': 'PT4H'},
)
print(response.json())


$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
    "Content-Type" = "application/json"
}
$body = '{
  "mode": "process",
  "pid": 1234,
  "expires": "PT4H"
}'
Invoke-RestMethod -Method POST -Uri "https://api-<data-region>.central.sophos.com/endpoint/v1/endpoints/<endpointId>/memory-dumps" -Headers $headers -Body $body -ContentType "application/json"


package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    req, err := http.NewRequest("POST", "https://api-<data-region>.central.sophos.com/endpoint/v1/endpoints/<endpointId>/memory-dumps", strings.NewReader(`{
  "mode": "process",
  "pid": 1234,
  "expires": "PT4H"
}`))
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}


const response = await fetch("https://api-<data-region>.central.sophos.com/endpoint/v1/endpoints/<endpointId>/memory-dumps", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "mode": "process",
  "pid": 1234,
  "expires": "PT4H"
}),
});
const data = await response.json();
console.log(data);

Responses

202 — Request accepted.

Response fields

idstring (uuid)required
Identifies a request to generate and collect memory dump from the endpoint.
statusstringrequired
Status of an endpoint file collection.
Must be one of: pending, finished, expired, failed.
receivedAtstring (date-time)required
Timestamp at which the action was received.
expiresAtstring (date-time)required
Timestamp from when to ignore the action on the endpoint.
errorMessagestring
Why the action failed.
memoryDumpFileobject
Details of the file uploaded by an endpoint.
Show child attributesHide child attributes
fileNamestringrequired
Name of the file.
sha256stringrequired
SHA-256 hash of the file.
sizeintegerrequired
Size of the file in bytes.

Errors

Status Meaning
400 Bad request.
404 Can't find endpoint.
500 Unexpected error.

All error responses share the same shape — see the error response object.

Response examples

202

{
  "id": "f1f1f848-e969-4df2-b41f-31544e34ef31",
  "status": "pending",
  "receivedAt": "2021-01-30T08:30:00.000Z",
  "expiresAt": "2021-02-04T08:30:00.000Z"
}

See the guide for a narrative walkthrough of this API.