fix(docs): improve security and accessibility in help section

- Add aria-label to all Help nav links for better screen reader support - Fix Samba config examples: use authenticated user instead of guest ok=yes - Fix chmod 777 to chmod 770 with group-based access control - Add security notes about dedicated groups and passwords in how-to guides - Fix Python script to use os.environ.get() with explicit error messages - Add app-specific password comment to EmailIngestion.md config example Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>
2026-03-07 20:38:12 +00:00
parent 46b2f17acc
commit fe8e1c41cc
4 changed files with 62 additions and 15 deletions
@@ -35,7 +35,9 @@ EMAIL_INGESTION_IMAP_HOST=mail.yourdomain.com
 EMAIL_INGESTION_IMAP_PORT=993
 EMAIL_INGESTION_IMAP_SSL=true
 EMAIL_INGESTION_USERNAME=scan@yourdomain.com
-EMAIL_INGESTION_PASSWORD=your-email-password
+# Use an app-specific password (Gmail, Outlook) – NOT your main account password.
+# See the Security Considerations section below for details.
+EMAIL_INGESTION_PASSWORD=your-app-specific-password
 EMAIL_INGESTION_FOLDER=INBOX
 EMAIL_INGESTION_INTERVAL=60           # Check every 60 seconds
 EMAIL_INGESTION_MARK_SEEN=true        # Mark emails as read after processing
