Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
version: 2
updates:
- package-ecosystem: gomod
directory: /
schedule:
interval: weekly
- package-ecosystem: github-actions
directory: /
schedule:
interval: weekly
75 changes: 75 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
name: CI

# Runs on every push to main and every pull request: formatting, vet, the
# test suite, a short fuzzing pass over the main parsers, and a check that the
# PyPI wheels can still be built from release-style archives.
on:
push:
branches: [main]
pull_request:

permissions:
contents: read

jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
- uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
with:
go-version-file: go.mod

- name: gofmt
run: |
out="$(gofmt -l $(git ls-files '*.go'))"
if [ -n "$out" ]; then echo "not gofmt-formatted:"; echo "$out"; exit 1; fi

- run: go vet ./...
- run: go test ./...

fuzz:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
include:
- { pkg: ".", target: FuzzAnalyzeBytes }
- { pkg: ".", target: FuzzAnalyzeVBScript }
- { pkg: ".", target: FuzzOneNote }
- { pkg: "./extractor", target: FuzzRTF }
- { pkg: "./extractor", target: FuzzBIFF }
- { pkg: "./payload", target: FuzzDeobfuscateBatch }
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
- uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
with:
go-version-file: go.mod
- name: Fuzz ${{ matrix.target }} for 30s
run: go test -run '^$' -fuzz "^${{ matrix.target }}\$" -fuzztime 30s "${{ matrix.pkg }}"

