Skip to main content

​
General Settings

This page covers the core configuration settings in config.yaml, including server options, logging, provider setup, monitoring, and alerting.

​
Server Configuration

Configure the KoreShield server host and port: 
server:
  host: "0.0.0.0"
  port: 8000

​
Parameters

​
server.host
string
default:"0.0.0.0"
IP address to bind the server to. Use 0.0.0.0 to listen on all interfaces.
​
server.port
integer
default:"8000"
Port number for the KoreShield server
In production, KoreShield typically runs behind a load balancer or reverse proxy. Bind to 0.0.0.0 to accept connections from the proxy.

​
Logging Configuration

Control logging output, format, and destination: 
logging:
  level: INFO
  json_logs: false
  container_mode: false
  file: logs/koreshield.log

​
Parameters

​
logging.level
string
default:"INFO"
Log level. Options: DEBUG, INFO, WARNING, ERROR, CRITICAL
​
logging.json_logs
boolean
default:"false"
Enable structured JSON logging for easier parsing by log aggregators
​
logging.container_mode
boolean
default:"false"
Log to stdout instead of files when running in containers
​
logging.file
string
default:"logs/koreshield.log"
Log file path (ignored if container_mode: true)

​
Production Recommendations

logging:
  level: DEBUG
  json_logs: false
  container_mode: false
  file: logs/koreshield.log
Always enable json_logs: true in production for structured logging. This makes it easier to query and analyze logs in tools like ELK, Splunk, or CloudWatch.

​
Security Configuration

Define security policies and threat detection behavior: 
security:
  sensitivity: medium
  default_action: block
  features:
    sanitization: true
    detection: true
    policy_enforcement: true
See Security Policies for detailed policy configuration.

​
Provider Configuration

Enable and configure AI provider integrations: 
providers:
  deepseek:
    enabled: true
    base_url: "https://api.deepseek.com/v1"
  openai:
    enabled: false
    base_url: "https://api.openai.com/v1"
  anthropic:
    enabled: false
    base_url: "https://api.anthropic.com/v1"
  gemini:
    enabled: false
    base_url: "https://generativelanguage.googleapis.com/v1beta"
  azure_openai:
    enabled: false
    base_url: "https://your-resource-name.openai.azure.com"

​
Provider Parameters

​
providers.<provider>.enabled
boolean
default:"false"
Enable or disable the provider
​
providers.<provider>.base_url
string
required
Base URL for the provider’s API endpoint

​
Environment Variables

Provider API keys must be set via environment variables: 
export OPENAI_API_KEY="sk-..."
Never hardcode API keys in configuration files. Always use environment variables or a secrets manager.

​
Multi-Provider Setup

Enable multiple providers for failover or routing: 
providers:
  openai:
    enabled: true
    base_url: "https://api.openai.com/v1"
  anthropic:
    enabled: true
    base_url: "https://api.anthropic.com/v1"
  deepseek:
    enabled: true
    base_url: "https://api.deepseek.com/v1"
When multiple providers are enabled, KoreShield routes requests based on the model specified in the API call. For example:
  • gpt-4 → OpenAI
  • claude-3-opus → Anthropic
  • deepseek-chat → DeepSeek
If a provider is unavailable, requests will fail unless you implement custom failover logic.
Yes, you can override the base URL for any provider. This is useful for:
  • Self-hosted model endpoints
  • Regional endpoints
  • Custom proxy configurations
providers:
  openai:
    enabled: true
    base_url: "https://custom-proxy.example.com/openai/v1"

​
Redis Configuration

Enable distributed rate limiting with Redis: 
redis:
  enabled: true
  url: "redis://localhost:6379/0"
See Rate Limiting for detailed Redis configuration and production setup.

​
Monitoring Configuration

Enable health checks and monitoring: 
monitoring:
  enabled: true
  check_interval_seconds: 60

​
Parameters

