Security & Authentication

XYBEROS includes a comprehensive security subsystem spanning authentication, authorization, risk assessment, audit, and resource governance.

---

Quick Start

from xyberos.security import SecurityService, Principal, Permission, Role
from xyberos.security.providers import DefaultSecurityProvider

svc = SecurityService(provider=DefaultSecurityProvider())

# Create a principal
alice = Principal(id="alice", name="Alice")

# Authenticate
svc.authenticate(alice)

# Check permissions
svc.authorize(alice, "files.read")

---

Core Concepts

Principal

An authenticated identity — user, agent, service, plugin, or session.

from xyberos.security import Principal, PrincipalType

user = Principal(id="user-1", name="Alice", type=PrincipalType.USER)
agent = Principal(id="agent-1", name="Bot", type=PrincipalType.AGENT)

SecurityContext

Carries the authenticated principal plus request metadata.

from xyberos.security import SecurityContext

ctx = SecurityContext(
    principal=user,
    metadata={"ip": "192.168.1.1", "session_id": "abc123"},
)

Tenant Isolation

Principals can be scoped to a tenant for multi-organization deployment.

tenant_user = Principal(
    id="u1", name="Alice",
    tenant_id="acme-corp",
)

---

Guardian Engine

The 8-step decision pipeline:

Authenticate → Capability Check → Permission Check → Risk Assessment
→ Policy Evaluation → Resource Check → Approval → Sandboxing

from xyberos.security.guardian import GuardianEngine
from xyberos.security.risk import RiskEngine
from xyberos.security.audit import AuditService

guardian = GuardianEngine()
risk = RiskEngine()
audit = AuditService()

---

Secrets Manager

Secure credential storage with pluggable backends.

from xyberos.security.secrets import SecretsManager, VaultSecretsProvider

# Default: reads from environment variables
mgr = SecretsManager()

# With Vault integration (auto-fallback to env vars)
mgr = SecretsManager(
    provider=VaultSecretsProvider(),
    cache_ttl=300,  # 5-minute cache
)

api_key = mgr.get("OPENAI_API_KEY")

Supports: - EnvSecretsProvider — reads from environment variables (default) - VaultSecretsProvider — HashiCorp Vault via hvac - TTL-based caching with manual invalidation

---

REST API Authentication

The FastAPI server supports JWT and API-key authentication.

from xyberos.server.auth import create_access_token, decode_access_token

# Create a token
token = create_access_token(
    "user-1",
    secret="your-secret",
    expires_minutes=60,
    tenant_id="acme",
)

# Verify a token
claims = decode_access_token(token, secret="your-secret")
print(claims["sub"])  # "user-1"

Header-based auth

Requests can authenticate via: - Authorization: Bearer <jwt_token> - X-API-Key: <api_key>

---

Key Modules

Module	Purpose
xyberos.security.models	Principal, Permission, Role, SecurityContext, Tenant
xyberos.security.secrets	SecretsManager with Vault/env backends
xyberos.server.auth	JWT creation/validation, AuthMiddleware
xyberos.security.guardian	Guardian decision engine
xyberos.security.risk	Action risk scoring (0–100)
xyberos.security.audit	Structured audit trail
xyberos.security.policy	Rule-based policy evaluation
xyberos.security.approval	Human-in-the-loop workflow
xyberos.security.governor	Resource consumption limits
xyberos.security.kill_switch	Emergency stop for agents/plugins
xyberos.storage.tenant	Tenant-isolated storage wrapper
xyberos.database.tenant	Tenant-isolated database wrapper