> 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/everyday-use.md).

# Using Shield day to day

Once Shield is active, there is nothing to do in your daily work. `npm install`, `pip install`, `mvn`, `gradle`, `cargo`, `go get`, `dotnet restore` and IDE extension installs work as usual. You do not need to configure a proxy or certificates in your tools.

### When a package is blocked

The tool that requested the package fails with an HTTP **403** error, and the response explains which package was blocked and why:

{% code title="A package denied by your organization's rules" %}

```
$ npm install is-odd@3.0.1
npm error 403 Blocked by Xygeni Shield
npm error 403
npm error 403   Package:  is-odd@3.0.1
npm error 403   Reason:   not approved by the security team (SEC-1234)
```

{% endcode %}

{% code title="A package found in the Xygeni malicious packages database" %}

```
Blocked by Xygeni Shield

  Package:  <package>@<version>
  Reason:   malware DB: XYG-DD-1234 confidence=90 sources=3
```

{% endcode %}

{% code title="A package published too recently (minimum-age policy)" %}

```
Blocked by Xygeni Shield

  Package:  next@16.2.6
  Reason:   min-age: published 0d ago, minimum is 7d
```

{% endcode %}

The **Reason** line tells you what to do next:

| Reason starts with                                                   | What it means                                                                      | What you can do                                                                                                                                                                                                        |
| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `malware DB:`                                                        | The package version is known to be malicious. The reason includes the advisory ID. | Do not use this version. Pick another version or another package. If you believe it is a false positive, contact your security team.                                                                                   |
| `min-age:`                                                           | The version was published fewer days ago than your policy requires.                | Wait until it is old enough, use an older version, or ask your security team for an exception. See [Minimum-age policy](https://docs.xygeni.io/xygeni-products/xygeni-shield/protection-policy.md#minimum-age-policy). |
| The text of a rule (for example `not approved by the security team`) | Your organization's Black/White list does not allow this package.                  | Ask your security team, who manage the policy.                                                                                                                                                                         |
| `registry` / `geo` related                                           | The download came from a registry or a country your policy does not allow.         | See [Geo-blocking and registry control](https://docs.xygeni.io/xygeni-products/xygeni-shield/network-controls.md).                                                                                                     |

Every block also raises a desktop notification and appears in the tray app's **Alerts** tab. On a centrally managed machine it is reported to the Xygeni dashboard as well.

### Checking a package before using it

`xygeni-fw test` tells you whether a package would be allowed, without downloading it. It applies every check Shield applies to a real download:

```
$ xygeni-fw test npm lodash 4.17.21
Package:    lodash@4.17.21
Ecosystem:  npm
Published:  2021-02-20T15:42:16+00:00  (2075d ago)
Min-age:    7d threshold
Action:     ALLOW (default)

$ xygeni-fw test npm next 16.2.6
Package:    next@16.2.6
Ecosystem:  npm
Published:  2026-10-28T09:01:54+00:00  (0d ago)
Min-age:    7d threshold
Action:     BLOCK (min_age)
Reason:     min-age: published 0d ago, minimum is 7d
```

The ecosystem accepts the usual names and aliases: `npm`, `yarn`, `pypi`, `pip`, `maven`, `gradle`, `nuget`, `dotnet`, `gem`, `cargo`, `rust`, `golang`, `go`, `composer`, `php`, `github-actions`, `vscode`, `jetbrains`, `eclipse` and `visual-studio`.

### The tray app

The tray app shows Shield's state at a glance and gives access to alerts, quarantined files, scans and the local policy.

#### Tray icon

| Icon                      | Meaning                                                                                                                                                                                                    |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Xygeni mascot             | Shield is active and protecting the machine.                                                                                                                                                               |
| Mascot with a red dot     | There are new alerts you have not seen yet.                                                                                                                                                                |
| Mascot with a red padlock | The machine is isolated from the network by your security team. See [Network isolation](https://docs.xygeni.io/xygeni-products/xygeni-shield/network-isolation.md).                                        |
| Grey mascot               | Shield is **not** protecting the machine. The first line of the tray menu and the panel explain why: no token, a token without the Shield permission, no Shield seat available, or the service is stopped. |

#### Panel

Click the tray icon to open the panel. If Shield is not activated yet, the panel shows the **Activate Xygeni Shield** screen, where you paste your token. Once active, it has four tabs:

* **Alerts**: the latest blocks, with the package, the reason and a coloured dot for the severity. **Mark all as read** and **Clear all** only affect your view; the alerts themselves are kept.
* **Quarantine**: the files that Shield's file protection took out of the way (see [File protection and scans](https://docs.xygeni.io/xygeni-products/xygeni-shield/files-and-scans.md)). **Release** copies a file to your Downloads folder as `xygeni-released-<sha>-<name>.bin` so you can inspect it (the quarantined copy is kept); **Delete** removes it permanently. Both ask for confirmation and are only accepted from an administrator or from the user who activated Shield on the machine.
* **Scans**: choose **Quick** or **Full** and click **Start scan**, follow its progress, and review past scans.
* **Policy**: the Xygeni token, the local policy (on locally configured machines) and the state of the synchronization with Xygeni. On a centrally managed machine, the policy is shown read-only with a **Managed by Xygeni Cloud** banner: changes are made in the dashboard.

{% hint style="info" %}
On Linux, the tray app needs your user to be in the `xygeni-fw` group, which the installer sets up. The change only takes effect after you log out and log back in; until then the tray shows a permission error.
{% endhint %}

### Tools that do not trust the Shield certificate

To inspect downloads, Shield presents its own certificate to your tools. The installer adds it to the system trust store, but some tools keep their own list of trusted certificates (Java, Node.js, pip, git). Run this once to add the Shield certificate to them as well:

```bash
sudo xygeni-fw trust sync     # add the Shield certificate to Java, Node.js, pip and git
xygeni-fw trust status        # show which trust stores already include it
```

If a program still refuses the certificate (for example, a virtual machine or a container that does not trust it, or a tool that pins certificates), Shield does not break its traffic: it lets **that program** reach **that host** without inspection for a while, starting at 10 minutes and growing up to 24 hours if the problem repeats. Other programs on the machine are still inspected.

While that happens, `xygeni-fw status` shows a warning such as:

```
Bypass:   WARNING - 1 client/host pair(s) passed through UNINSPECTED (registry.npmjs.org); live downloads from them are not checked. See `xygeni-fw bypass list`.
```

Downloads from those programs are not checked during that time. To see them and restore inspection:

```bash
xygeni-fw bypass list                       # which program, which host, until when
xygeni-fw bypass clear registry.npmjs.org   # inspect that host again (all programs)
xygeni-fw bypass clear                      # inspect everything again
```

Then fix the program's trust (for example with `xygeni-fw trust sync`), or it will be passed through again on its next failure.


---

# 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/everyday-use.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.
