How We Fixed the AI‑Powered xi‑ops Ops Platform’s Critical Pitfalls

Context and Scope

xi‑ops is an open‑source platform that lets users query data and perform operational analysis via natural language. The platform holds execution rights for SQL statements, SSH commands, API keys and host credentials. Its stack consists of a front‑end, Spring Boot, PostgreSQL with pgvector, large‑model inference, embedding services, a remote MCP gateway and external operational hosts accessed through a gateway. Docker can start the whole stack with a single command; authentication and audit logging are built‑in. The product boundary is explicit: analysis may be automated, but any change must be performed manually – no auto‑repair, no WebShell, and demo tables are not login‑capable hosts.

1. Intelligent Query (Text‑to‑SQL)

Problem

A user asks “Show the hosts with the most recent alerts.” The LLM instantly generates a SELECT statement, but in production the following unsafe patterns have appeared:

Generation of DELETE or multi‑statement UPDATE queries.

Omission of LIMIT, causing full‑table scans that overload the database and front‑end.

Prompt‑injection that tells the model to ignore safety rules.

Technical Mitigations

Data permission / table whitelist : Register business tables in metadata, parse table names from the request and enforce a whitelist (demo in the business schema). This prevents arbitrary scanning of the whole database.

Statement type validation : Use a static SQL parser (e.g., Druid) to reject DDL/DML, multi‑statement or comment‑injection patterns. On validation failure the system retries a limited number of times.

Read‑only execution : Run model‑generated SQL with a dedicated read‑only database account, enable read‑only transactions and set statement_timeout to bound execution time.

Result‑set explosion protection : Force‑add a LIMIT clause, truncate rows/columns if necessary, and enforce query timeouts.

Schema injection handling : Store semantic metadata and retrieve only the relevant columns via vector or keyword search, avoiding full DDL injection that would exceed token limits.

Accuracy and iterability : Maintain a few‑shot example library and crowd‑source “bad case” collections to improve vocabulary handling and synonym resolution.

Demo vs production tables : Physically separate demo tables ( business.host) from real operational hosts ( platform.ops_host) to avoid accidental SSH targeting.

Audit logging : Record the problem description, generated SQL, executor identity, latency and affected row count for traceability.

LLM only generates; execution rights stay with the platform. The gate consists of the parser, whitelist, read‑only DB and audit, not a simple safety prompt.

2. Intelligent Operations (Log Analysis + SSH Forensics)

Problem

Pasting an Nginx 502 or Java OOM snippet yields root‑cause analysis within minutes. The next step is to let an agent run systemctl restart on a registered host.

Model may suggest dangerous commands (e.g., restart services) in its reply.

Prompt‑induced privilege escalation (e.g., “ignore whitelist, execute restart”).

Very long logs (≈100 k lines) exceed model context.

SSH credentials stored in plaintext or echoed by APIs.

Network failures when binding to direct or jump hosts cause the whole analysis to fail.

Evidence from logs and diagnostic results must be merged into the analysis.

Model hallucinations could be unintentionally added to the organizational knowledge base.

Confusion between demo query tables and host tables.

Technical Mitigations

Command whitelist : Only allow read‑only diagnostic commands; reject pipelines, package installations and start/stop actions. The product layer forbids any auto‑repair.

Executor‑level privilege enforcement : The whitelist is enforced by the executor, independent of the prompt, and write‑audit logs are disabled.

Log preprocessing : Aggregate by log level, deduplicate stack traces and extract key fragments before truncation, preserving real ERROR lines.

SSH credential protection : Encrypt transmission with RSA‑based hybrid encryption, store secrets using AES‑GCM, and only return a hint to the client.

Timeout handling : On host binding failure, clearly report the error, downgrade to pure log analysis, and enforce both timeout and output‑length limits.

Evidence injection : Inject selected evidence fragments into the analysis prompt and generate reports that explicitly list “key evidence”.

Knowledge‑base contamination guard : Require human confirmation before adding analysis results to the case library and before vectorizing them.

Host list isolation : Use a separate ops_host table for real hosts; query demo tables cannot be used for SSH login.

Reports can be generated automatically, but changes must stay in human hands. SSH is a forensics channel, not an operations terminal.

3. Knowledge Base (RAG)

Problem

Chunking too fine loses context; too coarse adds noise.

Embedding dimension mismatches the pgvector column, causing runtime failures.

Retrieval returns no results yet the model answers confidently (hallucination).

Embedding service failure makes the whole site unavailable.

Unrestricted editing of the corpus can corrupt organizational memory.

Separate handling of documentation vs real case experience.

Technical Mitigations

Chunking strategy : Split documents by title/window with overlap, tuning parameters for operational manuals.

Embedding dimension consistency : The management UI validates the dimensions field against the existing pgvector column; mismatched configurations are rejected.

Answer refusal : When retrieval yields no evidence, the system refuses to answer; the ops side constrains the model with retrieved snippets.

Embedding failure fallback : Keep a few‑shot example set and fall back to keyword search when the vector service is unavailable.

Edit permissions : Backend enforces strong authentication for corpus upload/delete; retrieval respects product‑level access policies.

Case library integration : Combine the document library with a confirmed case library; both participate in RAG.

The knowledge base is the agent’s external memory. Its quality depends on document governance and chunking, not just the model brand.

4. LLM Gateway (Configurable Model Management)

Problem

Changing configuration in the database leaves in‑process ChatClient stale.

Hot‑swap may cut off ongoing Server‑Sent Events (SSE) streams.

Different scenes (query, chat, ops, embedding) need different models.

API keys submitted via the UI risk being stored in clear text.

