@yottameta/yotta-intel 0.1.0

package/bin/install.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/**
+ * yotta-intel 跨平台安装器（YottaSkills）
+ * 用法:
+ *   npx -y @yottameta/yotta-intel --agent <name>  # 按智能体默认用户级目录安装（推荐）
+ *   npx -y @yottameta/yotta-intel --dir PATH      # 装到指定目录（用户改了目录的智能体）
+ *   npx -y @yottameta/yotta-intel -g              # 安装到全部已知智能体用户级目录
+ *   npx -y @yottameta/yotta-intel                 # 安装到检测到的项目级目录
+ *   npx -y @yottameta/yotta-intel --list          # 列出智能体 -> 默认目录
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SKILL_NAME = 'yotta-intel';
+const PKG_ROOT = path.join(__dirname, '..');
+
+// 智能体 -> 用户级默认技能目录（dirs 按优先级排列；--agent 装到第一个）
+// 依据官方文档：.agents/skills 并非通用目录，被 OpenCode / Cursor / Cline / Amp /
+// Kimi / Gemini CLI / GitHub Copilot 等读取；Claude Code 与 Codex 默认不读 .agents。
+const AGENT_DIRS = {
+  claude:    { label: 'Claude Code',      dirs: ['.claude/skills'] },
+  cursor:    { label: 'Cursor',           dirs: ['.cursor/skills', '.agents/skills'] },
+  codex:     { label: 'Codex',            dirs: ['.codex/skills'] }, // 特判：$CODEX_HOME/skills
+  gemini:    { label: 'Gemini CLI',       dirs: ['.gemini/skills', '.agents/skills'] },
+  goose:     { label: 'Goose',            dirs: ['.config/goose/skills', '.agents/skills'] },
+  amp:       { label: 'Amp',              dirs: ['.config/agents/skills', '.agents/skills'] },
+  opencode:  { label: 'OpenCode',         dirs: ['.config/opencode/skills'] }, // 特判：$XDG_CONFIG_HOME
+  windsurf:  { label: 'Windsurf',         dirs: ['.codeium/windsurf/skills'] },
+  workbuddy: { label: 'WorkBuddy',        dirs: ['.workbuddy/skills'] },
+  kiro:      { label: 'Kiro',             dirs: ['.kiro/skills'] },
+  trae:      { label: 'Trae Code CLI',    dirs: ['.traecli/skills'] },
+  'trae-cn': { label: 'Trae IDE（国内）',  dirs: ['.trae-cn/skills'] },
+  qwen:      { label: 'Qwen Code',        dirs: ['.qwen/skills'] },
+  comate:    { label: 'Comate 文心快码',   dirs: ['.comate/skills'] },
+  codebuddy: { label: 'CodeBuddy Code',   dirs: ['.codebuddy/skills'] },
+  kimi:      { label: 'Kimi Code CLI',    dirs: ['.kimi/skills'] },
+  agents:    { label: '通用 AGENTS.md',    dirs: ['.agents/skills'] },
+};
+
+// Codex 用户级目录特判：优先 $CODEX_HOME/skills，否则 ~/.codex/skills
+function codexUserDir() {
+  const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+  return path.join(base, 'skills');
+}
+
+// OpenCode 用户级目录特判：优先 $XDG_CONFIG_HOME/opencode/skills，否则 ~/.config/opencode/skills
+function opencodeUserDir() {
+  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(base, 'opencode', 'skills');
+}
+
+function resolveUserDir(rel) {
+  if (rel === '.codex/skills') return codexUserDir();
+  if (rel === '.config/opencode/skills') return opencodeUserDir();
+  return path.join(os.homedir(), rel);
+}
+
+function installTo(dest) {
+  const target = path.join(dest, SKILL_NAME);
+  fs.mkdirSync(target, { recursive: true });
+  copyDir(PKG_ROOT, target, new Set(['package.json', 'bin', 'node_modules', '.git']));
+  console.log('installed -> ' + target);
+}
+
+function copyDir(src, dst, skip) {
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (skip.has(entry.name)) continue;
+    const s = path.join(src, entry.name);
+    const d = path.join(dst, entry.name);
+    if (entry.isDirectory()) {
+      fs.mkdirSync(d, { recursive: true });
+      copyDir(s, d, skip);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(s, d);
+    }
+  }
+}
+
+function displayDir(rel) {
+  if (process.platform === 'win32') return '%USERPROFILE%\\' + rel.replace(/\//g, '\\');
+  return '~/' + rel;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const isGlobal = args.includes('-g') || args.includes('--global');
+  const list = args.includes('--list') || args.includes('-l');
+  let explicitDir = null;
+  const di = args.indexOf('--dir');
+  if (di !== -1 && args[di + 1]) explicitDir = args[di + 1];
+  let agent = null;
+  const ai = args.indexOf('--agent');
+  if (ai !== -1 && args[ai + 1]) agent = String(args[ai + 1]).toLowerCase();
+
+  if (list) {
+    console.log('智能体 -> 默认技能目录（--agent <name> 装到第一个，用户级）:');
+    for (const [key, v] of Object.entries(AGENT_DIRS)) {
+      const resolved = v.dirs.map(displayDir);
+      console.log('  ' + key.padEnd(10) + v.label.padEnd(18) + resolved.join('、'));
+    }
+    console.log('\n说明：Windows 用 %USERPROFILE%，Linux/macOS 用 ~；仅收录有官方默认目录的智能体。');
+    console.log('改了目录的请用 --dir <路径>，不要依赖默认位置；若设置了 CODEX_HOME / XDG_CONFIG_HOME，安装自动以该变量为准。');
+    return;
+  }
+
+  if (explicitDir) { installTo(explicitDir); return; }
+
+  if (agent) {
+    const info = AGENT_DIRS[agent];
+    if (!info) {
+      console.log('未收录智能体: ' + agent + '。请用 --dir <路径> 指定技能目录。');
+      console.log('可用: ' + Object.keys(AGENT_DIRS).join(', '));
+      return;
+    }
+    installTo(resolveUserDir(info.dirs[0]));
+    console.log('完成。');
+    return;
+  }
+
+  if (isGlobal) {
+    const seen = new Set();
+    for (const v of Object.values(AGENT_DIRS)) {
+      for (const d of v.dirs) {
+        if (seen.has(d)) continue;
+        seen.add(d);
+        installTo(resolveUserDir(d));
+      }
+    }
+    console.log('完成。');
+    return;
+  }
+
+  const PROJECT_DIRS = [
+    '.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',
+  ];
+  let installedAny = false;
+  for (const d of PROJECT_DIRS) {
+    if (fs.existsSync(d)) { installTo(d); installedAny = true; }
+  }
+  if (!installedAny) {
+    console.log('未检测到项目级智能体目录。可手动复制，或用 --agent <name> / -g 装到用户级。');
+  }
+}
+
+main();

package/install.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# yotta-intel 多智能体安装脚本（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-intel"
+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-intel",
+  "version": "0.1.0",
+  "description": "Yuanqing — a zero-dependency threat-intel IOC extraction & normalization engine for AI agents: extracts IP (IPv4/IPv6), domains, URLs, emails, hashes (MD5/SHA1/SHA256/SHA512) and CVE IDs from threat reports, phishing emails and logs; recognizes and reverses defanged forms (hxxp / [.] / (.) / [dot] / [:] / [@]); deduplicates, normalizes (IDN punycode, default-port stripping) and outputs CSV / JSON / STIX-lite (STIX 2.1 Bundle) with the pure Python 3.8+ standard library. Triggers when the user provides text containing suspicious IPs / domains / URLs / hashes and needs IOC extraction, normalization, dedup, format conversion, or safe sharing. Boundaries: fully local and offline; no reputation lookups, no sample downloads, no proactive scanning; authorized / own-asset / educational use only.",
+  "license": "MIT",
+  "keywords": [
+    "agent-skills",
+    "yotta-intel"
+  ],
+  "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-intel.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "yotta-intel": "bin/install.js"
+  }
+}

package/references/defang-rules.md

@@ -0,0 +1,66 @@
+# defang / refang 规则与共享建议
+
+> 元情 yotta-intel v0.1.0：去活性（defang）写法识别、还原与安全共享指引。
+
+## 1. 为什么要 defang
+
+威胁情报共享时，邮件客户端 / 聊天平台 / 工单系统会把文本中的 URL、邮箱、IP 自动识别为可点击链接或可解析地址：
+
+- 收件人误点恶意链接；
+- 平台把 IOC 当普通链接处理、丢失原文；
+- 自动化沙箱在共享环节触发外联。
+
+defang（去活性）把 IOC 中的「可识别分隔符」替换成安全写法，让平台不再自动识别，同时人仍然能读懂。
+
+## 2. 引擎识别的 defang 写法（refang 输入）
+
+| 原始 | 常见 defang 写法（引擎都能还原） |
+|---|---|
+| `.` | `[.]` `(.)` `{.}` `[dot]` `(dot)` `{dot}`（大小写不敏感） |
+| `:` | `[:]` `(:)` `{:}` `[colon]` `(colon)` `{colon}` |
+| `@` | `[@]` `(@)` `{@}` `[at]` `(at)` `{at}` |
+| `/` | `[/]` `(/)` `[\/]` `[\\]` |
+| `http` | `hxxp` `hXXp` |
+| `https` | `hxxps` `hXXps` |
+
+例：`hxxp://malware[.]example[.]com/loader.exe` → refang → `http://malware.example.com/loader.exe`。
+
+## 3. 引擎输出的统一 defang 形态（defang_value）
+
+引擎输出统一风格，保证同一 IOC 在任何地方 defang 后形态一致：
+
+| 类型 | 原始 | defang |
+|---|---|---|
+| ipv4 | `203.0.113.5` | `203[.]0[.]113[.]5` |
+| ipv6 | `2001:db8::1` | `2001[:]db8[:][:]1` |
+| domain | `evil.example.com` | `evil[.]example[.]com` |
+| url | `https://evil.example.com/a` | `hxxps://evil[.]example[.]com/a` |
+| email | `admin@example.com` | `admin[@]example[.]com` |
+| hash | `44d886…2f` | 不变（十六进制不会被自动链接） |
+| cve | `CVE-2024-1234` | 不变（不会被自动链接） |
+
+URL 的 defang 会同时处理 host 里的 `@`（userinfo）：`http://user@evil.com/a` →
+`hxxp://user[@]evil[.]com/a`。
+
+## 4. 三个子命令怎么配合
+
+- `extract`：提取 + 归一 + 去重 + 输出。每条结果自带 `value`（原始规范形态）与 `defanged`（安全共享形态）。
+- `defang`：流式把一段文本中识别到的 IOC 替换为 defang 形态（其余原文保留）——适合「把报告转成可安全粘贴的版本」。
+- `refang`：把 defang 文本还原为原始形态——适合「把别人发来的 defang 情报喂给 extract 或其它工具」。
+
+```bash
+# 把一份威胁报告转成安全共享版
+python3 scripts/yotta_intel.py defang --path report.txt --output safe.txt
+
+# 把安全共享版还原后再提取
+python3 scripts/yotta_intel.py refang --path safe.txt | python3 scripts/yotta_intel.py extract --stdin --format json
+```
+
+## 5. 共享纪律建议
+
+1. 在邮件 / 群聊 / 工单里共享 IOC 时，优先贴 defang 形态 + 注明「已 defang」。
+3. 贴原始形态时，用代码块或等宽字体包起来，降低被自动链接的风险。
+3. 不要把 defang 当加密：defang 只是防误点，不是防分析——机器可以一键还原。
+4. 哈希与 CVE 无需 defang；不要给它们画蛇添足加括号，避免下游解析出错。
+5. 共享 STIX-lite 时（stix-lite-spec.md），pattern 内用原始值（机器可解析），
+   人看的备注列用 defang 形态。

package/references/ioc-spec.md

@@ -0,0 +1,66 @@
+# IOC 类型与判定规则（ioc-spec）
+
+> 元情 yotta-intel v0.1.0 内部规范：七类 IOC 的提取 / 归一 / 误报控制规则。
+> 本文件是引擎行为的权威说明；SKILL.md 只放入口，细节在这里。
+
+## 1. 支持的类型
+
+| 类型 key | 中文 | 示例 | STIX 对象 |
+|---|---|---|---|
+| `ipv4` | IPv4 地址 | `203.0.113.5` | `ipv4-addr` |
+| `ipv6` | IPv6 地址 | `2001:db8::1` | `ipv6-addr` |
+| `domain` | 域名（FQDN） | `evil.example.com` | `domain-name` |
+| `url` | URL | `http://evil.example.com/a` | `url` |
+| `email` | 邮箱 | `admin@example.com` | `email-addr` |
+| `hash` | 哈希（MD5/SHA1/SHA256/SHA512） | `44d886…2f` | `file:hashes` |
+| `cve` | CVE 编号 | `CVE-2024-1234` | `vulnerability` |
+
+## 2. 提取流程
+
+1. **refang 预处理**：先识别并还原 defang 写法（`hxxp`、`[.]`、`(.)`、`[dot]`、`[:]`、`[@]`、`[/]`），
+   让 defang 文本与原始文本走同一套提取逻辑；还原只替换分隔符，不改变行结构（行号可追溯）。
+2. **逐行提取**：对每一行跑类型正则 + 校验函数，输出 `(start, end, type, canonical)`。
+3. **归一化**：每种类型转成唯一的规范形态（见 §3）。
+4. **去重计数**：以 `(type, canonical)` 为键合并，记录 `count`（出现次数）、`first_line`（首次行号）与
+   `snippet`（首次出现的整行上下文）。
+
+## 3. 归一化规则
+
+| 类型 | 规则 |
+|---|---|
+| ipv4 | 用 `ipaddress.IPv4Address` 校验并规范化；前导零（如 `010.0.0.1`）归一为 `10.0.0.1`；非法八位组（如 `999.1.1.1`）剔除 |
+| ipv6 | 用 `ipaddress.IPv6Address` 校验；输出压缩写法（如 `2001:0db8::1` → `2001:db8::1`）；IPv4-mapped（`::ffff:192.168.1.1`）输出规范十六进制 `::ffff:c0a8:101` |
+| domain | 小写；去尾点（`example.com.` → `example.com`）；IDN 转 punycode（`例子.测试` → `xn--fsqu00a.xn--0zwm56d`） |
+| url | scheme/host 小写；host 做 IDN；去默认端口（http:80 / https:443 / ftp:21）；去 fragment（`#…` 不发给服务器）；保留 userinfo、path、query |
+| email | 小写；域名段做 IDN；要求域名段合法 |
+| hash | 十六进制小写；仅接受 32/40/64/128 位（MD5/SHA1/SHA256/SHA512） |
+| cve | 统一大写 `CVE-YYYY-NNNN` |
+
+## 4. 误报控制
+
+- **域名 TLD 白名单**：`valid_domain()` 只接受内置 TLD 集合（常见 gTLD + 主流新 gTLD + 全部 ISO 3166-1 ccTLD）内
+  的末段，或 `xn--` 开头的 IDN TLD；`badexample.zzz` 这类不存在的 TLD 不会误报。
+- **文件名过滤**：与常见文件扩展名重叠的 TLD（`md`/`py`/`sh`/`js`/`ts`/`json`/`log`/`png`/`pdf`…）在
+  **二段域名**命中时按文件名处理（`README.md`、`test.py` 不算域名）；三段及以上（如 `cdn.evil.md`）仍按域名。
+- **数字末段**：`1.2.3.44` 的末段 `44` 不是合法 TLD → 不算域名（由 IPv4 提取接管）。
+- **单标签**：`localhost` 等无点名称不算域名。
+- **邮箱内嵌域名**：`admin@example.com` 只提 email，`example.com` 不会被重复提为 domain。
+- **URL 标点**：URL 正则排除中文/全角标点（`，。！？；：、（）【】《》`），并去掉尾部 ASCII 标点
+  （`http://a.com/a.` → `http://a.com/a`）。
+- **哈希**：只接受连续的 32/40/64/128 位十六进制串；UUID（带连字符）与非常规长度（如 48 位）不匹配。
+- **IPv6**：`ipaddress` 严格校验；`namespace::method` 里的 `::` 因前邻单词字符不会误报为 IPv6。
+
+## 5. 已知取舍
+
+- 二段 `x.md` 这类「真域名 vs 文件名」无法仅凭文本区分，本引擎按文件名处理（降低常见误报），
+  需要时可在结果里人工放行。
+- 域名不去 `www.` 前缀、不拆注册域（eTLD+1），去重键 = 完整 FQDN；同一域名的不同子域是不同 IOC。
+- URL 与其中包含的 IP / 域名会同时输出（`http://1.2.3.4/x` 同时有 url 与 ipv4），便于下游按需取用。
+- defang 流式输出（`defang` 子命令）只替换识别为 IOC 的部分，其余文本原样保留；非 IOC 的零散 `[.]` 会被
+  refang 归一为 `.`（见 defang-rules.md）。
+
+## 6. 边界与红线
+
+- 纯本地离线：不联网查证、不下载样本、不主动扫描任何系统；只做文本提取与规范化。
+- 提取结果只是「候选指标」，是否恶意需人工 / 其他情报源核实；本引擎不给恶意定性。
+- 仅用于已获授权 / 自有资产 / 教学环境的安全分析。

package/references/stix-lite-spec.md

@@ -0,0 +1,76 @@
+# STIX-lite 输出规范
+
+> 元情 yotta-intel v0.1.0：`extract --format stix` 的产物说明。
+> 「lite」= 只生成 STIX 2.1 的 Indicator 对象 + 自定义扩展属性，不实现完整 STIX 库。
+
+## 1. 为什么叫 lite
+
+STIX 2.1 全量模型（SDO/SRO、Bundle、图谱关系、Confidence/Kill Chain 等）非常庞大。本引擎只做
+**单条 IOC → 单条 Indicator** 的确定性映射，输出合法、可被主流 STIX 解析器读取的最小 Bundle：
+不引入外部依赖，不生成复杂关系，方便直接贴进 MISP / OpenCTI 等平台做导入或人工核对。
+
+## 2. Bundle 结构
+
+```json
+{
+  "type": "bundle",
+  "id": "bundle--<uuid5>",
+  "spec_version": "2.1",
+  "objects": [ { "type": "indicator", ... }, ... ]
+}
+```
+
+- `id`：由 `yotta-intel:<生成时间>` 经 uuid5 派生，同一输入在同一时刻生成结果稳定；
+  每次运行时间戳不同，`bundle id` 会变（符合 STIX 对 id 唯一性的要求）。
+- `spec_version`：`2.1`。
+
+## 3. Indicator 对象
+
+```json
+{
+  "type": "indicator",
+  "spec_version": "2.1",
+  "id": "indicator--<uuid5>",
+  "created": "2026-08-27T00:00:00+00:00",
+  "modified": "2026-08-27T00:00:00+00:00",
+  "name": "域名: evil.example.com",
+  "pattern": "[domain-name:value = 'evil.example.com']",
+  "pattern_type": "stix",
+  "valid_from": "2026-08-27T00:00:00+00:00",
+  "labels": ["malicious-activity"],
+  "x_yottameta_type": "domain",
+  "x_yottameta_value": "evil.example.com",
+  "x_yottameta_defanged": "evil[.]example[.]com",
+  "x_yottameta_count": 3
+}
+```
+
+- `id`：`uuid5(NAMESPACE_URL, "yotta-intel:<type>:<value>")`，同一 IOC 跨运行稳定（确定性）。
+- `created` / `modified` / `valid_from`：均为生成时刻（UTC ISO 8601）。
+- `labels`：默认 `["malicious-activity"]`——仅表示「这是待核实的可疑指标」，不是最终定性。
+- `x_yottameta_*`：YottaMeta 自定义扩展属性，供下游直接取用；不认识的解析器会忽略未知字段。
+
+## 4. pattern 映射
+
+| 类型 | STIX 2.1 pattern |
+|---|---|
+| ipv4 | `[ipv4-addr:value = '203.0.113.5']` |
+| ipv6 | `[ipv6-addr:value = '2001:db8::1']` |
+| domain | `[domain-name:value = 'evil.example.com']` |
+| url | `[url:value = 'http://evil.example.com/a']` |
+| email | `[email-addr:value = 'admin@example.com']` |
+| hash (MD5) | `[file:hashes.'MD5' = '44d886…2f']` |
+| hash (SHA-1) | `[file:hashes.'SHA-1' = '…']` |
+| hash (SHA-256) | `[file:hashes.'SHA-256' = '…']` |
+| hash (SHA-512) | `[file:hashes.'SHA-512' = '…']` |
+| cve | `[vulnerability:name = 'CVE-2024-1234']` |
+
+pattern 内使用原始规范值（机器可解析）；人看的 defang 形态放在 `x_yottameta_defanged`。
+
+## 5. 使用建议
+
+- **导入平台**：把 `--format stix` 的输出直接贴进 MISP / OpenCTI / Splunk 的 STIX 导入接口。
+- **共享**：与报告一起发时，把 `defanged` 列给读者看，把 STIX 文件给机器用。
+- **人工核对**：`labels` 是默认值，接入生产情报库前应由分析师复核并补充 Confidence / 来源。
+- **升级提示**：本输出是 lite 子集，不含 Sighting / Relationship / Kill Chain；需要完整图谱时
+  请用专业 STIX 工具链。