@inventec/dsh-onetree-log 0.1.0

package/lib/detect.js

@@ -0,0 +1,179 @@
+/**
+ * detect.js — OneTree 一键日志（OpenBMC dreport dump）探测。
+ *
+ * OneTree 是 AMI 的 OpenBMC 商业发行版，其"一键日志"由 phosphor-debug-collector
+ * （dreport）产出：一组扁平的 *.log 文件（ipmitool/journalctl/busctl 等命令输出）。
+ * 本模块在解包后的目录树里按"标记文件评分"定位 dump 根：
+ *   - 强标记（dreport 专属）：selinfo.log / sensorinfo.log / journal-pretty.log … 每个 +3
+ *   - 中标记（通用 OpenBMC 采集项）：dmesg.log / fru-info.log / inventory.log … 每个 +1
+ *   - 分数 ≥3 判定为 OneTree dump
+ *
+ * 兼容两种常见包装：
+ *   1. 外层包直接就是 dump 文件集（根即 dump 根）
+ *   2. 外层包里嵌着内层压缩包（OEM 常见 zip 套 tar）→ 唯一压缩包时自动解一层（≤2 层）
+ *
+ * 另附 SP-X FFDC 血统标记（sulist / nvram / sensor_data 等），仅作提示——
+ * 命中说明用户上传的是老 SP-X FFDC 而非 OneTree dump，错误信息里指出来。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { extractArchive, isArchive } from './extract.js'
+
+export const STRONG_MARKERS = [
+  'selinfo.log', 'sensorinfo.log', 'sensor-readings.log', 'journal-pretty.log',
+  'dreport.log', 'dreport_cmdfailure.log', 'dreport.cfg', 'elogall.log',
+  'biospostcode.log', 'obmc-console.log', 'journalctl.log',
+]
+export const MEDIUM_MARKERS = [
+  'dmesg.log', 'fru-info.log', 'inventory.log', 'fw-version.log', 'fw-printenv.log',
+  'failed-services.log', 'pslist.log', 'top.log', 'hwmon.log', 'summary.log',
+  'em-system.json', 'bmc-state.log', 'host-state.log', 'chassis-state.log',
+  'cpuinfo', 'meminfo', 'uptime.log', 'network.log', 'netstat.log', 'iproute.log',
+  'kernalringbuff.log', 'kernelringbuff.log', 'bios.log', 'boot-progress-info.log',
+]
+export const SPX_MARKERS = [
+  'sulist', 'nvram', 'sensor_data', 'sel_data', 'all_sel_info', 'ipmi_log',
+  'confblob', 'ami_info', 'bmc_data',
+]
+
+const WALK_MAX_ENTRIES = 20_000
+const NESTED_DEPTH = 2
+
+function listDirSafe(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return []
+  }
+}
+
+/**
+ * 扫描目录树，返回 { perDir: Map<dir, {score, strong[], medium[], spx[]}>, files: [{dir,name,size}] }。
+ */
+function scanTree(rootDir) {
+  const perDir = new Map()
+  const files = []
+  let entries = 0
+  const walk = dir => {
+    for (const e of listDirSafe(dir)) {
+      if (++entries > WALK_MAX_ENTRIES) return
+      const full = path.join(dir, e.name)
+      if (e.isDirectory()) {
+        walk(full)
+      } else if (e.isFile()) {
+        const known = STRONG_MARKERS.includes(e.name) ? 'strong'
+          : MEDIUM_MARKERS.includes(e.name) ? 'medium'
+          : SPX_MARKERS.includes(e.name.toLowerCase()) ? 'spx' : null
+        let size = 0
+        try { size = fs.statSync(full).size } catch { /* ignore */ }
+        files.push({ dir, name: e.name, size, known })
+        if (known) {
+          let slot = perDir.get(dir)
+          if (!slot) { slot = { score: 0, strong: [], medium: [], spx: [] }; perDir.set(dir, slot) }
+          slot[known === 'spx' ? 'spx' : known].push(e.name)
+          if (known === 'strong') slot.score += 3
+          else if (known === 'medium') slot.score += 1
+        }
+      }
+    }
+  }
+  walk(rootDir)
+  return { perDir, files }
+}
+
+/** 从 perDir 里选 dump 根：分数最高者；平分取最深（最贴近文件集本身）。 */
+function pickRoot(rootDir, perDir) {
+  let best = null
+  for (const [dir, slot] of perDir) {
+    if (slot.score < 3) continue
+    const depth = dir.split(path.sep).length
+    if (best === null || slot.score > best.slot.score
+      || (slot.score === best.slot.score && depth > best.depth)) {
+      best = { dir, slot, depth }
+    }
+  }
+  return best
+}
+
+function topEntries(dir, limit = 15) {
+  try {
+    return fs.readdirSync(dir).slice(0, limit)
+  } catch {
+    return []
+  }
+}
+
+/**
+ * 探测 OneTree dump 根目录。
+ * 返回 { rootDir, score, markers: {strong, medium}, hint }；
+ * 未识别时抛错（错误信息包含顶层内容与 SP-X 提示，便于用户判断）。
+ */
+export function detectDumpRoot(extractDir) {
+  const { perDir, files } = scanTree(extractDir)
+  const best = pickRoot(extractDir, perDir)
+  if (best) {
+    return {
+      rootDir: best.dir,
+      score: best.slot.score,
+      markers: { strong: best.slot.strong, medium: best.slot.medium },
+      hint: null,
+    }
+  }
+  const spxHit = files.filter(f => f.known === 'spx').map(f => f.name)
+  if (spxHit.length > 0) {
+    const err = new Error('这更像 AMI MegaRAC SP-X 的 FFDC 日志（未发现 OneTree/OpenBMC dreport 标记文件，但发现 ' + spxHit.slice(0, 5).join(', ') + '）。本插件第一阶段只支持 OneTree（OpenBMC dreport）一键日志。')
+    err.code = 'SPX_NOT_ONETREE'
+    throw err
+  }
+  const err = new Error('未找到 OneTree 一键日志标记文件（如 selinfo.log / journal-pretty.log / dmesg.log）。顶层内容: ' + topEntries(extractDir).join(', '))
+  err.code = 'NOT_ONETREE'
+  err.topEntries = topEntries(extractDir)
+  throw err
+}
+
+/**
+ * 判断目录是否"只有一个压缩包值得展开"（嵌套包装场景）。
+ * 返回该压缩包路径或 null。
+ */
+function soleNestedArchive(extractDir, files) {
+  const archives = files.filter(f => isArchive(f.name))
+  const others = files.filter(f => !isArchive(f.name))
+  if (archives.length === 1 && others.length === 0) {
+    return path.join(archives[0].dir, archives[0].name)
+  }
+  return null
+}
+
+/**
+ * 解包 + 探测一体：处理嵌套包装（zip 套 tar 等，≤NESTED_DEPTH 层）。
+ * 返回 detectDumpRoot 的结果；每层解到 extractDir 下的子目录。
+ */
+export async function extractAndDetect(archivePath, extractDir, opts = {}) {
+  let currentArchive = archivePath
+  let currentDir = extractDir
+  for (let depth = 0; depth < NESTED_DEPTH; depth += 1) {
+    const innerDir = path.join(currentDir, '__extracted')
+    await extractArchive(currentArchive, innerDir, opts)
+    const { perDir, files } = scanTree(innerDir)
+    const best = pickRoot(innerDir, perDir)
+    if (best) {
+      return {
+        rootDir: best.dir,
+        score: best.slot.score,
+        markers: { strong: best.slot.strong, medium: best.slot.medium },
+        hint: depth > 0 ? `嵌套包装已自动展开 ${depth} 层` : null,
+      }
+    }
+    const nested = soleNestedArchive(innerDir, files)
+    if (nested === null) {
+      // 不是嵌套包装：用统一入口报错（带 SP-X 提示）
+      detectDumpRoot(innerDir)
+      return // unreachable: detectDumpRoot 必抛错
+    }
+    currentArchive = nested
+    currentDir = innerDir
+  }
+  const err = new Error(`嵌套压缩包超过 ${NESTED_DEPTH} 层，放弃展开`)
+  err.code = 'TOO_NESTED'
+  throw err
+}

