跳到主内容
快讯直播
AI智模界
教程

让编码智能体不碰明文密钥:短期令牌注入与出网审计

适用场景

当你把编码智能体(自动修 Bug、跑测试、开 PR 的那类工具)跑在容器或沙箱里,需要让它访问 Git 仓库、包管理器和 CI,但不想把长期 Personal Access AI 词典:Token">Token 明文塞进环境变量或 ~/.git-credentials 时,这套方案适用。核心思路是三件事:令牌由凭证代理按需签发、有效期以分钟计;权限按仓库和操作类型收窄到刚好够用;所有出网流量走白名单代理并留审计日志。这样即使智能体被提示注入或代码里藏了外传逻辑,能拿到的也只是一份很快过期、只能碰指定仓库的凭证。

环境与前置条件

  • 一台可运行容器的 Linux 主机或编排平台(Kubernetes 或普通 Docker 均可)。若在 Kubernetes 上,可使用投影 ServiceAccount 令牌做工作负载身份;若不在,可替换为 mTLS 客户端证书或云厂商工作负载身份,校验思路一致。
  • 凭证代理运行环境:Python 3.10 以上(以官方文档当前版本为准),依赖 fastapi、uvicorn、httpx、pyjwt[crypto]、pyyaml。
  • 一个 GitHub App(组织级),用于签发安装令牌。私钥文件放在代理所在主机,权限 600,绝不进入智能体容器。
  • 一台出网正向代理(Squid 或 Envoy 均可),智能体容器只能访问它,不能直连公网。
  • 资源建议:凭证代理 1 核 512MB 内存足够;代理与日志采集各 1 核 1GB;智能体容器按任务规模给,磁盘留 10GB 以上用于克隆仓库和装依赖。不需要 GPU。

分步骤部署

第一步:创建 GitHub App 并做仓库级授权

在组织设置里新建 GitHub App,把仓库选择设为「Only select repositories」,只勾选允许智能体改动的仓库。权限按最小集配置:Contents 读写、Pull requests 读写、Metadata 只读,其余全部设为 No access。生成私钥后下载到代理主机:

```bash

install -m 600 /path/to/downloaded.pem /etc/token-broker/app.pem

```

把 App ID 和 Installation ID 记录下来,后续通过环境变量注入代理。注意安装令牌的有效期由 GitHub 决定(通常一小时),不需要也不能自行延长;App 的 JWT 有效期上限是 10 分钟,这是官方固定规则。

第二步:编写凭证代理的策略文件

策略文件描述「哪个工作负载可以拿哪个仓库的什么权限」:

```yaml

/etc/token-broker/policy.yaml

coding-agent-bugfix:

repositories:

  • example-org/example-service

permissions:

contents: write

pull_requests: write

metadata: read

ttl_seconds: 900

max_requests_per_hour: 20

```

repositories 的取值必须落在 App 已授权的仓库范围内,permissions 必须是 App 已授予权限的子集,否则 GitHub 会直接拒绝。这一层是二次收窄:App 层面放宽到多个仓库,代理层面再按任务收到单个仓库。

第三步:部署凭证代理服务

代理只做四件事:校验调用方身份、查策略、向 GitHub 换令牌、写审计日志。

