QuickSand Python Package and Command-Line Tool
QuickSand is a fast, self-contained Python analysis framework for analyzing suspected malware documents and PDFs to identify exploits, obfuscated scripts, embedded executables, and high-risk active content across nested streams, encodings, and compressions.
QuickSand uses native Python standard-library binary parsers inside a single module (src/quicksand/quicksand.py) paired with YARA signatures (yara-python>=4.3.0 is the only external dependency).
A hosted version, developer REST API, and MCP server (malwaretracker-mcp) are available at malwaretracker.com.
- OLE2 Compound Files (
[MS-CFB]): Native parsing of.doc,.xls,.ppt,.msg, and HWP documents, including FAT/DIFAT/MiniFAT stream extraction,[MS-OLEPS]SummaryInformation/DocumentSummaryInformationmetadata extraction, and[MS-OXRTFCP]Outlook MAPI Compressed RTF (LZFu/MELA) decompression. - VBA Macros (
[MS-OVBA]): Native decompression of compressed VBA macro streams (Macros,_VBA_PROJECT_CUR,VBA) while also scanning raw streams to catch VBA stomping / p-code tampering. - Excel 4.0 (XLM) Macros (
[MS-XLS]): Native BIFF5/BIFF8 scanner forBOUNDSHEETmacro sheets,Auto_Open/Auto_Closebuilt-in labels,FORMULAtokens (EXEC,CALL,REGISTER,CHAR,GET.WORKSPACE),SST, andDCONNdata connections. - Encrypted Office Documents (
[MS-OFFCRYPTO]): Built-in detection and in-memory decryption of ECMA-376 Standard Encryption (AES-128/192/256 & CryptoAPI RC4) and Agile Encryption (XML v4.4) using user-supplied passwords and common malware passwords (such asVelvetSweatshop). - Rich Text Format (RTF): Native extraction of
\objdata,ods, anddatastorehex streams, OLE 1.0 objects (e.g., Equation EditorEquation.3), trailing\objdatapresentation streams (CVE-2025-21298), andOLEPackageembedded files (with resilience against RTF control-word obfuscation). - PDF Documents: Native stream parser and filter pipeline supporting
/FlateDecode(including PNG row predictors 10–15),/ASCIIHexDecode,/ASCII85Decode,/LZWDecode,/RunLengthDecode,#xxhex-escaped dictionary/filter names,/EmbeddedFilerecursive scanning, Widget/VBase64 payload decoding (CVE-2026-34621), and PDF 1.5+/ObjStmcompressed object streams. - OpenXML / ZIP / Archive Containers: Extraction and recursive analysis of
.docx,.xlsx,.pptx, embedded archives, password-protected ZIPs (both legacy PKWAREZipCryptoand WinZipAES-128/192/256/WZ_AESusing-pand built-in malware passwords likeinfectedandinfected1), ZIP entry filename manifests (CVE-2023-38831,CVE-2025-59689), WinRAR ADS path traversal (CVE-2025-8088), relationships (oleObject,aFChunk, external templates), and ActiveX controls. - CybercentreCanada CaRT (
.cart): Native, zero-dependency unpacking and recursive analysis of neutered malware transport containers (both default RC4 key and custom-p/ Base64 RC4 keys), including extraction of embedded JSON header/footer metadata and unpacked payload hashes. - MIME / MHT / ActiveMime / WordML (
mso): Base64 decoding and zlib inflation ofActiveMimeheaders and embedded payloads. - PostScript (
ps), OneNote (.one), Flash (CWS/FWS), & Windows Shell (.lnk,.library-ms,.settingcontent-ms): Hex/zlib payload extraction and embedded script, deserialization, NTLM coercion, and executable detection.
Because all format parsers in src/quicksand/quicksand.py are written in memory-safe pure Python with explicit bounds checks, document buffer-overflow exploits (such as Equation Editor stack overflows or RTF \fonttbl heap corruption) cannot corrupt memory in QuickSand. In addition, QuickSand enforces strict resource limits against parser Denial-of-Service (DoS) attacks:
- Decompression & Zip Bomb Protection: All
zlib, PDF/FlateDecode,/LZWDecode,/RunLengthDecode, MS-OVBA, and OpenXML ZIP stream reads are capped at 32 MB (MAX_DECOMPRESSED_STREAM_SIZE) with archive entry limits (MAX_ARCHIVE_ENTRIES = 1024). - Cycle & Depth Guards: OLE FAT/DIFAT/MiniFAT chains track visited sectors to prevent infinite loops, directory tree walks are depth-bounded, and recursive container analysis is capped at
MAX_NESTING_DEPTH = 10. - Header & Crypto Bounds: PDF PNG predictor column widths (
<= 65536), OLE sector shifts (512or4096bytes), and Agile Encryption KDFspinCount(<= 250,000) are validated, and<!DOCTYPE/<!ENTITYdeclarations are rejected to prevent XML Billion Laughs attacks.
src/quicksand/quicksand.py: Single-file QuickSand engine, native format parsers, and CLI entry point.src/quicksand/quicksand_exploits.yara: YARA signatures for Office, RTF, VBA, XLM, OpenXML, and OneNote exploits and warnings.src/quicksand/quicksand_pdf.yara: YARA signatures for PDF exploits, JavaScript obfuscation, and active content.src/quicksand/quicksand_exe.yara: YARA signatures for embedded PE/ELF binaries, LNK shortcuts, HTA/SCT scriptlets, and encoded payloads.bin/quicksand: Command-line wrapper script.quicksand.spec: PyInstaller specification for building standalone single-file executables (quicksand.exe,quicksand-linux-x86_64,quicksand-macos-arm64)..github/workflows/build-windows-exe.yml: GitHub Actions workflow for building standalone executables across Windows, Linux, and macOS..github/workflows/publish-pypi.yml: GitHub Actions workflow for building and publishing the Python package to PyPI.- gcloud/: Optional Google Cloud Run functions.
- lambda/: Optional AWS Lambda functions.
- Python
>= 3.7 yara-python >= 4.3.0
pip3 install quicksandpip3 install --upgrade quicksandgit clone https://github.com/tylabs/quicksand.git
cd quicksand
pip3 install .When installed via pip install . on Windows, pip automatically creates a quicksand.exe CLI wrapper in your Python Scripts\ directory.
To build a portable, single-file dist\quicksand.exe (which includes Python, yara-python, and all .yara rule files so no Python installation is required on the target machine):
pip install -r requirements.txt pyinstaller
pyinstaller --clean quicksand.specTip: The standalone
quicksand.exeuses its bundled.yararules automatically, or you can place customquicksand_exploits.yara,quicksand_exe.yara, orquicksand_pdf.yarafiles in the same folder asquicksand.exeto override them without rebuilding.
usage: quicksand [-h] [--version] [-v] [-c] [-y] [-t SECONDS] [-p PASSWORD]
[-d DIR] [-f {json,txt}] [-o FILE] [-e FILE] [-x FILE]
[-a FILE]
document
QuickSand v2.3.2 - Document and PDF malware analysis tool.
Scans nested streams inside Office (OLE2, OpenXML, RTF, VBA, XLM), PDF,
ZIP (including ZipCrypto & WinZip AES passwords), CaRT (.cart), MIME/ActiveMime,
PostScript, and OneNote files using YARA signatures.
positional arguments:
document path to a document file or directory of documents to
scan
options:
-h, --help show this help message and exit
--version show program's version number and exit
analysis & extraction options:
-v, --verbose enable verbose diagnostic logging during analysis
-c, --capture capture decoded stream contents in results
-y, --yara include matched YARA string offsets and previews in
output
-t SECONDS, --timeout SECONDS
per-file analysis timeout in seconds (default: 0 =
unlimited)
-p PASSWORD, --password PASSWORD
password for decrypting protected Office documents,
ZIP archives, and CaRT files
-d DIR, --dropdir DIR
directory to write extracted binary streams to
(implies --capture)
output options:
-f {json,txt}, --format {json,txt}
report output format: 'json' or 'txt' (default: json)
-o FILE, --out FILE write report output to FILE instead of stdout
custom YARA signature options:
-e FILE, --exploit FILE
custom path to exploit YARA rules (default: bundled
quicksand_exploits.yara)
-x FILE, --exe FILE custom path to executable YARA rules (default: bundled
quicksand_exe.yara)
-a FILE, --pdf FILE custom path to PDF YARA rules (default: bundled
quicksand_pdf.yara)
examples:
quicksand suspicious.doc
quicksand -f txt -y invoice.pdf
quicksand -p VelvetSweatshop encrypted.xls
quicksand -p infected1 sample.zip
quicksand sample.doc.cart
quicksand -d extracted_streams/ -o report.json samples_dir/
quicksand document.docquicksand -f txt -o report.txt malware_samples/quicksand -d extracted_streams/ suspicious.rtfimport pprint
from quicksand import quicksand
with open("document.doc", "rb") as f:
data = f.read()
qs = quicksand(data, timeout=18, strings=True)
qs.process()
pprint.pprint(qs.results)from quicksand import quicksand
qs = quicksand("file.pdf")
qs.process()
print(qs.results["risk"], qs.results["score"], qs.results["rating"])from quicksand import quicksand
results = quicksand.readDir("malware_samples/")Returns a dictionary mapping {filepath: qs.results, ...}.
capture(bool, defaultFalse): Store decoded stream bytes inresults["streams"].strings(bool, defaultTrue): Include matched YARA string offsets and previews inresults["results"].debug(bool, defaultFalse): Print debug trace messages during parsing.timeout(int, default0): Maximum processing time in seconds (0for unlimited).password(strorSequence[str], defaultNone): Password(s) to try when decrypting password-protected Office documents, ZIP archives (ZipCrypto&WZ_AES), and custom-key CaRT containers (tried before the built-in default password lists).exploityara,execyara,pdfyara(str, defaultNone): Custom paths to override the bundled YARA rule files.
Each YARA signature defines metadata classifying the detection (is_exploit, is_warning, is_feature, is_exe), a rank score weight, and MITRE ATT&CK® technique IDs (mitre).
To prevent double-counting when the same content appears in both a raw stream and a decompressed child stream, QuickSand deduplicates each rule's score contribution per document while recording all matching stream locations in results["results"].
| Rating | Risk Label | Criteria |
|---|---|---|
0 |
nothing detected |
score == 0 (only benign or informational rank = 0 features present) |
1 |
risky active content |
Low-to-moderate active content warnings (1 <= score < 6) |
2 |
high risk active content / risk of exploit |
Embedded executable (execute >= 1), single low-rank exploit indicator, or cumulative warning score >= 6 |
3 |
high risk of exploit |
Confirmed exploit with score >= 10, multiple distinct exploits (exploit >= 2), or executable paired with exploit/high warning score |
For live interactive scanning, REST API access, and MCP server integration, visit malwaretracker.com (API & MCP docs).
Let us know @tylabs