Sovana HQ Documentation

Sovana HQ is a next-generation security operations platform that combines AI-powered threat detection, predictive analytics, and unified security management. This documentation provides comprehensive guidance for installation, configuration, and usage.

Installation

System Requirements

Docker 20.10 or higher
Docker Compose 2.0 or higher
8GB RAM minimum (16GB recommended)
50GB disk space minimum
Linux, macOS, or Windows (WSL2)

Docker Installation

# Pull the latest image
docker pull sovanahq/sovana-core:latest

# Run Sovana HQ
docker run -d \
  --name sovana-hq \
  -p 8443:8443 \
  -p 514:514/udp \
  -v sovana-data:/data \
  -v sovana-config:/config \
  sovanahq/sovana-core:latest

Docker Compose Installation

version: '3.8'

services:
  sovana:
    image: sovanahq/sovana-core:latest
    container_name: sovana-hq
    ports:
      - "8443:8443"
      - "514:514/udp"  # Standard syslog port
    volumes:
      - ./data:/data
      - ./config:/config
    environment:
      - SOVANA_ADMIN_PASSWORD=${ADMIN_PASSWORD}  # Use environment variable
      - SOVANA_LOG_LEVEL=info
    restart: unless-stopped

Quick Start Guide

1. Initial Setup

After installation, access the web interface at https://localhost:8443

Default username: admin
Default password: Set via SOVANA_ADMIN_PASSWORD environment variable

2. Add Your First Data Source

Navigate to Settings > Data Sources and configure your first security data input:

Syslog: Standard syslog ports (UDP/TCP)
File monitoring: Configure paths to log files
API integration: Use REST API endpoints

3. Create Alert Rules

Set up automated alerting for security events:

# Example alert rule (YAML)
name: "Failed Login Attempts"
description: "Alert on multiple failed login attempts"
severity: high
conditions:
  - field: event.type
    operator: equals
    value: "authentication_failure"
  - field: event.count
    operator: greater_than
    value: 5
    timeframe: 5m
actions:
  - type: email
    recipients: ["security@company.com"]
  - type: webhook
    url: "https://alerts.company.com/sovana"

CLI Reference

Installation

# Install CLI
pip install sovana-cli

# Configure CLI
sovana config set-url https://sovana.company.com:8443
sovana config set-token YOUR_API_TOKEN

Common Commands

Command	Description
`sovana alerts list`	List all active alerts
`sovana events search`	Search security events
`sovana rules list`	List all alert rules
`sovana status`	Show system status
`sovana chat "query"`	Query the AI chat interface

API Documentation

Authentication

All API requests require a valid API token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Core Endpoints

POST /api/v1/events

Submit security events to Sovana HQ

{
  "timestamp": "2026-01-20T10:30:00Z",
  "source": "firewall-01",
  "event_type": "network_traffic",
  "severity": "medium",
  "data": {
    "src_ip": "10.0.0.100",
    "dst_ip": "203.0.113.50",
    "port": 443,
    "protocol": "https"
  }
}

GET /api/v1/alerts

Retrieve active alerts

GET /api/v1/alerts?status=open&severity=high&limit=50

POST /api/v1/chat

Query the AI chat interface

{
  "query": "Show me failed login attempts from the last hour",
  "context": {
    "timeframe": "1h"
  }
}

Configuration

Environment Variables

Variable	Description	Default
`SOVANA_ADMIN_PASSWORD`	Admin password	Required
`SOVANA_LOG_LEVEL`	Logging level	info
`SOVANA_DB_PATH`	Database path	/data/sovana.db
`SOVANA_TLS_ENABLED`	Enable TLS	true
`SOVANA_AI_ENABLED`	Enable AI features	true

Configuration File

# config/sovana.yaml
server:
  port: 8443
  tls_enabled: true
  tls_cert: /config/tls/cert.pem
  tls_key: /config/tls/key.pem

database:
  type: sqlite
  path: /data/sovana.db

security:
  encryption_key_path: /config/encryption.key
  session_timeout: 3600
  max_login_attempts: 5

logging:
  level: info
  output: /data/logs/sovana.log
  rotation: daily

Security Features

Encryption

Data at Rest: AES-256 encryption for all stored data
Data in Transit: TLS 1.3 for all network communications
Credential Vault: Secure storage for API keys and passwords

Access Control

Role-based access control (RBAC)
Multi-factor authentication (MFA) support
Session management with automatic timeout
Comprehensive audit logging

Compliance

NIST 800-53 controls implementation
CMMC compliance support
FedRAMP roadmap alignment
FISMA-ready architecture

Integrations

SIEM Integration

Sovana HQ integrates with major SIEM platforms:

Splunk
IBM QRadar
ArcSight
Elastic Security

Syslog Sources

# Configure syslog forwarding
# On source system:
*.* @sovana-host:514  # UDP (standard syslog port)
*.* @@sovana-host:514 # TCP (standard syslog port)

Webhook Notifications

# Webhook payload format
{
  "alert_id": "alert-12345",
  "severity": "high",
  "title": "Multiple Failed Login Attempts",
  "description": "User account locked after 5 failed attempts",
  "timestamp": "2026-01-20T10:30:00Z",
  "affected_assets": ["web-server-01"],
  "recommendation": "Investigate source IP and user account"
}

Troubleshooting

Common Issues

Cannot Access Web Interface

Verify Docker container is running: docker ps
Check port binding: Ensure 8443 is not in use
Review logs: docker logs sovana-hq

Authentication Failures

Verify API token is valid and not expired
Check user permissions in Settings > Users
Review audit logs for failed authentication attempts

Performance Issues

Monitor system resources: CPU, RAM, disk I/O
Review database size and optimize if needed
Check log retention policies
Consider scaling horizontally with multiple instances

Support Resources

Need additional help?

Submit a support ticket
Email: support@sovanahq.com
Documentation updates: Check this page regularly for the latest information