```python

/opt/token-broker/app.py

import json, os, time, logging

import httpx, jwt

from fastapi import FastAPI, Header, HTTPException, Request

APP_ID = os.environ["GH_APP_ID"]

INSTALLATION_ID = os.environ["GH_INSTALLATION_ID"]

PRIVATE_KEY = open(os.environ["GH_APP_PRIVATE_KEY_PATH"]).read()

K8S_API = os.environ.get("K8S_API", "https://kubernetes.default.svc")

K8S_TOKEN = open("/var/run/secrets/kubernetes.io/serviceaccount/token").read()

K8S_CA = "/var/run/secrets/kubernetes.io/serviceaccount/ca.crt"

app = FastAPI()

logging.basicConfig(level=logging.INFO)

log = logging.getLogger("token-broker")

def audit(event: dict) -> None:

event["ts"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())

print(json.dumps(event, ensure_ascii=False), flush=True)

async def verify_workload(token: str) -> str:

"""用 Kubernetes TokenReview 校验调用方身份,返回 ServiceAccount 名。"""

async with httpx.AsyncClient(verify=K8S_CA, timeout=5) as c:

r = await c.post(

f"{K8S_API}/apis/authentication.k8s.io/v1/tokenreviews",

headers={"Authorization": f"Bearer {K8S_TOKEN}"},

json={

"apiVersion": "authentication.k8s.io/v1",

"kind": "TokenReview",

"spec": {"token": token, "audiences": ["token-broker"]},

},

)

body = r.json()

if not body.get("status", {}).get("authenticated"):

raise HTTPException(status_code=401, detail="workload identity rejected")

return body["status"]["user"]["username"].split(":")[-1]

def app_jwt() -> str:

now = int(time.time())

iat 回拨 60 秒容忍时钟漂移,总时长不超过 10 分钟

return jwt.encode({"iat": now - 60, "exp": now + 480, "iss": APP_ID},

PRIVATE_KEY, algorithm="RS256")

async def mint(repos: list[str], perms: dict) -> dict:

async with httpx.AsyncClient(timeout=10) as c:

r = await c.post(

f"https://api.github.com/app/installations/{INSTALLATION_ID}/access_tokens",

headers={

"Authorization": f"Bearer {app_jwt()}",

"Accept": "application/vnd.github+json",

"X-GitHub-Api-Version": "2022-11-28",

},

json={"repositories": repos, "permissions": perms},

)

r.raise_for_status()

return r.json()

@app.post("/v1/token")

async def issue(request: Request, authorization: str = Header(...)):

workload_token = authorization.removeprefix("Bearer ").strip()

workload = await verify_workload(workload_token)

import yaml

policy = yaml.safe_load(open(os.environ["POLICY_PATH"]))

spec = policy.get(workload)

if not spec:

audit({"event": "deny", "workload": workload, "reason": "no_policy"})

raise HTTPException(status_code=403, detail="no policy for workload")

data = await request.json()

repo = data.get("repo")

if repo not in spec["repositories"]:

audit({"event": "deny", "workload": workload, "repo": repo,

"reason": "repo_not_allowed"})

raise HTTPException(status_code=403, detail="repo not allowed")

result = await mint([repo.split("/")[1]], spec["permissions"])

token = result["token"]

audit({

"event": "issue",

"workload": workload,

"repo": repo,

"permissions": spec["permissions"],

"expires_at": result.get("expires_at"),

"token_fp": __import__("hashlib").sha256(token.encode()).hexdigest()[:12],

})

return {"token": token, "expires_at": result.get("expires_at")}

```

启动命令:

```bash

cd /opt/token-broker && \

GH_APP_ID=... GH_INSTALLATION_ID=... \

GH_APP_PRIVATE_KEY_PATH=/etc/token-broker/app.pem \

POLICY_PATH=/etc/token-broker/policy.yaml \

uvicorn app:app --host 0.0.0.0 --port 8080

```

看到 Uvicorn running on http://0.0.0.0:8080 即启动成功。日志里绝不打印令牌明文,只记录 SHA256 前 12 位指纹,用于事后比对。

第四步:配置出网白名单代理

智能体容器不直连公网,默认路由指向代理;代理只放行必要域名:

```conf

squid.conf 片段

acl allowed_domains dstdomain .github.com .githubusercontent.com .pypi.org .npmjs.org

acl metadata_ip dst 169.254.169.254

http_access deny metadata_ip

http_access allow allowed_domains

http_access deny all

access_log /var/log/squid/access.log

```

