Security¶

Last update: October 8, 2026

Tolk for Cisco UC is built from the ground up for regulated environments, critical infrastructure, and data-sovereign organizations. Security is not a layer added on top — it is the foundation.

Every component follows a defense-in-depth architecture: multiple independent controls are layered so that no single failure opens a breach.

Security at a Glance¶

Layer	What it does
Air-gapped	No cloud, no telemetry, no outbound connections — ever
Docker hardening	Non-root container, read-only filesystem, no-new-privileges, multi-stage build
Transport	TLS 1.2+ enforced, DNS rebinding protection (`Host` / `Origin` validation)
Authentication	RS256 JWT, OAuth 2.1 (Authorization Code + PKCE / Client Credentials) or both
Authorization	RBAC per product, per protocol and per operation
Admin Web UI	Dedicated HTTPS port, source-IP allow-list, bcrypt passwords, login lockout, admin RBAC, CSRF
Data isolation	Per-client encrypted directory — secrets never cross client boundaries
Credentials at rest	AES-128-CBC + HMAC-SHA256 (Fernet), per-client key via PBKDF2-SHA512
Host verification	Explicit SSH fingerprint trust + HTTPS certificate verification against per-product trust stores
Brute-force protection	Per-IP Fail2Ban + per-client and global (per-host) sliding window rate limiting
Audit trail	Structured JSON audit log — every auth, action, admin change and anomaly recorded
Software integrity	RSA-PSS signature over SHA-512 manifest — verified at startup and periodically
Encrypted backups	RSA-OAEP-SHA512 + AES-256-GCM hybrid — decryptable only with your private key
CI scanning	Automated SAST, secret scan, CVE audit, MCP YARA scan + signed SBOM on every push

Air-Gapped & Sovereign Design¶

Tolk for Cisco UC contains zero cloud dependencies:

Designed for classified, government, and critical infrastructure networks.
Air-gapped model: the entire operational chain can run without any internet connectivity.
The server only connects to the Cisco UC nodes (and terminals) you explicitly configure.
No external service, no telemetry, no analytics, no phone-home mechanism.
The Admin Web UI loads no external asset (no CDN, no web font, no third-party script).
Licensing is offline — licenses are RS256-signed JWT files installed locally. No license server, no online activation.

Docker Security Hardening¶

When deployed with Docker, additional security controls are applied:

Measure	Description
Non-root user	The container runs as an unprivileged user — `UID` / `GID` `1000` by default, configurable (Docker container); `0` (root) is refused
Read-only filesystem	Container filesystem is immutable (`read_only: true`)
No privilege escalation	`no-new-privileges:true` prevents `setuid`/`setgid` exploits
Bounded tmpfs	`/tmp` is a 256 MB in-memory tmpfs (transient report rendering) — no persistent writable area outside the volumes
Multi-stage build	Build tools and compilers are absent from the production image; the base image is pinned by digest
Bind-mount volumes	Runtime data (configuration, secrets, client data, logs, backups) is isolated on the host, outside the image
Health check	Loopback-only container `HEALTHCHECK` (no credential required, nothing exposed)

Transport Security¶

All client-to-server communications are encrypted and strictly validated.

Mandatory encryption — The MCP server and the Admin Web UI only listen over HTTPS.
TLS 1.2+ only — SSL, TLS 1.0 and TLS 1.1 are refused.
Certificate management — CA-signed or auto-generated self-signed certificates, CSR generation and certificate import from the Web UI, expiry alerts (see TLS Certificates).
DNS rebinding protection — The Host and Origin headers of every request are validated against the allowed hosts and origins. Mismatched or forged headers are rejected and audited (TRANSPORT_BLOCKED).
Reverse proxies — X-Forwarded-For is honored only from the proxies listed in TRUSTED_PROXY_IPS (Reverse proxy); from any other source the header is ignored, so a client cannot spoof its IP address. Trusted proxies are never blacklisted.

Authentication¶

