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

# Managing Shield from the dashboard

When your subscription includes Shield with **centralized configuration**, your security team manages every machine from the Xygeni dashboard:

* the **protection policy** is defined once, in **configurations**, and Shield applies it automatically on each machine,
* every block is reported as an **alert**,
* every machine appears in the **Endpoints** inventory, where it can be **isolated** from the network.

Nothing has to be configured on the machines beyond [activating Shield](https://docs.xygeni.io/xygeni-products/xygeni-shield/activating.md) with a token.

{% hint style="info" %}
The Shield screens are available to users with the **Root** or **Manager policy** role, on subscriptions that include Shield with centralized configuration.
{% endhint %}

### Shield configurations

Open the **Settings** menu (gear icon at the top right) and choose **Shield**.

<figure><img src="https://4096647782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUTz59rJLkJBjiRWAMknU%2Fuploads%2Fgit-blob-6bbb77f17c3425991c6809734044d0d354ffd252%2Fshield-01-configurations.png?alt=media" alt="List of Shield configurations"><figcaption><p>Shield configurations</p></figcaption></figure>

A **configuration** is a complete protection policy that applies to a group of machines. You can have several, for example a strict one for build servers and CI runners and a more permissive one for developer workstations.

Configurations are **evaluated from top to bottom**: each machine runs the **first** configuration that matches it. The **Default** configuration (marked **Fallback**) is always last and applies to every machine that no other configuration matches.

The list shows, for each configuration:

* **Evaluated**: its position in the evaluation order.
* **Endpoint type | OS** and **Endpoint tags**: which machines it targets.
* **Endpoints**: how many machines currently run it. A `0` highlighted in orange means that no machine matches the configuration: check its targeting.
* **Enabled**: turn a configuration off without deleting it. Machines that matched it move to the next configuration that matches them.

Use **Add configuration** to create one, and the row menu (**⋮**) to **Edit**, **Move up**, **Move down** or **Delete** it. Machines pick up any change within about 30 seconds.

### Choosing which machines a configuration applies to

Open a configuration and go to the **Scope** tab:

<figure><img src="https://4096647782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUTz59rJLkJBjiRWAMknU%2Fuploads%2Fgit-blob-79dbeed99d3b533ded3782bce1adb02bc952ed94%2Fshield-02-scope.png?alt=media" alt="Scope tab of a Shield configuration"><figcaption><p>Scope: which machines run this configuration</p></figcaption></figure>

* **Endpoint types**: **Developer workstation**, **Server**, **CI/CD runner**, **Container** or **Unknown**.
* **Operating systems**: **Windows**, **Linux** or **macOS**.
* **Tags**: type a tag and press Enter. With more than one tag, choose whether the machine must carry **any** of them or **all** of them.

A configuration must target at least one endpoint type, operating system or tag. Scope changes are saved immediately.

The endpoint type and the tags of each machine are set in the **Endpoints** inventory (see [Endpoints inventory](#endpoints-inventory)).

### Defining the policy

The **Configuration** tab holds the policy itself, in four sections. Changes in these sections are saved together: click **Save** at the bottom of the page, or **Discard changes** to undo them. To rename the configuration, click the pencil icon next to its name.

For what each option means and how a download is decided, see [Protection policy](https://docs.xygeni.io/xygeni-products/xygeni-shield/protection-policy.md) and [Geo-blocking and registry control](https://docs.xygeni.io/xygeni-products/xygeni-shield/network-controls.md).

#### Min-age policy

<figure><img src="https://4096647782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUTz59rJLkJBjiRWAMknU%2Fuploads%2Fgit-blob-2ed7471ca8fac6bd12b47606ecd8e1777c5b0e60%2Fshield-03-min-age.png?alt=media" alt="Min-age policy tab"><figcaption><p>Min-age policy</p></figcaption></figure>

* **Global threshold**: block package versions published fewer than this many **Days** ago. Leave it empty or `0` to turn the global rule off.
* **On unknown publication date**: what to do when the publication date cannot be found: **Warn (log + allow)**, **Deny (strict posture)** or **Allow (silent)**.
* **Per-ecosystem overrides**: a different threshold for one ecosystem (`0` turns the check off for it).
* **Per-package thresholds**: a different threshold for one package.
* **Always allow** (bypass min-age): packages allowed even when they are newer than the threshold, typically your own packages.
* **Always deny** (regardless of age): packages always blocked, whatever their age and the rest of the policy.

#### Black/White list

<figure><img src="https://4096647782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUTz59rJLkJBjiRWAMknU%2Fuploads%2Fgit-blob-fce7bc3935e0e6cd8e4e58b4c8f511fcdbc4c5ea%2Fshield-04-black-white-list.png?alt=media" alt="Black/White list tab"><figcaption><p>Black/White list</p></figcaption></figure>

* **Enable Black/White list**: when it is off, only the minimum-age policy applies. Your rules are kept while it is off.
* **Mode**:
  * **Allow by default (blocklist)**: everything is allowed except the packages listed.
  * **Deny by default (allowlist)**: only the packages listed are allowed.
* **Packages**: exact package names. Choose the **Ecosystem**, enter the **Package name** and, optionally, the **Versions** (for example `^4.0.0, 3.0.1`; empty means every version) and a **Reason**, which developers see when the rule blocks a download. Click **+ Add**.
* **Patterns**: the same, for groups of packages: `@evil-org/*` (glob), or a regular expression with the `regex:` prefix.

The pencil and bin icons edit and remove a rule.

**Import CSV** adds many rules at once from a CSV file with a header row: `ecosystem,name,versions,reason` for packages, `ecosystem,pattern,versions,reason` for patterns, with several versions separated by `;`. The file can be added to the existing list or replace it. **Always allow** and **Always deny** in the Min-age policy section also accept CSV import.

#### Registries

<figure><img src="https://4096647782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUTz59rJLkJBjiRWAMknU%2Fuploads%2Fgit-blob-3cb755772938bf6e00fd4627c9e967fd77741eb3%2Fshield-05-registries.png?alt=media" alt="Registries tab"><figcaption><p>Registries</p></figcaption></figure>

* **Enable registry source control** and choose the **Mode**: **Allow by default (blocklist)** blocks the registries listed; **Deny by default (allowlist)** only allows the registries listed.
* Each entry is a **Registry / URL** (a host such as `registry.npmjs.org`, or a pattern such as `glob:https://repo.internal/*`), an optional **Ecosystem** (all ecosystems when empty) and an optional **Reason**.

For GitHub Actions, list `codeload.github.com`, not `github.com`.

#### Geo blocking

<figure><img src="https://4096647782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUTz59rJLkJBjiRWAMknU%2Fuploads%2Fgit-blob-2b5d848f2cd7273d42d877161f357b7d2692c754%2Fshield-06-geo-blocking.png?alt=media" alt="Geo blocking tab"><figcaption><p>Geo blocking</p></figcaption></figure>

* **Enable geo blocking** and choose the **Mode**: **Allow by default (blocklist)** blocks traffic to the countries listed; **Deny by default (allowlist)** only allows traffic to them.
* **Countries**: pick the countries from the list.
* **Unknown country**: what to do when the country of a destination cannot be determined: **Warn (log + allow)**, **Deny (strict posture)** or **Allow (silent)**.

Geo-blocking applies to every connection from the machine, not only package downloads.

#### Paranoid mode

The **Paranoid mode** switch, at the right of the policy sections, makes Shield react automatically: while it is on, **any critical alert** on a machine that runs this configuration **isolates that machine** from the network until someone releases it (see [Network isolation](https://docs.xygeni.io/xygeni-products/xygeni-shield/network-isolation.md)). Use it for machines where a confirmed threat must be contained at once, such as build servers.

### Alerts

Every block is reported to Xygeni within seconds and shown with the rest of the platform's suspicious activity, with the `xygeni_shield_block` detector. Each alert has a severity:

| Alert                                                                             | Severity |
| --------------------------------------------------------------------------------- | -------- |
| Connection to a known-malicious IP address or domain                              | Critical |
| Package found in Xygeni's malicious packages research                             | Critical |
| Package reported as malicious by other sources, with high confidence (80 or more) | Critical |
| Package reported as malicious by other sources, with lower confidence             | High     |
| Package blocked by your Black/White list, the minimum age or registry control     | High     |
| Connection blocked by geo-blocking                                                | Low      |

Alerts of a machine are also listed in its **Audit trail** in the Endpoints inventory.

### Endpoints inventory

Open **Inventory → Endpoints**:

<figure><img src="https://4096647782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUTz59rJLkJBjiRWAMknU%2Fuploads%2Fgit-blob-8cd961e562798524cf776358b77c1b8aeeb38276%2Fshield-07-endpoints.png?alt=media" alt="Endpoints inventory"><figcaption><p>Endpoints inventory</p></figcaption></figure>

The top of the page summarizes the fleet: the number of machines and how many are isolated, the **Shield seats** in use out of the contracted ones and how many are pinned, the machines by type, and the alerts by severity.

The list shows every machine with Shield, with filters by hostname, endpoint type, status, operating system and configuration:

* **Hostname**, with the operating system and the Shield version.
* **Type** and **IP** (the machine's last known address).
* **Last seen** and **Status**: **Active** (seen in the last few minutes), **Idle** (seen in the last day) or **Offline** (not seen for more than a day).
* **Alerts**, by severity.
* **Isolation**: **Normal**, **Isolating…**, **Isolated** or **Releasing…**.
* **Configuration**: the configuration the machine runs. The tooltip tells you why (matched by type, by tag, or default).
* **License**: **Licensed** or **Dormant**, and the pin that reserves a seat for the machine (see [Shield seats](#shield-seats)).

Click a machine to open its details:

<figure><img src="https://4096647782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUTz59rJLkJBjiRWAMknU%2Fuploads%2Fgit-blob-11c5ddc7c5bb800041f8ab2c44a730bebe55cd0a%2Fshield-08-endpoint-detail.png?alt=media" alt="Endpoint details"><figcaption><p>Endpoint details</p></figcaption></figure>

* **System**: the machine's details, its isolation state, its seat and its configuration. **Edit type & tags** sets the endpoint type and the tags that the configurations use to target it.
* **Audit trail**: the machine's alerts, newest first.
* **Components**: the packages, extensions and plugins found on the machine, refreshed every few hours.

The **Actions** menu isolates or releases the machine, pins or unpins its seat, and generates a manual release code:

<figure><img src="https://4096647782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUTz59rJLkJBjiRWAMknU%2Fuploads%2Fgit-blob-3cb8bdc80395ca2c3832cdb263f2591fbf1ebc97%2Fshield-09-endpoint-actions.png?alt=media" alt="Endpoint actions menu"><figcaption><p>Endpoint actions</p></figcaption></figure>

### Shield seats

Your subscription includes a number of **Shield seats**: the maximum number of machines that can be protected at the same time.

Seats are assigned **automatically**. A machine takes a free seat when it reports to Xygeni and gives it back when it stops reporting, so short-lived machines such as CI runners and autoscaled servers share the seats without anyone assigning them.

* When no seat is free, the machine becomes **dormant**: Shield stops protecting it, as if it were not installed, and `xygeni-fw status` shows `License: DORMANT`. It takes a seat again as soon as one is released.
* If a machine cannot reach Xygeni, it keeps its protection for up to **72 hours** after its last confirmation.

**Pinning** a machine reserves a seat for it permanently, even while it is switched off, so it never has to compete for one. Pin the workstations and servers that must always be protected, and leave CI runners and temporary machines floating. Pin a machine with the pin icon in the **License** column, or with **Pin (reserve a Shield seat)** in its **Actions** menu. You cannot pin more machines than you have seats.

Seats are also used without centralized configuration, but those machines do not appear in the dashboard, so they cannot be pinned.


---

# 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/dashboard.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.
