Skip to main content

GetLatestInstaller

Download the latest installer of the specified product.

Syntax​

Method ID​

#define WA_VMOD_PATCH_GET_LATEST_INSTALLER 50300

JSON Input Structure​

{
"input": {
"method": 50300,
"signature": number,
"path": string,
"token": string,
"download": number,
"os_id": number,
"language": string,
"architecture": string,
"os_architecture": string,
"index": number,
"online": number,
"patch_id": number,
"user_agent": string,
"enable_resolved_cves": boolean,
"package_filter": [
string,
...
],
"auto_update_repository": number,
"instance_id": string,
"requested_version": string
}
}

Input Properties​

ParameterTypeDescription
signaturenumberThe signature id of the product returned from the detection call.
pathstring(optional) Path to the directory that will save the installer (overwrite). This field is only needed when "download" field is set to 1.
tokenstring(optional) The OPSWAT-provided token to access to some resources. This field is only needed for installers that must be downloaded from OPSWAT servers.
downloadnumber(optional) Specify the desired download action for the installer. The value is 0 by default.
• 0: Return the download URL of the installer only.
• 1: Download the installer.
• 2: (Windows & macOS only) Return the internal patch identifier to get the detail of the corresponding patch from local database.
os_idnumber(optional) (Windows & macOS only) OESIS Framework identifier of the OS that uses the downloaded installer.
languagestring(optional) (Windows & macOS only) Language identifier of the product to download (e.g: "en-us", "fr"). If the vendor does not allow selecting language then this field is ignored. If the vendor allows setting language but the specified language is not supported then the default language of the product is used.
architecturestring(optional) (Windows & macOS only) Architecture of product to download ("32-bit", "64-bit" and "arm64" (Mac only)). If the installer does not allow selecting architecture then this field is ignored. If the installer allows setting architecture and this field is not specified then default value is architecture of the installed product, with fallback to OS architecture on Windows. On Mac, only OS architecture is used.
os_architecturestring(optional) (Windows & macOS only) Architecture of OS ("32-bit" or "64-bit"). This field is used to download latest installer for some exceptional products. Default value is OS architecture of current running machine.
indexnumber(optional) (Windows & macOS only) Index of patch file to return in output if the product requires many patch files. User can call this function many times, increase this field from 0 until WA_VMOD_ERROR_OUT_OF_RANGE error code is returned to iterate through all patches. Default value is 0.
onlinenumber(optional) (Windows & macOS only) Whether to use online database or not. Value 0 will disable online mode, value 1 will enable it. Default value is 0.
patch_idnumber(optional) (Windows & macOS only) Patch identifier to get download information from local database (for Analog use case). By default, the function determines the correct patch identifier itself.
user_agentstring(optional) (Windows & macOS only) Specify the user agent used to perform requests to the vendor of current product. The input characters must comply with the following rules:
1. Alphanumeric characters: a-z, A-Z, and 0-9
2. Special characters: _ :;.,\/"'?!()\{\}[]@=-+*#{{PARAMETERS_SECTION}}|~^%`
3. The max length of the value is 1012 characters.
enable_resolved_cvesboolean(optional) (Linux only) (Linux only) Enable CVE detection. The value is false by default.
• true:
• v2mod.dat and liv.dat have been loaded: resolvable_cves is shown in the output
• v2mod.dat and liv.dat have not been loaded: resolvable_cves is shown in the output as empty []
• false:
• resolvable_cves is not shown in the output
package_filterarray<string>(optional) (Linux only) (Linux only) (System patching flow) The list of patches must be specifically retrieved. This value is an array of package names, derived from GetLatestInstaller using the package managers signature, but without package_filter. Only patches that match the specified regex patterns will be included in the results.
• If the input has no elements ([]): The SDK will return an empty array.
• If the input has package name (["python", "libc6"]): The SDK will return patches matching the mentioned package names.
• Default case (["*"]): The SDK will return the full list of missing patches. For patches that are already the latest version or not installed, an empty array will be returned.
auto_update_repositorynumber(optional) (Linux only) (Linux only) (System patching flow) Specify the auto update mode of the package manager. The value is 2 by default.
• 0: The engine will not update the package manager.
• 1: Always update the package manager before get missing patches. The root privilege is required.
• 2: Only update the package manager if it failed to get missing patches in the first try. The root privilege may be required.
instance_idstring(optional) (macOS and Linux) Specify the id of the target instance. If not specify, the engine will try to target the first detected instance.
requested_versionstring(optional) (Third-party patching flow) Specify the expected version to download on the endpoint machine. If the requested version is missing from the OESIS database or the vendor does not provide a version-specific download URL, the SDK is unable to perform the version-specific patching process. A patchv2.dat is required for this parameter.

