Xvirus_SDK_CSharp/README.md

# Xvirus SDK C#

Xvirus SDK 4.1 C# bindings.

## Table of Contents

- [Xvirus SDK C#](#xvirus-sdk-c)
  - [Table of Contents](#table-of-contents)
  - [Minimum Requirements](#minimum-requirements)
  - [Changelog](#changelog)
  - [Known Issues](#known-issues)
  - [Get Started](#get-started)
  - [Avaiable Functions](#avaiable-functions)
  - [Model](#model)
  - [Settings](#settings)
  - [Exceptions](#exceptions)

## Minimum Requirements

To use Xvirus SDK you need:

- .NET 7 SDK - [download](https://dotnet.microsoft.com/en-us/download/dotnet/7.0)

## Changelog

- Version **4.1**:

  - Upgraded from .NET 5 to .NET 7
  - C++ bindings now also support Linux
  - Removed Minimum Requirements on C++ bindings and CLI
  - 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

- XvirusAI engine is still in BETA. It is not recomended to use in production yet.
- XvirusAI engine does not work in C++ bindings.
- The checkUpdate function can now check for SDK updates but can't update it

## Get Started

The "`example`" folder contains an example project on how to import and use Xvirus SDK in C# (.NET 7).

You can run it by building it and then running executable file in the output folder.

## Avaiable Functions

You have the following functions available:

- **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`](#Model).
- **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").
  - "**File not found!**" - If no file is found in the submited 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.
- **CheckUpdates** - Checks and updates the databases and AI engine to the most recent versions. If `checkSDKUpdates`=true then it will also check for SDK updates. 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 object representation of the `settings.json` file.
- **GetSettingsAsString** - returns a string representation of the `settings.json` file.
- **Version** - returns the version of the SDK/CLI.

## Model

The `scan` function returns a class `ScanResult` with the following properties:

```c#
public class ScanResult
{
    public bool IsMalware { get; set; } // true if malware
    public string Name { get; set; } // detection name
    public double MalwareScore { get; set; } // between 0 and 1, higher score means more likely to be malware, -1 if there was an error
}
```

## Settings

Settings are located in the "`settings.json`" file in the root folder of the SDK. There are 4 avaiable options:

- **EnableHeuristics** - Enables heuristics scanning of files. Default: _true_
- **EnableAIScan** - Enables XvirusAI scan engine. This feature is still in BETA. Default: _false_
- **MaxScanLength** - Maximum file size to be scanned in bytes. If set "null" then there is no limit. Default: _null_
- **DatabaseVersion** - KeyValue list of database files version. This is updated automatically when using the "checkUpdate()" function.

Example of a `settings.json` file:

```JSON
{
  "EnableHeuristics": true,
  "EnableAIScan": false,
  "MaxScanLength": null,
  "DatabaseVersion": {
    "AIModel": 0,
    "MainDB": 0,
    "DailyDB": 0,
    "WhiteDB": 0,
    "DailywlDB": 0,
    "HeurDB": 0,
    "HeurDB2": 0,
    "MalvendorDB": 0
  }
}
```

## Exceptions

If any of the functions fail it may return an [exception](https://docs.microsoft.com/en-us/dotnet/csharp/fundamentals/exceptions/).

All exceptions are logged in the `errorlog.txt` file.