From: norly <ny-git@enpas.org>
Date: Thu, 14 Feb 2019 11:28:07 +0000 (+0100)
Subject: Add README.md
X-Git-Url: https://git.enpas.org/?p=amiga-uae-virus-scan.git;a=commitdiff_plain;h=7f06301736d9f9164a6a8f4d29c7f4b18f7e70a2

Add README.md
---

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8034130
--- /dev/null
+++ b/README.md
@@ -0,0 +1,96 @@
+UAE based Amiga virus scanner for POSIX
+========================================
+
+
+What is this contraption?
+--------------------------
+
+A command line based Amiga virus scanner for Linux and similar systems.
+
+Usage:
+
+Either of
+
+    ./amiga-uae-virus-scan.sh floppy-to-test.adf
+
+or
+
+    ./amiga-uae-virus-scan.sh directory-to-scan
+
+
+What this can, and cannot scan
+-------------------------------
+
+Anything that CheckX, XAD, and XFD understand.
+
+This includes entire ADF files.
+However note that floppy images will be exposed to CheckX
+as *files* rather than be mounted, thus rendering it
+incapable of e.g. scanning IPF files.
+
+This script will scan only one element at a time, but that
+can be an entire folder structure.
+
+
+If you wish to scan raw floppies in strange image formats
+which are understood by FS-UAE, but not by CheckX, then
+change the script to mount the image as `DF1:`
+(see `write_uae_config()`), and to have it scan that drive
+rather than a folder structure (see `populate_dh0()`).
+
+
+Theory of operation
+--------------------
+
+This is a script that:
+
+ - prepares a virtual Amiga hard drive,
+ - installs a virus scanner onto it,
+ - copies the files to be scanned onto it,
+ - runs FS-UAE,
+ - and finally prints the results to stdout.
+
+If you abort the process by pressing Ctrl+C, there will be
+stale files in /tmp.
+
+
+Dependencies
+-------------
+
+The script will automatically download several archives from
+Aminet unless they have already been cached locally.
+
+See `installer_urls` for details.
+
+
+Security
+---------
+
+The files downloaded from Aminet are checked against local
+SHA-256 checksums.
+
+Files to be analyzed are copied into the virtual system first,
+to ensure that we do not have to grant it access to host files.
+Thus, even if something exploits a security issue in the Amiga
+virus scanner, it won't be able to break the host unless it
+also breaks FS-UAE.
+
+
+
+Thanks
+=======
+
+Acknowledgements go out to the authors of the software used,
+as well as to Aminet for hosting it.
+
+Thanks also to the UAE authors, and of course to the AROS
+kickstart hackers.
+
+This would not be possible without you.
+
+
+
+License
+========
+
+GNU General Public License v2 only.