Check an Excel file for macros and external links before opening

Why an unopened .xlsx deserves inspection

The extension is useful but incomplete. A normal macro-free workbook is usually named .xlsx; an Excel macro-enabled workbook is normally .xlsm. Yet a filename is not a trust decision. Files are renamed, archives can be constructed outside Excel, and a package can contain parts that deserve review even when its extension looks routine.

A workbook can carry a VBA project in a binary part commonly named xl/vbaProject.bin. Excel may use it to store VBA code, forms, and related project data. Workbooks can also contain external-link definitions. Those definitions tell Excel that formulas or named items refer to another workbook or a remote target. When opened, a spreadsheet program may prompt to update links or resolve a connection, depending on the file and application settings.

Neither finding proves intent. Finance teams often use approved linked workbooks; legacy models may require signed macros. The useful policy is simpler: unexpected executable or external behavior is an exception that needs an owner and a reason.

OOXML is a ZIP container

An OOXML workbook is a ZIP archive containing XML documents, relationship files, and sometimes binary payloads. Listing its entries reads the directory of the archive; it does not launch Excel, calculate formulas, refresh links, or run VBA. Copy the file to a controlled working directory and use a ZIP lister:

unzip -l suspicious-workbook.xlsx

# On systems with bsdtar:
bsdtar -tf suspicious-workbook.xlsx

Avoid extracting into a shared directory until you need to examine a specific text part. Listing first keeps the action narrow and creates an easily saved record. Do not use Excel's preview pane as an inspection technique; the point is to avoid invoking a spreadsheet application until the package evidence has been reviewed.

Search for the structural signals

The listing becomes practical when it is filtered for the paths that change your handling decision. The following shell snippet makes no modification to the source workbook. It records the ZIP listing, then returns matching part names.

unzip -l suspicious-workbook.xlsx | tee workbook-contents.txt
unzip -l suspicious-workbook.xlsx | \
  rg 'xl/vbaProject\.bin|xl/externalLinks/|xl/connections\.xml|xl/embeddings/|\.rels$'

If your environment does not have rg, replace it with grep -E. Treat a no-match result as “these named paths were not found,” not as a comprehensive safety finding. Structure can vary across producers, and a ZIP listing says nothing about the intent or exploitability of content inside a part.

A safe read-only inspection workflow

1. Preserve the original. Save the received file without opening it. Record its source, filename, size, and a SHA-256 hash so later reviewers know exactly what was checked.
2. Confirm it is a ZIP-based workbook. Run file workbook.xlsx and unzip -t workbook.xlsx. The test checks archive integrity; it does not certify safety.
3. List, then classify. Search for the macro, external-link, connection, embedding, and relationship paths above. Keep the command output with the ticket or intake record.
4. Read a small XML part only when needed. Extract a selected relationship or external-link XML file to standard output, for example unzip -p workbook.xlsx xl/_rels/workbook.xml.rels. This exposes relationship metadata without launching Excel.
5. Make a policy decision. Expected, approved links can proceed under normal controls. Unexpected macros, connections, or embedded objects should go to the sender, security process, or isolated analysis environment—not a user who is being asked to click Enable Content.

Hashing is especially helpful when a sender replaces a file. Two files with the same displayed name are not necessarily the same evidence. On macOS and Linux, use shasum -a 256 workbook.xlsx; on Windows PowerShell, use Get-FileHash workbook.xlsx -Algorithm SHA256.

Automate the structural gate in CI

CI is a good fit when a repository accepts spreadsheets as deliverables, fixtures, templates, or vendor uploads. The job should not claim to scan for malware. Its narrow purpose is to prevent an unreviewed workbook structure from silently entering a release or approval flow. Store the report as a build artifact and fail only on the policy signals your team has agreed to.

#!/usr/bin/env bash
set -euo pipefail

workbook="$1"
report="workbook-structure.txt"

unzip -t "$workbook" > /dev/null
unzip -l "$workbook" | tee "$report"

if unzip -l "$workbook" | rg -q 'xl/vbaProject\.bin'; then
  echo "Macro project detected: review required" >&2
  exit 20
fi

if unzip -l "$workbook" | rg -q 'xl/externalLinks/|xl/connections\.xml'; then
  echo "External dependency signal detected: review required" >&2
  exit 21
fi

A nonzero status here means “requires review,” not “malicious.” That distinction prevents a noisy security control from becoming untrusted. If macro-enabled files are allowed in one directory, scope the exception to that directory, require a reviewer, and preserve the resulting report. Do not weaken the gate globally because one legacy workbook is expected.

Call an inspection API from a pipeline

A service can centralize the report format, but it does not remove the need to protect confidential files. Start with a non-production sample, configure authentication through your CI secret store when required, and save only the resulting structural report. A minimal request shape is:

curl --fail --show-error --silent \
  --form "file=@workbook.xlsx" \
  https://api.lifestep.io/inspect

Check the API documentation and retention terms before sending sensitive payroll, customer, health, or financial data to any external service. For high-sensitivity files, prefer a local tool or an approved internal environment. Automation should create a reviewable decision trail, not move sensitive data to an unknown place merely to make a check convenient.

Common questions

Can an .xlsx really contain macros?

Standard Excel naming conventions reserve macro-enabled content for .xlsm, but the extension alone is not a reliable control. Inspect the actual package and enforce an organizational policy based on the evidence, source, and expected business purpose.

Do external links mean the workbook is unsafe?

No. They mean the workbook has an external dependency signal. A linked planning model may be legitimate; a link in a document from an unknown sender may be a reason to stop. Context decides the response.

Does unzip -l execute the spreadsheet?

No. It lists ZIP entries. It does not open the workbook in Excel, calculate formulas, refresh data, or run VBA. Still use normal endpoint protections because structural inspection is only one layer of a file-handling process.

Is this malware analysis?

No. This guide identifies package structure only. It does not deobfuscate VBA, emulate execution, classify a payload, find every exploit, or determine whether a workbook is benign. Use approved security tooling and incident procedures for that work.