README.md

   1 UAE based Amiga virus scanner for POSIX
   2 ========================================
   3
   4
   5 What is this contraption?
   6 --------------------------
   7
   8 A command line based Amiga virus scanner for Linux and similar systems.
   9
  10 Usage:
  11
  12 Either of
  13
  14     ./amiga-uae-virus-scan.sh floppy-to-test.adf
  15
  16 or
  17
  18     ./amiga-uae-virus-scan.sh directory-to-scan
  19
  20
  21 What this can, and cannot scan
  22 -------------------------------
  23
  24 Anything that CheckX, XAD, and XFD understand.
  25
  26 This includes entire ADF files.
  27 However note that floppy images will be exposed to CheckX
  28 as *files* rather than be mounted, thus rendering it
  29 incapable of e.g. scanning IPF files.
  30
  31 This script will scan only one element at a time, but that
  32 can be an entire folder structure.
  33
  34
  35 If you wish to scan raw floppies in strange image formats
  36 which are understood by FS-UAE, but not by CheckX, then
  37 change the script to mount the image as `DF1:`
  38 (see `write_uae_config()`), and to have it scan that drive
  39 rather than a folder structure (see `populate_dh0()`).
  40
  41
  42 Theory of operation
  43 --------------------
  44
  45 This is a script that:
  46
  47  - prepares a virtual Amiga hard drive,
  48  - installs a virus scanner onto it,
  49  - copies the files to be scanned onto it,
  50  - runs FS-UAE,
  51  - and finally prints the results to stdout.
  52
  53 If you abort the process by pressing Ctrl+C, there will be
  54 stale files in /tmp.
  55
  56
  57 Libraries used
  58 ---------------
  59
  60 This script makes use of the following tools and libraries:
  61
  62  - CheckX - the virus scanner
  63  - xvs.library - virus signature collection
  64  - xadmaster.library - archive unpacker (`.lha`, `.adf`, ...)
  65  - xfdmaster.library - decruncher (for packed executables, ...)
  66  - UAEquit - to shut down the emulator when done.
  67
  68
  69 Dependencies
  70 -------------
  71
  72 The script will automatically download several archives from
  73 Aminet unless they have already been cached locally.
  74
  75 See `installer_urls` for details.
  76
  77 It requires the following tools to be installed on the host:
  78
  79     curl
  80     lha
  81     fs-uae
  82     sha256sum
  83
  84
  85 Security
  86 ---------
  87
  88 The files downloaded from Aminet are checked against local
  89 SHA-256 checksums.
  90
  91 Files to be analyzed are copied into the virtual system first,
  92 to ensure that we do not have to grant it access to host files.
  93 Thus, even if something exploits a security issue in the Amiga
  94 virus scanner, it won't be able to break the host unless it
  95 also breaks FS-UAE.
  96
  97
  98 Comparison to similar tools
  99 ----------------------------
 100
 101 - ADFscan: The original inspiration for this project.
 102   This is a Visual Basic application scanning for only a
 103   handful of the most common signatures. It has its own
 104   unpacker for Amiga OFS to be able to scan ADFs.
 105
 106   + amiga-uae-virus-scan uses well-known Amiga libraries and
 107     tools to perform these tasks, allowing it to detect more
 108     viruses and unpack more formats, by order(s) of magnitude.
 109
 110
 111
 112 Thanks
 113 =======
 114
 115 Acknowledgements go out to the authors of the software used,
 116 as well as to Aminet for hosting it.
 117
 118 Thanks also to the UAE authors, and of course to the AROS
 119 kickstart hackers.
 120
 121 This would not be possible without you.
 122
 123
 124
 125 License
 126 ========
 127
 128 GNU General Public License v2 only.