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
| Parameter | Type | Description |
|---|---|---|
signature | number | The signature id of the product returned from the detection call. |
path | string | (optional) Path to the directory that will save the installer (overwrite). This field is only needed when "download" field is set to 1. |
token | string | (optional) The OPSWAT-provided token to access to some resources. This field is only needed for installers that must be downloaded from OPSWAT servers. |
download | number | (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_id | number | (optional) (Windows & macOS only) OESIS Framework identifier of the OS that uses the downloaded installer. |
language | string | (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. |
architecture | string | (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_architecture | string | (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. |
index | number | (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. |
online | number | (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_id | number | (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_agent | string | (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_cves | boolean | (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_filter | array<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_repository | number | (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_id | string | (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_version | string | (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
| Property | Type | Description |
|---|---|---|
result.method | number | The method ID that generated this result. |
result.code | number | The result code. See Result Codes. |
result.timing | number | The measured time for the method call in milliseconds. |
result.timestamp | string | The timestamp in seconds of when the call was made. |
result.signature | number | The signature identifier from the product. If it is different from input signature then it is redirected. |
result.type_id | number | The 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_id | number | Internal identifier of the patch data used. |
result.analog_id | string | The identifier to be sent to server in Analog use case. |
result.index | number | Index of the returned patch file within list of patches for the product. This has the same value as input's "index". |
result.eula | string | Link to the End User License Agreement page of the product. |
result.release_note | string | Link to the release note of the product. |
result.release_date | string | Release date of a product version. |
result.security_update_id | string | (optional) The security update id of a missing patch. This is equivalent to Knowledge Base ids for Windows. |
result.title | string | (optional) The title of the missing patch. |
result.product_name | string | (optional) The possible product name for a missing patch. |
result.severity | string | (optional) The severity of a missing patch: 'low', 'moderate', 'important', 'critical', 'unknown'. |
result.category | string | (optional) The category of a missing patch: 'security_update', 'update_rollup', 'critical_update', 'update', 'upgrade', 'driver', 'service_pack', 'unknown'. |
result.url | string | Link to download the installer. |
result.minimum_version | string | The minimum version expected upon completion of the patching process. |
result.language | string | The language code used for the installer. Empty value means not specified. |
result.architecture | string | The architecture used for the installer. |
result.os_id | number | (optional) The Os Info used for the installer. |
result.path | string | (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.sha1 | string | (optional) SHA1 hash of the downloaded installer. This field only exists if user chooses to download installer. |
result.sha256 | string | (optional) SHA256 hash of the downloaded installer. This field only exists if user chooses to download installer. |
result.md5 | string | (optional) MD5 hash of the downloaded installer. This field only exists if user chooses to download installer. |
result.size | string | (optional) Size of the downloaded installer in bytes. This field only exists if user chooses to download installer. |
result.file_type | string | File type of the installer. |
result.current_version | string | (optional) The current version of the installed product. |
result.download | number | (optional) The download mode of the method. |
result.expected_sha1 | array<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_sha256 | array<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_sha512 | array<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_md5 | array<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.certificates | array<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.issuer | string | The name of certificate's issuer. |
result.certificates.subject | string | The name of certificate's subject. |
result.certificates.serial_number | string | The certificate serial number. |
result.certificates.signature_algorithm | string | The signature algorithm used in the certificate. |
result.source_timestamp | number | (optional) The timestamp of cloud data being used for method with online mode. |
result.description | string | (optional) (Windows only) The description of a Microsoft KB. Value "n/a" means that the information is not available. |
result.vendor | string | (optional) (Windows only) The name of KB publishing vendor. |
result.optional | boolean | (optional) (Windows only) Whether the KB is optional update or not |
result.reboot_required | number | (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_first | number | (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_mapping | array<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_cves | array<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.dependencies | object | (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_version | string | (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_version | string | (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_version | string | (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>.status | string | (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.patches | array<object> | (optional) (Linux only) (System patching flow) List of missing patches on the machine. |
result.patches.description | string | The description of a missing patch. |
result.patches.title | string | (optional) The title of a missing patch. |
result.patches.name | string | The name of a missing patch. |
result.patches.vendor | string | The vendor's name of a missing patch. |
result.patches.type | number | (optional) Identify whether the patch is an operating system or an application. • 0: Operating system. • 1: Application. |
result.patches.url | string | The official source from which the missing patch can be obtained. |
result.patches.minimum_version | string | The minimum expected version of the patch that can be obtained. |
result.patches.current_version | string | The current version of the package on the machine. |
result.patches.category | string | The category of a missing patch. • security_update • update_rollup • critical_update • update • driver • service_pack • unknown |
result.patches.release_date | string | The release date of the missing patch. |
result.patches.size | string | Size of the missing patch in bytes. |
result.patches.dependencies | object | List 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_version | string | (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_version | string | (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_version | string | (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>.status | string | (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_cves | array<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.
| Code | Constant | Description |
|---|---|---|
| 1006 | WA_VMOD_REDIRECTED_TO_SYSTEM_FLOW | The 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. |
| 2 | WAAPI_OK_FALSE | The 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. |
| 0 | WAAPI_OK | The 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. |
| -5 | WAAPI_ERROR_NOT_INITIALIZED | This 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. |
| -7 | WAAPI_ERROR_COMPONENT_NOT_LICENSED | The 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). |
| -14 | WAAPI_ERROR_DATABASE_CORRUPTED | The 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. |
| -16 | WAAPI_ERROR_DATABASE_NOT_INITIALIZED | The patch database has not been loaded. Call LoadPatchDatabase (50302) before this method. |
| -17 | WAAPI_ERROR_NO_CONNECTION | The 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. |
| -19 | WAAPI_ERROR_INVALID_CREDENTIALS | The download server rejected the request as unauthenticated (HTTP 401). Check any proxy authentication and the credentials required to reach the vendor or gateway. |
| -20 | WAAPI_ERROR_INVALID_INPUT_ARGS | A 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. |
| -21 | WAAPI_ERROR_INVALID_JSON | The provided json_in is not valid JSON or does not parse into the expected object shape. |
| -22 | WAAPI_ERROR_ACCESS_DENIED | Either 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. |
| -26 | WAAPI_ERROR_DISPATCH_EXCEPTION | A 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. |
| -27 | WAAPI_ERROR_NATIVE_API | A 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. |
| -28 | WAAPI_ERROR_NOT_FOUND | No download entry matches this product for the requested OS, architecture or language, or the download URL returned HTTP 404. Retry with refreshed patch data. |
| -33 | WAAPI_ERROR_CRYPTO | Verifying 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. |
| -42 | WAAPI_ERROR_SCRIPTING_GENERAL | The 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. |
| -47 | WAAPI_ERROR_INVALID_SIGNATURE | The 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. |
| -58 | WAAPI_ERROR_INVALID_OUTPUT_ARGS | The 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. |
| -63 | WAAPI_ERROR_INVALID_INSTANCE_ID | The value provided for instance_id could not be resolved, which matters when a signature has multiple instances installed on the same machine. |
| -66 | WAAPI_ERROR_TEARDOWN_BUSY | The 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. |
| -69 | WAAPI_ERROR_MEMORY_CORUPTED | A 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. |
| -1016 | WA_VMOD_ERROR_INTERNAL_FORMAT_MISMATCH | Patch 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. |
| -1026 | WA_VMOD_ERROR_PRODUCT_NOT_SUPPORTED | The 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. |
| -1027 | WA_VMOD_ERROR_LANGUAGE_NOT_SUPPORTED | No 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. |
| -1028 | WA_VMOD_ERROR_ARCHITECTURE_NOT_SUPPORTED | No 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. |
| -1037 | WA_VMOD_ERROR_OUT_OF_MEMORY | The 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. |
| -1038 | WA_VMOD_ERROR_DATA_TYPE_NOT_SUPPORTED | The 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. |
| -1039 | WA_VMOD_ERROR_OUT_OF_RANGE | No 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. |
| -1042 | WA_VMOD_ERROR_VERSION_MISMATCH | A download link exists but its version does not match the version the patch database recorded for this product. |
| -1052 | WA_VMOD_VERSION_LOCK_NOT_SUPPORTED | The 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. |
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