Security

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.

Overview

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.

Quick start

Basic HTTPS setup

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

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

Environment variables

SSL/TLS configuration

Variable	Default	Description
SWML_SSL_ENABLED	false	Enable HTTPS (true, 1, yes to enable)
SWML_SSL_CERT_PATH	-	Path to SSL certificate file
SWML_SSL_KEY_PATH	-	Path to SSL private key file
SWML_DOMAIN	-	Domain name for SSL (used for URL generation)
SWML_SSL_VERIFY_MODE	CERT_REQUIRED	SSL verification mode

Authentication

Variable	Default	Description
SWML_BASIC_AUTH_USER	signalwire	Basic auth username
SWML_BASIC_AUTH_PASSWORD	auto-generated	Basic auth password (32-char token if not set)

Security headers and policies

Variable	Default	Description
SWML_USE_HSTS	true	Enable HSTS when HTTPS is active
SWML_HSTS_MAX_AGE	31536000	HSTS max-age in seconds (1 year)
SWML_ALLOWED_HOSTS	*	Comma-separated list of allowed hosts
SWML_CORS_ORIGINS	*	Comma-separated list of allowed CORS origins

Request limits

Variable	Default	Description
SWML_MAX_REQUEST_SIZE	10485760	Maximum request size in bytes (10MB)
SWML_RATE_LIMIT	60	Requests per minute limit
SWML_REQUEST_TIMEOUT	30	Request timeout in seconds

Service-specific usage

SWML services (AgentBase)

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()

Search service

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"
)

Security headers

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

CORS configuration

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"

Host validation

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

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

Best practices

1. Production HTTPS setup

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

2. Strong authentication

Always set strong credentials in production:

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

3. Certificate management

• 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

4. Rate limiting

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

5. Monitoring

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

Migration guide

From previous versions

If you were using environment variables directly before:

Old approach:

export SWML_SSL_ENABLED=true
export SWML_SSL_CERT_PATH=/path/to/cert.pem

New approach (still supported):

# Environment variables continue to work exactly as before
export SWML_SSL_ENABLED=true
export SWML_SSL_CERT_PATH=/path/to/cert.pem

Enhanced with configuration files:

{
  "security": {
    "ssl_enabled": "${SWML_SSL_ENABLED|false}",
    "ssl_cert_path": "${SWML_SSL_CERT_PATH}",
    "ssl_key_path": "${SWML_SSL_KEY_PATH}"
  }
}

Common security scenarios

Development environment

# Minimal security for local development
export SWML_SSL_ENABLED=false
export SWML_BASIC_AUTH_USER=dev
export SWML_BASIC_AUTH_PASSWORD=devpass123
export SWML_ALLOWED_HOSTS=localhost,127.0.0.1

Staging environment

# HTTPS with self-signed certificate
export SWML_SSL_ENABLED=true
export SWML_SSL_CERT_PATH=/etc/ssl/staging-cert.pem
export SWML_SSL_KEY_PATH=/etc/ssl/staging-key.pem
export SWML_DOMAIN=staging.yourdomain.com
export SWML_BASIC_AUTH_USER=staging_user
export SWML_BASIC_AUTH_PASSWORD=staging_secure_password

Production environment

# Full security configuration
export SWML_SSL_ENABLED=true
export SWML_SSL_CERT_PATH=/etc/ssl/certs/prod-cert.pem
export SWML_SSL_KEY_PATH=/etc/ssl/private/prod-key.pem
export SWML_DOMAIN=api.yourdomain.com
export SWML_ALLOWED_HOSTS=api.yourdomain.com
export SWML_CORS_ORIGINS=https://app.yourdomain.com
export SWML_BASIC_AUTH_USER=prod_api_user
export SWML_BASIC_AUTH_PASSWORD=$(openssl rand -base64 32)
export SWML_RATE_LIMIT=60
export SWML_USE_HSTS=true

Security checklist

Before deployment

• HTTPS enabled with valid certificates
• Strong authentication credentials set
• Allowed hosts configured (not using * in production)
• CORS origins restricted to known domains
• Rate limiting configured appropriately
• Security headers enabled
• Request size limits set appropriately
• Monitoring and logging configured

Ongoing maintenance

• Regularly rotate authentication credentials
• Monitor for certificate expiration
• Review security logs for anomalies
• Update rate limits based on usage patterns
• Test security configuration in staging
• Keep SSL/TLS configuration current

Troubleshooting

Common issues

SSL Certificate errors:

• Verify certificate and key file paths
• Check certificate validity and expiration
• Ensure proper file permissions

Authentication failures:

• Verify username and password are set correctly
• Check for special characters in credentials
• Ensure credentials match client configuration

CORS issues:

• Verify CORS origins are properly formatted
• Check for trailing slashes in URLs
• Ensure protocol (http/https) matches

For additional configuration options, see the Configuration guide.