dstdomain 前加点表示匹配该域名及其子域。metadata_ip 那条很关键:云主机元数据接口常被用来偷长期凭证,必须封死。修改后执行 squid -k reconfigure 生效。

第五步:在智能体容器内注入令牌

容器启动脚本先换取令牌,只在进程环境里保存,不写文件:

```bash

#!/usr/bin/env bash

/usr/local/bin/get-token.sh

set -euo pipefail

: "${BROKER_URL:?BROKER_URL 未设置}"

WORKLOAD_TOKEN=$(cat /var/run/secrets/token-broker/token)

curl -sS -f -X POST "${BROKER_URL}/v1/token" \

-H "Authorization: Bearer ${WORKLOAD_TOKEN}" \

-H "Content-Type: application/json" \

-d "{\"repo\":\"${TARGET_REPO}\"}" | jq -r .token

```

再配一个不落盘的 git 凭证助手:

```bash

#!/usr/bin/env bash

/usr/local/bin/git-credential-env

case "${1:-}" in

get)

echo "username=x-access-token"

echo "password=${GH_TOKEN}"

;;

esac

```

入口脚本里串起来:

```bash

export GH_TOKEN="$(/usr/local/bin/get-token.sh)"

git config --global credential.helper /usr/local/bin/git-credential-env

git config --global credential.useHttpPath true

```

x-access-token 是 GitHub App 安装令牌约定的用户名,配合令牌作为密码使用。

第六步:跑一次修 Bug 并提 PR 的任务

```bash

git clone "https://github.com/${TARGET_REPO}.git" /workspace/repo

cd /workspace/repo

git checkout -b "fix/agent-$(date +%s)"

此处交给智能体修改代码

git -c user.name="coding-agent" -c user.email="agent@example.invalid" \

commit -am "fix: 修正边界条件下的空指针"

git push -u origin HEAD

```

PR 通过 API 创建,同样复用环境里的短期令牌,不需要另配凭证:

```bash

curl -sS -f -X POST \

-H "Authorization: Bearer ${GH_TOKEN}" \

-H "Accept: application/vnd.github+json" \

"https://api.github.com/repos/${TARGET_REPO}/pulls" \

-d "{\"title\":\"fix: 修正边界条件下的空指针\",\"head\":\"$(git branch --show-current)\",\"base\":\"main\"}"

```

任务结束后销毁容器,令牌随环境一起消失,无需回收动作。

验证部署是否成功

1. 白名单外域名应被拒绝:

```bash

curl -sS -o /dev/null -w "%{http_code}\n" --proxy http://egress-proxy:3128 https://pypi.org

curl -sS -o /dev/null -w "%{http_code}\n" --proxy http://egress-proxy:3128 https://example.com

```

预期第一条返回 200,第二条返回 403 或连接被拒。

2. 元数据接口应不可达:

```bash

curl -sS -m 5 http://169.254.169.254/ ; echo "exit=$?"

```

预期超时或连接拒绝,不会返回任何实例信息。

3. 容器内不应存在明文凭证文件:

```bash

ls -la ~/.git-credentials 2>&1

env | grep -i -E 'token|secret' | sed 's/=.*/=<redacted>/'

```

预期第一条报文件不存在;第二条只看到短期的 GH_TOKEN 和代理地址,没有长期密钥。

4. 代理侧审计日志应出现签发记录:

```bash

docker logs token-broker 2>&1 | grep '"event": "issue"' | tail -n 3

```

预期能看到 workload、repo、expires_at 和 token_fp 字段,且没有完整令牌字符串。

5. 令牌确实会过期:

```bash

sleep 1000 && git push # 超过策略里的 ttl_seconds 后重试

```

预期返回 401,说明短时效生效,而不是永久有效。

6. PR 创建结果:curl 返回体中 html_url 字段有值,浏览器打开能看到由智能体分支发起的 PR,且改动范围只落在目标仓库。

常见报错与解决

