Whitelist and Blacklist Management¶

Control email delivery by explicitly allowing or blocking senders.

Overview¶

Whitelists and blacklists provide absolute control over email delivery:

Whitelist (Allow List) - Always accept email from these senders
Blacklist (Block List) - Always reject email from these senders

These lists override spam and virus filtering for specified senders.

When to Use¶

Whitelist: - Trusted business partners - Critical services (banks, utilities, government) - Known legitimate senders being caught by spam filters - Automated systems (monitoring, notifications)

Blacklist: - Known spam sources - Abusive senders - Fraudulent domains - Persistent phishing sources

Use with Caution

Whitelisting bypasses security checks. Only whitelist truly trusted senders. Blacklisting can cause false positives if too broad.

Whitelist Management¶

Adding to Whitelist¶

Whitelist by email address:

sudo mb-whitelist add sender@example.com

Whitelist entire domain:

sudo mb-whitelist add @example.com

Whitelist by IP address:

sudo mb-whitelist add 203.0.113.50
sudo mb-whitelist add 203.0.113.0/24  # Entire subnet

Whitelist with reason:

sudo mb-whitelist add partner@company.com --reason "Approved vendor - ticket #12345"

Whitelist with expiration:

sudo mb-whitelist add temp@sender.com --expires "2025-12-31"

Whitelist Options¶

Partial bypass (whitelist but still scan for viruses):

sudo mb-whitelist add sender@example.com --allow-virus-scan

Selective whitelist (specific recipient only):

sudo mb-whitelist add sender@example.com --for user@example.com

Score adjustment (lower spam score instead of full bypass):

sudo mb-whitelist add sender@example.com --score-adjustment -5.0

List Whitelist Entries¶

View all whitelist entries:

sudo mb-whitelist list

Example output:

Whitelist Entries
=================

Email Addresses:
  partner@company.com (added 2025-01-10, by admin@example.com)
    Reason: Approved vendor - ticket #12345
    Matches: 234

  critical@service.com (added 2025-01-08)
    Matches: 1,567

Domains:
  @trusted-partner.com (added 2025-01-05)
    Reason: Corporate partner
    Matches: 4,892

  @bank-alerts.com (added 2024-12-20)
    Matches: 89

IP Addresses:
  203.0.113.50 (added 2025-01-12)
    Matches: 45

  198.51.100.0/24 (added 2025-01-01)
    Reason: Corporate mail servers
    Matches: 12,345

Total: 6 entries
Total matches: 19,172

Filter by type:

sudo mb-whitelist list --type email
sudo mb-whitelist list --type domain
sudo mb-whitelist list --type ip

Show expired entries:

sudo mb-whitelist list --expired

Removing from Whitelist¶

Remove specific entry:

sudo mb-whitelist remove sender@example.com
sudo mb-whitelist remove @example.com
sudo mb-whitelist remove 203.0.113.50

Remove with confirmation:

sudo mb-whitelist remove @example.com --confirm

Example output:

Remove whitelist entry: @example.com
Added: 2025-01-05
Reason: Corporate partner
Matches: 4,892

This will affect future emails from this domain.
Proceed? [y/N]: y

Whitelist entry removed.

Bulk removal:

# Remove all expired entries
sudo mb-whitelist remove --expired

# Remove entries with no matches in 90 days
sudo mb-whitelist remove --inactive 90

Blacklist Management¶

Adding to Blacklist¶

Blacklist by email address:

sudo mb-blacklist add spammer@bad.com

Blacklist entire domain:

sudo mb-blacklist add @spam-domain.com

Blacklist by IP address:

sudo mb-blacklist add 198.51.100.25
sudo mb-blacklist add 198.51.100.0/24  # Entire subnet

Blacklist with reason:

sudo mb-blacklist add phisher@evil.com --reason "Phishing campaign targeting executives"

Blacklist with expiration:

sudo mb-blacklist add temp-spammer@example.com --expires "2025-02-01"

Blacklist Actions¶

Choose action on match:

# Reject (bounce back to sender)
sudo mb-blacklist add spammer@bad.com --action reject

# Discard (silently drop)
sudo mb-blacklist add spammer@bad.com --action discard

# Quarantine (hold for review)
sudo mb-blacklist add suspicious@sender.com --action quarantine

Custom reject message:

sudo mb-blacklist add spammer@bad.com --action reject \
  --message "Your email has been blocked due to policy violations"

List Blacklist Entries¶

View all blacklist entries:

sudo mb-blacklist list

Example output:

Blacklist Entries
=================

Email Addresses:
  spammer@bad.com (added 2025-01-13, by admin@example.com)
    Reason: Persistent spam
    Action: REJECT
    Matches: 1,234

  phisher@evil.net (added 2025-01-10)
    Reason: Phishing campaign targeting executives
    Action: DISCARD
    Matches: 567

