Skip to content

命令行 ​

安装 Python SDK 后就有 preworld-guard 命令,python -m preworld_guard 效果相同。TypeScript SDK 只有 connection-check,见 TypeScript SDK。

sh
preworld-guard [全局选项] <命令> [命令选项]

输出是打印到标准输出的 JSON。出错信息从不包含密钥的值。

全局选项 ​

全局选项要写在命令前面。

选项环境变量默认值
--endpointPREWORLD_GUARD_ENDPOINThttp://127.0.0.1:8765
--tokenPREWORLD_GUARD_TOKEN
--token-filePREWORLD_GUARD_TOKEN_FILE
--project-idPREWORLD_GUARD_PROJECT_ID
--agent-idPREWORLD_GUARD_AGENT_IDpython-agent
--cachePREWORLD_GUARD_CACHE.preworld-guard/policy.json

--token-file 指向存放令牌的文件,没给 --token 时使用。文件是符号链接或其他人可读时拒绝使用。connection-check 和 trial-check 不读它:给这两个命令的令牌要用 --token 或 PREWORLD_GUARD_TOKEN。

命令 ​

命令做什么需要令牌
connection-check检查一个接入包需要(执行器)
register注册一次执行器需要(执行器)
policy拉取并缓存当前策略需要(执行器)
heartbeat发一次心跳需要(执行器)
policy-validate编译一份策略文件不需要
policy-schema输出策略的 JSON Schema不需要
policy-replay在本地按策略回放动作不需要
mcp-proxy运行 MCP 代理需要(执行器)
mcp-origin、mcp-manifest查看和批准 MCP 上游及工具的摘要需要
mcp-auth连接、查看或解除某个用户对 MCP 上游的 OAuth 授权用户自己的访问令牌
sandbox在 srt 里运行命令,或检查主机不需要
siem-export把事件和审计导出为 NDJSON需要(viewer)
diagnose生成诊断包需要(执行器)
trial-init为某个框架生成接入的起步文件不需要
trial-check检查自部署环境是否就绪需要
onboard在自部署控制面上开通组织和项目初始化密钥

connection-check ​

sh
preworld-guard connection-check --config guard-connection.json [--output report.json]

检查凭据、执行器是否在线、当前策略是否已加载、是否收到首条事件。不执行任何业务工具。四项都就绪时退出码为 0,否则非 0。

register ​

sh
preworld-guard --project-id "$PREWORLD_GUARD_PROJECT_ID" --token "$PREWORLD_GUARD_TOKEN" register --name support-agent

--name(默认 python-sdk)、--version(默认是 SDK 的版本)。长驻的 Agent 改用 guard.start()。

policy ​

拉取当前策略,校验后写入缓存,并打印策略。

heartbeat ​

为这个执行器发一次心跳。

policy-validate ​

sh
preworld-guard policy-validate policy.yaml

编译 YAML 或 JSON 格式的策略,打印编译结果和 policy_hash。有任何格式错误都会失败。

policy-schema ​

sh
preworld-guard policy-schema [--output guard-policy.schema.json]

policy-replay ​

sh
preworld-guard policy-replay --policy candidate-policy.json --records actions.json --output replay-report.json

按一份策略回放 1 到 1,000 条完整的动作(文件不超过 2 MiB)。不执行工具,不发送任何东西,报告里只有判定结果。见发布策略。

mcp-proxy ​

sh
preworld-guard [全局选项] mcp-proxy --upstream <命令...>
preworld-guard [全局选项] mcp-proxy --upstream-transport streamable-http --upstream-url <url> [--header KEY=VALUE]
preworld-guard [全局选项] mcp-proxy --config registry.json [--downstream-transport streamable-http ...]
选项默认值含义
--upstream ...stdio 服务的启动命令,必须放在最后
--upstream-transportstdiostdio、streamable-http 或 sse
--upstream-urlHTTP 和 SSE 用
--header KEY=VALUE发给上游的请求头(可重复)
--timeout、--sse-read-timeout10、300 秒上游超时
--config多上游注册表,不能和单上游的选项一起用
--downstream-transportstdiostdio 或 streamable-http(只限注册表)
--listen-host、--listen-port127.0.0.1、8766HTTP 下游用
--downstream-tokenPREWORLD_GUARD_DOWNSTREAM_TOKEN客户端访问 HTTP 下游时必须带的 bearer 令牌
--allowed-host、--allowed-originPREWORLD_GUARD_ALLOWED_HOSTS、PREWORLD_GUARD_ALLOWED_ORIGINSHTTP 下游接受的 Host 和 Origin(可重复)
--subject-idPREWORLD_GUARD_SUBJECT_ID可信的服务主体,审批需要
--sandbox 和 --sandbox-*在 srt 里运行 stdio 上游,见沙箱

