From 3ce6e494bfc7558e06b2b0e3867ec78c4eb06286 Mon Sep 17 00:00:00 2001
From: AlexSSD7 <alexandersadovskyi7@protonmail.com>
Date: Thu, 28 Sep 2023 10:59:04 +0100
Subject: [PATCH] Document faulty block size detection serious bug

---
 README.md                                     |  8 +++++
 serious-bug-disclosures/README.md             | 11 +++++++
 .../faulty-block-size-detection.md            | 29 +++++++++++++++++++
 3 files changed, 48 insertions(+)
 create mode 100644 serious-bug-disclosures/README.md
 create mode 100644 serious-bug-disclosures/faulty-block-size-detection.md

diff --git a/README.md b/README.md
index 8f938be..9442bb5 100644
--- a/README.md
+++ b/README.md
@@ -42,6 +42,14 @@ Linsk relies on network file shares to expose files to the host machine. Below a
 - **Windows** - See [USAGE_WINDOWS.md](USAGE_WINDOWS.md).
 - **macOS** - See [USAGE_MACOS.md](USAGE_MACOS.md).
 
+# ⚠️ Serious bug disclosures (Obsolete versions)
+
+Linsk versions below **v1.1.0** are considered obsolete **UNLESS**:
+* The use of Linsk was limited exclusively to devices with a 512-byte logical block (sector) size.
+* The experimental USB passthrough was used.
+
+More information: [serious-bug-disclosures/README.md](serious-bug-disclosures/README.md)
+
 # 👨‍💻 Contributing
 
 Please see [CONTRIBUTING.md](CONTRIBUTING.md).
diff --git a/serious-bug-disclosures/README.md b/serious-bug-disclosures/README.md
new file mode 100644
index 0000000..fad11c9
--- /dev/null
+++ b/serious-bug-disclosures/README.md
@@ -0,0 +1,11 @@
+# Serious bug disclosures
+
+## Obsolete versions (Summary)
+
+Linsk versions below **v1.1.0** are considered obsolete **UNLESS**:
+* The use of Linsk was limited exclusively to devices with a 512-byte logical block (sector) size.
+* The experimental USB passthrough was used.
+
+## Index
+
+* [Faulty raw device block size detection](faulty-block-size-detection.md) (Fixed in: **v1.1.0**, Affected: **<v1.1.0**, Severity: **High**)
\ No newline at end of file
diff --git a/serious-bug-disclosures/faulty-block-size-detection.md b/serious-bug-disclosures/faulty-block-size-detection.md
new file mode 100644
index 0000000..1f217b0
--- /dev/null
+++ b/serious-bug-disclosures/faulty-block-size-detection.md
@@ -0,0 +1,29 @@
+# Serious bug: Faulty raw device block size detection
+
+## Key Aspects
+
+* **Affected versions**: below v1.1.0.
+* **Affected *UNLESS***:
+  * The use of Linsk was limited exclusively to devices with a 512-byte logical block (sector) size.
+  * The experimental USB passthrough was used.
+* **Possible outcomes**: A disk may be locked to Linsk after writing a considerable amount of data through Linsk. This means that the disk will not be accessible by any Linux machine, unless a 512-byte block size is emulated. Reformat is required to recover from this condition.
+* **Severity**: Although there is **no data loss**, the severity can be considered as **High**.
+
+## Brief description
+
+Prior to version v1.1.0, Linsk assumed that the block size detection was done by QEMU. However, that wasn't the case. QEMU used a default block size of 512 bytes, no matter the physical/logical block (sector) size of the actual drive.
+
+Originally, this was not an issue as the emulated block size of 512 bytes did not hinder mounting, reading, and writing the files to the disk. However, if a significant amount of writes were committed to the drive, the OS may attempt to optimize the file system(s). This is a problem since all possible optimizations will assume the emulated 512-byte block size to be the real logical block size. If this happens, the drive will get effectively locked to the emulated block size of 512 bytes. In that case, the host OS that recognizes a valid block size of over 512 bytes will not be able to access the files and/or recognize any of the filesystems in the disk.
+
+The solution to recover from this condition is to copy the files to another (temporary) drive through Linsk, reformat the original, broken drive, and copy the files back to the place.
+
+## Compatibility
+
+Linsk v1.1.0 is packaged with a custom `dev_faulty_bs` device type that preserves the original behavior that implied the use of the faulty block size detection. This should not be used for anything else but to recover the files from a drive that was locked to the emulated 512-byte block size.
+
+Example use:
+```sh
+sudo linsk run dev_faulty_bs:/dev/diskX vdb3
+```
+
+Notice the change from `dev` to `dev_faulty_bs`.
\ No newline at end of file