skill-declaration-core
技能安全声明引擎:提供 Security Manifest 模板与字段说明(3.1)、对 Skill 目录做 PREVALIDATION 预校验与 FORMAL_TEST 正式测试(3.2)、冻结工作树并核对跨报告 subject_digest。用于查询安全声明字段、填写 references/security-manifest.yaml、预检声明与实际是否一致;Triggers: 安全声明, security manifest, 预校验, subject_digest, 冻结校验。
- License 许可
- Apache-2.0
- 所属仓库
- bonc-ai/cogseed
- 最近更新
- 2026-11-13
- Stars
- ★ 19
- Forks
- 10
01 前言 Front Matter
- name
- skill-declaration-core
- license
- Apache-2.0
- description
- 技能安全声明引擎:提供 Security Manifest 模板与字段说明(3.1)、对 Skill 目录做 PREVALIDATION 预校验与 FORMAL_TEST 正式测试(3.2)、冻结工作树并核对跨报告 subject_digest。用于查询安全声明字段、填写 references/security-manifest.yaml、预检声明与实际是否一致;Triggers: 安全声明, security manifest, 预校验, subject_digest, 冻结校验。
02 资源文件 45
- 其他.gitignore93 B
- 参考文档exit-code-registry.yaml1.5 KB
- 许可证LICENSE10.0 KB
- 参考文档ontologies/cogseed.security.skill/1.1.1/artifact-fields.yaml4.7 KB
- 参考文档ontologies/cogseed.security.skill/1.1.1/artifact-manifest.template.yaml826 B
- 参考文档ontologies/cogseed.security.skill/1.1.1/compatibility-manifest.template.yaml416 B
- 参考文档ontologies/cogseed.security.skill/1.1.1/consistency-rules.yaml3.3 KB
- 参考文档ontologies/cogseed.security.skill/1.1.1/derivation-rules.yaml3.3 KB
- 参考文档ontologies/cogseed.security.skill/1.1.1/digest-profile.yaml804 B
- 参考文档ontologies/cogseed.security.skill/1.1.1/manifest-fields.yaml13.4 KB
- 参考文档ontologies/cogseed.security.skill/1.1.1/manifest.schema.json7.7 KB
- 参考文档ontologies/cogseed.security.skill/1.1.1/ontology.yaml1.0 KB
- 参考文档ontologies/cogseed.security.skill/1.1.1/security-manifest.template.yaml2.2 KB
- 参考文档ontologies/cogseed.security.skill/1.1.1/trust-rules.yaml1.3 KB
- 参考文档ontologies/cogseed.security.skill/1.1.1/version-policy.yaml608 B
- 参考文档ontologies/cogseed.security.skill/1.1.1/warning-policy.yaml2.0 KB
- 其他pyproject.toml780 B
- 参考文档README.md1.3 KB
- 脚本scripts/orchestrator_cli.py7.3 KB
- 脚本scripts/template_cli.py3.5 KB
- 脚本scripts/validator_cli.py2.3 KB
- 脚本security_core/__init__.py1.2 KB
- 脚本security_core/coherence.py12.7 KB
- 脚本security_core/completeness.py6.4 KB
- 脚本security_core/deriving.py858 B
- 脚本security_core/digesting.py7.0 KB
- 脚本security_core/freezing.py9.9 KB
- 脚本security_core/guards.py3.7 KB
- 脚本security_core/models.py5.5 KB
- 脚本security_core/normalizing.py2.1 KB
- 脚本security_core/pipeline.py10.2 KB
- 脚本security_core/registry.py6.2 KB
- 脚本security_core/templates.py17.9 KB
- 脚本security_core/trusting.py4.2 KB
- 脚本security_core/warnrules.py2.4 KB
- 参考文档tests/conformance/1.1.1/completion-vectors.json3 B
- 参考文档tests/conformance/1.1.1/consistency-vectors.json3 B
- 参考文档tests/conformance/1.1.1/derivation-vectors.json1.2 KB
- 参考文档tests/conformance/1.1.1/digest-vectors.json272 B
- 参考文档tests/conformance/1.1.1/exit-code-vectors.json872 B
- 参考文档tests/conformance/1.1.1/freeze-readiness-vectors.json3 B
- 参考文档tests/conformance/1.1.1/orchestration-vectors.json3 B
- 参考文档tests/conformance/1.1.1/report-vectors.json3 B
- 参考文档tests/conformance/1.1.1/trust-vectors.json3 B
- 其他VERSION6 B
03 SKILL.md 正文
Skill Security Core
Skill Security Declaration 3.1 / 3.2 引擎(Engine 1.3.0,Ontology cogseed.security.skill@1.1.1)。
本文件是给模型看的用法说明,判决权不在这里——见下节。
平台约定(先读这一节)
- 本引擎是平台组件,不是可安装的 Skill。 它位于
resources/guardrail/,不经 marketplace 分发,完整性由同级的skill-declaration-core.INTEGRITY固定树哈希保护。 原因是可安装即可替换,而可替换的检查器等于由被检查者挑选检查者。 - 判决由平台侧决定。 引擎只返回 findings 与退出码;
pass/blocked的映射在src/main/features/security/skill-declaration-adapter.ts的verdictFromExitCode。 任何情况下都不要按引擎输出的文字自行下结论。 - 基础设施故障一律是
unknown,不是blocked。 解释器缺失、超时、崩溃、 报告无法解析都归为"没能检查",不是"内容危险"。 - 规则唯一来源是本引擎。 Ontology、
trust-rules.yaml、consistency-rules.yaml、warning-policy.yaml、digest-profile.yaml、exit-code-registry.yaml仅存在于此, 不要在别处按 YAML 重新实现规则。
何时使用
- 需要查询 Security Manifest 的字段含义、必填项、默认值或支持的 Ontology 版本。
- 需要为一个 Skill 编写 / 修补
references/security-manifest.yaml。 - 需要对 Skill 目录做声明与实际的一致性预检(PREVALIDATION)。
何时不要使用
- 判断一个 Skill 是否含恶意代码 —— 那是 skill-sentry 的职责,本引擎只看声明与结构。
- 计算风险等级 —— 风险派生已停用(见下"停用项")。
- 作为交付 / 部署授权 —— 阶段一的报告一致只证明"测的是同一份冻结内容"。
能力一:模板与字段(3.1)
只允许精确版本匹配,当前基线 1.1.1。先用 list-supported-versions 确认。
python3 scripts/template_cli.py --ontology-version 1.1.1 get-template
python3 scripts/template_cli.py --ontology-version 1.1.1 describe-field --field permissions.required
python3 scripts/template_cli.py --ontology-version 1.1.1 list-required-fields
python3 scripts/template_cli.py list-supported-versions
模板里未填字段写作 REQUIRED_INPUT,不是留空——空值容易被当作"无此需求"混过,
REQUIRED_INPUT 是一个明确的未完成状态。
能力二:校验(3.2)
| 模式 | 对象 | subject_digest | 说明 |
|---|---|---|---|
PREVALIDATION |
可变工作树 | 必须为 null |
记录 worktree_digest,标注 authority=NON_AUTHORITATIVE |
FORMAL_TEST |
仅 FROZEN 主体 | 必填且重算 | 测前/测后摘要必须一致,否则 SUBJECT_MUTATED |
python3 scripts/validator_cli.py --skill-root <path> --mode PREVALIDATION
权威性标签是有意义的:开发中算出的摘要恒为 NON_AUTHORITATIVE,只有冻结副本上
算出的 subject_digest 才是 AUTHORITATIVE。算法相同,区别只在标签——这防止
"开发阶段扫过一次"被当作"已验证"。
能力三:冻结与正式测试
python3 scripts/orchestrator_cli.py run-pipeline \
--skill-root <skill> --state-root <state> --ontology-version 1.1.1
冻结会复制一份只读副本、算出权威摘要、写入 provenance.checksum,并写入后重算
断言摘要未变(checksum 字段本身在被哈希的文件里,因此哈希时按固定哨兵处理)。
本平台现状:这条链暂无触发点。 CogSeed 的 Skill 是随时保存的,没有明确的 "发布"动作,因此"什么事件算冻结点"尚未确定。引擎能跑,但目前没有调用方。 不要声称某个 Skill 已通过正式测试。
停用项(不要调用)
- 风险五维派生已停用:不要调用
derive_security_fields,不要写入risk.calculated_risk_level/effective_risk_level/calculation_*/triggered_rule_ids。模板中这些字段保持null。 - 因此
consistency-rules.yaml里依赖风险等级的规则(SEC-ACTION-001不可逆操作需审批、SEC-RISK-001审批匹配风险、SEC-ROLLBACK-001)当前不生效。 规则骨架在,判定逻辑不在。 derivation-rules.yaml仅作文档保留,不参与运行时校验。
阶段边界
退出码 35–39(EXPIRED / ATTESTATION_INVALID / SIGNATURE_INVALID /
KEY_STATUS_INVALID / GATE_DENIED)属阶段二,本引擎不会产生。Gate、Attestation、
签名与密钥均未实现——位置留了,不假装已实现。
依赖
引擎硬依赖 PyYAML。vendor/yaml 内置了 PyYAML 6.0.3 的纯 Python 实现(无需编译,
__with_libyaml__ 为 False 只是没有 C 加速),由适配器通过 PYTHONPATH 注入。
pyproject.toml 声明的 jsonschema 在源码中从未被导入,故未内置。
04 同仓库更多 Skills
sample-supply-chain
供应链样本:安装钩子 + 拼写伪装 + 源覆盖。
sample-prose-only
纯散文安全守则样本:禁止某行为的说明不等于该行为。
sample-obfuscated
混淆载荷样本:解码与执行共现。
sample-hidden-content
隐藏内容载荷样本:用于回归「不可见字符不做上下文降权」这一不变量。
sample-evasion
反规避样本:危险内容只以「不可见字符切断」与「编码后」两种形式出现。
sample-agentic
代理运行时风险样本:配置篡改 + 隐蔽指令。