@patrickdk77/office-defuse 0.2.2 → 0.3.0

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
 
@@ -248,9 +285,11 @@ A file comes as a `ContainedFile`. `name` is the part or entry name, a Packager
 | `removed` | goes, with every reference to it | EMBEDDED/PLUGIN_REMOVED, `strip` |
 | `scrubbed` with nothing written, or an error | goes, with every reference to it | EMBEDDED/PLUGIN_FAILED, `strip` |
 
-A file goes whatever the overrides say about these findings. A file no plugin accepts gets the rule it gets without plugins, such as EMBEDDED/OLE_OBJECT, and a picture, which no rule names, stays. When a plugin keeps a file, the findings that name the file for being there, such as EMBEDDED/PACKAGE or MACRO/VBA_PROJECT for `vbaProject.bin`, turn to `info` and leave the score, as pdf-defuse leaves out an attached file a plugin kept. Other rules still decide for themselves, so an Equation Editor object a plugin passes goes anyway, since EMBEDDED/EQUATION strips it. A plugin's output for an object's storage must be a compound file, whose storages and streams then take the storage's place. Where the rewrite cannot change the container, as for an object stored in a PowerPoint record, the output keeps the file as it arrived, so a plugin's `scrubbed` or `removed` there fails the output check.
+A file goes whatever the overrides say about these findings. A file no plugin accepts gets the rule it gets without plugins, such as EMBEDDED/OLE_OBJECT, and a picture, which no rule names, stays. A file whose plugin failed gets that rule too, and goes.
 
-The findings a plugin returns go into the report with their `location` after the file's own and with `attachment` naming the file. A `reject` inside the file becomes `strip`, since the file goes and the file holding it stays. Each scores at its `weight`. The upload's score leaves out PLUGIN_PASSED and PLUGIN_SCRUBBED, and the output's counts them. The check of the output does not ask the plugins again. It matches each file by the MD5 of its bytes against what the plugins kept, and reports the `outputFindings` the plugin gave for it.
+A plugin's answer is final. A file a plugin passed, scrubbed or removed gets none of office-defuse's own findings: no EMBEDDED/PACKAGE, EMBEDDED/OLE_OBJECT or EMBEDDED/EQUATION, and no MACRO/VBA_PROJECT for `vbaProject.bin`. office-defuse does not look inside it either, so an object's storage is not searched for VBA projects or other objects. An Equation Editor object a plugin passes stays. Through file-defuse no plugin takes a bare object storage, so EMBEDDED/EQUATION still removes one there. A plugin's output for an object's storage must be a compound file, whose storages and streams then take the storage's place. Where the rewrite cannot change the container, as for an object stored in a PowerPoint record, the output keeps the file as it arrived, so a plugin's `scrubbed` or `removed` there fails the output check.
+
+The findings a plugin returns go into the report with their `location` after the file's own and with `attachment` naming the file. A `reject` inside the file becomes `strip`, since the file goes and the file holding it stays. Each scores at its `weight`, and they are all the file adds to the score. PLUGIN_PASSED and PLUGIN_SCRUBBED weigh 0, in the upload's score and the output's. The check of the output does not ask the plugins again. It matches each file by the MD5 of its bytes against what the plugins kept, and reports the `outputFindings` the plugin gave for it.
 
 The plugin context has `depth`, the file's depth in the upload, and `deadline`, which every file of the upload shares. An error with `code: 'DEFUSE_LIMIT'` or `code: 'DEFUSE_IO'` from a plugin stops the whole upload. At depth 0, a limit becomes LIMIT/TIME or LIMIT/NESTING_DEPTH, and an I/O error is thrown as its cause.
 
