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 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 notes https //docs virustotal com/reference/authentication 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 path parameters id string required job identifier input example {"path parameters" {"id" "12345678 1234 1234 1234 123456789abc"}} output parameter type description status code number http status code of the response reason string response reason phrase output example {} 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 optional malware hunting ruleset definition data type string required must be 'hunting ruleset' data attributes object required response data data attributes name string required name of the ruleset data attributes rules string required yara rules for the ruleset data attributes enabled boolean optional whether the ruleset is enabled data attributes limit number optional maximum number of notifications data attributes notification emails array optional list of emails to notify data attributes match object type string optional entity kind to match (file, url, domain, ip) input example {"data" {"type" "hunting ruleset","attributes" {"name" "example name","rules" "string","enabled"\ true,"limit" 123,"notification emails" \["string"],"match object type" "string"}}} 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 links self string output field links self data object response data data attributes object response data data attributes name string response data data attributes enabled boolean response data data attributes limit number response data data attributes creation date number response data data attributes modification date number response data data attributes number of rules number response data data attributes rules string response data data attributes notification emails array response data data attributes match object type string response data output example {"type" "hunting ruleset","id" "{id}","links" {"self" "https //www virustotal com/api/v3/intelligence/hunting ruleset/{id}"},"data" {"attributes" {"name" "foobar","enabled"\ true,"limit" 100,"creation date" 1521016318,"modification date" 1521016318,"number of rules" 1,"rules" "rule foobar { strings $ = \\"foobar\\" condition all of them }","notification emails" \[],"match object type" "file"}}} 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 optional retrohunt job definition data type string required must be 'retrohunt job' data attributes object required response data data attributes rules string required yara rules for the retrohunt job data attributes notification email string optional email to notify when the job is finished data attributes corpus string optional dataset to scan (main or goodware) data attributes time range object optional time range for scanning (unix timestamps) data attributes time range start number optional start timestamp (utc) data attributes time range end number optional end timestamp (utc) input example {"data" {"type" "retrohunt job","attributes" {"rules" "string","notification email" "string","corpus" "string","time range" {"start" 123,"end" 123}}}} 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 attributes status string status value attributes creation date number date value attributes finished date \['number', 'null'] date value attributes ruleset id string unique identifier attributes ruleset name string name of the resource attributes yara rule string output field attributes yara rule output example {"type" "retrohunt job","id" "1234567890abcdef","attributes" {"status" "running","creation date" 1626960086,"finished date"\ null,"ruleset id" "{ruleset id}","ruleset name" "my ruleset","yara rule" "rule foobar { strings $ = \\"foobar\\" condition all of them }"}} 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 path parameters id string required ruleset identifier input example {"path parameters" {"id" "12345678 1234 1234 1234 123456789abc"}} output parameter type description status code number http status code of the response reason string response reason phrase output example {} 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 path parameters id string required the id of the ioc stream notification input example {"path parameters" {"id" "12345678 1234 1234 1234 123456789abc"}} 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 attributes notification date number date value attributes origin string output field attributes origin attributes sources array output field attributes sources attributes sources type string type of the resource attributes sources id string unique identifier attributes tags array output field attributes tags attributes hunting info object output field attributes hunting info attributes hunting info rule name string name of the resource attributes hunting info rule tags array output field attributes hunting info rule tags attributes hunting info snippet string output field attributes hunting info snippet attributes hunting info source country string output field attributes hunting info source country attributes hunting info source key string output field attributes hunting info source key output example {"type" "ioc stream notification","id" "961092289288866 4582222113734656 3c7f77cc43338e14824c111671beef30","attributes" {"notification date" 1543301214,"origin" "hunting","sources" \[{}],"tags" \["rats","bozok"],"hunting info" {"rule name" "bozok","rule tags" \[],"snippet" "00 61 64 64 41 75 64 69 6f \[ ]","source country" "us","source key" "b3190c38"}}} 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 parameters limit integer optional number of objects to retrieve (max 40) parameters descriptors only boolean optional return only object descriptors instead of full vt objects parameters filter string optional filter string for ioc stream objects parameters cursor string optional continuation cursor for pagination parameters order string optional sort order (date for most recent first, date+ for oldest first) input example {"parameters" {"limit" 123,"descriptors only"\ true,"filter" "string","cursor" "string","order" "string"}} output parameter type description status code number http status code of the response reason string response reason phrase data array response data data type string response data data id string response data data attributes object response data data attributes notification id string response data data attributes notification date number response data data attributes origin string response data data attributes sources array response data data attributes sources type string response data data attributes sources id string response data data attributes tags array response data data attributes hunting info object response data data attributes hunting info rule name string response data data attributes hunting info rule tags array response data data attributes hunting info snippet string response data data attributes hunting info source country string response data data attributes hunting info source key string response data meta object output field meta meta cursor string output field meta cursor links object output field links links self string output field links self links next string output field links next output example {"data" \[{"type" "file","id" "{sha256}","attributes" {}}],"meta" {"cursor" "cu0fcsaccpic9xurl9v "},"links" {"self" "https //www virustotal com/api/v3/ioc stream","next" "https //www virustotal com/api/v3/ioc stream?cursor=cu0fcsaccpic9xurl9v "}} 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 parameters limit integer optional maximum number of notification files to retrieve parameters filter string optional filter files by notification properties (e g , rule name, ruleset, file hash) parameters cursor string optional continuation cursor for pagination parameters count limit integer optional maximum number of notification files counted (meta count in the response) 10,000 maximum input example {"parameters" {"limit" 123,"filter" "string","cursor" "string","count limit" 123}} output parameter type description status code number http status code of the response reason string response reason phrase data array response data data type string response data data id string response data data attributes object response data data attributes size number response data data attributes type description string response data data attributes context attributes object response data data attributes context attributes match in subfile boolean response data data attributes context attributes notification date number response data data attributes context attributes notification id string response data data attributes context attributes notification snippet string response data data attributes context attributes notification source key string response data data attributes context attributes notification tags array response data data attributes context attributes ruleset id string response data data attributes context attributes ruleset name string response data data attributes context attributes rule name string response data data attributes context attributes rule tags array response data meta object output field meta meta count number count value meta cursor string output field meta cursor links object output field links links self string output field links self links next string output field links next output example {"data" \[{"type" "file","id" "{sha256}","attributes" {}}],"meta" {"count" 1,"cursor" "cu0fcsaccpic9xurl9v "},"links" {"self" "https //www virustotal com/api/v3/intelligence/hunting notification files","next" "https //www virustotal com/api/v3/intelligence/hunting notification files?cursor "}} 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 parameters limit number optional maximum number of notifications to retrieve parameters filter string optional filter notifications by attribute (e g , tag, owner, date) parameters cursor string optional continuation cursor for pagination parameters count limit number optional maximum number of notifications counted (meta count in the response) input example {"parameters" {"limit" 10,"filter" "string","cursor" "string","count limit" 200}} output parameter type description status code number http status code of the response reason string response reason phrase data array response data data type string response data data id string response data data attributes object response data data attributes date number response data data attributes ruleset name string response data data attributes file sha256 string response data data attributes tags array response data data attributes owner string response data meta object output field meta meta count number count value meta cursor string output field meta cursor links object output field links links self string output field links self links next string output field links next output example {"data" \[{"type" "hunting notification","id" "{notification id}","attributes" {}}],"meta" {"count" 10,"cursor" "cu0fcsaccpic9xurl9v "},"links" {"self" "https //www virustotal com/api/v3/intelligence/hunting notifications","next" "https //www virustotal com/api/v3/intelligence/hunting notifications?cursor=cu0f "}} 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 parameters limit number optional maximum number of rulesets to retrieve parameters filter string optional filter rulesets by attribute parameters order string optional sort order parameters cursor string optional continuation cursor input example {"parameters" {"limit" 10,"filter" "string","order" "string","cursor" "string"}} output parameter type description status code number http status code of the response reason string response reason phrase data array response data data type string response data data id string response data data links object response data data links self string response data data attributes object response data data attributes creation date number response data data attributes enabled boolean response data data attributes limit number response data data attributes modification date number response data data attributes name string response data data attributes notification emails array response data data attributes notification emails file name string response data data attributes notification emails file string response data data attributes rules string response data meta object output field meta meta cursor string output field meta cursor links object output field links links self string output field links self links next string output field links next output example {"data" \[{"type" "hunting ruleset","id" "{id}","links" {},"attributes" {}}],"meta" {"cursor" "cu0fcsaccpic9xurl9v "},"links" {"self" "https //www virustotal com/api/v3/users/{user}/hunting rulesets","next" "https //www virustotal com/api/v3/users/{user}/hunting rulesets?cursor=cu0fcsacc "}} 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 path parameters id string required job identifier input example {"path parameters" {"id" "12345678 1234 1234 1234 123456789abc"}} 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 attributes status string status value attributes creation date number date value attributes finished date \['number', 'null'] date value attributes ruleset id string unique identifier attributes ruleset name string name of the resource attributes yara rule string output field attributes yara rule output example {"type" "retrohunt job","id" "1234567890abcdef","attributes" {"status" "running","creation date" 1626960086,"finished date"\ null,"ruleset id" "{ruleset id}","ruleset name" "my ruleset","yara rule" "rule my rule { condition true }"}} 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 path parameters id string required job identifier parameters limit integer optional maximum number of matching files to retrieve parameters cursor string optional continuation cursor for pagination input example {"path parameters" {"id" "12345678 1234 1234 1234 123456789abc"},"parameters" {"limit" 123,"cursor" "string"}} output parameter type description status code number http status code of the response reason string response reason phrase data array response data data type string response data data id string response data data attributes object response data data attributes size number response data data attributes type description string response data meta object output field meta meta cursor string output field meta cursor links object output field links links self string output field links self links next string output field links next output example {"data" \[{"type" "file","id" "{sha256}","attributes" {}}],"meta" {"cursor" "cu0fcsaccpic9xurl9v "},"links" {"self" "https //www virustotal com/api/v3/intelligence/retrohunt jobs/1234567890abcdef/m ","next" "https //www virustotal com/api/v3/intelligence/retrohunt jobs/1234567890abcdef/m "}} 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 parameters limit integer optional maximum number of jobs to retrieve parameters filter string optional filter jobs by status (e g , status \ running ) parameters cursor string optional continuation cursor for pagination input example {"parameters" {"limit" 123,"filter" "string","cursor" "string"}} output parameter type description status code number http status code of the response reason string response reason phrase data array response data data type string response data data id string response data data attributes object response data data attributes status string response data data attributes creation date number response data data attributes finished date \['number', 'null'] response data data attributes ruleset id string response data data attributes ruleset name string response data data attributes yara rule string response data meta object output field meta meta cursor string output field meta cursor links object output field links links self string output field links self links next string output field links next output example {"data" \[{"type" "retrohunt job","id" "{job id}","attributes" {}}],"meta" {"cursor" "cu0fcsaccpic9xurl9v "},"links" {"self" "https //www virustotal com/api/v3/intelligence/retrohunt jobs","next" "https //www virustotal com/api/v3/intelligence/retrohunt jobs?cursor=cu0fcsaccpi "}} 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