JSON Output Structure​

{
"result": {
"method": 50300,
"code": number,
"timing": number,
"timestamp": string,
"signature": number,
"type_id": number,
"patch_id": number,
"analog_id": string,
"index": number,
"eula": string,
"release_note": string,
"release_date": string,
"security_update_id": string,
"title": string,
"product_name": string,
"severity": string,
"category": string,
"url": string,
"minimum_version": string,
"language": string,
"architecture": string,
"os_id": number,
"path": string,
"sha1": string,
"sha256": string,
"md5": string,
"size": string,
"file_type": string,
"current_version": string,
"download": number,
"expected_sha1": [
string,
...
],
"expected_sha256": [
string,
...
],
"expected_sha512": [
string,
...
],
"expected_md5": [
string,
...
],
"certificates": [
{
"issuer": string,
"subject": string,
"serial_number": string,
"signature_algorithm": string
},
...
],
"source_timestamp": number,
"description": string,
"vendor": string,
"optional": boolean,
"reboot_required": number,
"require_uninstall_first": number,
"system_package_mapping": [
{
"<signature>": [
string,
...
]
},
...
],
"resolvable_cves": [
string,
...
],
"dependencies": {
"<package_name>": {
"current_version": string,
"required_version": string,
"to_be_updated_version": string,
"status": string
}
},
"patches": [
{
"description": string,
"title": string,
"name": string,
"vendor": string,
"type": number,
"url": string,
"minimum_version": string,
"current_version": string,
"category": string,
"release_date": string,
"size": string,
"dependencies": {
"<package_name>": {
"current_version": string,
"required_version": string,
"to_be_updated_version": string,
"status": string
}
},
"resolvable_cves": [
string,
...
]
},
...
]
}
}

Output Properties​

