@patrickdk77/office-defuse 0.1.0 → 0.1.1

package/dist/word.js

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wordRules = wordRules;
+const errors_1 = require("./errors");
+const fields_1 = require("./fields");
+const io_1 = require("./io");
+const oleobj_1 = require("./oleobj");
+const types_1 = require("./types");
+/** wIdent of Word 97 and later, and of Word 6.0 and 95 (MS-DOC 2.5.2). */
+const WORD8 = 0xa5ec;
+const WORD6 = 0xa5dc;
+/** FibRgFcLcb97 pairs (MS-DOC 2.5.6): the attached template's table and the piece table. */
+const FC_STTBF_ASSOC = 32;
+const FC_CLX = 33;
+/** In a Word 6.0 or 95 FIB, the length of the macro table that holds WordBasic macros. Word writes 2 for an empty one. */
+const WORD6_MACROS = 0x11c;
+/** Text is read in pieces of at most this many characters. */
+const PIECE = 65536;
+const u16 = (b, at) => b[at] | (b[at + 1] << 8);
+const u32 = (b, at) => (b[at] | (b[at + 1] << 8) | (b[at + 2] << 16) | (b[at + 3] << 24)) >>> 0;
+/**
+ * Inspects a Word 6.0 to 2003 document: its FIB, whether it is encrypted, the fields in its text and the template it
+ * attaches. Returns whether it is a template, or undefined for an `optional` stream that holds no FIB.
+ */
+async function wordRules(ctx, cfb, stream, optional = false) {
+    const source = cfb.source(stream);
+    const fib = await source.read(0, 1024);
+    const ident = fib.length >= 32 ? u16(fib, 0) : 0;
+    if (ident !== WORD8 && ident !== WORD6) {
+        if (optional)
+            return undefined;
+        throw new errors_1.StopError(types_1.OfficeCategory.Package, types_1.OfficeDetail.Unrecognized, 'The WordDocument stream does not start with a Word FIB', { reason: 'a WordDocument stream without a FIB' });
+    }
+    const flags = u16(fib, 10);
+    // fEncrypted, set for both RC4 encryption and XOR obfuscation.
+    if (flags & 0x0100)
+        throw new errors_1.StopError(types_1.OfficeCategory.Encrypted, types_1.OfficeDetail.PasswordRequired, 'The document is encrypted', { stream: stream.name });
+    const location = stream.name;
+    const fields = new fields_1.FieldStack(ctx, location);
+    // Word marks a field's start, separator and end with 0x13, 0x14 and 0x15 in the text. Other control characters in
+    // a field's code, such as the 0x01 of a hyperlink's data, are not part of what it says.
+    const text = (s) => {
+        for (const ch of s) {
+            if (ch === '\x13')
+                fields.begin();
+            else if (ch === '\x14')
+                fields.separate();
+            else if (ch === '\x15')
+                fields.end();
+            else if (fields.inCode && (ch >= ' ' || ch === '\t'))
+                fields.text(ch);
+        }
+    };
+    const reader = new io_1.Reader(source, stream.size, 65536, 8);
+    if (ident === WORD6) {
+        // Word 6.0 and 95 keep their text as 8-bit characters from fcMin to fcMac. A file saved fast adds pieces to the
+        // end, and this reads every byte between, as msodde does.
+        const from = u32(fib, 0x18);
+        const to = Math.min(u32(fib, 0x1c), stream.size);
+        for (let at = from; at < to; at += PIECE) {
+            (0, errors_1.checkTime)(ctx.settings.deadline);
+            text(latin(await reader.read(at, Math.min(PIECE, to - at))));
+        }
+        if (fib.length >= WORD6_MACROS + 4 && u32(fib, WORD6_MACROS) > 2)
+            ctx.report(types_1.OfficeCategory.Macro, types_1.OfficeDetail.WordBasic, location, { stream: location, bytes: u32(fib, WORD6_MACROS) });
+    }
+    else {
+        const pairs = fcLcb(fib);
+        const table = cfb.child(cfb.root, flags & 0x0200 ? '1Table' : '0Table');
+        if (table?.kind === 'stream') {
+            const tableSource = cfb.source(table);
+            const clx = pairs[FC_CLX];
+            if (clx && clx.lcb > 0 && clx.fc + clx.lcb <= table.size) {
+                for (const p of pieces(await tableSource.read(clx.fc, clx.lcb))) {
+                    for (let cp = 0; cp < p.length; cp += PIECE) {
+                        (0, errors_1.checkTime)(ctx.settings.deadline);
+                        const n = Math.min(PIECE, p.length - cp);
+                        if (p.compressed)
+                            text(latin(await reader.read(p.fc + cp, n)));
+                        else
+                            text((0, oleobj_1.utf16)(await reader.read(p.fc + cp * 2, n * 2)));
+                    }
+                }
+            }
+            const assoc = pairs[FC_STTBF_ASSOC];
+            if (assoc && assoc.lcb > 0 && assoc.fc + assoc.lcb <= table.size) {
+                // The attached template is string 1 of SttbfAssoc (MS-DOC 2.9.271).
+                const template = sttb(await tableSource.read(assoc.fc, Math.min(assoc.lcb, 65536)))[1] ?? '';
+                if (template.trim())
+                    ctx.external(types_1.OfficeDetail.Template, template, location, { source: 'SttbfAssoc' }, 'template');
+            }
+        }
+    }
+    fields.finish();
+    return { template: (flags & 1) === 1 };
+}
+/** The fc and lcb pairs of a Word 97 FIB, after its variable-length arrays of 16- and 32-bit values. */
+function fcLcb(fib) {
+    const r = new oleobj_1.ByteReader(fib);
+    const out = [];
+    return (0, oleobj_1.bounded)(() => {
+        r.skip(32);
+        r.skip(r.u16() * 2);
+        r.skip(r.u16() * 4);
+        const n = r.u16();
+        for (let i = 0; i < n; i++)
+            out.push({ fc: r.u32(), lcb: r.u32() });
+        return out;
+    }, () => out);
+}
+/** The pieces of a Clx (MS-DOC 2.9.38): where each run of text is, and whether it is stored 8 bits a character. */
+function pieces(clx) {
+    const r = new oleobj_1.ByteReader(clx);
+    const out = [];
+    return (0, oleobj_1.bounded)(() => {
+        // Prc entries of formatting come first, each with its size.
+        while (r.left > 0 && clx[r.pos] === 0x01) {
+            r.skip(1);
+            r.skip(r.u16());
+        }
+        if (r.u8() !== 0x02)
+            return out;
+        const lcb = r.u32();
+        const n = Math.floor((lcb - 4) / 12);
+        const plc = new oleobj_1.ByteReader(r.bytes(Math.min(lcb, r.left)));
+        const cps = [];
+        for (let i = 0; i <= n; i++)
+            cps.push(plc.u32());
+        for (let i = 0; i < n; i++) {
+            plc.skip(2);
+            const fc = plc.u32();
+            plc.skip(2);
+            const length = cps[i + 1] - cps[i];
+            if (length <= 0)
+                continue;
+            const compressed = (fc & 0x40000000) !== 0;
+            out.push({ fc: compressed ? (fc & 0x3fffffff) / 2 : fc, length, compressed });
+        }
+        return out;
+    }, () => []);
+}
+/** The strings of an STTB (MS-DOC 2.2.4), in 16-bit characters when it starts with 0xFFFF, as Word 97 writes one. */
+function sttb(b) {
+    const r = new oleobj_1.ByteReader(b);
+    const out = [];
+    return (0, oleobj_1.bounded)(() => {
+        const wide = r.u16() === 0xffff;
+        if (!wide)
+            r.pos = 0;
+        const count = r.u16();
+        const extra = r.u16();
+        for (let i = 0; i < count; i++) {
+            const n = wide ? r.u16() : r.u8();
+            out.push(wide ? (0, oleobj_1.utf16)(r.bytes(n * 2)) : latin(r.bytes(n)));
+            r.skip(extra);
+        }
+        return out;
+    }, () => out);
+}
+const latin = (b) => Buffer.from(b.buffer, b.byteOffset, b.byteLength).toString('latin1');

