jisu82/Nexus_Function_Calling_Leaderboard
0
1 2# The natural language descriptions of different APIs3api_descriptions = {4"Climate": "The Climate API, provided by the National Climatic Data Center (NCDC), offers access to a comprehensive database of weather and climate data, catering to developers who want to create custom scripts or programs. The API allows up to five requests per second and a maximum of 10,000 requests per day.",5"Heldout_Combined": "This dataset is obtained from the stack (BigCode). The stack is primarily used as a pre-training dataset for Code LLMs, aiding in tasks like code completion from natural language, documentation generation, and auto-completion of code snippets. \n\n Note that due to specific policies, the stack data are not publicly available yet, so we didn't provide examples here. Thanks for your understanding!\n\n**Due to the complexity in converting the pythonic representation into a JSON representation [As each sample has unique API definition format and hundreds across the dataset, which is unlike other tasks where all samples shares the same function list which we manually converted], we did not have a chance to benchmark Gorilla Open Function V1 on the Stack API dataset. However, we manually converted a few randomly chosen samples and we observe the relative performance of Gorilla here is similar to Gorilla's relative performance on other tasks.",6"Places_API": "The Places API by Google, part of the Google Maps Platform, offers detailed information about over 200 million places worldwide, including ratings, reviews, and business data. It enhances user experience by providing features like accessibility information, special and secondary opening hours, editorial summaries, detailed dining and shopping service attributes, and the ability to sort and auto-translate reviews.",7"VT_Multi_Dependency": "Built on top of the VirusTotal (VT) dataset, we added 17 supplementary APIs to achieve more advanced functionalities. Multi_Dependency means that in order to fulfill the task requested by user's query, the model needs to call multiple apis, where some apis rely on the results of other apis.",8"VT_Multi_Disconnected": "Built on top of the VirusTotal (VT) dataset, we added 17 supplementary APIs to achieve more advanced functionalites. Disconnected means that in order to fultill the task requested by the user's query, the model needs to call multiple apis, where the apis don't repy on each other.",9"OTX": "AlienVault Open Threat Exchange (OTX) is a global community-based platform where participants can share and collaborate on threat intelligence in real-time, enhancing their ability to respond to emerging cybersecurity threats. OTX has 5 categories of APIs, and contains a total number of 40 APIs. In our dataset we selected a subset of OTX.",10"CVECPE": "CVEs and CPEs are critical in cybersecurity. CVE search and CPE search are tools provided by NVDLib that can find CVE and CPE items based on dates, keywords, severities, etc. These APIs are hard for LLMs to handle due to its large number of args, 47 args for searchCVE and 11 args for searchCPE, respectively.",11"VirusTotal": "VirusTotal is a well-accepted tool in cybersecurity that can analyze files and URLs for viruses, worms, trojans, etc. using a variety of antivirus engines and website scanners. VirusTotal is hard for LLMs to use because it has 8 categories, contains a total number of 208 APIs. We selected a subset in our experiments. In particular, note that many of the APIs have similar functionalites, with specific differences that are important, non-negligible but hard to find.",12"CVECPE_Multi_Dependency": "Built on top of the CVECPE dataset, we added 12 supplementary APIs to achieve more advanced functionalities. Multi_Dependency means that in order to fulfill the task requested by user's query, the model needs to call multiple apis, where some apis rely on the results of other apis."13}14 15 16func_definitions = {17"Climate": [("get_latitude_longitude(location: str)", 18 """19 Given a city name, this function provides the latitude and longitude of the specific location.20 21 Args:22 - location: This can be a city like 'Austin', or a place like 'Austin Airport', etc.23 """),24 ("get_current_location()", 25 """26 Returns the current location. ONLY use this if the user has not provided an explicit location in the query.27 28 Returns a string representation of the city, such as "Austin". This will not return a latitude or longitude.29 """),30 ("find_nearby_stations(lat_long : tuple)",31 """32 This endpoint provides a list of nearby weather stations for a given geographical location. Please provide the geographical location as a latitude and longitude.33 34 Args:35 - lat_long: This argument should be a tuple of the latitude as the first element and the longitude as the second element.36 37 Returns:38 - A list of dictionaries about the various stations near you.39 """),40 ("get_nearest_station_id(nearby_stations)",41 """42 Given a list of nearby stations, returns the one nearest to you and provides the system ID for it alone.43 44 Args:45 - nearby_stations: A list of nearby stations in dictionary format.46 47 Returns:48 The station_id alone for the nearest station in the list of the stations provided.49 """),50 ("get_timezone(lat_long)",51 """52 This gets the timezone for a given latlong.53 54 Args:55 - lat_long: The latitude and longitude of the area you want to query the timezone for.56 """),57 ("get_hourly_observation(station_id, start_time, end_time, time_zone)",58 """59 Returns hourly observations between start_time and end_time.60 61 Please ensure that the start and end times are provided in the format "YYYY-MM-DD".62 Please provide the timezone for your input as well!63 64 Args:65 - station_id: The station_id for the station you're interested in66 - start_time : The time span to start pulling hourly observations for. Should be in format of "YYYY-MM-DD".67 - end_time: The time span to end pulling hourly observations for. Should be in format of "YYYY-MM-DD".68 - timezone: The timezone string id for the location you're asking for.69 70 Returns:71 The list of hourly observations for your station and timespan.72 """),73 ("subtract_time_delta(date_time_str, delta_days)",74 """75 Subtracts a time delta from the date part of a given date time string and returns 76 the new date string with the updated date.77 78 DO NOT use this if delta_days is 0.79 80 :param date_time_str: The date time string in format 'YYYY-MM-DD'.81 :param delta_days: Number of days to subtract. HAS TO BE LARGER THAN 0.82 :return: New date string with the updated date after subtracting the delta.83 """),84 ("get_current_time_at_location(lat_long)",85 """86 Returns the current time at a given location.87 88 Args:89 - lat_long: The latitude and longitude of the location of interest.90 """)],91"Heldout_Combined": [("", "")],92"Places_API": [("get_current_location()", 93 """94 Returns the current location. ONLY use this if the user has not provided an explicit location in the query.95 """),96 ("sort_results(places, sort: str, ascending: bool)",97 """98 Sorts the results by either 'distance', 'rating' or 'price'.99 100 Args101 - places: The output list from the recommendations.102 - sort (str): If set, sorts by either 'distance' or 'rating' or 'price'. ONLY supports 'distance' or 'rating' or 'price'.103 - ascending (bool): If ascending is set, setting this boolean to true will sort the results by lower values first.104 """),105 ("get_latitude_longitude(location: str)",106 """107 Given a city name, this function provides the latitude and longitude of the specific location.108 109 Args110 - location: This can be a city like 'Austin', or a place like 'Austin Airport', etc.111 """),112 ("get_distance(place_1: str, place_2: str)", 113 """114 Provides distance between two locations. Do NOT provide latitude longitude, but rather, provide the string descriptions.115 116 Args117 - place_1: The first location.118 - place_2: The second location.119 """),120 ("get_recommendations(topics: list, lat_long: tuple)",121 """122 Returns the recommendations for a specific topic that is of interest. Remember, a topic IS NOT an establishment. For establishments, please use anothher function.123 124 Args125 - topics (list): A list of topics of interest to pull recommendations for. Can be multiple words.126 - lat_long (tuple): The lat_long of interest.127 """),128 ("find_places_near_location(type_of_place: list, location: str, radius_miles: int = 50)", 129 """130 Find places close to a very defined location.131 132 Args133 - type_of_place (list): The type of place. This can be something like 'restaurant' or 'airport'. Make sure that it is a physical location. You can provide multiple words.134 - location (str): The location for the search. This can be a city's name, region, or anything that specifies the location.135 - radius_miles (int): Optional. The max distance from the described location to limit the search. Distance is specified in miles.136 """),137 ("get_some_reviews(place_names: list, location: str = None)",138 """139 Given an establishment (or place) name, return reviews about the establishment.140 141 Args142 - place_names (list): The name of the establishment. This should be a physical location name. You can provide multiple inputs.143 - location (str) : The location where the restaurant is located. Optional argument.144 """)],145"VT_Multi_Dependency": [("vt_validate_historical_ssl_certificates(historical_ssl_certificates: list, x_apikey: str)",146 """This function takes historical SSL certificates as input and checks if there is at least one valid SSL certificate present inside the provided historical data. It validates the SSL certificate by checking whether it is not expired and its issuing authority is trustworthy. 147 148 Args: 149 - historical_ssl_certificates: list, required, List of SSL certificates in the history 150 - x_apikey: string, required, Your API key151 """),152 ("vt_get_threat_actors_main_source_region(threat_actors: list, x_apikey: str)", 153 """This function takes a list of threat actor objects and returns the primary source region among them. Each threat actor object has an attribute 'source region', and the function analyses this attribute across all objects to determine and return the most common source region, deemed as the 'main' source region. 154 155 Args: 156 - threat_actors: list, required, List of threat actor objects 157 - x_apikey: string, required, Your API key.158 """),159 ("vt_get_threat_actors_latest_modification_date(threat_actor_objects: list, x_apikey: str)", 160 """This function retrieves the latest modification date from a list of threat actor objects. It iterates through each threat actor object, checks its modification date, and returns the most recent modification date. 161 162 Args: 163 - threat_actor_objects: list of objects, required, A list of threat actor objects. 164 - x_apikey: string, required, Your API key.165 """),166 ("convert_unix_timestamp_to_date(unix_timestamp: int)", 167 """Converts a UNIX timestamp to a human-readable date in the format 'YYYY/MM/DD'. 168 169 Args: 170 - unix_timestamp: integer, required, The UNIX timestamp to be converted.171 """),172 ("vt_is_date_within_range(timestamp: int, start: str, end: str)", 173 """Checks if a given Unix timestamp is within a specified date range. The range is specified by 'start' and 'end' dates formatted as 'YYYY/MM/DD'. It's permissible for only one of 'start' or 'end' to be present in the function call. If 'start' is not provided, the function checks if the timestamp is earlier than or equal to the 'end' date. Similarly, If 'end' is not provided, the function checks if the timestamp is later than or equal to the 'start' date. 174 175 Args:176 - timestamp: int, required, Unix timestamp 177 - start: string, optional, Start of the date range in 'YYYY/MM/DD' format 178 - end: string, optional, End of the date range in 'YYYY/MM/DD' format179 """),180 ("vt_get_last_analysis_date_from_report(report: dict)", 181 """This function retrieves the last analysis date from the domain report collected by VirusTotal. The returned date is in Unix timestamp format. 182 183 Args: 184 - report: dict, required, The domain report collected by vt_get_domain_report function.185 """),186 ("vt_get_comments_on_multiple_domains(domains: list, x_apikey: str, limit: int, cursor: str)", 187 """This function will retrieve comments for each specified domain in the given list. 188 189 Args: 190 - domains, list of strings, required, List of domain names 191 - x_apikey, string, required, Your API key 192 - limit, int32, optional, Maximum number of comments to retrieve for each domain 193 - cursor, string, optional, Continuation cursor194 """),195 ("vt_get_multiple_domain_reports(domains: list, x_apikey: str)", 196 """retrieves reports for a list of domains provided. For each domain in the list, it requests the collected information regarding that domain from VirusTotal. 197 198 Args: 199 - domains: list of strings, required, A list of Domain names 200 - x_apikey: string, required, Your API key201 """),202 ("vt_get_majority_vote(votes: dict)", 203 """This function takes a dictionary of votes returns the name with the majority votes. If the votes are equal, it will return the first encountered key in the dictionary. 204 205 Args: 206 - votes: dictionary, required, dictionary of votes207 """),208 ("count_items_in_list(input_list: list)", 209 """This function takes a list as an input and returns the number of items present in the list. 210 211 Args: 212 - input_list: list, required, List whose items are to be counted213 """),214 ("extract_resolution_date(dns_res_obj: object)", 215 """Extracts the date of DNS resolution from a DNS resolution object. The date is returned as a Unix timestamp. 216 217 Args: 218 - dns_res_obj: object, required, The DNS resolution object from which the date of resolution is to be extracted.219 """),220 ("calculate_sum_of_numbers(num1: int, num2: int)", 221 """Computes the sum of two numbers provided. Input numbers can be either integer or floating-point values. 222 223 Args: 224 - num1: Integer or Float, required, The first number 225 - num2: Integer or Float, required, The second number226 """),227 ("get_first_object_from_list(list_of_objects: list)", 228 """Retrieves the first object from a given list. If the list is empty, it return `None`. 229 230 Args: 231 - list_of_objects: list, required, List containing objects from which the function will pick out the first object.232 """),233 ("get_random_object_from_list(list_of_objects: list)", 234 """This function selects and returns a random object from a list of objects. It is designed to handle any list length, including empty lists. 235 236 Args: 237 - list_of_objects: list, required, List containing objects from which the function will pick out a random object.238 """),239 ("resolve_ip_to_domain_and_parent_domain(ip_address: str)", 240 """Resolves an IP address to its associated domain and parent domain. This function leverages DNS resolution to determine the domain associated with the given IP address and then extracts the parent domain from the resolved domain. 241 242 Args: 243 - ip_address (string, required): The IP address to be resolved. Returns: 244 - tuple: A tuple containing the domain and parent domain if resolution is successful; otherwise, None for both.245 """),246 ("extract_domain_and_parent_domain(url: str)", 247 """Extracts the domain and parent domain from a given URL. 248 249 Args: 250 - url (string, required): The URL from which to extract the domain and parent domain. 251 252 Returns: 253 - tuple: A tuple containing the domain and parent domain.254 """),255 ("merge_two_lists(list1: list, list2: list)", 256 """Merges two lists of objects into a single list. This function takes in two lists and returns a combined list containing elements from both lists. Duplicates are not removed. 257 258 Args:259 - list1 (list, required): The first list of objects to be merged. 260 - list2 (list, required): The second list of objects to be merged. 261 262 Returns: 263 - list: A merged list containing elements from both input lists.264 """),265 ("vt_get_votes_on_ip_address(ip: str)", """266 This function will retrieve votes on a provided IP address.267 268 Args:269 - ip: string, required, ip address270 """), 271 ("vt_get_comments_on_domain(domain: str, x_apikey: str, limit: int = None, cursor: str = None)", 272 """273 This function will retrieve comments on a specified domain.274 275 Args:276 - domain, string, required, Domain name277 - x-apikey, string, required, Your API key278 - limit, int32, optional, Maximum number of comments to retrieve279 - cursor, string, optional, Continuation cursor280 """), 281 ("vt_get_object_descriptors_related_to_domain(domain: str, relationship: str, x_apikey: str, limit: int = None, cursor: str = None)", 282 """283 This specifically returns related object's IDs (and context attributes, if any). Please note that this will not return all attributes. This will return objects relating to a domain.284 285 - caa_records: Records CAA for the domain. 286 - cname_records: Records CNAME for the domain. 287 - comments: Community posted comments about the domain. 288 - communicating_files: Files that communicate with the domain. 289 - downloaded_files: Files downloaded from that domain. 290 - graphs: All graphs that include the domain. 291 - historical_ssl_certificates: SSL certificates associated with the domain. 292 - historical_whois: WHOIS information for the domain. 293 - immediate_parent: Domain's immediate parent. 294 - mx_records: Records MX for the domain. 295 - ns_records: Records NS for the domain. 296 - parent: Domain's top parent. 297 - referrer_files: Refers to any and all files that contain this domain. 298 - related_comments: Community posted comments in the domain's related objects. 299 - related_references: Refers to the References related to the domain. 300 - related_threat_actors: Refers to the threat actors related to the domain. A list of Threat Actors.301 - resolutions: DNS resolutions for the domain. 302 - soa_records: Records SOA for the domain. 303 - siblings: Refers to the Domain's sibling domains. 304 - subdomains: Refers to the Domain's subdomains. 305 - urls: Refers to the URLs that contain this domain. 306 - user_votes: Refers to the current user's votes. 307 308 Args:309 - domain: string, required, Domain name310 - relationship: string, required, Relationship name (see table)311 - x-apikey: string, required, Your API key312 - limit: int32, optional, Maximum number of comments to retrieve313 - cursor: string, optional, Continuation cursor314 """), 315 ("vt_get_objects_related_to_domain(domain: str, relationship: str, x_apikey: str, limit: int = None, cursor: str = None)",316 """317 Objects are a key concept in the VirusTotal API. Each object has an identifier and a type. 318 Each object has an associated URL, and each domain is associated with objects.319 This function returns ALL of the objects related to the domain, based on the specified relationship.320 321 The following describe the valid relationship:322 - caa_records: Records CAA for the domain. 323 - cname_records: Records CNAME for the domain. 324 - comments: Community posted comments about the domain. 325 - communicating_files: Files that communicate with the domain. 326 - downloaded_files: Files downloaded from that domain. 327 - graphs: All graphs that include the domain. 328 - historical_ssl_certificates: SSL certificates associated with the domain. 329 - historical_whois: WHOIS information for the domain. 330 - immediate_parent: Domain's immediate parent. 331 - mx_records: Records MX for the domain. 332 - ns_records: Records NS for the domain. 333 - parent: Domain's top parent. 334 - referrer_files: Refers to any and all files that contain this domain. 335 - related_comments: Community posted comments in the domain's related objects. 336 - related_references: Refers to the References related to the domain. 337 - related_threat_actors: Refers to the threat actors related to the domain. A list of Threat Actors.338 - resolutions: DNS resolutions for the domain. 339 - soa_records: Records SOA for the domain. 340 - siblings: Refers to the Domain's sibling domains. 341 - subdomains: Refers to the Domain's subdomains. 342 - urls: Refers to the URLs that contain this domain. 343 - user_votes: Refers to the current user's votes. 344 345 346 Args:347 - domain: string, required, Domain name348 - relationship, string, required, Relationship name (see table)349 - x-apikey, string, required, Your API key350 - limit, int32, optional, Maximum number of comments to retrieve351 - cursor, string, optional, Continuation cursor352 """), 353 ("vt_get_object_descriptors_related_to_ip_address(ip: str, relationship: str, x_apikey: str, limit: int = None, cursor: str = None)",354 """355 This specifically returns related object's IDs (and context attributes, if any). Please note that this will not return all attributes.356 357 You are expected to provide the relationship to the object you're interested in. The valid relationships are as follows.358 359 The relationships are documented here:360 - comments: The comments for the IP address. 361 - communicating_files: Files that communicate with the IP address. 362 - downloaded_files: Files downloaded from the IP address. VT Enterprise users only. 363 - graphs: Graphs including the IP address. 364 - historical_ssl_certificates: SSL certificates associated with the IP. 365 - historical_whois: WHOIS information for the IP address. Retrurns a list of Whois attributes.366 - related_comments: Community posted comments in the IP's related objects. 367 - related_references: Returns the references related to the IP address. 368 - related_threat_actors: Threat actors related to the IP address. 369 - referrer_files: Files containing the IP address. 370 - resolutions: Resolves the IP addresses. 371 - urls: Returns a list of URLs related to the IP address.372 373 Here are some useful descriptions of the arguments in this API, with the format - name of this argument: type of the data, required or optional, description of this argument.374 - ip: string, required, IP address375 - relationship: string, required, Relationship name (see table)376 - x-apikey: string, required, Your API key377 - limit: int32, optional, Maximum number of comments to retrieve378 - cursor: string, optional, Continuation cursor379 """), 380 ("vt_add_comment_to_ip_address(ip: str, data: dict, x_apikey: str)",381 """382 With this function you can post a comment for a given IP address. The body for the POST request must be the JSON representation of a comment object. Notice however that you don't need to provide an ID for the object, as they are automatically generated for new comments.383 However, please note that you will need to provide a valid data JSON for using this function.384 385 Any word starting with # in your comment's text will be considered a tag, and added to the comment's tag attribute.386 387 Returns a Comment object.388 389 Args:390 - ip: string, required, IP address391 - data: json, required, A comment object392 - x-apikey: string, required, Your API key393 """), 394 ("vt_get_comments_on_ip_address(ip: str, x_apikey: str, limit: int = None, cursor: str = None)",395 """396 Retrieves the comments on a provided IP address. Returns a list of Comment objects.397 398 Args:399 - ip, string, required, IP address400 - x-apikey, string, required, Your API key401 - limit, int32, optional, Maximum number of comments to retrieve402 - cursor, string, optional, Continuation cursor403 """), 404 ("vt_get_domain_report(domain: str, x_apikey: str)",405 """406 Retrieves a domain report. These reports contain information regarding the domain itself that VirusTotal has collected.407 408 Args:409 - domain: string, required, Domain name410 - x-apikey: string, required, Your API key411 """), 412 ("vt_add_votes_to_ip_address(ip: str, data: dict, x_apikey: str)",413 """414 With this function you can post a vote for a given file. The body for the POST request must be the JSON representation of a vote object. Note however that you don't need to provide an ID for the object, as they are automatically generated for new votes. The verdict attribute must have be either harmless or malicious.415 416 Please ensure that the JSON object you provide conforms accurately to valid JSON standards.417 418 Args:419 - ip, string, required, IP address420 - data, json, Vote object421 - x-apikey, string, required, Your API key422 """), 423 ("vt_get_ip_address_report(ip: str, x_apikey: str)", 424 """425 Retrieve an IP address report. These reports condense all of the recent activity that VirusTotal has seen for the resource under consideration, as well as contextual information about it.426 This function specifically generates these reports using the IP address parameter. 427 428 Args:429 - ip: string, required, IP address430 - x-apikey: string, required, Your API key431 """), 432 ("vt_get_objects_related_to_ip_address(ip: str, relationship: str, x_apikey: str, limit: int = None, cursor: str = None)",433 """434 IP addresses have number of relationships to other objects. This returns ALL objects that fit the relationship.435 436 The relationships are documented here:437 - comments: The comments for the IP address. Returns a list of comments. 438 - communicating_files: Files that communicate with the IP address. Returns a list of files.439 - downloaded_files: Files downloaded from the IP address. VT Enterprise users only. Returns a list of files.440 - graphs: Graphs including the IP address. Returns a list of graphs.441 - historical_ssl_certificates: SSL certificates associated with the IP. Returns a list of SSL certificates. 442 - historical_whois: WHOIS information for the IP address. Retrurns a list of Whois attributes.443 - related_comments: Community posted comments in the IP's related objects. Returns a list of comments.444 - related_references: Returns the references related to the IP address. Returns a list of References.445 - related_threat_actors: Threat actors related to the IP address. Returns a list of threat actors.446 - referrer_files: Files containing the IP address. Returns a list of Files.447 - resolutions: Resolves the IP addresses. Returns a list of resolutions.448 - urls: Returns a list of URLs related to the IP address. Returns a list of URLs.449 450 Args:451 - ip, string, required, IP address452 - relationship, string, required, Relationship name (see the list of items from above)453 - x-apikey, string, required, Your API key454 - limit, int32, optional, Maximum number of comments to retrieve455 - cursor, string, optional, Continuation cursor456 """), 457 ("vt_get_dns_resolution_object(id: str, x_apikey: str)",458 """459 This endpoint retrieves a Resolution object by its ID. A resolution object ID is made by appending the IP and the domain it resolves to together.460 461 Domain-IP resolutions. Resolution objects include the following attributes:462 date: <integer> date when the resolution was made (UTC timestamp).463 host_name: <string> domain or subdomain requested to the resolver.464 host_name_last_analysis_stats: <dictionary> last detection stats from the resolution's domain. Similar to the domains's last_analysis_stats attribute.465 ip_address: <string> IP address the domain was resolved to.466 ip_address_last_analysis_stats: <dictionary> last detection stats from the resolution's IP address. Similar to the IP address' last_analysis_stats attribute.467 resolver: <string> source of the resolution.468 469 Args:470 - id: string, required, Resolution object ID471 - x-apikey: string, required, Your API key472 """)],473"VT_Multi_Disconnected": [("vt_validate_historical_ssl_certificates(historical_ssl_certificates: list, x_apikey: str)",474 """This function takes historical SSL certificates as input and checks if there is at least one valid SSL certificate present inside the provided historical data. It validates the SSL certificate by checking whether it is not expired and its issuing authority is trustworthy. 475 476 Args: 477 - historical_ssl_certificates: list, required, List of SSL certificates in the history 478 - x_apikey: string, required, Your API key479 """),480 ("vt_get_threat_actors_main_source_region(threat_actors: list, x_apikey: str)", 481 """This function takes a list of threat actor objects and returns the primary source region among them. Each threat actor object has an attribute 'source region', and the function analyses this attribute across all objects to determine and return the most common source region, deemed as the 'main' source region. 482 483 Args: 484 - threat_actors: list, required, List of threat actor objects 485 - x_apikey: string, required, Your API key.486 """),487 ("vt_get_threat_actors_latest_modification_date(threat_actor_objects: list, x_apikey: str)", 488 """This function retrieves the latest modification date from a list of threat actor objects. It iterates through each threat actor object, checks its modification date, and returns the most recent modification date. 489 490 Args: 491 - threat_actor_objects: list of objects, required, A list of threat actor objects. 492 - x_apikey: string, required, Your API key.493 """),494 ("convert_unix_timestamp_to_date(unix_timestamp: int)", 495 """Converts a UNIX timestamp to a human-readable date in the format 'YYYY/MM/DD'. 496 497 Args: 498 - unix_timestamp: integer, required, The UNIX timestamp to be converted.499 """),500 ("vt_is_date_within_range(timestamp: int, start: str, end: str)", 501 """Checks if a given Unix timestamp is within a specified date range. The range is specified by 'start' and 'end' dates formatted as 'YYYY/MM/DD'. It's permissible for only one of 'start' or 'end' to be present in the function call. If 'start' is not provided, the function checks if the timestamp is earlier than or equal to the 'end' date. Similarly, If 'end' is not provided, the function checks if the timestamp is later than or equal to the 'start' date. 502 503 Args:504 - timestamp: int, required, Unix timestamp 505 - start: string, optional, Start of the date range in 'YYYY/MM/DD' format 506 - end: string, optional, End of the date range in 'YYYY/MM/DD' format507 """),508 ("vt_get_last_analysis_date_from_report(report: dict)", 509 """This function retrieves the last analysis date from the domain report collected by VirusTotal. The returned date is in Unix timestamp format. 510 511 Args: 512 - report: dict, required, The domain report collected by vt_get_domain_report function.513 """),514 ("vt_get_comments_on_multiple_domains(domains: list, x_apikey: str, limit: int, cursor: str)", 515 """This function will retrieve comments for each specified domain in the given list. 516 517 Args: 518 - domains, list of strings, required, List of domain names 519 - x_apikey, string, required, Your API key 520 - limit, int32, optional, Maximum number of comments to retrieve for each domain 521 - cursor, string, optional, Continuation cursor522 """),523 ("vt_get_multiple_domain_reports(domains: list, x_apikey: str)", 524 """retrieves reports for a list of domains provided. For each domain in the list, it requests the collected information regarding that domain from VirusTotal. 525 526 Args: 527 - domains: list of strings, required, A list of Domain names 528 - x_apikey: string, required, Your API key529 """),530 ("vt_get_majority_vote(votes: dict)", 531 """This function takes a dictionary of votes returns the name with the majority votes. If the votes are equal, it will return the first encountered key in the dictionary. 532 533 Args: 534 - votes: dictionary, required, dictionary of votes535 """),536 ("count_items_in_list(input_list: list)", 537 """This function takes a list as an input and returns the number of items present in the list. 538 539 Args: 540 - input_list: list, required, List whose items are to be counted541 """),542 ("extract_resolution_date(dns_res_obj: object)", 543 """Extracts the date of DNS resolution from a DNS resolution object. The date is returned as a Unix timestamp. 544 545 Args: 546 - dns_res_obj: object, required, The DNS resolution object from which the date of resolution is to be extracted.547 """),548 ("calculate_sum_of_numbers(num1: int, num2: int)", 549 """Computes the sum of two numbers provided. Input numbers can be either integer or floating-point values. 550 551 Args: 552 - num1: Integer or Float, required, The first number 553 - num2: Integer or Float, required, The second number554 """),555 ("get_first_object_from_list(list_of_objects: list)", 556 """Retrieves the first object from a given list. If the list is empty, it return `None`. 557 558 Args: 559 - list_of_objects: list, required, List containing objects from which the function will pick out the first object.560 """),561 ("get_random_object_from_list(list_of_objects: list)", 562 """This function selects and returns a random object from a list of objects. It is designed to handle any list length, including empty lists. 563 564 Args: 565 - list_of_objects: list, required, List containing objects from which the function will pick out a random object.566 """),567 ("resolve_ip_to_domain_and_parent_domain(ip_address: str)", 568 """Resolves an IP address to its associated domain and parent domain. This function leverages DNS resolution to determine the domain associated with the given IP address and then extracts the parent domain from the resolved domain. 569 570 Args: 571 - ip_address (string, required): The IP address to be resolved. Returns: 572 - tuple: A tuple containing the domain and parent domain if resolution is successful; otherwise, None for both.573 """),574 ("extract_domain_and_parent_domain(url: str)", 575 """Extracts the domain and parent domain from a given URL. 576 577 Args: 578 - url (string, required): The URL from which to extract the domain and parent domain. 579 580 Returns: 581 - tuple: A tuple containing the domain and parent domain.582 """),583 ("merge_two_lists(list1: list, list2: list)", 584 """Merges two lists of objects into a single list. This function takes in two lists and returns a combined list containing elements from both lists. Duplicates are not removed. 585 586 Args:587 - list1 (list, required): The first list of objects to be merged. 588 - list2 (list, required): The second list of objects to be merged. 589 590 Returns: 591 - list: A merged list containing elements from both input lists.592 """),593 ("vt_get_votes_on_ip_address(ip: str)", """594 This function will retrieve votes on a provided IP address.595 596 Args:597 - ip: string, required, ip address598 """), 599 ("vt_get_comments_on_domain(domain: str, x_apikey: str, limit: int = None, cursor: str = None)", 600 """601 This function will retrieve comments on a specified domain.602 603 Args:604 - domain, string, required, Domain name605 - x-apikey, string, required, Your API key606 - limit, int32, optional, Maximum number of comments to retrieve607 - cursor, string, optional, Continuation cursor608 """), 609 ("vt_get_object_descriptors_related_to_domain(domain: str, relationship: str, x_apikey: str, limit: int = None, cursor: str = None)", 610 """611 This specifically returns related object's IDs (and context attributes, if any). Please note that this will not return all attributes. This will return objects relating to a domain.612 613 - caa_records: Records CAA for the domain. 614 - cname_records: Records CNAME for the domain. 615 - comments: Community posted comments about the domain. 616 - communicating_files: Files that communicate with the domain. 617 - downloaded_files: Files downloaded from that domain. 618 - graphs: All graphs that include the domain. 619 - historical_ssl_certificates: SSL certificates associated with the domain. 620 - historical_whois: WHOIS information for the domain. 621 - immediate_parent: Domain's immediate parent. 622 - mx_records: Records MX for the domain. 623 - ns_records: Records NS for the domain. 624 - parent: Domain's top parent. 625 - referrer_files: Refers to any and all files that contain this domain. 626 - related_comments: Community posted comments in the domain's related objects. 627 - related_references: Refers to the References related to the domain. 628 - related_threat_actors: Refers to the threat actors related to the domain. A list of Threat Actors.629 - resolutions: DNS resolutions for the domain. 630 - soa_records: Records SOA for the domain. 631 - siblings: Refers to the Domain's sibling domains. 632 - subdomains: Refers to the Domain's subdomains. 633 - urls: Refers to the URLs that contain this domain. 634 - user_votes: Refers to the current user's votes. 635 636 Args:637 - domain: string, required, Domain name638 - relationship: string, required, Relationship name (see table)639 - x-apikey: string, required, Your API key640 - limit: int32, optional, Maximum number of comments to retrieve641 - cursor: string, optional, Continuation cursor642 """), 643 ("vt_get_objects_related_to_domain(domain: str, relationship: str, x_apikey: str, limit: int = None, cursor: str = None)",644 """645 Objects are a key concept in the VirusTotal API. Each object has an identifier and a type. 646 Each object has an associated URL, and each domain is associated with objects.647 This function returns ALL of the objects related to the domain, based on the specified relationship.648 649 The following describe the valid relationship:650 - caa_records: Records CAA for the domain. 651 - cname_records: Records CNAME for the domain. 652 - comments: Community posted comments about the domain. 653 - communicating_files: Files that communicate with the domain. 654 - downloaded_files: Files downloaded from that domain. 655 - graphs: All graphs that include the domain. 656 - historical_ssl_certificates: SSL certificates associated with the domain. 657 - historical_whois: WHOIS information for the domain. 658 - immediate_parent: Domain's immediate parent. 659 - mx_records: Records MX for the domain. 660 - ns_records: Records NS for the domain. 661 - parent: Domain's top parent. 662 - referrer_files: Refers to any and all files that contain this domain. 663 - related_comments: Community posted comments in the domain's related objects. 664 - related_references: Refers to the References related to the domain. 665 - related_threat_actors: Refers to the threat actors related to the domain. A list of Threat Actors.666 - resolutions: DNS resolutions for the domain. 667 - soa_records: Records SOA for the domain. 668 - siblings: Refers to the Domain's sibling domains. 669 - subdomains: Refers to the Domain's subdomains. 670 - urls: Refers to the URLs that contain this domain. 671 - user_votes: Refers to the current user's votes. 672 673 674 Args:675 - domain: string, required, Domain name676 - relationship, string, required, Relationship name (see table)677 - x-apikey, string, required, Your API key678 - limit, int32, optional, Maximum number of comments to retrieve679 - cursor, string, optional, Continuation cursor680 """), 681 ("vt_get_object_descriptors_related_to_ip_address(ip: str, relationship: str, x_apikey: str, limit: int = None, cursor: str = None)",682 """683 This specifically returns related object's IDs (and context attributes, if any). Please note that this will not return all attributes.684 685 You are expected to provide the relationship to the object you're interested in. The valid relationships are as follows.686 687 The relationships are documented here:688 - comments: The comments for the IP address. 689 - communicating_files: Files that communicate with the IP address. 690 - downloaded_files: Files downloaded from the IP address. VT Enterprise users only. 691 - graphs: Graphs including the IP address. 692 - historical_ssl_certificates: SSL certificates associated with the IP. 693 - historical_whois: WHOIS information for the IP address. Retrurns a list of Whois attributes.694 - related_comments: Community posted comments in the IP's related objects. 695 - related_references: Returns the references related to the IP address. 696 - related_threat_actors: Threat actors related to the IP address. 697 - referrer_files: Files containing the IP address. 698 - resolutions: Resolves the IP addresses. 699 - urls: Returns a list of URLs related to the IP address.700 701 Here are some useful descriptions of the arguments in this API, with the format - name of this argument: type of the data, required or optional, description of this argument.702 - ip: string, required, IP address703 - relationship: string, required, Relationship name (see table)704 - x-apikey: string, required, Your API key705 - limit: int32, optional, Maximum number of comments to retrieve706 - cursor: string, optional, Continuation cursor707 """), 708 ("vt_add_comment_to_ip_address(ip: str, data: dict, x_apikey: str)",709 """710 With this function you can post a comment for a given IP address. The body for the POST request must be the JSON representation of a comment object. Notice however that you don't need to provide an ID for the object, as they are automatically generated for new comments.711 However, please note that you will need to provide a valid data JSON for using this function.712 713 Any word starting with # in your comment's text will be considered a tag, and added to the comment's tag attribute.714 715 Returns a Comment object.716 717 Args:718 - ip: string, required, IP address719 - data: json, required, A comment object720 - x-apikey: string, required, Your API key721 """), 722 ("vt_get_comments_on_ip_address(ip: str, x_apikey: str, limit: int = None, cursor: str = None)",723 """724 Retrieves the comments on a provided IP address. Returns a list of Comment objects.725 726 Args:727 - ip, string, required, IP address728 - x-apikey, string, required, Your API key729 - limit, int32, optional, Maximum number of comments to retrieve730 - cursor, string, optional, Continuation cursor731 """), 732 ("vt_get_domain_report(domain: str, x_apikey: str)",733 """734 Retrieves a domain report. These reports contain information regarding the domain itself that VirusTotal has collected.735 736 Args:737 - domain: string, required, Domain name738 - x-apikey: string, required, Your API key739 """), 740 ("vt_add_votes_to_ip_address(ip: str, data: dict, x_apikey: str)",741 """742 With this function you can post a vote for a given file. The body for the POST request must be the JSON representation of a vote object. Note however that you don't need to provide an ID for the object, as they are automatically generated for new votes. The verdict attribute must have be either harmless or malicious.743 744 Please ensure that the JSON object you provide conforms accurately to valid JSON standards.745 746 Args:747 - ip, string, required, IP address748 - data, json, Vote object749 - x-apikey, string, required, Your API key750 """), 751 ("vt_get_ip_address_report(ip: str, x_apikey: str)", 752 """753 Retrieve an IP address report. These reports condense all of the recent activity that VirusTotal has seen for the resource under consideration, as well as contextual information about it.754 This function specifically generates these reports using the IP address parameter. 755 756 Args:757 - ip: string, required, IP address758 - x-apikey: string, required, Your API key759 """), 760 ("vt_get_objects_related_to_ip_address(ip: str, relationship: str, x_apikey: str, limit: int = None, cursor: str = None)",761 """762 IP addresses have number of relationships to other objects. This returns ALL objects that fit the relationship.763 764 The relationships are documented here:765 - comments: The comments for the IP address. Returns a list of comments. 766 - communicating_files: Files that communicate with the IP address. Returns a list of files.767 - downloaded_files: Files downloaded from the IP address. VT Enterprise users only. Returns a list of files.768 - graphs: Graphs including the IP address. Returns a list of graphs.769 - historical_ssl_certificates: SSL certificates associated with the IP. Returns a list of SSL certificates. 770 - historical_whois: WHOIS information for the IP address. Retrurns a list of Whois attributes.771 - related_comments: Community posted comments in the IP's related objects. Returns a list of comments.772 - related_references: Returns the references related to the IP address. Returns a list of References.773 - related_threat_actors: Threat actors related to the IP address. Returns a list of threat actors.774 - referrer_files: Files containing the IP address. Returns a list of Files.775 - resolutions: Resolves the IP addresses. Returns a list of resolutions.776 - urls: Returns a list of URLs related to the IP address. Returns a list of URLs.777 778 Args:779 - ip, string, required, IP address780 - relationship, string, required, Relationship name (see the list of items from above)781 - x-apikey, string, required, Your API key782 - limit, int32, optional, Maximum number of comments to retrieve783 - cursor, string, optional, Continuation cursor784 """), 785 ("vt_get_dns_resolution_object(id: str, x_apikey: str)",786 """787 This endpoint retrieves a Resolution object by its ID. A resolution object ID is made by appending the IP and the domain it resolves to together.788 789 Domain-IP resolutions. Resolution objects include the following attributes:790 date: <integer> date when the resolution was made (UTC timestamp).791 host_name: <string> domain or subdomain requested to the resolver.792 host_name_last_analysis_stats: <dictionary> last detection stats from the resolution's domain. Similar to the domains's last_analysis_stats attribute.793 ip_address: <string> IP address the domain was resolved to.794 ip_address_last_analysis_stats: <dictionary> last detection stats from the resolution's IP address. Similar to the IP address' last_analysis_stats attribute.795 resolver: <string> source of the resolution.796 797 Args:798 - id: string, required, Resolution object ID799 - x-apikey: string, required, Your API key800 """)],801"OTX": [("getIndicatorForIPv4(apiKey: str, ip: str, section: str)", 802 """803 Retrieves comprehensive information for a specific IPv4 address from the AlienVault database. This function provides varied data types. 'general' section includes general information about the IP, geo data, and lists of other available sections. 'reputation' provides OTX data on observed malicious activity by AlienVault Labs. 'geo' details extensive geographic data such as country code and coordinates. 'malware' section shows malware samples associated with the IP, 'urlList' reveals URLs linked to the IP, and 'passiveDns' offers passive DNS information about hostnames/domains associated with the IP.804 805 Args:806 - apiKey: string, required, Your AlienVault API key807 - ip: string, required, IPv4 address to query808 - section: string, required, Specific data section to retrieve (options: general, reputation, geo, malware, urlList, passiveDns)809 """),810 ("getIndicatorForIPv6(apiKey: str, ip: str, section: str)", 811 """812 Retrieves comprehensive information for a specific IPv6 address from the AlienVault database. This function allows you to obtain various types of data. The 'general' section provides general information about the IP, including geo data, and a list of other available sections. 'reputation' offers OTX data on malicious activity observed by AlienVault Labs. 'geo' details more verbose geographic data such as country code and coordinates. 'malware' reveals malware samples connected to the IP, and 'urlList' shows URLs associated with the IP. Lastly, 'passiveDns' includes passive DNS information about hostnames/domains pointing to this IP.813 814 Args:815 - apiKey: string, required, Your AlienVault API key816 - ip: string, required, IPv6 address to query817 - section: string, required, Specific data section to retrieve (options: general, reputation, geo, malware, urlList, passiveDns)818 """),819 ("getIndicatorForDomain(apiKey: str, domain: str, section: str)", 820 """821 Retrieves a comprehensive overview for a given domain name from the AlienVault database. This function provides various data types about the domain. The 'general' section includes general information about the domain, such as geo data, and lists of other available sections. 'geo' provides detailed geographic data including country code and coordinates. The 'malware' section indicates malware samples associated with the domain. 'urlList' shows URLs linked to the domain, 'passiveDns' details passive DNS information about hostnames/domains associated with the domain, and 'whois' gives Whois records for the domain.822 823 Args:824 - apiKey: string, required, Your AlienVault API key825 - domain: string, required, Domain address to query826 - section: string, required, Specific data section to retrieve (options: general, geo, malware, urlList, passiveDns, whois)827 """),828 ("getIndicatorForHostname(apiKey: str, hostname: str, section: str)", 829 """830 Retrieves detailed information for a specific hostname from the AlienVault database. This function provides various data types about the hostname. The 'general' section includes general information about the IP, geo data, and lists of other available sections. 'geo' provides detailed geographic data including country code and coordinates. The 'malware' section indicates malware samples associated with the hostname. 'urlList' shows URLs linked to the hostname, and 'passiveDns' details passive DNS information about hostnames/domains associated with the hostname.831 832 Args:833 - apiKey: string, required, Your AlienVault API key834 - hostname: string, required, Single hostname address to query835 - section: string, required, Specific data section to retrieve (options: general, geo, malware, urlList, passiveDns)836 """),837 ("getIndicatorForFileHashes(apiKey: str, fileHash: str, section: str)",838 """839 Retrieves information related to a specific file hash from the AlienVault database. This function provides two types of data: 'general', which includes general metadata about the file hash and a list of other available sections for the hash; and 'analysis', which encompasses both dynamic and static analysis of the file, including Cuckoo analysis, exiftool, etc.840 841 Args:842 - apiKey: string, required, Your AlienVault API key843 - fileHash: string, required, Single file hash to query844 - section: string, required, Specific data section to retrieve (options: general, analysis)845 """),846 ("getIndicatorForUrl(apiKey: str, url: str, section: str)", 847 """848 Retrieves information related to a specific URL from the AlienVault database. This function offers two types of data: 'general', which includes historical geographic information, any pulses this indicator is on, and a list of other available sections for this URL; and 'url_list', which provides full results from AlienVault Labs URL analysis, potentially including multiple entries.849 850 Args:851 - apiKey: string, required, Your AlienVault API key852 - url: string, required, Single URL to query853 - section: string, required, Specific data section to retrieve (options: general, url_list)854 """),855 ("getIndicatorForCVE(apiKey: str, cve: str, section: str)",856 """857 Retrieves information related to a specific CVE (Common Vulnerability Enumeration) from the AlienVault database. This function offers detailed data on CVEs. The 'General' section includes MITRE CVE data, such as CPEs (Common Platform Enumerations), CWEs (Common Weakness Enumerations), and other relevant details. It also provides information on any pulses this indicator is on, and lists other sections currently available for this CVE.858 859 Args:860 - apiKey: string, required, Your AlienVault API key861 - cve: string, required, Specific CVE identifier to query (e.g., 'CVE-2014-0160')862 - section: string, required, Specific data section to retrieve ('general' only)863 """),864 ("getIndicatorForNIDS(apiKey: str, nids: str, section: str)", 865 """866 Retrieves metadata information for a specific Network Intrusion Detection System (NIDS) indicator from the AlienVault database. This function is designed to provide general metadata about NIDS indicators.867 868 Args:869 - apiKey: string, required, Your AlienVault API key870 - nids: string, required, Specific NIDS indicator to query (e.g., '2820184')871 - section: string, required, Specific data section to retrieve ('general' only)872 """),873 ("getIndicatorForCorrelationRules(apiKey: str, correlationRule: str, section: str)",874 """875 Retrieves metadata information related to a specific Correlation Rule from the AlienVault database. This function is designed to provide general metadata about Correlation Rules used in network security and event correlation. Correlation Rules are crucial for identifying patterns and potential security threats in network data.876 877 Args:878 - apiKey: string, required, Your AlienVault API key879 - correlationRule: string, required, Specific Correlation Rule identifier to query (e.g., '572f8c3c540c6f0161677877')880 - section: string, required, Specific data section to retrieve ('general' only)881 """)],882"CVECPE": [("searchCVE(cpeName: str, cveId: str, cvssV2Metrics: str, cvssV2Severity: str, cvssV3Metrics: str, cvssV3Severity: str, cweId: str, hasCertAlerts: bool, hasCertNotes: bool, hasKev: bool, hasOval: bool, isVulnerable: bool, keywordExactMatch: bool, keywordSearch: str, lastModStartDate: str, lastModEndDate: str, noRejected: bool, pubStartDate: str, pubEndDate: str, sourceIdentifier: str, versionEnd: str, versionEndType: str, versionStart: str, versionStartType: str, virtualMatchString: str, limit: int, delay: int, key: str, verbose: bool)", 883 """884 Build and send GET request then return list of objects containing a collection of CVEs. For more information on the parameters available, please visit https://nvd.nist.gov/developers/vulnerabilities885 886 Args:887 - cpeName (str): Please do not confuse this with keywordSearch; this requires the argument to start with "cpe", whereas the keywordSearch argument allows for arbitrary keywords. This value will be compared agains the CPE Match Criteria within a CVE applicability statement. (i.e. find the vulnerabilities attached to that CPE). Partial match strings are allowed.888 889 - cveId (str): Please pass in a string integer, like "1" or "30". Returns a single CVE that already exists in the NVD.890 891 - cvssV2Metrics (str): This parameter returns only the CVEs that match the provided CVSSv2 vector string. Either full or partial vector strings may be used. This parameter cannot be used in requests that include cvssV3Metrics.892 893 - cvssV2Severity (str): Find vulnerabilities having a LOW, MEDIUM, or HIGH version 2 severity.894 895 - cvssV3Metrics (str): This parameter returns only the CVEs that match the provided CVSSv3 vector string. Either full or partial vector strings may be used. This parameter cannot be used in requests that include cvssV2Metrics.896 897 - cvssV3Severity (str): Find vulnerabilities having a LOW, MEDIUM, HIGH, or CRITICAL version 3 severity.898 899 - cweId (str): Please pass in a string integer, like "1" or "30". Filter collection by CWE (Common Weakness Enumeration) ID. You can find a list at https://cwe.mitre.org/. A CVE can have multiple CWE IDs assigned to it.900 901 - hasCertAlerts (bool): Returns CVE that contain a Technical Alert from US-CERT.902 903 - hasCertNotes (bool): Returns CVE that contain a Vulnerability Note from CERT/CC.904 905 - hasOval (bool): Returns CVE that contain information from MITRE's Open Vulnerability and Assessment Language (OVAL) before this transitioned to the Center for Internet Security (CIS).906 907 - isVulnerable (bool): Returns CVE associated with a specific CPE, where the CPE is also considered vulnerable. REQUIRES cpeName parameter. isVulnerable is not compatible with virtualMatchString parameter.908 909 - keywordExactMatch (bool): When keywordSearch is used along with keywordExactmatch, it will search the NVD for CVEs containing exactly what was passed to keywordSearch. REQUIRES keywordSearch.910 911 - keywordSearch (str): Searches CVEs where a word or phrase is found in the current description. If passing multiple keywords with a space character in between then each word must exist somewhere in the description, not necessarily together unless keywordExactMatch=True is passed to searchCVE.912 913 - lastModStartDate (str,datetime obj): These parameters return only the CVEs that were last modified during the specified period. If a CVE has been modified more recently than the specified period, it will not be included in the response. If filtering by the last modified date, both lastModStartDate and lastModEndDate are REQUIRED. The maximum allowable range when using any date range parameters is 120 consecutive days.914 915 - lastModEndDate (str, datetime obj): Required if using lastModStartDate.916 917 - noRejected (bool): Filters out all CVEs that are in a reject or rejected status. Searches without this parameter include rejected CVEs.918 919 - pubStartDate (str,datetime obj): These parameters return only the CVEs that were added to the NVD (i.e., published) during the specified period. If filtering by the published date, both pubStartDate and pubEndDate are REQUIRED. The maximum allowable range when using any date range parameters is 120 consecutive days.920 921 - pubEndDate (str, datetime obj): Required if using pubStartDate.922 923 - sourceIdentifier (str): Returns CVE where the data source of the CVE is the value that is passed to sourceIdentifier.924 925 - versionEnd (str): Must be combined with versionEndType and virtualMatchString. Returns only the CVEs associated with CPEs in specific version ranges.926 927 - versionEndType (str): Must be combined with versionEnd and virtualMatchString. Valid values are including or excluding. Denotes to include the specified version in versionEnd, or exclude it.928 929 - versionStart (str): Must be combined with versionStartType and virtualMatchString. Returns only CVEs with specific versions. Requests that include versionStart cannot include a version component in the virtualMatchString.930 931 - versionStartType (str): Must be combined with versionStart and virtualMatchString. Valid values are including or excluding. Denotes to include the specified version in versionStart, or exclude it.932 933 - virtualMatchString (str): A more broad filter compared to cpeName. The cpe match string that is passed to virtualMatchString is compared against the CPE Match Criteria present on CVE applicability statements.934 935 - limit (int): Custom argument to limit the number of results of the search. Allowed any number between 1 and 2000.936 937 - delay (int): Can only be used if an API key is provided. This allows the user to define a delay. The delay must be greater than 0.6 seconds. The NVD API recommends scripts sleep for atleast 6 seconds in between requests.938 939 - key (str): NVD API Key. Allows for the user to define a delay. NVD recommends scripts sleep 6 seconds in between requests. If no valid API key is provided, requests are sent with a 6 second delay.940 941 - verbose (bool): Prints the URL request for debugging purposes.942 """),943 ("searchCPE(cpeNameId: str, cpeMatchString: str, keywordExactMatch: bool, keywordSearch: str, lastModStartDate: str, lastModEndDate: str, matchCriteriaId: str, limit: int, key: str, delay: int, verbose: bool)", 944 """945 Build and send GET request then return list of objects containing a collection of CPEs.946 947 Args:948 - cpeNameId (str) Returns a specific CPE record using its UUID. If a correctly formatted UUID is passed but it does not exist, it will return empty results. The UUID is the cpeNameId value when searching CPE. 949 950 - cpeMatchString (str) Use a partial CPE name to search for other CPE names.951 952 - keywordExactMatch (bool) Searches metadata within CPE title and reference links for an exact match of the phrase or word passed to it. Must be included with keywordSearch.953 954 - keywordSearch (str) Returns CPE records where a word or phrase is found in the metadata title or reference links. Space characters act as an AND statement.955 956 - lastModStartDate (str/datetime obj) CPE last modification start date. Maximum 120 day range. A start and end date is required. All times are in UTC 00:00. A datetime object or string can be passed as a date. NVDLib will automatically parse the datetime object into the correct format. String Example: '2020-06-28 00:00'957 958 - lastModEndDate (str/datetime obj) CPE last modification end date. Maximum 120 day range. Must be included with lastModStartDate. Example: ‘2020-06-28 00:00’959 960 - limit (int) Limits the number of results of the search.961 962 - key (str) NVD API Key. Allows for a request every 0.6 seconds instead of 6 seconds.963 964 - delay (int) Can only be used if an API key is provided. The amount of time to sleep in between requests. Must be a value above 0.6 seconds if an API key is present. delay is set to 6 seconds if no API key is passed. 965 966 - verbose (bool) Prints the URL request for debugging purposes.967 """)],968"VirusTotal": [("vt_get_votes_on_ip_address(ip: str)", """969 This function will retrieve votes on a provided IP address.970 971 Args:972 - ip: string, required, ip address973 """), 974 ("vt_get_comments_on_domain(domain: str, x_apikey: str, limit: int = None, cursor: str = None)", 975 """976 This function will retrieve comments on a specified domain.977 978 Args:979 - domain, string, required, Domain name980 - x-apikey, string, required, Your API key981 - limit, int32, optional, Maximum number of comments to retrieve982 - cursor, string, optional, Continuation cursor983 """), 984 ("vt_get_object_descriptors_related_to_domain(domain: str, relationship: str, x_apikey: str, limit: int = None, cursor: str = None)", 985 """986 This specifically returns related object's IDs (and context attributes, if any). Please note that this will not return all attributes. This will return objects relating to a domain.987 988 - caa_records: Records CAA for the domain. 989 - cname_records: Records CNAME for the domain. 990 - comments: Community posted comments about the domain. 991 - communicating_files: Files that communicate with the domain. 992 - downloaded_files: Files downloaded from that domain. 993 - graphs: All graphs that include the domain. 994 - historical_ssl_certificates: SSL certificates associated with the domain. 995 - historical_whois: WHOIS information for the domain. 996 - immediate_parent: Domain's immediate parent. 997 - mx_records: Records MX for the domain. 998 - ns_records: Records NS for the domain. 999 - parent: Domain's top parent. 1000 - referrer_files: Refers to any and all files that contain this domain. 1001 - related_comments: Community posted comments in the domain's related objects. 1002 - related_references: Refers to the References related to the domain. 1003 - related_threat_actors: Refers to the threat actors related to the domain. A list of Threat Actors.1004 - resolutions: DNS resolutions for the domain. 1005 - soa_records: Records SOA for the domain. 1006 - siblings: Refers to the Domain's sibling domains. 1007 - subdomains: Refers to the Domain's subdomains. 1008 - urls: Refers to the URLs that contain this domain. 1009 - user_votes: Refers to the current user's votes. 1010 1011 Args:1012 - domain: string, required, Domain name1013 - relationship: string, required, Relationship name (see table)1014 - x-apikey: string, required, Your API key1015 - limit: int32, optional, Maximum number of comments to retrieve1016 - cursor: string, optional, Continuation cursor1017 """), 1018 ("vt_get_objects_related_to_domain(domain: str, relationship: str, x_apikey: str, limit: int = None, cursor: str = None)",1019 """1020 Objects are a key concept in the VirusTotal API. Each object has an identifier and a type. 1021 Each object has an associated URL, and each domain is associated with objects.1022 This function returns ALL of the objects related to the domain, based on the specified relationship.1023 1024 The following describe the valid relationship:1025 - caa_records: Records CAA for the domain. 1026 - cname_records: Records CNAME for the domain. 1027 - comments: Community posted comments about the domain. 1028 - communicating_files: Files that communicate with the domain. 1029 - downloaded_files: Files downloaded from that domain. 1030 - graphs: All graphs that include the domain. 1031 - historical_ssl_certificates: SSL certificates associated with the domain. 1032 - historical_whois: WHOIS information for the domain. 1033 - immediate_parent: Domain's immediate parent. 1034 - mx_records: Records MX for the domain. 1035 - ns_records: Records NS for the domain. 1036 - parent: Domain's top parent. 1037 - referrer_files: Refers to any and all files that contain this domain. 1038 - related_comments: Community posted comments in the domain's related objects. 1039 - related_references: Refers to the References related to the domain. 1040 - related_threat_actors: Refers to the threat actors related to the domain. A list of Threat Actors.1041 - resolutions: DNS resolutions for the domain. 1042 - soa_records: Records SOA for the domain. 1043 - siblings: Refers to the Domain's sibling domains. 1044 - subdomains: Refers to the Domain's subdomains. 1045 - urls: Refers to the URLs that contain this domain. 1046 - user_votes: Refers to the current user's votes. 1047 1048 1049 Args:1050 - domain: string, required, Domain name1051 - relationship, string, required, Relationship name (see table)1052 - x-apikey, string, required, Your API key1053 - limit, int32, optional, Maximum number of comments to retrieve1054 - cursor, string, optional, Continuation cursor1055 """), 1056 ("vt_get_object_descriptors_related_to_ip_address(ip: str, relationship: str, x_apikey: str, limit: int = None, cursor: str = None)",1057 """1058 This specifically returns related object's IDs (and context attributes, if any). Please note that this will not return all attributes.1059 1060 You are expected to provide the relationship to the object you're interested in. The valid relationships are as follows.1061 1062 The relationships are documented here:1063 - comments: The comments for the IP address. 1064 - communicating_files: Files that communicate with the IP address. 1065 - downloaded_files: Files downloaded from the IP address. VT Enterprise users only. 1066 - graphs: Graphs including the IP address. 1067 - historical_ssl_certificates: SSL certificates associated with the IP. 1068 - historical_whois: WHOIS information for the IP address. Retrurns a list of Whois attributes.1069 - related_comments: Community posted comments in the IP's related objects. 1070 - related_references: Returns the references related to the IP address. 1071 - related_threat_actors: Threat actors related to the IP address. 1072 - referrer_files: Files containing the IP address. 1073 - resolutions: Resolves the IP addresses. 1074 - urls: Returns a list of URLs related to the IP address.1075 1076 Here are some useful descriptions of the arguments in this API, with the format - name of this argument: type of the data, required or optional, description of this argument.1077 - ip: string, required, IP address1078 - relationship: string, required, Relationship name (see table)1079 - x-apikey: string, required, Your API key1080 - limit: int32, optional, Maximum number of comments to retrieve1081 - cursor: string, optional, Continuation cursor1082 """), 1083 ("vt_add_comment_to_ip_address(ip: str, data: dict, x_apikey: str)",1084 """1085 With this function you can post a comment for a given IP address. The body for the POST request must be the JSON representation of a comment object. Notice however that you don't need to provide an ID for the object, as they are automatically generated for new comments.1086 However, please note that you will need to provide a valid data JSON for using this function.1087 1088 Any word starting with # in your comment's text will be considered a tag, and added to the comment's tag attribute.1089 1090 Returns a Comment object.1091 1092 Args:1093 - ip: string, required, IP address1094 - data: json, required, A comment object1095 - x-apikey: string, required, Your API key1096 """), 1097 ("vt_get_comments_on_ip_address(ip: str, x_apikey: str, limit: int = None, cursor: str = None)",1098 """1099 Retrieves the comments on a provided IP address. Returns a list of Comment objects.1100 1101 Args:1102 - ip, string, required, IP address1103 - x-apikey, string, required, Your API key1104 - limit, int32, optional, Maximum number of comments to retrieve1105 - cursor, string, optional, Continuation cursor1106 """), 1107 ("vt_get_domain_report(domain: str, x_apikey: str)",1108 """1109 Retrieves a domain report. These reports contain information regarding the domain itself that VirusTotal has collected.1110 1111 Args:1112 - domain: string, required, Domain name1113 - x-apikey: string, required, Your API key1114 """), 1115 ("vt_add_votes_to_ip_address(ip: str, data: dict, x_apikey: str)",1116 """1117 With this function you can post a vote for a given file. The body for the POST request must be the JSON representation of a vote object. Note however that you don't need to provide an ID for the object, as they are automatically generated for new votes. The verdict attribute must have be either harmless or malicious.1118 1119 Please ensure that the JSON object you provide conforms accurately to valid JSON standards.1120 1121 Args:1122 - ip, string, required, IP address1123 - data, json, Vote object1124 - x-apikey, string, required, Your API key1125 """), 1126 ("vt_get_ip_address_report(ip: str, x_apikey: str)", 1127 """1128 Retrieve an IP address report. These reports condense all of the recent activity that VirusTotal has seen for the resource under consideration, as well as contextual information about it.1129 This function specifically generates these reports using the IP address parameter. 1130 1131 Args:1132 - ip: string, required, IP address1133 - x-apikey: string, required, Your API key1134 """), 1135 ("vt_get_objects_related_to_ip_address(ip: str, relationship: str, x_apikey: str, limit: int = None, cursor: str = None)",1136 """1137 IP addresses have number of relationships to other objects. This returns ALL objects that fit the relationship.1138 1139 The relationships are documented here:1140 - comments: The comments for the IP address. Returns a list of comments. 1141 - communicating_files: Files that communicate with the IP address. Returns a list of files.1142 - downloaded_files: Files downloaded from the IP address. VT Enterprise users only. Returns a list of files.1143 - graphs: Graphs including the IP address. Returns a list of graphs.1144 - historical_ssl_certificates: SSL certificates associated with the IP. Returns a list of SSL certificates. 1145 - historical_whois: WHOIS information for the IP address. Retrurns a list of Whois attributes.1146 - related_comments: Community posted comments in the IP's related objects. Returns a list of comments.1147 - related_references: Returns the references related to the IP address. Returns a list of References.1148 - related_threat_actors: Threat actors related to the IP address. Returns a list of threat actors.1149 - referrer_files: Files containing the IP address. Returns a list of Files.1150 - resolutions: Resolves the IP addresses. Returns a list of resolutions.1151 - urls: Returns a list of URLs related to the IP address. Returns a list of URLs.1152 1153 Args:1154 - ip, string, required, IP address1155 - relationship, string, required, Relationship name (see the list of items from above)1156 - x-apikey, string, required, Your API key1157 - limit, int32, optional, Maximum number of comments to retrieve1158 - cursor, string, optional, Continuation cursor1159 """), 1160 ("vt_get_dns_resolution_object(id: str, x_apikey: str)",1161 """1162 This endpoint retrieves a Resolution object by its ID. A resolution object ID is made by appending the IP and the domain it resolves to together.1163 1164 Domain-IP resolutions. Resolution objects include the following attributes:1165 date: <integer> date when the resolution was made (UTC timestamp).1166 host_name: <string> domain or subdomain requested to the resolver.1167 host_name_last_analysis_stats: <dictionary> last detection stats from the resolution's domain. Similar to the domains's last_analysis_stats attribute.1168 ip_address: <string> IP address the domain was resolved to.1169 ip_address_last_analysis_stats: <dictionary> last detection stats from the resolution's IP address. Similar to the IP address' last_analysis_stats attribute.1170 resolver: <string> source of the resolution.1171 1172 Args:1173 - id: string, required, Resolution object ID1174 - x-apikey: string, required, Your API key1175 """)],1176"CVECPE_Multi_Dependency": [("mergeCPEs(list1: list, list2: list)",1177 """Combines two lists of CPEs into one. 1178 1179 Args: 1180 - list1 (list): List of CPEs. Each object in the list should contain a collection of CPEs. 1181 - list2 (list): Another list of CPEs. Each object in this list should also contain a collection of CPEs.1182 1183 Returns: 1184 - combined_list (list): A combined list of CPEs from both the input lists.1185 """1186 ),1187 ("mergeCVEs(list1: list, list2: list)", 1188 """This function takes two lists of objects each containing a collection of CVEs, and combines them into a single list. 1189 1190 Args: 1191 - list1 (list): First list of objects each holding details of a CVE. Each object in this list represents a CVE (Common Vulnerabilities and Exposures) in the format defined by the NVD (National Vulnerability Database). 1192 - list2 (list): Second list of objects each holding details of a CVE. Like list1, each object represents a CVE in the format defined by the NVD. 1193 1194 Returns: 1195 - list: A single list that combines all objects from list1 and list2. Hence, the resulting list is a collection of CVEs taken from both input lists.1196 """),1197 ("sortCPEsByLastMod(cpeList: list, descending: bool)", 1198 """Sorts a list of object collections of CPEs by their last modification time. 1199 1200 Args: