# Malware Scanner

## Table of Contents

1. [Purpose](#purpose)
2. [Quick Start](#quick_start)
3. [Usage](#usage)
4. [Malware Detectors](#detectors)

### Purpose <a href="#purpose" id="purpose"></a>

A compromised software supply chain can result in alterations to the software, potentially serving as a vector for malware distribution. Allowing malicious actors to introduce harmful code, unintended behaviors and backdoors.&#x20;

**Malicious Code Evidence** consists of indicators of malicious software (malware) identified through static analysis of the target software. Analyzing software for potential supply chain vulnerabilities complements software security reviews with automation. Adversaries often employ obfuscation techniques to conceal their alterations from human review, but these methods can also provide evidence of their behaviour. See ([Common types of Malware found in Open Source Packages](https://docs.xygeni.io/xygeni-products/open-source-security-oss/malware-early-warning-mew/common-types-of-malware-found-in-open-source-packages))&#x20;

Based on the collected evidence, a `maliciousness score` is calculated for the software being analyzed. If sufficient evidence is gathered, the software may be classified as potentially malicious.

The **Malware Scanner** is a tool that analyzes software project files and reports the evidence detected by the active malware policies assigned to the project. Detected evidence can be uploaded to Xygeni platform for consolidation and for enabling response actions.

{% hint style="info" %}
The `maliciousness score` of the project depends on the total **quantity** and **severity** of the **evidence identified**.
{% endhint %}

### Quick Start <a href="#quick_start" id="quick_start"></a>

Use the following command to run and upload the results of the **Malware Scan** to the **Xygeni Platform.** This command will scan the current directory for the target project.

```bash
xygeni malware -n MyProject --upload
```

{% hint style="info" %}
Malware scanner can be run in two different ways:

* Running its own specific command ( `xygeni malware [options]` )
* Running the general command ( `xygeni scan --run="malware" [options]` )
  {% endhint %}

Export malware evidence with critical severity to CSV for review or to import findings into other tools:

```bash
xygeni malware -n MyProject --detectors critical \
       --format csv --output MyProject.malware.csv
```

### &#x20;Usage <a href="#usage" id="usage"></a>

Use the `xygeni malware [options]` command to execute the Malware Scanner.

To view all available options, use the `--help` flag:

```bash
xygeni malware --help
```

The most important properties are:

* **Name** of the Xygeni Project `-n` or `--name`.
* **Input source** to analyze. Either specify a **directory** with: `-d` or `--dir` or specify a **repository** using: `--repo`. The scan will analyze the current working directory when no target is specified.
* **Upload** results to the service `--upload`. By default, results are not uploaded.
* **Output file** (`-o` or `--output`) and **format** (`-f` or `--format`). If no output file is specified (or stdout / - are used), the standard output is used. Use `--format=none` for no output.
* Specify what detectors to run with the `--detectors` / `--skip-detectors` options. A common use-case is to consider only issues with high or critical severity with `--detectors=high`.
* The *resource kinds* to be scanned could also be tailored with the `--kinds` / `--skip-kinds` options.

```bash
Configuration options:
      --custom-detectors-dir=<customDetectorsDir>
                             Directory with custom detectors.
      --detectors=<detectors>
                             Comma-separated list of IDs for detectors to run, PRIORITY or 'all'
      --skip-detectors=<skipDetectors>
                             Comma-separated list of IDs for detectors to ignore, or PRIORITY
      --kinds=<kinds>        Resource kinds to scan (execution, file, network, _package, registry,
                               sensitive_data, system, all).
      --skip-kinds=<skipKinds>
                             Resource kinds to ignore (execution, file, network, _package, registry,
                               sensitive_data, system, all).
```

### Malware Detectors <a href="#detectors" id="detectors"></a>

Please refer to the [Malware detectors](https://docs.xygeni.io/xygeni-products/code-security-cs/malware-scanner/malware-detectors) documentation for information regarding this topic.