@@ -38,14 +38,24 @@ Use a lightweight tool like [imapfilter](https://github.com/lefcha/imapfilter) o
 ```python
 import imaplib
 import email
-import requests
 import os
+import sys
+
+import requests

 IMAP_HOST = "mail.yourdomain.com"
 IMAP_USER = "docuelevate-inbox@yourdomain.com"
-IMAP_PASS = os.environ["IMAP_PASS"]
+# Use an app-specific password (Gmail/Outlook), NOT your main account password.
+# Store credentials as environment variables – never hardcode them.
+IMAP_PASS = os.environ.get("IMAP_PASS")
 DOCUELEVATE_URL = "http://your-docuelevate-host:8000"
-API_KEY = os.environ["DOCUELEVATE_API_KEY"]
+API_KEY = os.environ.get("DOCUELEVATE_API_KEY")
+
+if not IMAP_PASS:
+    sys.exit("Error: IMAP_PASS environment variable is not set.")
+if not API_KEY:
+    sys.exit("Error: DOCUELEVATE_API_KEY environment variable is not set.")
+

 def fetch_and_upload():
    mail = imaplib.IMAP4_SSL(IMAP_HOST)
@@ -101,6 +111,10 @@ On your DocuElevate server (or any reachable server), create a shared folder:
 # Create the shared folder
 mkdir -p /srv/scanner-inbox

+# Create a dedicated Samba user for the printer
+sudo useradd -M -s /sbin/nologin scanner
+sudo smbpasswd -a scanner   # set a password for the printer to authenticate with
+
 # Install Samba
 sudo apt-get install samba

@@ -108,10 +122,14 @@ sudo apt-get install samba
 [scanner-inbox]
  path = /srv/scanner-inbox
  writable = yes
-  guest ok = yes
-  force user = nobody
+  guest ok = no
+  valid users = scanner
+  create mask = 0660
+  directory mask = 0770
 ```

+> **Security note:** Use a dedicated user (`scanner`) with a strong password instead of `guest ok = yes`. This prevents unauthorised devices on your network from depositing files.
+
 Restart Samba: `sudo systemctl restart smbd`

 ### Step 2: Configure the HP Printer for Scan to Network Folder
@@ -120,7 +138,8 @@ Restart Samba: `sudo systemctl restart smbd`
 2. Go to **Scan** → **Scan to Network Folder**.
 3. Click **Add** to create a new Quick Set:
   - **UNC Path:** `\\192.168.1.200\scanner-inbox` (replace with your server's IP)
-   - **Username/Password:** Leave blank for guest, or provide credentials
+   - **Username:** `scanner` (the Samba user created above)
+   - **Password:** the password set with `smbpasswd`
   - **File Type:** PDF (Searchable PDF if available)
   - **Resolution:** 200–300 DPI
 4. Test the connection from the EWS interface.
@@ -57,9 +57,20 @@ Create the folder and set permissions:

 ```bash
 sudo mkdir -p /srv/docuelevate/watch
-sudo chmod 777 /srv/docuelevate/watch
+
+# Create a dedicated group for scanner/upload access
+sudo groupadd scanner-upload
+
+# Set group ownership and restrict access to owner + group only
+sudo chown root:scanner-upload /srv/docuelevate/watch
+sudo chmod 770 /srv/docuelevate/watch
+
+# Add the user running DocuElevate (e.g., www-data or your deploy user) to the group
+sudo usermod -aG scanner-upload www-data
 ```

+> **Security note:** Avoid `chmod 777` (world-writable). Use group-based access control so only authorised processes can write to the watched folder.
+
 ---

 ## Multiple Watch Folders
@@ -90,19 +101,27 @@ DocuElevate will monitor all subdirectories and tag documents with the subfolder

 Share the watch folder over the network so scanners and Windows PCs can drop files directly:

+> **Security note:** The example below uses a dedicated Samba user (`scanner`) for authentication. Using `guest ok = yes` (no password) is convenient but allows any device on the network to write files — avoid it in multi-tenant or internet-exposed environments.
+
 ```bash
 # Install Samba
 sudo apt-get install samba -y

+# Create a dedicated Samba user for scanner devices
+sudo useradd -M -s /sbin/nologin scanner
+sudo smbpasswd -a scanner   # set a password
+
 # Add to /etc/samba/smb.conf
 [DocuElevate-Inbox]
  comment = DocuElevate Document Inbox
  path = /srv/docuelevate/watch
  browsable = yes
-  guest ok = yes
+  guest ok = no
+  valid users = scanner
  read only = no
-  create mask = 0777
-  directory mask = 0777
+  create mask = 0660
+  directory mask = 0770
+  force group = scanner-upload
 ```

 Restart Samba:
@@ -186,10 +205,13 @@ You can also view processing status in the DocuElevate web interface under **Que

 **Permission denied errors?**
 ```bash
-# Fix permissions
-sudo chmod -R 777 /srv/docuelevate/watch
-# Or use ACLs for more granular control
-sudo setfacl -m u:nobody:rwx /srv/docuelevate/watch
+# Preferred: use group-based ACL for targeted access
+sudo setfacl -m g:scanner-upload:rwx /srv/docuelevate/watch
+sudo setfacl -d -m g:scanner-upload:rwx /srv/docuelevate/watch
+
+# If you need a quick fix and understand the risk, restrict to owner+group:
+sudo chown -R root:scanner-upload /srv/docuelevate/watch
+sudo chmod -R 770 /srv/docuelevate/watch
 ```

 **Files processed but not deleted?**
@@ -78,6 +78,7 @@
            </a>
            <a href="/help/"
               class="px-3 py-2 rounded-md text-sm font-medium text-gray-700 hover:text-gray-900 hover:bg-gray-100"
+               aria-label="Help and How-To Guides"
               title="Help &amp; How-To Guides"
               {% if request and request.url.path.startswith('/help') %}aria-current="page"{% endif %}>
              <i class="fas fa-circle-question mr-1 text-gray-400" aria-hidden="true"></i>Help
@@ -180,6 +181,7 @@
            <!-- Help documentation – visible to all users -->
            <a href="/help/"
               class="px-3 py-2 rounded-md text-sm font-medium text-gray-700 hover:text-gray-900 hover:bg-gray-100"
+               aria-label="Help and How-To Guides"
               title="Help &amp; How-To Guides"
               {% if request and request.url.path.startswith('/help') %}aria-current="page"{% endif %}>
              <i class="fas fa-circle-question mr-1 text-gray-400" aria-hidden="true"></i>Help
@@ -245,6 +247,7 @@
              </a>
              <a href="/help/"
                 class="block px-3 py-3 rounded-md text-base font-medium text-gray-700 hover:text-gray-900 hover:bg-gray-50"
+                 aria-label="Help and How-To Guides"
                 {% if request and request.url.path.startswith('/help') %}aria-current="page"{% endif %}>
                <i class="fas fa-circle-question mr-2 text-gray-400" aria-hidden="true"></i>Help
              </a>
@@ -320,6 +323,7 @@
              <!-- Help documentation -->
              <a href="/help/"
                 class="block px-3 py-3 rounded-md text-base font-medium text-gray-700 hover:text-gray-900 hover:bg-gray-50"
+                 aria-label="Help and How-To Guides"
                 {% if request and request.url.path.startswith('/help') %}aria-current="page"{% endif %}>
                <i class="fas fa-circle-question mr-2 text-gray-400" aria-hidden="true"></i>Help
              </a>