Dragos

the dragos connector enables seamless integration of dragos' industrial cybersecurity capabilities with the swimlane turbine platform, facilitating automated threat detection and response in ics and ot environments dragos specializes in industrial cybersecurity, providing a robust platform for asset identification, threat detection, and response within industrial control systems (ics) and operational technology (ot) environments the dragos turbine connector enables seamless integration with swimlane turbine, allowing users to automate incident response, manage cases, and enhance asset visibility by leveraging this connector, security teams can efficiently coordinate actions, streamline workflows, and bolster their cyber resilience against industrial threats prerequisites to utilize the dragos connector for turbine, ensure you have the following prerequisites http basic authentication with the following parameters url the endpoint url for the dragos api api key id your unique identifier used as the username for api access api secret key the secret key associated with your api key id, used as the password asset setup this connector requires following assets api key id api secret key id steps to generate the api key id and secret id in the dragos is as below login to dragos platform click + add new api key the generate new api key box expands in the name field, add the name of the api key being added, for example my external app click generate key, and a message box appears note this message box contains the updated name, the id, and the secret use the copy icon to copy the secret warning this is the only time the secret is displayed once this message box is closed, there is no way to retrieve the secret if the secret his lost, then the api key must be deleted and a new api key assigned click ok and the api key is configured capabilities this connector provides the following capabilities create note create zone delete note delete vulnerability detection rule delete zone fetch single case get a page of notifications get asset history events get assets get communications summary get notification details get page vulnerabilities get page vulnerability detection rules get page vulnerability detections get report data and so on configurations dragos api authentication authenticates using api key as username and api secret as password configuration parameters parameter description type required url a url to the target host string required username api key id string required password api secret key string required verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional actions create note add a note to an open case in dragos where the user is an admin, author, assignee, or watcher requires 'case id' and 'message' endpoint url /cases/cases/{{case id}}/notes method post input argument name type required description message string required response message case id number required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase id number unique identifier caseid number unique identifier generated boolean output field generated author string output field author message string response message referencetype object type of the resource referenceid object unique identifier createdat string output field createdat updatedat string output field updatedat example \[ { "status code" 200, "response headers" { "alt svc" "h3=\\" 443\\"; ma=2592000", "cache control" "max age=0, private, must revalidate", "content type" "application/json; charset=utf 8", "etag" "w/\\"b1a427116345f8a069b8a1640cada731\\"", "server" "caddy", "x content type options" "nosniff", "x frame options" "sameorigin", "x identity id" "61bf8f1c 2679 4e84 8c25 3ffa85b15099", "x privileges" "analytic\ read,asset\ map,asset\ read,asset\ write,auth\ identity\ read,baseline\ read, ", "x request id" "je1jvv 1vh13pp7fa21+acvcphqa kfhmz4s5mmwl=ypp4wvlqgjozl3regzx1aj", "x runtime" "0 025329", "x username" "tp7864", "x xss protection" "1; mode=block", "date" "wed, 28 feb 2024 05 45 37 gmt", "transfer encoding" "chunked" }, "reason" "ok", "json body" { "id" 17, "caseid" 1, "generated" false, "author" "tp7864", "message" "create note test for demo", "referencetype" null, "referenceid" null, "createdat" "2024 02 28t05 45 37 920z", "updatedat" "2024 02 28t05 45 37 920z" } } ] create zone initiates a new zone creation in dragos, triggering asset re zoning with the specified configuration endpoint url /assets/api/v4/createzone method post input argument name type required description headers object optional http headers for the request x username string optional username of requester not needed if accessing via gateway service x privileges string optional comma separated privilege ids of requester not needed if accessing via gateway service create object required parameter for create zone name string required name of the resource description string optional parameter for create zone colorhex string optional parameter for create zone criteria object required parameter for create zone idoroldidin array optional filters assets by ids (or old ids from pre merge) attributesmatches object optional filters assets by having attribute(s) with matching values property1 object optional parameter for create zone property2 object optional parameter for create zone addressselector object optional filters assets by address criteria idin array optional unique identifier typein array optional type of the resource networkidin array optional unique identifier collectorselector object optional parameter for create zone valuematches object optional value for the parameter anyof array optional parameter for create zone allof array optional parameter for create zone not object optional parameter for create zone associationtimerangeoverlaps object optional parameter for create zone createdatbefore string optional parameter for create zone createdatafter string optional response data lastseenatbefore string optional parameter for create zone output parameter type description status code number http status code of the response reason string response reason phrase id number unique identifier name string name of the resource description string output field description colorhex string output field colorhex criteria object output field criteria idoroldidin array unique identifier attributesmatches object output field attributesmatches property1 object output field property1 type string type of the resource property2 object output field property2 type string type of the resource addressselector object output field addressselector idin array unique identifier typein array type of the resource networkidin array unique identifier collectorselector object output field collectorselector customerid string unique identifier midpointid string unique identifier collectorid string unique identifier anyof array output field anyof allof array output field allof not object output field not valuematches object value for the parameter example \[ { "status code" 200, "response headers" {}, "reason" "success", "json body" { "id" 0, "name" "string", "description" "string", "colorhex" "#000000", "criteria" {}, "coordinates" {}, "grouplabel" "string", "metadata" {} } } ] delete note remove a specific note from an open case in dragos, given the correct case and note ids and appropriate user permissions endpoint url /cases/cases/{{case id}}/notes/{{note id}} method delete input argument name type required description case id number required unique identifier note id number required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" {} } ] delete vulnerability detection rule removes a specified vulnerability detection rule from dragos, requiring 'vulnerabilitydetectionruledelete' privilege endpoint url /vulnerabilities/api/v1/vulnerability/detection/rules/delete method post input argument name type required description headers object optional http headers for the request x username string optional username of requester not needed if accessing via gateway service x privileges string optional comma separated privilege ids of requester not needed if accessing via gateway service uuid string optional unique identifier output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 202, "response headers" {}, "reason" "accepted", "json body" {} } ] delete zone removes a specified zone from dragos, re zoning associated assets an 'id' for the zone is required endpoint url /assets/api/v4/deletezone method post input argument name type required description headers object optional http headers for the request x username string optional username of requester not needed if accessing via gateway service x privileges string optional comma separated privilege ids of requester not needed if accessing via gateway service id number required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase id number unique identifier name string name of the resource description string output field description colorhex string output field colorhex criteria object output field criteria idoroldidin array unique identifier attributesmatches object output field attributesmatches property1 object output field property1 type string type of the resource property2 object output field property2 type string type of the resource addressselector object output field addressselector idin array unique identifier typein array type of the resource networkidin array unique identifier collectorselector object output field collectorselector customerid string unique identifier midpointid string unique identifier collectorid string unique identifier anyof array output field anyof allof array output field allof not object output field not valuematches object value for the parameter example \[ { "status code" 200, "response headers" {}, "reason" "success", "json body" { "id" 0, "name" "string", "description" "string", "colorhex" "#000000", "criteria" {}, "coordinates" {}, "grouplabel" "string", "metadata" {} } } ] fetches a single case retrieves detailed information for a specific case in dragos using the provided case id, including notes, evidences, and tasks endpoint url /cases/cases/{{id}} method get input argument name type required description id number required case id output parameter type description status code number http status code of the response reason string response reason phrase id number unique identifier name string name of the resource hypothesis object output field hypothesis justification object output field justification visibility string output field visibility status string status value priority number output field priority incident boolean unique identifier creator string output field creator assignee object output field assignee createdat string output field createdat updatedat string output field updatedat notificationids array unique identifier file name string name of the resource file string output field file watchers string output field watchers evidences array unique identifier id number unique identifier caseid number unique identifier author string output field author datatype string response data data string response data notes array output field notes example \[ { "status code" 200, "response headers" { "alt svc" "h3=\\" 443\\"; ma=2592000", "cache control" "max age=0, private, must revalidate", "content type" "application/json; charset=utf 8", "etag" "w/\\"0b4e0bef532ca790db2dd6a24abaae68\\"", "server" "caddy", "x content type options" "nosniff", "x frame options" "sameorigin", "x identity id" "61bf8f1c 2679 4e84 8c25 3ffa85b15099", "x privileges" "analytic\ read,asset\ map,asset\ read,asset\ write,auth\ identity\ read,baseline\ read, ", "x request id" "o+ +fpuvbw1m4735can/9x5yni0g=3bq8026cg1w=3yk5mbncmj7ux uvjzfpyv+", "x runtime" "0 035914", "x username" "tp7864", "x xss protection" "1; mode=block", "date" "wed, 28 feb 2024 05 54 31 gmt", "transfer encoding" "chunked" }, "reason" "ok", "json body" { "id" 1, "name" "case2 updated twice", "hypothesis" null, "justification" null, "visibility" "private", "status" "open", "priority" 0, "incident" false, "creator" "tp7864", "assignee" null, "createdat" "2024 02 13t07 02 46 000z", "updatedat" "2024 02 14t07 02 10 000z", "notificationids" \[], "watchers" "", "evidences" \[] } } ] get a page of notifications retrieve a specific page of notifications from dragos, filtered according to user defined criteria endpoint url /notifications/api/v2/notification method get input argument name type required description pagenumber number optional parameter for get a page of notifications pagesize number optional parameter for get a page of notifications sorts string optional the format is comma separated sets of a sort field, colon, and 'a' (for ascending) or 'd' (for descending) sortfield string optional parameter for get a page of notifications sortdescending boolean optional parameter for get a page of notifications limittotalcount number optional count value filter string optional a filter string in fiql format see relevant information on fiql operators and notification selectors in doc resolvechildrendepth boolean optional number of steps deep to recursively resolve child notifications output parameter type description status code number http status code of the response headers object http headers for the request alt svc string output field alt svc content type string type of the resource server string output field server x identity id string unique identifier x privileges string output field x privileges x request id string unique identifier x username string name of the resource date string date value connection string output field connection transfer encoding string output field transfer encoding status reason string status value body object request body data pagenumber number output field pagenumber pagesize number output field pagesize sorts array output field sorts field string output field field descending boolean output field descending totalcount number count value totalpages number output field totalpages content array response content id number unique identifier assets array output field assets file name string name of the resource example \[ { "status code" 200, "headers" { "alt svc" "h3=\\" 443\\"; ma=2592000", "content type" "application/json; charset=utf 8", "server" "caddy", "x identity id" "61bf8f1c 2679 4e84 8c25 3ffa85b15099", "x privileges" "analytic\ read,asset\ map,asset\ read,asset\ write,auth\ identity\ read,baseline\ read, ", "x request id" "5k3wyzt=3sw1346h++pzgvf22arbqyqf996=1fmovm156=/3i0w12gnui072xfbj", "x username" "tp7864", "date" "wed, 28 feb 2024 14 26 20 gmt", "connection" "close", "transfer encoding" "chunked" }, "status reason" "ok", "body" { "pagenumber" 1, "pagesize" 10, "sorts" \[], "totalcount" 3, "totalpages" 1, "content" \[] } } ] get asset history events retrieve the historical events associated with a specific asset in dragos, requiring 'assetread' privilege endpoint url /assets/api/v4/getassethistoryevents method post input argument name type required description headers object optional http headers for the request x username string optional username of requester not needed if accessing via gateway service x privileges string optional comma separated privilege ids of requester not needed if accessing via gateway service selector object optional parameter for get asset history events assetidin array optional unique identifier timestampisorafter string optional parameter for get asset history events timestampisorbefore string optional parameter for get asset history events typein array optional type of the resource addressselector object optional parameter for get asset history events idin array optional unique identifier typein array optional type of the resource networkidin array optional unique identifier collectorselector object optional parameter for get asset history events customerid string optional unique identifier midpointid string optional unique identifier collectorid string optional unique identifier anyof array optional parameter for get asset history events allof array optional parameter for get asset history events not object optional parameter for get asset history events valuematches object optional value for the parameter type string optional type of the resource anyof array optional parameter for get asset history events allof array optional parameter for get asset history events not object optional parameter for get asset history events attributenamematches object optional name of the resource output parameter type description pagenumber number output field pagenumber pagesize number output field pagesize sorts array output field sorts file name string name of the resource file string output field file totalcount number count value totalpages number output field totalpages content array response content assetid number unique identifier timestamp string output field timestamp userid string unique identifier reason string response reason phrase resolutioncontext object output field resolutioncontext macsandips array output field macsandips addressid number unique identifier hostsanddomains array output field hostsanddomains file name string name of the resource file string output field file at string output field at type string type of the resource addressid number unique identifier addresscoordinates object output field addresscoordinates type string type of the resource networkid string unique identifier value string value for the parameter example \[ { "pagenumber" 1, "pagesize" 10, "sorts" \[], "totalcount" 284289, "totalpages" 28429, "content" \[ {}, {} ] } ] get assets retrieves a list of assets, addresses, and time ranges from dragos with 'assetread' privilege endpoint url /assets/api/v4/getassets method post input argument name type required description headers object optional http headers for the request x username string optional username of requester not needed if accessing via gateway service x privileges string optional comma separated privilege ids of requester not needed if accessing via gateway service selector object optional parameter for get assets idoroldidin array optional unique identifier attributesmatches object optional parameter for get assets property1 object optional parameter for get assets type string optional type of the resource property2 object optional parameter for get assets type string optional type of the resource addressselector object optional parameter for get assets idin array optional unique identifier typein array optional type of the resource networkidin array optional unique identifier collectorselector object optional parameter for get assets customerid string optional unique identifier midpointid string optional unique identifier collectorid string optional unique identifier anyof array optional parameter for get assets allof array optional parameter for get assets not object optional parameter for get assets valuematches object optional value for the parameter type string optional type of the resource anyof array optional parameter for get assets allof array optional parameter for get assets output parameter type description status code number http status code of the response reason string response reason phrase pagenumber number output field pagenumber pagesize number output field pagesize sortdescending boolean output field sortdescending totalcount number count value totalpages number output field totalpages totalcountexceededlimit boolean output field totalcountexceededlimit sorts array output field sorts field string output field field descending boolean output field descending content array response content id number unique identifier oldids array unique identifier attributes object output field attributes createdat string output field createdat lastseenat string output field lastseenat addresses array output field addresses type string type of the resource networkid string unique identifier value string value for the parameter id number unique identifier flags array output field flags collectors array output field collectors customerid string unique identifier example \[ { "status code" 200, "response headers" {}, "reason" "success", "json body" { "pagenumber" 0, "pagesize" 0, "sortdescending" true, "totalcount" 0, "totalpages" 0, "totalcountexceededlimit" true, "sorts" \[], "content" \[] } } ] get communications summary retrieve a summary of communications data from dragos, with optional filters for time based analysis endpoint url /maps/api/v1/getcommunicationssummary method post input argument name type required description headers object optional http headers for the request x username string optional username of requester not needed if accessing via gateway service x privileges string optional comma separated privilege ids of requester not needed if accessing via gateway service from string optional parameter for get communications summary to string optional parameter for get communications summary views array optional parameter for get communications summary output parameter type description status code number http status code of the response reason string response reason phrase from string output field from to string output field to bycollector array output field bycollector collector object output field collector customerid string unique identifier midpointid string unique identifier collectorid string unique identifier networkid string unique identifier protocolid string unique identifier zoneid number unique identifier addressescommunicatingwithnetworkids array unique identifier addressescommunicatingwithzoneids array unique identifier protocolids array unique identifier communicationsbytes number output field communicationsbytes communicationspackets number output field communicationspackets bynetworkid array unique identifier collector object output field collector customerid string unique identifier midpointid string unique identifier collectorid string unique identifier networkid string unique identifier protocolid string unique identifier zoneid number unique identifier example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "from" "2019 08 24t14 15 22z", "to" "2019 08 24t14 15 22z", "bycollector" \[], "bynetworkid" \[], "byprotocolid" \[], "byzoneid" \[], "total" {} } } ] get notification details retrieve detailed information for a specific dragos notification using the unique identifier provided in path parameters endpoint url /notifications/api/v2/notification/{{id}} method get input argument name type required description id number required id of the notification resolvechildrendepth number optional number of steps deep to recursively resolve child notifications includeconversations boolean optional whether conversations should be included with the notification, default is true output parameter type description status code number http status code of the response reason string response reason phrase id number unique identifier assets array output field assets file name string name of the resource file string output field file createdat string output field createdat matchedruleids array unique identifier file name string name of the resource file string output field file reviewed boolean output field reviewed retained boolean output field retained type string type of the resource detectionquads array output field detectionquads count number count value source string output field source summary string output field summary content string response content detectorid string unique identifier occurredat string output field occurredat severity number output field severity analyticeventid string unique identifier sourceindex string output field sourceindex sourceidfield string unique identifier sourceids array unique identifier example \[ { "status code" 200, "response headers" { "alt svc" "h3=\\" 443\\"; ma=2592000", "content type" "application/json; charset=utf 8", "server" "caddy", "x identity id" "61bf8f1c 2679 4e84 8c25 3ffa85b15099", "x privileges" "analytic\ read,asset\ map,asset\ read,asset\ write,auth\ identity\ read,baseline\ read, " }, "reason" "ok", "json body" { "id" 1, "assets" \[], "createdat" "2023 03 02t15 27 24z", "matchedruleids" \[], "reviewed" false, "retained" false, "type" "network analytic", "detectionquads" \[], "count" 1, "source" "network traffic", "summary" "arp scan", "content" "possible arp scan detected mac 00 0c 29\ ff 54 6c (vmware inc ) 10 20 0 30 sca ", "detectorid" "7205ebab ff5c 499b 9f87 f648e7b2f438", "occurredat" "2023 03 02t15 20 43z", "severity" 0 } } ] get page of vulnerabilities retrieve a paginated list of vulnerabilities from dragos, requiring the 'vulnerabilityread' privilege endpoint url /vulnerabilities/api/v1/vulnerability method post input argument name type required description headers object optional http headers for the request x username string optional username of requester not needed if accessing via gateway service x privileges string optional comma separated privilege ids of requester not needed if accessing via gateway service selector object optional parameter for get page of vulnerabilities idin array optional filters by id in list valuematches object optional filters by matching value type string required type of the resource field string required parameter for get page of vulnerabilities exact string required parameter for get page of vulnerabilities anyof array optional list of other selectors to combine as an or; only allowed if no other fields specified allof array optional list of other selectors to combine as an and; only allowed if no other fields specified pagination object optional parameter for get page of vulnerabilities pagenumber number optional parameter for get page of vulnerabilities pagesize number optional parameter for get page of vulnerabilities limittotalcount number optional an optional limit of total count to avoid counting large data sets sorts array optional parameter for get page of vulnerabilities output parameter type description status code number http status code of the response reason string response reason phrase pagenumber number output field pagenumber pagesize number output field pagesize totalcount number count value totalpages number output field totalpages content array response content @timestamp string output field @timestamp labels string output field labels message string response message tags string output field tags host object output field host observer object output field observer related object output field related threat object output field threat vulnerability object output field vulnerability example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "pagenumber" 0, "pagesize" 0, "totalcount" 0, "totalpages" 0, "content" \[] } } ] get page of vulnerability detection rules retrieve a specific page of vulnerability detection rules from dragos, requiring 'vulnerabilitydetectionruleread' privilege endpoint url /vulnerabilities/api/v1/vulnerability/detection/rules method post input argument name type required description headers object optional http headers for the request x username string optional username of requester not needed if accessing via gateway service x privileges string optional comma separated privilege ids of requester not needed if accessing via gateway service selector object optional parameter for get page of vulnerability detection rules idin array optional filters by id in list valuematches object optional filters by matching value type string optional type of the resource anyof array optional list of other selectors to combine as an or; only allowed if no other fields specified allof array optional list of other selectors to combine as an and; only allowed if no other fields specified pagination object optional parameter for get page of vulnerability detection rules pagenumber number optional parameter for get page of vulnerability detection rules pagesize number optional parameter for get page of vulnerability detection rules limittotalcount number optional an optional limit of total count to avoid counting large data sets sorts array optional parameter for get page of vulnerability detection rules output parameter type description status code number http status code of the response reason string response reason phrase pagenumber number output field pagenumber pagesize number output field pagesize totalcount number count value totalpages number output field totalpages content array response content selector object output field selector idin array unique identifier valuematches object filters by matching value type string type of the resource field string output field field exact string output field exact anyof array output field anyof allof array output field allof actions array output field actions type string type of the resource name string name of the resource description string output field description category string output field category license string output field license reference string output field reference expiration string output field expiration uuid string unique identifier author string output field author example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "pagenumber" 0, "pagesize" 0, "totalcount" 0, "totalpages" 0, "content" \[] } } ] get page vulnerability detections retrieve a page of vulnerability detection data from dragos, requiring 'vulnerabilitydetectionread' privilege endpoint url /vulnerabilities/api/v1/vulnerability/detection method post input argument name type required description headers object optional http headers for the request x username string optional username of requester not needed if accessing via gateway service x privileges string optional comma separated privilege ids of requester not needed if accessing via gateway service selector object optional parameter for get page vulnerability detections idin array optional filters by id in list valuematches object optional filters by matching value type string required type of the resource field string required parameter for get page vulnerability detections exact string required parameter for get page vulnerability detections anyof array optional list of other selectors to combine as an or; only allowed if no other fields specified allof array optional list of other selectors to combine as an and; only allowed if no other fields specified pagination object optional parameter for get page vulnerability detections pagenumber number optional parameter for get page vulnerability detections pagesize number optional parameter for get page vulnerability detections limittotalcount number optional an optional limit of total count to avoid counting large data sets sorts array optional parameter for get page vulnerability detections output parameter type description status code number http status code of the response reason string response reason phrase pagenumber number output field pagenumber pagesize number output field pagesize totalcount number count value totalpages number output field totalpages content array response content @timestamp string output field @timestamp labels string output field labels message string response message tags string output field tags observer object output field observer vulnerability object output field vulnerability hardware object output field hardware package object output field package os object output field os host object output field host event object output field event related object output field related example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "pagenumber" 0, "pagesize" 0, "totalcount" 0, "totalpages" 0, "content" \[] } } ] get report retrieves a specific dragos report using the 'reportid' from path parameters; 'report read' privilege needed endpoint url /reports/api/v2/report/{{reportid}} method get input argument name type required description reportid number required the report's id headers object required http headers for the request x username string required requester's identity x privileges string required requester's privileges output parameter type description status code number http status code of the response reason string response reason phrase id number unique identifier name string name of the resource description string output field description state string output field state failurereason string response reason phrase createdtime string time value generationstartedtime string time value generationcompletedtime string time value generationprogress number output field generationprogress type string type of the resource formats array output field formats files object output field files example \[ { "status code" 200, "response headers" {}, "reason" "success", "json body" { "id" 0, "name" "string", "description" "string", "state" "ready to generate", "failurereason" "string", "createdtime" "2019 08 24t14 15 22z", "generationstartedtime" "2019 08 24t14 15 22z", "generationcompletedtime" "2019 08 24t14 15 22z", "generationprogress" 0, "parameters" {}, "files" {} } } ] get report data retrieves specified report data from dragos using 'reportid' and 'format', ensuring 'report read' privilege and header parameters are set endpoint url /reports/api/v2/report/{{reportid}}/{{format}} method get input argument name type required description reportid string required the report's id format string required parameter for get report data headers object required http headers for the request x username string required requester's identity x privileges string required requester's privileges output parameter type description status code number http status code of the response reason string response reason phrase id number unique identifier name string name of the resource description string output field description state string output field state failurereason string response reason phrase createdtime string time value generationstartedtime string time value generationcompletedtime string time value generationprogress number output field generationprogress type string type of the resource formats array output field formats files object output field files property1 number output field property1 property2 number output field property2 example \[ { "status code" 200, "response headers" {}, "reason" "success", "json body" { "id" 0, "name" "string", "description" "string", "state" "ready to generate", "failurereason" "string", "createdtime" "2019 08 24t14 15 22z", "generationstartedtime" "2019 08 24t14 15 22z", "generationcompletedtime" "2019 08 24t14 15 22z", "generationprogress" 0, "parameters" {}, "files" {} } } ] get results from detector id retrieve detection results from dragos using a specified detector id endpoint url /analytics/analyticmetadata/{{detector id}} method get input argument name type required description detector id string required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase display name string name of the resource engine string output field engine description string output field description silent boolean output field silent type string type of the resource id string unique identifier metadata object response data detection quad array output field detection quad kill chain array output field kill chain attack tactic array output field attack tactic attack technique array output field attack technique date source array output field date source purdue layer array output field purdue layer intelligence report array output field intelligence report activity group array output field activity group tool array output field tool asset type array type of the resource vendor array output field vendor protocols array output field protocols notifications array output field notifications summary string output field summary message string response message example \[ { "status code" 200, "response headers" { "alt svc" "h3=\\" 443\\"; ma=2592000", "content type" "application/json; charset=utf 8", "server" "caddy", "x identity id" "61bf8f1c 2679 4e84 8c25 3ffa85b15099", "x privileges" "analytic\ read,asset\ map,asset\ read,asset\ write,auth\ identity\ read,baseline\ read, " }, "reason" "ok", "json body" { "display name" "arp scan", "engine" "bro", "description" "arp scanning can be use to discover live hosts ", "silent" false, "type" "detection", "id" "1bf8f1c 2679 4e84 8c25 3ffa85b15099", "metadata" {} } } ] get snapshot retrieves metadata and data for a specified snapshot in dragos, requiring 'assetsnapshotread' privilege endpoint url /maps/api/v1/getsnapshot method post input argument name type required description headers object optional http headers for the request x username string optional username of requester not needed if accessing via gateway service x privileges string optional comma separated privilege ids of requester not needed if accessing via gateway service id number required id of the snapshot to get view object optional parameter for get snapshot type string optional type of the resource fetchfreshassetattributes boolean optional whether to pull fresh asset attributes from ais output parameter type description status code number http status code of the response reason string response reason phrase metadata object response data id number unique identifier generationfilter object output field generationfilter assetselector object output field assetselector id object unique identifier createdat object output field createdat lastseenat object output field lastseenat attributes object output field attributes property1 object output field property1 property2 object output field property2 address object output field address id object unique identifier type object type of the resource networkid object unique identifier value object value for the parameter collector object output field collector anyof array output field anyof allof array output field allof anyof array output field anyof allof array output field allof communicationsselector object output field communicationsselector addressid object unique identifier originatorports object output field originatorports example \[ { "status code" 200, "response headers" { "content type" "application/json", "date" "thu, 01 jan 2024 00 00 00 gmt" }, "reason" "ok", "json body" { "metadata" {}, "view" {} } } ] get snapshot metadata retrieves metadata for a specified snapshot in dragos using the 'id', requiring 'assetsnapshotread' privilege endpoint url /maps/api/v1/getsnapshotmetadata method post input argument name type required description headers object optional http headers for the request x username string optional username of requester not needed if accessing via gateway service x privileges string optional comma separated privilege ids of requester not needed if accessing via gateway service id number required id of the snapshot to get output parameter type description status code number http status code of the response reason string response reason phrase id number unique identifier generationfilter object output field generationfilter assetselector object output field assetselector id object unique identifier createdat object output field createdat lastseenat object output field lastseenat attributes object output field attributes address object output field address anyof array output field anyof allof array output field allof communicationsselector object output field communicationsselector addressid object unique identifier originatorports object output field originatorports responderports object output field responderports protocolid object unique identifier ipprotocolid object unique identifier bytes object output field bytes packets object output field packets anyof array output field anyof allof array output field allof limitassetcount number count value bins array output field bins id number unique identifier example \[ { "status code" 200, "response headers" { "content type" "application/json", "date" "thu, 01 jan 2024 00 00 00 gmt" }, "reason" "ok", "json body" { "id" 123, "generationfilter" {}, "bins" \[], "frommin" "string", "tomax" "string", "composite" true, "ephemeral" true, "retention" {}, "createdat" "string", "state" "string", "statechangedat" "string", "metrics" {} } } ] get snapshot metadata page retrieves a page of snapshot metadata from dragos, requiring 'assetsnapshotread' privilege for access endpoint url /maps/api/v1/getsnapshotmetadatapage method post input argument name type required description headers object optional http headers for the request x username string optional username of requester not needed if accessing via gateway service x privileges string optional comma separated privilege ids of requester not needed if accessing via gateway service selector object optional parameter for get snapshot metadata page pagination object optional parameter for get snapshot metadata page pagenumber number optional parameter for get snapshot metadata page pagesize number optional parameter for get snapshot metadata page sortdescending boolean optional parameter for get snapshot metadata page sortfield string optional parameter for get snapshot metadata page output parameter type description status code number http status code of the response reason string response reason phrase pagenumber number output field pagenumber pagesize number output field pagesize sortdescending boolean output field sortdescending totalcount number count value totalpages number output field totalpages sortfield string output field sortfield content array response content id number unique identifier generationfilter object output field generationfilter assetselector object output field assetselector id object unique identifier createdat object output field createdat lastseenat object output field lastseenat attributes object output field attributes address object output field address anyof array output field anyof allof array output field allof communicationsselector object output field communicationsselector limitassetcount number count value bins array output field bins id number unique identifier from string output field from to string output field to example \[ { "status code" 200, "response headers" { "content type" "application/json", "date" "thu, 01 jan 2024 00 00 00 gmt" }, "reason" "ok", "json body" { "pagenumber" 123, "pagesize" 123, "sortdescending" true, "totalcount" 123, "totalpages" 123, "sortfield" "string", "content" \[] } } ] get zones retrieve a comprehensive list of zones from dragos, detailing attributes and status for each zone endpoint url /assets/api/v4/getzones method post input argument name type required description headers object optional http headers for the request x username string optional username of requester not needed if accessing via gateway service x privileges string optional comma separated privilege ids of requester not needed if accessing via gateway service output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" {}, "reason" "success", "json body" \[ {} ] } ] list evidences from case retrieve evidence items from a specific case in dragos, requiring the case id and accessible by permitted roles endpoint url /cases/cases/{{case id}}/evidences method get input argument name type required description case id number required case id output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "alt svc" "h3=\\" 443\\"; ma=2592000", "cache control" "max age=0, private, must revalidate", "content type" "application/json; charset=utf 8", "etag" "w/\\"49d28362723562024cd4c788aab9b05d\\"", "server" "caddy", "x content type options" "nosniff", "x frame options" "sameorigin", "x identity id" "61bf8f1c 2679 4e84 8c25 3ffa85b15099", "x privileges" "analytic\ read,asset\ map,asset\ read,asset\ write,auth\ identity\ read,baseline\ read, ", "x request id" "8niq8z7/thwtw3nv82q4//odh2k3xre25bfrp9e/qjwexfyeq4cmwluib7um/u==", "x runtime" "0 017550", "x username" "tp7864", "x xss protection" "1; mode=block", "date" "wed, 28 feb 2024 05 52 05 gmt", "transfer encoding" "chunked" }, "reason" "ok", "json body" \[ {} ] } ] list notes from a case retrieve all notes associated with a given case id in dragos for users with specific privileges endpoint url /cases/cases/{{case id}}/notes method get input argument name type required description case id number required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "alt svc" "h3=\\" 443\\"; ma=2592000", "cache control" "max age=0, private, must revalidate", "content type" "application/json; charset=utf 8", "etag" "w/\\"465c975a3297a25173d3c2b284f638c0\\"", "server" "caddy", "x content type options" "nosniff", "x frame options" "sameorigin", "x identity id" "61bf8f1c 2679 4e84 8c25 3ffa85b15099", "x privileges" "analytic\ read,asset\ map,asset\ read,asset\ write,auth\ identity\ read,baseline\ read, ", "x request id" "5vyck6pw0g g7+6tfrp mj5wxeijz4zxrn =t+lw1ai1+=//pr z742ijbkdv28v", "x runtime" "0 027900", "x username" "tp7864", "x xss protection" "1; mode=block", "date" "wed, 28 feb 2024 05 50 25 gmt", "transfer encoding" "chunked" }, "reason" "ok", "json body" \[ {}, {} ] } ] list report retrieves a paginated list of reports from dragos, requiring 'report read' privilege for access includes necessary headers endpoint url /reports/api/v2/report method get input argument name type required description pagenumber number optional parameter for list report pagesize number optional parameter for list report sortdescending boolean optional parameter for list report sortfield string optional parameter for list report includeid array optional unique identifier excludeid array optional unique identifier includetype array optional type of the resource excludetype array optional type of the resource includestate array optional parameter for list report excludestate array optional parameter for list report createdtimeatorafter string optional parameter for list report createdtimeatorbefore string optional parameter for list report generationstartedtimeatorafter string optional parameter for list report generationstartedtimeatorbefore string optional parameter for list report generationcompletedtimeatorafter string optional parameter for list report generationcompletedtimeatorbefore string optional parameter for list report headers object required http headers for the request x username string required requester's identity x privileges string required requester's privileges output parameter type description status code number http status code of the response reason string response reason phrase pagenumber number output field pagenumber pagesize number output field pagesize sorts array output field sorts descending boolean output field descending field string output field field totalcount number count value totalpages number output field totalpages content array response content id number unique identifier name string name of the resource description string output field description state string output field state failurereason string response reason phrase createdtime string time value generationstartedtime string time value generationcompletedtime string time value generationprogress number output field generationprogress type string type of the resource formats array output field formats files object output field files property1 number output field property1 property2 number output field property2 example \[ { "status code" 200, "response headers" {}, "reason" "success", "json body" { "pagenumber" 1, "pagesize" 1, "sorts" \[], "totalcount" 0, "totalpages" 0, "content" \[] } } ] update case updates specific attributes of a dragos case for admins, assignees, or creators using the 'id' path parameter endpoint url /cases/cases/{{id}} method patch input argument name type required description id number required case id name string optional name hypothesis string optional hypothesis for case justification string optional justification priority number optional priority level (0 is the lowest) notificationids array optional notification ids are comma separated string or array of integers output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" {} } ] update note updates a note for an open case in dragos, requiring message content along with note and case identifiers endpoint url /cases/cases/{{case id}}/notes/{{id}} method patch input argument name type required description case id number required unique identifier id number required note id message string required message output parameter type description status code number http status code of the response headers object http headers for the request alt svc string output field alt svc cache control string output field cache control content type string type of the resource etag string output field etag server string output field server x content type options string type of the resource x frame options string output field x frame options x identity id string unique identifier x privileges string output field x privileges x request id string unique identifier x runtime string time value x username string name of the resource x xss protection string output field x xss protection date string date value connection string output field connection transfer encoding string output field transfer encoding status reason string status value body object request body data id number unique identifier caseid number unique identifier generated boolean output field generated author string output field author message string response message example \[ { "status code" 200, "headers" { "alt svc" "h3=\\" 443\\"; ma=2592000", "cache control" "max age=0, private, must revalidate", "content type" "application/json; charset=utf 8", "etag" "w/\\"aaba14bd2f6d36cda98410747ea0255f\\"", "server" "caddy", "x content type options" "nosniff", "x frame options" "sameorigin", "x identity id" "61bf8f1c 2679 4e84 8c25 3ffa85b15099", "x privileges" "analytic\ read,asset\ map,asset\ read,asset\ write,auth\ identity\ read,baseline\ read, ", "x request id" "p+8czg0kzgj9cd=nx9 xi/c//5g97q719ygpmv13nc38b/sf +3i/jn4yl2xmsog", "x runtime" "0 044061", "x username" "tp7864", "x xss protection" "1; mode=block", "date" "wed, 28 feb 2024 05 48 22 gmt", "connection" "close" }, "status reason" "ok", "body" { "id" 7, "caseid" 2, "generated" false, "author" "tp7864", "message" "update note for case", "referencetype" null, "referenceid" null, "createdat" "2024 02 13t07 17 05 000z", "updatedat" "2024 02 28t05 48 22 971z" } } ] update vulnerability detection rule updates an existing vulnerability detection rule in dragos platform using a unique identifier (uuid) requires 'vulnerabilitydetectionruleupdate' privilege endpoint url /vulnerabilities/api/v1/vulnerability/detection/rules/update method post input argument name type required description headers object optional http headers for the request x username string optional username of requester not needed if accessing via gateway service x privileges string optional comma separated privilege ids of requester not needed if accessing via gateway service selector object optional parameter for update vulnerability detection rule idin array optional unique identifier valuematches object optional value for the parameter type string required type of the resource field string required parameter for update vulnerability detection rule anyof array optional list of other selectors to combine as an or; only allowed if no other fields specified allof array optional list of other selectors to combine as an and; only allowed if no other fields specified actions array optional parameter for update vulnerability detection rule type string required type of the resource risk number optional parameter for update vulnerability detection rule name string optional name of the resource description string optional parameter for update vulnerability detection rule category string optional parameter for update vulnerability detection rule license string optional parameter for update vulnerability detection rule reference string optional parameter for update vulnerability detection rule expiration string optional parameter for update vulnerability detection rule uuid string required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase selector object output field selector idin array unique identifier valuematches object value for the parameter type string type of the resource anyof array output field anyof allof array output field allof actions array output field actions type string type of the resource name string name of the resource description string output field description category string output field category license string output field license reference string output field reference expiration string output field expiration uuid string unique identifier author string output field author lastmodifiedby string output field lastmodifiedby lastmodifiedat string output field lastmodifiedat createdat string output field createdat version number output field version example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "selector" {}, "actions" \[], "name" "string", "description" "string", "category" "string", "license" "string", "reference" "string", "expiration" "2019 08 24", "uuid" "string", "author" "string", "lastmodifiedby" "string", "lastmodifiedat" "2019 08 24t14 15 22z", "createdat" "2019 08 24t14 15 22z", "version" 0 } } ] update zone updates a zone's attributes in dragos, including name, description, color, and criteria, triggering asset re zoning endpoint url /assets/api/v4/updatezone method post input argument name type required description headers object optional http headers for the request x username string optional name of the resource x privileges string optional parameter for update zone id number required unique identifier update object required date value name string optional name of the resource description string required parameter for update zone colorhex string optional parameter for update zone criteria object optional parameter for update zone idoroldidin array optional unique identifier attributesmatches object optional parameter for update zone property1 object optional parameter for update zone property2 object optional parameter for update zone addressselector object optional parameter for update zone idin array optional unique identifier typein array optional type of the resource networkidin array optional unique identifier collectorselector object optional parameter for update zone valuematches object optional value for the parameter anyof array optional parameter for update zone allof array optional parameter for update zone not object optional parameter for update zone associationtimerangeoverlaps object optional parameter for update zone createdatbefore string optional parameter for update zone createdatafter string optional response data output parameter type description status code number http status code of the response reason string response reason phrase id number unique identifier name string name of the resource description string output field description colorhex string output field colorhex criteria object output field criteria idoroldidin array unique identifier attributesmatches object output field attributesmatches property1 object output field property1 type string type of the resource property2 object output field property2 type string type of the resource addressselector object output field addressselector idin array unique identifier typein array type of the resource networkidin array unique identifier collectorselector object output field collectorselector customerid string unique identifier midpointid string unique identifier collectorid string unique identifier anyof array output field anyof allof array output field allof not object output field not valuematches object value for the parameter example \[ { "status code" 200, "response headers" {}, "reason" "success", "json body" { "id" 0, "name" "string", "description" "string", "colorhex" "#000000", "criteria" {}, "coordinates" {}, "grouplabel" "string", "metadata" {} } } ] response headers header description example alt svc http response header alt svc h3=" 443 "; ma=2592000 cache control directives for caching mechanisms max age=0, private, must revalidate content type the media type of the resource application/json; charset=utf 8 date the date and time at which the message was originated wed, 28 feb 2024 05 52 05 gmt etag an identifier for a specific version of a resource w/"b1a427116345f8a069b8a1640cada731" server information about the software used by the origin server caddy transfer encoding http response header transfer encoding chunked x content type options http response header x content type options nosniff x frame options http response header x frame options sameorigin x identity id http response header x identity id 61bf8f1c 2679 4e84 8c25 3ffa85b15099 x privileges http response header x privileges analytic \ read ,asset \ map ,asset \ read ,asset \ write ,auth\ identity \ read ,baseline \ read ,baseline \ update ,case \ create ,case \ read ,file \ upload ,network \ read ,notification \ read ,notification\ rule \ read ,notification \ update ,playbook \ create ,playbook \ read ,report \ read ,report \ write ,sensor \ read ,tasking\ capture \ create ,tasking \ read ,vulnerability\ log \ read ,vulnerability \ read ,vulnerability\ rule \ read x request id a unique identifier for the request 8niq8z7/thwtw3nv82q4//odh2k3xre25bfrp9e/qjwexfyeq4cmwluib7um/u== x runtime http response header x runtime 0 035914 x username http response header x username tp7864 x xss protection http response header x xss protection 1; mode=block notes notificationread permission allow reading of notifications(not including system notifications) notificationsystemtype permission allow reading of system notifications to get detector id in action get results from detector id , run action get notification details