Google Chronicle Legacy API

the google chronicle legacy api connector allows for automated interaction with google chronicle's security analytics platform, enabling efficient threat detection and incident management google chronicle legacy api offers a powerful suite of tools for security incident management and threat intelligence analysis with the swimlane turbine connector, users can effortlessly manage cases, add tags, and retrieve detailed information about incidents and detections this integration enables security teams to streamline their incident response workflows, enhance case analysis with rich data, and efficiently detect and investigate threats using curated rules and detections by leveraging this connector, swimlane turbine users can maximize their security operations efficiency and effectiveness limitations none to date supported versions this connector supports the latest version of google chronicle legacy api additional docs https //cloud google com/chronicle/docs/reference/rest/v1alpha/projects locations instances legacy configuration prerequisites before utilizing the google chronicle legacy api connector with swimlane turbine, ensure you have the following prerequisites oauth2 0 authentication with the following parameters service account info a json file containing credentials for a service account url the endpoint url for the google chronicle legacy api scopes the specific oauth scopes required for the desired api operations authentication methods oauth 2 0 client credentials authentication to effectively utilize the google chronicle legacy api connector within swimlane turbine, ensure you have the following prerequisites oauth2 0 authentication for google chronicle legacy api with these parameters service account info a json file containing your service account credentials url the endpoint url for the google chronicle legacy api gcp project creation log in to gcp console here https //console cloud google com/ navigate to this link to create a new project https //console cloud google com/projectcreate name your project and click create we recommend specific and recognizable project names navigate to your projects, and select your new project enable the google chronicle api go to the api & services dashboard in the cloud console click on the "enable apis and services" button asset configuration configuring a service account google chronicle legacy api connector requires a google service account to authenticate open https //console developers google com/iam admin/serviceaccounts select the appropriate project click + create new service account assign a name for the service account and add a description, click create and continue click the select a role dropdown and type “owner” in the filter choose owner , chronicle api admin and click continue for the menu specifying grant users access to this service account (optional) you may select users or skip and click done this is not required for the connector click on the newly created service account email navigate to the keys menu click add key , select create new key , select json format, and click create make sure you download the json file presented json needs to be passed in the asset input service account info as a base64 encoded string this file will be needed when configuring the asset in swimlane setting api scopes after creating a service account, the necessary api scopes required to be authorized must be set from https //admin google com/ , navigate to security > api controls and then click manage domain wide delegation at the bottom of the window click add new in the client id field, enter the unique id from the service account details menu enter the following csv value into the oauth scopes (comma delimited) input https //www googleapis com/auth/chronicle backstory click authorize capabilities this google chronicle legacy api connector provides the following capabilities add tag for case get case legacy create or update case legacy get detection legacy search curated detections legacy search detections legacy search rule detection events legacy update alert list cases list rules merge cases patch case add tag for case adds a specified tag to a case in google chronicle legacy api using the case name and tag provided https //cloud google com/chronicle/docs/reference/rest/v1alpha/projects locations instances cases/addtag?rep location=us get case retrieves a specific case from google chronicle legacy api, providing detailed information about the incident https //cloud google com/chronicle/docs/reference/rest/v1alpha/projects locations instances cases/get?rep location=us legacy create or update case create or update cases in google chronicle legacy api using specified instance and caseresource details https //cloud google com/chronicle/docs/reference/rest/v1alpha/projects locations instances legacy/legacycreateorupdatecase?rep location=us legacy get detection retrieve a specific detection from google chronicle legacy api using ruleid and detectionid as parameters https //cloud google com/chronicle/docs/reference/rest/v1alpha/projects locations instances legacy/legacygetdetection?rep location=us legacy search curated detections search for detections associated with a curated rule in google chronicle using the legacy endpoint requires 'instance' path parameter and 'ruleid' https //cloud google com/chronicle/docs/reference/rest/v1alpha/projects locations instances legacy/legacysearchcurateddetections?rep location=us legacy search detections search for detections associated with a specific rule version in google chronicle using the legacy api endpoint requires 'instance' path parameter and 'ruleid' https //cloud google com/chronicle/docs/reference/rest/v1alpha/projects locations instances legacy/legacysearchdetections?rep location=us legacy search rule detection events list events linked to a specific detection from a rules engine rule in google chronicle legacy api, requiring 'instance' and 'ruleid' https //cloud google com/chronicle/docs/reference/rest/v1alpha/projects locations instances legacy/legacysearchruledetectionevents?rep location=us legacy update alert updates an existing alert in google chronicle using the legacy api endpoint, requiring alertid and feedback https //cloud google com/chronicle/docs/reference/rest/v1alpha/projects locations instances legacy/legacyupdatealert?rep location=us list cases retrieve a list of cases from google chronicle legacy api using the specified parent path parameter https //cloud google com/chronicle/docs/reference/rest/v1alpha/projects locations instances cases/list?rep location=us list rules retrieves a list of rules from google chronicle legacy api based on the specified parent path parameter https //cloud google com/chronicle/docs/reference/rest/v1alpha/projects locations instances rules/list?rep location=us merge cases combine multiple cases into a single case in google chronicle, specifying the parent case and the ids of cases to merge https //cloud google com/chronicle/docs/reference/rest/v1alpha/projects locations instances cases/merge?rep location=us patch case updates an existing case in google chronicle legacy api using the specified case name https //cloud google com/chronicle/docs/reference/rest/v1alpha/projects locations instances cases/patch?rep location=us configurations google chronicle legacy api authentication oauth2 0 authentication for google chronicle legacy api configuration parameters parameter description type required b64 service info base64 encoded credentials json authentication file contents string required url server api address string required scopes scope to be used for authentication array required verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional actions add tag for case adds a specified tag to an existing case in google chronicle legacy api, requiring the case name and tag endpoint url v1alpha/{{name}}\ addtag method post input argument name type required description path parameters name string required the resource name of the case to add tag for format projects/{project}/locations/{location}/instances/{instance}/cases/{case} timeout integer optional maximum number of seconds to wait for the search to complete before timing out default is 600 seconds (10 minutes) tag string optional the tag to add to the case input example {"json body" {"tag" "tag 1234567890"},"path parameters" {"name" "projects/1234567890/locations/us central1/instances/1234567890/cases/1234567890"}} output parameter type description data object response data output example {"data" {}} get case retrieves detailed information about a specific incident case from google chronicle legacy api using the provided case name endpoint url v1alpha/{{name}} method get input argument name type required description parameters expand string optional expand field for getting related resources path parameters name string required the resource name of the case to retrieve format projects/{project}/locations/{location}/instances/{instance}/cases/{case} timeout integer optional maximum number of seconds to wait for the search to complete before timing out default is 600 seconds (10 minutes) input example {"parameters" {"expand" "expand 1"},"path parameters" {"name" "projects/1234567890/locations/us central1/instances/1234567890/cases/1234567890"}} output parameter type description data object response data output example {"data" {}} legacy create or update case create or update cases in google chronicle legacy api using the provided instance and caseresource details endpoint url v1alpha/{{instance}}/legacy\ legacycreateorupdatecase method post input argument name type required description path parameters instance string required the name of the parent resource, which is the secops instance this request is sent to format projects/{project}/locations/{location}/instances/{instance} timeout integer optional maximum number of seconds to wait for the search to complete before timing out default is 600 seconds (10 minutes) caseresource object optional the case to be created or updated caseresource id string optional the id of the case caseresource soarplatforminfo object optional case related info of this same case in customer's soar platform caseresource soarplatforminfo caseid string optional id of the case in soar product caseresource soarplatforminfo responseplatformtype string optional type of soar product caseresource displayname string optional the display name of the case caseresource stage string optional the stage of the case predefined values include "triage", "assessment", "investigation", "incident", "improvement", "research" and users can define custom string values caseresource priority string optional the priority of the case caseresource status string optional the status of the case caseresource alertids array optional alert ids that are part of this case input example {"json body" {"caseresource" {"id" "case 1234567890","soarplatforminfo" {"caseid" "case 1234567890","responseplatformtype" "response platform type unspecified"},"displayname" "testing case 1","stage" "stage unspecified","priority" "priority unspecified","status" "status unspecified","alertids" \["alert 1234567890"]}},"path parameters" {"instance" "projects/1234567890/locations/us central1/instances/1234567890"}} output parameter type description data object response data output example {"data" {}} legacy get detection retrieve a specific detection from google chronicle legacy api using the provided ruleid and detectionid endpoint url v1alpha/{{instance}}/legacy\ legacygetdetection method get input argument name type required description parameters ruleid string required the specific rule revision to get a detection for here are two acceptable formats {ruleid} gets a detection for the latest revision of the rule with rule id ruleid {ruleid}@{revisionid} gets a detection for the rule revision with rule id ruleid and revision id revisionid parameters detectionid string required the detection to get path parameters instance string required the instance to get a detection for the name of the parent resource, which is the secops instance this request is sent to format projects/{project}/locations/{location}/instances/{instance} timeout integer optional maximum number of seconds to wait for the search to complete before timing out default is 600 seconds (10 minutes) input example {"parameters" {"ruleid" "1234567890","detectionid" "1234567890"},"path parameters" {"instance" "projects/1234567890/locations/us central1/instances/1234567890"}} output parameter type description data object response data output example {"data" {}} legacy search curated detections retrieve detections linked to a specific curated rule in google chronicle, utilizing 'instance' and 'ruleid' for targeted results endpoint url v1alpha/{{instance}}/legacy\ legacysearchcurateddetections method get input argument name type required description parameters ruleid string required the specific curated rule id to list detections for detections will be aggregated across all versions of the rule parameters alertstate string optional filters which detections are returned by their alertstate parameters starttime string optional the time to start search detections from, inclusive uses rfc 3339, where generated output will always be z normalized and use 0, 3, 6 or 9 fractional digits offsets other than "z" are also accepted examples "2014 10 02t15 01 23z ", "2014 10 02t15 01 23 045123456z" or "2014 10 02t15 01 23 +05 30 " parameters endtime string optional the time to end search detections from, exclusive uses rfc 3339, where generated output will always be z normalized and use 0, 3, 6 or 9 fractional digits offsets other than "z" are also accepted examples "2014 10 02t15 01 23z ", "2014 10 02t15 01 23 045123456z" or "2014 10 02t15 01 23 +05 30 " parameters listbasis string optional the basis on which detections are listed parameters pagesize number optional the maximum number of detections to return the service may return fewer than this value if unspecified, at most 100 detections will be returned the maximum value is 1000; values above 1000 will be coerced to 1000 parameters pagetoken string optional a page token, received from a previous legacy legacysearchcurateddetections call provide this to retrieve the subsequent page when paginating, all other parameters provided to legacy legacysearchcurateddetections must match the call that provided the page token parameters maxrespsizebytes number optional the maximum size of response in bytes if it is set to 0 (or is omitted), the server will not enforce any max response size limit parameters includenesteddetections boolean optional if true, include one level of nested detections in the response path parameters instance string required the name of the parent resource, which is the secops instance this request is sent to format projects/{project}/locations/{location}/instances/{instance} timeout integer optional maximum number of seconds to wait for the search to complete before timing out default is 600 seconds (10 minutes) input example {"parameters" {"ruleid" "1234567890","alertstate" "not alerting","starttime" "2014 10 02t15 01 23z","endtime" "2014 10 02t15 01 23z","listbasis" "list basis unspecified","pagesize" 100,"pagetoken" "testtoken","maxrespsizebytes" 1024,"includenesteddetections"\ true},"path parameters" {"instance" "projects/1234567890/locations/us central1/instances/1234567890"}} output parameter type description data object response data output example {"data" {}} legacy search detections search for detections linked to a rule version in google chronicle legacy api using 'instance' and 'ruleid' endpoint url v1alpha/{{instance}}/legacy\ legacysearchdetections method get input argument name type required description parameters ruleid string required the specific rule revision to search detections for there are four acceptable formats {ruleid} retrieves detections for the latest revision of the rule with rule id ruleid {ruleid}@{revisionid} retrieves detections for the rule revision with rule id ruleid and revision id revisionid {ruleid}@{wildcard} retrieves detections for all revisions of the rule with rule id ruleid {wildcard} retrieves detections for all revisions of all rules parameters alertstate string optional filters which detections are returned by their alertstate parameters starttime string optional the time to start search detections from, inclusive uses rfc 3339, where generated output will always be z normalized and use 0, 3, 6 or 9 fractional digits offsets other than "z" are also accepted examples "2014 10 02t15 01 23z ", "2014 10 02t15 01 23 045123456z" or "2014 10 02t15 01 23 +05 30 " parameters endtime string optional the time to end search detections from, exclusive uses rfc 3339, where generated output will always be z normalized and use 0, 3, 6 or 9 fractional digits offsets other than "z" are also accepted examples "2014 10 02t15 01 23z ", "2014 10 02t15 01 23 045123456z" or "2014 10 02t15 01 23 +05 30 " parameters listbasis string optional the basis on which detections are listed parameters pagesize number optional the maximum number of detections to return the service may return fewer than this value if unspecified, at most 100 detections will be returned the maximum value is 1000; values above 1000 will be coerced to 1000 parameters pagetoken string optional a page token, received from a previous legacy legacysearchdetections call provide this to retrieve the subsequent page when paginating, all other parameters provided to legacy legacysearchdetections must match the call that provided the page token parameters maxrespsizebytes number optional the maximum size of response in bytes if it is set to 0 (or is omitted), the server will not enforce any max response size limit parameters includenesteddetections boolean optional if true, include one level of nested detections in the response path parameters instance string required the name of the parent resource, which is the secops instance this request is sent to format projects/{project}/locations/{location}/instances/{instance} timeout integer optional maximum number of seconds to wait for the search to complete before timing out default is 600 seconds (10 minutes) input example {"parameters" {"ruleid" "1234567890","alertstate" "not alerting","starttime" "2014 10 02t15 01 23z","endtime" "2014 10 02t15 01 23z","listbasis" "list basis unspecified","pagesize" 100,"pagetoken" "testtoken","maxrespsizebytes" 1024,"includenesteddetections"\ true},"path parameters" {"instance" "projects/1234567890/locations/us central1/instances/1234567890"}} output parameter type description status code number http status code of the response reason string response reason phrase output example {"status code" 200,"response headers" {},"reason" "ok","json body" {}} legacy search rule detection events list events associated with a specific detection rule in google chronicle legacy api, using 'instance' and 'ruleid' endpoint url v1alpha/{{instance}}/legacy\ legacysearchruledetectionevents method get input argument name type required description parameters ruleid string required the rule id that generated the detection parameters versiontimestamp string optional the version timestamp of the rule that generated the detection if omitted, the latest version of the rule will be used uses rfc 3339, where generated output will always be z normalized and use 0, 3, 6 or 9 fractional digits offsets other than "z" are also accepted examples "2014 10 02t15 01 23z ", "2014 10 02t15 01 23 045123456z" or "2014 10 02t15 01 23 +05 30 " parameters detectionid string optional the id of the detection parameters maxevents number optional max events returned over all event variables the default and limit is 100k events over all event variables the events of this detection are sorted by event timestamp, truncated to maxevents events, and grouped by event variable in the response path parameters instance string required chronicle instance this request is sent to format projects/{project}/locations/{location}/instances/{instance} timeout integer optional maximum number of seconds to wait for the search to complete before timing out default is 600 seconds (10 minutes) input example {"parameters" {"ruleid" "1234567890","versiontimestamp" "2014 10 02t15 01 23z","detectionid" "1234567890","maxevents" 10000},"path parameters" {"instance" "projects/1234567890/locations/us central1/instances/1234567890"}} output parameter type description data object response data output example {"data" {}} legacy update alert updates an existing alert in google chronicle legacy api with the provided alertid and feedback endpoint url v1alpha/{{instance}}/legacy\ legacyupdatealert method post input argument name type required description path parameters instance string required chronicle instance this request is sent to timeout integer optional maximum number of seconds to wait for the search to complete before timing out default is 600 seconds (10 minutes) alertid string optional the unique identifier for the alert to be updated feedback object optional parameter for legacy update alert feedback verdict string optional a verdict on whether the finding reflects a security inc feedback reputation string optional a categorization of the finding as useful or not useful feedback confidencescore number optional confidence score (0 100) of the finding feedback riskscore number optional risk score (0 100) of the finding feedback disregarded boolean optional analyst disregard (or un disregard) the event feedback severity number optional severity score (1 100) of the finding feedback comment string optional analyst comment feedback status string optional the status of the alert feedback priority string optional the priority of the alert feedback rootcause string optional the root cause of the alert feedback reason string optional the reason for the alert feedback severitydisplay string optional severity display name for ui and filtering feedback triageagentinvestigationid string optional output only investigation id of the latest investigation performed by the triage agent on the alert the triage agent is designed to autonomously investigate alerts and determine whether an alert needs to be escalated to a human while providing transparency about the actions it took as part of its investigation feedback usertype string optional output only type of user that submitted or updated the feedback this field is used to distinguish between the feedback submitted by a human analyst and an ai agent by default, the user is assumed to be a human analyst casename string optional the case name that the alert is associated with responseplatforminfo object optional the response platform info of the alert responseplatforminfo alertid string optional id of the alert in soar product responseplatforminfo responseplatformtype string optional type of soar product input example {"json body" {"alertid" "alert 1","feedback" {"verdict" "malicious","reputation" "high","confidencescore" 85,"riskscore" 70,"disregarded"\ false,"severity" 4,"comment" "suspicious activity detected ","status" "open","priority" "high","rootcause" "phishing email","reason" "suspicious behavior","severitydisplay" "critical","triageagentinvestigationid" "invest 67890","usertype" "employee"},"casename" "case name 1","responseplatforminfo" {"alertid" "alert 1","responseplatformtype" "response platform type unspecified"}},"path parameters" {"instance" "testing 1"}} output parameter type description data object response data output example {"data" {}} list cases retrieve a list of cases from google chronicle legacy api using the specified 'parent' path parameter endpoint url v1alpha/{{parent}}/cases method get input argument name type required description parameters pagesize number optional the maximum number of cases to return the service may return fewer than this value if unspecified, at most 50 cases will be returned the maximum value is 1000; values above 1000 will be coerced to 1000 parameters pagetoken string optional a page token, received from a previous cases list call provide this to retrieve the subsequent page when paginating, all other parameters provided to cases list must match the call that provided the page token parameters filter string optional a filter to apply to the list of cases supported filter fields displayname , creatoruserid , creatoruser , lastmodifyinguserid , lastmodifyinguser , assignee , assigneduser , stage , priority , important , type , environment , case data state , score , alertssla , sla , tags , products , closuredetails , tasks parameters orderby string optional configures ordering of cases in the response if not specified, cases are returned in descending order of their create time the default ordering is by create time in descending order the orderby string is a comma separated list of fields supported sort fields displayname , creatoruserid , creatoruser , lastmodifyinguserid , lastmodifyinguser , assignee , assigneduser , stage , priority , important , type , environment , case data state , score , alertssla , sla , tags , products , closuredetails , tasks parameters expand string optional expand the response to include the full case object supported values tasks, tags, products path parameters parent string required the instance to list cases for format projects/{project}/locations/{location}/instances/{instance}/cases timeout integer optional maximum number of seconds to wait for the search to complete before timing out default is 600 seconds (10 minutes) input example {"parameters" {"pagesize" 100,"pagetoken" "testtoken","filter" "displayname='some name'","orderby" "displayname desc, priority","expand" "tags, products"},"path parameters" {"parent" "projects/1234567890/locations/us central1/instances/1234567890/cases"}} output parameter type description data object response data output example {"data" {}} list rules retrieves a list of detection rules from google chronicle legacy api, utilizing the specified 'parent' path parameter endpoint url v1alpha/{{parent}}/rules method get input argument name type required description parameters pagesize number optional the maximum number of rules to return the service may return fewer than this value if unspecified, at most 100 rules will be returned the maximum value is 1000; values above 1000 will be coerced to 1000 parameters pagetoken string optional a page token, received from a previous rules list call provide this to retrieve the subsequent page when paginating, all other parameters provided to rules list must match the call that provided the page token parameters view string optional view indicates the scope of fields to populate for the rule being returned if unspecified, defaults to basic parameters filter string optional only the following filters are allowed "referencelists {reference list name}", "datatables {data table name}", "displayname {displayname}" path parameters parent string required the parent, which owns this collection of rules timeout integer optional maximum number of seconds to wait for the search to complete before timing out default is 600 seconds (10 minutes) input example {"parameters" {"pagesize" 50,"pagetoken" "testtoken","view" "rule view unspecified","filter" "referencelists {reference list name}"},"path parameters" {"parent" "projects/1234567890/locations/us central1/instances/1234567890"}} output parameter type description data object response data output example {"data" {}} merge cases combine multiple cases into one within google chronicle using the parent case id and specific case ids to merge endpoint url v1alpha/{{parent}}/cases\ merge method post input argument name type required description path parameters parent string required the instance to merge cases on format projects/{project}/locations/{location}/instances/{instance}/cases timeout integer optional maximum number of seconds to wait for the search to complete before timing out default is 600 seconds (10 minutes) casesids array optional the ids of the cases to merge casetomergewith number optional the id of the case to merge with input example {"json body" {"casesids" \[1234567890,1234567891],"casetomergewith" 1234567890},"path parameters" {"parent" "projects/1234567890/locations/us central1/instances/1234567890/cases"}} output parameter type description data object response data output example {"data" {}} patch case updates an existing case in google chronicle legacy api using the specified 'case name' required inputs include path parameters and json body endpoint url v1alpha/{{case name}} method patch input argument name type required description parameters updatemask string optional the list of fields to update if not included, all fields with default/non default values will be overwritten this is a comma separated list of fully qualified names of fields path parameters case name string required the unique name(id) of the case format projects/{project}/locations/{location}/instances/{instance}/cases/{case} timeout integer optional maximum number of seconds to wait for the search to complete before timing out default is 600 seconds (10 minutes) input example {"parameters" {"updatemask" "user displayname,photo"},"json body" {},"path parameters" {"case name" "projects/1234567890/locations/us central1/instances/1234567890/cases/1234567890"}} output parameter type description data object response data output example {"data" {}} response headers header description example content type the media type of the resource application/json date the date and time at which the message was originated thu, 01 jan 2024 00 00 00 gmt