package/lib/extract.js

@@ -0,0 +1,310 @@
+/**
+ * extract.js — 安全解包：OneTree 一键日志压缩包 → 目录。
+ *
+ * 设计参照 openUBMC bmcstudio_log_reviewer 的 archive.ts 思路（纯 JS tar 读取器，
+ * 拒绝路径逃逸 / 符号链接 / 超限解压），并适配 OneTree 生态：
+ *   - `.tar` / `.tar.gz` / `.tgz`：纯 JS 流式 tar 解析（ustar / pax / GNU longname）
+ *   - `.tar.zst` / `.tzst`：Node ≥22.15 的 zlib zstd 流；无原生支持时回退系统 `zstd -dc`
+ *   - `.zip`：系统 `unzip`（回退 `tar`），先列目校验再解压（execFile，无 shell）
+ *
+ * 防护：zip-slip（绝对路径 / `..` / NUL）、符号链接与硬链接直接拒绝、
+ * 单文件 1GiB / 总量 2GiB / 条目数 20k 上限，超限立即中止并抛错。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import zlib from 'node:zlib'
+import { execFile, spawn } from 'node:child_process'
+import { Readable } from 'node:stream'
+import { finished } from 'node:stream/promises'
+
+export const ARCHIVE_EXTS = ['.tar', '.tar.gz', '.tgz', '.tar.zst', '.tzst', '.zip']
+export const DEFAULT_MAX_TOTAL_BYTES = 2 * 1024 * 1024 * 1024
+export const DEFAULT_MAX_FILES = 20_000
+const MAX_FILE_BYTES = 1024 * 1024 * 1024
+const EXEC_OPTS = { maxBuffer: 64 * 1024 * 1024, timeout: 300_000 }
+
+export function archiveFormat(p) {
+  const lower = String(p).toLowerCase()
+  if (lower.endsWith('.tar.gz') || lower.endsWith('.tgz')) return 'tar.gz'
+  if (lower.endsWith('.tar.zst') || lower.endsWith('.tzst')) return 'tar.zst'
+  if (lower.endsWith('.tar')) return 'tar'
+  if (lower.endsWith('.zip')) return 'zip'
+  return null
+}
+
+export function isArchive(p) {
+  return archiveFormat(p) !== null
+}
+
+// ── 路径安全（zip-slip 防护） ─────────────────────────────────────────────
+
+function safeJoin(destDir, name) {
+  const raw = String(name ?? '')
+  if (raw.includes('\0')) throw new Error(`检测到不安全的归档条目（含 NUL）: ${raw}`)
+  if (raw.startsWith('/') || /^[A-Za-z]:[\\/]/.test(raw)) {
+    throw new Error(`检测到不安全的归档条目（绝对路径）: ${raw}`)
+  }
+  const segments = raw.split(/[\\/]+/).filter(s => s !== '' && s !== '.')
+  if (segments.includes('..')) throw new Error(`检测到不安全的归档条目（路径逃逸）: ${raw}`)
+  if (segments.length === 0) throw new Error(`检测到空的归档条目名: ${raw}`)
+  if (segments.some(s => s.length > 255)) throw new Error(`检测到超长条目名: ${raw.slice(0, 80)}…`)
+  const target = path.resolve(destDir, ...segments)
+  const base = path.resolve(destDir)
+  if (target !== base && !target.startsWith(base + path.sep)) {
+    throw new Error(`检测到不安全的归档条目（越界）: ${raw}`)
+  }
+  return target
+}
+
+// ── 纯 JS 流式 tar 解析（ustar / pax / GNU longname） ─────────────────────
+
+function parseOctal(field) {
+  const text = field.toString('latin1').replace(/[\0 ]/g, '')
+  if (text === '') return 0
+  const value = parseInt(text, 8)
+  return Number.isNaN(value) ? 0 : value
+}
+
+/** 解析 pax 扩展头（`%d key=value\n` 记录序列），提取 path 等覆盖项。 */
+function parsePax(buf) {
+  const out = {}
+  let offset = 0
+  while (offset < buf.length) {
+    const sp = buf.indexOf(' ', offset)
+    if (sp < 0) break
+    const len = parseInt(buf.subarray(offset, sp).toString('latin1'), 10)
+    if (!Number.isFinite(len) || len <= 0 || offset + len > buf.length) break
+    const record = buf.subarray(sp + 1, offset + len).toString('utf8')
+    const eq = record.indexOf('=')
+    if (eq > 0) out[record.slice(0, eq)] = record.slice(eq + 1).replace(/\n$/, '')
+    offset += len
+  }
+  return out
+}
+
+const padBytesFor = size => (512 - (size % 512)) % 512
+
+/**
+ * 从 tar 字节流解包到 destDir。流式消费（for-await 天然背压），文件内容
+ * 逐段落盘，不整包进内存。truncated 归档 / 链接条目 / 越限均抛错。
+ *
+ * 状态机：header（512B 头）→ payload（size 字节）→ padding（512 对齐填充，
+ * padRemain 显式记录，未到齐不会误当下一头）→ header …
+ */
+export async function extractTar(source, destDir, opts = {}) {
+  const maxTotal = opts.maxTotalBytes ?? DEFAULT_MAX_TOTAL_BYTES
+  const maxFiles = opts.maxFiles ?? DEFAULT_MAX_FILES
+  fs.mkdirSync(destDir, { recursive: true })
+
+  let buf = Buffer.alloc(0)
+  let total = 0
+  let files = 0
+  let pendingName = null // GNU 'L' 长文件名
+  let paxPath = null // pax 'x' 的 path 覆盖
+  let sawAny = false
+  let done = false
+  let payload = null // {kind,size,written,ws?,chunks?} | null=等 header
+  let padRemain = 0 // 载荷后的对齐填充剩余字节
+  const flushes = [] // 每个写流的 finished promise：返回前必须等全部落盘
+
+  const take = n => { const out = buf.subarray(0, n); buf = buf.subarray(n); return out }
+
+  /** 处理恰好一个 512B 头；返回 false 表示还差数据。 */
+  function headerOne() {
+    if (buf.length < 512) return false
+    const header = take(512)
+    if (header.every(b => b === 0)) { done = true; return false } // 结尾空块
+    sawAny = true
+    const size = parseOctal(header.subarray(124, 136))
+    const typeflag = String.fromCharCode(header[156] || 0x30)
+    let name = header.subarray(0, 100).toString('utf8').replace(/\0.*$/s, '')
+    const magic = header.subarray(257, 263).toString('latin1')
+    if (magic.startsWith('ustar')) {
+      const prefix = header.subarray(345, 500).toString('utf8').replace(/\0.*$/s, '')
+      if (prefix !== '') name = `${prefix}/${name}`
+    }
+    if (pendingName !== null) { name = pendingName; pendingName = null }
+    if (paxPath !== null) { name = paxPath; paxPath = null }
+
+    if (typeflag === 'L') { payload = { kind: 'longname', size, written: 0, chunks: [] }; return true }
+    if (typeflag === 'K' || typeflag === 'g') { payload = { kind: 'skip', size, written: 0 }; return true }
+    if (typeflag === 'x') { payload = { kind: 'pax', size, written: 0, chunks: [] }; return true }
+    if (typeflag === '1' || typeflag === '2') {
+      throw new Error(`检测到链接条目（${typeflag === '2' ? '符号链接' : '硬链接'}），已拒绝: ${name}`)
+    }
+    if (typeflag === '5' || name.endsWith('/')) {
+      if (name !== '' && name !== './') fs.mkdirSync(safeJoin(destDir, name), { recursive: true })
+      if (++files > maxFiles) throw new Error(`归档条目数超过上限 ${maxFiles}`)
+      return true
+    }
+    if (typeflag === '0' || typeflag === '\0' || typeflag === '7') {
+      if (size > MAX_FILE_BYTES) throw new Error(`单文件超过 1GiB 上限: ${name}`)
+      total += size
+      if (total > maxTotal) throw new Error(`解压总量超过上限 ${(maxTotal / 1024 / 1024).toFixed(0)}MiB`)
+      if (++files > maxFiles) throw new Error(`归档条目数超过上限 ${maxFiles}`)
+      const target = safeJoin(destDir, name)
+      fs.mkdirSync(path.dirname(target), { recursive: true })
+      if (size === 0) { fs.writeFileSync(target, Buffer.alloc(0)); return true }
+      const ws = fs.createWriteStream(target)
+      flushes.push(finished(ws))
+      payload = { kind: 'file', size, written: 0, ws }
+      return true
+    }
+    // 其余类型（设备/FIFO 等）：跳过载荷
+    if (size === 0) return true
+    payload = { kind: 'skip', size, written: 0 }
+    return true
+  }
+
+  /** 载荷推进一档；返回 false 表示还需更多数据（pump 须退出等下一块）。 */
+  function payloadStep() {
+    if (buf.length === 0) return false
+    const need = payload.size - payload.written
+    const give = take(Math.min(need, buf.length))
+    payload.written += give.length
+    if (payload.kind === 'file') payload.ws.write(give)
+    else if (payload.kind === 'longname' || payload.kind === 'pax') payload.chunks.push(give)
+    if (payload.written < payload.size) return false
+
+    const { kind, size, ws, chunks } = payload
+    if (kind === 'file') ws.end()
+    else if (kind === 'longname') {
+      pendingName = Buffer.concat(chunks).toString('utf8').replace(/\0.*$/s, '').trim()
+    } else if (kind === 'pax') {
+      const overrides = parsePax(Buffer.concat(chunks))
+      if (typeof overrides.path === 'string' && overrides.path !== '') paxPath = overrides.path
+    }
+    payload = null
+    padRemain = padBytesFor(size)
+    return true
+  }
+
+  let pumpIters = 0
+  function pump() {
+    for (;;) {
+      if (++pumpIters > 5_000_000) {
+        throw new Error(`tar 解析状态机失控（迭代超限）：state=${payload?.kind ?? 'header'} written=${payload?.written} size=${payload?.size} padRemain=${padRemain} bufLen=${buf.length} done=${done}`)
+      }
+      if (done) return
+      if (padRemain > 0) {
+        if (buf.length === 0) return
+        const eat = Math.min(padRemain, buf.length)
+        take(eat)
+        padRemain -= eat
+        continue
+      }
+      if (payload === null) {
+        if (!headerOne()) return
+        continue
+      }
+      if (!payloadStep()) return
+    }
+  }
+
+  let backpressure = null
+  for await (const chunk of source) {
+    if (done) break
+    buf = buf.length ? Buffer.concat([buf, chunk]) : chunk
+    try {
+      pump()
+    } catch (error) {
+      if (payload?.kind === 'file') payload.ws.destroy()
+      throw error
+    }
+    while (backpressure) { await backpressure; backpressure = null }
+    if (payload?.kind === 'file') {
+      const ws = payload.ws
+      if (ws.writableLength > 1 << 20) {
+        backpressure = new Promise(resolve => ws.once('drain', resolve))
+      }
+    }
+  }
+  if (payload !== null) {
+    if (payload.kind === 'file') payload.ws.end()
+    throw new Error('归档在条目载荷中途结束（文件损坏或下载不完整）')
+  }
+  if (!sawAny) throw new Error('不是有效的 tar 归档（未发现任何条目头）')
+  // 所有写流真正落盘后才算解包完成（end() 只入队，flush 是异步的）
+  await Promise.all(flushes)
+}
+
+// ── zip（系统工具，execFile 无 shell） ─────────────────────────────────────
+
+function execFilePromise(cmd, args) {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, EXEC_OPTS, (error, stdout, stderr) => {
+      if (error) reject(Object.assign(error, { stderr: String(stderr || '') }))
+      else resolve(String(stdout))
+    })
+  })
+}
+
+function assertSafeEntryNames(listing) {
+  for (const raw of listing.split('\n')) {
+    const name = raw.trim()
+    if (!name) continue
+    if (name.startsWith('/') || name.split(/[\\/]+/).includes('..') || name.includes('\0')) {
+      throw new Error(`检测到不安全的归档条目（路径逃逸）: ${name}`)
+    }
+  }
+}
+
+async function extractZip(archivePath, destDir) {
+  fs.mkdirSync(destDir, { recursive: true })
+  let listing
+  try {
+    listing = await execFilePromise('unzip', ['-Z1', archivePath])
+  } catch (eUnzip) {
+    try {
+      listing = await execFilePromise('tar', ['-tf', archivePath])
+    } catch {
+      throw new Error(`无法读取 zip 包（需要系统 unzip 或 tar）: ${eUnzip.message}`)
+    }
+    assertSafeEntryNames(listing)
+    await execFilePromise('tar', ['-xf', archivePath, '-C', destDir])
+    return
+  }
+  assertSafeEntryNames(listing)
+  await execFilePromise('unzip', ['-o', '-q', archivePath, '-d', destDir])
+}
+
+// ── 入口 ─────────────────────────────────────────────────────────────────
+
+/** zlib 是否带原生 zstd 流（Node ≥22.15）。 */
+function zstdDecodeStream(archivePath) {
+  if (typeof zlib.createZstdDecompress === 'function') return null // 由调用方 pipe
+  // 回退：系统 zstd -dc 的 stdout 包成 Readable
+  const child = spawn('zstd', ['-dc', String(archivePath)], { stdio: ['ignore', 'pipe', 'pipe'] })
+  child.stderr.resume()
+  child.on('error', () => {}); // 流错误经 stdout 'error' 传出
+  return Readable.from(child.stdout)
+}
+
+/**
+ * 解包 OneTree 一键日志压缩包到 destDir（应为空目录）。
+ * 返回 { format }；不支持的扩展名 / 解包失败 / 安全违规均抛错。
+ */
+export async function extractArchive(archivePath, destDir, opts = {}) {
+  const format = archiveFormat(archivePath)
+  if (format === null) {
+    throw new Error(`不支持的压缩格式（支持 ${ARCHIVE_EXTS.join(' / ')}）: ${path.basename(archivePath)}`)
+  }
+  if (format === 'zip') {
+    await extractZip(String(archivePath), destDir)
+    return { format }
+  }
+  let stream
+  if (format === 'tar.zst') {
+    const fallback = zstdDecodeStream(archivePath)
+    if (fallback) {
+      stream = fallback
+    } else {
+      stream = fs.createReadStream(String(archivePath)).pipe(zlib.createZstdDecompress())
+    }
+  } else {
+    stream = fs.createReadStream(String(archivePath))
+    if (format === 'tar.gz') stream = stream.pipe(zlib.createGunzip())
+  }
+  await extractTar(stream, destDir, opts)
+  return { format }
+}