diff --git a/docs/howto/EmailIngestion.md b/docs/howto/EmailIngestion.md
index 97ed52c2..1a911f6f 100644
--- a/docs/howto/EmailIngestion.md
+++ b/docs/howto/EmailIngestion.md
@@ -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
diff --git a/docs/howto/HPPrinterSetup.md b/docs/howto/HPPrinterSetup.md
index 30fcadba..4897e43d 100644
--- a/docs/howto/HPPrinterSetup.md
+++ b/docs/howto/HPPrinterSetup.md
@@ -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.
diff --git a/docs/howto/WatchedFolderSetup.md b/docs/howto/WatchedFolderSetup.md
index 325a9ed4..aa4a5b11 100644
--- a/docs/howto/WatchedFolderSetup.md
+++ b/docs/howto/WatchedFolderSetup.md
@@ -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?**
diff --git a/frontend/templates/base.html b/frontend/templates/base.html
index 5005b620..d29c66b3 100644
--- a/frontend/templates/base.html
+++ b/frontend/templates/base.html
@@ -78,6 +78,7 @@
Help
@@ -180,6 +181,7 @@
Help
@@ -245,6 +247,7 @@
Help
@@ -320,6 +323,7 @@
Help