This guide covers the security features and configuration options available in SignalWire AI Agents SDK for both SWML-based services (including AgentBase) and the standalone Search Service.

The SDK provides a unified security configuration system that ensures consistent security behavior across all services. All security settings are controlled through environment variables, with secure defaults that can be overridden as needed.

To enable HTTPS for any service:

export SWML_SSL_ENABLED=true
export SWML_SSL_CERT_PATH=/path/to/cert.pem
export SWML_SSL_KEY_PATH=/path/to/key.pem
export SWML_DOMAIN=yourdomain.com

Basic authentication is enabled by default with auto-generated credentials. To set custom credentials:

export SWML_BASIC_AUTH_USER=myusername
export SWML_BASIC_AUTH_PASSWORD=mysecurepassword

SWML-based services automatically use the unified security configuration:

from signalwire_agents import AgentBase

class MyAgent(AgentBase):
    def __init__(self):
        super().__init__(name="secure-agent", route="/agent")
        # Security is automatically configured from environment

# The agent will use HTTPS if SWML_SSL_ENABLED=true
agent = MyAgent()
agent.run()

The standalone search service also supports the same security configuration:

from signalwire_agents.search import SearchService

# Basic usage - security configured from environment
service = SearchService(port=8001, indexes={"docs": "index.swsearch"})
service.start()

# Override SSL settings programmatically
service.start(
    host="0.0.0.0",
    port=8001,
    ssl_cert="/path/to/cert.pem",
    ssl_key="/path/to/key.pem"
)

When HTTPS is enabled, the following security headers are automatically added to responses:

• Strict-Transport-Security: Forces HTTPS connections (when SWML_USE_HSTS=true)
• X-Content-Type-Options: nosniff: Prevents MIME type sniffing
• X-Frame-Options: DENY: Prevents clickjacking
• X-XSS-Protection: 1; mode=block: Enables XSS filtering
• Referrer-Policy: strict-origin-when-cross-origin: Controls referrer information

Cross-Origin Resource Sharing (CORS) is configured to:

• Allow credentials
• Allow all methods by default
• Allow all headers by default
• Origins controlled by SWML_CORS_ORIGINS

To restrict CORS to specific domains:

export SWML_CORS_ORIGINS="https://app1.example.com,https://app2.example.com"

By default, all hosts are allowed (SWML_ALLOWED_HOSTS=*). To restrict to specific hosts:

export SWML_ALLOWED_HOSTS="example.com,api.example.com"

For production environments, always enable HTTPS:

# Production configuration
export SWML_SSL_ENABLED=true
export SWML_SSL_CERT_PATH=/etc/ssl/certs/server.crt
export SWML_SSL_KEY_PATH=/etc/ssl/private/server.key
export SWML_DOMAIN=api.yourdomain.com
export SWML_ALLOWED_HOSTS=api.yourdomain.com
export SWML_CORS_ORIGINS=https://app.yourdomain.com

Always set strong credentials in production:

export SWML_BASIC_AUTH_USER=api_user
export SWML_BASIC_AUTH_PASSWORD=$(openssl rand -base64 32)

• Use certificates from a trusted CA in production
• For development, you can generate self-signed certificates:

# Generate self-signed certificate for development
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

Adjust rate limits based on your usage patterns:

# Higher rate limit for internal services
export SWML_RATE_LIMIT=300

# Lower rate limit for public APIs
export SWML_RATE_LIMIT=20

Monitor security-related logs:

# Security events are logged with structured data
# Look for log entries with:
# - "security_config_loaded" - Configuration details
# - "ssl_config_invalid" - SSL configuration errors
# - "starting_search_service" / "starting_server" - Service startup with security info

The security configuration is backward compatible. Existing environment variables continue to work:

• SWML_SSL_ENABLED, SWML_SSL_CERT_PATH, SWML_SSL_KEY_PATH - Still supported
• SWML_BASIC_AUTH_USER, SWML_BASIC_AUTH_PASSWORD - Still supported
• Auto-generated credentials if not set - Still works the same way

The following are new security features:

1. Search Service HTTPS: The search service now supports HTTPS using the same environment variables
2. Security Headers: Automatically added when appropriate
3. CORS Configuration: Fine-grained control over CORS origins
4. Host Validation: Restrict which hosts can access the service
5. Rate Limiting: Built-in rate limiting support
6. HSTS: HTTP Strict Transport Security for HTTPS connections

If you see SSL configuration errors:

1. Check file paths exist and are readable:

   ls -la $SWML_SSL_CERT_PATH $SWML_SSL_KEY_PATH

2. Verify certificate validity:

   openssl x509 -in $SWML_SSL_CERT_PATH -text -noout

3. Check for matching key and certificate:

   openssl x509 -noout -modulus -in $SWML_SSL_CERT_PATH | openssl md5
   openssl rsa -noout -modulus -in $SWML_SSL_KEY_PATH | openssl md5

If authentication fails:

1. Check credentials are set correctly:

   echo "User: $SWML_BASIC_AUTH_USER"
   echo "Pass length: ${#SWML_BASIC_AUTH_PASSWORD}"

2. Look for auto-generated credentials in startup logs:

   Basic Auth: signalwire:generated_password_here
   

3. Test with curl:

   curl -u username:password https://localhost:8000/health

If you encounter CORS errors:

1. Check the origin is allowed:

   echo $SWML_CORS_ORIGINS

2. For development, you can temporarily allow all origins:

   export SWML_CORS_ORIGINS="*"

3. For production, specify exact origins:

   export SWML_CORS_ORIGINS="https://app.example.com,https://admin.example.com"

Before deploying to production:

• HTTPS enabled with valid certificates
• Strong authentication credentials set
• CORS origins restricted to known domains
• Host validation configured
• Rate limits appropriate for usage
• Security headers verified in responses
• Logs monitored for security events
• SSL certificate expiration monitoring in place
• Regular security updates applied