twbgc/sunzip

Provide secure unzip against zip bomb :bomb:.

SUNZIP

---

Introduction

Why are we doing this?

According to Cara Marie, an archive bomb a.k.a. A zip bomb is often employed to disable antivirus software, in order to create an opening for more traditional viruses. In addition, various kinds of pitfalls may occur during decompression.

Description for decompression pitfalls on zipfile doc

What is zip bomb?

It often appeared as a relatively small size zip file. And the unzipped file will be much larger than the zipped one. This would probably cause a problem when your disk volume or memory is relatively small than the unzipped one.

How do we defense zip bomb?

• Defense Layer 1 - checks perform on the server side.

    1. Check if it's a nested zip file. (i.e. 42.zip)
    2. Check if the compression ratio (Uncompressed Content/Compressed Content)
       is greater than the threshold?
    3. Check if the file format is expected for context.
    4. Upload file size does not exceed the maximum limit.

• Defense Layer 2 - limit the number of resources available to the process and its children.

    1. Check if CPU time is greater than the threshold.
    2. Check if the extracted part in memory is oversized. (memory usage)

• Defense Layer 3 - filetype-specific mitigations.

  Filetype: Archives

    1. Restrict output file size and number of extracted files
       to ensure the total doesn't exceed the maximum limit.

How do we set thresholds?

Defense Layer 1:
  Uncompressed content size:  200 MB (vt)
  Compression ratio:          https://youtu.be/IXkX2ojrKZQ?t=553

Defense Layer 2:
  CPU time:                   2 seconds(vt)
  Memoery oversized:

Defense Layer 3:
  Output file size:
  Number of extracted files:

Useful resources

Bomb Codes
https://bomb.codes/

Mitigation Summary
https://youtu.be/IXkX2ojrKZQ?t=1296

Defense layers
https://bomb.codes/mitigations

Install

$ pip3 install sunzip

# for development use "development mode"
# https://packaging.python.org/tutorials/installing-packages/
$ pip3 install -e <directory to project root>

Usage

# for command line usage see the help
$ sunzip-cli -h

You can find the arguments defined at the top of cli.py

import sunzip

f = sunzip.Sunzip("archive.zip")

Customize your resource limit.

Maximum compression ratio threshold

f.threshold = 50

Maximum CPU time (second)

f.cpu = 1

Maximum memory usage (byte)

f.memory = 1024

Maximum file size (byte)

f.filesize = 1024

If there is no setting, the default value will be used.

extract() would perform a series of the above checks before decompression. If all pass, the zip file will be decompressed.

import sunzip

f = sunzip.Sunzip("archive.zip")

f.extract()

sunzip's Issues

Error : division by zero

When the file size in the compressed archive is 0, it will be wrong.

Tag and publish fix #1

Hello!

I would like to use this package for my side project and I'm currently encountering the divide by zero error fixed in #1 . Could you tag the repository and publish a v0.0.2 so I can pick up the update? Tagging will help others find out which commit the package is built off of.

Thanks!

bug in check_is_nested

the function returns after just checking the first file, instead of checking all the files
PR: #8

Error when using the example code

Hello, i have installed sunzip on my windows computer using "pip install sunzip" and i got an error when using this example code :

import sunzip

f = sunzip.Sunzip("archive.zip")

f.extract()

the error

Traceback (most recent call last):
  File "c:\Users\*****\Desktop\sunzip\sunzip.py", line 1, in <module>
    import sunzip
  File "c:\Users\*****\Desktop\sunzip\sunzip.py", line 3, in <module>
    f = sunzip.Sunzip("archive.zip")
        ^^^^^^^^^^^^^
AttributeError: partially initialized module 'sunzip' has no attribute 'Sunzip' (most likely due to a circular import). Did you mean: 'sunzip'?

Thanks !

Please clarify the license, setup.py contradicts itself

I looked for a LICENSE or COPYING file but wasn't able to find one. I checked setup.py and found two contradictory license statements:

• license='MIT', in the keyword arguments to setup()
• "License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)" in the classifiers list

Could you please choose one and place the corresponding text in a LICENSE file under the root of the repository?