Sophos Central

the sophos central connector enables streamlined security management and automation by interfacing with sophos' suite of security products sophos central is a unified console for managing sophos products, offering a comprehensive security solution the sophos central turbine connector allows users to automate critical security tasks such as managing allowlists and blocklists, executing alert actions, and isolating endpoints by integrating with sophos central, swimlane turbine users can streamline threat response, enhance endpoint security, and leverage sophos' advanced threat intelligence within their automated workflows sophos central's public api program makes it easy for you to automate your monitoring, security and administration activities in sophos central this connector integrates sophos central's rest api with swimlane turbine to analyze urls, ips, and files for threats prerequisites to effectively utilize the sophos central connector with swimlane turbine, ensure you have the following prerequisites oauth 2 0 client credentials authentication with the following parameters url the base url for the sophos central api client id your sophos central application client identifier client secret the secret key associated with your sophos central application asset setup to obtain the required asset paramaters url, client id, client secret click here https //developer sophos com/getting started tenant capabilities this connector currently supports the following capabilities common api execute alert action list alert actions endpoint api add entities to allowlist add entities to blocklist get isolation by endpoint get endpoints isolate or unisolate endpoints scan endpoints siem integration api get siem alerts get siem events task setup the following tasks inputs there are different ways to pass parameters get endpoints for lastseenbefore and lastseenafter parameters you can pass two values date and time (utc) ex 2019 09 23t12 02 01 700z duration relative to the current date and time ex pt1d4h500s (ptndnhns) and negative indicates time ago configurations sophos central oauth 2 0 client credentials authenticates using oauth 2 0 client credentials configuration parameters parameter description type required url a url to the target dataregion string required x tenant id x tenant id string optional token url string optional x tenant id url a url to get the x tenant id, if x tenant id not provided string optional client id the client id string required client secret the client secret string required scope permission scopes for this action array optional verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional actions add entities to allowlist exempt items from conviction by adding them to the sophos central allowlist with specified type, properties, and an optional comment endpoint url /endpoint/v1/settings/allowed items method post input argument name type required description type string required property by which an item is allowed properties object required allowed item properties filename string optional file name path string optional path for the application sha256 string optional sha256 value for the application certificatesigner string optional value saved for the certificatesigner comment string required comment indicating why the item should be allowed originpersonid string optional person associated with the endpoint where the item to be allowed was last seen originendpointid string optional endpoint where the item to be allowed was last seen output parameter type description status code number http status code of the response reason string response reason phrase id string unique identifier createdat string output field createdat updatedat string output field updatedat properties object output field properties filename string name of the resource path string output field path sha256 string output field sha256 certificatesigner string output field certificatesigner comment string output field comment type string type of the resource createdby object output field createdby id string unique identifier name string name of the resource originperson object output field originperson id string unique identifier name string name of the resource originendpoint object output field originendpoint id string unique identifier example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "id" "123e4567 e89b 12d3 a456 426614174000", "createdat" "2024 06 24t15 00 00z", "updatedat" "2024 06 24t15 30 00z", "properties" {}, "comment" "allowed for testing purposes ", "type" "sha256", "createdby" {}, "originperson" {}, "originendpoint" {} } } ] add entities to blocklist blocks an entity in sophos central by specifying type, properties, and a comment requires 'type', 'properties', and 'comment' in json body input endpoint url /endpoint/v1/settings/blocked items method post input argument name type required description type string required property by which an item is blocked properties object required blocked item properties filename string optional file name path string optional path for the application sha256 string optional sha256 value for the application certificatesigner string optional value saved for the certificatesigner comment string required comment indicating why the item should be blocked output parameter type description status code number http status code of the response reason string response reason phrase id string unique identifier createdat string output field createdat updatedat string output field updatedat properties object output field properties filename string name of the resource path string output field path sha256 string output field sha256 certificatesigner string output field certificatesigner comment string output field comment type string type of the resource createdby object output field createdby id string unique identifier name string name of the resource originperson object output field originperson id string unique identifier name string name of the resource originendpoint object output field originendpoint id string unique identifier example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "id" "456e7890 f321 4dc5 ba87 654edcba0987", "createdat" "2024 06 25t10 00 00z", "updatedat" "2024 06 25t10 15 00z", "properties" {}, "comment" "detected as malicious by antivirus engine ", "type" "sha256", "createdby" {}, "originperson" {}, "originendpoint" {} } } ] execute alert action executes a specified action on an identified alert in sophos central using the alertid and action details provided endpoint url /common/v1/alerts/{{alertid}}/actions method post input argument name type required description alertid string required alert id action string required actions that you can perform on these alerts message string optional message to send for the action output parameter type description status code number http status code of the response reason string response reason phrase id string unique identifier alertid string unique identifier action string output field action status string status value requestedat string output field requestedat startedat string output field startedat completedat string output field completedat result string result of the operation example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "id" "2f2d0c43 5687 4cf6 ba15 dd1c1173e673", "alertid" "f9415c5f e0e9 41d7 8126 1956223a66f1", "action" "cleanpua", "status" "started", "requestedat" "2021 02 12t14 35 20 248", "startedat" "2021 02 12t14 37 01 922", "completedat" "2021 02 12t14 37 01 922", "result" "xyz" } } ] get endpoints retrieves a comprehensive list of all endpoints associated with the specified tenant in sophos central endpoint url /endpoint/v1/endpoints method get input argument name type required description pagefromkey string optional the key of the item from where to fetch a page pagesize number optional the size of the page requested pagetotal boolean optional whether the number of pages should be calculated and returned in the response sort array optional defines how to sort the data healthstatus array optional find endpoints by health status type array optional find endpoints by type tamperprotectionenabled boolean optional find endpoints by whether tamper protection is turned on lockdownstatus array optional find endpoints by lockdown status lastseenbefore string optional find endpoints that were last seen before the given date and time (utc) or a duration relative to the current date and time (exclusive), or you can provide 3 days 4 hours 5 minutes and 0 seconds ago, value is case sensitive( p3dt4h5m0s) lastseenafter string optional find endpoints that were last seen after the given date and time (utc) or a duration relative to the current date and time (inclusive), or you can provide 3 days 4 hours 5 minutes and 0 seconds ago, value is case sensitive( p3dt4h5m0s) ids array optional find endpoints with the specified ids isolationstatus string optional find endpoints by isolation status hostnamecontains string optional find endpoints where the hostname contains the given string only the first 10 characters of the given string are matched associatedpersoncontains string optional find endpoints where the name of the person associated with the endpoint contains the given string groupnamecontains string optional find endpoints where the name of the group the endpoint is in contains the given string search string optional term to search for in the specified search fields searchfields array optional list of search fields for finding the given search term defaults to all applicable fields by default it takes all five values in an array ipaddresses array optional find endpoints by ip addresses cloud array optional find endpoints that are cloud instances fields array optional the fields to return in a partial response view string optional type of view to be returned in response assignedtogroup boolean optional whether endpoint is assigned to a group groupids array optional match endpoints by assigned group macaddresses array optional find endpoints by mac addresses must contain at most 50 items must be unique output parameter type description status code number http status code of the response reason string response reason phrase items array output field items id string unique identifier type string type of the resource tenant object output field tenant id string unique identifier hostname string name of the resource health object output field health overall string output field overall threats object output field threats status string status value services object output field services status string status value servicedetails array output field servicedetails name string name of the resource status string status value os object output field os isserver boolean output field isserver platform string output field platform name string name of the resource majorversion number output field majorversion minorversion number output field minorversion build number output field build ipv4addresses array output field ipv4addresses example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "items" \[], "pages" {} } } ] get isolation by endpoint retrieve isolation settings for a specified endpoint in sophos central using the unique endpointid endpoint url /endpoint/v1/endpoints/{{endpointid}}/isolation method get input argument name type required description endpointid string required endpoint id output parameter type description status code number http status code of the response reason string response reason phrase enabled boolean output field enabled lastenabledat string output field lastenabledat lastenabledby object output field lastenabledby id string unique identifier type string type of the resource name string name of the resource accounttype string type of the resource accountid string unique identifier lastdisabledat string output field lastdisabledat lastdisabledby object output field lastdisabledby id string unique identifier type string type of the resource name string name of the resource accounttype string type of the resource accountid string unique identifier comment string output field comment example \[ { "status code" 200, "response headers" { "date" "tue, 25 jun 2024 08 37 17 gmt", "content type" "application/json", "transfer encoding" "chunked", "connection" "keep alive", "x correlation id" "ff459065 adfe 4deb 8d75 8df4d1629e7f", "x request id" "49f7d5e4 c3b0 4314 a965 a3338b232b09" }, "reason" "", "json body" { "enabled" true, "lastenabledat" "2024 06 25t15 30 00z", "lastenabledby" {}, "lastdisabledat" "2024 06 24t12 00 00z", "lastdisabledby" {}, "comment" "endpoint isolated due to security incident " } } ] get siem alerts fetches the latest sophos central siem alerts, including timestamps, from the past 24 hours endpoint url /siem/v1/alerts method get input argument name type required description limit number optional the maximum number of items to return from date number optional the starting date from which alerts will be retrieved defined as unix timestamp in utc ignored if cursor is set must be within last 24 hours cursor string optional identifier for next item in the list, this value is available in response as next cursor output parameter type description status code number http status code of the response reason string response reason phrase has more boolean output field has more items array output field items created at string output field created at customer id string unique identifier data object response data description string output field description event service event id string unique identifier id string unique identifier info object output field info location string output field location severity string output field severity source string output field source threat string output field threat threat cleanable boolean output field threat cleanable type string type of the resource when string output field when next cursor string output field next cursor example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "has more" false, "items" \[], "next cursor" "abcdef123456" } } ] get siem events retrieve sophos central events with timestamps from the last 24 hours for siem integration endpoint url /siem/v1/events method get input argument name type required description prameters object optional parameter for get siem events limit number optional the maximum number of items to return cursor string optional identifier for next item in the list, this value is available in response as next cursor from date number optional the starting date from which alerts will be retrieved defined as unix timestamp in utc ignored if cursor is set exclude types string optional the string of list of types of events to be excluded output parameter type description status code number http status code of the response reason string response reason phrase has more boolean output field has more items array output field items amsi threat data object response data parentprocessid string unique identifier parentprocesspath string output field parentprocesspath processid string unique identifier processname string name of the resource processpath string output field processpath appcerts array output field appcerts signer string output field signer thumbprint string output field thumbprint appsha256 string output field appsha256 core remedy items object output field core remedy items items array output field items descriptor string output field descriptor result string result of the operation type string type of the resource totalitems number output field totalitems created at string output field created at customer id string unique identifier details array output field details property string output field property type string type of the resource example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "has more" true, "items" \[], "next cursor" "next cursor example" } } ] isolate or unisolate endpoints enables or disables isolation for multiple endpoints in sophos central, with a recommended time gap between state changes endpoint url /endpoint/v1/endpoints/isolation method post input argument name type required description enabled boolean required whether the endpoints should be isolated or not comment string optional reason the endpoints should be isolated or not length is lessthan 400 ids array required list of endpoints ids max contain is 50 output parameter type description status code number http status code of the response reason string response reason phrase id string unique identifier isolation object output field isolation enabled boolean output field enabled lastenabledat string output field lastenabledat lastenabledby object output field lastenabledby id string unique identifier type string type of the resource name string name of the resource accounttype string type of the resource accountid string unique identifier lastdisabledat string output field lastdisabledat lastdisabledby object output field lastdisabledby id string unique identifier type string type of the resource name string name of the resource accounttype string type of the resource accountid string unique identifier comment string output field comment example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "id" "123e4567 e89b 12d3 a456 426614174000", "isolation" {} } } ] list alert actions retrieve a list of actions taken on a specific alert in sophos central using the alertid endpoint url /common/v1/alerts/{{alertid}} method get input argument name type required description alertid string required alert id output parameter type description status code number http status code of the response reason string response reason phrase id string unique identifier allowedactions array output field allowedactions category string output field category description string output field description groupkey string output field groupkey managedagent object output field managedagent id string unique identifier type string type of the resource person object output field person id string unique identifier product string output field product raisedat string output field raisedat severity string output field severity tenant object output field tenant id string unique identifier name string name of the resource type string type of the resource example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "id" "a5ded91c 6575 435c a6b4 64b94f9048ff", "allowedactions" \[], "category" "updating", "description" "john pc is out of date ", "groupkey" "msxfdmvuddo6rw5kcg9pbnq6ok91de9mrgf0zsw1mtms", "managedagent" {}, "person" {}, "product" "endpoint", "raisedat" "2021 02 12t15 04 53 780z", "severity" "medium", "tenant" {}, "type" "event endpoint outofdate" } } ] scan endpoints initiates or configures a scan on a specified endpoint using its endpointid in sophos central endpoint url /endpoint/v1/endpoints/{{endpointid}}/scans method post input argument name type required description endpointid string required endpoint id output parameter type description status code number http status code of the response reason string response reason phrase id string unique identifier status string status value requestedat string output field requestedat example \[ { "status code" 201, "response headers" { "date" "tue, 25 jun 2024 07 33 17 gmt", "content type" "application/json", "transfer encoding" "chunked", "connection" "keep alive", "x correlation id" "5304dbd8 ac5b 4915 b296 3e26c94cd5ff", "x request id" "4028517a 90cc 47e5 870a 1e52ff3ef064" }, "reason" "", "json body" { "id" "416e722a 4ee3 4e81 98c0 a5489ee23fc6", "status" "requested", "requestedat" "2024 06 25t07 33 16 990060040z" } } ] response headers header description example connection http response header connection keep alive content type the media type of the resource application/json date the date and time at which the message was originated tue, 25 jun 2024 08 37 17 gmt transfer encoding http response header transfer encoding chunked x correlation id a unique identifier for correlating requests ff459065 adfe 4deb 8d75 8df4d1629e7f x request id a unique identifier for the request 4028517a 90cc 47e5 870a 1e52ff3ef064 notes authentication steps to get x tenant id , url authentication information can be found here https //developer sophos com/intro#introductionapi documentation for common api https //developer sophos com/docs/common v1/1/overviewapi documentaion for endpoint api https //developer sophos com/docs/endpoint v1/1/overviewapi documentation for siem integration api https //developer sophos com/docs/siem v1/1/overview