PropertyTypeDescription
result.methodnumberThe method ID that generated this result.
result.codenumberThe result code. See Result Codes.
result.timingnumberThe measured time for the method call in milliseconds.
result.timestampstringThe timestamp in seconds of when the call was made.
result.signaturenumberThe signature identifier from the product. If it is different from input signature then it is redirected.
result.type_idnumberThe identifier of output type (schema). Type 1 means single patch file, type 2 means multiple patch files, type 3 means multiple patch files as a zip package. User should only process known output types.
result.patch_idnumberInternal identifier of the patch data used.
result.analog_idstringThe identifier to be sent to server in Analog use case.
result.indexnumberIndex of the returned patch file within list of patches for the product. This has the same value as input's "index".
result.eulastringLink to the End User License Agreement page of the product.
result.release_notestringLink to the release note of the product.
result.release_datestringRelease date of a product version.
result.security_update_idstring(optional) The security update id of a missing patch. This is equivalent to Knowledge Base ids for Windows.
result.titlestring(optional) The title of the missing patch.
result.product_namestring(optional) The possible product name for a missing patch.
result.severitystring(optional) The severity of a missing patch: 'low', 'moderate', 'important', 'critical', 'unknown'.
result.categorystring(optional) The category of a missing patch: 'security_update', 'update_rollup', 'critical_update', 'update', 'upgrade', 'driver', 'service_pack', 'unknown'.
result.urlstringLink to download the installer.
result.minimum_versionstringThe minimum version expected upon completion of the patching process.
result.languagestringThe language code used for the installer. Empty value means not specified.
result.architecturestringThe architecture used for the installer.
result.os_idnumber(optional) The Os Info used for the installer.
result.pathstring(optional) Path to the downloaded installer. The installer name is specified by vendor's provided link with each space get replaced by underscore. This field only exists if user chooses to download installer.
result.sha1string(optional) SHA1 hash of the downloaded installer. This field only exists if user chooses to download installer.
result.sha256string(optional) SHA256 hash of the downloaded installer. This field only exists if user chooses to download installer.
result.md5string(optional) MD5 hash of the downloaded installer. This field only exists if user chooses to download installer.
result.sizestring(optional) Size of the downloaded installer in bytes. This field only exists if user chooses to download installer.
result.file_typestringFile type of the installer.
result.current_versionstring(optional) The current version of the installed product.
result.downloadnumber(optional) The download mode of the method.
result.expected_sha1array<string>(optional) List of expected SHA1 checksums of the installer. This field only exists if checksum database is loaded and the product is supported.
result.expected_sha256array<string>(optional) List of expected SHA256 checksums of the installer. This field only exists if checksum database is loaded and the product is supported.
result.expected_sha512array<string>(optional) List of expected SHA512 checksums of the installer. This field only exists if checksum database is loaded and the product is supported.
result.expected_md5array<string>(optional) List of expected MD5 checksums of the installer. This field only exists if checksum database is loaded and the product is supported.
result.certificatesarray<object>(optional) List of certificates in the certificate chain embedded into the installer. The code signing certificate is the first item in the array, the next certificate in the chain is the second and so on. This field only exists if user choose to download installer and it is signed by vendor.
result.certificates.issuerstringThe name of certificate's issuer.
result.certificates.subjectstringThe name of certificate's subject.
result.certificates.serial_numberstringThe certificate serial number.
result.certificates.signature_algorithmstringThe signature algorithm used in the certificate.
result.source_timestampnumber(optional) The timestamp of cloud data being used for method with online mode.
result.descriptionstring(optional) (Windows only) The description of a Microsoft KB. Value "n/a" means that the information is not available.
result.vendorstring(optional) (Windows only) The name of KB publishing vendor.
result.optionalboolean(optional) (Windows only) Whether the KB is optional update or not
result.reboot_requirednumber(optional) Whether system reboot or application restart is required after installation (Please refer to this Knowledge Base Article for details regarding distinguishing OS restart and application restart). Possible values are 0 (no reboot needed), 1 (reboot needed) and 2 (conditional reboot required).
result.require_uninstall_firstnumber(optional) Indicates if the existing application must be uninstalled before installation. Possible values are 0 (no uninstall required) and 1 (uninstall required).
result.system_package_mappingarray<object>(optional) (Linux Only) The package name in the system flow if exists.
• If the current package can be patched via system flow, the value is the package name correspondent.
• Firefox for example:
• 3rd-party output: system_package_mapping: [ '200041': ["firefox"], '200209': ["firefox"]]. In this case, 200041 is the signature of APT, and 200209 is the signature of SNAP.
• System output: name: "firefox"
result.system_package_mapping.<signature>array<string>(optional) (Linux Only) The list of possible package names that associated with this signature.
result.resolvable_cvesarray<string>(optional) (Linux Only) (Third-party patching flow) This appears when the input enable_resolved_cve is true. The list of CVEs will be considered resolved after the patch is applied.
result.dependenciesobject(optional) (Linux Only) (Third-party patching flow) List of dependencies needed to install a package.
result.dependencies.<package_name>object(optional) The package name of a dependency.
result.dependencies.<package_name>.current_versionstring(optional) The current version of the dependency package.
• The current version of the dependency package (Ex. "12.abc") if the current dependency is installed.
• "n/a" if the current dependency is not installed.
result.dependencies.<package_name>.required_versionstring(optional) The required version to install the patch. This is obtained by parsing the installer.
• No required version specified: "*"
• Has required version: Directive string follows dpkg format (Ex. >=2.2.1).
• Has multiple requirements of a dependency in a package: Single string with each requirement separated by a comma (e.g., >=2.2.1,<=2.2.3).
• Special case: If more than one package needs the same dependency A with multiple requirement ranges, the result is the best range the SDK can find.
result.dependencies.<package_name>.to_be_updated_versionstring(optional) The version of a dependency package after applying a patch. If running with download mode 0, the value will be n/a.
result.dependencies.<package_name>.statusstring(optional) The status of a dependency package.
• resolved: Indicates the current dependency package has met the required version. In this case, the value of to_be_updated_version is equal to current_version.
• installable: The dependency will be installed after patching. to_be_updated_version in this case is the required version.
• not installable: The dependency cannot be installed after patching and may cause failure if forced install. to_be_updated_version in this case is an empty string.
• upgradable: The dependency will be upgraded after applying a patch. to_be_updated_version in this case is the required version specified in the patch.
• downgradable: The dependency will be downgraded after applying a patch. to_be_updated_version in this case is the required version specified in the patch.
• removable: The dependency will be removed after applying a patch. to_be_updated_version in this case is an empty string.
• n/a: Can not get dependency status.
result.patchesarray<object>(optional) (Linux only) (System patching flow) List of missing patches on the machine.
result.patches.descriptionstringThe description of a missing patch.
result.patches.titlestring(optional) The title of a missing patch.
result.patches.namestringThe name of a missing patch.
result.patches.vendorstringThe vendor's name of a missing patch.
result.patches.typenumber(optional) Identify whether the patch is an operating system or an application.
• 0: Operating system.
• 1: Application.
result.patches.urlstringThe official source from which the missing patch can be obtained.
result.patches.minimum_versionstringThe minimum expected version of the patch that can be obtained.
result.patches.current_versionstringThe current version of the package on the machine.
result.patches.categorystringThe category of a missing patch.
• security_update
• update_rollup
• critical_update
• update
• driver
• service_pack
• unknown
result.patches.release_datestringThe release date of the missing patch.
result.patches.sizestringSize of the missing patch in bytes.
result.patches.dependenciesobjectList of dependencies needed to install a missing patch.
result.patches.dependencies.<package_name>object(optional) The package name of a dependency.
result.patches.dependencies.<package_name>.current_versionstring(optional) The current version of the dependency package.
• The current version of the dependency package (Ex. "12.abc") if installed.
• "n/a" if not installed.
result.patches.dependencies.<package_name>.required_versionstring(optional) The required version to install the patch.
• No required version specified: "*"
• Has required version: Directive follows dpkg format (Ex. >=2.2.1).
• Multiple requirements: Single string with requirements separated by commas (e.g., >=2.2.1,<=2.2.3).
• Special case: If multiple packages need the same dependency A with different requirement ranges, SDK finds the best range.
result.patches.dependencies.<package_name>.to_be_updated_versionstring(optional) The version of a dependency package after applying a patch. If running with download mode 0, the value will be n/a.
result.patches.dependencies.<package_name>.statusstring(optional) The status of a dependency package.
• resolved: Dependency met the required version; to_be_updated_version equals current_version.
• installable: Will be installed after patching; to_be_updated_version is required version.
• not installable: Cannot be installed; to_be_updated_version is empty.
• upgradable: Will be upgraded after patch; to_be_updated_version is required version in the patch.
• downgradable: Will be downgraded after patch; to_be_updated_version is required version in the patch.
• removable: Will be removed; to_be_updated_version is empty.
• n/a: Can not get dependency status.
result.patches.resolvable_cvesarray<string>(optional) This appears when the input enable_resolved_cve is true. The list of CVEs that will be resolved after applying the patch.

