Virustotal Hunting

the virustotal hunting connector enables automated threat hunting and intelligence gathering from the extensive virustotal database virustotal hunting is a powerful threat intelligence and hunting service that allows security professionals to search for and detect malware and other threats within their digital environment this connector enables swimlane turbine users to integrate with virustotal hunting's api, providing the ability to create, manage, and analyze livehunt and retrohunt jobs, as well as retrieve notifications and file matches by leveraging this integration, users can automate the threat detection process, streamline incident response, and enhance their overall security posture with up to date threat intelligence limitations none to date supported version this connector supports the virustotal hunting api v3 configuration prerequisites to effectively utilize the virustotal hunting connector within swimlane turbine, ensure you have the following prerequisites api key authentication url endpoint url for the virustotal hunting api api key your personal api key provided by virustotal public key in order to get the api key, you must first register with the virustotal community by going here https //www virustotal com/gui/sign in then click new? join the community provide a name, email, username, and password once complete, click join us an activation link will be sent to the email you provided click on the activation link to activate your virustotal community membership return to the virustotal homepage and click the blue message icon on the lower right hand corner of the homepage this will bring up the virustotal bot window click the option, i have a feed of new files that i can upload, i want free api quota to do so a window opens where you can create a message to virustotal complete the subject and email fields and then include a simple message stating why you need a free api key once virustotal reviews your message, you can sign into your account and find your public api in the corresponding menu item, api key, under your username premium key login to your account click your username and then click api key click request premium api key fill out the request prompt on this page required fields include "company size", "company country", and "already paying customer?" virus total will respond to your request asset setup the asset requires an api key to use if your organization requires the use of a proxy, then that proxy can be used during the asset setup the public api is limited to 500 requests per day and a rate of 4 requests per minute must not be used in commercial products or services must not be used in business workflows that do not contribute new files capabilities abort retrohunt job create livehunt ruleset create retrohunt job delete livehunt ruleset get livehunt notification files get livehunt notifications get livehunt rulesets get retrohunt job get retrohunt jobs get an ioc stream notification get objects from the ioc stream retrieve matches for a retrohunt job configurations virustotal hunting api key authentication authenticates using an api key configuration parameters parameter description type required url a url to the target host string required x apikey api key string required verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional actions abort retrohunt job aborts a specified retrohunt job in virustotal hunting using the provided job id endpoint url /api/v3/intelligence/retrohunt jobs/{{id}}/abort method post input argument name type required description id string required job 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" { "content type" "application/json", "date" "thu, 01 jan 2024 00 00 00 gmt" }, "reason" "ok", "json body" {} } ] create livehunt ruleset create a new virustotal hunting livehunt ruleset using specified data attributes provided in the json body endpoint url /api/v3/intelligence/hunting rulesets method post input argument name type required description data object required malware hunting ruleset definition type string required must be 'hunting ruleset' attributes object required parameter for create livehunt ruleset name string required name of the ruleset rules string required yara rules for the ruleset enabled boolean optional whether the ruleset is enabled limit number optional maximum number of notifications notification emails array optional list of emails to notify match object type string optional entity kind to match (file, url, domain, ip) output parameter type description status code number http status code of the response reason string response reason phrase type string type of the resource id string unique identifier links object output field links self string output field self data object response data attributes object output field attributes name string name of the resource enabled boolean output field enabled limit number output field limit creation date number date value modification date number date value number of rules number output field number of rules rules string output field rules notification emails array output field notification emails match object type string type of the resource example \[ { "status code" 200, "response headers" { "content type" "application/json", "date" "thu, 01 jan 2024 00 00 00 gmt" }, "reason" "ok", "json body" { "type" "string", "id" "12345678 1234 1234 1234 123456789abc", "links" {}, "data" {} } } ] create retrohunt job initiates a new retrohunt job in virustotal using yara rules, requiring specific data parameters endpoint url /api/v3/intelligence/retrohunt jobs method post input argument name type required description data object required retrohunt job definition type string required must be 'retrohunt job' attributes object required parameter for create retrohunt job rules string required yara rules for the retrohunt job notification email string optional email to notify when the job is finished corpus string optional dataset to scan (main or goodware) time range object optional time range for scanning (unix timestamps) start number optional start timestamp (utc) end number optional end timestamp (utc) output parameter type description status code number http status code of the response reason string response reason phrase type string type of the resource id string unique identifier attributes object output field attributes status string status value creation date number date value finished date \['number', 'null'] date value ruleset id string unique identifier ruleset name string name of the resource yara rule string output field yara rule example \[ { "status code" 200, "response headers" { "content type" "application/json", "date" "thu, 01 jan 2024 00 00 00 gmt" }, "reason" "ok", "json body" { "type" "string", "id" "12345678 1234 1234 1234 123456789abc", "attributes" {} } } ] delete livehunt ruleset removes a specified virustotal hunting livehunt ruleset using its unique identifier endpoint url /api/v3/intelligence/hunting rulesets/{{id}} method delete input argument name type required description id string required ruleset 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" { "content type" "application/json", "date" "thu, 01 jan 2024 00 00 00 gmt" }, "reason" "ok", "json body" {} } ] get an ioc stream notification retrieve a specific indicator of compromise (ioc) stream notification by its id from virustotal hunting endpoint url /api/v3/ioc stream notifications/{{id}} method get input argument name type required description id string required the id of the ioc stream notification output parameter type description status code number http status code of the response reason string response reason phrase type string type of the resource id string unique identifier attributes object output field attributes notification date number date value origin string output field origin sources array output field sources type string type of the resource id string unique identifier tags array output field tags hunting info object output field hunting info rule name string name of the resource rule tags array output field rule tags snippet string output field snippet source country string output field source country source key string output field source key example \[ { "status code" 200, "response headers" { "content type" "application/json", "date" "thu, 01 jan 2024 00 00 00 gmt" }, "reason" "ok", "json body" { "type" "string", "id" "12345678 1234 1234 1234 123456789abc", "attributes" {} } } ] get objects from the ioc stream retrieve filtered objects from the virustotal hunting ioc stream endpoint with support for ordering and pagination endpoint url /api/v3/ioc stream method get input argument name type required description limit integer optional number of objects to retrieve (max 40) descriptors only boolean optional return only object descriptors instead of full vt objects filter string optional filter string for ioc stream objects cursor string optional continuation cursor for pagination order string optional sort order (date for most recent first, date+ for oldest first) output parameter type description status code number http status code of the response reason string response reason phrase data array response data type string type of the resource id string unique identifier attributes object output field attributes notification id string unique identifier notification date number date value origin string output field origin sources array output field sources type string type of the resource id string unique identifier tags array output field tags hunting info object output field hunting info rule name string name of the resource rule tags array output field rule tags snippet string output field snippet source country string output field source country source key string output field source key meta object output field meta cursor string output field cursor links object output field links self string output field self next string output field next example \[ { "status code" 200, "response headers" { "content type" "application/json", "date" "thu, 01 jan 2024 00 00 00 gmt" }, "reason" "ok", "json body" { "data" \[], "meta" {}, "links" {} } } ] get livehunt notification files retrieve file objects and context attributes related to virustotal hunting livehunt notification matches endpoint url /api/v3/intelligence/hunting notification files method get input argument name type required description limit integer optional maximum number of notification files to retrieve filter string optional filter files by notification properties (e g , rule name, ruleset, file hash) cursor string optional continuation cursor for pagination count limit integer optional maximum number of notification files counted (meta count in the response) 10,000 maximum output parameter type description status code number http status code of the response reason string response reason phrase data array response data type string type of the resource id string unique identifier attributes object output field attributes size number output field size type description string type of the resource context attributes object output field context attributes match in subfile boolean output field match in subfile notification date number date value notification id string unique identifier notification snippet string output field notification snippet notification source key string output field notification source key notification tags array output field notification tags ruleset id string unique identifier ruleset name string name of the resource rule name string name of the resource rule tags array output field rule tags meta object output field meta count number count value cursor string output field cursor links object output field links self string output field self next string output field next example \[ { "status code" 200, "response headers" { "content type" "application/json", "date" "thu, 01 jan 2024 00 00 00 gmt" }, "reason" "ok", "json body" { "data" \[], "meta" {}, "links" {} } } ] get livehunt notifications retrieve notifications from virustotal hunting livehunt triggered by user defined or shared rulesets endpoint url /api/v3/intelligence/hunting notifications method get input argument name type required description limit number optional maximum number of notifications to retrieve filter string optional filter notifications by attribute (e g , tag, owner, date) cursor string optional continuation cursor for pagination count limit number optional maximum number of notifications counted (meta count in the response) output parameter type description status code number http status code of the response reason string response reason phrase data array response data type string type of the resource id string unique identifier attributes object output field attributes date number date value ruleset name string name of the resource file sha256 string output field file sha256 tags array output field tags owner string output field owner meta object output field meta count number count value cursor string output field cursor links object output field links self string output field self next string output field next example \[ { "status code" 200, "response headers" { "content type" "application/json", "date" "thu, 01 jan 2024 00 00 00 gmt" }, "reason" "ok", "json body" { "data" \[], "meta" {}, "links" {} } } ] get livehunt rulesets obtain virustotal hunting livehunt rulesets with details and sharing information accessible to the user endpoint url /api/v3/intelligence/hunting rulesets method get input argument name type required description limit number optional maximum number of rulesets to retrieve filter string optional filter rulesets by attribute order string optional sort order cursor string optional continuation cursor output parameter type description status code number http status code of the response reason string response reason phrase data array response data type string type of the resource id string unique identifier links object output field links self string output field self attributes object output field attributes creation date number date value enabled boolean output field enabled limit number output field limit modification date number date value name string name of the resource notification emails array output field notification emails file name string name of the resource file string output field file rules string output field rules meta object output field meta cursor string output field cursor links object output field links self string output field self next string output field next example \[ { "status code" 200, "response headers" { "content type" "application/json", "date" "thu, 01 jan 2024 00 00 00 gmt" }, "reason" "ok", "json body" { "data" \[], "meta" {}, "links" {} } } ] get retrohunt job retrieve details of a specific retrohunt job in virustotal hunting using the provided job id endpoint url /api/v3/intelligence/retrohunt jobs/{{id}} method get input argument name type required description id string required job identifier output parameter type description status code number http status code of the response reason string response reason phrase type string type of the resource id string unique identifier attributes object output field attributes status string status value creation date number date value finished date \['number', 'null'] date value ruleset id string unique identifier ruleset name string name of the resource yara rule string output field yara rule example \[ { "status code" 200, "response headers" { "content type" "application/json", "date" "thu, 01 jan 2024 00 00 00 gmt" }, "reason" "ok", "json body" { "type" "string", "id" "12345678 1234 1234 1234 123456789abc", "attributes" {} } } ] retrieve matches for a retrohunt job retrieve files matching a specific virustotal hunting retrohunt job using the provided job id, with pagination endpoint url /api/v3/intelligence/retrohunt jobs/{{id}}/matching files method get input argument name type required description id string required job identifier limit integer optional maximum number of matching files to retrieve cursor string optional continuation cursor for pagination output parameter type description status code number http status code of the response reason string response reason phrase data array response data type string type of the resource id string unique identifier attributes object output field attributes size number output field size type description string type of the resource meta object output field meta cursor string output field cursor links object output field links self string output field self next string output field next example \[ { "status code" 200, "response headers" { "content type" "application/json", "date" "thu, 01 jan 2024 00 00 00 gmt" }, "reason" "ok", "json body" { "data" \[], "meta" {}, "links" {} } } ] get retrohunt jobs retrieve a list of retrohunt job objects from virustotal, optionally filtered by job status endpoint url /api/v3/intelligence/retrohunt jobs method get input argument name type required description limit integer optional maximum number of jobs to retrieve filter string optional filter jobs by status (e g , status \ running ) cursor string optional continuation cursor for pagination output parameter type description status code number http status code of the response reason string response reason phrase data array response data type string type of the resource id string unique identifier attributes object output field attributes status string status value creation date number date value finished date \['number', 'null'] date value ruleset id string unique identifier ruleset name string name of the resource yara rule string output field yara rule meta object output field meta cursor string output field cursor links object output field links self string output field self next string output field next example \[ { "status code" 200, "response headers" { "content type" "application/json", "date" "thu, 01 jan 2024 00 00 00 gmt" }, "reason" "ok", "json body" { "data" \[], "meta" {}, "links" {} } } ] 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 notes virustotal hunting api documentation https //docs virustotal com/reference/authentication