@perrylink/dsh-skill-pack-security-provider 2.0.0 → 2.0.1

package/lib/vet/config.js

@@ -0,0 +1,36 @@
+/**
+ * Resolved plugin_vet configuration: plain values with defaults applied.
+ *
+ * The Schemastery schema lives in `../index.ts` next to the skills-provider
+ * config; this module only consumes the already-validated plain object so the
+ * engine never depends on Schemastery at runtime.
+ *
+ * @module dsh-skill-pack-security/vet/config
+ */
+export const VET_DEFAULTS = {
+    enable: true,
+    timeoutMs: 15000,
+    maxFiles: 800,
+    maxFileBytes: 256 * 1024,
+    maxExtractBytes: 64 * 1024 * 1024,
+    maxDepNodes: 600,
+    maxFindingsPerCheck: 12,
+    userAgent: 'dsh-skill-pack-security/2.0.0 (+https://github.com/PerryLink/dsh-skill-pack-security)',
+    gate: { policy: 'warn' },
+};
+/** Merge raw config over the defaults (the schema already validated shape/ranges). */
+export function resolveVetConfig(raw) {
+    if (raw === undefined)
+        return VET_DEFAULTS;
+    return {
+        enable: raw.enable ?? VET_DEFAULTS.enable,
+        timeoutMs: raw.timeoutMs ?? VET_DEFAULTS.timeoutMs,
+        maxFiles: raw.maxFiles ?? VET_DEFAULTS.maxFiles,
+        maxFileBytes: raw.maxFileBytes ?? VET_DEFAULTS.maxFileBytes,
+        maxExtractBytes: raw.maxExtractBytes ?? VET_DEFAULTS.maxExtractBytes,
+        maxDepNodes: raw.maxDepNodes ?? VET_DEFAULTS.maxDepNodes,
+        maxFindingsPerCheck: raw.maxFindingsPerCheck ?? VET_DEFAULTS.maxFindingsPerCheck,
+        userAgent: raw.userAgent ?? VET_DEFAULTS.userAgent,
+        gate: { policy: raw.gate?.policy ?? VET_DEFAULTS.gate.policy },
+    };
+}

package/lib/vet/engine.js

