@yottameta/yotta-chain 0.1.0

package/install.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# yotta-chain 多智能体安装脚本（YottaSkills 模板）
+# 用法:
+#   bash install.sh --agent <name>  # 按智能体默认用户级目录安装
+#   bash install.sh --dir <path>    # 装到指定目录（用户改过目录的智能体）
+#   bash install.sh -g              # 装到全部已知智能体用户级目录
+#   bash install.sh                  # 检测并安装到已存在的项目级目录
+#   bash install.sh --list          # 列出智能体 -> 默认目录
+set -euo pipefail
+
+SKILL_NAME="yotta-chain"
+SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+case "$(uname -s)" in
+  MINGW*|MSYS*)
+    SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -W)"
+    ;;
+esac
+
+# 智能体 -> 用户级默认目录（--agent 装到第一个）
+# .agents/skills 并非通用目录：OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot 读取。
+# 判断当前环境：Windows Git Bash 用 %USERPROFILE%，Unix 用 ~
+_IS_WINDOWS=0
+case "$(uname -s)" in
+  MINGW*|MSYS*|CYGWIN*) _IS_WINDOWS=1 ;;
+esac
+dirs_for() {
+  case "$1" in
+    claude)     echo ".claude/skills" ;;
+    cursor)     echo ".cursor/skills .agents/skills" ;;
+    codex)      echo "__CODEX__" ;;
+    gemini)     echo ".gemini/skills .agents/skills" ;;
+    goose)      echo ".config/goose/skills .agents/skills" ;;
+    amp)        echo ".config/agents/skills .agents/skills" ;;
+    opencode)   echo "__OPENCODE__" ;;
+    windsurf)   echo ".codeium/windsurf/skills" ;;
+    workbuddy)  echo ".workbuddy/skills" ;;
+    kiro)       echo ".kiro/skills" ;;
+    trae)       echo ".traecli/skills" ;;
+    trae-cn)    echo ".trae-cn/skills" ;;
+    qwen)       echo ".qwen/skills" ;;
+    comate)     echo ".comate/skills" ;;
+    codebuddy)  echo ".codebuddy/skills" ;;
+    kimi)       echo ".kimi/skills" ;;
+    agents)     echo ".agents/skills" ;;
+    *)          return 1 ;;
+  esac
+}
+
+codex_dir() {
+  if [ -n "${CODEX_HOME:-}" ]; then printf '%s' "$CODEX_HOME/skills"; else printf '%s' "$HOME/.codex/skills"; fi
+}
+opencode_dir() {
+  if [ -n "${XDG_CONFIG_HOME:-}" ]; then printf '%s' "$XDG_CONFIG_HOME/opencode/skills"; else printf '%s' "$HOME/.config/opencode/skills"; fi
+}
+resolve_user() {
+  case "$1" in
+    __CODEX__)    codex_dir ;;
+    __OPENCODE__) opencode_dir ;;
+    *)            printf '%s' "$HOME/$1" ;;
+  esac
+}
+
+install_to() {
+  mkdir -p "$1/$SKILL_NAME"
+  cp -r "$SOURCE_DIR/." "$1/$SKILL_NAME/"
+  rm -rf "$1/$SKILL_NAME/.git"
+  echo "installed -> $1/$SKILL_NAME"
+}
+
+list() {
+  echo "智能体 -> 默认技能目录（--agent <name> 装到第一个，用户级）:"
+  for a in claude cursor codex gemini goose amp opencode windsurf workbuddy kiro trae trae-cn qwen comate codebuddy kimi agents; do
+    local dirs first
+    dirs="$(dirs_for "$a")"
+    first="${dirs%% *}"
+    case "$first" in
+      __CODEX__)    first=".codex/skills" ;;
+      __OPENCODE__) first=".config/opencode/skills" ;;
+    esac
+    if [ "$_IS_WINDOWS" = "1" ]; then
+      first="%USERPROFILE%\\${first//\//\\}"
+    else
+      first="~/$first"
+    fi
+    printf '  %-10s %s\n' "$a" "$first"
+  done
+  echo '说明：Windows 用 %USERPROFILE%，Linux/macOS 用 ~；仅收录有官方默认目录的智能体。'
+  echo '改了目录的请用 --dir <路径>，不要依赖默认位置；若设置了 CODEX_HOME / XDG_CONFIG_HOME，安装自动以该变量为准。'
+}
+
+main() {
+  local agent="" dir="" global=0 show_list=0
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --agent) shift; agent="${1:-}" ;;
+      --dir)   shift; dir="${1:-}" ;;
+      -g|--global) global=1 ;;
+      --list|-l) show_list=1 ;;
+      *) echo "未知参数: $1" >&2; exit 2 ;;
+    esac
+    shift
+  done
+
+  if [ "$show_list" = "1" ]; then list; return; fi
+  if [ -n "$dir" ]; then install_to "$dir"; echo "完成。"; return; fi
+  if [ -n "$agent" ]; then
+    local dirs first
+    if ! dirs="$(dirs_for "$agent")"; then
+      echo "未收录智能体: $agent。请用 --dir <路径> 指定技能目录。" >&2; exit 2
+    fi
+    first="${dirs%% *}"
+    install_to "$(resolve_user "$first")"; echo "完成。"; return
+  fi
+  if [ "$global" = "1" ]; then
+    echo "安装到全部已知智能体用户级目录..."
+    local dirs rel
+    for a in claude cursor codex gemini goose amp opencode windsurf workbuddy kiro trae trae-cn qwen comate codebuddy kimi agents; do
+      dirs="$(dirs_for "$a")"
+      for rel in $dirs; do install_to "$(resolve_user "$rel")"; done
+    done
+    echo "完成。"; return
+  fi
+  local installed=0 d
+  for d in .claude/skills .cursor/skills .codex/skills .config/goose/skills .config/agents/skills .opencode/skills .codeium/windsurf/skills .workbuddy/skills .kiro/skills .traecli/skills .gemini/skills .trae-cn/skills .qwen/skills .comate/skills .codebuddy/skills .kimi/skills .agents/skills; do
+    if [ -d "$d" ]; then install_to "$d"; installed=1; fi
+  done
+  if [ "$installed" = "0" ]; then
+    echo "未检测到项目级智能体目录。可用 --agent <name> / -g 装到用户级，或 --dir 指定。"
+  fi
+}
+
+main "$@"

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@yottameta/yotta-chain",
+  "version": "0.1.0",
+  "description": "Yuanlian — a zero-dependency supply-chain dependency validator for AI agents: detects dependency confusion (private package names resolved from public registries, mixed registries, suspicious registry URLs), lockfile consistency issues (missing entries, unsatisfied ranges, dangling references, missing integrity), missing lockfiles, unpinned versions, SNAPSHOT deps and typosquatting across npm (package.json + package-lock v1/v2/v3), Python (requirements.txt, pyproject.toml, poetry.lock, Pipfile/Pipfile.lock) and Maven (pom.xml); generates SBOM-lite (CycloneDX 1.5 subset). Pure Python 3.8+ standard library, fully local and offline, no online CVE lookups. Triggers when the user needs to check a project dependencies for supply-chain risks before build/release, verify a lockfile matches its manifest, detect dependency-confusion exposure, or generate an SBOM. Boundaries: local and offline; no CVE databases, no package-registry queries, no data leaves the machine; findings are review signals to be verified by humans; authorized / own-asset / educational use only.",
+  "license": "MIT",
+  "keywords": [
+    "agent-skills",
+    "yotta-chain"
+  ],
+  "files": [
+    "SKILL.md",
+    "LICENSE",
+    "README.md",
+    "README.zh-CN.md",
+    "install.sh",
+    "references",
+    "scripts",
+    "assets",
+    "bin",
+    "NOTICE",
+    "CHANGELOG.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YottaMeta/yotta-chain.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "yotta-chain": "bin/install.js"
+  }
+}