wheels:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
- uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
with:
go-version-file: go.mod
- name: Build release-style archives and wheels
run: |
VERSION="$(sed -n 's/^var Version = "\(.*\)"/\1/p' analyze.go)"
mkdir -p dist
for p in windows/amd64 windows/arm64 linux/amd64 linux/arm64 darwin/amd64 darwin/arm64; do
os="${p%/*}"; arch="${p#*/}"; name="maldocTrace_${VERSION}_${os}_${arch}"
bin=maldocTrace; [ "$os" = windows ] && bin=maldocTrace.exe
mkdir -p "stage/$name"
GOOS=$os GOARCH=$arch CGO_ENABLED=0 go build -trimpath -ldflags "-s -w" -o "stage/$name/$bin" ./cmd/maldoctrace
if [ "$os" = windows ]; then (cd stage && zip -qr "../dist/$name.zip" "$name"); else tar -C stage -czf "dist/$name.tar.gz" "$name"; fi
done
python3 python/build_wheels.py --version "$VERSION" --dist dist --out wheels
- name: Install the Linux wheel and run it
run: |
python3 -m venv venv
venv/bin/pip install wheels/*manylinux*x86_64*.whl
venv/bin/maldoctrace version
venv/bin/python -c "import maldoctrace; print(maldoctrace.__version__, maldoctrace.find_binary())"
59 changes: 50 additions & 9 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,21 +2,24 @@ name: Release

# Pushing a tag such as v0.1.0 tests the code, builds MaldocTrace for
# Windows, Linux and macOS, and publishes a GitHub Release with the archives,
# SHA-256 checksums and the matching CHANGELOG.md section as release notes.
# SHA-256 checksums, build provenance attestations and the matching
# CHANGELOG.md section as release notes. The same binaries are then wrapped
# in platform wheels and published to PyPI as the `maldoctrace` package
# (trusted publishing from the `pypi` environment; no token is stored).
on:
push:
tags:
- "v*"

permissions:
contents: write
contents: read

jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
- uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
with:
go-version-file: go.mod
- run: go vet ./...
Expand All @@ -35,8 +38,8 @@ jobs:
- { goos: darwin, goarch: amd64 }
- { goos: darwin, goarch: arm64 }
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
- uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
with:
go-version-file: go.mod

Expand All @@ -60,7 +63,7 @@ jobs:
tar -czf "../dist/$NAME.tar.gz" "$NAME"
fi

- uses: actions/upload-artifact@v4
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
with:
name: dist-${{ matrix.goos }}-${{ matrix.goarch }}
path: dist/*
Expand All @@ -69,10 +72,14 @@ jobs:
release:
needs: build
runs-on: ubuntu-latest
permissions:
contents: write
id-token: write
attestations: write
steps:
- uses: actions/checkout@v4
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4

- uses: actions/download-artifact@v4
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
with:
pattern: dist-*
path: dist
Expand All @@ -84,6 +91,11 @@ jobs:
sha256sum * > checksums.txt
cat checksums.txt

- name: Attest build provenance
uses: actions/attest-build-provenance@e8998f949152b193b063cb0ec769d69d929409be # v2
with:
subject-path: dist/maldocTrace_*

- name: Release notes from CHANGELOG.md
run: |
VERSION="${GITHUB_REF_NAME#v}"
Expand All @@ -107,3 +119,32 @@ jobs:
--title "MaldocTrace $GITHUB_REF_NAME" \
--notes-file notes.md \
--verify-tag

pypi:
needs: release
runs-on: ubuntu-latest
environment:
name: pypi
url: https://pypi.org/project/maldoctrace/
permissions:
contents: read
id-token: write
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4

- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
with:
pattern: dist-*
path: dist
merge-multiple: true

- name: Build wheels from the release binaries
run: |
VERSION="${GITHUB_REF_NAME#v}"
python3 python/build_wheels.py --version "$VERSION" --dist dist --out wheels
ls -l wheels

- name: Publish to PyPI
uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1
with:
packages-dir: wheels/
22 changes: 20 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),

## [Unreleased]

Coverage fixes from 14 recent MalwareBazaar OneNote droppers (IcedID, Emotet, Qakbot, Gozi, MetaStealer): commands are now recovered from all the script-based ones.
## [0.6.0] - 2026-11-20

Coverage fixes from 14 recent MalwareBazaar OneNote droppers (IcedID, Emotet, Qakbot, Gozi, MetaStealer): commands are now recovered from all the script-based ones. MaldocTrace is now also published on PyPI, and release archives carry build provenance attestations.

### Downloads

| Platform | Archive |
|---|---|
| Windows x64 / ARM64 | `maldocTrace_0.6.0_windows_amd64.zip`, `maldocTrace_0.6.0_windows_arm64.zip` |
| Linux x64 / ARM64 | `maldocTrace_0.6.0_linux_amd64.tar.gz`, `maldocTrace_0.6.0_linux_arm64.tar.gz` |
| macOS Intel / Apple Silicon | `maldocTrace_0.6.0_darwin_amd64.tar.gz`, `maldocTrace_0.6.0_darwin_arm64.tar.gz` |

Or install with `pip install maldoctrace` (also `pipx` / `uv tool install`): the wheels contain these same binaries.

You can verify downloads against `checksums.txt` (SHA-256), or check that an archive was built by the release workflow with `gh attestation verify <archive> --repo debugactiveprocess/MaldocTrace`. The binaries are static and have no dependencies. The macOS builds are not notarized, so remove the quarantine flag before running them: `xattr -d com.apple.quarantine maldocTrace`.

### Added

Expand All @@ -15,6 +29,8 @@ Coverage fixes from 14 recent MalwareBazaar OneNote droppers (IcedID, Emotet, Qa
- **MSI packages** and **CHM help files** are classified and reported as `embedded_executable`.
- `onenote_encrypted_data` finding (suspicious): embedded data that is encrypted or random and of no known type, as in a password-protected section.
- Emulation: `Err` object (`Err.Number` is 0), `Shell.Application.Open`, `FileSystemObject` path helpers (`GetParentFolderName`, `GetFileName`, `GetBaseName`, `GetExtensionName`). Text written through `CreateTextFile` is captured as one artifact when the stream is closed and returned by `ReadAll`.
- **PyPI package** `maldoctrace`: platform wheels (Windows, Linux, macOS; x64 and ARM64) that install the release binary as the `maldoctrace` command, plus a small Python API (`maldoctrace.analyze()`, `maldoctrace.analyze_bytes()`) that returns the JSON report as a dict.
- Release archives get a GitHub build provenance attestation (`gh attestation verify`). Continuous integration runs formatting, vet, the tests and a short fuzzing pass on every pull request. `SECURITY.md` describes how to report vulnerabilities privately.

### Fixed

Expand All @@ -23,6 +39,7 @@ Coverage fixes from 14 recent MalwareBazaar OneNote droppers (IcedID, Emotet, Qa
- Encrypted or random data was reported as shellcode because two-byte XOR decoder patterns occur in it by chance; on high-entropy data only stubs at the start are considered.
- VBA/VBScript runtime: `Dim a, b, c` and `Public a, b` declared only the first name; a module-level variable assigned inside a procedure became a local; `Split` with an empty delimiter returned characters instead of the whole string; `obj.Run (cmd), 0, True` failed to parse; `FileSystemObject.GetTempName` returned a path instead of a bare name and could not be read without parentheses.
- URLs no longer swallow a following `|` or `^` (`...p.ps1|iex`).
- A compound file whose header declares a huge FAT or mini FAT sector count made the parser try to allocate terabytes and crash the process; buffers are now sized from the file length (found by fuzzing).

## [0.5.1] - 2026-11-14

Expand Down Expand Up @@ -294,7 +311,8 @@ You can verify downloads against `checksums.txt` (SHA-256). The binaries are sta
- `--dump-payloads DIR` to write decoded payloads and dropped files with neutral extensions and a `manifest.json`.
- **Robustness**: each pipeline stage recovers from panics and records them as diagnostics. The VBA pipeline and container parsers are fuzzed.

[Unreleased]: https://github.com/debugactiveprocess/MaldocTrace/compare/v0.5.1...HEAD
[Unreleased]: https://github.com/debugactiveprocess/MaldocTrace/compare/v0.6.0...HEAD
[0.6.0]: https://github.com/debugactiveprocess/MaldocTrace/releases/tag/v0.6.0
[0.5.1]: https://github.com/debugactiveprocess/MaldocTrace/releases/tag/v0.5.1
[0.5.0]: https://github.com/debugactiveprocess/MaldocTrace/releases/tag/v0.5.0
[0.4.0]: https://github.com/debugactiveprocess/MaldocTrace/releases/tag/v0.4.0
Expand Down
25 changes: 23 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,9 @@ Prebuilt binaries for **Windows**, **Linux** and **macOS** (x64 and ARM64) are o
With a package manager:

```bash
# Any platform with Python 3.8+ (PyPI; the wheel contains the same static binary)
pip install maldoctrace # or: pipx install maldoctrace / uv tool install maldoctrace

# macOS / Linux (Homebrew)
brew install debugactiveprocess/tap/maldoctrace

Expand All @@ -85,7 +88,7 @@ Requires Go 1.23+. Dependencies: `golang.org/x/text` and, for 7z archives, [`git
Install a tagged release:

```bash
go install github.com/debugactiveprocess/MaldocTrace/cmd/maldoctrace@v0.5.1
go install github.com/debugactiveprocess/MaldocTrace/cmd/maldoctrace@v0.6.0
```

Or build from a release tarball or a clone:
Expand Down Expand Up @@ -478,7 +481,25 @@ Inputs that made the fuzzers fail are kept under `testdata/fuzz/` as permanent r
git push origin vX.Y.Z
```

The [release workflow](.github/workflows/release.yml) then runs the tests and builds static binaries for Windows, Linux and macOS (amd64/arm64), stamping each with the version from the tag. It publishes a GitHub Release with the archives, `checksums.txt` and that CHANGELOG section as notes. A tag without a matching CHANGELOG section fails instead of publishing an empty release.
The [release workflow](.github/workflows/release.yml) then runs the tests and builds static binaries for Windows, Linux and macOS (amd64/arm64), stamping each with the version from the tag. It publishes a GitHub Release with the archives, `checksums.txt`, build provenance attestations and that CHANGELOG section as notes, then wraps the same binaries in wheels ([python/](python/)) and publishes them to PyPI as `maldoctrace` through trusted publishing. A tag without a matching CHANGELOG section fails instead of publishing an empty release.

Prebuilt binaries can be checked against their attestation:

```bash
gh attestation verify maldocTrace_<version>_linux_amd64.tar.gz --repo debugactiveprocess/MaldocTrace
```

### Python API

The PyPI package also exposes the analyzer to Python; it runs the bundled binary and returns the JSON report:

```python
import maldoctrace

report = maldoctrace.analyze("sample.one")
print(report["verdict"], report["risk_score"])
report = maldoctrace.analyze_bytes(data, name="invoice.xls", passwords=["infected"])
```

## Acknowledgements

Expand Down
33 changes: 33 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Security policy

MaldocTrace parses hostile files by design, so bugs in its parsers and emulator are security bugs: a crash, hang, excessive memory use or path traversal triggered by a crafted document can be used to blind a triage pipeline or to attack the machine that runs it.

## Supported versions

Security fixes go into the latest release. Please check that a problem still happens with the latest version (or `main`) before reporting it.

## Reporting a vulnerability

Please report vulnerabilities privately through GitHub: open the [Security tab](https://github.com/debugactiveprocess/MaldocTrace/security) of the repository and choose **Report a vulnerability**. Do not open a public issue for them.

Useful details:

- the MaldocTrace version (`maldoctrace version`) and platform;
- the command line you used;
- a minimal input that triggers the problem. If it is a live malware sample, send its SHA-256 (and where it can be obtained, such as MalwareBazaar) rather than the file, or attach it in a password-protected archive (password `infected`).

You should get a first answer within a week. Once a fix is released, the advisory is published with credit to the reporter, unless you prefer to stay anonymous.

## Scope

In scope: crashes, hangs, unbounded resource use, files written outside the `--dump-payloads` directory, and any way a sample could get MaldocTrace to execute code or contact the network. MaldocTrace never runs the sample and never makes network requests; anything that breaks either rule is a vulnerability.

Out of scope: samples that MaldocTrace fails to detect or misclassifies. Please report those as regular issues, ideally with a SHA-256.

## Verifying releases

Each release lists SHA-256 checksums in `checksums.txt`, and every archive carries a GitHub build provenance attestation. To check that an archive was built by this repository's release workflow:

```bash
gh attestation verify maldocTrace_<version>_linux_amd64.tar.gz --repo debugactiveprocess/MaldocTrace
```
2 changes: 1 addition & 1 deletion analyze.go
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ import (

// Version is the tool version reported in output. Release builds set it
// from the git tag: -ldflags "-X maldoctrace.Version=1.2.3".
var Version = "0.5.1"
var Version = "0.6.0"

// Options configures an analysis run.
type Options struct {
Expand Down
8 changes: 8 additions & 0 deletions debian/changelog
Original file line number Diff line number Diff line change
@@ -1,3 +1,11 @@
maldoctrace (0.6.0-0kali1) kali-dev; urgency=medium

* New upstream release: OneNote droppers are followed through their
VBScript stages, batch scripts are deobfuscated, and ISO, MSI and CHM
files are recognized. See CHANGELOG.md.

-- Ialle Teixeira <49375302+debugactiveprocess@users.noreply.github.com> Fri, 20 Nov 2026 12:00:00 -0300

maldoctrace (0.5.1-0kali1) kali-dev; urgency=medium

* New upstream release: Word altChunk imports are analysed, and Equation
Expand Down
2 changes: 1 addition & 1 deletion debian/maldoctrace.1
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.TH MALDOCTRACE 1 "November 2026" "maldoctrace 0.5.1" "User Commands"
.TH MALDOCTRACE 1 "November 2026" "maldoctrace 0.6.0" "User Commands"
.SH NAME
maldoctrace \- analyze malicious Office documents by emulating VBA and Excel 4.0 macros
.SH SYNOPSIS
Expand Down
11 changes: 9 additions & 2 deletions extractor/cfb.go
Original file line number Diff line number Diff line change
Expand Up @@ -121,8 +121,11 @@ func parseCFB(data []byte, lim *Limits) (*cfbReader, error) {
if numFatSectors == 0 {
numFatSectors = uint32(len(difat))
}
fat := make([]uint32, 0, int(numFatSectors)*int(r.sectorSize/4))
// The sector counts come from the header and cannot be trusted: a file
// can hold at most len(data)/sectorSize sectors, so size buffers from that.
maxSectors := uint32(len(data)/int(r.sectorSize)) + 1
maxFatEntries := int(lim.MaxContainerEntries) * 128
fat := make([]uint32, 0, min(int(min(numFatSectors, maxSectors, uint32(len(difat))))*int(r.sectorSize/4), maxFatEntries))
for i := 0; i < len(difat) && i < int(numFatSectors); i++ {
sect := difat[i]
if sect > maxRegularSector {
Expand All @@ -146,7 +149,8 @@ func parseCFB(data []byte, lim *Limits) (*cfbReader, error) {
}
// Read mini FAT.
if numMiniFat > 0 && firstMiniFat <= maxRegularSector {
miniFat := make([]uint32, 0, int(numMiniFat)*int(r.sectorSize/4))
numMiniFat = min(numMiniFat, maxSectors)
miniFat := make([]uint32, 0, min(int(numMiniFat)*int(r.sectorSize/4), maxFatEntries))
cur = firstMiniFat
for i := 0; cur <= maxRegularSector && i < int(numMiniFat); i++ {
b, err := r.readSectorBytes(cur)
Expand All @@ -155,6 +159,9 @@ func parseCFB(data []byte, lim *Limits) (*cfbReader, error) {
}
for j := 0; j+4 <= len(b); j += 4 {
miniFat = append(miniFat, binary.LittleEndian.Uint32(b[j:]))
if len(miniFat) > maxFatEntries {
return nil, Wrap("cfb", ErrLimitExceeded)
}
}
cur = r.nextSector(cur)
}
Expand Down
Loading
Loading