The global authentication mode (AUTH_MODE) is selected per deployment in the Admin Web UI; in jwt+oauth2 mode each client gets its own mode (see Authentication Modes). The server refuses a global mode more restrictive than the modes already assigned to clients.

JWT ModeOAuth 2.1 Mode

Clients authenticate with RS256-signed JSON Web Tokens signed by the server RSA key pair (4096 bits by default).

Long-lived tokens generated for each client and revealed once in the Web UI (View credentials).
Immediate revocation from the Web UI (Reset tokens): the active token is blacklisted (JTI) and a new one is issued.
JTI blacklist persisted across restarts, with automatic cleanup of expired entries.

Full OAuth 2.1 flow with two supported grants:

Authorization Code + PKCE (RFC 7636 S256) — browser-based login for interactive clients (AI IDEs).
Client Credentials (RFC 6749 §4.4) — headless M2M token issuance.
Short-lived access tokens (1 hour by default); client secrets stored as bcrypt hashes.
Client secret revealed once in the Web UI; Reset tokens rotates it immediately.
redirect_uri allow-list per client, enforced in strict mode (see OAuth Redirect URI Allow-List).
Token revocation via /revoke (RFC 7009) — a client can only revoke its own tokens.
Authorization Server Metadata (RFC 8414) and Protected Resource Metadata (RFC 9728) for MCP-compliant clients.
HTTP Basic and POST client authentication methods.

RSA key pair

The RSA key pair signs the JWT tokens and wraps the backup keys. It can be rotated from the Web UI (Regenerate keypair): full-system backup, archive of the current key pair, generation of a new key pair and re-issue of every client token (see RSA keys).

Authorization — RBAC¶

Every MCP operation is authorized through a Role-Based Access Control engine before execution.

Predefined profiles: admin, operator, auditor — each with a specific scope of allowed operations.
Custom profiles — created and edited from the Admin Web UI (Clients → Profiles), hot-reloaded without restart.
Per-product granularity — each client only sees the product modules (CUCM, IMP, CUC) of its profile.
Per-protocol granularity — AXL operation prefixes, SSH command allowlists, RIS classes, CUPI, terminal and report operations.
Per-operation enforcement — every AXL, RIS, SSH, CUPI, xAPI, Serviceability or report operation is checked against the profile before any Cisco UC API is contacted; a denied operation is rejected and audited.
Self-service visibility — infra_get_my_permissions returns the effective permission matrix of the calling client.

Admin Web UI Security¶

The Admin Web UI is the single configuration point of the product. It is protected independently from the MCP server:

Dedicated HTTPS listener — separate port (9443 by default), its own or the shared TLS certificate; it can be disabled entirely (Admin UI).
Source-IP allow-list — ADMIN_UI_TRUSTED_IPS (CIDR); empty = deny all. The loopback is always allowed (container health check, local recovery).
Manual blacklist — an administrator can blacklist an IP address or a CIDR subnet from the System & reload page, per scope (Web UI admin, MCP client or both).
Passwords — bcrypt-hashed (configurable cost) with a minimum length and complexity policy; never stored in the configuration. The first superadmin password is set from the command line, with an interactive prompt.
Login lockout — temporary lockout after repeated failures per login and source IP.
Sessions — HMAC-SHA256 signed cookies (HttpOnly, Secure, SameSite=Strict), idle timeout and maximum lifetime.
CSRF protection — double-submit token on every form.
Strict security headers — Content Security Policy without inline script or style, HSTS, X-Frame-Options: DENY, nosniff, no-referrer, no-store.
Admin RBAC — per-page access level (none / read-only / read-write) defined by admin profiles; the superadmin profile is locked (see Administrators).
Accountability — every admin action is written to the audit log with the administrator login and source IP.

Configuration Change Control¶

