@patrickdk77/office-defuse 0.0.0-stage → 0.1.1

package/dist/links.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAbsoluteTarget = exports.isInsidePackage = exports.isLocalTarget = exports.isFragment = void 0;
+exports.checkLink = checkLink;
+const types_1 = require("./types");
+const xml_1 = require("./xml");
+const IPV4 = /^\d{1,3}(\.\d{1,3}){3}$/;
+const SCHEME = /^([a-zA-Z][a-zA-Z0-9+.-]*):/;
+/** A browser drops control characters from a URL, and so does this before reading one. */
+const clean = (s) => s.replace(/\p{Cc}/gu, '').trim();
+const networkPrefix = (s) => s.startsWith('\\\\') || s.startsWith('//') || s.startsWith('\\/') || s.startsWith('/\\');
+/** A target that names the same document or a place in it. RFC 3986 reads an empty reference as the document itself. */
+const isFragment = (target) => {
+    const t = clean(target);
+    return t === '' || t.startsWith('#');
+};
+exports.isFragment = isFragment;
+/**
+ * Classifies a hyperlink target with pdf-defuse's checks, without the comparison of the target with the link's text.
+ * Call it only for targets that are more than a fragment. A target that holds the content of an external entity
+ * cannot be read, and reads as the empty string: a relative link, which is what pdf-defuse makes of a URI it cannot
+ * resolve.
+ */
+function checkLink(rawTarget) {
+    const uri = rawTarget.includes(xml_1.UNKNOWN) ? '' : clean(rawTarget);
+    const link = (detail, site) => ({ category: types_1.OfficeCategory.Link, detail, host: site });
+    if (networkPrefix(uri))
+        return link(types_1.OfficeDetail.NetworkPath);
+    const m = SCHEME.exec(uri);
+    if (!m)
+        return link(types_1.OfficeDetail.Relative);
+    const scheme = m[1].toLowerCase();
+    // C:\path is a drive, not a scheme.
+    if (scheme.length === 1)
+        return link(types_1.OfficeDetail.FileUrl);
+    if (scheme === 'javascript' || scheme === 'vbscript')
+        return link(types_1.OfficeDetail.ScriptUrl);
+    if (scheme === 'vnd.sun.star.script' || scheme === 'macro')
+        return { category: types_1.OfficeCategory.Macro, detail: types_1.OfficeDetail.Link };
+    if (scheme === 'data')
+        return link(types_1.OfficeDetail.DataUrl);
+    if (scheme === 'smb' || scheme === 'cifs' || scheme === 'afp' || scheme === 'nfs')
+        return link(types_1.OfficeDetail.NetworkPath);
+    if (scheme === 'file') {
+        let host = '';
+        try {
+            host = new URL(uri).hostname;
+        }
+        catch {
+            // A file: URL the parser refuses is read as a local path.
+        }
+        return link(host && host.toLowerCase() !== 'localhost' ? types_1.OfficeDetail.NetworkPath : types_1.OfficeDetail.FileUrl);
+    }
+    if (scheme === 'mailto') {
+        let addr = uri.slice(7).split('?')[0];
+        try {
+            addr = decodeURIComponent(addr);
+        }
+        catch {
+            // The address stays as written.
+        }
+        const domain = addr.includes('@') ? addr.slice(addr.lastIndexOf('@') + 1).toLowerCase() : '';
+        return link(hostVerdict(domain, domain) ?? types_1.OfficeDetail.Safe, domain);
+    }
+    if (scheme !== 'http' && scheme !== 'https')
+        return link(types_1.OfficeDetail.OtherScheme);
+    // The authority as written, before the URL parser normalizes it.
+    const rawAuth = uri
+        .slice(m[0].length)
+        .replace(/^[\\/]*/, '')
+        .split(/[/\\?#]/, 1)[0];
+    let parsed;
+    try {
+        parsed = new URL(uri);
+    }
+    catch {
+        return link(types_1.OfficeDetail.OtherScheme);
+    }
+    if (parsed.username || parsed.password || rawAuth.includes('@'))
+        return link(types_1.OfficeDetail.Credentials);
+    // The parser lowercases, punycodes and turns every IPv4 shorthand into dotted form, as browsers do.
+    const host = parsed.hostname.replace(/\.$/, '');
+    return link(hostVerdict(host, rawAuth) ?? types_1.OfficeDetail.Safe, host);
+}
+function hostVerdict(host, raw) {
+    if (!host)
+        return types_1.OfficeDetail.OtherScheme;
+    if (raw.includes('%'))
+        return types_1.OfficeDetail.EncodedHost;
+    if (host.startsWith('[') || IPV4.test(host))
+        return types_1.OfficeDetail.IpHost;
+    if (/^\d+$/.test(host) || /^0x[0-9a-f]+$/i.test(host))
+        return types_1.OfficeDetail.IpHost;
+    if (/\P{ASCII}/u.test(host) || host.split('.').some(label => label.startsWith('xn--')))
+        return types_1.OfficeDetail.LookalikeHost;
+    return undefined;
+}
+/**
+ * The target with every %XX turned into its character. A target can percent-encode its scheme, as `%73cript:` does in
+ * a CVE-2017-0199 sample, so the checks below hold a target local or inside the package only when both forms are.
+ */
+const decoded = (s) => s.replace(/%([0-9a-fA-F]{2})/g, (_, hex) => String.fromCharCode(Number.parseInt(hex, 16)));
+function local(t) {
+    if (networkPrefix(t))
+        return false;
+    const m = SCHEME.exec(t);
+    if (!m || m[1].length === 1)
+        return true;
+    if (m[1].toLowerCase() !== 'file')
+        return false;
+    try {
+        const host = new URL(t).hostname;
+        return !host || host.toLowerCase() === 'localhost';
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Whether a target outside the file is on this machine: a drive path, a file: URL without a host, an absolute path or
+ * a relative one. A UNC path, a file: URL with a host and every other scheme reach elsewhere, and so can a target that
+ * holds the content of an external entity.
+ */
+const isLocalTarget = (rawTarget) => !rawTarget.includes(xml_1.UNKNOWN) && local(clean(rawTarget)) && local(clean(decoded(rawTarget)));
+exports.isLocalTarget = isLocalTarget;
+function inside(t) {
+    if (t === '' || networkPrefix(t) || SCHEME.test(t) || t.startsWith('/') || t.startsWith('\\'))
+        return false;
+    let depth = 0;
+    for (const seg of t.split(/[/\\]/)) {
+        if (seg === '..')
+            depth--;
+        else if (seg !== '.' && seg !== '')
+            depth++;
+        if (depth < 0)
+            return false;
+    }
+    return true;
+}
+/** Whether an ODF reference names an entry inside the package: a relative path that does not climb out of it. */
+const isInsidePackage = (rawHref) => inside(clean(rawHref)) && inside(clean(decoded(rawHref)));
+exports.isInsidePackage = isInsidePackage;
+/** Whether an OOXML relationship target is not a part name, whatever TargetMode says: a scheme, a drive or a network path. */
+const isAbsoluteTarget = (rawTarget) => [rawTarget, decoded(rawTarget)].some(t => SCHEME.test(clean(t)) || t.startsWith('\\') || t.startsWith('//'));
+exports.isAbsoluteTarget = isAbsoluteTarget;

package/dist/msg.d.ts

@@ -0,0 +1,7 @@
+import { type CfbEntry, type CompoundFile } from './cfb';
+import { type RunContext } from './context';
+/**
+ * Inspects an Outlook message (MS-OXMSG): each attachment is reported with its name and type, and an attachment by
+ * reference with what it points to. An embedded message's own attachments are read as well.
+ */
+export declare function messageRules(ctx: RunContext, cfb: CompoundFile, message: CfbEntry, depth?: number): Promise<void>;

package/dist/msg.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.messageRules = messageRules;
+const cfb_1 = require("./cfb");
+const context_1 = require("./context");
+const oleobj_1 = require("./oleobj");
+const types_1 = require("./types");
+/** Property ids of an attachment (MS-OXPROPS). */
+const P = { method: 0x3705, longName: 0x3707, name: 0x3704, display: 0x3001, mime: 0x370e, data: 0x3701, longPath: 0x370d, path: 0x3708 };
+/** How an attachment holds its file (MS-OXCMSG 2.2.2.9): by value, by reference, embedded message, OLE object, web reference. */
+const METHODS = { 1: 'by value', 2: 'by reference', 3: 'by reference, resolved', 4: 'by reference only', 5: 'embedded message', 6: 'OLE object', 7: 'by web reference' };
+/** Embedded messages can hold messages in turn. Past this depth they are still reported, and not read further. */
+const MAX_DEPTH = 16;
+/**
+ * Inspects an Outlook message (MS-OXMSG): each attachment is reported with its name and type, and an attachment by
+ * reference with what it points to. An embedded message's own attachments are read as well.
+ */
+async function messageRules(ctx, cfb, message, depth = 0) {
+    for (const a of message.children) {
+        if (a.kind !== 'storage' || !/^__attach_version1\.0_#[0-9A-F]{8}$/i.test(a.name))
+            continue;
+        await attachmentRules(ctx, cfb, a, depth);
+    }
+}
+async function attachmentRules(ctx, cfb, a, depth) {
+    const location = (0, cfb_1.entryPath)(a);
+    const props = await properties(cfb, a);
+    const text = async (id) => {
+        for (const [type, decode] of [
+            ['001F', oleobj_1.utf16],
+            ['001E', oleobj_1.latin1],
+        ]) {
+            const s = a.children.find(c => c.kind === 'stream' && c.name.toUpperCase() === `__SUBSTG1.0_${id.toString(16).toUpperCase().padStart(4, '0')}${type}`);
+            if (s && s.size <= 65536)
+                return decode(await cfb.bytes(s)).replace(/\0+$/, '');
+        }
+        return '';
+    };
+    const method = props.get(P.method) ?? 0;
+    const name = (await text(P.longName)) || (await text(P.name)) || (await text(P.display));
+    const declaredType = await text(P.mime);
+    const dataId = `__SUBSTG1.0_${P.data.toString(16).toUpperCase()}`;
+    const data = a.children.find(c => c.name.toUpperCase().startsWith(dataId));
+    const info = { attachment: location, method: METHODS[method] ?? String(method) };
+    if (name)
+        info.name = (0, context_1.clip)(name);
+    if (declaredType)
+        info.type = (0, context_1.clip)(declaredType);
+    if (method >= 2 && method <= 4) {
+        const path = (await text(P.longPath)) || (await text(P.path));
+        if (path)
+            ctx.external(types_1.OfficeDetail.Other, path, location, { source: 'attachment by reference', ...(name ? { name: (0, context_1.clip)(name) } : {}) }, 'attachment');
+        return;
+    }
+    if (method === 7) {
+        const path = (await text(P.longPath)) || (await text(P.path));
+        if (path)
+            ctx.external(types_1.OfficeDetail.Other, path, location, { source: 'attachment by web reference', ...(name ? { name: (0, context_1.clip)(name) } : {}) }, 'attachment');
+        return;
+    }
+    if (!data)
+        return;
+    if (data.kind === 'stream') {
+        attachment(ctx, { name: name || undefined, declaredType: declaredType || undefined, size: data.size, location, depth: 1, source: cfb.source(data) }, info);
+        return;
+    }
+    // An embedded message or an OLE object is a storage of this file. The object rules read an object's storage, and
+    // an embedded message's attachments are read here.
+    info.size = 0;
+    if (method === 5)
+        info.type ??= 'application/vnd.ms-outlook';
+    ctx.report(types_1.OfficeCategory.Embedded, types_1.OfficeDetail.Attachment, location, info);
+    if (method === 5 && depth < MAX_DEPTH)
+        await messageRules(ctx, cfb, data, depth + 1);
+}
+/**
+ * The place every attached file passes, with what a contained file plugin needs to read it. office-defuse reports it;
+ * the family's router, once office-defuse has a plugin for it, is where it would be handed on.
+ */
+function attachment(ctx, file, info) {
+    ctx.report(types_1.OfficeCategory.Embedded, types_1.OfficeDetail.Attachment, file.location, { ...info, size: file.size });
+}
+/** The fixed-size values of a property stream (MS-OXMSG 2.4.2), by property id. An attachment's has an 8-byte header. */
+async function properties(cfb, storage) {
+    const out = new Map();
+    const s = storage.children.find(c => c.kind === 'stream' && c.name.toUpperCase() === '__PROPERTIES_VERSION1.0');
+    if (!s || s.size > 65536)
+        return out;
+    const b = await cfb.bytes(s);
+    for (let at = 8; at + 16 <= b.length; at += 16) {
+        const tag = (b[at] | (b[at + 1] << 8) | (b[at + 2] << 16) | (b[at + 3] << 24)) >>> 0;
+        // PT_LONG values sit in the first four bytes of the value.
+        if ((tag & 0xffff) === 0x0003)
+            out.set(tag >>> 16, (b[at + 8] | (b[at + 9] << 8) | (b[at + 10] << 16) | (b[at + 11] << 24)) >>> 0);
+    }
+    return out;
+}

package/dist/objects.d.ts

@@ -0,0 +1,42 @@
+import { type CfbEntry, type CompoundFile } from './cfb';
+import { type RunContext } from './context';
+import { type PackagedFile } from './oleobj';
+/** Equation Editor 3.0's ProgID, which rtfobj matches as a prefix. */
+export declare const isEquationClass: (name: string) => boolean;
+/** Reports what the reader of a compound file inside this one noted, at the place it sits. */
+export declare function nestedNotes(ctx: RunContext, cfb: CompoundFile, location: string): void;
+/**
+ * The rules every compound file gets: VBA projects, embedded objects and controls, wherever they sit in the tree.
+ * `prefix` names where the file sits when it is inside another, and `rootIsObject` says that its root is itself an
+ * OLE object's storage, as an object in a presentation or an RTF file is.
+ */
+export declare function compoundRules(ctx: RunContext, cfb: CompoundFile, prefix: string, rootIsObject: boolean): Promise<void>;
+/** What an OLE object's storage says about the object. */
+export interface ObjectInfo {
+    clsid: string;
+    progId?: string;
+    userType?: string;
+    /** An ActiveX control's storage, with the control's name. */
+    control: boolean;
+    controlName?: string;
+    linked: boolean;
+    /** What a linked object loads, or ''. */
+    target: string;
+    /** The target is a URL moniker's, which loads from outside however it is spelled. */
+    url: boolean;
+    /** A Packager object's file, held or linked to. */
+    pkg?: PackagedFile;
+    equation: boolean;
+}
+/** Reads an OLE object's storage: its class, its CompObj and OLE streams, and Packager's native data. */
+export declare function describeObject(cfb: CompoundFile, e: CfbEntry, _location: string): Promise<ObjectInfo>;
+/**
+ * Reports a linked object. A URL moniker's target loads from outside the file whatever its text looks like: a
+ * CVE-2017-0199 sample puts a character with a stray high byte where the colon of https: goes.
+ */
+export declare function linkedObject(ctx: RunContext, d: {
+    target: string;
+    url: boolean;
+}, location: string, data: Record<string, string>): void;
+/** What a finding shows of a Packager object's file: its name and paths, and its size when the object holds it. */
+export declare function packageData(p: PackagedFile): Record<string, string | number>;

package/dist/objects.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isEquationClass = void 0;
+exports.nestedNotes = nestedNotes;
+exports.compoundRules = compoundRules;
+exports.describeObject = describeObject;
+exports.linkedObject = linkedObject;
+exports.packageData = packageData;
+const cfb_1 = require("./cfb");
+const context_1 = require("./context");
+const oleobj_1 = require("./oleobj");
+const types_1 = require("./types");
+/** The class ids of Equation Editor 3.0 and its kin, which CVE-2017-11882 and CVE-2018-0802 exploit, as oletools lists them. */
+const EQUATION_CLSIDS = new Set(['0002CE02-0000-0000-C000-000000000046', '00021700-0000-0000-C000-000000000046', '0003000B-0000-0000-C000-000000000046', '0004A6B0-0000-0000-C000-000000000046']);
+/** Equation Editor 3.0's ProgID, which rtfobj matches as a prefix. */
+const isEquationClass = (name) => name.trim().toLowerCase().startsWith('equation.3');
+exports.isEquationClass = isEquationClass;
+/** Streams that only an OLE object's storage holds. */
+const OBJECT_STREAMS = new Set(['\x01OLE', '\x01COMPOBJ', '\x01OLE10NATIVE', '\x03OBJINFO']);
+/** Streams that only an ActiveX control's storage holds. */
+const CONTROL_STREAMS = new Set(['\x03OCXNAME', '\x03OCXDATA']);
+/** A CompObj, OLE or ObjInfo stream is small. More is not read. */
+const SMALL = 65536;
+/** Packager's header is short, and its names are at most 1,024 bytes each. */
+const PACKAGE_HEAD = 4096;
+const upper = (e) => e.name.toUpperCase();
+/** Reports what the reader of a compound file inside this one noted, at the place it sits. */
+function nestedNotes(ctx, cfb, location) {
+    for (const n of cfb.notes)
+        ctx.report(types_1.OfficeCategory.Container, n.detail, location, { bytes: n.bytes });
+}
+/** Where a finding about an entry points: `prefix`, then the entry's path. */
+const at = (prefix, e) => [prefix, (0, cfb_1.entryPath)(e)].filter(Boolean).join(' > ');
+/**
+ * The rules every compound file gets: VBA projects, embedded objects and controls, wherever they sit in the tree.
+ * `prefix` names where the file sits when it is inside another, and `rootIsObject` says that its root is itself an
+ * OLE object's storage, as an object in a presentation or an RTF file is.
+ */
+async function compoundRules(ctx, cfb, prefix, rootIsObject) {
+    const projects = new Set();
+    for (const e of cfb.entries) {
+        if (e.kind === 'stream')
+            continue;
+        const child = (name) => e.children.find(c => upper(c) === name);
+        // A VBA project: a VBA storage with a dir stream, which names the modules (MS-OVBA 2.2).
+        const vba = child('VBA');
+        if (vba?.kind === 'storage' && vba.children.some(c => c.kind === 'stream' && upper(c) === 'DIR')) {
+            projects.add(e);
+            ctx.report(types_1.OfficeCategory.Macro, types_1.OfficeDetail.VbaProject, at(prefix, vba), { storage: at(prefix, vba) });
+        }
+        if (e.kind === 'storage' && (upper(e) === '_VBA_PROJECT_CUR' || upper(e) === 'MACROS') && e.children.length && !projects.has(e)) {
+            // Excel's and Word's project storages, without the dir stream a whole project has.
+            ctx.report(types_1.OfficeCategory.Macro, types_1.OfficeDetail.VbaProject, at(prefix, e), { storage: at(prefix, e) });
+        }
+        const names = new Set(e.children.map(upper));
+        const parent = e.parent ? upper(e.parent) : '';
+        const isObject = e.kind === 'root'
+            ? rootIsObject
+            : [...names].some(n => OBJECT_STREAMS.has(n) || CONTROL_STREAMS.has(n)) ||
+                (parent === 'OBJECTPOOL' && e.parent?.parent?.kind === 'root') ||
+                (e.parent?.kind === 'root' && /^MBD[0-9A-F]{8}$/i.test(e.name));
+        if (isObject)
+            await objectRules(ctx, cfb, e, at(prefix, e));
+    }
+}
+/** Reads an OLE object's storage: its class, its CompObj and OLE streams, and Packager's native data. */
+async function describeObject(cfb, e, _location) {
+    const child = (name) => e.children.find(c => c.kind === 'stream' && upper(c) === name);
+    const small = async (name) => {
+        const s = child(name);
+        return s && s.size <= SMALL ? cfb.bytes(s) : undefined;
+    };
+    const clsid = e.clsid === '00000000-0000-0000-0000-000000000000' ? '' : e.clsid;
+    const compObjBytes = await small('\x01COMPOBJ');
+    const comp = compObjBytes ? (0, oleobj_1.parseCompObj)(compObjBytes) : {};
+    const info = { clsid, progId: comp.progId, userType: comp.userType, control: false, linked: false, target: '', url: false, equation: false };
+    info.equation = EQUATION_CLSIDS.has(clsid) || (0, exports.isEquationClass)(comp.progId ?? '');
+    if ([...CONTROL_STREAMS].some(n => child(n))) {
+        const name = await small('\x03OCXNAME');
+        info.control = true;
+        if (name)
+            info.controlName = Buffer.from(name).toString('utf16le').replace(/\0+$/, '');
+        return info;
+    }
+    const oleBytes = await small('\x01OLE');
+    const ole = oleBytes ? (0, oleobj_1.parseOleStream)(oleBytes) : { linked: false, target: '', url: false };
+    Object.assign(info, ole);
+    const native = child('\x01OLE10NATIVE');
+    if (native) {
+        // The stream starts with the native data's size, then Packager's data.
+        info.pkg = (0, oleobj_1.parsePackage)(await cfb.source(native).read(4, PACKAGE_HEAD));
+    }
+    return info;
+}
+/** One OLE object's storage: a control, a linked object, or an embedded one, with what it holds. */
+async function objectRules(ctx, cfb, e, location) {
+    const d = await describeObject(cfb, e, location);
+    const data = { storage: location };
+    if (d.clsid)
+        data.clsid = d.clsid;
+    if (d.progId)
+        data.progId = (0, context_1.clip)(d.progId);
+    if (d.userType)
+        data.className = (0, context_1.clip)(d.userType);
+    if (d.control) {
+        ctx.report(types_1.OfficeCategory.Control, types_1.OfficeDetail.ActiveX, location, d.controlName ? { ...data, name: (0, context_1.clip)(d.controlName) } : data);
+        return;
+    }
+    if (d.pkg) {
+        Object.assign(data, packageData(d.pkg));
+        if (!d.pkg.embedded && d.pkg.sourcePath)
+            ctx.external(types_1.OfficeDetail.Object, d.pkg.sourcePath, location, { storage: location }, 'package link');
+    }
+    if (d.linked)
+        linkedObject(ctx, d, location, { storage: location, ...(d.clsid ? { clsid: d.clsid } : {}) });
+    else
+        ctx.report(types_1.OfficeCategory.Embedded, types_1.OfficeDetail.OleObject, location, data);
+    if (d.equation)
+        ctx.report(types_1.OfficeCategory.Embedded, types_1.OfficeDetail.Equation, location, data);
+}
+/**
+ * Reports a linked object. A URL moniker's target loads from outside the file whatever its text looks like: a
+ * CVE-2017-0199 sample puts a character with a stray high byte where the colon of https: goes.
+ */
+function linkedObject(ctx, d, location, data) {
+    if (d.target && !d.url)
+        ctx.external(types_1.OfficeDetail.Object, d.target, location, data, 'linked object');
+    else
+        ctx.report(types_1.OfficeCategory.External, types_1.OfficeDetail.Object, location, d.target ? { ...data, target: (0, context_1.clip)(d.target, 2000) } : data);
+}
+/** What a finding shows of a Packager object's file: its name and paths, and its size when the object holds it. */
+function packageData(p) {
+    return { fileName: (0, context_1.clip)(p.fileName), sourcePath: (0, context_1.clip)(p.sourcePath, 2000), tempPath: (0, context_1.clip)(p.tempPath, 2000), ...(p.embedded ? { size: p.size } : {}) };
+}

package/dist/odf.d.ts

@@ -0,0 +1,3 @@
+import { type ZipContext } from './context';
+/** Inspects an OpenDocument package. */
+export declare function inspectOdf(ctx: ZipContext): Promise<void>;