Server Configuration

Configure the VigilPrism server, database, users, and security settings.

Configuration File

The server configuration file is located at:

# Linux

/opt/vigilprism/config/server.yaml

# Windows

C:\ProgramData\VigilPrism\config\server.yaml

Restart the server after making configuration changes.

Essential Settings

# Server binding

host: 0.0.0.0          # Listen on all interfaces

port: 8000             # API port

# IMPORTANT: Change this secret key!

secret_key: your-256-bit-secret-key-here

# Database

database_url: sqlite:///./data/vigilprism.db

# JWT token settings

jwt_expiry_hours: 24

refresh_token_days: 7

Database Options

SQLite (Default)

Good for small deployments with fewer than 20 agents.

database_url: sqlite:///./data/vigilprism.db

PostgreSQL (Recommended for Production)

Better performance for larger deployments with concurrent access.

database_url: postgresql://user:password@localhost:5432/vigilprism

User Management

VigilPrism supports multiple user roles:

Role	Permissions
`admin`	Full access - manage users, settings, all systems
`analyst`	View audits, run scans, view compliance reports
`viewer`	Read-only access to dashboards and reports

Create User via API

curl -X POST http://localhost:8000/api/v1/users \

  -H "Authorization: Bearer $TOKEN" \

  -H "Content-Type: application/json" \

  -d '{

    "username": "analyst1",

    "email": "analyst1@example.com",

    "password": "SecurePass123!",

    "role": "analyst"

}'

Enrollment Tokens

Enrollment tokens allow agents to securely register with the server.

Create Token via API

curl -X POST http://localhost:8000/api/v1/agents/enrollment-token \

  -H "Authorization: Bearer $TOKEN" \

  -H "Content-Type: application/json" \

  -d '{

    "name": "Production Servers",

    "expires_days": 30,

    "max_uses": 100

}'

Token Best Practices

Set expiration dates - avoid permanent tokens
Limit uses to expected number of agents
Use descriptive names for tracking
Rotate tokens regularly (monthly recommended)
Revoke unused tokens promptly

Security Settings

# Password policy

password_min_length: 8

password_require_uppercase: true

password_require_lowercase: true

password_require_digit: true

password_require_special: false

# Rate limiting

rate_limit_enabled: true

rate_limit_requests: 100     # Per IP per minute

rate_limit_window: 60

# Session settings

session_timeout_minutes: 30

max_sessions_per_user: 5

NEW IN 0.71.0

Dashboard Settings

Configure server-wide defaults from Settings → Server in the dashboard. These settings use a three-tier inheritance system: Server → Group → System.

Agent Update Policy

Control how agents receive updates:

Policy	Behavior
`Latest`	Update immediately when new version available
`Stable`	Wait for version stability (recommended)
`Conservative`	Only security-critical updates
`Pinned`	Never auto-update

Vulnerability Scan Mode

Control how agents perform CVE scanning:

Mode	Description
`Online`	Send package inventory to server for matching
`Offline`	Use local CVE database on agent
`Auto`	Online with offline fallback (recommended)

CVE Database Sync Policy

Control when agents sync their local CVE database:

Policy	Use Case
`Always`	Sync on every heartbeat if outdated
`Scheduled`	Sync only during maintenance windows
`Manual`	Sync only when admin triggers it
`Never`	Agent uses its own database only

Tip: Use "Manual" for air-gapped systems where you push the database manually. Use "Scheduled" for systems with limited bandwidth.

Settings Inheritance

Settings are resolved using three-tier inheritance. More specific settings override general ones:

Server

Default

Group

Override

System

Final

Example: Server default is "Online" scan mode. Group "Production" overrides to "Offline". System "web-server-01" inherits "Offline" unless it has its own override.

Agent Settings (Config File)

# Agent management

agents:

  heartbeat_interval: 60      # Expected heartbeat (seconds)

  offline_threshold: 300      # Mark offline after N seconds

  auto_cleanup_days: 30       # Remove inactive agents

# Audit settings

audits:

  retention_days: 365         # Keep audit history

  max_per_agent: 1000         # Max audits per agent

  default_schedule: "0 2 * * *"  # Daily at 2 AM

Logging Configuration

logging:

  level: INFO                 # DEBUG, INFO, WARNING, ERROR

  file: /var/log/vigilprism/server.log

  max_size_mb: 100

  backup_count: 5

  format: json                # json or text

Environment Variables

Configuration can be overridden using environment variables:

# Format: VIGILPRISM_<SECTION>_<KEY>

export VIGILPRISM_DATABASE_URL="postgresql://localhost/vigilprism"

export VIGILPRISM_SECRET_KEY="my-secret-key"

export VIGILPRISM_LOGGING_LEVEL="DEBUG"

Health Monitoring

Monitor server health using the built-in endpoint:

curl http://localhost:8000/health

Response:

  "status": "healthy",

  "version": "0.71.0",

  "database": "connected",

  "agents_online": 15,

  "agents_total": 20,

  "uptime_seconds": 86400

Installation

Agent Deployment