@@ -262,6 +301,42 @@ 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.
+
+When a plugin passed or removed every module, the answers are final. The report holds MACRO/PLUGIN_PASSED and PLUGIN_REMOVED with the plugins' findings, and no MACRO/VBA_PROJECT, and the project scores what the plugins found in it. MACRO/VBA_PROJECT, at office-defuse's weight, reports a project with a module no plugin took or a plugin failed on, or one office-defuse removes for a reason of its own, such as a user form that holds an ActiveX control.
+
+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. Once the plugins answered for the project, kept or removed, these findings weigh 0, since the plugins scored the macros they run.
+
+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:
@@ -382,6 +457,8 @@ Three combinations add more. Code here means macros or DDE. Code or a run-progra
 
 The bands are NONE at 0, LOW from 1, MEDIUM from 25, HIGH from 50 and CRITICAL from 80. `scoreWeights` and `scoreBands` change them. A finding of a kind office-defuse does not make, such as one from another package, scores at its `weight`, or 0 without one.
 
+Content a plugin answered for scores at the weights of the plugin's findings alone, as [File plugins](#file-plugins) and [Script plugins](#script-plugins) describe. A workbook whose VBA project script-defuse keeps scores only what is left, such as the 10 of MACRO/COMPILED_CODE.
+
 ## Options
 
 | Option | Default | Purpose |
@@ -402,6 +479,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 +525,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

@@ -1,6 +1,6 @@
-import type { RunContext, RunState } from './context';
+import type { Reported, RunContext, RunState } from './context';
 import { SpillSink } from './io';
-import { type DefuseFinding, type OfficeOptions, type PluginContext } from './types';
+import { OfficeCategory as C, OfficeDetail as D, type DefuseFinding, type OfficeOptions, type PluginContext } from './types';
 /** The key under which office-defuse hands its run's options to a plugin. No other package can name it. */
 export declare const RUN_OPTIONS: unique symbol;
 /** A plugin context as office-defuse makes it. */