报错:remote: Permission to example-org/example-service.git denied to x-access-token

→ 原因:GitHub App 未安装到该仓库,或代理申请时请求的权限超出 App 已授予范围。

→ 解决:检查 App 的仓库选择列表,确认目标仓库已勾选;再核对策略文件里的 permissions 是否为 App 权限的子集。可用以下命令确认安装范围:

```bash

curl -sS -H "Authorization: Bearer ${GH_TOKEN}" \

https://api.github.com/repos/example-org/example-service | jq '.permissions'

```

报错:fatal: could not read Username for 'https://github.com': No such device or address

→ 原因:credential helper 未生效,或 GH_TOKEN 在该 shell 里为空(常见于 export 写在子 shell 中)。

→ 解决:确认 helper 已注册并在当前 shell 可见:

```bash

git config --global --get credential.helper

echo "${GH_TOKEN:+token-present}"

```

若第二行没有输出,说明令牌没注入到当前进程,改由入口脚本统一 export 后再启动子进程。

报错:403 Forbidden 或 Proxy CONNECT aborted(访问包管理器时)

→ 原因:目标域名不在 Squid 白名单,或被 http_access deny all 兜底拦截。

→ 解决:把域名加入 allowed_domains 后重新加载:

```bash

squid -k reconfigure && tail -n 20 /var/log/squid/access.log

```

报错:凭证代理返回 401 workload identity rejected

→ 原因:投影令牌的 audience 与 TokenReview 请求中的 audiences 不一致,或令牌已超过 expirationSeconds。

→ 解决:核对 Pod 卷配置里的 audience: token-broker,并确认 expirationSeconds 大于任务时长;重启 Pod 让令牌重新投影。

报错:A JSON web token could not be decoded 或 'iss' claim is invalid

→ 原因:App JWT 的 iss 不是 App ID 字符串,或 exp 超过 10 分钟上限,或主机时钟偏移过大。

→ 解决:确认 iss 使用 App ID 而非 Client ID;把 JWT 有效期压到 9 分钟以内并保留 60 秒回拨;对宿主机开启时间同步。

报错:Resource not accessible by integration

→ 原因:App 权限不足,或安装令牌被收窄到不含该操作的权限集。

→ 解决:在 App 设置里补上对应权限并重新安装,同时更新策略文件中的 permissions。

后续维护

凭证轮换:GitHub App 私钥建议按季度轮换。做法是先在 App 页面生成新私钥,把新文件放到代理主机并更新 GH_APP_PRIVATE_KEY_PATH 指向,重启代理验证签发正常后,再删除旧私钥。整个过程不需要改动智能体侧任何代码。

策略演进:随着智能体任务类型增加,策略文件会变长。建议把「仓库 → 允许的权限 → 每小时请求上限」做成评审项,新增条目走代码评审而非线上手改,避免权限悄悄放大。

日志留存与关联:凭证代理日志记录「谁在什么时候拿了哪个仓库的令牌」,出网代理日志记录「这个工作负载访问了哪些域名」。两边都带 workload 标识,按时间窗口关联即可还原一次任务的完整行为。留存周期按合规要求设定,日志本身不含令牌明文,可以放心长期保存。

监控告警:对三类信号设阈值告警——单工作负载每小时令牌申请次数突增、出现 deny 事件(说明有越权尝试或策略漏配)、出网代理出现大量非白名单拒绝。前两类通常意味着智能体被注入或任务配置错误,值得立即人工介入。

升级:代理依赖的框架与 GitHub API 版本会更新,升级前先看官方文档的变更说明,尤其是 API 版本头(示例中的 X-GitHub-Api-Version)与权限名称的变化;具体版本号以官方文档当前版本为准。升级顺序建议先在预发环境跑一遍完整的「修 Bug → 提 PR」流程,再切生产。

AI 生成本文由 AI 基于公开信息自动生成,仅供参考。