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 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 notes authentication steps to get x tenant id , url https //developer sophos com/intro#introduction https //developer sophos com/docs/common v1/1/overview https //developer sophos com/docs/endpoint v1/1/overview https //developer sophos com/docs/siem v1/1/overview 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 optional property by which an item is allowed properties object optional allowed item properties properties filename string optional file name properties path string optional path for the application properties sha256 string optional sha256 value for the application properties certificatesigner string optional value saved for the certificatesigner comment string optional 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 input example {"json body" {"type" "path","properties" {"filename" "filename txt","path" "$desktop/documents/filename txt","sha256" "","certificatesigner" ""},"comment" "item is not a malware","originpersonid" "3fa85f64 5717 4562 b3fc 2c963f66afa6","originendpointid" "3fa85f64 5717 4562 b3fc 2c963f66afa6"}} 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 properties filename string name of the resource properties path string output field properties path properties sha256 string output field properties sha256 properties certificatesigner string output field properties certificatesigner comment string output field comment type string type of the resource createdby object output field createdby createdby id string unique identifier createdby name string name of the resource originperson object output field originperson originperson id string unique identifier originperson name string name of the resource originendpoint object output field originendpoint originendpoint id string unique identifier output 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" {"filename" "example exe","path" "/opt/application/example exe","sha256" "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","certificatesigner" "example signer"},"comment" "allowed for testing purposes ","type" "sha256","createdby" {"id" "111aaa222bbb333ccc444ddd555eee666","name" "admin u 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 optional property by which an item is blocked properties object optional blocked item properties properties filename string optional file name properties path string optional path for the application properties sha256 string optional sha256 value for the application properties certificatesigner string optional value saved for the certificatesigner comment string optional comment indicating why the item should be blocked input example {"json body" {"type" "sha256","properties" {"filename" "filename txt","path" "$desktop/documents/filename txt","sha256" "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad","certificatesigner" "xyz"},"comment" "item is a malware"}} 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 properties filename string name of the resource properties path string output field properties path properties sha256 string output field properties sha256 properties certificatesigner string output field properties certificatesigner comment string output field comment type string type of the resource createdby object output field createdby createdby id string unique identifier createdby name string name of the resource originperson object output field originperson originperson id string unique identifier originperson name string name of the resource originendpoint object output field originendpoint originendpoint id string unique identifier output 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" {"filename" "malicious exe","path" "/tmp/malicious exe","sha256" "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789","certificatesigner" "unknown"},"comment" "detected as malicious by antivirus engine ","type" "sha256","createdby" {"id" "111aaa222bbb333ccc444ddd555eee666","name" "security 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 path parameters alertid string required alert id action string optional actions that you can perform on these alerts message string optional message to send for the action input example {"json body" {"action" "cleanpua","message" "remove winexesvc"},"path parameters" {"alertid" "a5ded91c 6575 435c a6b4 64b94f9048ff"}} 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 output 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 parameters pagefromkey string optional the key of the item from where to fetch a page parameters pagesize number optional the size of the page requested parameters pagetotal boolean optional whether the number of pages should be calculated and returned in the response parameters sort array optional defines how to sort the data parameters healthstatus array optional find endpoints by health status parameters type array optional find endpoints by type parameters tamperprotectionenabled boolean optional find endpoints by whether tamper protection is turned on parameters lockdownstatus array optional find endpoints by lockdown status parameters 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) parameters 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) parameters ids array optional find endpoints with the specified ids parameters isolationstatus string optional find endpoints by isolation status parameters hostnamecontains string optional find endpoints where the hostname contains the given string only the first 10 characters of the given string are matched parameters associatedpersoncontains string optional find endpoints where the name of the person associated with the endpoint contains the given string parameters groupnamecontains string optional find endpoints where the name of the group the endpoint is in contains the given string parameters search string optional term to search for in the specified search fields parameters 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 parameters ipaddresses array optional find endpoints by ip addresses parameters cloud array optional find endpoints that are cloud instances parameters fields array optional the fields to return in a partial response parameters view string optional type of view to be returned in response parameters assignedtogroup boolean optional whether endpoint is assigned to a group parameters groupids array optional match endpoints by assigned group parameters macaddresses array optional find endpoints by mac addresses must contain at most 50 items must be unique input example {"parameters" {"pagefromkey" "abcdef123456","pagesize" 50,"pagetotal"\ false,"sort" \["hostname\ asc","lastseenat\ desc"],"healthstatus" \["good","bad"],"type" \["computer","server"],"tamperprotectionenabled"\ true,"lockdownstatus" \["unlocked","notinstalled"],"lastseenbefore" "2019 09 23t12 02 01 700z","lastseenafter" "pt4h500s","ids" \["123e4567 e89b 12d3 a456 426614174000","987e6543 21cb 43d1 ba69 123456789000"],"isolationstatus" "isolated","hostnamecontains" "example","associatedpersoncontains" "john","groupnamecontains" "workstations","search" "windows","searchfields" \["hostname","groupname","associatedpersonname","osname"],"ipaddresses" \["192 168 1 100","10 0 0 1"],"cloud" \["aws\ i 3bc4829309","azure 42349c92"],"fields" \["id","hostname","os"],"view" "full","assignedtogroup"\ true,"groupids" \["654321ab cdef 9876 5432 fedcba098765","abcdef12 3456 7890 fedc ba9876543210"],"macaddresses" \["01 23 45 67 89\ ab","0123456789ab"]}} output parameter type description status code number http status code of the response reason string response reason phrase items array output field items items id string unique identifier items type string type of the resource items tenant object output field items tenant items tenant id string unique identifier items tenant hostname string name of the resource items health object output field items health items health overall string output field items health overall items threats object output field items threats items threats status string status value items services object output field items services items services status string status value items services servicedetails array output field items services servicedetails items services servicedetails name string name of the resource items services servicedetails status string status value items os object output field items os items os isserver boolean output field items os isserver items os platform string output field items os platform items os name string name of the resource items os majorversion number output field items os majorversion items os minorversion number output field items os minorversion items os build number output field items os build items os ipv4addresses array output field items os ipv4addresses output example {"status code" 200,"response headers" {},"reason" "ok","json body" {"items" \[{}],"pages" {"fromkey" "key1","nextkey" "key2","size" 10,"total" 100,"items" 1000,"maxsize" 50}}} 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 path parameters endpointid string required endpoint id input example {"path parameters" {"endpointid" "416e722a 4ee3 4e81 98c0 a5489ee23fc6"}} 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 lastenabledby id string unique identifier lastenabledby type string type of the resource lastenabledby name string name of the resource lastenabledby accounttype string type of the resource lastenabledby accountid string unique identifier lastdisabledat string output field lastdisabledat lastdisabledby object output field lastdisabledby lastdisabledby id string unique identifier lastdisabledby type string type of the resource lastdisabledby name string name of the resource lastdisabledby accounttype string type of the resource lastdisabledby accountid string unique identifier comment string output field comment output 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" {"id" "john doe\@example com","type" "user","name" "john doe","accounttype" "organization","accountid" "98765432 abcdef 01234 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 parameters limit number optional the maximum number of items to return parameters 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 parameters cursor string optional identifier for next item in the list, this value is available in response as next cursor input example {"parameters" {"limit" 100,"from date" 86400,"cursor" "xyz"}} 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 items created at string output field items created at items customer id string unique identifier items data object response data items description string output field items description items event service event id string unique identifier items id string unique identifier items info object output field items info items location string output field items location items severity string output field items severity items source string output field items source items threat string output field items threat items threat cleanable boolean output field items threat cleanable items type string type of the resource items when string output field items when next cursor string output field next cursor output 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 prameters limit number optional the maximum number of items to return prameters cursor string optional identifier for next item in the list, this value is available in response as next cursor prameters from date number optional the starting date from which alerts will be retrieved defined as unix timestamp in utc ignored if cursor is set prameters exclude types string optional the string of list of types of events to be excluded input example {"prameters" {"limit" 100,"cursor" "xyz","from date" "86400","exclude types" "error,warning,info,debug"}} 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 items amsi threat data object response data items amsi threat data parentprocessid string response data items amsi threat data parentprocesspath string response data items amsi threat data processid string response data items amsi threat data processname string response data items amsi threat data processpath string response data items appcerts array output field items appcerts items appcerts signer string output field items appcerts signer items appcerts thumbprint string output field items appcerts thumbprint items appsha256 string output field items appsha256 items core remedy items object output field items core remedy items items core remedy items items array output field items core remedy items items items core remedy items items descriptor string output field items core remedy items items descriptor items core remedy items items result string result of the operation items core remedy items items type string type of the resource items core remedy items totalitems number output field items core remedy items totalitems items created at string output field items created at items customer id string unique identifier items details array output field items details items details property string output field items details property items details type string type of the resource output 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 optional 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 optional list of endpoints ids max contain is 50 input example {"json body" {"enabled"\ true,"comment" "isolating endpoints with suspicious health","ids" \["3fa85f64 5717 4562 b3fc 2c963f66afa6","9d5d6819 0238 43e6 ba03 815cae0d474d","2da8b591 9164 4f7e a367 ad9b9cb77736","66046f6a bff0 4b51 aa0b ac18bd363207"]}} 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 isolation enabled boolean output field isolation enabled isolation lastenabledat string output field isolation lastenabledat isolation lastenabledby object output field isolation lastenabledby isolation lastenabledby id string unique identifier isolation lastenabledby type string type of the resource isolation lastenabledby name string name of the resource isolation lastenabledby accounttype string type of the resource isolation lastenabledby accountid string unique identifier isolation lastdisabledat string output field isolation lastdisabledat isolation lastdisabledby object output field isolation lastdisabledby isolation lastdisabledby id string unique identifier isolation lastdisabledby type string type of the resource isolation lastdisabledby name string name of the resource isolation lastdisabledby accounttype string type of the resource isolation lastdisabledby accountid string unique identifier isolation comment string output field isolation comment output example {"status code" 200,"response headers" {},"reason" "ok","json body" {"id" "123e4567 e89b 12d3 a456 426614174000","isolation" {"enabled"\ true,"lastenabledat" "2024 06 25t15 30 00z","lastenabledby" {},"lastdisabledat" "2024 06 24t12 00 00z","lastdisabledby" {},"comment" "endpoint isolated due to security incident "}}} 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 path parameters alertid string required alert id input example {"path parameters" {"alertid" "a5ded91c 6575 435c a6b4 64b94f9048ff"}} 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 managedagent id string unique identifier managedagent type string type of the resource person object output field person 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 tenant id string unique identifier tenant name string name of the resource type string type of the resource output example {"status code" 200,"response headers" {},"reason" "ok","json body" {"id" "a5ded91c 6575 435c a6b4 64b94f9048ff","allowedactions" \["acknowledge"],"category" "updating","description" "john pc is out of date ","groupkey" "msxfdmvuddo6rw5kcg9pbnq6ok91de9mrgf0zsw1mtms","managedagent" {"id" "bb90527d 73a8 4e6e 85c6 20c2e0c5bc6f","type" "computer"},"person" {"id" "17dd896f ee9f 4f7d a2a2 6a8c0b48ff15"},"product" "endpoint","raisedat" "2021 02 12t15 04 53 780z","severity" "medium","tenant" {"id" "79067f 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 path parameters endpointid string required endpoint id input example {"json body" {},"path parameters" {"endpointid" "416e722a 4ee3 4e81 98c0 a5489ee23fc6"}} 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 output 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 5304dbd8 ac5b 4915 b296 3e26c94cd5ff x request id a unique identifier for the request 49f7d5e4 c3b0 4314 a965 a3338b232b09