​
monitoring.enabled
boolean
default:"true"
Enable monitoring and health checks
​
monitoring.check_interval_seconds
integer
default:"60"
Interval between health checks in seconds

​
Health Check Endpoint

When monitoring is enabled, KoreShield exposes a health check endpoint: 
curl http://localhost:8000/health
Response: 
{
  "status": "healthy",
  "version": "1.0.0",
  "checks": {
    "redis": "connected",
    "providers": "operational"
  }
}
Configure your load balancer to use /health for health checks.

​
Alerting Configuration

Configure alerts for security events and system health: 
alerting:
  enabled: false
  rules:
    - name: "High Attack Rate"
      condition: "attacks_detected > 10"
      severity: "warning"
      channels: ["email", "slack"]
      cooldown_minutes: 5
      description: "Alert when attack detection rate is high"
      enabled: true

​
Alert Parameters

​
alerting.enabled
boolean
default:"false"
Enable alerting system
​
alerting.rules[].name
string
required
Human-readable name for the alert rule
​
alerting.rules[].condition
string
required
Condition expression that triggers the alert (e.g., attacks_detected > 10)
​
alerting.rules[].severity
string
default:"warning"
Alert severity level: info, warning, critical
​
alerting.rules[].channels
array
required
Notification channels: email, slack, pagerduty, webhook
​
alerting.rules[].cooldown_minutes
integer
default:"5"
Minimum time between repeated alerts for the same condition
​
alerting.rules[].enabled
boolean
default:"true"
Enable or disable this specific alert rule

​
Alert Examples

alerting:
  enabled: true
  rules:
    - name: "High Attack Rate"
      condition: "attacks_detected > 10"
      severity: "warning"
      channels: ["slack"]
      cooldown_minutes: 5
      enabled: true
Configure alert channels (Slack webhook, email SMTP, etc.) via environment variables to avoid exposing credentials in configuration files.

​
Complete Production Example

Here’s a complete production-ready configuration: 
server:
  host: "0.0.0.0"
  port: 8000

logging:
  level: INFO
  json_logs: true
  container_mode: true

security:
  sensitivity: medium
  default_action: block
  features:
    sanitization: true
    detection: true
    policy_enforcement: true

providers:
  openai:
    enabled: true
    base_url: "https://api.openai.com/v1"
  anthropic:
    enabled: true
    base_url: "https://api.anthropic.com/v1"

redis:
  enabled: true
  url: "rediss://:${REDIS_PASSWORD}@redis.example.com:6380/0"

monitoring:
  enabled: true
  check_interval_seconds: 60

alerting:
  enabled: true
  rules:
    - name: "High Attack Rate"
      condition: "attacks_detected > 10"
      severity: "warning"
      channels: ["slack", "email"]
      cooldown_minutes: 5
      enabled: true
    - name: "Provider Outage"
      condition: "provider_errors > 5"
      severity: "critical"
      channels: ["pagerduty"]
      cooldown_minutes: 10
      enabled: true

​
Frequently Asked Questions

KoreShield validates configuration on startup. To test:
# Dry run to validate config
koreshield --config config.yaml --validate

# Check startup logs for errors
koreshield --config config.yaml 2>&1 | grep -i "error\|warning"
Yes, use ${VARIABLE_NAME} syntax:
redis:
  enabled: true
  url: "redis://:${REDIS_PASSWORD}@${REDIS_HOST}:6379/0"

server:
  port: ${KORESHIELD_PORT:-8000}  # Default to 8000
When using file-based logging (not container mode), use logrotate:
# /etc/logrotate.d/koreshield
/var/log/koreshield/*.log {
  daily
  rotate 7
  compress
  delaycompress
  missingok
  notifempty
}

Security Policies

Configure threat detection and response policies

Rate Limiting

Set up Redis-based distributed rate limiting

Production Checklist

Pre-deployment checklist for production

Monitoring

Monitor KoreShield metrics and health

Build docs developers (and LLMs) love

Get started for freeTalk to us