Staged changes — a modified setting is not applied immediately; it is staged, then applied in one go from System & reload → Apply / Restart.
Pre-restart checks — before restarting, the page shows every change (before / after, author) and checks software integrity, TLS certificates, active MCP clients and admin sessions.
Consistency checks — each value is validated (type, range, enumeration); inconsistent combinations, such as a global authentication mode incompatible with a declared client, are refused.
Snapshots — a timestamped snapshot of the configuration, certificates and RSA keys is kept before each change, and any staged change can be reverted.
Maintenance mode — drains MCP clients before an intervention: new or idle clients are refused ("retry later") while active clients finish their work (see Maintenance mode).

Per-Client Data Isolation¶

Each registered client operates in a fully isolated environment:

Dedicated directory with its own secrets, credentials, reports, and configuration.
No data sharing between clients — credentials and reports are never accessible cross-client.
Automatic cleanup — when a client is deleted, its directory and all associated data are purged.

Credential Encryption at Rest¶

All stored Cisco UC credentials are encrypted using Fernet (AES-128-CBC + HMAC-SHA256).

Encryption keys are derived per client from the client UUID + a server-side salt using PBKDF2-SHA512 with 600,000 iterations (NIST SP 800-132 compliant).
The server salt is generated once and stored in a restricted-access file (mode 600).
Credentials are decrypted in memory only when used; they are never written in plaintext to disk or to the logs.
Server-level secrets (SFTP backup password) are encrypted with a server-level key derived the same way.

Host Identity Verification¶

Tolk verifies the identity of every Cisco UC node before sending any credential.

SSH connections — The fingerprint (SHA-256) of a new node is presented and must be explicitly trusted (*_os_trust_fingerprint) before any connection. All subsequent connections verify it — a mismatch aborts the connection before authentication, so no credential is sent.
HTTPS connections (AXL, RIS, CUPI) — Certificate verification is enabled by default against a per-product CA trust store, editable from the Web UI. Disabling it (lab only) logs a critical audit event (SSL_DISABLED).
Terminals (IP phones, RoomOS codecs) — Reached by IP address with per-terminal HTTP Basic credentials. Certificate chain verification is optional (SERVER_CUCM_PHONES_SSL_VERIFY / SERVER_CUCM_ROOMOS_SSL_VERIFY, off by default since terminals usually present MIC / self-signed certificates) against dedicated CA trust stores; a startup warning is logged while it is off.

Brute-Force & Rate-Limit Protection¶

Independent mechanisms guard against abuse:

Fail2Ban (per IP): Tracks MCP / OAuth authentication failures per source IP. After a configurable number of failures within a sliding window, the IP is automatically blocked for a configurable duration (Brute-force protection). Administrators can also blacklist or release an IP or a subnet manually. All events are recorded in the audit log.

Admin login throttling: Independent from the MCP mechanism: failed Web UI logins are counted per login and source IP, with a temporary lockout.

Rate Limiting (per client): Each authenticated client is subject to per-service sliding window rate limits defined in its RBAC profile. Requests exceeding the limit return HTTP 429 and are logged (RATE_LIMITED).

Global Rate Limiting (all clients, per destination host): An optional cumulative limit protects each Cisco node individually. Keyed per destination host + product/service and checked after the per-client gate, it is configured in the Admin Web UI (Rate limiting tab and the Rate limiting tab of each product). A rejection is logged as RATE_LIMITED_GLOBAL.

Audit Trail¶

Every security-relevant event is written to a dedicated audit.log in structured JSON format, viewable from the Audit page of the Web UI (full list in the Reference).

Event category	What is logged
Authentication	Token verification, OAuth code / token issuance and revocation, IP blacklisting and release
MCP calls	Every RBAC decision and tool / prompt / resource call — client, operation, host, result
Rate limiting	Per-client (`RATE_LIMITED`) and global per-host (`RATE_LIMITED_GLOBAL`) rejections
Credentials	Store, update, delete credential operations
Host trust	SSH fingerprint trust decisions
Reports	Report writing and PDF export
Admin Web UI	Sign-in, lockout, every configuration, client, administrator, license and system action
Server	Startup, shutdown, license state, integrity checks, maintenance rejections
Transport	`Host` / `Origin` header violations (DNS rebinding attempts)

Log injection is prevented by sanitizing control characters in all logged values (CWE-117 mitigation).

