managing-network-policies

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Managing Network Policies

管理网络策略

A network policy is a named pair of IP lists -- addresses allowed to connect and addresses always refused -- kept per environment and assigned wherever access should be limited by source address. One policy can guard many things, and a policy guards nothing until it is assigned. Concerns when managing network policies:

What a policy decides -- deny beats allow, and an empty allow list admits everything the deny list doesn't name
Where it applies -- an MCP server, an account API token, workspace-user sign-in, or end-user sign-in
Editing safely -- a patch changes only what you name; a full replace empties every list it leaves out
Deleting -- an assigned policy is refused unless forced, and forcing lifts every restriction it imposed
Lockout -- a policy on the token or sign-in you are using applies to you

Only the account owner and administrators manage network policies, and the feature must be enabled for the account. Each environment (production, a sandbox) keeps its own library: a policy is visible and assignable only in the environment that created it.

网络策略是一个命名的一对 IP 列表——允许连接的地址和始终拒绝的地址——按环境分别保存，并分配到需要按源地址限制访问的任何位置。一个策略可以保护许多对象，但在被分配之前不会保护任何对象。管理网络策略时需要关注：

策略判定什么——拒绝优先于允许；如果允许列表为空，则允许拒绝列表未列出的所有内容
策略在哪里生效——MCP server、账户 API token、workspace-user 登录或 end-user 登录
安全编辑——patch 只更改指定的字段；完整替换会清空所有未提交的列表
删除——已分配的策略会被拒绝删除，除非强制执行；强制删除会解除该策略施加的所有限制
锁定——应用于当前所用 token 或登录的策略也会作用于你

仅账户所有者和管理员可管理网络策略，并且账户必须启用此功能。每个环境（production、sandbox）维护自己的策略库：策略仅在创建它的环境中可见和可分配。

How to Run the Steps

如何执行步骤

This skill names each step by what it reads or changes; the exact calls depend on how you reach the account. Read the one reference that matches your tools -- both follow the step numbers of How to Manage Network Policies below:

Celigo MCP tools -- references/mcp.md. The deployed server has no network-policy tools: it can only assign or clear a policy on an MCP server, so most steps go to the CLI or the integrator.io UI.
The
celigo
CLI -- references/cli.md

Assigning a policy to an API token or to sign-in happens only in the integrator.io UI, on either surface.

本 skill 按每一步读取或更改的内容来命名；具体调用方式取决于如何访问账户。请阅读与所用工具匹配的那一份参考文档——两者均遵循下文“如何管理网络策略”的步骤编号：

Celigo MCP 工具——references/mcp.md。已部署的 server 没有网络策略工具：它只能在 MCP server 上分配或清除策略，因此大多数步骤需使用 CLI 或 integrator.io UI 完成。
celigo
CLI——references/cli.md

将策略分配给 API token 或登录设置，只能在 integrator.io UI 中完成，无论从哪个入口进入均是如此。

How a Policy Decides

策略如何判定

Entries are IPv4 or IPv6 addresses or CIDR ranges (
```
203.0.113.5
```
,
```
10.0.0.0/8
```
,
```
2001:db8::/32
```
), at most 200 per list. A bare address is stored as
```
/32
```
or
```
/128
```
and IPv6 is compressed and lowercased, so compare against the stored form a read returns, not what you sent.
Deny always wins. An address on
```
ipDenyList
```
is refused even when
```
ipAllowList
```
covers it.
An empty allow list admits every address the deny list doesn't block. A deny-only policy blocks a few addresses and lets everything else through; a policy with both lists empty restricts nothing, even when assigned.
The address checked is where the request comes from, so list a VPN's or proxy's egress range rather than people's own machines.

