Skip to main content

Allowlist

Allowlist (whitelist) lets you bypass all security checks for trusted users, channels, or domains. Perfect for team members, VIP users, or testing environments.

Quick Start​

Trust a specific phone number:

{
  "allowlist": {
    "enabled": true,
    "senders": ["+15551234567"]
  }
}

This user bypasses:

  • ✅ Threat detection (all types)
  • ✅ Rate limiting
  • ✅ Semantic analysis
  • ✅ All security checks

Allowlist Types​

By Sender ID​

Trust specific users by their unique ID:

{
  "allowlist": {
    "senders": [
      "+15551234567",           // WhatsApp/SMS
      "telegram:@admin",        // Telegram username
      "discord:123456789",      // Discord user ID
      "email:boss@company.com"  // Email
    ]
  }
}

Sender ID formats:

  • WhatsApp: +1555123456 (phone number)
  • Telegram: telegram:@username or telegram:123456789 (user ID)
  • Discord: discord:123456789012345678 (user ID)
  • Slack: slack:U12345678 (user ID)
  • Email: email:user@domain.com
  • SMS: +1555123456 (phone number)

By Channel​

Trust entire channels/groups:

{
  "allowlist": {
    "channels": [
      "whatsapp:team_group",
      "telegram:-1001234567890",
      "discord:987654321",
      "slack:C12345678"
    ]
  }
}

Everyone in these channels is trusted.

Use cases:

  • Internal team channels
  • Private company groups
  • Admin-only channels
  • Testing environments

By Domain​

Trust all users from specific email domains:

{
  "allowlist": {
    "domains": [
      "@company.com",
      "@partners.com"
    ]
  }
}

Anyone with user@company.com or user@partners.com is trusted.

Use cases:

  • All company employees
  • Partner organizations
  • Educational institutions
  • Enterprise deployments

Combining Allowlist Types​

Mix and match for flexible control:

{
  "allowlist": {
    "enabled": true,
    
    "// Individual VIPs": "",
    "senders": [
      "+15551111111",
      "telegram:@ceo"
    ],
    
    "// Trusted Channels": "",
    "channels": [
      "whatsapp:executive_group",
      "slack:C98765432"
    ],
    
    "// Company Employees": "",
    "domains": [
      "@company.com"
    ]
  }
}

Precedence and Behavior​

Allowlist Checking Happens First​

  1. ✅ Allowlist check (immediate pass)
  2. Rate limit check
  3. Threat detection
  4. Semantic analysis

If user is allowlisted, skip everything else.

Performance​

Allowlist checks are ultra-fast:

  • Latency: < 0.1 ms
  • Lookup: Hash table (O(1))
  • No impact on throughput

Use Cases​

Internal Team Members​

{
  "allowlist": {
    "domains": ["@company.com"],
    "channels": ["slack:team-internal"]
  }
}

All employees can use the bot without restrictions.

VIP Customers​

{
  "allowlist": {
    "senders": [
      "+15551111111",
      "+15552222222",
      "+15553333333"
    ]
  }
}

Premium users get priority access without rate limits.

Testing and Development​

{
  "allowlist": {
    "senders": [
      "+15555551234"  // Your test phone
    ],
    "channels": [
      "telegram:test_group"
    ]
  }
}

Test threatening messages without getting blocked.

Admin Operations​

{
  "allowlist": {
    "senders": [
      "telegram:@admin1",
      "telegram:@admin2"
    ]
  }
}

Admins can perform maintenance without interference.

Security Considerations​

Risks​

⚠ī¸ Allowlisted users bypass ALL security

This means they can:

  • Send malicious content
  • Spam without limits
  • Trigger prompt injection
  • Leak data via bot

Best Practices​

  1. Minimize allowlist - Only add truly trusted users
  2. Use channels for groups, not individual IDs
  3. Regular audits - Review allowlist monthly
  4. Document reasons - Why is each entry trusted?
  5. Emergency removal - Have process to quickly remove compromised users

When NOT to Use Allowlist​

❌ Don't use for:

  • Public users (even if they complain)
  • Unverified identities
  • Temporary testing (use /shield pause instead)
  • "Less strict" filtering (use flag mode instead)

✅ DO use for:

  • Verified team members
  • System administrators
  • Automated services
  • Partner integrations

Dynamic Allowlist​

Via Dashboard​

Add users dynamically without config changes:

  1. Go to dashboard.securecheck.io
  2. Navigate to "Allowlist"
  3. Click "Add User"
  4. Enter sender ID
  5. Save

Changes apply immediately without restart.

Via Shield Commands​

/shield allowlist add +15551234567

Add temporarily (resets on restart).

Partial Trust (Advanced)​

Skip Only Rate Limiting​

{
  "allowlist": {
    "senders": ["+15551234567"]
  },
  "rateLimit": {
    "enabled": true,
    "bypassAllowlist": true
  }
}

Wait, that's not in the current implementation. Let me revise:

{
  "rateLimit": {
    "enabled": true,
    "exemptSenders": ["+15551234567"]
  }
}

This user bypasses ONLY rate limiting, still checked for threats.

Future Feature

Full "partial trust" levels coming soon. Currently allowlist is all-or-nothing.

Testing Allowlist​

Verify User is Allowlisted​

/shield test dangerous message from <sender-id>

If allowlisted:

ℹī¸ Sender is allowlisted - all checks bypassed

Check Current Allowlist​

/shield allowlist

Shows all allowlisted senders, channels, and domains.

Troubleshooting​

User Still Being Blocked​

Problem: Allowlisted user getting blocked

Solutions:

  1. Verify exact sender ID format
  2. Check spelling/case sensitivity
  3. Verify enabled: true
  4. Restart OpenClaw after config change
  5. Check logs: grep "allowlist" ~/.securecheck/shield/logs/*.log

Can't Find Sender ID​

Problem: Don't know user's sender ID

Solutions:

  1. Check Shield logs when they message: 
    tail -f ~/.securecheck/shield/logs/security-*.log
  2. Dashboard shows sender IDs in alerts
  3. Use /shield status to see recent senders

Allowlist Not Working​

Problem: All users still being checked

Solutions:

  1. Verify enabled: true
  2. Check JSON syntax is valid
  3. Restart bot after config change
  4. Test with /shield validate

Complete Configuration Example​

{
  "allowlist": {
    "enabled": true,
    
    "// CEO and CTO": "",
    "senders": [
      "+15551111111",
      "telegram:@ceo",
      "discord:123456789012345678"
    ],
    
    "// Internal Channels": "",
    "channels": [
      "whatsapp:exec_team",
      "slack:C12345678",
      "discord:987654321"
    ],
    
    "// All Employees": "",
    "domains": [
      "@company.com",
      "@subsidiary.com"
    ]
  }
}

Allowlist vs Other Methods​

Allowlist vs Flag Mode​

Allowlist:

  • Completely bypasses checks
  • Zero processing overhead
  • All-or-nothing trust

Flag Mode:

  • Still checks messages
  • Adds warning but allows
  • Maintains audit trail

Recommendation: Use allowlist for team, flag mode for less-trusted users.

Allowlist vs Disabling Shield​

Allowlist:

  • Only affects specific users
  • Everyone else still protected
  • Granular control

Disabling Shield:

  • Affects ALL users
  • No protection for anyone
  • Global effect

Recommendation: Always use allowlist, never disable Shield globally.

Next Steps​