Cisco Umbrella Investigate

the cisco umbrella investigate connector enables automated access to domain, ip, and threat intelligence data for enhanced security analysis and incident response cisco umbrella investigate provides a complete view of the relationships and evolution of internet domains, ips, and file hashes by integrating with swimlane turbine, users can leverage cisco's threat intelligence to enrich security events, automate investigations, and enhance incident response the connector enables real time domain and ip analysis, access to historical dns data, and retrieval of whois information, directly within swimlane playbooks this empowers security teams to rapidly assess threats and take informed actions, improving overall security posture and response times limitations none to date supported versions this cisco umbrella investigate connector uses the umbrella investigate api (investigate api opendns com) additional docs https //developer cisco com/docs/cloud security/#!umbrella api reference overview https //developer cisco com/docs/cloud security/#!get domain status and categorization https //docs umbrella com/deployment umbrella/docs/manage umbrella investigate configuration prerequisites to effectively utilize the cisco umbrella investigate connector with swimlane turbine, ensure you have the following http bearer token authentication with these parameters url endpoint for the cisco umbrella investigate api token bearer token required to authenticate api requests authentication methods http bearer authentication url the endpoint url for the umbrella investigate api (default https //investigate api opendns com/ ) token the api token provided by umbrella investigate create an investigate api token in the umbrella dashboard verify ssl certificates (optional) enable or disable ssl certificate verification http(s) proxy (optional) a proxy url to route requests through capabilities this cisco umbrella investigate connector provides the following capabilities get domain status and categorization query domain domain risk score security information for a domain related domains for a domain get passive dns history for domain get passive dns results by ip whois domain get domain status and categorization returns the status and categorization for a domain, including status ( 1 malicious, 1 safe, 0 undetermined), security categories, and content categories cisco's documentation for this action can be found https //developer cisco com/docs/cloud security/#!get domain status and categorization query domain queries cisco umbrella information on the domain, including status and categorization cisco's documentation for this action can be found https //developer cisco com/docs/cloud security/#!umbrella api reference overview domain risk score returns the umbrella investigate risk score for a domain based on lexical characteristics, query patterns, and other indicators cisco's documentation for this action can be found https //developer cisco com/docs/cloud security/#!umbrella api reference overview security information for a domain returns multiple security scores and features for a domain (e g dga score, entropy, geodiversity, popularity) cisco's documentation for this action can be found https //developer cisco com/docs/cloud security/#!umbrella api reference overview related domains for a domain returns a list of domain names that frequently co occur with the given domain in queries cisco's documentation for this action can be found https //developer cisco com/docs/cloud security/#!umbrella api reference overview get passive dns history for domain returns passive dns (pdns) history for a domain cisco's documentation for this action can be found https //developer cisco com/docs/cloud security/#!umbrella api reference overview get passive dns results by ip returns passive dns results for a given ip address cisco's documentation for this action can be found https //developer cisco com/docs/cloud security/#!umbrella api reference overview whois domain returns whois information for the specified domain cisco's documentation for this action can be found https //developer cisco com/docs/cloud security/#!umbrella api reference overview configurations http bearer authentication authenticates using bearer token such as a jwt, etc configuration parameters parameter description type required url a url to the target host string required token the api token provided by investigate string required verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional actions domain risk score retrieve the risk score for a domain from cisco umbrella investigate, based on lexical analysis and query patterns endpoint url domains/risk score/{{domain}} method get input argument name type required description path parameters domain string required parameters for the domain risk score action input example {"path parameters" {"domain" "cisco com"}} output parameter type description status code number http status code of the response reason string response reason phrase indicators array output field indicators indicators indicator string output field indicators indicator indicators indicator id string unique identifier indicators normalized score number score value indicators score boolean score value risk score number score value output example {"status code" 200,"response headers" {"server" "nginx","date" "thu, 09 feb 2023 19 56 23 gmt","content type" "application/json","content length" "1001","connection" "keep alive","vary" "accept encoding","access control allow origin" "https //dashboard umbrella com","access control allow methods" "get, post, options","access control allow headers" "authorization, accept,dnt,user agent,x requested with,if modified since,cache co ","access control expose headers" "content length,content range"," get domain status and categorization retrieves domain status, security, and content categorizations from cisco umbrella investigate for a specified domain endpoint url domains/categorization/{{domain}} method get input argument name type required description path parameters domain string required the domain name to look up (e g cisco com, umbrella com) input example {"path parameters" {"domain" "cisco com"}} output parameter type description status code number http status code of the response reason string response reason phrase cisco com object output field cisco com cisco com status number 1 = malicious, 1 = safe, 0 = undetermined cisco com security categories array security category ids for this domain cisco com content categories array content category ids for this domain output example {"status code" 200,"response headers" {"server" "nginx","date" "thu, 09 feb 2023 20 31 00 gmt","content type" "application/json; charset=utf 8","transfer encoding" "chunked","connection" "keep alive","vary" "accept encoding","x frame options" "sameorigin, sameorigin","x xss protection" "1; mode=block, 1; mode=block","access control allow origin" "https //dashboard umbrella com","access control allow methods" "get, post, options","access control allow headers" "authorization, accept,dnt,user agen get passive dns history for domain retrieve the passive dns history for a specified domain from cisco umbrella investigate, filtering records by security categories endpoint url /pdns/name/{{domain}} method get input argument name type required description path parameters domain string required parameters for the get passive dns history for domain action input example {"path parameters" {"domain" "cisco com"}} output parameter type description status code number http status code of the response reason string response reason phrase records array output field records records minttl number output field records minttl records maxttl number output field records maxttl records firstseen number output field records firstseen records lastseen number output field records lastseen records name string name of the resource records type string type of the resource records rr string output field records rr records securitycategories array output field records securitycategories records securitycategories file name string name of the resource records securitycategories file string output field records securitycategories file records contentcategories array response content records contentcategories file name string name of the resource records contentcategories file string response content records lastseeniso string output field records lastseeniso records firstseeniso string output field records firstseeniso pageinfo object output field pageinfo pageinfo hasmorerecords boolean output field pageinfo hasmorerecords pageinfo offset number output field pageinfo offset pageinfo limit number output field pageinfo limit pageinfo totalnumrecords number output field pageinfo totalnumrecords recordinfo object output field recordinfo recordinfo minttl number output field recordinfo minttl output example {"status code" 200,"response headers" {"server" "nginx","date" "thu, 09 feb 2023 19 45 45 gmt","content type" "application/json; charset=utf 8","transfer encoding" "chunked","connection" "keep alive","strict transport security" "max age=15768000; includesubdomains"},"reason" "internal server error","json body" {"records" \[{},{}],"pageinfo" {"hasmorerecords"\ true,"offset" 0,"limit" 500,"totalnumrecords" 2544},"recordinfo" {"minttl" 3,"maxttl" 604800,"totalmaliciousdomain" 0}}} get passive dns results by ip retrieve passive dns records filtered by security categories for a specified ip address using cisco umbrella investigate endpoint url /pdns/ip/{{ip}} method get input argument name type required description path parameters ip string required parameters for the get passive dns results by ip action input example {"path parameters" {"ip" "3 219 99 232"}} output parameter type description status code number http status code of the response reason string response reason phrase records array output field records records minttl number output field records minttl records maxttl number output field records maxttl records firstseen number output field records firstseen records lastseen number output field records lastseen records name string name of the resource records type string type of the resource records rr string output field records rr records securitycategories array output field records securitycategories records securitycategories file name string name of the resource records securitycategories file string output field records securitycategories file records contentcategories array response content records contentcategories file name string name of the resource records contentcategories file string response content records lastseeniso string output field records lastseeniso records firstseeniso string output field records firstseeniso pageinfo object output field pageinfo pageinfo hasmorerecords boolean output field pageinfo hasmorerecords pageinfo offset number output field pageinfo offset pageinfo limit number output field pageinfo limit pageinfo totalnumrecords number output field pageinfo totalnumrecords recordinfo object output field recordinfo recordinfo minttl number output field recordinfo minttl output example {"status code" 200,"response headers" {"server" "nginx","date" "thu, 09 feb 2023 19 37 54 gmt","content type" "application/json; charset=utf 8","transfer encoding" "chunked","connection" "keep alive","vary" "accept encoding","x frame options" "sameorigin, sameorigin","x xss protection" "1; mode=block, 1; mode=block","access control allow origin" "https //dashboard umbrella com","access control allow methods" "get, post, options","access control allow headers" "authorization, accept,dnt,user agen query domain retrieve cisco umbrella investigate data for a specified domain, requiring the domain as a path parameter endpoint url domains/categorization/{{domain}} method get input argument name type required description path parameters domain string required parameters for the query domain action input example {"path parameters" {"domain" "cisco com"}} output parameter type description status code number http status code of the response reason string response reason phrase cisco com object output field cisco com cisco com status number status value cisco com security categories array output field cisco com security categories cisco com security categories file name string name of the resource cisco com security categories file string output field cisco com security categories file cisco com content categories array response content output example {"status code" 200,"response headers" {"server" "nginx","date" "thu, 09 feb 2023 20 31 00 gmt","content type" "application/json; charset=utf 8","transfer encoding" "chunked","connection" "keep alive","vary" "accept encoding","x frame options" "sameorigin, sameorigin","x xss protection" "1; mode=block, 1; mode=block","access control allow origin" "https //dashboard umbrella com","access control allow methods" "get, post, options","access control allow headers" "authorization, accept,dnt,user agen related domains for a domain retrieve a list of domains frequently requested around the same time as a specified domain, exclusive to that domain's timeframe endpoint url /links/name/{{domain}} method get input argument name type required description path parameters domain string required parameters for the related domains for a domain action input example {"path parameters" {"domain" "cisco com"}} output parameter type description status code number http status code of the response reason string response reason phrase tb1 array output field tb1 tb1 0 string output field tb1 0 tb1 1 number output field tb1 1 found boolean output field found output example {"status code" 200,"response headers" {"server" "nginx","date" "thu, 09 feb 2023 20 35 12 gmt","content type" "application/json; charset=utf 8","transfer encoding" "chunked","connection" "keep alive","vary" "accept encoding","x frame options" "sameorigin, sameorigin","x xss protection" "1; mode=block, 1; mode=block","access control allow origin" "https //dashboard umbrella com","access control allow methods" "get, post, options","access control allow headers" "authorization, accept,dnt,user agen security information for a domain retrieve a comprehensive list of security scores and features for a specified domain using cisco umbrella investigate endpoint url security/name/{{domain}} method get input argument name type required description path parameters domain string required parameters for the security information for a domain action input example {"path parameters" {"domain" "cisco com"}} output parameter type description status code number http status code of the response reason string response reason phrase dga score number score value perplexity number output field perplexity entropy number output field entropy securerank2 number output field securerank2 pagerank number output field pagerank asn score number score value prefix score number score value rip score number score value popularity number output field popularity fastflux boolean output field fastflux geodiversity array output field geodiversity geodiversity 0 string output field geodiversity 0 geodiversity 1 number output field geodiversity 1 geodiversity normalized array output field geodiversity normalized geodiversity normalized 0 string output field geodiversity normalized 0 geodiversity normalized 1 number output field geodiversity normalized 1 tld geodiversity array output field tld geodiversity tld geodiversity file name string name of the resource tld geodiversity file string output field tld geodiversity file geoscore number score value ks test number output field ks test attack string output field attack threat type string type of the resource output example {"status code" 200,"response headers" {"server" "nginx","date" "thu, 09 feb 2023 20 26 42 gmt","content type" "application/json; charset=utf 8","transfer encoding" "chunked","connection" "keep alive","vary" "accept encoding","x frame options" "sameorigin, sameorigin","x xss protection" "1; mode=block, 1; mode=block","access control allow origin" "https //dashboard umbrella com","access control allow methods" "get, post, options","access control allow headers" "authorization, accept,dnt,user agen whois domain retrieve whois information for a specified domain using cisco umbrella investigate, requiring the domain as a path parameter endpoint url /whois/{{domain}} method get input argument name type required description path parameters domain string required parameters for the whois domain action input example {"path parameters" {"domain" "cisco com"}} output parameter type description status code number http status code of the response reason string response reason phrase administrativecontactfax object output field administrativecontactfax whoisservers string output field whoisservers addresses array output field addresses administrativecontactname string name of the resource zonecontactemail object output field zonecontactemail billingcontactfax object output field billingcontactfax administrativecontacttelephoneext object output field administrativecontacttelephoneext administrativecontactemail string output field administrativecontactemail technicalcontactemail string output field technicalcontactemail technicalcontactfax string output field technicalcontactfax nameservers array name of the resource zonecontactname object name of the resource billingcontactpostalcode object output field billingcontactpostalcode zonecontactfax object output field zonecontactfax registranttelephoneext object output field registranttelephoneext zonecontactfaxext object output field zonecontactfaxext technicalcontacttelephoneext object output field technicalcontacttelephoneext billingcontactcity object output field billingcontactcity zonecontactstreet array output field zonecontactstreet zonecontactstreet file name string name of the resource zonecontactstreet file string output field zonecontactstreet file created string output field created administrativecontactcity string output field administrativecontactcity output example {"status code" 200,"response headers" {"server" "nginx","date" "thu, 09 feb 2023 20 10 06 gmt","content type" "application/json; charset=utf 8","transfer encoding" "chunked","connection" "keep alive","vary" "accept encoding","x frame options" "sameorigin, sameorigin","x xss protection" "1; mode=block, 1; mode=block","access control allow origin" "https //dashboard umbrella com","access control allow methods" "get, post, options","access control allow headers" "authorization, accept,dnt,user agen response headers header description example access control allow credentials http response header access control allow credentials true access control allow headers http response header access control allow headers authorization, accept,dnt,user agent,x requested with,if modified since,cache control,content type,range,x sgraph is research access control allow methods http response header access control allow methods get, post, options access control allow origin http response header access control allow origin https //dashboard umbrella com access control expose headers http response header access control expose headers content length,content range connection http response header connection keep alive content length the length of the response body in bytes 1001 content type the media type of the resource application/json; charset=utf 8 date the date and time at which the message was originated thu, 09 feb 2023 20 10 06 gmt server information about the software used by the origin server nginx strict transport security http response header strict transport security max age=15768000; includesubdomains transfer encoding http response header transfer encoding chunked vary http response header vary accept encoding x content type options http response header x content type options nosniff x frame options http response header x frame options sameorigin, sameorigin x xss protection http response header x xss protection 1; mode=block