package/dist/xls.d.ts

@@ -0,0 +1,27 @@
+import { type BiffRecord } from './biff';
+import type { CfbEntry, CompoundFile } from './cfb';
+import { type RunContext } from './context';
+/** Turns an encrypted record body into its plain bytes. Without encryption the body is as stored. */
+export type Decrypt = (r: BiffRecord) => Uint8Array;
+/**
+ * Opens a workbook encrypted by its FILEPASS record, or says it cannot. Set by the decryption module, so this module
+ * reads workbooks without knowing how they are encrypted.
+ */
+export type Unlock = (ctx: RunContext, filePass: BiffRecord, stream: string) => Decrypt | Promise<Decrypt>;
+/**
+ * Inspects an Excel 5.0 to 2003 workbook stream. Excel reads the globals substream from the start of the stream,
+ * then each sheet from where its BoundSheet record says the sheet starts. The globals give the macro sheets, the
+ * names Excel runs as macros, and the DDE, OLE and workbook links. The sheets give shapes that run macros and
+ * hyperlinks. An encrypted workbook goes through `unlock`.
+ */
+export declare function excelRules(ctx: RunContext, cfb: CompoundFile, stream: CfbEntry, unlock: Unlock): Promise<{
+    template: boolean;
+    addIn: boolean;
+}>;
+/**
+ * A VirtualPath (MS-XLS 2.5.277) written out. One that starts with U+0001 is encoded: its control characters name a
+ * volume, the root, a folder, a step up, a URL's volume or Excel's startup folders.
+ */
+export declare function virtualPath(p: string): string;
+/** The target of an HLink record: its Hyperlink Object (MS-OSHARED 2.3.7.1) after the cell range and class id. */
+export declare function hyperlink(b: Uint8Array): string;

