Implement managed browser security, individual agents and observability

docs/office-macro-inspection.md

@@ -0,0 +1,33 @@
+# Office macro download inspection
+
+With central YARA enabled, `security.yara.scanOfficeMacros` defaults to true.
+The contained local scanner matches the same administrator rules against original
+bytes, unpacked VBA projects, contiguous OLE streams (including compiled data),
+and decompressed VBA source. It does not execute macros or retain source code.
+
+Admins can turn this additional extraction off independently of YARA. ICAP remains
+mandatory when enabled; all enabled scanners must approve the exact downloaded
+bytes before the browser offers to save them. A matching rule blocks the file.
+Benign VBA is not blocked simply because a macro exists. Archive, stream, module,
+code and runtime budgets bound parsing; failures do not become clean results.
+
+The default incoming document-DLP requirement remains conservative. Office rendered
+content is not completely classified. To allow incoming Office after malware
+inspection, an admin can explicitly disable `fileTransfers.download.requireDocumentDlp`
+in Download inspection and publish the policy. This affects incoming document DLP;
+upload checks remain enforced. At least one malware scanner is still required.
+Explicit no-antivirus mode continues to require complete document DLP.
+
+Supported local extraction targets ordinary VBA projects in OOXML and OLE. XLM,
+XLSB, encrypted/corrupt projects and embedded Office containers remain unsupported
+and block when extraction is enabled. Source matching cannot establish source/p-code
+equivalence or detect every obfuscated macro; ICAP/AV remains a complementary layer.
+
+A pinned benign XlsxWriter fixture verifies that a source-only YARA marker absent
+from original ZIP bytes blocks after extraction, while an unmatched benign project
+allows the malware gate. The same two outcomes are tested inside Windows AppContainer.
+Dependencies are four curated hash-pinned wheels in requirements-macros.lock.txt;
+optional p-code/XLM tools are not installed or invoked.
+
+Extraction follows [olevba's source extraction API](https://github.com/decalage2/oletools/blob/master/oletools/doc/olevba.md)
+and bounded [MS-OVBA compression](https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-ovba/ec1bc788-27de-47d9-8db4-6be2b5cff52b).