1. clamav-devel
  2. Commit ceef37d3b68ca64a2e5a29a980c87e14790d5cc6
Browse code

jira-191 - dev/0.101 - expanding upon on-access documentation

Mickey Sola authored on 2018/11/01 04:18:39
Showing 2 changed files
docs/UserManual/OnAccess.md
History View file @ ceef37d
... ... 
@@ -1,21 +1,115 @@
1 1 
 # On-Access Scanning
2 2
3 
+---
4 
+
3 5 
 ## Purpose
4 6
7 
+---
8 
+
5 9 
 This guide is for users interested in leveraging and understanding ClamAV's On-Access Scanning feature. It will walk through how to set up and use the On-Access Scanner and step through some common issues and their solutions.
6 10
11 
+---
12 
+
7 13 
 ## Requirements
8 14
15 
+---
16 
+
9 17 
 On-Access is only available on Linux systems. On Linux, On-Access requires a `kernel version >= 3.8`. This is because it leverages a kernel api called [fanotify](http://man7.org/linux/man-pages/man7/fanotify.7.html) to perform its blocking.
10 18
19 
+---
20 
+
21 
+## General Use
22 
+
23 
+---
24 
+
25 
+To use ClamAV's On-Access Scanner, simply open `clamd.conf`, set the `ScanOnAccess` option to `yes`, and then specify the path(s) you would like to recursively watch with the `OnAccessIncludePath` option. Finally, set `OnAccessPrevention` to `yes`. Then, run `clamd` with elevated permissions (e.g. `sudo clamd`). If all went well, the On-Access scanner will now be actively protecting the specified path(s). You can test this by dropping an eicar file into the specified path, and attempting to read/access it (e.g. `cat eicar.txt`). This will result in an "Operation not permitted" message, triggered by fanotify blocking the access attempt at the kernel level.
26 
+
27 
+---
28 
+
11 29 
 ## Troubleshooting
30 
+---
31 
+
32 
+Some OS distributors have disabled fanotify, despite kernel support. You can check for fanotify support on your kernel by running the command:
33 
+
34 
+> $ cat /boot/config-<kernel_version> | grep FANOTIFY
35 
+
36 
+You should see the following:
37 
+
38 
+```
39 
+CONFIG_FANOTIFY=y
40 
+CONFIG_FANOTIFY_ACCESS_PERMISSIONS=y
41 
+```
42 
+
43 
+If you see:
44 
+
45 
+```
46 
+# CONFIG_FANOTIFY_ACCESS_PERMISSIONS is not set
47 
+```
48 
+
49 
+Then ClamAV's On-Access Scanner will still function, scanning and alerting on files normally in real time. However, it will be unable to block access attempts on malicious files. We call this `notify-only` mode.
50 
+
51 
+---
52 
+
53 
+ClamAV's On-Access Scanning system uses a scheme called Dynamic Directory Determination (DDD for short) which is a shorthand way of saying that it tracks the layout of every directory specified with `OnAccessIncludePath` dynamically, and recursively, in real time. It does this by leveraging [inotify](http://man7.org/linux/man-pages/man7/inotify.7.html) which by default has a limited number of watchpoints available for use by a process at any given time. Given the complexity of some directory hierarchies, ClamAV may warn you that it has exhausted its supply of inotify watchpoints (8192 by default). To increase the number of inotify watchpoints available for use by ClamAV (to 524288), run the following command:
54 
+
55 
+> $ echo 524288 | sudo tee -a /proc/sys/fs/inotify/max_user_watches
56 
+
57 
+---
12 58
59 
+The `OnAccessIncludePath` option will not accept `/` as a valid path. This is because fanotify works by blocking a process' access to a file until a access_ok or access_denied determination has been made by the original fanotify calling process. Thus, by placing fanotify watchpoints on the entire filesystem, key system files may have their access blocked at the kernel level, which will result in a system lockup.
13 60
61 
+This restriction was made to prevent users from "shooting themselves in the foot." However, clever users will find it's possible to circumvent this restriction by using multiple `OnAccessIncludePath` options to protect most all the filesystem anyways, or simply the paths they truly care about.
14 62
15 
-## Recipes
63 
+---
16 64
17 
-#### Use Case #0
18 
-  - This is a use case.
65 
+The `OnAccessMountPath` option uses a different fanotify api configuration which makes it incompatible with `OnAccessIncludePath` and the DDD System. Therefore, inotify will not be a concern when using this option. Unfortunately, this also means `OnAccessExtraScanning` (which is built around catching inotify events), and `OnAccessExcludePath` (which is built upon the DDD System) cannot be used in conjunction with `OnAccessMountPath`.
66 
+
67 
+---
68 
+
69 
+## Configuration and Recipes
70 
+
71 
+---
72 
+
73 
+More nuanced behavior can be coerced from ClamAV's On-Access Scanner via careful modification to `clamd.conf`. Each option related to On-Access Scanning is easily identified by looking for the `OnAccess` prefix pre-pended to each option. The default `clamd.conf` file contains descriptions of each option, along with any documented limitations or safety features.
74 
+
75 
+Below are examples of common use cases, recipes for the correct minimal configuration, and the expected behavioral result.
76 
+
77 
+---
78 
+
79 
+#### Use Case 0x0
80 
+  - User needs to watch the entire file system, but blocking malicious access attempts isn't a concern
19 81 
   ```
20 
-  This is a recipe.
82 
+  ScanOnAccess yes
83 
+  OnAccessMountPath /
84 
+  OnAccessExcludeRootUID yes
21 85 
   ```
86 
+
87 
+  This configuration will put the On-Access Scanner into `notify-only` mode. It will also ensure only non-root, non-clam, user processes will trigger scans against the filesystem.
88 
+
89 
+---
90 
+
91 
+#### Use Case 0x1
92 
+  - System Administrator needs to watch the home directory of multiple Users, but not all users. Blocking access attempts is un-needed.
93 
+  ```
94 
+  ScanOnAccess yes
95 
+  OnAccessIncludePath /home
96 
+  OnAccessExcludePath /home/user2
97 
+  OnAccessExcludePath /home/user4
98 
+  ```
99 
+
100 
+  With this configuration, the On-Access Scanner will watch the entirety of the `/home` directory recursively in `notify-only` mode. However, it will recursively exclude the `/home/user2` and `/home/user4` directories.
101 
+
102 
+---
103 
+
104 
+#### Use Case 0x2
105 
+  - The user needs to protect a single directory non-recursively and ensure all access attempts on malicious files are blocked.
106 
+  ```
107 
+  ScanOnAccess yes
108 
+  OnAccessIncludePath /home/user/Downloads
109 
+  OnAccessPrevention yes
110 
+  OnAccessDisableDDD yes
111 
+  ```
112 
+
113 
+  The configuration above will result in non-recursive real-time protection of the `/home/user/Downloads` directory by ClamAV's On-Access Scanner. Any access attempts that ClamAV detects on malicious files within the top level of the directory hierarchy will be blocked by fanotify at the kernel level.
114 
+
115 
+---
docs/UserManual/Usage.md
History View file @ ceef37d
... ... 
@@ -63,34 +63,7 @@ There is a special thread in `clamd` that performs on-access scanning under Linu
63 63 
 - Watch your entire filesystem only using the `clamd.conf` OnAccessMountPath option. While this will disable on-access prevention, it will avoid potential system lockups caused by fanotify’s blocking functionality.
64 64 
 - Using the On-Access Scanner to watch a virtual filesystem will result in undefined behaviour.
65 65
66 
-The default configuration utilizes inotify to recursively keep track of directories. If you need to protect more than 8192 directories it will be necessary to change inotify’s `max_user_watches` value.
67 
-
68 
-This can be done temporarily with:
69 
-
70 
-```bash
71 
-    $ sysctl fs.inotify.max_user_watches=<n>
72 
-```
73 
-
74 
-Where `<n>` is the new maximum desired.
75 
-
76 
-To watch your entire filesystem add the following lines to `clamd.conf`:
77 
-
78 
-```ini
79 
-    ScanOnAccess yes
80 
-    OnAccessMountPath /
81 
-```
82 
-
83 
-Similarly, to protect your home directory add the following lines to
84 
-`clamd.conf`:
85 
-
86 
-```ini
87 
-    ScanOnAccess yes
88 
-    OnAccessIncludePath /home
89 
-    OnAccessExcludePath /home/user/temp/dir/of/your/mail/scanning/software
90 
-    OnAccessPrevention yes
91 
-```
92 
-
93 
-For more configuration options, type ’man clamd.conf’ or reference the example clamd.conf.
66 
+For more configuration options, type ’man clamd.conf’ or reference the example clamd.conf. And for additional details on how to use this feature, please reference the [OnAccess usage manual](OnAccess.md).
94 67
95 68 
 ## Clamdtop
96 69
... ... 
@@ -185,7 +158,7 @@ LDFLAGS:
185 185 
 Configure: '--prefix=/xclam/gcc/release/' '--disable-clamav' '--enable-debug' 'CFLAGS=-g -O0'
186 186 
 sizeof(void*) = 4
187 187 
 Engine flevel: 77, dconf: 77
188 
-
188 
+
189 189 
 ```
190 190
191 191 
 For more detailed help, type ’man clamconf’ or ’clamconf –help’.
... ... 
@@ -207,7 +180,7 @@ For more detailed help, type ’man clamconf’ or ’clamconf –help’.
207 207 
 When a virus is found its name is printed between the `filename:` and `FOUND` strings. In case of archives the scanner depends on libclamav and only prints the first virus found within an archive:
208 208
209 209 
 ```bash
210 
-    $ clamscan malware.zip
210 
+    $ clamscan malware.zip
211 211 
     malware.zip: Worm.Mydoom.U FOUND
212 212 
 ```
213 213