@@ -0,0 +1,236 @@
+/**
+ * plugin_vet engine: resolves a target, runs the eight checks, scores the five
+ * risk dimensions, applies the installation gate, and returns the canonical
+ * report. Pure orchestration — all side effects live in `source.ts`/`fetch.ts`
+ * and every value produced here is JSON-safe and redacted.
+ *
+ * @module dsh-skill-pack-security/vet/engine
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ALL_CHECK_IDS } from './vocabulary.js';
+import { runChecks } from './checks.js';
+import { parseLockfile, parseManifest } from './manifest.js';
+import { resolveTarget } from './source.js';
+import { VetFetchError } from './fetch.js';
+import { CHECK_NAME, SKILL_REF, T } from './skills.js';
+/** Engine-level failure: target unusable (not found, offline, budget). */
+export class VetTargetError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'VetTargetError';
+    }
+}
+/** Parse and validate the requested check subset. */
+function requestedChecks(args) {
+    if (args.checks === undefined || args.checks.length === 0)
+        return [...ALL_CHECK_IDS];
+    const selected = [];
+    for (const raw of args.checks) {
+        const id = raw.trim();
+        if (!ALL_CHECK_IDS.includes(id)) {
+            throw new VetTargetError(`unknown check "${raw}"; available: ${ALL_CHECK_IDS.join(', ')}`);
+        }
+        if (!selected.includes(id))
+            selected.push(id);
+    }
+    return selected;
+}
+/** Read a local git HEAD commit without spawning git (best effort). */
+async function readLocalHead(root) {
+    try {
+        const head = (await readFile(join(root, '.git', 'HEAD'), 'utf8')).trim();
+        const direct = /^[0-9a-f]{40}$/i.exec(head);
+        if (direct !== null)
+            return direct[0];
+        const refMatch = /^ref:\s*(.+)$/.exec(head);
+        if (refMatch === null)
+            return '';
+        const ref = (await readFile(join(root, '.git', refMatch[1]), 'utf8')).trim();
+        return /^[0-9a-f]{40}$/i.test(ref) ? ref : '';
+    }
+    catch {
+        return '';
+    }
+}
+const WEIGHTS = { license: 0.25, source: 0.2, dependencies: 0.15, 'build-scripts': 0.25, maintenance: 0.15 };
+/**
+ * Recursively drop `undefined` properties from plain objects/arrays so the
+ * canonical value is always lossless JSON (the tool runtime rejects anything
+ * less). Engine internals may carry optional undefined fields; only this
+ * projection is surfaced.
+ */
+function jsonClean(value) {
+    if (Array.isArray(value))
+        return value.map(jsonClean);
+    if (typeof value === 'object' && value !== null && !(value instanceof Date)) {
+        const out = {};
+        for (const [key, child] of Object.entries(value)) {
+            if (child === undefined)
+                continue;
+            out[key] = jsonClean(child);
+        }
+        return out;
+    }
+    return value;
+}
+/** Dimension → checks contributing to it. */
+const DIMENSION_CHECKS = {
+    license: ['license'],
+    source: ['source', 'commit-lock'],
+    dependencies: ['sbom'],
+    'build-scripts': ['install-scripts', 'network-exfil', 'obfuscation'],
+    maintenance: ['maintenance'],
+};
+/** Build the five-dimension scorecard from executed checks. */
+function scoreDimensions(checks) {
+    const byId = new Map(checks.map(check => [check.id, check]));
+    const dims = {};
+    for (const dim of Object.keys(DIMENSION_CHECKS)) {
+        const contributors = DIMENSION_CHECKS[dim].map(id => byId.get(id)).filter((check) => check !== undefined);
+        const run = contributors.filter(check => check.verdict !== 'skip');
+        if (run.length === 0) {
+            dims[dim] = 60; // unknown: neither penalize nor credit
+            continue;
+        }
+        const weighted = run.map(check => {
+            if (dim === 'build-scripts') {
+                const factor = check.id === 'install-scripts' ? 0.4 : check.id === 'network-exfil' ? 0.35 : 0.25;
+                return check.score * factor;
+            }
+            if (dim === 'source') {
+                return check.score * (check.id === 'source' ? 0.5 : 0.5);
+            }
+            return check.score;
+        });
+        // build-scripts and source already sum their weight factors to 1; other
+        // dimensions average their contributors.
+        const divisor = dim === 'build-scripts' || dim === 'source' ? 1 : weighted.length;
+        dims[dim] = Math.round(weighted.reduce((a, b) => a + b, 0) / divisor);
+    }
+    const overall = Math.round(Object.keys(dims).reduce((sum, dim) => sum + dims[dim] * WEIGHTS[dim], 0));
+    return {
+        license: dims.license,
+        source: dims.source,
+        dependencies: dims.dependencies,
+        'build-scripts': dims['build-scripts'],
+        maintenance: dims.maintenance,
+        overall,
+    };
+}
+/** Run the whole pipeline for one tool call. */
+export async function runVet(args, config, lang, signal) {
+    const ids = requestedChecks(args);
+    const policy = args.policy === undefined || args.policy === 'inherit' ? config.gate.policy : args.policy;
+    const now = Date.now();
+    const fetchedAt = new Date(now).toISOString();
+    let resolved;
+    try {
+        resolved = await resolveTarget(args.target, config, signal);
+    }
+    catch (error) {
+        if (error instanceof VetFetchError) {
+            // Offline/timeout: every check skips with the concrete reason.
+            const skipReason = `${T[lang].offline}: ${error.message}`;
+            const checks = ALL_CHECK_IDS.map(id => ({
+                id,
+                name: CHECK_NAME[lang][id],
+                verdict: 'skip',
+                skipReason,
+                score: 60,
+                findings: [],
+                truncatedFindings: false,
+                skill: SKILL_REF[id],
+            }));
+            return jsonClean({
+                kind: 'vet-report',
+                target: { raw: args.target, kind: 'github-repo', resolved: args.target, ref: '' },
+                fetchedAt,
+                checks,
+                scores: scoreDimensions(checks),
+                verdict: 'skip',
+                gate: { policy, applied: false, blocked: false },
+                sbom: { lockfile: null, directDependencies: 0, directDevDependencies: 0, packages: [], truncated: false, totalPackages: 0, unpinned: [] },
+                budget: { filesScanned: 0, filesSkipped: 0, bytesScanned: 0, truncated: false, truncatedReason: skipReason },
+                followupSkills: ['security-audit'],
+            });
+        }
+        throw error;
+    }
+    if (resolved.files.length === 0 && resolved.budget.truncatedReason !== undefined) {
+        throw new VetTargetError(resolved.budget.truncatedReason);
+    }
+    const manifest = parseManifest(resolved.files);
+    const lock = parseLockfile(resolved.files);
+    const localHead = resolved.kind === 'local-path' ? await readLocalHead(resolved.resolved) : '';
+    const results = runChecks({
+        files: resolved.files,
+        manifest,
+        lock,
+        github: resolved.github,
+        npm: resolved.npm,
+        target: resolved,
+        config,
+        lang,
+        localHead,
+        now,
+    }, ids);
+    const checks = results.map(result => result.check);
+    const sbom = results.find(result => result.sbom !== undefined)?.sbom;
+    // Unrequested checks are absent; the scorecard treats them as neutral.
+    const scores = scoreDimensions(checks);
+    let verdict = 'pass';
+    if (checks.some(check => check.verdict === 'fail'))
+        verdict = 'fail';
+    else if (scores.overall < 60)
+        verdict = 'warn';
+    const gateApplied = verdict === 'fail';
+    const blocked = gateApplied && policy === 'deny';
+    const followupSkills = new Set(['security-audit']);
+    for (const check of checks) {
+        for (const finding of check.findings) {
+            if (finding.level !== 'fail' && finding.level !== 'warn')
+                continue;
+            const skillName = finding.skill.split(' ')[0];
+            if (skillName !== '')
+                followupSkills.add(skillName);
+        }
+    }
+    const budget = { ...resolved.budget };
+    if (resolved.files.length === 0) {
+        budget.truncated = true;
+        budget.truncatedReason = resolved.budget.truncatedReason ?? 'target contained no scannable files';
+    }
+    return jsonClean({
+        kind: 'vet-report',
+        target: {
+            raw: args.target,
+            kind: resolved.kind,
+            resolved: resolved.resolved,
+            ref: resolved.ref,
+        },
+        fetchedAt,
+        checks,
+        scores,
+        verdict,
+        gate: {
+            policy,
+            applied: gateApplied,
+            blocked,
+            reason: blocked
+                ? lang === 'zh' ? 'verdict=fail 且门禁策略为 deny' : 'verdict=fail with deny gate policy'
+                : undefined,
+        },
+        sbom: sbom ?? {
+            lockfile: null,
+            directDependencies: 0,
+            directDevDependencies: 0,
+            packages: [],
+            truncated: false,
+            totalPackages: 0,
+            unpinned: [],
+        },
+        budget,
+        followupSkills: [...followupSkills],
+    });
+}