条目可以是 IPv4 或 IPv6 地址，也可以是 CIDR 范围（
```
203.0.113.5
```
、
```
10.0.0.0/8
```
、
```
2001:db8::/32
```
），每个列表最多 200 条。裸地址会存为
```
/32
```
或
```
/128
```
，IPv6 地址会被压缩并转为小写，因此应与读取结果返回的存储形式比较，而不是与发送内容比较。
拒绝始终优先。 即使
```
ipAllowList
```
包含某个地址，只要它出现在
```
ipDenyList
```
中，就会被拒绝。
允许列表为空时，会允许拒绝列表未阻止的每个地址。 仅含拒绝项的策略会阻止少数地址，并放行其余所有地址；两个列表都为空的策略不会限制任何内容，即使已分配也是如此。
检查的地址是请求的来源地址，因此应列出 VPN 或 proxy 的出口地址范围，而不是用户自己的设备地址。

Where a Policy Applies

策略在哪里生效

Assigned to	Where it's set	What it restricts
An MCP server	The server's `_networkPolicyId` -- CLI or MCP	Every MCP protocol request to that server
An account API token	The token's network policy, in the integrator.io UI (the token API refuses bearer callers)	Every request authenticated with that token
Workspace-user sign-in	Account security settings, UI only	Workspace users signing in to that environment. Personal access tokens have no policy of their own and follow this one
End-user sign-in	Account security settings, UI only	MCP end users signing in

A policy's assignments are listed by its dependencies read: the MCP servers and API tokens that carry it, and whether it restricts workspace-user or end-user sign-in, per environment. An empty result means the policy restricts nothing and deletes without force.

分配给	设置位置	限制内容
MCP server	server 的 `_networkPolicyId` ——CLI 或 MCP	发往该 server 的每个 MCP 协议请求
账户 API token	integrator.io UI 中 token 的网络策略（token API 会拒绝 bearer 调用方）	使用该 token 进行身份验证的每个请求
workspace-user 登录	账户安全设置，仅限 UI	workspace user 登录该环境。Personal access token 没有自己的策略，并遵循此策略
end-user 登录	账户安全设置，仅限 UI	MCP end user 登录

读取策略的依赖项时，会按环境列出其分配情况：承载该策略的 MCP server 和 API token，以及它是否限制 workspace-user 或 end-user 登录。空结果表示该策略不限制任何内容，可以无需强制执行即可删除。

Quick Reference

快速参考

Decision Matrix

决策矩阵