Domains:
  @spam-domain.com (added 2025-01-05)
    Action: REJECT
    Matches: 8,901

  @phishing-site.ru (added 2025-01-08)
    Action: DISCARD
    Matches: 2,345

IP Addresses:
  198.51.100.25 (added 2025-01-12)
    Action: REJECT
    Matches: 89

  192.0.2.0/24 (added 2024-12-28)
    Reason: Spam botnet
    Action: DISCARD
    Matches: 45,678

Total: 6 entries
Total blocks: 58,814

Filter by action:

sudo mb-blacklist list --action reject
sudo mb-blacklist list --action discard
sudo mb-blacklist list --action quarantine

Removing from Blacklist¶

Remove specific entry:

sudo mb-blacklist remove spammer@bad.com
sudo mb-blacklist remove @spam-domain.com
sudo mb-blacklist remove 198.51.100.25

Bulk removal:

# Remove expired entries
sudo mb-blacklist remove --expired

# Remove entries with no matches in 180 days
sudo mb-blacklist remove --inactive 180

Pattern Matching¶

Wildcard Patterns¶

Email patterns:

# Match any address at domain
sudo mb-whitelist add @example.com

# Match subdomain
sudo mb-whitelist add @*.example.com

# Match pattern
sudo mb-blacklist add *casino*@*
sudo mb-blacklist add *viagra*@*

Sender names:

sudo mb-blacklist add --from-name "Nigerian Prince"
sudo mb-blacklist add --from-name "*lottery*"

Regular Expressions¶

Advanced pattern matching:

# Match various spellings
sudo mb-blacklist add --regex "v[i1][a@]gr[a@]@.*"

# Match numeric usernames
sudo mb-blacklist add --regex "^[0-9]+@spam\.com$"

# Match suspicious patterns
sudo mb-blacklist add --regex ".*\.(ru|cn|kp)$" --reason "Block high-risk TLDs"

Test regex:

sudo mb-pattern-test --regex "v[i1][a@]gr[a@]@.*" "v1agra@spam.com"
# Output: MATCH

IP Ranges¶

CIDR notation:

# Class C network
sudo mb-blacklist add 192.0.2.0/24

# Class B network
sudo mb-blacklist add 198.51.0.0/16

# Smaller range
sudo mb-blacklist add 203.0.113.0/28  # 16 addresses

IP ranges:

sudo mb-blacklist add --ip-range 192.0.2.10-192.0.2.50

Testing Lists¶

Test Whitelist¶

Check if sender is whitelisted:

sudo mb-whitelist test sender@example.com

Example output:

Testing: sender@example.com

MATCH: Whitelist entry
  Type: Email address
  Entry: sender@example.com
  Added: 2025-01-10
  Reason: Approved vendor

Action: ALLOW (bypass spam/virus checks)

Test with IP:

sudo mb-whitelist test sender@example.com --from-ip 203.0.113.50

Test Blacklist¶

Check if sender is blacklisted:

sudo mb-blacklist test spammer@bad.com

Example output:

Testing: spammer@bad.com

MATCH: Blacklist entry
  Type: Email address
  Entry: spammer@bad.com
  Added: 2025-01-13
  Reason: Persistent spam
  Action: REJECT
  Matches: 1,234

Action: REJECT with message "Sender blocked by policy"

Test domain:

sudo mb-blacklist test anyone@spam-domain.com
# Tests against domain blacklist entry

Bulk Testing¶

Test multiple addresses:

cat > /tmp/test-senders.txt << EOF
sender@example.com
partner@company.com
spammer@bad.com
phisher@evil.net
EOF

sudo mb-whitelist test-bulk /tmp/test-senders.txt

Priority and Precedence¶

List Priority¶

When both whitelist and blacklist match:

Explicit entry (email address) overrides domain
Whitelist overrides blacklist
Most specific entry wins

Example:

# Domain blacklisted
sudo mb-blacklist add @example.com

# But specific address whitelisted
sudo mb-whitelist add trusted@example.com

# Result: trusted@example.com is ALLOWED
# Other addresses at example.com are BLOCKED

Priority Order¶

1. Whitelist (email address)
2. Whitelist (domain)
3. Whitelist (IP)
4. Blacklist (email address)
5. Blacklist (domain)
6. Blacklist (IP)
7. Normal spam/virus filtering

Override Control¶

Force blacklist precedence:

sudo mb-config set blacklist.override_whitelist true

Security Risk

This allows blacklist to override whitelist, which may be desired for blocking compromised partners.

Integration with Spam Filtering¶

Scoring Mode¶

Add to spam score instead of absolute block:

# Blacklist adds to spam score
sudo mb-blacklist add @suspicious-domain.com --score-adjustment 5.0