见 MCP 代理。

mcp-origin ​

sh
preworld-guard mcp-origin --config ./mcp.json --server NAME [--approve SHA256]

显示上游的身份摘要。加 --approve 时批准它。

mcp-manifest ​

sh
preworld-guard mcp-manifest --config ./mcp.json --server NAME --kind tool --name TOOL [--approve SHA256]

--kind 取 tool、resource 或 resource_template。显示当前元数据的摘要。加 --approve 时批准它。

mcp-auth ​

sh
preworld-guard mcp-auth connect --upstream finance \
  --endpoint https://guard-proxy.example.com --token-file /private/employee-access-token

子命令是 connect、status 或 disconnect。--endpoint 是你们 MCP 代理的 HTTP 下游地址,不是控制面。令牌文件里放的是用户自己从身份提供方拿到的访问令牌,不是执行器凭据。--no-browser 不打开浏览器,改为打印一个一次性链接。connect 授权成功时退出码为 0。见 MCP 代理。

sandbox ​

sh
preworld-guard sandbox verify --executable tooling/node_modules/.bin/srt
preworld-guard sandbox run --workspace ./workspace --deny-read ~/.ssh -- python agent.py

verify 只有所有探针都通过才以 0 退出。run 原样返回命令的退出码。选项见沙箱。

siem-export ​

sh
PREWORLD_GUARD_TOKEN="$GUARD_VIEWER_TOKEN" preworld-guard \
  --endpoint https://guard.example.com --project-id "$PREWORLD_GUARD_PROJECT_ID" \
  siem-export --output /var/lib/preworld-guard-siem/events.ndjson \
  --state /var/lib/preworld-guard-siem/cursor.json

--limit(默认 500)、--max-pages(默认 20)。见事件、审计与导出。

diagnose ​

sh
preworld-guard [全局选项] diagnose --framework langchain --output guard-diagnostics.json [--send-ping]

检查解释器、框架依赖、策略来源、生命周期和事件队列,写出一个只有你自己可读的诊断包。包里只有白名单内的字段,从不读取参数值或环境变量的值。--send-ping 还会发一条诊断事件。一切正常时退出码为 0,否则为 2。

trial-init ​

sh
preworld-guard trial-init --framework openai-agents --directory ./guard-trial

为 python、langchain、langgraph、claude、openai-agents、pydantic-ai、google-adk、agent-framework、llama-index、agno、dspy 或 crewai 生成起步文件。不会覆盖已有文件,模板里的令牌都是占位符。

trial-check ​

sh
preworld-guard [全局选项] trial-check [--mcp-config ./mcp.json] [--sandbox-executable srt] [--output report.json]

检查到控制面的 HTTPS、凭据、策略版本和 MCP 上游摘要。加 --sandbox-executable 时还运行沙箱探针。提供 viewer 令牌(--viewer-token)和预期出口清单(--expected-exits)时,还报告执行器、资产和策略的覆盖情况。就绪时退出码为 0。它代替不了在目标网络里做一次本应失败的测试。

onboard ​

sh
preworld-guard --endpoint https://guard.example.com \
  onboard \
  --bootstrap-token "$PREWORLD_GUARD_BOOTSTRAP_TOKEN" \
  --organization 'Example' \
  --project 'support-agent'

只用于自部署。每调用一次就新建一个组织和项目,owner 令牌只返回这一次。见自部署控制面。