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

# Geo-blocking and registry control

Besides checking each package, Shield can control **where** your machines connect to and **where** packages come from. On a centrally managed machine both are set in the dashboard, in the **Geo blocking** and **Registries** tabs of each configuration (see [Managing Shield from the dashboard](https://docs.xygeni.io/xygeni-products/xygeni-shield/dashboard.md)). On a locally configured machine, use the tray app's **Policy** tab or the commands below.

Both use the same three modes as the Black/White list:

| Mode                             | Behaviour                                              |
| -------------------------------- | ------------------------------------------------------ |
| **Disabled**                     | No control (default).                                  |
| **Allow by default** (blocklist) | Everything is allowed except what is in the deny list. |
| **Deny by default** (allowlist)  | Only what is in the allow list is allowed.             |

### Geo-blocking

Geo-blocking controls connections by the **country of the destination**. It applies to every outbound connection from the machine, not only package downloads.

* Countries are written as two-letter ISO codes: `RU`, `CN`, `KP`...
* The **unknown country** setting decides what happens when the country of a destination cannot be determined: **warn** (allow and log it, the default), **deny** or **allow**.
* The country database ships with Shield and is updated automatically, so geo-blocking also works offline.

What a blocked connection looks like:

* Web requests through Shield get a **403** response that names the blocked country, and the block is recorded as an alert.
* On Linux, other connections (any port or protocol) to a blocked country are dropped. System services and Shield's own connection to Xygeni are never cut.
* On Windows, connections to a blocked country are refused by the Windows firewall, so the tool reports a connection error instead of a 403.

```bash
sudo xygeni-fw policy geo mode allow-default
sudo xygeni-fw policy geo deny add RU --reason "sanctioned"
sudo xygeni-fw policy geo deny add KP
sudo xygeni-fw policy geo unknown warn
xygeni-fw policy geo show
xygeni-fw geo lookup example.com      # which country, and would it be blocked?
```

### Registry control

Registry control restricts the registries and URLs packages may be **downloaded** from. Use it to make sure packages only come from your approved registries, or to ban a specific mirror. Normal web browsing is never affected.

Each entry is:

* a host (`registry.npmjs.org`, `*.npmjs.org`) or a pattern over the full URL (`glob:https://repo.internal/*`),
* optionally an **ecosystem**, so the rule only applies to that ecosystem's downloads,
* optionally a **reason**, shown in the block.

{% hint style="info" %}
GitHub Actions are downloaded from `codeload.github.com`, not from `github.com`. List `codeload.github.com` to allow or block them.
{% endhint %}

```bash
# Only allow npm, GitHub Actions and an internal PyPI mirror
sudo xygeni-fw policy registry mode deny-default
sudo xygeni-fw policy registry allow add registry.npmjs.org
sudo xygeni-fw policy registry allow add codeload.github.com
sudo xygeni-fw policy registry allow add repo.internal.example.com --ecosystem pypi
xygeni-fw policy registry show
```

With this policy, `pip install` from the public PyPI is blocked with a 403, while npm, GitHub Actions and the internal mirror keep working.


---

# 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/network-controls.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.
