PRODUCT GUIDE

VBA Modernization Assessment

A local, source-based assessment for workbooks your organization already owns and trusts.

Before starting

Only use known, trusted internal workbooks or exported VBA. Do not use third-party, suspicious or unknown files. This tool is not malware analysis.

Requirements

Python 3.12 or later and a local command prompt.
oletools 0.60.2 for .xlsm extraction.
Organization-owned, trusted internal .xlsm or exported VBA source.
Enough local disk space for input and temporary analysis copies. A workbook over 50 MB is refused.

A packaged download and free preflight are not available in this preview. The commands below describe the current source checkout and should be verified again against the release package.

Installation

From the VBA source directory, install the declared dependency into a Python 3.12+ environment:

python -m pip install -r requirements.txt

Keep dependency installation separate from sensitive workbooks. The CLI itself does not upload workbook content.

First run

Choose one known internal workbook. Run the command from the VBA directory:

python -m src assess path/to/book.xlsm --trusted-internal --output assessment

Open assessment/assessment.html locally. The flag is your declaration that the file is trusted; the tool cannot verify where it came from.

Trusted-internal requirement

The input must belong to your organization, be already trusted and come from a known internal source. Never run this against stranger downloads, attachments of uncertain origin, outside customer files or malware samples.

Static analysis uses a separate process and resource limits. Those controls do not form an operating-system file/network sandbox for a compromised parser.

Command examples

One workbook

python -m src assess path/to/book.xlsm --trusted-internal --output assessment

Exported VBA with its workbook structure

python -m src assess path/to/modules --workbook path/to/book.xlsm --trusted-internal --output assessment

Batch

python -m src batch path/to/input-folder --trusted-internal --output assessment-batch

Batch scans immediate .xlsm files and VBA module directories. It does not automatically pair each exported-source directory with a workbook. For non-UTF-8 exported source, add an encoding such as --encoding cp932.

Reading the report

Single assessment writes assessment.json, assessment.html, blockers.csv and manual-actions.md. Batch also writes index.html, batch-summary.json and batch-summary.csv.

Status fields are separate judgments
Field / value	Meaning
`migration_status: BLOCKED`	Source-based migration blockers were found.
`REVIEW_REQUIRED`	Some findings require human judgment.
`LOW_FRICTION_CANDIDATE`	Fewer blockers were identified; migration success is not guaranteed.
`NO_VBA_PROJECT`	No VBA project was found in the inspected workbook.
`inspection_status: INSPECTION_INCOMPLETE`	Extraction or structure inspection did not complete. Do not treat missing findings as clearance.
`pcode_trust_status: NOT_VERIFIED`	VBA source and P-code equivalence was not checked. This is separate from migration blockers.
`NOT_APPLICABLE / UNKNOWN`	No P-code comparison applies, or inspection could not establish a trust status.

status is a compatibility alias for migration_status. A complete inspection does not prove source safety or target behavior.

Common errors

Missing --trusted-internal: The CLI refuses to run until you explicitly declare the allowed input scope.
Extraction or structure failure: Check whether the file is a valid supported workbook, encrypted, damaged or above a size/resource limit. Keep the result as INSPECTION_INCOMPLETE; do not infer that it has no blockers.
Unexpected source text: For exported modules, retry with the correct --encoding. Do not alter source merely to obtain a favorable status.
Missing sheet/table reference: Check the actual workbook and dynamic references manually. A static check cannot resolve every runtime target.

FAQ

Which workbooks can I assess?

Only .xlsm workbooks or exported VBA that your organization owns, already trusts and obtained from a known internal source. Unknown or external files are outside the supported boundary.

Does the tool run macros or create Office Scripts?

No. It performs a static, source-based assessment and does not generate converted code.

Does a low-friction result guarantee migration?

No. Test the original workflow and any replacement in Excel and the target environment.

Is P-code checked against the source?

No. Read pcode_trust_status separately. NOT_VERIFIED is expected when source and P-code have not been compared.

Where does workbook data go?

The current analysis path runs locally without telemetry or workbook upload. Temporary copies are removed after processing; reports omit VBA source, cell values and external-link URLs.

Is a free preflight available now?

No. A limited, local preflight is planned and must be implemented and validated before any download or purchase flow is enabled.

Uninstall / remove

Delete the source checkout or release directory and any reports you created. If you installed dependencies into a dedicated virtual environment, remove that environment too. Review locally saved reports under your own retention policy.