File size: 92,442 Bytes
ed063d7 551935e ed063d7 f9890fa ed063d7 46ca192 ed063d7 46ca192 ed063d7 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 |
# The natural language descriptions of different APIs
api_descriptions = {
"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.",
"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.",
"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.",
"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.",
"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.",
"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.",
"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.",
"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.",
"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."
}
func_definitions = {
"Climate": [("get_latitude_longitude(location: str)",
"""
Given a city name, this function provides the latitude and longitude of the specific location.
Args:
- location: This can be a city like 'Austin', or a place like 'Austin Airport', etc.
"""),
("get_current_location()",
"""
Returns the current location. ONLY use this if the user has not provided an explicit location in the query.
Returns a string representation of the city, such as "Austin". This will not return a latitude or longitude.
"""),
("find_nearby_stations(lat_long : tuple)",
"""
This endpoint provides a list of nearby weather stations for a given geographical location. Please provide the geographical location as a latitude and longitude.
Args:
- lat_long: This argument should be a tuple of the latitude as the first element and the longitude as the second element.
Returns:
- A list of dictionaries about the various stations near you.
"""),
("get_nearest_station_id(nearby_stations)",
"""
Given a list of nearby stations, returns the one nearest to you and provides the system ID for it alone.
Args:
- nearby_stations: A list of nearby stations in dictionary format.
Returns:
The station_id alone for the nearest station in the list of the stations provided.
"""),
("get_timezone(lat_long)",
"""
This gets the timezone for a given latlong.
Args:
- lat_long: The latitude and longitude of the area you want to query the timezone for.
"""),
("get_hourly_observation(station_id, start_time, end_time, time_zone)",
"""
Returns hourly observations between start_time and end_time.
Please ensure that the start and end times are provided in the format "YYYY-MM-DD".
Please provide the timezone for your input as well!
Args:
- station_id: The station_id for the station you're interested in
- start_time : The time span to start pulling hourly observations for. Should be in format of "YYYY-MM-DD".
- end_time: The time span to end pulling hourly observations for. Should be in format of "YYYY-MM-DD".
- timezone: The timezone string id for the location you're asking for.
Returns:
The list of hourly observations for your station and timespan.
"""),
("subtract_time_delta(date_time_str, delta_days)",
"""
Subtracts a time delta from the date part of a given date time string and returns
the new date string with the updated date.
DO NOT use this if delta_days is 0.
:param date_time_str: The date time string in format 'YYYY-MM-DD'.
:param delta_days: Number of days to subtract. HAS TO BE LARGER THAN 0.
:return: New date string with the updated date after subtracting the delta.
"""),
("get_current_time_at_location(lat_long)",
"""
Returns the current time at a given location.
Args:
- lat_long: The latitude and longitude of the location of interest.
""")],
"Heldout_Combined": [("", "")],
"Places_API": [("get_current_location()",
"""
Returns the current location. ONLY use this if the user has not provided an explicit location in the query.
"""),
("sort_results(places, sort: str, ascending: bool)",
"""
Sorts the results by either 'distance', 'rating' or 'price'.
Args
- places: The output list from the recommendations.
- sort (str): If set, sorts by either 'distance' or 'rating' or 'price'. ONLY supports 'distance' or 'rating' or 'price'.
- ascending (bool): If ascending is set, setting this boolean to true will sort the results by lower values first.
"""),
("get_latitude_longitude(location: str)",
"""
Given a city name, this function provides the latitude and longitude of the specific location.
Args
- location: This can be a city like 'Austin', or a place like 'Austin Airport', etc.
"""),
("get_distance(place_1: str, place_2: str)",
"""
Provides distance between two locations. Do NOT provide latitude longitude, but rather, provide the string descriptions.
Args
- place_1: The first location.
- place_2: The second location.
"""),
("get_recommendations(topics: list, lat_long: tuple)",
"""
Returns the recommendations for a specific topic that is of interest. Remember, a topic IS NOT an establishment. For establishments, please use anothher function.
Args
- topics (list): A list of topics of interest to pull recommendations for. Can be multiple words.
- lat_long (tuple): The lat_long of interest.
"""),
("find_places_near_location(type_of_place: list, location: str, radius_miles: int = 50)",
"""
Find places close to a very defined location.
Args
- 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.
- location (str): The location for the search. This can be a city's name, region, or anything that specifies the location.
- radius_miles (int): Optional. The max distance from the described location to limit the search. Distance is specified in miles.
"""),
("get_some_reviews(place_names: list, location: str = None)",
"""
Given an establishment (or place) name, return reviews about the establishment.
Args
- place_names (list): The name of the establishment. This should be a physical location name. You can provide multiple inputs.
- location (str) : The location where the restaurant is located. Optional argument.
""")],
"VT_Multi_Dependency": [("vt_validate_historical_ssl_certificates(historical_ssl_certificates: list, x_apikey: str)",
"""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.
Args:
- historical_ssl_certificates: list, required, List of SSL certificates in the history
- x_apikey: string, required, Your API key
"""),
("vt_get_threat_actors_main_source_region(threat_actors: list, x_apikey: str)",
"""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.
Args:
- threat_actors: list, required, List of threat actor objects
- x_apikey: string, required, Your API key.
"""),
("vt_get_threat_actors_latest_modification_date(threat_actor_objects: list, x_apikey: str)",
"""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.
Args:
- threat_actor_objects: list of objects, required, A list of threat actor objects.
- x_apikey: string, required, Your API key.
"""),
("convert_unix_timestamp_to_date(unix_timestamp: int)",
"""Converts a UNIX timestamp to a human-readable date in the format 'YYYY/MM/DD'.
Args:
- unix_timestamp: integer, required, The UNIX timestamp to be converted.
"""),
("vt_is_date_within_range(timestamp: int, start: str, end: str)",
"""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.
Args:
- timestamp: int, required, Unix timestamp
- start: string, optional, Start of the date range in 'YYYY/MM/DD' format
- end: string, optional, End of the date range in 'YYYY/MM/DD' format
"""),
("vt_get_last_analysis_date_from_report(report: dict)",
"""This function retrieves the last analysis date from the domain report collected by VirusTotal. The returned date is in Unix timestamp format.
Args:
- report: dict, required, The domain report collected by vt_get_domain_report function.
"""),
("vt_get_comments_on_multiple_domains(domains: list, x_apikey: str, limit: int, cursor: str)",
"""This function will retrieve comments for each specified domain in the given list.
Args:
- domains, list of strings, required, List of domain names
- x_apikey, string, required, Your API key
- limit, int32, optional, Maximum number of comments to retrieve for each domain
- cursor, string, optional, Continuation cursor
"""),
("vt_get_multiple_domain_reports(domains: list, x_apikey: str)",
"""retrieves reports for a list of domains provided. For each domain in the list, it requests the collected information regarding that domain from VirusTotal.
Args:
- domains: list of strings, required, A list of Domain names
- x_apikey: string, required, Your API key
"""),
("vt_get_majority_vote(votes: dict)",
"""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.
Args:
- votes: dictionary, required, dictionary of votes
"""),
("count_items_in_list(input_list: list)",
"""This function takes a list as an input and returns the number of items present in the list.
Args:
- input_list: list, required, List whose items are to be counted
"""),
("extract_resolution_date(dns_res_obj: object)",
"""Extracts the date of DNS resolution from a DNS resolution object. The date is returned as a Unix timestamp.
Args:
- dns_res_obj: object, required, The DNS resolution object from which the date of resolution is to be extracted.
"""),
("calculate_sum_of_numbers(num1: int, num2: int)",
"""Computes the sum of two numbers provided. Input numbers can be either integer or floating-point values.
Args:
- num1: Integer or Float, required, The first number
- num2: Integer or Float, required, The second number
"""),
("get_first_object_from_list(list_of_objects: list)",
"""Retrieves the first object from a given list. If the list is empty, it return `None`.
Args:
- list_of_objects: list, required, List containing objects from which the function will pick out the first object.
"""),
("get_random_object_from_list(list_of_objects: list)",
"""This function selects and returns a random object from a list of objects. It is designed to handle any list length, including empty lists.
Args:
- list_of_objects: list, required, List containing objects from which the function will pick out a random object.
"""),
("resolve_ip_to_domain_and_parent_domain(ip_address: str)",
"""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.
Args:
- ip_address (string, required): The IP address to be resolved. Returns:
- tuple: A tuple containing the domain and parent domain if resolution is successful; otherwise, None for both.
"""),
("extract_domain_and_parent_domain(url: str)",
"""Extracts the domain and parent domain from a given URL.
Args:
- url (string, required): The URL from which to extract the domain and parent domain.
Returns:
- tuple: A tuple containing the domain and parent domain.
"""),
("merge_two_lists(list1: list, list2: list)",
"""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.
Args:
- list1 (list, required): The first list of objects to be merged.
- list2 (list, required): The second list of objects to be merged.
Returns:
- list: A merged list containing elements from both input lists.
"""),
("vt_get_votes_on_ip_address(ip: str)", """
This function will retrieve votes on a provided IP address.
Args:
- ip: string, required, ip address
"""),
("vt_get_comments_on_domain(domain: str, x_apikey: str, limit: int = None, cursor: str = None)",
"""
This function will retrieve comments on a specified domain.
Args:
- domain, string, required, Domain name
- x-apikey, string, required, Your API key
- limit, int32, optional, Maximum number of comments to retrieve
- cursor, string, optional, Continuation cursor
"""),
("vt_get_object_descriptors_related_to_domain(domain: str, relationship: str, x_apikey: str, limit: int = None, cursor: str = None)",
"""
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.
- caa_records: Records CAA for the domain.
- cname_records: Records CNAME for the domain.
- comments: Community posted comments about the domain.
- communicating_files: Files that communicate with the domain.
- downloaded_files: Files downloaded from that domain.
- graphs: All graphs that include the domain.
- historical_ssl_certificates: SSL certificates associated with the domain.
- historical_whois: WHOIS information for the domain.
- immediate_parent: Domain's immediate parent.
- mx_records: Records MX for the domain.
- ns_records: Records NS for the domain.
- parent: Domain's top parent.
- referrer_files: Refers to any and all files that contain this domain.
- related_comments: Community posted comments in the domain's related objects.
- related_references: Refers to the References related to the domain.
- related_threat_actors: Refers to the threat actors related to the domain. A list of Threat Actors.
- resolutions: DNS resolutions for the domain.
- soa_records: Records SOA for the domain.
- siblings: Refers to the Domain's sibling domains.
- subdomains: Refers to the Domain's subdomains.
- urls: Refers to the URLs that contain this domain.
- user_votes: Refers to the current user's votes.
Args:
- domain: string, required, Domain name
- relationship: string, required, Relationship name (see table)
- x-apikey: string, required, Your API key
- limit: int32, optional, Maximum number of comments to retrieve
- cursor: string, optional, Continuation cursor
"""),
("vt_get_objects_related_to_domain(domain: str, relationship: str, x_apikey: str, limit: int = None, cursor: str = None)",
"""
Objects are a key concept in the VirusTotal API. Each object has an identifier and a type.
Each object has an associated URL, and each domain is associated with objects.
This function returns ALL of the objects related to the domain, based on the specified relationship.
The following describe the valid relationship:
- caa_records: Records CAA for the domain.
- cname_records: Records CNAME for the domain.
- comments: Community posted comments about the domain.
- communicating_files: Files that communicate with the domain.
- downloaded_files: Files downloaded from that domain.
- graphs: All graphs that include the domain.
- historical_ssl_certificates: SSL certificates associated with the domain.
- historical_whois: WHOIS information for the domain.
- immediate_parent: Domain's immediate parent.
- mx_records: Records MX for the domain.
- ns_records: Records NS for the domain.
- parent: Domain's top parent.
- referrer_files: Refers to any and all files that contain this domain.
- related_comments: Community posted comments in the domain's related objects.
- related_references: Refers to the References related to the domain.
- related_threat_actors: Refers to the threat actors related to the domain. A list of Threat Actors.
- resolutions: DNS resolutions for the domain.
- soa_records: Records SOA for the domain.
- siblings: Refers to the Domain's sibling domains.
- subdomains: Refers to the Domain's subdomains.
- urls: Refers to the URLs that contain this domain.
- user_votes: Refers to the current user's votes.
Args:
- domain: string, required, Domain name
- relationship, string, required, Relationship name (see table)
- x-apikey, string, required, Your API key
- limit, int32, optional, Maximum number of comments to retrieve
- cursor, string, optional, Continuation cursor
"""),
("vt_get_object_descriptors_related_to_ip_address(ip: str, relationship: str, x_apikey: str, limit: int = None, cursor: str = None)",
"""
This specifically returns related object's IDs (and context attributes, if any). Please note that this will not return all attributes.
You are expected to provide the relationship to the object you're interested in. The valid relationships are as follows.
The relationships are documented here:
- comments: The comments for the IP address.
- communicating_files: Files that communicate with the IP address.
- downloaded_files: Files downloaded from the IP address. VT Enterprise users only.
- graphs: Graphs including the IP address.
- historical_ssl_certificates: SSL certificates associated with the IP.
- historical_whois: WHOIS information for the IP address. Retrurns a list of Whois attributes.
- related_comments: Community posted comments in the IP's related objects.
- related_references: Returns the references related to the IP address.
- related_threat_actors: Threat actors related to the IP address.
- referrer_files: Files containing the IP address.
- resolutions: Resolves the IP addresses.
- urls: Returns a list of URLs related to the IP address.
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.
- ip: string, required, IP address
- relationship: string, required, Relationship name (see table)
- x-apikey: string, required, Your API key
- limit: int32, optional, Maximum number of comments to retrieve
- cursor: string, optional, Continuation cursor
"""),
("vt_add_comment_to_ip_address(ip: str, data: dict, x_apikey: str)",
"""
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.
However, please note that you will need to provide a valid data JSON for using this function.
Any word starting with # in your comment's text will be considered a tag, and added to the comment's tag attribute.
Returns a Comment object.
Args:
- ip: string, required, IP address
- data: json, required, A comment object
- x-apikey: string, required, Your API key
"""),
("vt_get_comments_on_ip_address(ip: str, x_apikey: str, limit: int = None, cursor: str = None)",
"""
Retrieves the comments on a provided IP address. Returns a list of Comment objects.
Args:
- ip, string, required, IP address
- x-apikey, string, required, Your API key
- limit, int32, optional, Maximum number of comments to retrieve
- cursor, string, optional, Continuation cursor
"""),
("vt_get_domain_report(domain: str, x_apikey: str)",
"""
Retrieves a domain report. These reports contain information regarding the domain itself that VirusTotal has collected.
Args:
- domain: string, required, Domain name
- x-apikey: string, required, Your API key
"""),
("vt_add_votes_to_ip_address(ip: str, data: dict, x_apikey: str)",
"""
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.
Please ensure that the JSON object you provide conforms accurately to valid JSON standards.
Args:
- ip, string, required, IP address
- data, json, Vote object
- x-apikey, string, required, Your API key
"""),
("vt_get_ip_address_report(ip: str, x_apikey: str)",
"""
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.
This function specifically generates these reports using the IP address parameter.
Args:
- ip: string, required, IP address
- x-apikey: string, required, Your API key
"""),
("vt_get_objects_related_to_ip_address(ip: str, relationship: str, x_apikey: str, limit: int = None, cursor: str = None)",
"""
IP addresses have number of relationships to other objects. This returns ALL objects that fit the relationship.
The relationships are documented here:
- comments: The comments for the IP address. Returns a list of comments.
- communicating_files: Files that communicate with the IP address. Returns a list of files.
- downloaded_files: Files downloaded from the IP address. VT Enterprise users only. Returns a list of files.
- graphs: Graphs including the IP address. Returns a list of graphs.
- historical_ssl_certificates: SSL certificates associated with the IP. Returns a list of SSL certificates.
- historical_whois: WHOIS information for the IP address. Retrurns a list of Whois attributes.
- related_comments: Community posted comments in the IP's related objects. Returns a list of comments.
- related_references: Returns the references related to the IP address. Returns a list of References.
- related_threat_actors: Threat actors related to the IP address. Returns a list of threat actors.
- referrer_files: Files containing the IP address. Returns a list of Files.
- resolutions: Resolves the IP addresses. Returns a list of resolutions.
- urls: Returns a list of URLs related to the IP address. Returns a list of URLs.
Args:
- ip, string, required, IP address
- relationship, string, required, Relationship name (see the list of items from above)
- x-apikey, string, required, Your API key
- limit, int32, optional, Maximum number of comments to retrieve
- cursor, string, optional, Continuation cursor
"""),
("vt_get_dns_resolution_object(id: str, x_apikey: str)",
"""
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.
Domain-IP resolutions. Resolution objects include the following attributes:
date: <integer> date when the resolution was made (UTC timestamp).
host_name: <string> domain or subdomain requested to the resolver.
host_name_last_analysis_stats: <dictionary> last detection stats from the resolution's domain. Similar to the domains's last_analysis_stats attribute.
ip_address: <string> IP address the domain was resolved to.
ip_address_last_analysis_stats: <dictionary> last detection stats from the resolution's IP address. Similar to the IP address' last_analysis_stats attribute.
resolver: <string> source of the resolution.
Args:
- id: string, required, Resolution object ID
- x-apikey: string, required, Your API key
""")],
"VT_Multi_Disconnected": [("vt_validate_historical_ssl_certificates(historical_ssl_certificates: list, x_apikey: str)",
"""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.
Args:
- historical_ssl_certificates: list, required, List of SSL certificates in the history
- x_apikey: string, required, Your API key
"""),
("vt_get_threat_actors_main_source_region(threat_actors: list, x_apikey: str)",
"""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.
Args:
- threat_actors: list, required, List of threat actor objects
- x_apikey: string, required, Your API key.
"""),
("vt_get_threat_actors_latest_modification_date(threat_actor_objects: list, x_apikey: str)",
"""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.
Args:
- threat_actor_objects: list of objects, required, A list of threat actor objects.
- x_apikey: string, required, Your API key.
"""),
("convert_unix_timestamp_to_date(unix_timestamp: int)",
"""Converts a UNIX timestamp to a human-readable date in the format 'YYYY/MM/DD'.
Args:
- unix_timestamp: integer, required, The UNIX timestamp to be converted.
"""),
("vt_is_date_within_range(timestamp: int, start: str, end: str)",
"""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.
Args:
- timestamp: int, required, Unix timestamp
- start: string, optional, Start of the date range in 'YYYY/MM/DD' format
- end: string, optional, End of the date range in 'YYYY/MM/DD' format
"""),
("vt_get_last_analysis_date_from_report(report: dict)",
"""This function retrieves the last analysis date from the domain report collected by VirusTotal. The returned date is in Unix timestamp format.
Args:
- report: dict, required, The domain report collected by vt_get_domain_report function.
"""),
("vt_get_comments_on_multiple_domains(domains: list, x_apikey: str, limit: int, cursor: str)",
"""This function will retrieve comments for each specified domain in the given list.
Args:
- domains, list of strings, required, List of domain names
- x_apikey, string, required, Your API key
- limit, int32, optional, Maximum number of comments to retrieve for each domain
- cursor, string, optional, Continuation cursor
"""),
("vt_get_multiple_domain_reports(domains: list, x_apikey: str)",
"""retrieves reports for a list of domains provided. For each domain in the list, it requests the collected information regarding that domain from VirusTotal.
Args:
- domains: list of strings, required, A list of Domain names
- x_apikey: string, required, Your API key
"""),
("vt_get_majority_vote(votes: dict)",
"""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.
Args:
- votes: dictionary, required, dictionary of votes
"""),
("count_items_in_list(input_list: list)",
"""This function takes a list as an input and returns the number of items present in the list.
Args:
- input_list: list, required, List whose items are to be counted
"""),
("extract_resolution_date(dns_res_obj: object)",
"""Extracts the date of DNS resolution from a DNS resolution object. The date is returned as a Unix timestamp.
Args:
- dns_res_obj: object, required, The DNS resolution object from which the date of resolution is to be extracted.
"""),
("calculate_sum_of_numbers(num1: int, num2: int)",
"""Computes the sum of two numbers provided. Input numbers can be either integer or floating-point values.
Args:
- num1: Integer or Float, required, The first number
- num2: Integer or Float, required, The second number
"""),
("get_first_object_from_list(list_of_objects: list)",
"""Retrieves the first object from a given list. If the list is empty, it return `None`.
Args:
- list_of_objects: list, required, List containing objects from which the function will pick out the first object.
"""),
("get_random_object_from_list(list_of_objects: list)",
"""This function selects and returns a random object from a list of objects. It is designed to handle any list length, including empty lists.
Args:
- list_of_objects: list, required, List containing objects from which the function will pick out a random object.
"""),
("resolve_ip_to_domain_and_parent_domain(ip_address: str)",
"""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.
Args:
- ip_address (string, required): The IP address to be resolved. Returns:
- tuple: A tuple containing the domain and parent domain if resolution is successful; otherwise, None for both.
"""),
("extract_domain_and_parent_domain(url: str)",
"""Extracts the domain and parent domain from a given URL.
Args:
- url (string, required): The URL from which to extract the domain and parent domain.
Returns:
- tuple: A tuple containing the domain and parent domain.
"""),
("merge_two_lists(list1: list, list2: list)",
"""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.
Args:
- list1 (list, required): The first list of objects to be merged.
- list2 (list, required): The second list of objects to be merged.
Returns:
- list: A merged list containing elements from both input lists.
"""),
("vt_get_votes_on_ip_address(ip: str)", """
This function will retrieve votes on a provided IP address.
Args:
- ip: string, required, ip address
"""),
("vt_get_comments_on_domain(domain: str, x_apikey: str, limit: int = None, cursor: str = None)",
"""
This function will retrieve comments on a specified domain.
Args:
- domain, string, required, Domain name
- x-apikey, string, required, Your API key
- limit, int32, optional, Maximum number of comments to retrieve
- cursor, string, optional, Continuation cursor
"""),
("vt_get_object_descriptors_related_to_domain(domain: str, relationship: str, x_apikey: str, limit: int = None, cursor: str = None)",
"""
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.
- caa_records: Records CAA for the domain.
- cname_records: Records CNAME for the domain.
- comments: Community posted comments about the domain.
- communicating_files: Files that communicate with the domain.
- downloaded_files: Files downloaded from that domain.
- graphs: All graphs that include the domain.
- historical_ssl_certificates: SSL certificates associated with the domain.
- historical_whois: WHOIS information for the domain.
- immediate_parent: Domain's immediate parent.
- mx_records: Records MX for the domain.
- ns_records: Records NS for the domain.
- parent: Domain's top parent.
- referrer_files: Refers to any and all files that contain this domain.
- related_comments: Community posted comments in the domain's related objects.
- related_references: Refers to the References related to the domain.
- related_threat_actors: Refers to the threat actors related to the domain. A list of Threat Actors.
- resolutions: DNS resolutions for the domain.
- soa_records: Records SOA for the domain.
- siblings: Refers to the Domain's sibling domains.
- subdomains: Refers to the Domain's subdomains.
- urls: Refers to the URLs that contain this domain.
- user_votes: Refers to the current user's votes.
Args:
- domain: string, required, Domain name
- relationship: string, required, Relationship name (see table)
- x-apikey: string, required, Your API key
- limit: int32, optional, Maximum number of comments to retrieve
- cursor: string, optional, Continuation cursor
"""),
("vt_get_objects_related_to_domain(domain: str, relationship: str, x_apikey: str, limit: int = None, cursor: str = None)",
"""
Objects are a key concept in the VirusTotal API. Each object has an identifier and a type.
Each object has an associated URL, and each domain is associated with objects.
This function returns ALL of the objects related to the domain, based on the specified relationship.
The following describe the valid relationship:
- caa_records: Records CAA for the domain.
- cname_records: Records CNAME for the domain.
- comments: Community posted comments about the domain.
- communicating_files: Files that communicate with the domain.
- downloaded_files: Files downloaded from that domain.
- graphs: All graphs that include the domain.
- historical_ssl_certificates: SSL certificates associated with the domain.
- historical_whois: WHOIS information for the domain.
- immediate_parent: Domain's immediate parent.
- mx_records: Records MX for the domain.
- ns_records: Records NS for the domain.
- parent: Domain's top parent.
- referrer_files: Refers to any and all files that contain this domain.
- related_comments: Community posted comments in the domain's related objects.
- related_references: Refers to the References related to the domain.
- related_threat_actors: Refers to the threat actors related to the domain. A list of Threat Actors.
- resolutions: DNS resolutions for the domain.
- soa_records: Records SOA for the domain.
- siblings: Refers to the Domain's sibling domains.
- subdomains: Refers to the Domain's subdomains.
- urls: Refers to the URLs that contain this domain.
- user_votes: Refers to the current user's votes.
Args:
- domain: string, required, Domain name
- relationship, string, required, Relationship name (see table)
- x-apikey, string, required, Your API key
- limit, int32, optional, Maximum number of comments to retrieve
- cursor, string, optional, Continuation cursor
"""),
("vt_get_object_descriptors_related_to_ip_address(ip: str, relationship: str, x_apikey: str, limit: int = None, cursor: str = None)",
"""
This specifically returns related object's IDs (and context attributes, if any). Please note that this will not return all attributes.
You are expected to provide the relationship to the object you're interested in. The valid relationships are as follows.
The relationships are documented here:
- comments: The comments for the IP address.
- communicating_files: Files that communicate with the IP address.
- downloaded_files: Files downloaded from the IP address. VT Enterprise users only.
- graphs: Graphs including the IP address.
- historical_ssl_certificates: SSL certificates associated with the IP.
- historical_whois: WHOIS information for the IP address. Retrurns a list of Whois attributes.
- related_comments: Community posted comments in the IP's related objects.
- related_references: Returns the references related to the IP address.
- related_threat_actors: Threat actors related to the IP address.
- referrer_files: Files containing the IP address.
- resolutions: Resolves the IP addresses.
- urls: Returns a list of URLs related to the IP address.
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.
- ip: string, required, IP address
- relationship: string, required, Relationship name (see table)
- x-apikey: string, required, Your API key
- limit: int32, optional, Maximum number of comments to retrieve
- cursor: string, optional, Continuation cursor
"""),
("vt_add_comment_to_ip_address(ip: str, data: dict, x_apikey: str)",
"""
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.
However, please note that you will need to provide a valid data JSON for using this function.
Any word starting with # in your comment's text will be considered a tag, and added to the comment's tag attribute.
Returns a Comment object.
Args:
- ip: string, required, IP address
- data: json, required, A comment object
- x-apikey: string, required, Your API key
"""),
("vt_get_comments_on_ip_address(ip: str, x_apikey: str, limit: int = None, cursor: str = None)",
"""
Retrieves the comments on a provided IP address. Returns a list of Comment objects.
Args:
- ip, string, required, IP address
- x-apikey, string, required, Your API key
- limit, int32, optional, Maximum number of comments to retrieve
- cursor, string, optional, Continuation cursor
"""),
("vt_get_domain_report(domain: str, x_apikey: str)",
"""
Retrieves a domain report. These reports contain information regarding the domain itself that VirusTotal has collected.
Args:
- domain: string, required, Domain name
- x-apikey: string, required, Your API key
"""),
("vt_add_votes_to_ip_address(ip: str, data: dict, x_apikey: str)",
"""
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.
Please ensure that the JSON object you provide conforms accurately to valid JSON standards.
Args:
- ip, string, required, IP address
- data, json, Vote object
- x-apikey, string, required, Your API key
"""),
("vt_get_ip_address_report(ip: str, x_apikey: str)",
"""
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.
This function specifically generates these reports using the IP address parameter.
Args:
- ip: string, required, IP address
- x-apikey: string, required, Your API key
"""),
("vt_get_objects_related_to_ip_address(ip: str, relationship: str, x_apikey: str, limit: int = None, cursor: str = None)",
"""
IP addresses have number of relationships to other objects. This returns ALL objects that fit the relationship.
The relationships are documented here:
- comments: The comments for the IP address. Returns a list of comments.
- communicating_files: Files that communicate with the IP address. Returns a list of files.
- downloaded_files: Files downloaded from the IP address. VT Enterprise users only. Returns a list of files.
- graphs: Graphs including the IP address. Returns a list of graphs.
- historical_ssl_certificates: SSL certificates associated with the IP. Returns a list of SSL certificates.
- historical_whois: WHOIS information for the IP address. Retrurns a list of Whois attributes.
- related_comments: Community posted comments in the IP's related objects. Returns a list of comments.
- related_references: Returns the references related to the IP address. Returns a list of References.
- related_threat_actors: Threat actors related to the IP address. Returns a list of threat actors.
- referrer_files: Files containing the IP address. Returns a list of Files.
- resolutions: Resolves the IP addresses. Returns a list of resolutions.
- urls: Returns a list of URLs related to the IP address. Returns a list of URLs.
Args:
- ip, string, required, IP address
- relationship, string, required, Relationship name (see the list of items from above)
- x-apikey, string, required, Your API key
- limit, int32, optional, Maximum number of comments to retrieve
- cursor, string, optional, Continuation cursor
"""),
("vt_get_dns_resolution_object(id: str, x_apikey: str)",
"""
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.
Domain-IP resolutions. Resolution objects include the following attributes:
date: <integer> date when the resolution was made (UTC timestamp).
host_name: <string> domain or subdomain requested to the resolver.
host_name_last_analysis_stats: <dictionary> last detection stats from the resolution's domain. Similar to the domains's last_analysis_stats attribute.
ip_address: <string> IP address the domain was resolved to.
ip_address_last_analysis_stats: <dictionary> last detection stats from the resolution's IP address. Similar to the IP address' last_analysis_stats attribute.
resolver: <string> source of the resolution.
Args:
- id: string, required, Resolution object ID
- x-apikey: string, required, Your API key
""")],
"OTX": [("getIndicatorForIPv4(apiKey: str, ip: str, section: str)",
"""
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.
Args:
- apiKey: string, required, Your AlienVault API key
- ip: string, required, IPv4 address to query
- section: string, required, Specific data section to retrieve (options: general, reputation, geo, malware, urlList, passiveDns)
"""),
("getIndicatorForIPv6(apiKey: str, ip: str, section: str)",
"""
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.
Args:
- apiKey: string, required, Your AlienVault API key
- ip: string, required, IPv6 address to query
- section: string, required, Specific data section to retrieve (options: general, reputation, geo, malware, urlList, passiveDns)
"""),
("getIndicatorForDomain(apiKey: str, domain: str, section: str)",
"""
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.
Args:
- apiKey: string, required, Your AlienVault API key
- domain: string, required, Domain address to query
- section: string, required, Specific data section to retrieve (options: general, geo, malware, urlList, passiveDns, whois)
"""),
("getIndicatorForHostname(apiKey: str, hostname: str, section: str)",
"""
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.
Args:
- apiKey: string, required, Your AlienVault API key
- hostname: string, required, Single hostname address to query
- section: string, required, Specific data section to retrieve (options: general, geo, malware, urlList, passiveDns)
"""),
("getIndicatorForFileHashes(apiKey: str, fileHash: str, section: str)",
"""
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.
Args:
- apiKey: string, required, Your AlienVault API key
- fileHash: string, required, Single file hash to query
- section: string, required, Specific data section to retrieve (options: general, analysis)
"""),
("getIndicatorForUrl(apiKey: str, url: str, section: str)",
"""
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.
Args:
- apiKey: string, required, Your AlienVault API key
- url: string, required, Single URL to query
- section: string, required, Specific data section to retrieve (options: general, url_list)
"""),
("getIndicatorForCVE(apiKey: str, cve: str, section: str)",
"""
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.
Args:
- apiKey: string, required, Your AlienVault API key
- cve: string, required, Specific CVE identifier to query (e.g., 'CVE-2014-0160')
- section: string, required, Specific data section to retrieve ('general' only)
"""),
("getIndicatorForNIDS(apiKey: str, nids: str, section: str)",
"""
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.
Args:
- apiKey: string, required, Your AlienVault API key
- nids: string, required, Specific NIDS indicator to query (e.g., '2820184')
- section: string, required, Specific data section to retrieve ('general' only)
"""),
("getIndicatorForCorrelationRules(apiKey: str, correlationRule: str, section: str)",
"""
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.
Args:
- apiKey: string, required, Your AlienVault API key
- correlationRule: string, required, Specific Correlation Rule identifier to query (e.g., '572f8c3c540c6f0161677877')
- section: string, required, Specific data section to retrieve ('general' only)
""")],
"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)",
"""
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/vulnerabilities
Args:
- 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.
- cveId (str): Please pass in a string integer, like "1" or "30". Returns a single CVE that already exists in the NVD.
- 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.
- cvssV2Severity (str): Find vulnerabilities having a LOW, MEDIUM, or HIGH version 2 severity.
- 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.
- cvssV3Severity (str): Find vulnerabilities having a LOW, MEDIUM, HIGH, or CRITICAL version 3 severity.
- 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.
- hasCertAlerts (bool): Returns CVE that contain a Technical Alert from US-CERT.
- hasCertNotes (bool): Returns CVE that contain a Vulnerability Note from CERT/CC.
- 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).
- 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.
- 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.
- 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.
- 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.
- lastModEndDate (str, datetime obj): Required if using lastModStartDate.
- noRejected (bool): Filters out all CVEs that are in a reject or rejected status. Searches without this parameter include rejected CVEs.
- 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.
- pubEndDate (str, datetime obj): Required if using pubStartDate.
- sourceIdentifier (str): Returns CVE where the data source of the CVE is the value that is passed to sourceIdentifier.
- versionEnd (str): Must be combined with versionEndType and virtualMatchString. Returns only the CVEs associated with CPEs in specific version ranges.
- 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.
- 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.
- 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.
- 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.
- limit (int): Custom argument to limit the number of results of the search. Allowed any number between 1 and 2000.
- 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.
- 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.
- verbose (bool): Prints the URL request for debugging purposes.
"""),
("searchCPE(cpeNameId: str, cpeMatchString: str, keywordExactMatch: bool, keywordSearch: str, lastModStartDate: str, lastModEndDate: str, matchCriteriaId: str, limit: int, key: str, delay: int, verbose: bool)",
"""
Build and send GET request then return list of objects containing a collection of CPEs.
Args:
- 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.
- cpeMatchString (str) Use a partial CPE name to search for other CPE names.
- 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.
- 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.
- 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'
- lastModEndDate (str/datetime obj) CPE last modification end date. Maximum 120 day range. Must be included with lastModStartDate. Example: ‘2020-06-28 00:00’
- limit (int) Limits the number of results of the search.
- key (str) NVD API Key. Allows for a request every 0.6 seconds instead of 6 seconds.
- 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.
- verbose (bool) Prints the URL request for debugging purposes.
""")],
"VirusTotal": [("vt_get_votes_on_ip_address(ip: str)", """
This function will retrieve votes on a provided IP address.
Args:
- ip: string, required, ip address
"""),
("vt_get_comments_on_domain(domain: str, x_apikey: str, limit: int = None, cursor: str = None)",
"""
This function will retrieve comments on a specified domain.
Args:
- domain, string, required, Domain name
- x-apikey, string, required, Your API key
- limit, int32, optional, Maximum number of comments to retrieve
- cursor, string, optional, Continuation cursor
"""),
("vt_get_object_descriptors_related_to_domain(domain: str, relationship: str, x_apikey: str, limit: int = None, cursor: str = None)",
"""
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.
- caa_records: Records CAA for the domain.
- cname_records: Records CNAME for the domain.
- comments: Community posted comments about the domain.
- communicating_files: Files that communicate with the domain.
- downloaded_files: Files downloaded from that domain.
- graphs: All graphs that include the domain.
- historical_ssl_certificates: SSL certificates associated with the domain.
- historical_whois: WHOIS information for the domain.
- immediate_parent: Domain's immediate parent.
- mx_records: Records MX for the domain.
- ns_records: Records NS for the domain.
- parent: Domain's top parent.
- referrer_files: Refers to any and all files that contain this domain.
- related_comments: Community posted comments in the domain's related objects.
- related_references: Refers to the References related to the domain.
- related_threat_actors: Refers to the threat actors related to the domain. A list of Threat Actors.
- resolutions: DNS resolutions for the domain.
- soa_records: Records SOA for the domain.
- siblings: Refers to the Domain's sibling domains.
- subdomains: Refers to the Domain's subdomains.
- urls: Refers to the URLs that contain this domain.
- user_votes: Refers to the current user's votes.
Args:
- domain: string, required, Domain name
- relationship: string, required, Relationship name (see table)
- x-apikey: string, required, Your API key
- limit: int32, optional, Maximum number of comments to retrieve
- cursor: string, optional, Continuation cursor
"""),
("vt_get_objects_related_to_domain(domain: str, relationship: str, x_apikey: str, limit: int = None, cursor: str = None)",
"""
Objects are a key concept in the VirusTotal API. Each object has an identifier and a type.
Each object has an associated URL, and each domain is associated with objects.
This function returns ALL of the objects related to the domain, based on the specified relationship.
The following describe the valid relationship:
- caa_records: Records CAA for the domain.
- cname_records: Records CNAME for the domain.
- comments: Community posted comments about the domain.
- communicating_files: Files that communicate with the domain.
- downloaded_files: Files downloaded from that domain.
- graphs: All graphs that include the domain.
- historical_ssl_certificates: SSL certificates associated with the domain.
- historical_whois: WHOIS information for the domain.
- immediate_parent: Domain's immediate parent.
- mx_records: Records MX for the domain.
- ns_records: Records NS for the domain.
- parent: Domain's top parent.
- referrer_files: Refers to any and all files that contain this domain.
- related_comments: Community posted comments in the domain's related objects.
- related_references: Refers to the References related to the domain.
- related_threat_actors: Refers to the threat actors related to the domain. A list of Threat Actors.
- resolutions: DNS resolutions for the domain.
- soa_records: Records SOA for the domain.
- siblings: Refers to the Domain's sibling domains.
- subdomains: Refers to the Domain's subdomains.
- urls: Refers to the URLs that contain this domain.
- user_votes: Refers to the current user's votes.
Args:
- domain: string, required, Domain name
- relationship, string, required, Relationship name (see table)
- x-apikey, string, required, Your API key
- limit, int32, optional, Maximum number of comments to retrieve
- cursor, string, optional, Continuation cursor
"""),
("vt_get_object_descriptors_related_to_ip_address(ip: str, relationship: str, x_apikey: str, limit: int = None, cursor: str = None)",
"""
This specifically returns related object's IDs (and context attributes, if any). Please note that this will not return all attributes.
You are expected to provide the relationship to the object you're interested in. The valid relationships are as follows.
The relationships are documented here:
- comments: The comments for the IP address.
- communicating_files: Files that communicate with the IP address.
- downloaded_files: Files downloaded from the IP address. VT Enterprise users only.
- graphs: Graphs including the IP address.
- historical_ssl_certificates: SSL certificates associated with the IP.
- historical_whois: WHOIS information for the IP address. Retrurns a list of Whois attributes.
- related_comments: Community posted comments in the IP's related objects.
- related_references: Returns the references related to the IP address.
- related_threat_actors: Threat actors related to the IP address.
- referrer_files: Files containing the IP address.
- resolutions: Resolves the IP addresses.
- urls: Returns a list of URLs related to the IP address.
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.
- ip: string, required, IP address
- relationship: string, required, Relationship name (see table)
- x-apikey: string, required, Your API key
- limit: int32, optional, Maximum number of comments to retrieve
- cursor: string, optional, Continuation cursor
"""),
("vt_add_comment_to_ip_address(ip: str, data: dict, x_apikey: str)",
"""
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.
However, please note that you will need to provide a valid data JSON for using this function.
Any word starting with # in your comment's text will be considered a tag, and added to the comment's tag attribute.
Returns a Comment object.
Args:
- ip: string, required, IP address
- data: json, required, A comment object
- x-apikey: string, required, Your API key
"""),
("vt_get_comments_on_ip_address(ip: str, x_apikey: str, limit: int = None, cursor: str = None)",
"""
Retrieves the comments on a provided IP address. Returns a list of Comment objects.
Args:
- ip, string, required, IP address
- x-apikey, string, required, Your API key
- limit, int32, optional, Maximum number of comments to retrieve
- cursor, string, optional, Continuation cursor
"""),
("vt_get_domain_report(domain: str, x_apikey: str)",
"""
Retrieves a domain report. These reports contain information regarding the domain itself that VirusTotal has collected.
Args:
- domain: string, required, Domain name
- x-apikey: string, required, Your API key
"""),
("vt_add_votes_to_ip_address(ip: str, data: dict, x_apikey: str)",
"""
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.
Please ensure that the JSON object you provide conforms accurately to valid JSON standards.
Args:
- ip, string, required, IP address
- data, json, Vote object
- x-apikey, string, required, Your API key
"""),
("vt_get_ip_address_report(ip: str, x_apikey: str)",
"""
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.
This function specifically generates these reports using the IP address parameter.
Args:
- ip: string, required, IP address
- x-apikey: string, required, Your API key
"""),
("vt_get_objects_related_to_ip_address(ip: str, relationship: str, x_apikey: str, limit: int = None, cursor: str = None)",
"""
IP addresses have number of relationships to other objects. This returns ALL objects that fit the relationship.
The relationships are documented here:
- comments: The comments for the IP address. Returns a list of comments.
- communicating_files: Files that communicate with the IP address. Returns a list of files.
- downloaded_files: Files downloaded from the IP address. VT Enterprise users only. Returns a list of files.
- graphs: Graphs including the IP address. Returns a list of graphs.
- historical_ssl_certificates: SSL certificates associated with the IP. Returns a list of SSL certificates.
- historical_whois: WHOIS information for the IP address. Retrurns a list of Whois attributes.
- related_comments: Community posted comments in the IP's related objects. Returns a list of comments.
- related_references: Returns the references related to the IP address. Returns a list of References.
- related_threat_actors: Threat actors related to the IP address. Returns a list of threat actors.
- referrer_files: Files containing the IP address. Returns a list of Files.
- resolutions: Resolves the IP addresses. Returns a list of resolutions.
- urls: Returns a list of URLs related to the IP address. Returns a list of URLs.
Args:
- ip, string, required, IP address
- relationship, string, required, Relationship name (see the list of items from above)
- x-apikey, string, required, Your API key
- limit, int32, optional, Maximum number of comments to retrieve
- cursor, string, optional, Continuation cursor
"""),
("vt_get_dns_resolution_object(id: str, x_apikey: str)",
"""
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.
Domain-IP resolutions. Resolution objects include the following attributes:
date: <integer> date when the resolution was made (UTC timestamp).
host_name: <string> domain or subdomain requested to the resolver.
host_name_last_analysis_stats: <dictionary> last detection stats from the resolution's domain. Similar to the domains's last_analysis_stats attribute.
ip_address: <string> IP address the domain was resolved to.
ip_address_last_analysis_stats: <dictionary> last detection stats from the resolution's IP address. Similar to the IP address' last_analysis_stats attribute.
resolver: <string> source of the resolution.
Args:
- id: string, required, Resolution object ID
- x-apikey: string, required, Your API key
""")],
"CVECPE_Multi_Dependency": [("mergeCPEs(list1: list, list2: list)",
"""Combines two lists of CPEs into one.
Args:
- list1 (list): List of CPEs. Each object in the list should contain a collection of CPEs.
- list2 (list): Another list of CPEs. Each object in this list should also contain a collection of CPEs.
Returns:
- combined_list (list): A combined list of CPEs from both the input lists.
"""
),
("mergeCVEs(list1: list, list2: list)",
"""This function takes two lists of objects each containing a collection of CVEs, and combines them into a single list.
Args:
- 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).
- 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.
Returns:
- 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.
"""),
("sortCPEsByLastMod(cpeList: list, descending: bool)",
"""Sorts a list of object collections of CPEs by their last modification time.
Args:
- cpeList (list): The list of object collections of CPEs that need to be sorted. Each object collection has a lastModified field.
- descending (bool): Determines the order of sort. If True, CPEs will be sorted in descending order of 'last modification time'. If False, the sorting will be in ascending order. Default value is True.
Returns:
- List of object collections of CPEs sorted by the lastModified field.
"""),
("filterDeprecatedCPEs(cpeList: list)",
"""Loop through the CPE objects in the list and return the ones that are not deprecated.
Args:
- cpeList (list): A list of CPE objects. Each CPE object has a 'deprecated' key. If the value of this key is False, it means the CPE object is not deprecated.
Returns:
- cpeList (list): This function will return a list of non-deprecated CPE objects."""),
("filterCVEsBySeverity(cveList: list, severityLevel: str)",
"""Returns a list of CVE objects from the given collection that have the provided severity level.
Args:
- cveList: list, required, List of objects containing a collection of CVEs. Each CVE object is expected to have 'cvssV2Severity' and/or 'cvssV3Severity' properties reflecting the severity level of the vulnerability.
- severityLevel: str, required, The severity level with which to filter the CVEs. Accepts 'LOW', 'MEDIUM', 'HIGH' for both 'cvssV2Severity' and 'cvssV3Severity', and 'CRITICAL' for 'cvssV3Severity' only.
Returns:
- matchingCVEs: list, Only the objects from the given CVE list that have the provided severity level."""),
("filterCVEByLanguage(cve_list: list, language: str)",
"""Filters a collection of CVE (Common Vulnerabilities and Exposures) objects and returns a list of the ones that have descriptions for a specific language.
Args:
- cve_list (list): A list of CVE objects. Each object should contain information about a particular CVE, including its description available in various languages.
- language (str): Language code for which the function will check in the description field of the CVE objects. This must follow the ISO 639-1 language codes, such as 'en' for English, 'es' for Spanish, and 'de' for German, etc.
Returns:
- A list of CVE objects from the original collection that contain a description in the specified language. If no matching CVE objects are found, returns an empty list."""),
("sortCVEsByModDate(cve_list: list, descending: bool)",
"""This function sorts a list of CVE objects by their last modification date.
Args:
- cve_list (list of CVE objects): A required list of CVE objects. Each object should at least have a property for last modification date.
- descending (bool, optional): If set to True, the list will be sorted in descending order (most recently modified first). Defaults to True.
Returns:
- list of CVE objects: Sorted list of CVE objects."""),
("sortCVEsByCVSSv2Score(cve_list: list, descending: bool)",
"""Accepts a list of CVE objects and sorts them by their CVSS Version 2.0 base scores. If a CVE object does not contain a CVSS v2 score, it is assumed to have the lowest possible score (i.e., 0).
Args:
- cve_list (list): List of CVE objects, where each object contains details such as CVE identifier, CVSS v2 and v3 scores, etc.
- descending (bool, optional): If set to True, the list will be sorted in descending order (highest CVSSv2Score first). Defaults to True.
Returns:
- list: The input list of CVEs sorted in decreasing order of their CVSS Version 2.0 base scores."""),
("sortCVEsByCVSSv3Score(cve_list: list, descending: bool)",
"""Accepts a list of CVE objects and sorts them by their CVSS Version 3.x base scores. If a CVE object does not contain a CVSS v3 score, it is assumed to have the lowest possible score (i.e., 0).
Args:
- cve_list (list): List of CVE objects, where each object contains details such as CVE identifier, CVSS v2 and v3 scores, etc.
- descending (bool, optional): If set to True, the list will be sorted in descending order (highest CVSSv3Score first). Defaults to True.
Returns:
- list: The input list of CVEs sorted in decreasing order of their CVSS Version 3.x base scores."""),
("countCVEsBySeverity(cve_list: list)",
"""Analyze a list of CVE objects, and return a dictionary with counts of CVEs according to their 'cvssV3Severity' (LOW, MEDIUM, HIGH, CRITICAL).
Args:
- cve_list (list): A list of dictionary objects each representing a CVE. Each dictionary should include a 'cvssV3Severity' key.
Returns:
- dict: A dictionary with keys as 'LOW', 'MEDIUM', 'HIGH', 'CRITICAL' and values as counts of CVEs having corresponding 'cvssV3Severity'."""),
("get_first_object_from_list(list_of_objects: list)",
"""Retrieves the first object from a given list. If the list is empty, it return `None`.
Args:
- list_of_objects: list, required, List containing objects from which the function will pick out the first object."""),
("getCPEName(cpeObject: object)",
"""This function takes a CPE object and extracts the CPE name.
Args:
- cpeObject: A CPE object from which the CPE name is to be extracted. The object should have a 'cpeName' field,
Returns:
- str: The CPE name retrieved from the CPE object."""),
("search_backup_keywords(cvecpeList: list, backup_keyword: str)",
"""This function takes in a backup keyword and a list of CVE or CPE items found by an initial searchCVE or searchCPE. If the list is empty, the function will search again using the backup keyword instead of the original keyword. If it is not empty, the function returns the original searched results.
Args:
- cvecpeList, list, required, This arg takes in a list of CVE or CPE items.
- backup_keyword, str, required, The backup keyword to search if the original keyword doesn't lead to corresponding results.
"""),
("compare_cvecpes(cvecpeList1: list, cvecpeList2: list)",
"""This function can compare the contents of two lists of provided CVE or CPE items, summarizing the common parts and differences between the two lists.
Args:
- cvecpeList1, list, required, This arg takes in a list of CVE or CPE items to compare with another list.
- cvecpeList2", list, required, This arg takes in a list of CVE or CPE items to compare with another list.
"""),
("verify_and_process_data_range_end(startdate: str, enddate: str)",
"""This function can verify whether the range of dates being searched is within 3 months. If true, it returns the original enddate. If not, it will automatically truncate and return an appropriate enddate resulting in a 3-month time span. Note that searchCVE or searchCPE cannot handle time span longer than 3 months.
Args:
- startdate, str, required, The start date of the searched time span.
- enddate", str, required, The end date of the searched time span.
"""),
("verify_and_process_data_range_start(startdate: str, enddate: str)",
"""{This function can verify whether the range of dates being searched is within 3 months. If true, it returns the original startdate. If not, it will automatically truncate and return an appropriate startdate resulting in a 3-month time span. Note that searchCVE or searchCPE cannot handle time span longer than 3 months.
Args:
- startdate, str, required, The start date of the searched time span.
- enddate, str, required, The end date of the searched time span.
"""),
("summarize_cvecpes(cvecpeList: list)",
"""{This function can summarize the contents of provided CVE or CPE items.
Args:
- cvecpeList: list, required, This arg takes in a list of CVE or CPE items.
"""),
("count_cvecpe_items(cvecpeList: list)",
"""{This function counts the total number of CVE and CPE items provided in the arg.
Args:
- cvecpeList, list, required, This arg takes in a list of CVE or CPE items.
"""),
("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)",
"""
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/vulnerabilities
Args:
- 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.
- cveId (str): Please pass in a string integer, like "1" or "30". Returns a single CVE that already exists in the NVD.
- 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.
- cvssV2Severity (str): Find vulnerabilities having a LOW, MEDIUM, or HIGH version 2 severity.
- 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.
- cvssV3Severity (str): Find vulnerabilities having a LOW, MEDIUM, HIGH, or CRITICAL version 3 severity.
- 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.
- hasCertAlerts (bool): Returns CVE that contain a Technical Alert from US-CERT.
- hasCertNotes (bool): Returns CVE that contain a Vulnerability Note from CERT/CC.
- 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).
- 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.
- 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.
- 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.
- 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.
- lastModEndDate (str, datetime obj): Required if using lastModStartDate.
- noRejected (bool): Filters out all CVEs that are in a reject or rejected status. Searches without this parameter include rejected CVEs.
- 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.
- pubEndDate (str, datetime obj): Required if using pubStartDate.
- sourceIdentifier (str): Returns CVE where the data source of the CVE is the value that is passed to sourceIdentifier.
- versionEnd (str): Must be combined with versionEndType and virtualMatchString. Returns only the CVEs associated with CPEs in specific version ranges.
- 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.
- 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.
- 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.
- 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.
- limit (int): Custom argument to limit the number of results of the search. Allowed any number between 1 and 2000.
- 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.
- 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.
- verbose (bool): Prints the URL request for debugging purposes.
"""),
("searchCPE(cpeNameId: str, cpeMatchString: str, keywordExactMatch: bool, keywordSearch: str, lastModStartDate: str, lastModEndDate: str, matchCriteriaId: str, limit: int, key: str, delay: int, verbose: bool)",
"""
Build and send GET request then return list of objects containing a collection of CPEs.
Args:
- 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.
- cpeMatchString (str) Use a partial CPE name to search for other CPE names.
- 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.
- 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.
- 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'
- lastModEndDate (str/datetime obj) CPE last modification end date. Maximum 120 day range. Must be included with lastModStartDate. Example: ‘2020-06-28 00:00’
- limit (int) Limits the number of results of the search.
- key (str) NVD API Key. Allows for a request every 0.6 seconds instead of 6 seconds.
- 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.
- verbose (bool) Prints the URL request for debugging purposes.
""")]
}
CVECPE_Explain = (
"NVDLib is a Python API wrapper for the NIST National Vulnerability Database (NVD). "
"It allows pulling data on known CVEs, including CVE ID, description, reference links, CWE, "
"CPE applicability statements, optional CPE names, CVSS scores or metrics, and CVE publication and modified dates. "
"Features include searching the NVD for CVEs by keywords, dates, cweID, CVSS metrics, CPE strings, US-CERT alerts, "
"and more. It also enables searching for CPE names using modification dates, keywords, and CPE match strings. "
"Data can be easily accessed as class attributes. If no API key is provided, NVDLib defaults to a 6-second delay "
"between requests as recommended by NVD."
)
|