package/dist/xls.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.excelRules = excelRules;
+exports.virtualPath = virtualPath;
+exports.hyperlink = hyperlink;
+const biff_1 = require("./biff");
+const context_1 = require("./context");
+const errors_1 = require("./errors");
+const links_1 = require("./links");
+const oleobj_1 = require("./oleobj");
+const types_1 = require("./types");
+const STATES = ['visible', 'hidden', 'very hidden', 'hidden'];
+/**
+ * Inspects an Excel 5.0 to 2003 workbook stream. Excel reads the globals substream from the start of the stream,
+ * then each sheet from where its BoundSheet record says the sheet starts. The globals give the macro sheets, the
+ * names Excel runs as macros, and the DDE, OLE and workbook links. The sheets give shapes that run macros and
+ * hyperlinks. An encrypted workbook goes through `unlock`.
+ */
+async function excelRules(ctx, cfb, stream, unlock) {
+    const location = stream.name;
+    const records = new biff_1.RecordReader(cfb, stream, 0, ctx.settings.deadline);
+    const first = await records.next();
+    if (first?.type !== biff_1.R.bof || first.body.length < 4)
+        throw new errors_1.StopError(types_1.OfficeCategory.Package, types_1.OfficeDetail.Unrecognized, `The ${stream.name} stream does not start with a BOF record`, { reason: 'a workbook stream without a BOF record' });
+    const biff8 = (first.body[0] | (first.body[1] << 8)) === 0x0600;
+    let decrypt = r => r.body;
+    const sheets = [];
+    const books = [];
+    const flags = { template: false, addIn: false };
+    for (let r = await records.next(); r && r.type !== biff_1.R.eof; r = await records.next()) {
+        if (r.type === biff_1.R.filePass) {
+            decrypt = await unlock(ctx, r, location);
+            continue;
+        }
+        const body = decrypt(r);
+        if (r.type === biff_1.R.boundSheet)
+            sheets.push((0, biff_1.parseBoundSheet)(body, biff8));
+        else if (r.type === biff_1.R.template)
+            flags.template = true;
+        else if (r.type === biff_1.R.addIn)
+            flags.addIn = true;
+        else if (r.type === biff_1.R.lbl) {
+            const name = (0, biff_1.parseLbl)(body, biff8);
+            const auto = (0, biff_1.autoName)(name.name);
+            if (auto)
+                ctx.report(types_1.OfficeCategory.Macro, auto.onOpen ? types_1.OfficeDetail.EventOnOpen : types_1.OfficeDetail.Event, location, { event: auto.event, name: (0, context_1.clip)(name.name) });
+        }
+        else if (r.type === biff_1.R.supBook && body.length >= 4) {
+            const cch = body[2] | (body[3] << 8);
+            books.push({ ctab: body[0] | (body[1] << 8), cch, path: cch > 0 && cch <= 0xff ? (0, biff_1.xlString)(body, 4, cch).text : '', ole: false, dde: false });
+        }
+        else if (r.type === biff_1.R.externName && body.length >= 2 && books.length) {
+            // fOle and fOleLink mark an OLE object's name. Excel writes StdDocumentName with fOle beside the items of a DDE
+            // link, so a link with any DDE item is a DDE link.
+            if ((body[0] | (body[1] << 8)) & 0x18)
+                books[books.length - 1].ole = true;
+            else
+                books[books.length - 1].dde = true;
+        }
+    }
+    for (const b of books)
+        linkRules(ctx, b, location);
+    for (const s of sheets)
+        await sheetRules(ctx, cfb, stream, s, decrypt, location);
+    return flags;
+}
+/** A SupBook record, read as MS-XLS 2.4.271 and oletools tell its kinds apart. */
+function linkRules(ctx, b, location) {
+    if (b.cch === 0x401 || b.cch === 0x3a01 || b.path === ' ' || b.path === '\0' || !b.path)
+        return;
+    if (b.ctab === 0) {
+        // A DDE or OLE data source: the application or class, U+0003, and the topic or file.
+        const [application, topic = ''] = b.path.split('\x03');
+        if (b.ole && !b.dde) {
+            const data = { source: 'SupBook', className: (0, context_1.clip)(application) };
+            if (topic)
+                ctx.external(types_1.OfficeDetail.Object, topic, location, data, 'linked object');
+            else
+                ctx.report(types_1.OfficeCategory.External, types_1.OfficeDetail.Object, location, data);
+        }
+        else
+            ctx.report(types_1.OfficeCategory.Dde, types_1.OfficeDetail.Link, location, { application: (0, context_1.clip)(application), topic: (0, context_1.clip)(topic) });
+        return;
+    }
+    ctx.external(types_1.OfficeDetail.Workbook, virtualPath(b.path), location, { source: 'SupBook' }, 'external workbook');
+}
+/**
+ * A VirtualPath (MS-XLS 2.5.277) written out. One that starts with U+0001 is encoded: its control characters name a
+ * volume, the root, a folder, a step up, a URL's volume or Excel's startup folders.
+ */
+function virtualPath(p) {
+    if (p.charCodeAt(0) !== 1)
+        return p;
+    let out = '';
+    for (let i = 1; i < p.length; i++) {
+        const c = p.charCodeAt(i);
+        if (c === 1) {
+            // A drive letter, or @ for a UNC host. A U+0003 after it starts the path.
+            const v = p[i + 1] ?? '';
+            i++;
+            out += v === '@' ? '\\\\' : `${v}:`;
+        }
+        else if (c === 2 || c === 3)
+            out += '\\';
+        else if (c === 4)
+            out += '..\\';
+        // A long volume, such as a URL, after a character that counts it.
+        else if (c === 5)
+            i++;
+        else if (c >= 6 && c <= 8)
+            out += 'XLSTART\\';
+        else
+            out += p[i];
+    }
+    return out;
+}
+/** One sheet's substream, with any chart substreams inside it: Obj records that run macros, and hyperlinks. */
+async function sheetRules(ctx, cfb, stream, s, decrypt, location) {
+    const records = new biff_1.RecordReader(cfb, stream, s.position, ctx.settings.deadline);
+    const bof = await records.next();
+    if (bof?.type !== biff_1.R.bof || bof.body.length < 4)
+        return;
+    const bofType = bof.body[2] | (bof.body[3] << 8);
+    // The sheet's own BOF says what it is, and so does its BoundSheet record. Either one makes a macro sheet.
+    if (s.type === 1 || bofType === 0x0040)
+        ctx.report(types_1.OfficeCategory.Macro, types_1.OfficeDetail.XlmMacrosheet, location, { sheet: (0, context_1.clip)(s.name), state: STATES[s.state] });
+    let depth = 1;
+    for (let r = await records.next(); r && depth > 0; r = await records.next()) {
+        if (r.type === biff_1.R.bof)
+            depth++;
+        else if (r.type === biff_1.R.eof)
+            depth--;
+        else if (r.type === biff_1.R.obj) {
+            if (objMacro(decrypt(r)))
+                ctx.report(types_1.OfficeCategory.Macro, types_1.OfficeDetail.Link, location, { sheet: (0, context_1.clip)(s.name) });
+        }
+        else if (r.type === biff_1.R.hlink) {
+            const target = hyperlink(decrypt(r));
+            if (target.trim() && !(0, links_1.isFragment)(target))
+                ctx.link(target, location, { sheet: (0, context_1.clip)(s.name), source: 'HLink record' });
+        }
+    }
+}
+/** Whether an Obj record (MS-XLS 2.4.181) holds an FtMacro subrecord, the macro a click runs. */
+function objMacro(b) {
+    let at = 0;
+    while (at + 4 <= b.length) {
+        const ft = b[at] | (b[at + 1] << 8);
+        const cb = b[at + 2] | (b[at + 3] << 8);
+        // FtEnd ends the list, and FtLbsData's length does not count all its data, so the walk stops there.
+        if (ft === 0x00 || ft === 0x13)
+            return false;
+        if (ft === 0x04)
+            return cb > 0;
+        at += 4 + cb;
+    }
+    return false;
+}
+/** The target of an HLink record: its Hyperlink Object (MS-OSHARED 2.3.7.1) after the cell range and class id. */
+function hyperlink(b) {
+    const r = new oleobj_1.ByteReader(b);
+    return (0, oleobj_1.bounded)(() => {
+        r.skip(8 + 16 + 4);
+        const flags = r.u32();
+        const string = () => (0, oleobj_1.utf16)(r.bytes(r.u32() * 2)).replace(/\0+$/, '');
+        if (flags & 0x10)
+            string();
+        if (flags & 0x80)
+            string();
+        if (!(flags & 0x01))
+            return '';
+        return flags & 0x100 ? string() : (0, oleobj_1.readMoniker)(r).target;
+    }, () => '');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patrickdk77/office-defuse",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Inspect Office and OpenDocument files for VBA and Excel 4.0 macros, LibreOffice Basic and scripts, DDE, external templates and links, embedded OLE objects and ActiveX controls, and score the risk. Strict ZIP and XML readers, bounded memory, no runtime dependencies.",
   "license": "MIT",
   "author": "patrickdk77",
@@ -22,7 +22,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=18.0.0"
   },
   "scripts": {
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true});require('fs').rmSync('build-test',{recursive:true,force:true})\"",
@@ -84,7 +84,7 @@
     "@biomejs/biome": "^2.5.15",
     "@types/chai": "^5.2.3",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^22.20.5",
+    "@types/node": "^18.19.130",
     "c8": "^12.0.0",
     "chai": "^6.3.0",
     "husky": "^9.1.7",