> For the complete documentation index, see [llms.txt](https://docs.xygeni.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xygeni.io/xygeni-products/xygeni-shield/files-and-scans.md).

# File protection and scans

Inspecting downloads stops most threats, but packages also reach a machine in other ways: copied from a USB drive, downloaded by a tool that bypasses Shield, extracted from another archive, or already on disk before Shield was installed. Shield covers those cases with **file protection**, which watches package files as they are written, and **on-demand scans**, which look for dangerous packages already on the machine.

Both use the same checks as downloads: the Xygeni malicious packages database, your Black/White list and the minimum-age policy. Shield recognises a package by its contents, not by its file name.

### File protection

File protection is on by default.

* **Linux**: Shield watches `/tmp`, `/var/tmp`, `/media`, `/mnt` and `/run/media`, and blocks a dangerous package file when a program tries to open it.
* **Windows**: Shield watches each user's **Downloads** and **Temp** folders and the package-manager caches (npm, pip, uv, poetry, Cargo, Maven, NuGet, RubyGems, Go, Composer, VS Code and JetBrains extensions). A dangerous package file is moved to quarantine right after it is written.

When a file is blocked, it is moved to the **quarantine**, a protected folder where it can do no harm, and you get a desktop notification and an alert. The folders watched can be changed in the [agent settings](https://docs.xygeni.io/xygeni-products/xygeni-shield/agent-settings.md#the-configuration-file).

### Quarantine

Quarantined files are listed in the tray app's **Quarantine** tab, and with the command line:

```bash
sudo xygeni-fw fs quarantine list                       # newest first: date, package, reason, SHA-256
sudo xygeni-fw fs quarantine release <sha256>           # copy the file out for inspection
sudo xygeni-fw fs quarantine release <sha256> --dest /tmp/sample.bin
sudo xygeni-fw fs quarantine purge <sha256>             # delete one file permanently
sudo xygeni-fw fs quarantine purge --all                # empty the quarantine
```

**Release** copies the file to your Downloads folder as `xygeni-released-<sha>-<name>.bin` (or to `--dest`), so it cannot be run or installed by mistake. The quarantined copy is kept, and the released copy is not quarantined again. Only an administrator or the user who activated Shield on the machine can release or delete quarantined files.

{% hint style="danger" %}
A released file is still dangerous. Release files only to analyze them, never to use them.
{% endhint %}

To check a file without waiting for Shield to see it:

```bash
xygeni-fw fs test ./some-package.tgz      # what it is, and whether Shield would block it
```

### On-demand scans

A scan looks for dangerous packages already on the machine: installed before Shield, restored from a backup, or found malicious after they were downloaded.

| Scan      | What it checks                                                                                                                                                                                                                                                                                                                | Typical duration                                        |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| **Quick** | The usual package locations of every supported ecosystem: npm cache and global packages, Python environments and caches, Maven and Gradle caches, NuGet, RubyGems, Cargo, Go, Composer, GitHub workflows in your repositories, VS Code / Cursor / VSCodium extensions, JetBrains and Eclipse plugins, and browser extensions. | Minutes                                                 |
| **Full**  | Everything Quick checks, plus the whole file system (on Windows, every fixed drive), skipping system folders.                                                                                                                                                                                                                 | Longer; meant for periodic checks and incident response |

Start a scan from the tray app (**Scans** tab, or the **Run quick scan** / **Run full scan** menu entries), or from the command line:

```bash
sudo xygeni-fw scan quick                  # quick scan
sudo xygeni-fw scan quick --dry-run        # report only, do not quarantine
sudo xygeni-fw scan full                   # full scan
xygeni-fw scan status                      # progress of the current scan
xygeni-fw scan cancel                      # stop it (Ctrl-C also works)
xygeni-fw scan list                        # past scans, newest first
xygeni-fw scan show <scan-id>              # details of one past scan
```

The tray's **Scans** tab shows the scan in progress (phase, elapsed time, a progress bar and the counters) and the past scans. The counters are:

* **discovered**, **scanned**, **skipped** and **allowed**: the packages found and checked,
* **alerts**: the packages that would be blocked,
* **quarantined**: the files actually moved to quarantine (none with `--dry-run`).

Scans run with low priority so they do not slow down your work, and they slow down further when the machine is busy. The command exits with an error code when it finds something, so it can also be used as a check in scripts.

### Auditing GitHub Actions workflows

`xygeni-fw scan-workflow` checks the actions your GitHub workflows use (`uses: owner/repo@ref`) against the Xygeni malicious packages database, without running anything:

```
$ xygeni-fw scan-workflow .
[xygeni] scan-workflow - 1 file(s), 3 `uses:` reference(s)
uses (owner/repo@ref)                       verdict     source
actions/checkout@v4                         CLEAN       .github/workflows/release.yml:7
tj-actions/changed-files@v44.0.0            DENY        .github/workflows/release.yml:8
actions/setup-node@v4                       CLEAN       .github/workflows/release.yml:10
```

It accepts a workflow file, a repository or a folder with many repositories, and exits with an error when it finds a malicious action, so you can run it as a pre-commit hook.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.xygeni.io/xygeni-products/xygeni-shield/files-and-scans.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