@@ -10,6 +10,11 @@ export type RunPluginContext = PluginContext & {
 /** What the plugins decided about a file inside the file. Undefined from `decideContained` means no plugin took it. */
 export interface ContainedDecision {
     keep: boolean;
+    /**
+     * A plugin passed, cleaned or removed the file. Its answer is final: the report holds it and what the plugin found,
+     * and office-defuse reports nothing of its own about the file.
+     */
+    answered?: boolean;
     /** The bytes a plugin kept in place of the file's own. */
     replacement?: SpillSink;
 }
@@ -22,6 +27,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.
@@ -38,9 +48,9 @@ export declare function pushContained(ctx: RunContext, found: DefuseFinding[] |
  */
 export declare function decideContained(ctx: RunContext, inner: InnerFile): Promise<ContainedDecision | undefined>;
 /**
- * The rule a file gets for being there, such as EMBEDDED/OLE_OBJECT, applies when no plugin took the file. A plugin
- * that kept the file turns those findings to info, since the content stays.
+ * Reports the rule a file gets for being there, such as EMBEDDED/OLE_OBJECT, when no plugin answered for the file. A
+ * plugin's answer is final: when one answered, nothing is reported, and the result only says whether the file stays.
  */
-export declare function presence(decision: ContainedDecision | undefined): 'info' | undefined;
+export declare function ownFinding(ctx: RunContext, decision: ContainedDecision | undefined, category: C, detail: D, location: string, data?: Record<string, string | number>): Reported;
 /** Bytes in a spill sink the run holds until it ends, as the rewrite takes a plugin's output. */
 export declare function spillOf(run: RunState, bytes: Uint8Array): Promise<SpillSink>;

package/dist/contained.js

@@ -1,9 +1,10 @@
 "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;
+exports.ownFinding = ownFinding;
 exports.spillOf = spillOf;
 const errors_1 = require("./errors");
 const io_1 = require("./io");
@@ -64,7 +65,7 @@ async function decideContained(ctx, inner) {
         if (expected) {
             ctx.report(types_1.OfficeCategory.Embedded, expected.result === 'passed' ? types_1.OfficeDetail.PluginPassed : types_1.OfficeDetail.PluginScrubbed, inner.location, { plugin: expected.plugin, name: name ?? '' });
             pushContained(ctx, expected.findings, inner.location, name);
-            return { keep: true };
+            return { keep: true, answered: true };
         }
         if (!plugins.length)
             return undefined;
@@ -107,6 +108,7 @@ async function decideContained(ctx, inner) {
                     }
                     else
                         ctx.removal(types_1.OfficeCategory.Embedded, r.result === 'removed' ? types_1.OfficeDetail.PluginRemoved : types_1.OfficeDetail.PluginFailed, inner.location, data);
+                    const answered = keep || r.result === 'removed';
                     pushContained(ctx, r.findings, inner.location, name);
                     const replacement = keep && out.length > 0 ? out : undefined;
                     if (replacement) {
@@ -116,7 +118,7 @@ async function decideContained(ctx, inner) {
                     }
                     else
                         await out.dispose();
-                    return { keep, replacement };
+                    return { keep, replacement, answered };
                 }
                 catch (e) {
                     await out.dispose();
@@ -136,11 +138,13 @@ async function decideContained(ctx, inner) {
     }
 }
 /**
- * The rule a file gets for being there, such as EMBEDDED/OLE_OBJECT, applies when no plugin took the file. A plugin
- * that kept the file turns those findings to info, since the content stays.
+ * Reports the rule a file gets for being there, such as EMBEDDED/OLE_OBJECT, when no plugin answered for the file. A
+ * plugin's answer is final: when one answered, nothing is reported, and the result only says whether the file stays.
  */
-function presence(decision) {
-    return decision?.keep ? 'info' : undefined;
+function ownFinding(ctx, decision, category, detail, location, data) {
+    if (decision?.answered)
+        return { action: decision.keep ? 'info' : 'strip' };
+    return ctx.report(category, detail, location, data);
 }
 /** Bytes in a spill sink the run holds until it ends, as the rewrite takes a plugin's output. */
 async function spillOf(run, bytes) {

package/dist/context.d.ts

@@ -68,15 +68,17 @@ export interface RunState {
     kept: Map<string, Expected>;
     /** Plugin output that waits for the rewrite. The run disposes of it when it ends. */
     held: SpillSink[];
-    /**
-     * Findings whose content a plugin kept, such as EMBEDDED/PACKAGE for a package a plugin passed. They stay in the
-     * report as info and leave the score to what the plugin found, as pdf-defuse leaves out a kept attached file.
-     */
-    superseded: WeakSet<DefuseFinding>;
     /** Sources the rewrite reads from, such as a compound file a plugin returned, which the run closes when it ends. */
     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;
+    /** The script plugins answered for the document's own VBA project, whether they kept it or removed it. */
+    macrosAnswered?: boolean;
 }
 /** A finding the rules made, with its action, which the rewrite reads. Past 200 of one kind, `finding` is absent. */
 export interface Reported {
@@ -115,11 +117,23 @@ export declare class RunContext {
     withPlan(): PlanContext;
     /**
      * Records a finding. Past 200 of one kind, as in pdf-defuse, one more finding counts the rest. `action` replaces the
-     * action the overrides give, for content whose fate a plugin decided.
+     * action the overrides give, for content whose fate a plugin decided. Such a finding as info weighs nothing.
      */
     report(category: C, detail: D, location?: string, data?: Record<string, string | number>, action?: OfficeFindingAction): Reported;
+    /**
+     * Reports a link, callback or field that runs the macro `name`. When the script plugins answered for the document's
+     * own VBA project, a trigger of one of its macros follows their answer: it stays, as info, when they kept the
+     * project, and the overrides decide it when they removed the project. Either way it weighs nothing, since the
+     * plugins scored the macro it runs.
+     */
+    macroTrigger(category: C, detail: D, location: string, data: Record<string, string | number>, name: string | undefined): Reported;
     /** Reports content that goes whatever the overrides say: its action is strip, or reject when the caller asked for that. */
     removal(category: C, detail: D, location?: string, data?: Record<string, string | number>): Reported;
+    /**
+     * Takes back a finding reported before a plugin answered for its content, whose answer is final. A finding past the
+     * first 200 of its kind was only counted, so there is none to take back.
+     */
+    retract(finding: DefuseFinding | undefined): void;
     /** Adds findings from another package as they are, such as those a plugin made inside a file. */
     push(findings: DefuseFinding[]): void;
     /** Reports a link, classified by pdf-defuse's checks of its target. */

package/dist/context.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZipContext = exports.PlanContext = exports.RunContext = exports.clip = void 0;
 const links_1 = require("./links");
 const plan_1 = require("./plan");
+const score_1 = require("./score");
 const types_1 = require("./types");
 const xml_1 = require("./xml");
 const OLE_SIGNATURE = [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1];
@@ -12,6 +13,8 @@ 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;
 /** What one inspection holds while the format rules run. */
 class RunContext {
     factory;
@@ -51,7 +54,7 @@ class RunContext {
     }
     /**
      * Records a finding. Past 200 of one kind, as in pdf-defuse, one more finding counts the rest. `action` replaces the
-     * action the overrides give, for content whose fate a plugin decided.
+     * action the overrides give, for content whose fate a plugin decided. Such a finding as info weighs nothing.
      */
     report(category, detail, location, data, action) {
         const act = action ?? this.factory.actionFor(category, detail);
@@ -64,7 +67,7 @@ class RunContext {
             const finding = this.factory.make(category, detail, location, data);
             finding.action = act;
             if (action === 'info')
-                this.run.superseded.add(finding);
+                (0, score_1.pluginDecided)(finding);
             this.shared.findings.push(finding);
             return { action: act, finding };
         }
@@ -76,17 +79,39 @@ class RunContext {
             const finding = this.factory.make(category, detail, 'additional occurrences', counted);
             finding.action = act;
             if (action === 'info')
-                this.run.superseded.add(finding);
+                (0, score_1.pluginDecided)(finding);
             this.shared.findings.push(finding);
         }
         counted.count = Number(counted.count) + 1;
         return { action: act };
     }
+    /**
+     * Reports a link, callback or field that runs the macro `name`. When the script plugins answered for the document's
+     * own VBA project, a trigger of one of its macros follows their answer: it stays, as info, when they kept the
+     * project, and the overrides decide it when they removed the project. Either way it weighs nothing, since the
+     * plugins scored the macro it runs.
+     */
+    macroTrigger(category, detail, location, data, name) {
+        const own = name !== undefined && this.run.macrosAnswered === true && OWN_MACRO.test(name.trim());
+        const r = this.report(category, detail, location, data, own && this.run.macrosKept ? 'info' : undefined);
+        if (own && r.finding)
+            (0, score_1.pluginDecided)(r.finding);
+        return r;
+    }
     /** Reports content that goes whatever the overrides say: its action is strip, or reject when the caller asked for that. */
     removal(category, detail, location, data) {
         const act = this.factory.actionFor(category, detail);
         return this.report(category, detail, location, data, act === 'info' ? 'strip' : act);
     }
+    /**
+     * Takes back a finding reported before a plugin answered for its content, whose answer is final. A finding past the
+     * first 200 of its kind was only counted, so there is none to take back.
+     */
+    retract(finding) {
+        const i = finding ? this.shared.findings.indexOf(finding) : -1;
+        if (i >= 0)
+            this.shared.findings.splice(i, 1);
+    }
     /** Adds findings from another package as they are, such as those a plugin made inside a file. */
     push(findings) {
         this.shared.findings.push(...findings);

package/dist/engine.js

@@ -59,21 +59,21 @@ const xmlLimitsOf = (limits) => ({
     entityExpansions: limits.xmlEntityExpansions,
     entitySize: limits.xmlEntitySize,
 });
-const PLUGIN_KEPT = new Set([types_1.OfficeDetail.PluginPassed, types_1.OfficeDetail.PluginScrubbed]);
 /**
  * `incomplete` marks a run that stopped before it read the whole package. It is rejected without a score, whatever
  * the actions say, because an override can make the finding that stopped it look harmless. In the check of an output,
  * `isOutput`, the files plugins kept count in the score; in an upload they do not, and a file a plugin cleaned makes
  * the upload strippable, since the output must be written.
  */
-function finish(findings, options, incomplete, format, isOutput = false, superseded) {
+function finish(findings, options, incomplete, format, isOutput = false) {
     const named = { format: format?.format ?? '', mimeType: format?.mimeType ?? '' };
     if (incomplete)
         return { status: 'rejected', score: null, risk: types_1.OfficeRisk.Unknown, findings, ...named };
     const rejected = findings.some(f => f.action === 'reject');
     const strippable = findings.some(f => f.action === 'strip' || (!isOutput && f.detail === types_1.OfficeDetail.PluginScrubbed));
-    const scored = findings.filter(f => !superseded?.has(f) && (isOutput || !PLUGIN_KEPT.has(f.detail)));
-    const { score, risk } = (0, score_1.scoreFindings)(scored, options);
+    // What a plugin decided counts at the weights of the plugin's own findings; the PLUGIN_* findings that record its
+    // answer weigh nothing.
+    const { score, risk } = (0, score_1.scoreFindings)(findings, options);
     return { status: rejected ? 'rejected' : strippable ? 'strippable' : 'clean', score, risk, findings, ...named };
 }
 /**
@@ -167,7 +167,6 @@ function newRun(options, depth, deadline, verify) {
         verify,
         kept: new Map(),
         held: [],
-        superseded: new WeakSet(),
         sources: [],
     };
 }
@@ -246,7 +245,7 @@ async function analyze(run, source) {
         findings.push(...ctx.findings);
         if (run.temp.ioError !== undefined)
             throw run.temp.ioError;
-        return finish(findings, options, false, ctx.format, isOutput, run.superseded);
+        return finish(findings, options, false, ctx.format, isOutput);
     }
     catch (e) {
         if (src.failure !== undefined)
@@ -401,6 +400,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.macroTrigger(types_1.OfficeCategory.Field, types_1.OfficeDetail.Macrobutton, location, { ...data, macro: (0, context_1.clip)(words[1]?.text ?? '') }, 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', 0, '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');
@@ -133,12 +137,14 @@ def(types_1.OfficeCategory.Embedded, types_1.OfficeDetail.Applet, 'strip', 60, '
 def(types_1.OfficeCategory.Embedded, types_1.OfficeDetail.Plugin, 'strip', 50, 'An embedded browser plug-in object');
 def(types_1.OfficeCategory.Embedded, types_1.OfficeDetail.Equation, 'strip', 70, 'An Equation Editor 3.0 object, which CVE-2017-11882 and CVE-2018-0802 exploit');
 def(types_1.OfficeCategory.Embedded, types_1.OfficeDetail.Attachment, 'strip', 30, '<An attached file "{name}"|An attached file> (<{type}|unknown type>)');
-def(types_1.OfficeCategory.Embedded, types_1.OfficeDetail.PluginPassed, 'info', 20, 'An embedded file was kept by <plugin {plugin}|a plugin> with nothing removed');
-def(types_1.OfficeCategory.Embedded, types_1.OfficeDetail.PluginScrubbed, 'info', 10, 'An embedded file was cleaned and kept by <plugin {plugin}|a plugin>');
+def(types_1.OfficeCategory.Embedded, types_1.OfficeDetail.PluginPassed, 'info', 0, 'An embedded file was kept by <plugin {plugin}|a plugin> with nothing removed');
+def(types_1.OfficeCategory.Embedded, types_1.OfficeDetail.PluginScrubbed, 'info', 0, 'An embedded file was cleaned and kept by <plugin {plugin}|a plugin>');
 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/flat.js

@@ -281,13 +281,10 @@ async function decideBinaries(ctx, odf) {
         const object = plan.objects.find(o => o.index === parent.index);
         if (object) {
             decided.add(parent.index);
-            if (decision?.keep) {
-                if (object.finding) {
-                    object.finding.action = 'info';
-                    ctx.run.superseded.add(object.finding);
-                }
-            }
-            else if (decision || object.strips)
+            // A plugin's answer on the object's file is final, so the object's own finding is taken back.
+            if (decision?.answered)
+                ctx.retract(object.finding);
+            if (!decision?.keep && (decision || object.strips))
                 plan.element(exports.FLAT_ODF_PART, parent.index, { remove: true });
         }
         else if (decision && !decision.keep)