Collect forensic log¶

POST/endpoints/{endpointId}/forensic-logs

Sends a request to the endpoint to collect forensic log.

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 forensic log collection modes. * fast - Collects a reduced set of diagnostic files. * full - Collects the full set of diagnostic files. * standard - The default mode. * none - Only collects the additional files specified in the request. This is intended for use when normal data has already been collected and some additional files are required.
Must be one of: fast, full, standard, none.

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.

pathsarray of string

List of additional file paths to include.
Must contain at most 50 items.

Request samples¶

cURLPythonPowerShellGoJavaScript

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

import requests

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

$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
    "Content-Type" = "application/json"
}
$body = '{
  "mode": "fast",
  "expires": "PT4H"
}'
Invoke-RestMethod -Method POST -Uri "https://api-<data-region>.central.sophos.com/endpoint/v1/endpoints/<endpointId>/forensic-logs" -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>/forensic-logs", strings.NewReader(`{
  "mode": "fast",
  "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>/forensic-logs", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "mode": "fast",
  "expires": "PT4H"
}),
});
const data = await response.json();
console.log(data);

Responses¶

`202` — Request accepted.¶

Response fields

idstring (uuid)required

Identifies a request to collect forensic log 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.

forensicLogFileobject

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.