@patrickdk77/office-defuse 0.2.2 → 0.2.4

package/README.md

@@ -77,7 +77,7 @@ The format comes from the content, never from the file name.
 |---|---|---|---|
 | Word | .docx .docm .dotx .dotm | .doc .dot from Word 6.0 to 2003, and .rtf | Flat OPC .xml |
 | Excel | .xlsx .xlsm .xltx .xltm .xlam .xlsb | .xls .xlt .xla from Excel 5.0 to 2003 | Flat OPC .xml |
-| PowerPoint | .pptx .pptm .potx .potm .ppsx .ppsm .ppam .sldx .sldm | .ppt from PowerPoint 97 to 2003 | Flat OPC .xml |
+| PowerPoint | .pptx .pptm .potx .potm .ppsx .ppsm .ppam .sldx .sldm | .ppt from PowerPoint 97 to 2003, and .ppa add-ins | Flat OPC .xml |
 | Visio | .vsdx .vsdm .vstx .vstm .vssx .vssm | .vsd from Visio 2000 to 2010 | |
 | XPS | .xps .oxps | | |
 | OpenDocument | .odt .ott .ods .ots .odp .otp .odg .otg .odf .odm .odb | | .fodt .fods .fodp .fodg |
@@ -91,7 +91,7 @@ A ZIP with both markers is rejected as PACKAGE/AMBIGUOUS_FORMAT, since Office co
 
 A .xlsb gets the package checks. Its sheets are binary records, and the formulas in them go unread. Its external link parts are binary too, and office-defuse reads their link records for DDE links. A .odb gets every ODF check, and the database under `database/` goes unread.
 
-A file that starts with the compound file signature is a compound file, MS-CFB. The streams and storages at its root name the format: `WordDocument` for Word, `Workbook` or `Book` for Excel, `PowerPoint Document`, `VisioDocument`, `__properties_version1.0` for an Outlook message, a `Quill` storage or Publisher's class id beside a `Contents` stream for Publisher, and a `Props` stream beside a storage named by a number for Project. Word's FIB says whether a document is a template, and Excel's records whether a workbook is a template or an add-in. Neither needs the password of an encrypted file. An Outlook template has a class id of its own. A PowerPoint 97 to 2003 template or show reports its format as .ppt, and a Visio stencil or template as .vsd.
+A file that starts with the compound file signature is a compound file, MS-CFB. The streams and storages at its root name the format: `WordDocument` for Word, `Workbook` or `Book` for Excel, `PowerPoint Document`, `VisioDocument`, `__properties_version1.0` for an Outlook message, a `Quill` storage or Publisher's class id beside a `Contents` stream for Publisher, and a `Props` stream beside a storage named by a number for Project. Word's FIB says whether a document is a template, and Excel's records whether a workbook is a template or an add-in. Neither needs the password of an encrypted file. An Outlook template has a class id of its own, and so does a PowerPoint 97 to 2003 add-in, a .ppa, whose root is its VBA project. A PowerPoint 97 to 2003 template or show reports its format as .ppt, and a Visio stencil or template as .vsd.
 
 A compound file with two of these is PACKAGE/AMBIGUOUS_FORMAT. One with none is PACKAGE/UNRECOGNIZED, and so is a `WordDocument` stream that holds no Word 6.0 to 2003 FIB. A PowerPoint 4.0 file, a bare OLE object and a `vbaProject.bin` on its own all land there.
 
@@ -118,7 +118,7 @@ Detection does not claim a file whose format office-defuse cannot name. That cov
 
 In a ZIP package:
 
