Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 39 additions & 3 deletions .github/workflows/gate.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,15 @@ on:
push:
branches: [main]

permissions: {contents: read}
permissions: {}

jobs:
gate:
runs-on: ubuntu-latest
timeout-minutes: 10 # testing.yaml T-01 "gate<5min" 原则的硬上限(红队 #18 P2:无 timeout 的 job 失控可挂 6h)
permissions:
contents: read # job 级最小权限(评审项:防后续新增 job 继承 workflow 级权限)
pull-requests: read # 仅 adr-required 步骤读取 PR 文件清单
steps:
- uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
with:
Expand All @@ -26,10 +30,12 @@ jobs:
for f in files:
yaml.safe_load(open(f, encoding="utf-8")); print("OK", f)
EOF
- name: ruleset JSON 解析
# JSON 全量校验(红队 #17-B):expected-state.json 与 rulesets 同为 drift-check/apply 的
# 期望状态真源——此前 gate 只验 rulesets/*.json,expected-state.json 畸形可静默合入
- name: JSON 校验(rulesets + expected-state)
run: |
sudo apt-get -qq update && sudo apt-get -qq install -y jq >/dev/null
for f in governance/rulesets/*.json; do jq -e . "$f" >/dev/null || exit 1; echo "OK $f"; done
for f in governance/rulesets/*.json governance/expected-state.json; do jq -e . "$f" >/dev/null || exit 1; echo "OK $f"; done
- name: 脚本语法检查
run: |
bash -n governance/apply.sh && bash -n governance/drift-check.sh && bash -n scripts/new-repo-init.sh && bash -n scripts/gh-app-token.sh
Expand All @@ -43,3 +49,33 @@ jobs:
assert len(names) == len(set(names)), 'REPOS.yaml 有重名仓'
print('OK REPOS.yaml', len(names), 'repos')
EOF
# adr-required(红队 #17-B/D、#18-P0 部分;对齐 agent-registry ADR-0013 同名 check):
# C1 路径(governance/ standards/ scripts/ .github/ CODEOWNERS)变更的 PR,
# title/body 必须引用 ADR-NNNN——GOVERNANCE flows.governance_change "无 ADR 不合并"
# 的机器执行。本仓不落盘 ADR(L1 决策记录在 agent-registry/decisions/,
# 见 REPOS.yaml role)。被引 ADR 的**存在性**校验不在本步骤做:agent-registry 是
# 私有仓,PR 上下文的 GITHUB_TOKEN 无跨仓读权,而把 org secret(如
# GOVERNANCE_TOKEN)注入 PR 触发的 workflow = 向 PR 控制的代码暴露凭据
# (zizmor secret-exposure 模型)——存在性由 drift-check.sh §10 后验(每日,
# 可信 main 上下文),owner-only review 仍是 C1 的权威人类门禁。
- name: adr-required(C1 变更须引用 ADR)
if: github.event_name == 'pull_request'
env:
GH_TOKEN: ${{ github.token }}
PR_TITLE: ${{ github.event.pull_request.title }}
PR_BODY: ${{ github.event.pull_request.body }}
run: |
# --paginate(评审项):>100 文件的 PR 首页截断会把 C1 变更漏检成非 C1
FILES=$(gh api --paginate "repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/files?per_page=100" --jq '.[].filename')
if ! echo "$FILES" | grep -qE '^(governance/|standards/|scripts/|\.github/|CODEOWNERS|profile/)'; then
echo "非 C1 路径变更,跳过 adr-required"
exit 0
fi
# 词边界(评审项):NOTADR-0013junk 之类子串不得满足 ADR 引用要求
ADR_RE='\bADR-[0-9]{4}\b'
if { echo "$PR_TITLE"; echo "$PR_BODY"; } | grep -qE "$ADR_RE"; then
echo "OK adr-required: $( { echo "$PR_TITLE"; echo "$PR_BODY"; } | grep -oE "$ADR_RE" | sort -u | tr '\n' ' ')(存在性后验:drift-check §10)"
else
echo "::error::C1 路径变更(governance/standards/scripts/.github/CODEOWNERS)但 PR 未引用任何 ADR-NNNN(GOVERNANCE flows.governance_change C1:无 ADR 不合并)"
exit 1
fi
32 changes: 28 additions & 4 deletions .github/workflows/governance-drift.yml
Original file line number Diff line number Diff line change
@@ -1,14 +1,15 @@
name: governance-drift
on:
schedule:
- cron: "0 3 * * 1" # 每周一 03:00 UTC
- cron: "0 3 * * *" # 每日 03:00 UTC(红队 #18 P0-1:周检盲区最长 7 天 → 每日;轻量只读检测,成本可忽略)
workflow_dispatch:

permissions: {}

jobs:
drift-check:
runs-on: ubuntu-latest
timeout-minutes: 15
permissions:
contents: read
issues: write
Expand All @@ -32,7 +33,11 @@ jobs:
REPO: ${{ github.repository }}
run: |
TITLE="治理漂移检测:组织配置与 governance/ 落盘不一致"
EXISTING=$(gh issue list --repo "$REPO" --state open --search "in:title 治理漂移" --json number --jq 'length')
# 归属标记(评审项):issue 归属判定用专属 label 而非标题搜索——
# 标题搜索会把人工/其他来源的同名 issue 误当作本检测器的报告去评论/关闭
LABEL="auto-drift-report"
gh label create "$LABEL" --repo "$REPO" --description "governance-drift 工作流自动报告(勿手工使用)" --color d73a4a >/dev/null 2>&1 || true
EXISTING=$(gh issue list --repo "$REPO" --state open --label "$LABEL" --json number --jq 'length')
BODY="自动化检测发现以下漂移(运行 #${{ github.run_id }}):

$(cat drift-report.txt)
Expand All @@ -41,8 +46,27 @@ jobs:

@randypanding"
if [[ "$EXISTING" != "0" ]]; then
NUM=$(gh issue list --repo "$REPO" --state open --search "in:title 治理漂移" --json number --jq '.[0].number')
NUM=$(gh issue list --repo "$REPO" --state open --label "$LABEL" --json number --jq '.[0].number')
gh issue comment "$NUM" --repo "$REPO" --body "$BODY"
else
gh issue create --repo "$REPO" --title "$TITLE" --body "$BODY"
gh issue create --repo "$REPO" --title "$TITLE" --body "$BODY" --label "$LABEL"
fi
# 漂移消除自动关闭(红队 #17-G:漂移修复后 open issue 永不关闭=噪音累积,
# 真漂移会被淹没在陈旧报告里)。检测全绿即判定漂移已消除。
# 只关本检测器自己的报告(--label auto-drift-report,评审项)——
# 人工开的其他漂移类 issue 不在自动关闭范围,须人工确认后关闭。
- name: 漂移消除则关闭 issue
if: success() && github.event_name != 'pull_request'
env:
GH_TOKEN: ${{ github.token }}
REPO: ${{ github.repository }}
run: |
NUMS=$(gh issue list --repo "$REPO" --state open --label "auto-drift-report" --json number --jq '.[].number')
if [[ -z "$NUMS" ]]; then
echo "无本检测器的 open 漂移 issue"; exit 0
fi
for NUM in $NUMS; do
gh issue comment "$NUM" --repo "$REPO" --body "漂移已消除(运行 #${{ github.run_id }} 全绿)。自动关闭;如复现将重新开启新报告。"
gh issue close "$NUM" --repo "$REPO" --reason completed
echo "closed #$NUM"
done
Binary file not shown.
29 changes: 29 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# AGENTS.md

AI agent 进入本仓的工作契约(索引型,CG-1;细节按需读引用文件,不常驻上下文)。

## 硬规则

- 治理文件(governance/ standards/ scripts/ .github/ CODEOWNERS profile/)= C1 路径:PR 必须引用 ADR-NNNN,owner-only review(GOVERNANCE flows.governance_change;与 gate adr-required 机器检查同路径集)
- agent 写仓库身份 = GitHub App `cloudbrid-agent`(AG-1);令牌经 scripts/gh-app-token.sh,单仓作用域、1h 过期
- 本仓只读治理声明;ADR 与注册条目落盘 agent-registry(REPOS.yaml L1)
- 不引入新第三方 Action:白名单见 expected-state.json#actions_policy(CI-2)

## 常用命令

- 校验本仓声明:`.github/workflows/gate.yml`(本地等价:yaml/json 解析 + `bash -n` 各脚本)
- 漂移检测:`GH_TOKEN=<org admin> bash governance/drift-check.sh`(每日 CI 自动跑)
- 漂移修复:`GH_TOKEN=<org admin> bash governance/apply.sh`(幂等;失败 loud 退出)
- 新仓初始化:`bash scripts/new-repo-init.sh <name>`(失败 loud 退出)

## 索引

| 主题 | 文件 |
|---|---|
| 治理总声明(域/措施/流程) | governance/GOVERNANCE.yaml |
| 组织仓库地图 | governance/REPOS.yaml |
| 期望状态(漂移真源) | governance/expected-state.json |
| 语言/依赖政策 | governance/policy/languages.yaml |
| 测试政策 | governance/policy/testing.yaml |
| agent 标准 schema | standards/agent/*.schema.yaml |
| 原型 profiles / 注册条目 | Cloudbird-Software/agent-registry |
28 changes: 25 additions & 3 deletions SECURITY.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,27 @@
# 安全问题反馈
# 安全策略

请通过仓库 Security → Report a vulnerability 提交(Private vulnerability reporting 已开启)。
## 报告漏洞

不要在 Issue 里公开披露。
请通过仓库 **Security → Report a vulnerability** 提交(Private vulnerability reporting 已开启)。不要在 Issue/PR/讨论中公开披露。

## 响应时限(红队修复:此前无 SLA)

| 级别 | 定义 | 首次响应 | 处置目标 |
|---|---|---|---|
| P0 | 治理防线可被绕过 / 凭据泄露 / 供应链投毒路径 | 24h | 7 天内修复或缓解 |
| P1 | 单仓防线削弱 / 漂移长期未消 | 72h | 14 天 |
| P2 | 加固建议 | 7 天 | 排期 |

- 接收人:owner(randypanding);owner 缺席超时限由 stewardship curator(team:stewardship)在周报升级。
- 处置记录:P0/P1 修复须附 ADR(flows.governance_change C1)。

## 报告范围

- 本仓治理文件与脚本(governance/ scripts/ .github/)
- 组织 ruleset / App `cloudbrid-agent` / secret 配置异常
- CI-Workflows 可复用工作流与 agent-registry 声明中的安全问题(转对应仓处置,本仓追踪)

## 披露

- 修复发布后,报告者可选择公开致谢;细节披露在修复落地后进行。
- 未修复前不披露利用细节。
1 change: 0 additions & 1 deletion agent-registry
Submodule agent-registry deleted from 5ce5ac
26 changes: 13 additions & 13 deletions governance/GOVERNANCE.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ domains:
intent: "默认分支仅经 PR+squash 进入;禁删/force-push;线性历史"
strength: enforced
platform: {github: {mechanism: org-ruleset, name: main-protection, definition: rulesets/main-protection.json}}
verify: {method: drift-check, frequency: weekly}
verify: {method: drift-check, frequency: daily}
exception: [AI_Web_School]
- id: BP-2
intent: "合并前置:唯一 required check = gate(聚合检查)"
Expand All @@ -33,12 +33,12 @@ domains:
intent: "发布标签 v* 不可删除/覆盖"
strength: enforced
platform: {github: {mechanism: org-ruleset, name: release-tags, definition: rulesets/release-tags.json}}
verify: {method: drift-check, frequency: weekly}
verify: {method: drift-check, frequency: daily}
- id: BP-4
intent: "仓库基线:squash-only、合并删分支、auto-merge 开、wiki/projects 关"
strength: enforced
platform: {github: {mechanism: repo-settings, apply: apply.sh#step5}}
verify: {method: drift-check, frequency: weekly}
verify: {method: drift-check, frequency: daily}
- id: BP-5
intent: "成员不可建仓;成员默认权限 read"
strength: enforced
Expand All @@ -54,7 +54,7 @@ domains:
intent: "Actions 仅允许:github 官方+已验证+白名单(zizmor/astral-sh/dependabot/docker/softprops/org 自有)"
strength: enforced
platform: {github: {mechanism: actions-permissions, state: expected-state.json#actions_policy}}
verify: {method: drift-check, frequency: weekly}
verify: {method: drift-check, frequency: daily}
- id: CI-3
intent: "GITHUB_TOKEN 默认只读;不允许 Actions 批准 PR"
strength: enforced
Expand Down Expand Up @@ -90,7 +90,7 @@ domains:
intent: "agent 写仓库唯一身份 = App(cloudbrid-agent);权限 contents/issues/PRs:write,无 workflows/administration"
strength: enforced
platform: {github: {mechanism: github-app, id: 4632704, state: expected-state.json#github_app}}
verify: {method: drift-check, frequency: weekly}
verify: {method: drift-check, frequency: daily}
- id: AG-2
intent: "App 令牌:单仓库作用域、1h 过期、磁盘不落长期凭据"
strength: enforced
Expand All @@ -114,14 +114,14 @@ domains:
governance_meta:
measures:
- id: GM-1
intent: "期望状态落盘;周漂移检测;漂移自动开 issue"
intent: "期望状态落盘;每日漂移检测(红队修复:周检盲区最长 7 天→1 天);漂移自动开 issue;漂移消除自动关闭 issue(防陈旧报告累积噪音)"
strength: monitored
platform: {github: {mechanism: workflow, file: .github/workflows/governance-drift.yml, cron: "Mon 03:00 UTC"}}
platform: {github: {mechanism: workflow, file: .github/workflows/governance-drift.yml, cron: "daily 03:00 UTC"}}
verify: {method: self, state: expected-state.json}
- id: GM-2
intent: "治理仓变更一律走 flows.governance_change 分级流程(C1 附 ADR / C2 过 validate / C3 走 PR);破玻璃=直推后 24h 内回填;owner 与 AI 同受约束"
strength: enforced
verify: {method: drift-check, part: section-8, frequency: weekly}
verify: {method: drift-check, part: section-8, frequency: daily}
- id: GM-3
intent: "政策文件机器可判定(本目录);agent 按需读取,不常驻上下文"
strength: advisory
Expand All @@ -130,7 +130,7 @@ domains:
intent: "组织地图 REPOS.yaml 声明全部仓(层级/角色/可见性/状态):结构层导航的唯一入口;线上未申报仓=漂移;active 仓存在性与 visibility 周检;新仓初始化后必须申报入图(见 flows.new_repo)"
strength: enforced
files: [REPOS.yaml]
verify: {method: drift-check, part: section-7, frequency: weekly}
verify: {method: drift-check, part: section-7, frequency: daily}

context_governance:
measures:
Expand Down Expand Up @@ -168,7 +168,7 @@ domains:
intent: "双层控制:软引导(AGENTS.md/identity/skill 正文)+ 硬边界(工具面裁剪→权限引擎→凭据→平台防线);冲突时硬控制优先;拦截记录进事件流"
strength: enforced
- id: AR-6
intent: "团队必须声明 lifecycle;ephemeral 团队 archive_to+handoff 全部完成才允许销毁;persistent 团队(governance-core)对治理资产持续负责"
intent: "团队必须声明 lifecycle;ephemeral 团队 archive_to+handoff 全部完成才允许销毁;persistent 团队(team:stewardship——ADR-0004 规划名 governance-core 的落地形态)对治理资产持续负责"
strength: enforced
platform: {github: {mechanism: script, entry: agent-registry/scripts/validate.py, check: lifecycle}}
- id: AR-7
Expand All @@ -190,9 +190,9 @@ flows:
# 授权凭证 = ADR + PR 记录;破玻璃保留但被监控
classes:
- id: C1
scope: [GOVERNANCE.yaml, rulesets/, expected-state.json, standards/, models.yaml, decisions/]
scope: ["governance/(整目录——含 GOVERNANCE/REPOS.yamlrulesetsexpected-state、apply/drift 脚本、policy)", standards/, models.yaml, decisions/, scripts/, ".github/(CI 门禁自身——改门禁=改治理)", CODEOWNERS, profile/, "tests/(agent-registry 验证器元测试——验证器之验证)", "template-service(整仓——供应链入口:模板被污染=全部新仓继承后门,红队修复 P0)"]
requires: [PR, "ADR(新建或引用编号)", "drift-check 本地预检", owner-merge]
rationale: "治理意图变更必须可追溯到一个决策记录;无 ADR 不合并"
rationale: "治理意图变更必须可追溯到一个决策记录;无 ADR 不合并。scope 与机器执法路径全集一致(.github gate:governance/standards/scripts/.github/CODEOWNERS/profile;agent-registry validate:standards/decisions/scripts/.github/CODEOWNERS/tests——评审项:声明与执行不得互斥);template-service 是新仓派生源头,视同治理意图变更(gate adr-required 机器检查 + owner-only review)"
- id: C2
scope: [agent-registry/registry/, 业务仓 AGENTS.md/CODEOWNERS]
requires: [PR, "validate.py 通过"]
Expand Down Expand Up @@ -223,7 +223,7 @@ flows:
- {step: 1, action: "从 agent-registry 声明实例化 team(引用 id@version)", gate: AR-1}
- {step: 2, action: "运行期事件按 event.schema 追加到数据层;拦截记录 tool_called.denied_by", policies: [AR-5, AR-7]}
- {step: 3, action: "ephemeral 完成→执行 handoff:artifacts 走 PR、经验提炼 skill、关键决策升 ADR、轨迹归档", policy: AR-6}
- {step: 4, action: "persistent 团队(governance-core)审核归档资产入库;handoff_done 审计", policy: AR-6}
- {step: 4, action: "persistent 团队(team:stewardship)审核归档资产入库;handoff_done 审计", policy: AR-6}

portability:
neutral: [intent, strength, verify, risk_posture, flows] # 平台无关,直接搬运
Expand Down
Loading