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.

Overview​

Quick start​

Basic HTTPS setup​

Basic authentication​

Environment variables​

SSL/TLS configuration​

Authentication​

Security headers and policies​

Request limits​

Service-specific usage​

SWML services (AgentBase)​

Search service​

Security headers​

CORS configuration​

Host validation​

Best practices​

1. Production HTTPS setup​

2. Strong authentication​

3. Certificate management​

4. Rate limiting​

5. Monitoring​

Migration guide​

From previous versions​

Common security scenarios​

Development environment​

Staging environment​

Production environment​

Security checklist​

Before deployment​

Ongoing maintenance​

Troubleshooting​

Common issues​