-- VBA projects, Excel 4.0 macro sheets, and OpenDocument `Basic/`, `Scripts/` and `Dialogs/` folders. These go by content type, relationship type or folder name, and a folder counts when it holds a file that is not empty. office-defuse parses no OLE part of a package, such as `vbaProject.bin`.
+- VBA projects, Excel 4.0 macro sheets, and OpenDocument `Basic/`, `Scripts/` and `Dialogs/` folders. These go by content type, relationship type or folder name, and a folder counts when it holds a file that is not empty. office-defuse parses no OLE part of a package, such as `vbaProject.bin`, unless `scriptPlugins` is set. Then it reads the VBA project, as [Script plugins](#script-plugins) says.
 - OpenDocument script event listeners that name a script URL or macro. Those that fire as the document opens or is created get a finding of their own. LibreOffice ignores a listener whose URL and macro name are both empty, and so does office-defuse. Visio ShapeSheet cells that call RUNADDON, RUNADDONWARGS, CALLTHIS, RUNMACRO, OPENFILE or DOOLEVERB.
 - Links and actions that run macros: `vnd.sun.star.script:` and `macro:` targets, PowerPoint's `ppaction://macro`, Excel drawing shapes with a `macro` attribute, and form controls with an `x:FmlaMacro`. Ribbon callbacks such as `onLoad` and `onAction`. OpenDocument menu, toolbar and key settings under `Configurations2/`. LibreOffice writes an empty `Configurations2/accelerator/current.xml` into the documents it saves, and an empty file counts for nothing.
 - Excel defined names that run a macro sheet: Auto_Open and Auto_Activate as MACRO/EVENT_ON_OPEN, Auto_Close and Auto_Deactivate as MACRO/EVENT. A name counts when it starts with one of these, as `Auto_Open2` does.
@@ -131,7 +131,7 @@ In a ZIP package:
 - References that load from outside the file on their own: attached and OpenDocument templates, linked OLE objects and packages, images, frames, included files and linked sections, external workbooks, `meta:auto-reload`, and any other external relationship. A target on the machine itself is EXTERNAL/LOCAL_FILE. An empty OpenDocument reference is the document itself and names no file, so it goes unreported. A target counts as local only if its percent-decoded form is local too, because a CVE-2017-0199 sample writes its `script:` scheme as `%73cript:`.
 - Hyperlinks, with pdf-defuse's checks of the target: the scheme, file and network paths, data URLs, credentials before the host, IP hosts, punycode and mixed-script hosts, and percent-encoded hosts. A link to a place inside the document goes unreported, and so does an empty link, which is the document itself.
 - A safe link whose label is an address of another site than the one it opens is LINK/TEXT_MISMATCH. A label counts as an address when it is a web URL, a mail address, or a host with or without a path that starts with `www.` or ends in a known top-level domain. Text that only mentions an address names no site, and neither do Excel function names such as `BETA.DIST` and file names such as `moon.htm`, which look like hosts. Sites compare as in pdf-defuse: a subdomain or parent of the label's site matches, and `evil.co.uk` is not under `mybank.co.uk`. The labels are a Word hyperlink's text and tooltip, a HYPERLINK field's result and `\o` tooltip, a DrawingML run's text and a link's tooltip, an Excel hyperlink's display name and tooltip, an OpenDocument link's text and title, and the characters of an XPS Glyphs element. The rewrite removes the link and keeps its text.
-- Embedded OLE objects and packages, OLE files nothing declares as an object, Java applets, plug-ins and ActiveX controls.
+- Embedded OLE objects and packages, OLE files nothing declares as an object, Java applets, plug-ins and ActiveX controls. A Forms 2.0 control whose persisted properties read as Office writes them is CONTROL/FORMS_CONTROL, `info`, and stays. See [ActiveX controls](#activex-controls).
 - Package structure: parts without a content type, parts no relationship reaches, files the ODF manifest does not list, an irregular ODF layout, and names a package gives twice.
 - Document type declarations in XML parts, and references to external entities. See [Document types and entities](#document-types-and-entities).
 
@@ -200,7 +200,7 @@ The check reads the output with the caller's overrides and limits, without `file
 - A part loses its root element only by going whole. Edits happen in place, and everything the rewrite does not touch keeps its characters, in the part's own encoding, UTF-8 or UTF-16, behind its own byte order mark.
 - A Word field a strip finding names loses its begin, separator and end marks and its code, nested fields included, and keeps its result. A `w:fldSimple` keeps the runs inside it.
 - An Excel 4.0 macro sheet becomes an empty worksheet of the same name, with the worksheet content type and relationship type, so the indexes of the sheets after it stay right. A defined name that runs a macro goes. So does a formula that calls DDE, and its cell keeps its cached value.
-- A drawing shape loses its `macro` attribute, a ribbon control its callbacks, and a PowerPoint shape an action that runs a program, a macro or an object verb. A Visio cell that calls code goes.
+- A drawing shape loses its `macro` attribute, a ribbon control its callbacks, and a PowerPoint shape an action that runs a program, a macro or an object verb. A Visio cell that calls code goes. When script plugins keep the document's VBA project, a shape, form control, callback, action or MACROBUTTON field that runs one of its macros by name stays.
 - The main part keeps its content type, so a `.docm` without its VBA project is still a `.docm`.
 - In an OpenDocument package, `mimetype` comes first, stored, without an extra field, and holds the media type without white space. A package without one gets one, and a package without a manifest gets a manifest listing its entries. `Basic/`, `Scripts/`, `Dialogs/` and `Configurations2/` go whole. An entry goes with its manifest entry and with every element whose `xlink:href` names it. A link `text:a` or `draw:a` keeps what it holds. A form control loses its link, and a cell loses a formula that calls DDE. An embedded OLE object goes and the preview image beside it stays.
 - A document type declaration with an internal subset goes when XML/INTERNAL_SUBSET strips it. Each reference to an internal entity is written out as its text, markup included, and each start tag whose attributes the declarations changed or added to is written out whole, namespace declarations included. The part then reads as the inspection read it. References to external entities go when XML/EXTERNAL_ENTITY strips them. If that finding is overridden to `info` while the subset would go, the references still need their declarations, so the declaration stays and the check of the output reports it.
@@ -216,13 +216,50 @@ A Flat OPC package is rewritten as the package of its parts is, then written bac
 
 ### Compound files
 
-The rewrite writes a new compound file, version 3 with 512-byte sectors, without the streams and storages a strip finding names: VBA project storages, the storages of embedded objects, linked objects and ActiveX controls, Excel's `Ctls` stream, and Outlook attachments. A message's property stream counts its attachments, and the count drops by the ones that went.
+The rewrite writes a new compound file, version 3 with 512-byte sectors, without the streams and storages a strip finding names: VBA project storages, the storages of embedded objects, linked objects and ActiveX controls, Excel's `Ctls` stream, Word's picture for printing a control, and Outlook attachments. A VBA project that script plugins keep is written without its compiled code. A message's property stream counts its attachments, and the count drops by the ones that went.
 
 The FAT comes right after the header, so no stream lands in the first 1024 bytes, where PDF readers look for a header. When a stream ends with a ZIP end record, as an embedded package does, free sectors of zeros follow the last stream until the record is more than 65,557 bytes from the end of the file, past where ZIP readers look.
 
 An Outlook message's RTF body with a strip finding is rewritten the way an RTF file is, and stored back uncompressed, which MS-OXRTFCP allows. A body that does not decompress, or one with a `reject` finding inside, goes, and the message keeps its plain text body. The property stream entry of a body that went goes too, and that of a rewritten body takes its new size. Every other stream is copied unchanged. Sectors no stream holds, the rest of each stream's last sector and data past the last sector are not written.
 
-Content inside a stream stays as it was. That covers Word's fields, template and WordBasic macros, Excel's records for macro sheets, defined names, links, hyperlinks and buttons, every record of a PowerPoint presentation along with the objects stored in its records, the ShapeSheet cells of a Visio drawing, and the RC4 encryption of a workbook. A finding there is still in the output, so the output fails its check and the upload is rejected.
+Excel's and PowerPoint's records are written again, as the next two sections say. Content inside any other stream stays as it was: Word's fields, template and WordBasic macros, Excel's cell formulas, and the ShapeSheet cells of a Visio drawing. A finding there is still in the output, so the output fails its check and the upload is rejected.
+
+### Excel workbooks
+
+A workbook stream, Excel 97 to 2003 or Excel 5.0 and 95, is written again record by record, in the order the stream holds them:
+
+- An Excel 4.0 macro sheet becomes an empty worksheet of the same name and visibility, so formulas and names keep their sheet numbers.
+- A name that runs a macro, such as Auto_Open, is renamed `Removed_Auto_Open_1` and so on, and is no longer a built-in name. Formulas refer to names by number, so removing it would point them at the wrong name.
+- A button or shape loses the macro it runs, unless the workbook's VBA project stays and the macro is one of its own: one name of the SupBook that is the workbook itself, as Excel names a VBA macro. A defined name can stand for anything, so a button that runs one loses it.
+- A hyperlink goes with its tooltip.
+- An external workbook, DDE or OLE link keeps its SupBook record, which formulas count to by number, with a path that is the workbook itself, U+0002.
+- A workbook encrypted with VelvetSweatshop is written decrypted, without its FILEPASS record. So is any encrypted workbook that is written again, since office-defuse does not encrypt.
+
+Records change size, so the stream positions other records hold are written anew: each sheet's in BoundSheet8, the DefColWidth and DBCell positions in Index, a DBCell's offset back to its first row, and ExtSST's string positions. A position that lands where no record starts, or inside a record that changed, leaves the stream as it was, and the output check rejects the upload. Excel 5.0 and 95 workbooks get the sheet and name edits only. A cell formula that calls EXEC, CALL or WEBSERVICE is not written again.
+
+### PowerPoint presentations
+
+A presentation is written as a full save: each persist object the current edit reaches, in persist id order, then one persist directory and one UserEditAtom with no edit before it, which the Current User stream points at. A container's length follows the records left in it.
+
+- An embedded object, a linked object or an ActiveX control that goes takes its ExOleObjStg and its container in ExObjList with it. A Forms 2.0 control stays. An object a file plugin rewrote takes the plugin's bytes, compressed again when PowerPoint stored it compressed.
+- A VBA project that goes takes its VBAInfoContainer with it. One that script plugins keep is written without its compiled code inside its compressed storage.
+- An action that runs a program, a macro or an OLE verb becomes no action. A macro of a kept VBA project keeps its action.
+- A hyperlink that goes takes its ExHyperlinkContainer, and the actions that open it become no action.
+- A linked movie or sound loses its path.
+- An encrypted presentation that is written again is written decrypted, without its encryption session. Its Pictures and EncryptedSummary streams are encrypted too, and office-defuse does not decrypt them, so a presentation that has either stays as it was and the output check rejects it.
+
+## ActiveX controls
+
+An ActiveX control runs whatever code its class names, so a control goes unless office-defuse can tell it is one of the Forms 2.0 controls Office ships, as Office persisted it: CommandButton, Label, TextBox, ListBox, ComboBox, CheckBox, OptionButton, ToggleButton, SpinButton or ScrollBar. Such a control is CONTROL/FORMS_CONTROL, `info`, and stays, with or without a VBA project. An override to `strip` removes it like any other control.
+
+office-defuse reads the control's properties as MS-OFORMS lays them out and as LibreOffice reads them, and keeps the control when:
+
+- its class id, or the ProgID its CompObj, ax:ocx element or Obj record names, is one of those controls;
+- every bit of its property mask names a property MS-OFORMS defines;
+- it holds no picture or mouse icon, whose bytes are a picture file Office decodes;
+- its properties, its font and, for a list, its column infos fill its data to the last byte.
+
+The control can sit in an OOXML activeX part, persisted as a stream that starts with the class id, as a storage with a contents stream, or as a property bag with plain values. In a Word document it is a storage under ObjectPool, and its `\x03PRINT` stream, a Windows metafile Word prints in its place, goes as CONTROL/CONTROL_PICTURE. In an Excel workbook every control is in one `Ctls` stream, which stays only when the Obj records place Forms 2.0 controls over all of it. Any other control, a Forms 2.0 control with a picture, and a frame, multipage or tab strip are CONTROL/ACTIVEX with `data.reason`.
 
 ### RTF
 
@@ -262,6 +299,40 @@ const { disarmOffice, officePlugin } = require('@patrickdk77/office-defuse');
 await disarmOffice(bytes, { filePlugins: [officePlugin()] });
 ```
 
+## Script plugins
+
+`scriptPlugins` takes script plugins that decide about VBA. office-defuse reads a VBA project's dir stream and modules as MS-OVBA describes them, and shows each module to the plugins as a `ContainedScript`:
+
+| Field | What it holds |
+|---|---|
+| `text` | The module's source, decoded with the project's code page |
+| `trigger` | `vba-document`, `vba-standard`, `vba-class` or `vba-form`, as the PROJECT stream lists the module |
+| `location` | Where the module sits, such as `xl/vbaProject.bin > VBA/Module1` |
+| `fieldName` | The module's name |
+| `language`, `form` | `vba` and `office` |
+| `references` | On the first module only, the project's references, each `{ name, kind, libid }` |
+
+The first plugin whose `accepts` returns true decides a module. A module it passes gets MACRO/PLUGIN_PASSED, `info`. Any other answer, `scrubbed` included, is MACRO/PLUGIN_REMOVED, and an error is MACRO/PLUGIN_FAILED, both `strip`, since office-defuse writes no module a plugin rewrote. The plugin's findings go into the report as they are.
+
+The project stays when every module passed. Otherwise it goes, as it does without plugins, and so does a project with a module no plugin took. A project that stays is written without its compiled code, the way Mandiant's OfficePurge writes one. Each module stream holds only its source, compressed again, the dir stream says each source starts at 0, `_VBA_PROJECT` names no VBA version, and the `__SRP_` caches go. Office then compiles the source the plugins read, so p-code that does something other than its source, which VBA stomping relies on, never runs. MACRO/COMPILED_CODE, `strip`, reports the purge, and MACRO/VBA_PROJECT turns to `info`.
+
+A user form stays with its project when its designer storage holds Forms 2.0 controls only. The designer must be the UserForm designer, the storages under it must be Forms 2.0 forms, frames and multipages, and every form's class table must be empty, since a class table can name any ActiveX control. A form that fails gets CONTROL/ACTIVEX at its designer, and while that finding strips, the project goes.
+
+When the document's own project stays, so does what runs its macros by name: an Excel shape's `macro`, a form control's `x:FmlaMacro`, a ribbon callback, PowerPoint's `ppaction://macro` and Word's MACROBUTTON field. Their findings turn to `info`. A name that points into another file, as `'other.xlsm'!Macro`, still goes.
+
+office-defuse decides the `vbaProject.bin` part of an OOXML package, which with `scriptPlugins` set, even to an empty list, goes to the script plugins and not to the file plugins. It decides the project storages of a Word document, a workbook, a PowerPoint 97 presentation, a .ppa add-in and the other compound files. A project inside an embedded object is for the file plugins that take the object.
+
+A source that does not decompress, or a dir stream that names a module stream that is not there, leaves nothing to check. The project goes, and MACRO/VBA_PROJECT's `data.reason` says why. The check of the output does not ask the plugins again. It matches the project by the MD5 of its references and module sources, reports the plugins' findings again, and reports MACRO/COMPILED_CODE if the output still holds p-code, which fails the check.
+
+[script-defuse](https://github.com/patrickdk77/script-defuse)'s `formScriptPlugin` is a script plugin for VBA:
+
+```js
+const { disarmOffice } = require('@patrickdk77/office-defuse');
+const { formScriptPlugin } = require('@patrickdk77/script-defuse');
+
+await disarmOffice(bytes, { scriptPlugins: [formScriptPlugin()] });
+```
+
 ## The containers
 
 The ZIP reader starts from the end record and the central directory. It checks each local header against the central directory before it reads any content. It refuses these, and stops the run:
@@ -402,6 +473,7 @@ The bands are NONE at 0, LOW from 1, MEDIUM from 25, HIGH from 50 and CRITICAL f
 | `actionOverrides` | none | Change the action for a category, or for a category and detail |
 | `scoreWeights`, `scoreBands` | built in | Change the scoring |
 | `filePlugins` | none | Plugins that decide about the files inside the file. See [File plugins](#file-plugins) |
+| `scriptPlugins` | none | Plugins that decide about the modules of a VBA project. See [Script plugins](#script-plugins) |
 | `tempDir` | `os.tmpdir()` | Where temporary files go |
 | `memoryThreshold` | 8 MiB | Disarm keeps its copy of the upload, its output and each file it shows a plugin in memory up to this size, and in a temporary file past it. The copies plugins return share this much memory while they wait for the rewrite |
 
@@ -447,8 +519,8 @@ Exit codes are 0 for clean, 1 for defused or strippable, 2 for rejected and 3 fo
 
 ## What it does not check
 
-- The OLE parts of a ZIP package, such as `vbaProject.bin`, the objects inside `oleObject*.bin`, and ActiveX binaries. office-defuse hands them to the file plugins and reads none of them itself.
-- VBA source. A VBA project is reported whole, and its modules go unread.
+- The OLE parts of a ZIP package, such as the objects inside `oleObject*.bin`, the binaries of ActiveX controls other than Forms 2.0 ones, and `vbaProject.bin` without script plugins. office-defuse hands them to the file plugins and reads none of them itself.
+- VBA source. office-defuse reads the modules only to show them to script plugins, and without plugins reports a project whole. In a user form that stays, the controls' data and pictures in its `o` stream go unread.
 - Encrypted Word 6.0 and 95 documents. They are rejected. In a Word document encrypted with RC4 CryptoAPI, the OLE objects that Word keeps in the Data stream rather than in ObjectPool. The pictures of an encrypted presentation.
 - Formulas in .xlsb sheets, and in an Excel 5.0 or 95 workbook. A DDE link that a formula uses is found in the workbook's link records.
 - Hyperlinks in a Visio .vsd, ShapeSheet cells in a drawing from Visio 5.0 or earlier, and anything in Publisher and Project files but VBA projects and objects.

package/dist/biff.d.ts

@@ -24,6 +24,8 @@ export interface BiffRecord {
 /** A sheet as BoundSheet8 (or BIFF5's BOUNDSHEET) lists it. */
 export interface Sheet {
     position: number;
+    /** Where its BoundSheet record starts in the stream. */
+    record?: number;
     /** 0 visible, 1 hidden, 2 very hidden. */
     state: number;
     /** 0 worksheet or dialog, 1 macro sheet, 2 chart, 6 VBA module. */
@@ -42,6 +44,15 @@ export declare class RecordReader {
     constructor(cfb: CompoundFile, stream: CfbEntry, start: number, deadline?: number | undefined);
     next(): Promise<BiffRecord | undefined>;
 }
+/**
+ * The subrecords of a BIFF8 Obj record (MS-XLS 2.4.181), each with its type, where its header starts and its data. The
+ * walk stops at FtEnd, and at FtLbsData, whose length does not count all its data.
+ */
+export declare function objSubrecords(b: Uint8Array): Generator<{
+    ft: number;
+    at: number;
+    data: Uint8Array;
+}>;
 /** BIFF8 writes strings with a flag byte: 8-bit characters, or 16-bit ones when its low bit is set. */
 export declare function xlString(b: Uint8Array, at: number, chars: number): {
     text: string;

package/dist/biff.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RecordReader = exports.R = void 0;
+exports.objSubrecords = objSubrecords;
 exports.xlString = xlString;
 exports.parseBoundSheet = parseBoundSheet;
 exports.parseLbl = parseLbl;
@@ -56,6 +57,20 @@ class RecordReader {
     }
 }
 exports.RecordReader = RecordReader;
+/**
+ * The subrecords of a BIFF8 Obj record (MS-XLS 2.4.181), each with its type, where its header starts and its data. The
+ * walk stops at FtEnd, and at FtLbsData, whose length does not count all its data.
+ */
+function* objSubrecords(b) {
+    for (let at = 0; at + 4 <= b.length;) {
+        const ft = b[at] | (b[at + 1] << 8);
+        const cb = b[at + 2] | (b[at + 3] << 8);
+        if (ft === 0x00 || ft === 0x13)
+            return;
+        yield { ft, at, data: b.subarray(at + 4, at + 4 + cb) };
+        at += 4 + cb;
+    }
+}
 /** BIFF8 writes strings with a flag byte: 8-bit characters, or 16-bit ones when its low bit is set. */
 function xlString(b, at, chars) {
     if (at >= b.length)

package/dist/contained.d.ts

@@ -22,6 +22,11 @@ export interface InnerFile {
     /** The file's bytes, in order. */
     chunks(): AsyncIterable<Uint8Array>;
 }
+/**
+ * Throws on an error a plugin threw that stops the whole tree. An I/O error fails this run as one of its own would,
+ * so its cause goes up.
+ */
+export declare function passOn(run: RunState, e: unknown): void;
 /**
  * Adds the findings a plugin reported from inside a file, labeled with the file's name and place. A reject inside the
  * file means the file goes, not the one that holds it, so it is recorded here as strip.

package/dist/contained.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RUN_OPTIONS = void 0;
+exports.passOn = passOn;
 exports.pushContained = pushContained;
 exports.decideContained = decideContained;
 exports.presence = presence;

package/dist/context.d.ts

@@ -77,7 +77,17 @@ export interface RunState {
     sources: ByteSource[];
     /** The container, once the format rules have read it. */
     output?: Output;
+    /**
+     * The document's own VBA project stays, as the script plugins passed it. The buttons, shapes, callbacks and fields
+     * that run one of its macros by name then stay too.
+     */
+    macrosKept?: boolean;
 }
+/**
+ * 'info' for a link or callback that runs one of the document's own macros when its project stays, so the finding
+ * reports it without removing it. Undefined otherwise, leaving the action to the overrides.
+ */
+export declare function ownMacro(run: RunState, name: string): 'info' | undefined;
 /** A finding the rules made, with its action, which the rewrite reads. Past 200 of one kind, `finding` is absent. */
 export interface Reported {
     action: OfficeFindingAction;

package/dist/context.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZipContext = exports.PlanContext = exports.RunContext = exports.clip = void 0;
+exports.ownMacro = ownMacro;
 const links_1 = require("./links");
 const plan_1 = require("./plan");
 const types_1 = require("./types");
@@ -12,6 +13,15 @@ const clip = (raw, n = 200) => {
     return s.length > n ? `${s.slice(0, n - 3)}...` : s;
 };
 exports.clip = clip;
+/** A macro of the document's own project, by name: Macro, Module.Macro, or Excel's [0]!Macro for this workbook. */
+const OWN_MACRO = /^(?:\[0\]!)?[\p{L}_][\p{L}\p{N}_]*(?:\.[\p{L}_][\p{L}\p{N}_]*)?$/u;
+/**
+ * 'info' for a link or callback that runs one of the document's own macros when its project stays, so the finding
+ * reports it without removing it. Undefined otherwise, leaving the action to the overrides.
+ */
+function ownMacro(run, name) {
+    return run.macrosKept && OWN_MACRO.test(name.trim()) ? 'info' : undefined;
+}
 /** What one inspection holds while the format rules run. */
 class RunContext {
     factory;

package/dist/engine.js

@@ -401,6 +401,8 @@ async function disarmAtDepth(source, sink, options, depth, deadline = options.li
         }
         // The output is checked with the caller's overrides and limits, and the plugins' verdicts in place of the plugins.
         const verifyOptions = {
+            // No plugin is asked again. An empty list still reads VBA project parts the way the upload's run did.
+            scriptPlugins: options.scriptPlugins && [],
             actionOverrides: options.actionOverrides,
             scoreWeights: options.scoreWeights,
             scoreBands: options.scoreBands,

package/dist/fields.js

@@ -29,7 +29,7 @@ function evaluateField(ctx, location, code, computed, result = '') {
     if (name === 'DDE' || name === 'DDEAUTO')
         actions.push(ctx.report(types_1.OfficeCategory.Dde, types_1.OfficeDetail.Field, location, data).action);
     else if (name === 'MACROBUTTON')
-        actions.push(ctx.report(types_1.OfficeCategory.Field, types_1.OfficeDetail.Macrobutton, location, { ...data, macro: (0, context_1.clip)(words[1]?.text ?? '') }).action);
+        actions.push(ctx.report(types_1.OfficeCategory.Field, types_1.OfficeDetail.Macrobutton, location, { ...data, macro: (0, context_1.clip)(words[1]?.text ?? '') }, (0, context_1.ownMacro)(ctx.run, words[1]?.text ?? '')).action);
     else if (name === 'INCLUDETEXT' || name === 'INCLUDEPICTURE' || name === 'IMPORT' || name === 'LINK') {
         const target = arg(name === 'LINK' ? 2 : 1);
         if (target === undefined)

package/dist/findings.js

@@ -75,6 +75,10 @@ def(types_1.OfficeCategory.Encrypted, types_1.OfficeDetail.XorObfuscation, 'info
 def(types_1.OfficeCategory.Encrypted, types_1.OfficeDetail.UnsupportedAlgorithm, 'reject', 0, 'The file is encrypted with an algorithm office-defuse does not decrypt<: {algorithm}|>');
 // MACRO
 def(types_1.OfficeCategory.Macro, types_1.OfficeDetail.VbaProject, 'strip', 70, 'The document holds VBA macros');
+def(types_1.OfficeCategory.Macro, types_1.OfficeDetail.CompiledCode, 'strip', 10, "The VBA project's compiled code was removed, so Office compiles the source the plugins checked");
+def(types_1.OfficeCategory.Macro, types_1.OfficeDetail.PluginPassed, 'info', 30, 'A VBA module was kept by <plugin {plugin}|a plugin>');
+def(types_1.OfficeCategory.Macro, types_1.OfficeDetail.PluginRemoved, 'strip', 0, '<Plugin {plugin}|A plugin> did not keep a VBA module, so the VBA project was removed');
+def(types_1.OfficeCategory.Macro, types_1.OfficeDetail.PluginFailed, 'strip', 0, '<Plugin {plugin}|A plugin> failed on a VBA module, so the VBA project was removed');
 def(types_1.OfficeCategory.Macro, types_1.OfficeDetail.XlmMacrosheet, 'strip', 70, 'The workbook holds an Excel 4.0 macro sheet');
 def(types_1.OfficeCategory.Macro, types_1.OfficeDetail.WordBasic, 'strip', 70, 'The Word 6.0 or 95 document holds WordBasic macros, which Word runs as VBA');
 def(types_1.OfficeCategory.Macro, types_1.OfficeDetail.OdfBasic, 'strip', 70, 'The document holds Basic macros');
@@ -138,7 +142,9 @@ def(types_1.OfficeCategory.Embedded, types_1.OfficeDetail.PluginScrubbed, 'info'
 def(types_1.OfficeCategory.Embedded, types_1.OfficeDetail.PluginFailed, 'strip', 0, '<Plugin {plugin}|A plugin> failed, so the embedded file was removed');
 def(types_1.OfficeCategory.Embedded, types_1.OfficeDetail.PluginRemoved, 'strip', 0, 'An embedded file was removed by <plugin {plugin}|a plugin>');
 // CONTROL
-def(types_1.OfficeCategory.Control, types_1.OfficeDetail.ActiveX, 'strip', 50, 'An ActiveX control');
+def(types_1.OfficeCategory.Control, types_1.OfficeDetail.ActiveX, 'strip', 50, 'An ActiveX control<: {reason}|>');
+def(types_1.OfficeCategory.Control, types_1.OfficeDetail.FormsControl, 'info', 10, 'A Forms 2.0 control<, {className}|>, whose persisted properties office-defuse read');
+def(types_1.OfficeCategory.Control, types_1.OfficeDetail.ControlPicture, 'strip', 10, "A control's picture for printing, a Windows metafile");
 // PROCESSING
 def(types_1.OfficeCategory.Processing, types_1.OfficeDetail.VerificationFailed, 'reject', 0, 'The defused output did not pass its own inspection, so nothing was written');
 /** The built-in spec for a kind of finding, or undefined for a kind office-defuse does not make, such as one from another package. */

package/dist/forms.d.ts

@@ -0,0 +1,51 @@
+import { type CfbEntry, type CompoundFile } from './cfb';
+/** The number of classes in the class table of a FormControl (MS-OFORMS 2.2.10.1), the `f` stream. */
+export declare function classTableCount(f: Uint8Array): number;
+/**
+ * Why a user form's designer storage may hold something other than Forms 2.0 controls, or undefined when it holds
+ * only those: the UserForm designer, storages of Forms 2.0 classes, and forms whose class tables are empty.
+ */
+export declare function designerProblem(cfb: CompoundFile, storage: CfbEntry, limit: number): Promise<string | undefined>;
+/**
+ * The properties a Forms 2.0 control persists, in the order of its property mask (MS-OFORMS 2.2). Each takes the
+ * next bit. A number sits in the data block, aligned to its size; a string or a pair in the extra data block; a
+ * picture in the stream data; a flag holds no data. A bit MS-OFORMS leaves undefined must be clear.
+ */
+type Prop = 'u8' | 'u16' | 'u32' | 'pair' | 'string' | 'picture' | 'flag' | 'undefined';
+interface ControlLayout {
+    props: Prop[];
+    /** The property mask is 64 bits wide. */
+    wide: boolean;
+    text: boolean;
+}
+/** The Forms 2.0 controls office-defuse reads, by class id. Frames, multipages and tab strips hold other controls and are not here. */
+export declare const FORMS_CONTROLS: ReadonlyMap<string, ControlLayout>;
+/** The ProgIDs of those controls, which a property bag or CompObj may name. */
+export declare const FORMS_PROGIDS: ReadonlyMap<string, string>;
+/**
+ * Why the persisted data of a Forms 2.0 control may not be what Forms 2.0 writes, or undefined when it is: the
+ * control's property block, then its TextProps for a control with text, then the column infos a list control counts,
+ * and nothing after. A picture or a mouse icon counts as a problem, since its bytes are a picture file Office decodes
+ * and office-defuse cannot rewrite in place.
+ */
+export declare function controlProblem(classId: string, data: Uint8Array): string | undefined;
+/**
+ * Why a Forms 2.0 control persisted as a property bag in its activeX part may hold more than plain values, or
+ * undefined when it does not. `props` are the bag's name and value pairs, `nested` says ax:ocx held any other element,
+ * inside an ax:ocxPr or beside one, such as a font or a picture.
+ */
+export declare function bagProblem(classId: string, props: ReadonlyArray<{
+    name: string;
+    value: string;
+}>, nested: boolean): string | undefined;
+/** Streams a control's storage holds in an OOXML binary part: its class and its properties. */
+export declare const OOXML_CONTROL_STREAMS: ReadonlySet<string>;
+/** In a Word document, the storage also holds the control's name and its picture for printing. */
+export declare const WORD_CONTROL_STREAMS: ReadonlySet<string>;
+/**
+ * Why a control's storage may not hold a Forms 2.0 control as Office persists one, or undefined when it does. Its
+ * class is the storage's class id, or its CompObj's ProgID when that is null, and must be `classId` when given. It
+ * holds only the `allowed` streams and a contents stream that `controlProblem` passes.
+ */
+export declare function controlStorageProblem(cfb: CompoundFile, storage: CfbEntry, allowed: ReadonlySet<string>, classId?: string): Promise<string | undefined>;
+export {};