matthiasrohr/appsec-advisor-packaging-template

# appsec-advisor — 组织打包模板 [](LICENSE) [](https://docs.claude.com/en/docs/claude-code) [](https://codecov.io/gh/matthiasrohr/appsec-advisor-packaging-template) [](https://github.com/matthiasrohr/appsec-advisor) 用于构建内部 [`appsec-advisor`](https://github.com/matthiasrohr/appsec-advisor) Claude Code 插件的 Template repo，包含您自己组织特定的默认设置、需求目录和成本护栏。 ## 快速开始 **前置条件：** `git`, `python3` (3.10+), `make` **1. 创建您的打包 repo** 运行初始化脚本——它会询问您的组织名称和插件名称，然后创建一个随时可用的 git repo，并且所有的占位符都已替换完成： ``` bash <(curl -fsSL https://raw.githubusercontent.com/matthiasrohr/appsec-advisor-packaging-template/main/scripts/init-org-repo.sh) ``` 或者，在 GitHub 上点击 **Use this template** 并手动替换 `Acme Corp` / `acme-appsec`。 **2. 编辑您的组织配置** 在您的新 repo 中打开 `org-profile/org-profile.yaml`。如果您使用了初始化脚本，`organization.id`、`.name`、`.profile_version` 和 `.owner` 已经自动填好。需要手动更新的一项是： - 将 `requirements.source.requirements_yaml_url` 指向您的内部需求目录，或者如果您还没有，请移除该 block。 如果您使用了 GitHub Template，还需要将 `organization.id`、`.name`、`.profile_version` 和 `.owner` 替换为您的值。 **3. 为您的平台设置 CI** — 运行以下命令之一： ``` make ci-github # copies ci-templates/github/workflows/package.yml → .github/workflows/ make ci-gitlab # copies ci-templates/gitlab-ci.yml → .gitlab-ci.yml ``` 然后在 CI repository 变量中将 `INTERNAL_NAME` 设置为您的插件名称（如果它与默认值不同）。 **4. 在本地构建插件：** ``` make package ``` 这会拉取上游插件，覆盖您的组织配置，运行冒烟测试，并将结果写入 `build/your-plugin-name/`。要强制进行全新重建： ``` make rebuild ``` **5. 在 Claude Code 中加载它：** ``` claude --plugin-dir build/your-plugin-name ``` **6. 运行您的第一次威胁建模：** ``` /your-plugin-name:check-permissions --update /your-plugin-name:create-threat-model ``` 对于 CI，标记 release 会自动触发第 3 步中的 pipeline。 ## 自定义 除了快速开始之外，您可以编辑这些文件： | 文件 | 用途 | |---|---| | `org-profile/org-profile.yaml` | 预设、成本护栏、需求来源、输出格式 | | `org-profile/context/organization.md` | 注入到分析中的简短组织上下文（最大 50 KB） | | `org-profile/actors/*.yaml` | 用于威胁建模的自定义威胁行为者 —— 编辑或删除 | | `org-profile/package-policy.yaml` | 包含哪些技能和 hook 的允许列表 | | `org-skills//SKILL.md` | 随上游技能一起发布的可选组织自有的技能 | | `org-mcp.json` | 可选的 MCP server（例如内部 SAST/SCA endpoint）被复制到构建好的插件的 `.mcp.json` 中 —— 选择性启用，仅通过 `${ENV_VAR}` 传递密钥 | `build/`、`dist/` 和 `upstream/` 都是自动生成的 —— 请勿提交它们。 ### 添加您自己的技能 保持上游作为事实来源，并将组织自有的技能放在 `org-skills/` 下： ``` org-skills/ └── acme-architecture-review/ └── SKILL.md ``` `make package` 会在上游打包器运行之前，将这些技能复制到临时的上游源代码树中。`upstream/` 中的 checkout 保持不变。 为了保持可预测性，请遵守两个规则： - 不要重用上游的技能名称。如果本地技能会覆盖 `upstream/appsec-advisor/skills/`，构建将会失败。 - 如果 `org-profile/package-policy.yaml` 使用了 `plugin_surface.skills.include`，请在那里也添加本地技能名称。允许列表同时涵盖上游和组织技能。 ## 构建参考 ``` # 仅验证 org profile make validate # 拉取 upstream + 构建 + smoke test make package # 强制执行 clean rebuild（先移除 upstream/、build/、dist/） make rebuild # 移除所有生成的目录 make clean # 只读 drift check（较新的 release，或者 branch tip 已超过本地 build） make upstream-check # 锁定特定的 upstream release APPSEC_ADVISOR_REF=v0.5.0-beta make package # 跟踪 branch tip 而非 release（每次 build 时重新拉取至其 tip） APPSEC_ADVISOR_REF=develop make package # 构建可分发 archive（.tgz + .sha256） ARCHIVE=1 VERSION=1.0.0 make package-archive # 使用现有的本地 upstream checkout APPSEC_ADVISOR_SOURCE=/path/to/local/appsec-advisor make package ``` ## CI 运行 `make ci-github` 或 `make ci-gitlab` 来安装 CI pipeline（见快速开始第 3 步）。两者执行的操作与本地构建相同：拉取上游代码、构建、冒烟测试，并将 `.tgz` 及其 `.sha256` 作为构建产物上传。pipeline 会在 `v*` tag 和 `workflow_dispatch` 时触发。 | 变量 | 默认值 | 描述 | |---|---|---| | `APPSEC_ADVISOR_URL` | upstream GitHub | 上游 repo 或内部 fork | | `APPSEC_ADVISOR_REF` | `v0.5.0-beta` | Release tag、分支或 `latest` —— 锁定版本以确保构建可重现 | | `INTERNAL_NAME` | `acme-appsec` | 插件名称和 Claude Code 命令命名空间 | | `VERSION` | 派生自 git tag 或 commit SHA | 生成包的版本 | ## 相关项目 - [appsec-advisor](https://github.com/matthiasrohr/appsec-advisor) — 此模板所打包的上游 Claude Code 插件 - [appsec-advisor-fixtures](https://github.com/matthiasrohr/appsec-advisor-fixtures) — `appsec-advisor` 的测试 fixtures ## 参考 - [github.com/matthiasrohr/appsec-advisor](https://github.com/matthiasrohr/appsec-advisor) — 上游插件 - [docs/internal-plugin-packaging.md](https://github.com/matthiasrohr/appsec-advisor/blob/main/docs/internal-plugin-packaging.md) — 完整的打包操作手册 - [docs/org-profiles.md](https://github.com/matthiasrohr/appsec-advisor/blob/main/docs/org-profiles.md) — org-profile.yaml 参考

标签：AI插件, Claude Code, 打包模板, 网络安全研究, 逆向工具