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

# Protection policy

The Xygeni malicious packages database protects every activated machine without any configuration. The **protection policy** adds your organization's own rules on top of it:

* the **Black/White list**: packages you always block, or the only packages you allow,
* the **minimum-age policy**: block package versions that were published too recently,
* **geo-blocking** and **registry control**, described in [Geo-blocking and registry control](https://docs.xygeni.io/xygeni-products/xygeni-shield/network-controls.md).

{% hint style="warning" %}
The policy, local rules included, only applies while Shield is activated with a valid token. See [Activating Shield](https://docs.xygeni.io/xygeni-products/xygeni-shield/activating.md).
{% endhint %}

### Where the policy is defined

|                    | Centrally managed machine                                                                                                                             | Locally configured machine                                                        |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Where you edit it  | Xygeni dashboard, **Settings → Shield**. See [Managing Shield from the dashboard](https://docs.xygeni.io/xygeni-products/xygeni-shield/dashboard.md). | On the machine: the tray app's **Policy** tab, or the `xygeni-fw policy` command. |
| When changes apply | Within about 30 seconds. `xygeni-fw policy sync` fetches the policy immediately.                                                                      | Immediately, without restarting anything.                                         |
| Local edits        | Not allowed: the tray and the command line show that the policy is managed by Xygeni Cloud.                                                           | Allowed.                                                                          |

On a centrally managed machine the last policy received is kept and applied even while the machine is offline.

To see which policy a machine is applying:

```bash
xygeni-fw policy show      # the policy in force, whatever its origin
xygeni-fw policy status    # centrally managed machines: last synchronization and errors
```

### How a download is decided

1. **Geo-blocking and registry control** are checked first: if the destination country or the registry is not allowed, the download is blocked.
2. Then the package is checked in this order, and **the first match decides**:
   1. the minimum-age **Always deny** list (always blocks, whatever the rest of the policy says),
   2. the **Black/White list**,
   3. the **Xygeni malicious packages database**,
   4. the **minimum-age** threshold,
   5. otherwise, the package is allowed.

### Black/White list

The Black/White list has three modes:

| Mode                             | Behaviour                                                                        |
| -------------------------------- | -------------------------------------------------------------------------------- |
| **Disabled**                     | The list is not used.                                                            |
| **Allow by default** (blocklist) | Everything is allowed except the packages in the **deny** list.                  |
| **Deny by default** (allowlist)  | Only the packages in the **allow** list are allowed; everything else is blocked. |

Only the list that matches the mode is used: in *Allow by default* the allow list is ignored, and in *Deny by default* the deny list is ignored. An allow entry therefore never creates an exception to a deny rule.

Each rule names a package, or a pattern of package names, in one ecosystem, and optionally:

* the **versions** it applies to (all versions when omitted),
* a **reason**, which is shown to the developer when the rule blocks a download.

#### Package names

| Ecosystem                        | Name format                                                 |
| -------------------------------- | ----------------------------------------------------------- |
| npm                              | Lowercase; scoped packages as `@scope/name`                 |
| PyPI                             | Lowercase; `_` and `.` are treated as `-`                   |
| Maven                            | `groupId:artifactId` (case-sensitive)                       |
| NuGet, RubyGems, Cargo, Composer | Lowercase                                                   |
| Go modules                       | Full module path, for example `github.com/BurntSushi/toml`  |
| GitHub Actions                   | `owner/repo`                                                |
| VS Code, Visual Studio           | `publisher.extension`                                       |
| JetBrains                        | Plugin id, numeric (`12345`) or text (`org.rust-lang.rust`) |
| Eclipse                          | Marketplace node id                                         |

#### Patterns

* `@my-org/*`: `*` matches any text and `?` a single character.
* `regex:^typo[0-9]+`: a regular expression, for more complex cases.

#### Versions

| Version             | Matches                                      |
| ------------------- | -------------------------------------------- |
| `=1.2.3`            | Exactly 1.2.3                                |
| `1.2.3` or `^1.2.3` | 1.2.3 and later, up to (not including) 2.0.0 |
| `~1.2.3`            | 1.2.3 and later, up to (not including) 1.3.0 |
| `>=1.0,<2.0`        | Both conditions (AND)                        |
| `1.0 \|\| 2.0`      | Either condition (OR)                        |
| (empty)             | Every version                                |

{% hint style="warning" %}
A plain version such as `1.2.3` means `^1.2.3`, not exactly `1.2.3`. Write `=1.2.3` to target a single version.
{% endhint %}

For PyPI, versions follow the Python rules (PEP 440): pre-releases, post-releases and epochs are compared correctly, and the operators `==`, `!=`, `~=`, `===` and `==1.4.*` are also accepted. To err on the side of safety, pre-releases always count: a rule for `<2.0` also matches `2.0rc1`.

### Minimum-age policy

Most supply-chain attacks are found and removed from the registries within hours or days. The minimum-age policy blocks any package version published fewer days ago than the threshold, so new malicious versions are stopped before anyone has reported them.

The threshold can be set at three levels; the most specific one applies:

1. **Per package**: for example, a longer cooling period for a critical dependency.
2. **Per ecosystem**: for example, 14 days for npm.
3. **Global**: 7 days is a good starting value.

A threshold of `0` turns the check off for that package or ecosystem.

Two exception lists complete it:

* **Always allow (bypass min-age)**: packages allowed even if they are newer than the threshold. Typical for packages your own teams publish every day.
* **Always deny (regardless of age)**: packages that are always blocked, whatever their age or the rest of the policy.

When Shield cannot find out the publication date (the registry does not answer, for example), the **unknown age** setting decides: **warn** (allow and log it, the default), **deny** (block) or **allow** (allow silently).

The minimum age applies both to downloads and to package files written to disk.

### Editing the local policy

On a locally configured machine, use the tray app's **Policy** tab, or the command line:

```bash
sudo xygeni-fw policy mode deny-default            # disabled | allow-default | deny-default
sudo xygeni-fw policy allow add --ecosystem npm --name lodash --version "^4.17.21" --reason "vetted - SEC-1234"
sudo xygeni-fw policy allow add-pattern --ecosystem npm --pattern "@my-org/*" --reason "our own packages"
sudo xygeni-fw policy deny add --ecosystem pypi --name some-package --reason "not approved"
sudo xygeni-fw policy force-deny add --ecosystem npm --name some-package --reason "IR-2026-01"   # Always deny
sudo xygeni-fw policy allow remove --ecosystem npm --name lodash
xygeni-fw policy list                               # your rules
xygeni-fw policy show                               # the policy in force
```

The policy is stored in `/etc/xygeni-fw/policy.yaml` (`C:\ProgramData\Xygeni\Shield\config\policy.yaml` on Windows). You can also edit it with `sudo xygeni-fw policy edit`, which checks the file when you save it, and check a file with `xygeni-fw policy validate <file>`. Changes apply as soon as the file is saved; if the file is not valid, the previous policy stays in force.

{% code title="policy.yaml" %}

```yaml
policy_mode: allow_default            # disabled | allow_default | deny_default

deny_packages:                        # used in allow_default
  - ecosystem: pypi
    name: some-package
    versions: ["<2.0"]
    reason: "known vulnerable"

deny_patterns:                        # used in allow_default
  - ecosystem: npm
    pattern: "regex:^typo[0-9]+"
    reason: "typosquats"

allow_packages: []                    # used in deny_default
allow_patterns: []                    # used in deny_default

min_age_force_deny:                   # Always deny
  - ecosystem: npm
    name: some-package
    reason: "never install this"

min_age_days: 7                       # global threshold
min_age_days_per_ecosystem:
  npm: 14
  maven: 0                            # disabled for Maven
min_age_overrides:
  - ecosystem: npm
    name: "@my-org/internal-cli"
    min_age_days: 0                   # Always allow (bypass min-age)
on_unknown_age: warn                  # allow | warn | deny
```

{% endcode %}

### Examples

**Only allow vetted packages.** Use *Deny by default* and list what your team has approved:

```bash
sudo xygeni-fw policy mode deny-default
sudo xygeni-fw policy allow add --ecosystem npm --name lodash --version "^4.17.21"
sudo xygeni-fw policy allow add-pattern --ecosystem npm --pattern "@my-org/*"
```

**Protect against dependency confusion.** If your internal packages must only come from your private registry, deny their scope from the public one:

```bash
sudo xygeni-fw policy mode allow-default
sudo xygeni-fw policy deny add-pattern --ecosystem npm --pattern "@my-org/*" \
    --reason "internal scope, use the private registry"
```

**Block one line of versions of a whole organization:**

```bash
sudo xygeni-fw policy deny add-pattern --ecosystem npm --pattern "@some-org/*" \
    --version "^1.0.0" --reason "1.x is unmaintained"
```


---

# 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/protection-policy.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.
