Merge pull request #16 from luckalgorithm/documentation

Add description for new parameters

Author: luckalgorithm

README.md

@@ -1,95 +1,38 @@
-# ByteBomber
-
-ByteBomber is a tool for creating ZIP bombs. A ZIP bomb is a highly compressed ZIP file that massively expands in size when extracted. ByteBomber is designed to demonstrate how compression algorithms (specifically ZIP's DEFLATE) can be used to exhaust system resources (disk space, RAM, or CPU), potentially crashing systems or causing instability.
+ByteBomber is a Python tool for creating ZIP bombs. It demonstrates how compression algorithms (specifically ZIP's DEFLATE) can exploit redundancy to create highly compressed files that expand drastically when extracted. It’s primarily for educational purposes to understand the impact of such files.
 
 ## Installation
 
-To install ByteBomber, run the following command: `pip install bytebomber` (Alternatively, use `pip3` if necessary.)
-
-Once installed, you can integrate ByteBomber into your own project by importing the `build_zip_bomb` function: `from bytebomber import build_zip_bomb`
-
-You can then call `build_zip_bomb()` in your code to generate ZIP bombs.
-
-## What ByteBomber Does
-
-1. Takes input for how big the uncompressed bomb should be.
-2. Takes input for how large each individual payload file should be.
-3. Generates a file filled with null bytes (`\x00`) of that size.
-4. Creates a ZIP archive containing that file duplicated many times.
-5. Applies DEFLATE compression to exploit redundancy.
-
-Since every payload file is identical and filled with zeroes, compression is extremely effective—producing a small ZIP file that expands drastically when extracted.
-
-## CLI
-
-When you run the script, you'll be prompted for the following:
-
-`Bomb decompressed size:`
-
-- This is the total uncompressed size you want the final ZIP bomb to expand to.
-- Default is 500 GB.
-
-`Payload file size:`
-
-- Size of the individual file inside the ZIP archive.
-- The smaller this is, the more files the ZIP bomb will contain.
-- Default is 1 MB.
+Install ByteBomber via pip: `pip install bytebomber`
 
-`Output zip name:`
+You can then use it in your project: `from bytebomber import build_zip_bomb`
 
-- Name of the final ZIP file to be created.
-- Default is `bomb.zip`.
+## Usage
 
-`Bomb directory name:`
-
-- Directory where files are extracted when the bomb is decompressed.
-- Default is `bomb-dir`.
-
-Use the format `<number> <unit>` when entering values (e.g., `500 GB`, `1 TB`).
-
-| Supported Unit | Size     | Size In Bytes                     |
-| -------------- | -------- | --------------------------------- |
-| B (byte)       | 1 B      | 1                                 |
-| KB (Kilobyte)  | 1,024 B  | 1,024                             |
-| MB (Megabyte)  | 1,024 KB | 1,048,576                         |
-| GB (Gigabyte)  | 1,024 MB | 1,073,741,824                     |
-| TB (Terabyte)  | 1,024 GB | 1,099,511,627,776                 |
-| PB (Petabyte)  | 1,024 TB | 1,125,899,906,842,624             |
-| EB (Exabyte)   | 1,024 PB | 1,152,921,504,606,846,976         |
-| ZB (Zettabyte) | 1,024 EB | 1,180,591,620,717,411,303,424     |
-| YB (Yottabyte) | 1,024 ZB | 1,208,925,819,614,629,174,706,176 |
-
-> [!NOTE]
-> For most purposes, GB or TB ranges are more than sufficient to stress a system. PB, EB, ZB, and YB represent astronomical data sizes far beyond what typical systems can handle.
-
-Once input is provided, a summary of the configuration is shown:
+Call `build_zip_bomb()` to create a ZIP bomb. You can pass several arguments to customize the behavior:
 
 ```
-Creating ZIP bomb:
-
-    Payload size:         1048576 bytes
-    Total uncompressed:   536870912000 bytes
-    File count:           512000
-    Output:               bomb.zip
+build_zip_bomb(
+    target_input="500 GB",
+    payload_input="1 MB",
+    zip_name="bomb.zip",
+    folder_name="bomb-dir",
+    verbose=True,
+    show_progress=True
+)
 ```
 
-- Payload size: Size of the file being copied inside the ZIP.
-- Total uncompressed: Target final size when the ZIP is extracted.
-- File count: How many copies of the payload file are added.
-- Output: Filename of the ZIP bomb.
-
-It will then show live progress as files are added to the ZIP.
-
-## What's in the ZIP
+| **Parameter** | Description |
+|----------------| ----------------------------------------------------------------------------------|
+| `target_input` | Total uncompressed size of the ZIP bomb. Default: prompts user or uses `"500 GB"`. |
+| `payload_input` | Size of each file inside the ZIP. Smaller values = more files. Default: prompts user or uses `"1 MB"`. |
+| `zip_name` | Output ZIP file name. Default: prompts user or uses `"bomb.zip"`. |
+| `folder_name` | Internal folder name for the payload files. Default: prompts user or uses `"bomb_dir"`. |
+| `verbose` | If `True`, shows config + summary output. Default: `True`. |
+| `show_progress` | If `True`, shows a live progress bar. Default: `True`. |
 
-Inside the ZIP there are tens of thousands to millions of identical files like:
+Use the format `<number> <unit>` when entering values (e.g., `500 GB`, `1 TB`). ByteBomber supports B, KB, MB, GB, TB, PB, EB, ZB, and YB. Valuse in the GB-TB range are usaully more than enough to stress a system. Values above TB are astronomical data zizes far more than most systems can handle.
 
-- 0.txt
-- 1.txt
-- 2.txt
-- ...
-
-All filled with null bytes. The compression algorithm detects repetition and compresses it heavily.
+> [!NOTE]
+> The program accepts values using standard units (e.g., MB, GB), but internally it treats them as binary units (e.g., MiB, GiB).
 
-> [!WARNING]
-> **ByteBomber is for educational purposes only. Do not deploy ZIP bombs on systems you do not own or have permission to test. Misuse can result in data loss or system damage.**
+**ByteBomber is for educational purposes only. Do not deploy ZIP bombs on systems you do not own or have permission to test. Misuse can result in data loss or system damage.**