8.6 KiB

Raw Permalink Blame History

Xvirus SDK C++

Xvirus SDK 5.0 C++ bindings.

Xvirus SDK C++

Minimum Requirements

The following Operating Systems are supported:

Windows:
- Windows 10 1607
- Windows 11 22H2
- Windows Server 2012
- Windows Server Core 2012
Linux (glibc 2.35):
- Alpine Linux 3.19
- Azure Linux 3.0
- CentOS Stream 9
- Debian 12
- Fedora 41
- openSUSE Leap 15.6
- Red Hat Enterprise Linux 8
- SUSE Enterprise Linux 15.6
- Ubuntu 22.04

Changelog

Version 5.0:
- Updated to .NET 8
- XvirusAI is now out of beta
- XvirusAI now works on C++ bindings
- Improved performance of heuristics engine
- Added new settings: EnableSignatures, HeuristicsLevel, AILevel, MaxHeuristicsPeScanLength, MaxHeuristicsOthersScanLength, MaxAIScanLength, CheckSDKUpdates
Version 4.2.3:
- Fixed Windows scan performance regression
- Fixed ScanFolder command not working in CLI
- Fixed ScanFolderString JSON not formatted correctly
- Fixed update check always returning there was an update
Version 4.2.2:
- Optimized scanning speed of PDF files
- ScanResult now returns the file path
- Added new ScanFolder() and ScanFolderString() functions
Version 4.2.1:
- Optimized scanning speed of big files
- Optimized scanning speed in Linux version
Version 4.2:
- Reduced glibc minimum version to 2.17 on Linux
- Added "Logging()" function to enable/disable logging
- Added "BaseFolder()" function to set a custom base folder
- Added new setting "DatabaseFolder" to set the Database folder path
- Fixed C++ binding will return "Success=false" correctly when failing to scan a file
Version 4.1:
- Upgraded from .NET 5 to .NET 7
- C++ bindings now also support Linux
- Changed how exceptions are handled in C++ bindings
Version 4.0:
- Completely redone in .NET 5
- Now supports Linux (CLI and C# bindings only)
- Added XvirusAI scan engine (BETA)
- Scan speed is up to 2x faster
- Fixed memory usage spike when scanning large files
- Removed file size limit for scanned files by default
- The checkUpdate function can now check for SDK updates
- Added 3 new settings "EnableAIScan", "MaxScanLength" and "DatabaseVersion"

Known Issues

The checkUpdate function can check for SDK/CLI updates but can't update it automatically
When loading or scanning files with the AI scanner, the TensorFlow library might print diagnostic information to the console. To suppress these messages, set the environment variable "TF_CPP_MIN_LOG_LEVEL" to "3" before starting the SDK/CLI.

Get Started

The "example" folder contains an example project on how to import and use Xvirus SDK in C++.

This project shows you how to dynamically load Xvirus SDK (XvirusSDK.dll) for both Windows and Linux and call a function. You can also read more here.

You can run it by building it, copying the files from the bin folder to the output folder of the build and then running xvbdc.exe.

Available Functions

You can find the definition of all functions and structs in the file xvneng.h located in the "headers" folder.

load - Loads Xvirus Scan Engine into memory, if set force=true it will reload the scan engine, even if it is already loaded.
unload - Unloads Xvirus Scan Engine from memory.
scan - Scans the file located at filepath. It will return a ScanResult.
scanAsString - Scans the file located at filepath. It will return one of the following strings:
- "Safe" - If no malware is detected.
- "Malware" - If malware is detected but the name isn't known.
- Malware Name - If it is malware from a known family (example: "Trojan.Downloader").
- "AI.{aiScore}" - Score of the file using XvirusAI from 0 to 100, the higher the score the more probable it is malicious (example: "AI.99.99").
- "File not found!" - If no file is found in the submitted path.
- "File too big!" - If the file size is bigger than the set limit.
- "Could not get file hash!" - There was an error calculating the hash of the file.
scanFolder - Scans all the files inside the folder at folderpath. It will return a pointer for an array of ScanResult.
scanFolderAsString - Scans all the files inside the folder at folderpath. It will return the scan result message for each file scanned.
checkUpdates - Checks and updates the databases and AI engine to the most recent versions. If loadDBAfterUpdate=true then it will reload the Xvirus Scan Engine after the update is done. It can return the following strings:
- "There is a new SDK version available!"
- "Database was updated!"
- "Database is up-to-date!"
getSettings - returns a string representation of the settings.json file.
logging - Sets and return if Logging is enabled. If enableLogging Null value is provided it will only return.
baseFolder - Sets and return the BaseFolder path. If baseFolder Null value is provided it will only return.
version - returns the version of the SDK/CLI.

Model

The scan and scanFolder functions return a struct ScanResult with the following properties:

struct ScanResult {
  bool sucess; // true if scan was successful
  wchar_t* error; // error message, only has value if success=false
	bool isMalware; // true if malware
  wchar_t* name; // detection name
	double score; // between 0 and 1, higher score means more likely to be malware, -1 if there was an error
  wchar_t* path; // file path
};

All other functions return a struct ActionResult with the following properties:

struct ActionResult {
  bool sucess; // true if action was successful
	wchar_t* result; // result message, only has value if success=true
  wchar_t* error; // error message, only has value if success=false
};

Settings

Settings are located in the "settings.json" file in the root folder of the SDK/CLI. Available options:

Engine Settings

EnableSignatures - Enables signature-based scanning of files. Default: true
EnableHeuristics - Enables heuristics scanning of files. Default: true
EnableAIScan - Enables XvirusAI scan engine. Default: true

Scan Levels

HeuristicsLevel - Heuristics aggressiveness level from 1 to 5, higher is more aggressive. Default: 4
AILevel - AI scan aggressiveness level from 1 to 100, higher is more aggressive. Default: 10

File Size Limits

MaxScanLength - Maximum file size to be scanned in bytes. If set "null" then there is no limit. Default: null
MaxHeuristicsPeScanLength - Maximum PE file size for heuristics scanning in bytes. If set "null" then there is no limit. Default: 20971520 (20MB)
MaxHeuristicsOthersScanLength - Maximum non-PE file size for heuristics scanning in bytes. If set "null" then there is no limit. Default: 10485760 (10MB)
MaxAIScanLength - Maximum file size for AI scanning in bytes. If set "null" then there is no limit. Default: 20971520 (20MB)

Update Settings

CheckSDKUpdates - Enables checking for SDK updates. Default: true
DatabaseFolder - Path to the database folder, it accepts both relative and absolute paths. Default: "Database"
DatabaseVersion - KeyValue list of database files version. This is updated automatically when using the "checkUpdate()" function.

Example of a settings.json file:

{
  "EnableSignatures": true,
  "EnableHeuristics": true,
  "EnableAIScan": true,
  "HeuristicsLevel": 4,
  "AILevel": 10,
  "MaxScanLength": null,
  "MaxHeuristicsPeScanLength": 20971520,
  "MaxHeuristicsOthersScanLength": 10485760,
  "MaxAIScanLength": 20971520,
  "CheckSDKUpdates": true,
  "DatabaseFolder": "Database",
  "DatabaseVersion": {
    "AIModel": 0,
    "MainDB": 0,
    "DailyDB": 0,
    "WhiteDB": 0,
    "DailywlDB": 0,
    "HeurDB": 0,
    "HeurDB2": 0,
    "MalvendorDB": 0
  }
}

Exceptions

If any of the functions fails the success property returns false and the error property contains the error message.

All exceptions are logged in the errorlog.txt file.

8.6 KiB Raw Permalink Blame History