# Whitelist reduces spam score
sudo mb-whitelist add @trusted-domain.com --score-adjustment -3.0

Combined with spam detection:

Email from blacklisted domain:
  Base spam score: 3.0
  + Blacklist adjustment: 5.0
  = Total: 8.0 → QUARANTINE

Conditional Lists¶

Whitelist only if authenticated:

sudo mb-whitelist add @partner.com --require-spf-pass
sudo mb-whitelist add @vendor.com --require-dkim-pass

Blacklist unless authenticated:

sudo mb-blacklist add @suspicious.com --unless-dmarc-pass

Monitoring and Statistics¶

List Statistics¶

View whitelist statistics:

sudo mb-whitelist stats

Example output:

Whitelist Statistics
====================

Total Entries: 45
  Email addresses: 23
  Domains: 18
  IP addresses: 4

Total Matches (Last 30 days): 19,172
  Email: 8,234
  Domain: 10,567
  IP: 371

Top Matches:
  1. @trusted-partner.com - 4,892 matches
  2. critical@service.com - 1,567 matches
  3. 198.51.100.0/24 - 371 matches

Inactive Entries (no matches in 90 days): 5
Expired Entries: 2

View blacklist statistics:

sudo mb-blacklist stats

Example output:

Blacklist Statistics
====================

Total Entries: 89
  Email addresses: 45
  Domains: 32
  IP addresses: 12

Total Blocks (Last 30 days): 58,814
  Email: 12,345
  Domain: 43,210
  IP: 3,259

Top Blocks:
  1. @spam-domain.com - 8,901 blocks
  2. 192.0.2.0/24 - 3,259 blocks
  3. @phishing-site.ru - 2,345 blocks

Actions:
  Rejected: 45,678 (77.6%)
  Discarded: 12,345 (21.0%)
  Quarantined: 791 (1.3%)

Real-time Monitoring¶

Watch whitelist matches:

sudo tail -f /var/log/mailborder/whitelist.log

Example log:

2025-01-13 14:23:45 [WHITELIST] from=partner@company.com to=user@example.com ip=203.0.113.50 entry=partner@company.com action=ALLOW
2025-01-13 14:24:12 [WHITELIST] from=sender@trusted.com to=admin@example.com ip=198.51.100.25 entry=@trusted.com action=ALLOW

Watch blacklist blocks:

sudo tail -f /var/log/mailborder/blacklist.log

Example log:

2025-01-13 14:25:03 [BLACKLIST] from=spammer@bad.com to=victim@example.com ip=192.0.2.50 entry=spammer@bad.com action=REJECT
2025-01-13 14:26:15 [BLACKLIST] from=sender@spam-domain.com to=user@example.com ip=198.51.100.123 entry=@spam-domain.com action=DISCARD

Audit Trail¶

View list modifications:

sudo mb-audit-log --type whitelist
sudo mb-audit-log --type blacklist

Example output:

2025-01-13 10:23:45  admin@example.com  WHITELIST_ADD    partner@company.com  "Approved vendor"
2025-01-13 11:15:32  admin@example.com  BLACKLIST_ADD    spammer@bad.com      "Persistent spam"
2025-01-13 14:45:18  admin@example.com  WHITELIST_REMOVE old@sender.com       "No longer needed"

Import and Export¶

Export Lists¶

Export whitelist:

sudo mb-whitelist export /tmp/whitelist.txt

Example file format:

# Mailborder Whitelist Export
# Generated: 2025-01-13 15:30:00
# Format: type,entry,reason,added,matches

email,partner@company.com,"Approved vendor",2025-01-10,234
domain,@trusted.com,"Corporate partner",2025-01-05,4892
ip,203.0.113.50,"Mail server",2025-01-12,45

Export blacklist:

sudo mb-blacklist export /tmp/blacklist.txt

JSON format:

sudo mb-whitelist export /tmp/whitelist.json --format json
sudo mb-blacklist export /tmp/blacklist.json --format json

Import Lists¶

Import whitelist:

sudo mb-whitelist import /tmp/whitelist.txt

Import blacklist:

sudo mb-blacklist import /tmp/blacklist.txt

Merge import (keep existing):

sudo mb-whitelist import /tmp/whitelist.txt --merge

Replace import (delete existing):

sudo mb-whitelist import /tmp/whitelist.txt --replace

Example output:

Importing whitelist from /tmp/whitelist.txt...

Parsed: 45 entries
  Email: 23
  Domain: 18
  IP: 4

Importing... [========================================] 45/45

Import complete:
  Added: 45
  Skipped (duplicate): 0
  Failed: 0

Synchronization and Clustering¶

Cluster Synchronization¶

Sync to child nodes:

sudo mb-cluster sync-whitelist
sudo mb-cluster sync-blacklist

Auto-sync configuration:

sudo mb-config set cluster.auto_sync_lists true
sudo mb-config set cluster.sync_interval 300  # 5 minutes

External List Feeds¶

Subscribe to external blacklists:

sudo mb-blacklist subscribe https://example.com/spammer-list.txt
sudo mb-blacklist subscribe https://abuse-feed.org/blacklist.json

Update subscriptions:

sudo mb-blacklist update-subscriptions

Auto-update configuration:

sudo mb-config set blacklist.auto_update true
sudo mb-config set blacklist.update_schedule "hourly"

Best Practices¶

Whitelist Management¶

Be specific - Prefer email addresses over domains
Document reasons - Record why each entry was added
Review regularly - Remove inactive entries quarterly
Use expiration - For temporary whitelisting
Still scan for viruses - Don't fully bypass security
Avoid wildcards - Too broad, potential security risk

Good whitelist usage:

sudo mb-whitelist add critical@vendor.com --reason "Approved invoice system - ticket #12345" --expires "2025-12-31"

Bad whitelist usage:

sudo mb-whitelist add @gmail.com  # Too broad!

Blacklist Management¶

Use specific entries - Block specific senders when possible
Escalate actions - Start with quarantine, escalate to reject/discard
Document evidence - Record spam samples and timestamps
Set expiration - For temporary blocks
Review effectiveness - Remove ineffective entries
Combine with GeoIP - Geographic restrictions for broad blocks

Good blacklist usage:

sudo mb-blacklist add persistent-spammer@domain.com --reason "50+ spam messages, samples in ticket #67890" --action reject

Maintenance Schedule¶

Daily: - Review logs for new spam patterns - Add obvious spammers to blacklist

Weekly: - Review quarantine for false positives - Add legitimate senders to whitelist - Check blacklist effectiveness

Monthly: - Remove inactive entries (no matches in 90 days) - Review and renew expiring entries - Analyze statistics for patterns

Quarterly: - Full audit of whitelist (still needed?) - Full audit of blacklist (still effective?) - Export for backup

Performance Optimization¶

Limit list size - <1000 entries per list recommended
Use specific matches - Email > domain > IP
Avoid complex regex - Use simple patterns when possible
Cache lookups - Enable list caching
Regular cleanup - Remove unused entries

Enable caching:

sudo mb-config set whitelist.cache_enabled true
sudo mb-config set blacklist.cache_enabled true
sudo mb-config set list.cache_ttl 3600  # 1 hour

Troubleshooting¶

Whitelist Not Working¶

Verify entry exists:

sudo mb-whitelist list | grep sender@example.com

Test match:

sudo mb-whitelist test sender@example.com

Check logs:

sudo grep "sender@example.com" /var/log/mailborder/whitelist.log

Common issues: - Typo in email address - Blacklist overriding (if configured) - Email coming from different address (check envelope sender) - Whitelist disabled in configuration

Blacklist Not Working¶

Verify entry exists:

sudo mb-blacklist list | grep spammer@bad.com

Test match:

sudo mb-blacklist test spammer@bad.com

Check configuration:

sudo mb-config get blacklist.enabled

Common issues: - Spammer using different addresses - Need domain-level block instead of email - Whitelist overriding blacklist - Blacklist disabled

Performance Issues¶

Large lists:

sudo mb-whitelist list | wc -l
sudo mb-blacklist list | wc -l

If >5000 entries, consider: 1. Enable caching 2. Remove inactive entries 3. Use more specific rules 4. Consider policy-based filtering instead

Optimize lists:

sudo mb-whitelist optimize
sudo mb-blacklist optimize

Whitelist and Blacklist Management¶

Overview¶

When to Use¶

Whitelist Management¶

Adding to Whitelist¶

Whitelist Options¶

List Whitelist Entries¶

Removing from Whitelist¶

Blacklist Management¶

Adding to Blacklist¶

Blacklist Actions¶

List Blacklist Entries¶

Removing from Blacklist¶

Pattern Matching¶

Wildcard Patterns¶

Regular Expressions¶

IP Ranges¶

Testing Lists¶

Test Whitelist¶

Test Blacklist¶

Bulk Testing¶

Priority and Precedence¶

List Priority¶

Priority Order¶

Override Control¶

Integration with Spam Filtering¶

Scoring Mode¶

Conditional Lists¶

Monitoring and Statistics¶

List Statistics¶

Real-time Monitoring¶

Audit Trail¶

Import and Export¶

Export Lists¶

Import Lists¶

Synchronization and Clustering¶

Cluster Synchronization¶

External List Feeds¶

Best Practices¶

Whitelist Management¶

Blacklist Management¶

Maintenance Schedule¶

Performance Optimization¶

Troubleshooting¶

Whitelist Not Working¶

Blacklist Not Working¶

Performance Issues¶

See Also¶