package/lib/vet/fetch.js

@@ -0,0 +1,124 @@
+/**
+ * Zero-dependency network access for the scan engine.
+ *
+ * Only `globalThis.fetch` (Node 18+ built-in undici) is used. Every request:
+ *  - honors the caller's AbortSignal AND a cooperative timeout
+ *    (`AbortSignal.any` + `AbortSignal.timeout`), so a hung upstream can never
+ *    stall a session;
+ *  - enforces a hard byte cap while reading the body (stream-counted, no
+ *    unbounded buffering);
+ *  - sends a fixed User-Agent and never attaches credentials.
+ *
+ * @module dsh-skill-pack-security/vet/fetch
+ */
+/** A network failure — always surfaced as a check `skip`, never as a finding. */
+export class VetFetchError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.name = 'VetFetchError';
+        this.kind = kind;
+    }
+}
+/** Compose the caller signal with the cooperative timeout. */
+function combinedSignal(options) {
+    const timeout = AbortSignal.timeout(options.timeoutMs);
+    return options.signal === undefined ? timeout : AbortSignal.any([options.signal, timeout]);
+}
+/** Map a fetch rejection into a classified VetFetchError. */
+function classify(error) {
+    if (error instanceof VetFetchError)
+        return error;
+    if (error instanceof Error && error.name === 'TimeoutError') {
+        return new VetFetchError('timeout', `network request timed out: ${error.message}`);
+    }
+    if (error instanceof Error && error.name === 'AbortError') {
+        return new VetFetchError('aborted', 'network request was aborted');
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return new VetFetchError('network', `network request failed: ${message}`);
+}
+/** Fetch a text body with size cap. */
+export async function fetchText(url, options) {
+    let response;
+    try {
+        response = await fetch(url, {
+            signal: combinedSignal(options),
+            headers: { 'user-agent': options.userAgent, accept: 'application/json, text/plain, */*' },
+            redirect: 'follow',
+        });
+    }
+    catch (error) {
+        throw classify(error);
+    }
+    if (!response.ok) {
+        throw new VetFetchError('http', `HTTP ${response.status} for ${url}`);
+    }
+    const reader = response.body?.getReader();
+    if (reader === undefined) {
+        return { status: response.status, text: await response.text(), truncated: false };
+    }
+    const chunks = [];
+    let bytes = 0;
+    let truncated = false;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            bytes += value.byteLength;
+            if (bytes > options.maxBytes) {
+                truncated = true;
+                await reader.cancel();
+                break;
+            }
+            chunks.push(value);
+        }
+    }
+    catch (error) {
+        throw classify(error);
+    }
+    const buffer = Buffer.concat(chunks);
+    return { status: response.status, text: buffer.toString('utf8'), truncated };
+}
+/** Fetch a binary body with size cap (tarballs). */
+export async function fetchBuffer(url, options) {
+    let response;
+    try {
+        response = await fetch(url, {
+            signal: combinedSignal(options),
+            headers: { 'user-agent': options.userAgent },
+            redirect: 'follow',
+        });
+    }
+    catch (error) {
+        throw classify(error);
+    }
+    if (!response.ok) {
+        throw new VetFetchError('http', `HTTP ${response.status} for ${url}`);
+    }
+    const reader = response.body?.getReader();
+    if (reader === undefined) {
+        const buffer = new Uint8Array(await response.arrayBuffer());
+        return { status: response.status, buffer, truncated: buffer.byteLength > options.maxBytes };
+    }
+    const chunks = [];
+    let bytes = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            bytes += value.byteLength;
+            if (bytes > options.maxBytes) {
+                await reader.cancel();
+                throw new VetFetchError('too-large', `response exceeds the ${options.maxBytes} byte cap`);
+            }
+            chunks.push(value);
+        }
+    }
+    catch (error) {
+        throw classify(error);
+    }
+    return { status: response.status, buffer: Buffer.concat(chunks), truncated: false };
+}