You need to...	Do this
Limit one MCP server to known networks	Assign an allow-list policy to the server
Limit a service token (CI, a partner's script)	Assign a policy to the token in the UI
Limit where people can sign in from	Assign a policy to workspace-user sign-in in the UI; personal access tokens follow it
Limit where MCP end users can sign in from	Assign a policy to end-user sign-in in the UI
Refuse a few known-bad addresses, admit the rest	A deny-only policy (empty `ipAllowList` )
Change a range on every place a policy guards	Edit the policy once -- the change applies everywhere it's assigned

你需要……	请执行
将一个 MCP server 限制在已知网络中	向该 server 分配白名单策略
限制服务 token（CI、合作方的脚本）	在 UI 中向 token 分配策略
限制人员登录的来源网络	在 UI 中向 workspace-user 登录分配策略；personal access token 遵循该策略
限制 MCP end user 登录的来源网络	在 UI 中向 end-user 登录分配策略
拒绝少数已知不良地址并放行其余地址	使用仅含拒绝项的策略（ `ipAllowList` 为空）
更改策略所保护的所有位置中的某个范围	只需编辑策略一次——更改会应用到所有分配位置

Minimum Fields

最低必需字段

```
name
```
-- required, at most 150 characters, unique among the environment's live policies. Name it after the network ("Corporate VPN egress"), not after what it guards: one policy serves many assignments.
```
ipAllowList
```
,
```
ipDenyList
```
-- at most 200 entries each; omit a list only on create.
```
description
```
-- optional, at most 500 characters: what the ranges are and where they come from.

```
name
```
——必填，最多 150 个字符，在该环境的有效策略中唯一。请按网络命名（“Corporate VPN egress”），而不是按其保护对象命名：同一策略可用于多个分配。
```
ipAllowList
```
、
```
ipDenyList
```
——每个列表最多 200 条；仅在创建策略时可以省略某个列表。
```
description
```
——可选，最多 500 个字符：说明地址范围及其来源。

Field Reference

字段参考

The full request, response and assignment shapes are in the API reference's Network Policies page (agent-readable markdown). The assignments read returns

mcpservers

and

accesstokens

(each

{_id, name}

) and

account

workspaceUsers

and

endUsers

flags with the environments each applies to.

完整的请求、响应和分配结构见 API reference 的 Network Policies 页面（Agent 可读的 Markdown）。分配读取结果会返回

mcpservers

和

accesstokens

（各自为

{_id, name}

），以及

account

——其中包含

workspaceUsers

和

endUsers

标志，以及各自适用的环境。

Related Skills

How to Manage Network Policies

如何管理网络策略

1. Check what exists and where it's assigned

1. 检查现有策略及其分配位置

List the environment's policies, then read the assignments of any you might change. A policy assigned to nothing restricts nothing -- it isn't the reason a caller is refused, and it deletes without force.

列出环境中的策略，然后读取任何可能更改的策略的分配情况。未分配给任何对象的策略不会限制任何内容——它不是调用方被拒的原因，并且无需强制执行即可删除。

2. Decide the lists -- and check for lockout

2. 确定列表并检查锁定风险

Allow the networks that should reach the thing you're guarding; deny addresses to refuse even inside an allowed range.

Before you assign a policy, or edit one already assigned, check whether it covers your own access: the API token your CLI profile, script or MCP client signs in with, or workspace-user sign-in (which personal access tokens follow). If it does, keep the address you connect from on the allow list. An allow list that leaves it out locks that caller -- and every script using the same token -- out until someone repairs the policy from the UI or with another token.

允许应当能够访问受保护对象的网络；拒绝即使位于允许范围内也要阻止的地址。

在分配策略或编辑已分配策略之前，请检查它是否覆盖你自己的访问路径：CLI 配置文件、脚本或 MCP client 用于登录的 API token，或 workspace-user 登录（personal access token 也遵循此设置）。如果覆盖，请将你连接时使用的地址保留在允许列表中。允许列表遗漏该地址会锁定该调用方，以及使用同一 token 的所有脚本；直到有人通过 UI 或使用另一个 token 修复策略后，它们才能恢复访问。

3. Create the policy

3. 创建策略

Create it with a name, a description, and both lists. Read the response: entries come back in stored form. A live policy with the same name is refused with 409

conflict

; an entry that isn't an address or CIDR range (a hostname, an empty string, a prefix longer than the address family allows) with 400

invalid_cidr

; a list over 200 entries with 400

max_cidr_entries_exceeded

使用名称、描述和两个列表创建策略。读取响应：条目会以存储形式返回。同名有效策略会返回 409

conflict

；条目不是地址或 CIDR 范围（主机名、空字符串，或前缀长度超出相应地址族允许范围）时返回 400

invalid_cidr

；列表超过 200 条时返回 400

max_cidr_entries_exceeded

。

4. Assign it

4. 分配策略

MCP server -- set the server's
```
_networkPolicyId
```
to the policy's
```
_id
```
. It must be a policy from the same environment (otherwise 422
```
invalid_ref
```
).
API token or sign-in -- in the integrator.io UI: give the user the policy's name and where to pick it.

Then read the policy's assignments to confirm.

MCP server——将 server 的
```
_networkPolicyId
```
设置为策略的
```
_id
```
。它必须是来自同一环境的策略（否则返回 422
```
invalid_ref
```
）。
API token 或登录——在 integrator.io UI 中：向用户提供策略名称及其选择位置。

随后读取策略的分配情况以进行确认。

5. Edit a policy

5. 编辑策略

An edit applies at once to everything the policy is assigned to.

Patch the fields you're changing --
```
name
```
,
```
description
```
,
```
ipAllowList
```
,
```
ipDenyList
```
. A list you send replaces that whole list; the other fields keep their values.
A full replace clears whatever it omits, with no error: a list left out comes back empty -- lifting every restriction it imposed -- and a description left out is removed. If you replace, read the policy first and send
```
name
```
,
```
description
```
and both lists.
To drop one entry, send the whole list without it; removing a single entry by index is refused (422).

编辑会立即应用到策略分配到的所有对象。

Patch 要更改的字段——
```
name
```
、
```
description
```
、
```
ipAllowList
```
、
```
ipDenyList
```
。提交的列表会整体替换对应列表；其他字段保持原值。
完整替换会清除所有未提交的内容，且不会报错：未提交的列表会返回为空——解除该策略施加的所有限制——未提交的 description 也会被移除。如果执行完整替换，请先读取策略，然后提交
```
name
```
、
```
description
```
和两个列表。
要删除一个条目，提交不含该条目的完整列表；按索引删除单个条目会被拒绝（422）。

6. Unassign or delete

6. 取消分配或删除

Unassign from an MCP server by removing its
```
_networkPolicyId
```
(a patch
```
remove
```
, or
```
null
```
on a full update). A full update that leaves
```
_networkPolicyId
```
out keeps it.
Delete an unassigned policy and it's gone from reads (404); its name is free to reuse. An assigned policy is refused with 409
```
network_policy_in_use
```
, listing every assignment, and nothing changes. Forcing the delete clears the policy from every MCP server, token and sign-in setting first, so each of them loses the restriction -- read the assignments before you force, and keep that list: the clear leaves no entry in an MCP server's own change history.
Keep the lists before deleting. A deleted policy is meant to wait 30 days in the recycle bin, but the bin can't find deleted policies today (see Gotchas), so treat a delete as final and recreate the policy from the copy if needed. Its change history stays in the account audit log under resource type
```
networkpolicy
```
, though the policy's own audit route answers 404 once it's deleted.

从 MCP server 取消分配的方法是移除其
```
_networkPolicyId
```
（使用 patch
```
remove
```
，或在完整更新中设为
```
null
```
）。完整更新若省略
```
_networkPolicyId
```
，则会保留该值。
删除未分配的策略后，它会从读取结果中消失（404）；其名称可以立即复用。删除已分配的策略会返回 409
```
network_policy_in_use
```
，并列出每项分配，且不会更改任何内容。强制删除会先从每个 MCP server、token 和登录设置中清除该策略，因此每项都会失去相应限制——强制删除前请读取分配项并保留该列表：从 MCP server 自身的变更历史中不会留下清除操作的记录。
删除前请保留列表。 按设计，已删除策略应在回收站中保留 30 天，但目前回收站无法找到已删除的策略（参见“常见问题”），因此应将删除视为最终操作，并在需要时根据副本重新创建策略。其变更历史仍保留在账户审计日志中，资源类型为
```
networkpolicy
```
，不过删除后，策略自身的审计路由会返回 404。

7. Check whether a policy explains a refused caller

7. 检查策略是否可以解释被拒绝的调用方

Work out which policies apply to the call -- the MCP server's

_networkPolicyId

, the token's policy (shown in the UI), the sign-in settings -- read their lists, and compare them with the address the caller connects from (for someone on a VPN, its egress). Remember that deny wins and that every applicable policy has to admit the caller. A caller refused while no assigned policy covers its address is refused for another reason: see the guarding resource's own skill.

确定适用于该调用的策略——MCP server 的

_networkPolicyId

、token 的策略（在 UI 中显示）以及登录设置——读取它们的列表，并与调用方连接所用的地址（对于使用 VPN 的人，则是其出口地址）进行比较。请记住，拒绝优先，且每个适用策略都必须允许该调用方。如果某个调用方被拒绝，但没有任何已分配策略覆盖其地址，则拒绝原因是其他问题：请查看受保护资源自身的 skill。