package/references/rules.md

@@ -0,0 +1,124 @@
+# 元链 yotta-chain — 检测规则参考
+
+> 每条规则的触发逻辑、严重度与修复指引。用于人工复核与教学。
+
+## 严重度
+
+`info < low < medium < high`。`scan` 默认 `--gate=info`（任何发现即退出 1），CI 可 `--gate high` 收紧。
+
+## 一、依赖混淆（dependency confusion）
+
+依赖混淆：攻击者把「只应存在于私有仓库的包名」发布到公共仓库（npm / PyPI），利用解析优先级让受害者装到恶意包。本引擎**纯本地**用「仓库配置 vs 实际解析来源」给强信号。
+
+### confusion_scope_registry（high）
+
+- 触发：`.npmrc` 为某 scope 配置了私有仓库（`@scope:registry=...`），但 package-lock.json 里该 scope 的包 `resolved` 指向其它（公共）仓库主机。
+- 含义：私有包名本应从私有仓库解析，实际却可能被公共仓库的同名攻击者包抢占。
+- 示例：
+
+  ```
+  # .npmrc
+  @corp:registry=https://npm.corp.example.com/
+  # package-lock.json
+  "node_modules/@corp/secret": { "resolved": "https://registry.npmjs.org/@corp/secret.tgz" }
+  ```
+
+- 修复：核对 resolved 是否应指向私有仓库；用正确的私有仓库重新 `npm install` 并检查锁文件 resolved 主机；把 `.npmrc` 提交入库（或用 CI 注入）。
+
+### confusion_mixed_registry（high）
+
+- 触发：同一包名在锁文件里被解析自多个不同仓库主机（如顶层来自公共 registry，嵌套来自公司镜像）。
+- 含义：同一依赖来源不一致，可能是镜像污染或被替换。
+- 修复：统一到单一可信仓库；删除不一致条目后重新安装。
+
+### confusion_suspicious_registry（medium）
+
+- 触发：仓库 / 索引地址为 `http://`（非 TLS）、IP 字面量（如 `http://192.168.1.5/...`）、本机地址（localhost / 127.0.0.1）。
+- 含义：非 HTTPS 或指向内网 / 本机的仓库可被中间人篡改，或指向开发环境残留。
+- 修复：改用 HTTPS 域名仓库；删除开发期残留地址。
+
+### confusion_extra_index（medium）
+
+- 触发：pip 同时配置 `--index-url`（私有）与 `--extra-index-url`（公共，如 PyPI）；或 poetry 源标记 `secondary = true`；或 Pipfile 同时列出公共 PyPI 与私有源。
+- 含义：公共仓库成为回退源——私有包名只要在公共仓库出现同名包，就可能被抢占（依赖混淆经典场景）。
+- 修复：只保留单一可信源；私有包确保只在私有源解析；poetry 把私有源设为 `default` 并关闭 PyPI 回退；pip 用 `--index-url` 单一私有源 + 显式 `--extra-index-url` 白名单。
+
+### confusion_registry_mismatch（medium）
+
+- 触发：项目配置了私有默认仓库（`.npmrc registry=` 或 package.json publishConfig），但锁文件里包从公共仓库（registry.npmjs.org）解析。
+- 含义：配置与锁定来源不一致，私有包名可能从公共仓库被抢占。
+- 修复：核对默认仓库配置与锁文件生成时机；重新安装生成锁文件。
+
+## 二、lockfile 一致性
+
+### lockfile_missing_entry（high）
+
+- 触发：清单（package.json / pyproject.toml / Pipfile）声明了依赖，锁文件里却没有。
+- 修复：`npm install` / `poetry lock` / `pipenv lock` 重新生成锁文件；若锁文件被手工删条目需还原。
+
+### lockfile_range_unsatisfied（high）
+
+- 触发：锁文件版本不满足清单声明的版本范围（npm semver / PEP 440 语义）。
+- 示例：`"lodash": "^5.0.0"` 但锁文件锁定 `4.17.21`。
+- 修复：声明与锁定必须一致；升级或回退后重新生成锁文件。
+
+### lockfile_dangling_ref（high）
+
+- 触发：锁文件里某包依赖的包名不存在于锁文件包列表（依赖图断裂）。
+- 修复：重新生成锁文件；手工编辑锁文件会破坏依赖图。
+
+### lockfile_duplicate_conflict（high）
+
+- 触发：同名同版本存在多个不同 `resolved` / `integrity` 来源。
+- 含义：同一版本解析到不同 tarball，存在被替换风险。
+- 修复：统一来源；核对 integrity 是否与官方一致。
+
+### lockfile_root_mismatch（medium）
+
+- 触发：锁文件根 `name` / `version` 与清单不一致。
+- 修复：锁文件与清单应对应同一项目；复制 / 改名后需重新生成。
+
+### lockfile_integrity_missing（medium）
+
+- 触发：package-lock.json（v2/v3）条目缺 `integrity`、poetry.lock `files` 为空、Pipfile.lock 条目缺 `hashes`。
+- 含义：缺少完整性校验，安装无法防篡改。
+- 修复：重新生成锁文件（npm / poetry / pipenv 均会写入哈希）。
+
+## 三、卫生
+
+### missing_lockfile（medium）
+
+- 触发：声明了依赖但没有锁文件（package.json 无 package-lock.json / npm-shrinkwrap.json；pyproject.toml 或 Pipfile 无 poetry.lock / Pipfile.lock）。
+- 修复：提交锁文件并使用 `npm ci` / `poetry install --locked` / `pipenv install --deploy` 保证可复现。
+
+### unpinned（low / medium）
+
+- 触发：npm 依赖为 `*` / `latest` / 未指定；requirements.txt 无版本约束；Maven 依赖未声明 `<version>` 且不在 dependencyManagement（medium）。
+- 修复：给出精确或收窄范围并配合锁文件。
+
+### snapshot（low）
+
+- 触发：Maven 依赖使用 `-SNAPSHOT` 版本。
+- 修复：发布物改用 release 版本。
+
+## 四、typo-squat
+
+### typosquat（low）
+
+- 触发：依赖名与内置知名 npm / PyPI 包列表编辑距离 ≤ 2（含转置），如 `lodassh`→lodash、`requets`→requests。
+- 含义：拼写仿冒包是供应链投毒常见手法，需人工确认包名与来源。
+- 修复：核对包名拼写与发布者；用精确版本 + 完整性哈希；可配置私有仓库白名单。
+- 说明：内置列表是常用包子集，未覆盖 ≠ 安全；本规则只做提示，不自动判定恶意。
+
+## 五、版本范围语义
+
+- **npm semver**：`^` `~` `>=` `<=` `>` `<` `=`、x 范围（`1.x` / `1.2.x`）、`*`、`||` 或、连字符范围（`1.2.3 - 2.3.4`）、预发布规则（预发布版本默认不满足不含预发布的比较器）。
+- **PEP 440**：`==` `!=` `>=` `<=` `>` `<` `~=` `===`、逗号 AND、`||` 或、`==1.2.*` 通配；`~=1.2` = `>=1.2,==1.2.*`。
+
+## 六、已知限制（v0.1.0）
+
+- 不做在线 CVE 比对（那是 snyk / trivy / npm audit 的地盘）。
+- 依赖混淆为本地近似：真正确认「私有包名被公共仓库抢占」需要在线核对，引擎给强信号供人工复核。
+- `yarn.lock` / `pnpm-lock.yaml` / `go.mod` / `Cargo.lock` 未支持（见 CHANGELOG 后续计划）。
+- 只扫描给定目录（不递归子目录 monorepo）；`-r` 递归的 requirements 会跟随（深度 ≤ 5）。
+- 不读用户级 `.npmrc` / `pip.conf`（只读项目内配置），避免触碰项目外数据。