Skip to main content

QuickSand is a module to scan streams inside documents with Yara

Project description

QuickSand Version 2

QuickSand Python Package and Command Line Tool

QuickSand is a Python-based analysis framework to analyze suspected malware documents to identify exploits in streams of different encodings or compressions. QuickSand supports documents, PDFs, Mime/Email, Postscript and other common formats. A built-in command line tool can process a single document or directory of documents.

QuickSand scans within the decoded streams of documents and PDFs using Yara signatures to identify exploits or high risk active content.

A hosted version is available to try without any installation at scan.tylabs.com.

Files:

  • src/quicksand/quicksand.py: Main quicksand class and CLI tool

  • src/quicksand/quicksand_exe.yara: Yara rules to detect executables.

  • src/quicksand/quicksand_exploits.yara: Yara rules to detect exploits in documents.

  • src/quicksand/quicksand_pdf.yara: Yara rules to detect exploits in PDFs.

  • bin/quicksand: Command line tool.

  • requirements.txt: Python dependencies

  • lambda/ Optional AWS Lambda functions

With Thanks to the Creators of:

  • pdfreader

  • oletools

  • cryptography

  • zipfile38

  • olefile

  • yara-python

  • yara

Installation from Pypi using pip

pip3 install quicksand

Upgrade from Pypi using pip

pip3 install --upgrade quicksand

Install from source

If you want to install from the source, such as the uicksand-main.zip downloaded from GitHub:

pip3 install quicksand-main.zip

Command Line Usage

A command line tool for quicksand to process and output json or txt results.

usage: quicksand [-h] [-v] [-c] [-y] [-t TIMEOUT] [-e EXPLOIT] [-x EXE] [-a PDF] [-f {json,txt}] [-o OUT] [-p PASSWORD]
                 [-d DROPDIR]
                 document

QuickSand Document and PDF maldoc analysis tool.

positional arguments:
  document              document or directory to scan

optional arguments:
  -h, --help            show this help message and exit
  -v, --verbose         increase output verbosity
  -c, --capture         capture stream content
  -y, --yara            capture yara matched strings
  -t TIMEOUT, --timeout TIMEOUT
                        timeout in seconds
  -e EXPLOIT, --exploit EXPLOIT
                        yara exploit signatures
  -x EXE, --exe EXE     yara executable signatures
  -a PDF, --pdf PDF     yara PDF signatures
  -f {json,txt}, --format {json,txt}
                        output format
  -o OUT, --out OUT     save output to this filename
  -p PASSWORD, --password PASSWORD
                        password to decrypt ole or pdf
  -d DROPDIR, --dropdir DROPDIR
                        save objects to this directory

Process a single file

quicksand document.doc

Process a directory of files

quicksand malware/

Python Module Usage

File from memory

from quicksand.quicksand import quicksand
import pprint

qs = quicksand(data, timeout=18, strings=True)
qs.process()
pprint.pprint(qs.results)

Processing using a filename

from quicksand.quicksand import quicksand

qs2 = quicksand("file.doc")
qs2.process()
qs.results

Process a Directory

from quicksand.quicksand import quicksand
qs = quicksand.readDir("malware")
qs

Returns a dictionary of {filename: qs_results,...}.

Optional initializer values

  • capture: True|False return content of extracted streams

  • debug: True|False print debugging messages to stdout

  • exploityara: Path to exploit yara rules

  • execyara: Path to executable yara rules

  • pdfyara: PDF Exploits yara rules

  • password: Password for encrypted documents/PDFs

  • timeout: Timeout processing: 0 for unlimited.

Scoring

Documents are scored based on the rank value in the associated Yara signature metadata.

Additionally, each signature defines whether the detected item is an exploit, a warning or a risky feature. For more information on how to interpret the results, please see https://scan.tylabs.com/howto.

If you add your own signatures, they don't need to include the extra metadata to function.

zlib issues on MacOS

MacOS users may get zlib issues (PDF FlateDecode etc) due to missing OpenSSL headers since MacOs 10.4.

zlib.error: Error -3 while decompressing data: unknown compression method
zlib.error: Error -3 while decompressing data: incorrect header check

One solution is to install zlib with Brew.sh and reinstall Python 3 using pyenv:

export LDFLAGS="-L/usr/local/opt/zlib/lib"
export CPPFLAGS="-I/usr/local/opt/zlib/include"
pyenv install 3.8.5

Using Quicksand?

Let us know @tylabs

Issues and Project Home

QuickSand GitHub

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

quicksand-2.0.13.tar.gz (35.4 kB view details)

Uploaded Source

Built Distribution

quicksand-2.0.13-py3-none-any.whl (34.3 kB view details)

Uploaded Python 3

File details

Details for the file quicksand-2.0.13.tar.gz.

File metadata

  • Download URL: quicksand-2.0.13.tar.gz
  • Upload date:
  • Size: 35.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.1 importlib_metadata/4.6.1 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.61.1 CPython/3.8.5

File hashes

Hashes for quicksand-2.0.13.tar.gz
Algorithm Hash digest
SHA256 316e26b8797fa844d7558a19c45c3b715356b037159bb090ce229bfb97972ab9
MD5 8e87b6f58c910f4a0c345ae29b294839
BLAKE2b-256 e4ba9acb5446cf0bc32b797ae72ac2bb694ae4496450cc85d5d46f376e1c9400

See more details on using hashes here.

File details

Details for the file quicksand-2.0.13-py3-none-any.whl.

File metadata

  • Download URL: quicksand-2.0.13-py3-none-any.whl
  • Upload date:
  • Size: 34.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.1 importlib_metadata/4.6.1 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.61.1 CPython/3.8.5

File hashes

Hashes for quicksand-2.0.13-py3-none-any.whl
Algorithm Hash digest
SHA256 9ad7644feb15896e37e6c1756173da601576d68479ad1119826f72ef64ca8dea
MD5 e743edf9d5acc3354a4b35e95c39c8ae
BLAKE2b-256 2cfc9efbef07a4b9cd9adfbc8dce7ae52b3a060ef237ca32e6dca92f179622fb

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page