Result Codes​

This method resolves an installer and downloads it; it does not install, so no installation failure code appears below. Availability differs by platform.

CodeConstantDescription
1006WA_VMOD_REDIRECTED_TO_SYSTEM_FLOWThe call was redirected to the system package manager flow (APT / DNF / SNAP). The response describes the packages to install rather than a downloaded installer file.
2WAAPI_OK_FALSEThe installer was resolved, but the returned url is not directly usable: it still carries an <opswat_token> placeholder because no token was supplied in the input. Only occurs in query mode (download 0 or 2). Supply a valid token to receive a usable URL.
0WAAPI_OKThe installer was resolved. With download set to 1 the file was downloaded to download_path; with 0 or 2 the response carries the download URL and patch metadata without fetching the file.
-5WAAPI_ERROR_NOT_INITIALIZEDThis method was called while the SDK is not initialized. Call wa_api_setup and verify it returned a success code before invoking, and do not invoke after wa_api_teardown.
-7WAAPI_ERROR_COMPONENT_NOT_LICENSEDThe license does not permit the mode the SDK is running in — it is set to online mode on an offline-only license, or the reverse. Checked before the call is dispatched, so no patch lookup is attempted. Not specific to this method, and not about the Vulnerability component: this method is not tied to a licensed component, so it never returns WAAPI_ERROR_COMPONENT_LICENSE_EXPIRED (-8).
-14WAAPI_ERROR_DATABASE_CORRUPTEDThe patch database loaded, but this product's entry in it could not be read. Re-download the patch data; re-calling LoadPatchDatabase (50302) on the same file will not help.
-16WAAPI_ERROR_DATABASE_NOT_INITIALIZEDThe patch database has not been loaded. Call LoadPatchDatabase (50302) before this method.
-17WAAPI_ERROR_NO_CONNECTIONThe download source could not be reached — the address did not resolve, the connection was refused, the TLS handshake failed, or a proxy refused the connection. Check outbound connectivity and any proxy configuration.
-19WAAPI_ERROR_INVALID_CREDENTIALSThe download server rejected the request as unauthenticated (HTTP 401). Check any proxy authentication and the credentials required to reach the vendor or gateway.
-20WAAPI_ERROR_INVALID_INPUT_ARGSA required input key is missing, or one of the fields is malformed — most commonly method, signature, download_path, user_agent, token, architecture, or requested_version.
-21WAAPI_ERROR_INVALID_JSONThe provided json_in is not valid JSON or does not parse into the expected object shape.
-22WAAPI_ERROR_ACCESS_DENIEDEither the download server refused the request (HTTP 403), or the SDK could not read the patch data or write to download_path. Confirm the destination exists and is writable, and check proxy access. Elevation is typically required.
-26WAAPI_ERROR_DISPATCH_EXCEPTIONA C++ exception escaped while the call was being dispatched. The call did not complete and no result is returned. Treat as an internal error and report it with the SDK debug log.
-27WAAPI_ERROR_NATIVE_APIA call the SDK made into an operating-system or system-library API failed with an error the SDK does not yet classify. Native failures are mapped to specific codes wherever they are recognised — a missing file to WAAPI_ERROR_NOT_FOUND (-28), a permissions failure to WAAPI_ERROR_ACCESS_DENIED (-22), and so on — and this code is the fallback for a case that mapping does not cover. So it tells you where the failure came from, not what it was: read the underlying error from the response's error_message field. On this method such calls arise while resolving and downloading the installer.
-28WAAPI_ERROR_NOT_FOUNDNo download entry matches this product for the requested OS, architecture or language, or the download URL returned HTTP 404. Retry with refreshed patch data.
-33WAAPI_ERROR_CRYPTOVerifying the downloaded installer could not be completed: computing the file's hash, or extracting and parsing its certificate chain, failed. A truncated or corrupt download is the usual cause — retry it. Distinct from WAAPI_ERROR_INVALID_SIGNATURE (-47), where the signature was read successfully but does not belong to the expected vendor.
-42WAAPI_ERROR_SCRIPTING_GENERALThe script that resolves this product's download failed, or returned output that could not be used. Check that PowerShell is available on the endpoint and that it has connectivity.
-47WAAPI_ERROR_INVALID_SIGNATUREThe downloaded file did not come from the expected vendor — its digital signature did not match the signing information recorded for this patch. Only checked when the installer is actually downloaded (download: 1), and not for products whose installer is resolved by a script. A common cause is the vendor renewing its code-signing certificate before the patch data caught up. Do not run the installer. Refresh the patch data and retry.
-58WAAPI_ERROR_INVALID_OUTPUT_ARGSThe call succeeded but its response failed the SDK's own output-schema check, so this code replaces the success code. Only occurs while JSON I/O validation is enabled — a diagnostic setting, not a default. Treat as an internal error and report it.
-63WAAPI_ERROR_INVALID_INSTANCE_IDThe value provided for instance_id could not be resolved, which matters when a signature has multiple instances installed on the same machine.
-66WAAPI_ERROR_TEARDOWN_BUSYThe call arrived while wa_api_teardown was still running. Nothing was dispatched. Do not invoke after starting teardown; if teardown is expected to finish, wait for it to return and re-run wa_api_setup before calling again.
-69WAAPI_ERROR_MEMORY_CORUPTEDA non-standard exception escaped while the call was being dispatched — typically a structured or access-violation fault. The call did not complete. Treat as an internal error and report it with the SDK debug log.
-1016WA_VMOD_ERROR_INTERNAL_FORMAT_MISMATCHPatch data needed for this product could not be read because its format was not what the SDK expects. Usually transient — refresh the patch data and retry.
-1026WA_VMOD_ERROR_PRODUCT_NOT_SUPPORTEDThe requested signature is not present in the loaded patch data — including when the patch database was never loaded — so no installer applies to it. Call LoadPatchDatabase (50302) first, then confirm the signature is patch-supported.
-1027WA_VMOD_ERROR_LANGUAGE_NOT_SUPPORTEDNo package exists for the requested language. Applies only where the product publishes per-language variants; otherwise the requested value is accepted as-is. Omit the override, or request a language the product ships.
-1028WA_VMOD_ERROR_ARCHITECTURE_NOT_SUPPORTEDNo package exists for the requested architecture. Applies only where the product publishes per-architecture variants; otherwise the requested value is accepted as-is. Omit the override, or request an architecture the product ships.
-1037WA_VMOD_ERROR_OUT_OF_MEMORYThe SDK ran out of memory while reading patch data. Applies to operating-system update patches rather than third-party products. Retry with more memory available.
-1038WA_VMOD_ERROR_DATA_TYPE_NOT_SUPPORTEDThe patch data describes an installer delivery method this SDK build does not support. Refresh the patch data; if it persists, this product cannot be patched automatically with this SDK version — upgrade the SDK or patch it manually.
-1039WA_VMOD_ERROR_OUT_OF_RANGENo patch exists at the requested index — iteration has passed the product's last patch file. For Windows OS updates, increase index from 0 until this code is returned to enumerate every missing patch. Third-party patching does not support multiple patch files yet, so only index 0 is valid there and any other value returns this code immediately.
-1042WA_VMOD_ERROR_VERSION_MISMATCHA download link exists but its version does not match the version the patch database recorded for this product.
-1052WA_VMOD_VERSION_LOCK_NOT_SUPPORTEDThe requested_version cannot be served: either it is not in the OESIS database, or the vendor publishes no version-specific download URL for this product. Omit requested_version to take the latest available version.
note

Other codes may be returned. See the full Result Codes reference for the complete list.

Remarks​

Error Handling​

The results of this function are determined by the error code returned by the call. If successful, WAAPI_OK or a special success code will be returned. Always check both the function return value and the result.code field in the output JSON. Test success with the WAAPI_SUCCESS macro, which treats any value >= 0 as success, rather than comparing against 0.

This method can return a non-zero success code — WAAPI_OK_FALSE (2) and WA_VMOD_REDIRECTED_TO_SYSTEM_FLOW (1006). Both carry a usable result; code that tests code == 0 will misread them as failures.

Prerequisites​

Call LoadPatchDatabase (50302) first. Without it the call fails in one of two ways: with WAAPI_ERROR_DATABASE_NOT_INITIALIZED (-16), or with WA_VMOD_ERROR_PRODUCT_NOT_SUPPORTED (-1026) when the signature cannot be found in patch data that was never loaded. Both have the same fix — load the patch database, then confirm the signature is patch-supported.

Examples​

Examples will be added here demonstrating the usage of this method.

See Also​


Last updated: 2026-10-01