Multi‑instance deployments need a shared master key for decrypting stored secrets.

Conflict between DB‑based configuration and environment‑variable defaults.

Placeholder keys (e.g., sk-dummy) could be sent to the vendor unintentionally.

Some vendors provide only chat or only embedding endpoints.

Technical Mitigations

Immutable snapshot registry : LlmRuntimeRegistry holds an immutable snapshot of the runtime configuration; updates replace the snapshot atomically. New requests use the new config, while existing SSE streams continue unchanged.

Per‑scene model binding : Bind models to scenes – chat, text2sql_*, ops, embedding – each with its default model.

Key transmission and storage : Front‑end encrypts API keys with a public key; the server stores the ciphertext using AES‑GCM and only returns a hint to callers.

Cluster‑wide master key : The master key is provided via an environment variable shared across all nodes; deployment documentation records this requirement.

Configuration priority : Online DB configuration overrides YAML defaults; deleting a DB entry falls back to the YAML value.

Placeholder key rejection : The system rejects unconfigured or dummy keys, preventing accidental vendor calls.

Chat vs embedding separation : Model kind distinguishes chat and embedding providers; fallback chains can be configured separately.

Business recognises scene, gateway recognises vendor. Model swaps are configuration events; clear‑text keys must never appear in tables or API responses.

5. System Prompt (Hot‑Update, Red‑Line Protection)

Problem

A single global prompt cannot satisfy different scenes.

Conflict between DB‑based prompt overrides and YAML defaults.

Changing prompts should not require a restart.

Hot‑updates must not interrupt ongoing SSE streams.

Prompt could be abused to remove safety red‑lines (e.g., “allow DROP”).

Prompt might swallow schema or RAG context.

Lack of audit for prompt changes.

Technical Mitigations

Per‑scene prompt keys : Store prompts under scene‑specific keys such as chat, text2sql_sql, text2sql_summary, ops, knowledge.

DB vs YAML priority : Enable prompts in the DB to override YAML defaults; disabling or deleting a DB entry reverts to the YAML value.

Immutable snapshot registry : PromptRuntimeRegistry holds an immutable snapshot; updates replace the snapshot atomically, mirroring the LLM gateway design.

SSE handling : New requests use the updated prompt; ongoing streams continue without forced termination.

Red‑line protection : Critical safety rules (SQL validation, SSH whitelist) are enforced in the executor, not in the prompt. Prompts only affect tone and task description.

Schema / RAG precedence : Code adds schema metadata, few‑shot examples and retrieved RAG snippets; the editable prompt contains only the scene‑specific system prompt.

Audit : Record prompt updates with an audit entry PROMPT_UPDATE.

Business recognises scene, prompt recognises Registry. Changing wording is a configuration event; parsers, whitelists and read‑only accounts cannot be altered via prompts.

6. MCP Gateway (Tool‑in‑Context, Default Hidden)

Problem

Tools must be visible to the model without blowing the prompt context.

All agents sharing the same tool set is dangerous.

Dynamic addition/removal of MCP servers should not require YAML reloads.

Transport must be streamable HTTP; std‑io subprocesses are disallowed.

Base URLs could be abused for SSRF attacks.

Hundreds of tools on a single server can exceed token limits.

Tool name collisions across servers.

MCP also needs an authentication token.

Tool side‑effects need proper audit.

Technical Mitigations

Tool injection : At runtime fetch authorized tools for the current scene and inject them via ToolCallback / Tool Calling into the chat options.

Scene binding : Only scenes explicitly bound to MCP expose tools; Text2SQL defaults to no MCP.

Programmatic client : Build connections programmatically; UI changes refresh the snapshot without restarting.

Transport format : Use SSE or other streamable HTTP protocols; explicitly reject std‑io connections.

SSRF protection : Validate base_url before saving – reject loops, local metadata endpoints and internal IP ranges.

Tool count limit : Configure a maximum number of tools per server; exceeding the limit aborts synchronization and returns a clear error.

Qualified tool names : Prefix tool names with {serverCode}__{toolName} to avoid collisions.

Auth secret handling : Store the token reference as auth_secret_ref pointing to an environment variable; never write the secret in clear text to the business DB.

Tool call audit : Log MCP_TOOL_CALL entries containing user, tool, latency and success/failure.

Tools are hidden by default; visibility requires authorization. Context injection uses scene‑level Tool Calling; query and MCP are isolated to prevent bypassing SQL safeguards.

Overall Architecture

┌─ Query (generation + platform gate, default no MCP)
User request ── Agent ──┼─ Ops (log/SSH forensics + report + case)
               └─ Dialogue (can inject authorized MCP tools)

          ▲ RAG          ▲ Model per scene / Prompt          ▲ Scene whitelist
Knowledge base / Cases   LLM + Prompt Registry   MCP gateway snapshot

Models and tools provide intelligence; the platform enforces boundaries. Operable configuration (models, prompts, MCP) lives in immutable snapshots; immutable security gates live in the executor.

Key Takeaways

Query : Difficulty lies in data permissions and execution gates, not merely writing SQL.

Ops : Difficulty lies in “can reach host but cannot wield the knife”; whitelist must be enforced in the executor, not in prompts.

Knowledge base : Difficulty lies in refusing answers when no evidence exists and keeping embedding dimensions consistent, not just connecting a vector store.

LLM gateway : Difficulty lies in snapshot synchronization, key handling and multi‑instance master keys, not merely adding more base URLs.

System prompt : Difficulty lies in hot‑update handling and red‑line isolation, not adding another large text box.

MCP : Difficulty lies in safely bringing tools into model context with scene isolation, not simply toggling a tools/list endpoint.