Software Integrity Verification¶

Every release is signed. The integrity of the installation / upgrade package is verified with its SHA-512 checksum, published by the editor in DNS, before installation.

Additionally, the integrity of all project files is verifiable at any time:

An SHA-512 manifest (manifest.json) covers every source file.
The manifest is signed with RSA-PSS over SHA-512 (RSA-4096), producing manifest.sig.
Integrity is verified at startup, before any other subsystem: the server refuses to start on any violation.
A background watchdog re-checks it periodically and shuts the server down gracefully if tampering is detected.

Encrypted Backups¶

Backups are protected with hybrid encryption:

A random AES-256-GCM session key encrypts the backup archive.
The session key is wrapped with your RSA public key using RSA-OAEP with SHA-512 (MGF1-SHA512).
Only the holder of the private key can decrypt — the server itself cannot read its own backups without the key.
An SHA-512 sidecar file ensures backup integrity before any restore attempt.
Optional SFTP export with SSH key or encrypted password authentication; configurable remote retention policy.
Mandatory SFTP host key verification (anti-MITM): the SFTP server host key must be trusted beforehand (Get server keys in the Web UI, fingerprints verified out-of-band). If the host is unknown, the transfer aborts before any credential is sent.

CI Security Scanning¶

Every push to main / develop and every pull request triggers an automated security pipeline. CI fails on any unsafe finding not explicitly documented in the allowlist.

Stage	Tool	Scope / Engine
MCP YARA scan	`cisco-ai-mcp-scanner` by Cisco AI Defense	Static / offline (no live server, no API key) — YARA rules covering prompt injection, data exfiltration and tool abuse patterns across all MCP tools, prompts and resources
SAST	`bandit`	Python source analysis over `lib/`, `servers/`, `scripts/`
Lint / static checks	`ruff` + `mypy`	Style, common bug patterns and static type checking
Secret detection	`gitleaks`	Full Git history scanned for committed credentials / tokens
Container image scan	`trivy image`	OS packages + Python dependencies in the published Docker image (CVE + misconfigurations)
Dependency CVE audit	`pip-audit`	Resolved runtime + dev dependency set (from `uv export --no-dev`)
SBOM	`cyclonedx-py`	CycloneDX 1.5 JSON SBOM published as a CI artifact, signed offline (RSA-PSS / SHA-512) with the editor private key and verifiable with the embedded `lib/editor_public.pem`
Unit & coverage	`pytest` + `pytest-cov`	Full unit-test suite with ≥ 88 % coverage gate (`lib/`, `servers/`, `scripts/`)

Reproducible locally

All scanners above ship in the dev dependency group of pyproject.toml and can be re-run on a developer workstation with uv sync then bandit, pip-audit, gitleaks detect, trivy image tolk-for-cisco-uc:latest, pytest, and python tests/tests_check_mcp_scan.py (which validates the MCP-scanner JSON output against the known false-positive allowlist).

Vulnerability Reporting¶

If you discover a security vulnerability, please report it privately:

Email: tolk@sourdeau.com
Response time: 48 hours

Responsible disclosure is appreciated. All reports are treated with confidentiality.

We sincerely thank every researcher and user who takes the time to report a vulnerability — your contribution directly strengthens the security of Tolk for Cisco UC and the organizations that rely on it.

Standards & Compliance¶

Standard / Framework	Coverage
RFC 6749	OAuth 2.0 Authorization Framework
RFC 7009	Token Revocation
RFC 7636	Proof Key for Code Exchange (PKCE) — S256 code challenge
RFC 7519	JSON Web Tokens (JWT)
RFC 8414	OAuth 2.0 Authorization Server Metadata
RFC 9728	OAuth 2.0 Protected Resource Metadata
NIST SP 800-132	PBKDF2 key derivation (600k iterations, SHA-512)
OWASP Top 10	Input validation, log injection (CWE-117), transport security
CWE-117	Log injection prevention via control character sanitization

The full list of supported standards is in the Reference.