Add high level software diagram and scan flowchart to Usage page

Author: val-ms

.github/workflows/deploy.yml

@@ -17,7 +17,7 @@ jobs:
       run: rustup update stable --no-self-update && rustup default stable
     - name: Install mdBook
       run: |
-        cargo install mdbook
+        cargo install mdbook mdbook-mermaid
         cargo install --git https://github.com/Cisco-Talos/mdbook-sitemap-generator.git --branch rename-urls-url
     - name: Build book
       run: |

book.toml

@@ -14,6 +14,7 @@ site-url = "/"
 theme = "theme"
 default-theme = "clamav"
 preferred-dark-theme  = "clamav"
+additional-js = ["mermaid.min.js", "mermaid-init.js"]
 
 [output.html.playground]
 editable = true
@@ -27,3 +28,8 @@ boost-hierarchy = 2
 boost-paragraph = 1
 expand = true
 heading-split-level = 2
+
+[preprocessor]
+
+[preprocessor.mermaid]
+command = "mdbook-mermaid"

src/manual/Usage.md

@@ -4,6 +4,8 @@ Table Of Contents
 
 - [Usage](#usage)
   - [Purpose](#purpose)
+  - [High-Level Software Diagram](#high-level-software-diagram)
+  - [Rough Scan Flowchart](#rough-scan-flowchart)
   - [Daemon](#daemon)
   - [Scanner](#scanner)
   - [Signature Testing and Management](#signature-testing-and-management)
@@ -13,12 +15,102 @@ Table Of Contents
 
 This user guide presents an overview of the various ways that *libclamav* can be used through the tools provided by ClamAV. To learn more about how to better use each facet of ClamAV that interests you, please follow the links provided.
 
+## High-Level Software Diagram
+
+```mermaid
+flowchart TD
+    subgraph CLAMAV[ClamAV Programs, Services, Libraries, and Data]
+        DB[(Virus Databases)]
+        NET[(ClamAV mirrors / update source)]
+
+        LF[libfreshclam<br/>update library]
+
+        FC[freshclam<br/>updates databases]
+        CD[clamd<br/>scanner daemon]
+        CS[clamscan<br/>standalone scanner]
+        CDS[clamdscan<br/>client for clamd]
+        CDT[clamdtop<br/>monitor for clamd]
+        COA[clamonacc<br/>on-access scanner]
+        CMI[clamav-milter<br/>mail filter]
+        ST[sigtool<br/>signature/db utility]
+        CBC[clambc<br/>bytecode utility]
+        CCF[clamconf<br/>config/report utility]
+        CSU[clamsubmit<br/>sample submission tool]
+
+        NET --> FC
+        LF --> FC
+        FC --> DB
+
+        DB --> CD
+        DB --> CS
+        DB --> ST
+        DB --> CBC
+
+        CDS --> CD
+        CDT --> CD
+        COA --> CD
+        CMI --> CD
+    end
+
+```
+
+## Rough Scan Flowchart
+
+```mermaid
+flowchart LR
+    subgraph DIRECT[Direct scan flow]
+        direction LR
+        CS[clamscan]
+        CS_VERDICT[Scan verdicts / alerts]
+        CS_META[Logs / metadata]
+
+        CS -->|report verdict| CS_VERDICT
+        CS -->|emit logs / metadata| CS_META
+    end
+
+    subgraph CLIENTSERVER[Client/server scan flow]
+        direction LR
+
+        subgraph CLIENTS[ ]
+            direction TB
+            CDS[clamdscan]
+            COA[clamonacc]
+            CMI[clamav-milter]
+        end
+
+        subgraph DAEMON[ ]
+            direction TB
+            CD[clamd]
+        end
+
+        subgraph OUTPUTS[ ]
+            direction TB
+            CD_VERDICT[Scan verdicts / alerts]
+            CD_META[Logs / metadata]
+        end
+
+        CDS -->|request scan| CD
+        COA -->|request scan| CD
+        CMI -->|request scan| CD
+
+        CDS -->|report verdict| CD_VERDICT
+        COA -->|report verdict| CD_VERDICT
+        CMI -->|report verdict| CD_VERDICT
+
+        CDS -->|emit logs / metadata| CD_META
+        COA -->|emit logs / metadata| CD_META
+        CMI -->|emit logs / metadata| CD_META
+    end
+
+```
+
 ## Daemon
 
 The ClamAV Daemon, or [`clamd`](Usage/Scanning.md#clamd), is a multi-threaded daemon that uses *libclamav* to [scan files for viruses](Usage/Scanning.md). ClamAV provides a number of tools which interface with this daemon. They are, as follows:
 
   - [`clamdscan`](Usage/Scanning.md#clamdscan) - a simple scanning client
-  - [`on-access scanning`](Usage/Scanning.md#On-access-scanning) - provides real-time protection via a `clamd` instance
+  - [`clamonacc`](Usage/Scanning.md#On-access-scanning) - provides on-access scanning (aka real-time protection via a `clamd` instance
+  - [`clamav-milter`](Usage/Scanning.md#On-access-scanning) - a mail filtering plugin for the Sendmail email processing server software to scan emails
   - [`clamdtop`](Usage/Scanning.md#clamdtop) - a resource monitoring interface for `clamd`
 
 ## Scanner
@@ -40,6 +132,4 @@ The more complex tools ClamAV provides each require some degree of [configuratio
   - [`clamd.conf`](Usage/Configuration.md#clamdconf) - for configuring the behavior of the ClamAV Daemon `clamd` and associated tools
   - [`freschclam.conf`](Usage/Configuration.md#freshclamconf) - for configuring the behavior of the signature database update tool, `freshclam`
 
-ClamAV also provides a mail filtering tool called [`clamav-milter`](Usage/Configuration.md#clamav-milterconf) which can be attached to a `clamd` instance for mail scanning purposes.
-
 Additionally, a tool called [`clamconf`](Usage/Configuration.md#clamconf) allows users to check the configurations used by each other tool, pulling information from the configuration files listed above, alongside other relevant information.