> For the complete documentation index, see [llms.txt](https://docs.flopsar.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flopsar.com/7/security/ai-assistant.md).

# AI Assistant

This page is the security description of the optional AI Assistant: what the Flopsar server sends to a model, which controls bound that disclosure, how secrets and audit records are handled, and what residual risk remains after those controls. Configuring the fields themselves is in the Administrator Guide: [AI Assistant](/7/administrator-guide/ai-assistant.md). Analysts use the chat as described in the [user guide](/7/user-guide/observing-and-diagnosing/ai-assistant.md).

The assistant is **off by default**. Flopsar Technology Sp. z o.o. is never the model host: there is no vendor telemetry and no call to Flopsar-operated model infrastructure. The destination is the provider **you** configure. How that design maps to the Cyber Resilience Act and to customer-side frameworks (DORA, NIS2, GDPR) is below. Residual risk for operators is also on [Known Risks & Limitations](/7/security/known-risks-and-limitations.md).

## Trust model

Every model call is made **from the Flopsar server process**, not from the analyst's browser. The browser only streams the conversation over the Workstation HTTPS session.

* The **server host** must be able to reach the provider Base URL (directly or through the assistant-only HTTP/HTTPS proxy). A workstation that can open the vendor's site is irrelevant if the server cannot. `localhost` in the Base URL is the server machine. Outbound ports and firewall guidance are on [Network Surface & Port Reference](/7/security/network-surface-and-port-reference.md).
* The analyst instruction (system prompt) is **fixed in the server**. It cannot be edited from the Workstation, from the API, or by the browser. The client cannot inject a `system` role: anything sent that way is treated as a user message.
* The model is given **pointers** (application, time range, call id), not a dump the browser assembled. The server loads the data, formats it, and checks permissions again. A user cannot smuggle another application's telemetry into the prompt.
* Tools, when enabled, run **as the asking user**. Banned applications apply. Missing permissions return an error string to the model rather than data. The assistant never receives a tool the administrator's policy forbids.
* The assistant is **read-only**. It cannot create users, change roles, deploy profiles, edit tokens, change AI settings, or mutate server configuration. Tools that would do those things are not offered.

## What leaves your infrastructure

{% hint style="info" %}
To keep every prompt and every analytics payload on your own network, run a local OpenAI-compatible model (Ollama, vLLM, LM Studio, or an internal gateway) and set **Base URL** to that host. The Flopsar server then talks only to that endpoint — typically `localhost` on the server machine.
{% endhint %}

Traffic starts only when **Enable assistant** is on **and** an analyst submits a question (or a grounded view auto-starts an analysis). Saving a provider configuration with the assistant still disabled sends nothing.

When a conversation runs, the server sends the provider:

* the fixed Flopsar system prompt (task instructions, expertise level, language instruction);
* the analyst's question;
* for a grounded view (Data Analysis, call stack, aggregated tree): a server-built summary of **that** view — typically application name, time range, filters, latency percentiles, exception names, method names, and timings;
* for the free-form workspace: only workspace clock/timezone metadata until tools fetch more;
* if **Let the assistant query data** is on: whatever the model then requests through tools (further aggregates, heat maps, hotspots, call trees, individual stacks, symbol names, and — when separately allowed — recorded arguments or live JVM diagnostics);
* if **Log model requests** is on: the same JSON is also written to disk on the server (see below).

Class names, method names, thread names, instance names, exception class names, and numeric telemetry **are** in those payloads. They leave your network whenever the Base URL is a host outside it.

{% hint style="warning" %}
Recorded **method argument values** are sent to the model only when **all** of the following are true: **Allow call parameters** is on, **Let the assistant query data** is on, the asking user has **View parameters**, and the model actually calls `get_call_parameters` (or a grounded call-stack view includes root arguments under the same rule). Keep **Allow call parameters** off unless that disclosure is acceptable for the provider you chose.

Heap histograms, thread dumps, JVM properties, command lines, and agent logs leave only when **Allow live agent queries** is on, tools are on, and the asking user has **Query agents**. A heap histogram or thread dump can **pause** a live JVM. Those queries are off by default for that reason.
{% endhint %}

Air-gapped operation is supported when the model host is on the same network as the server: the assistant then needs no Internet route.

Choosing a public cloud model is a **customer** decision. That vendor — not Flopsar Technology Sp. z o.o. — may become a processor of whatever you send it. Review that vendor's data-processing terms before you enable the assistant against a public API. See [Privacy & Data Handling](/7/trust-and-compliance/privacy-and-data-handling.md) and [GDPR](/7/trust-and-compliance/regulatory-compliance/gdpr.md).

## Relation to CRA, DORA, NIS2, and GDPR

The same split of roles that applies to the rest of Flopsar applies here. **CRA binds Flopsar Technology Sp. z o.o. as manufacturer. DORA, NIS2, and the GDPR bind the customer** as financial entity, operator, or controller. The assistant does not move Flopsar Technology into those customer roles, and it does not create a hosted service from Flopsar Technology. See [Regulatory Compliance](/7/trust-and-compliance/regulatory-compliance.md).

### Cyber Resilience Act (manufacturer)

The assistant is part of the product with digital elements assessed under Regulation (EU) 2024/2847. It does not change the product's classification (default category, Module A). What CRA requires of this feature is that it be designed and documented so the operator can run it securely — not that every deployment keep prompts inside one network.

The feature meets the essential requirements that touch it as follows (the map for the whole product is [Cyber Resilience Act](/7/trust-and-compliance/regulatory-compliance/cyber-resilience-act.md)):

* **Secure by default (Annex I, Part I (b)).** The assistant is off until an administrator enables it. Call parameters, live agent queries, request logging, and skip-verify are off.
* **Data minimization (g).** The prompt contains only what the view, the tools, and the asking user's permissions allow. Recorded arguments and live JVM dumps are separate, off-by-default controls.
* **Protection from unauthorized access (d).** Configuration and chat are separate permissions. Tools run as the asking user; banned applications apply; the assistant cannot change users, profiles, or server settings.
* **Confidentiality (e).** API keys and proxy passwords are sealed with the master key. Traffic to an `https://` Base URL uses TLS; skip-verify is off by default.
* **Limited attack surface (j).** There is no extra listening port. Outbound HTTP(S) to the configured Base URL exists only when the operator enables the assistant. The path is documented on [Network Surface & Port Reference](/7/security/network-surface-and-port-reference.md).
* **Recording of security-relevant activity (l).** Configuration changes, chats, connection tests, and tool calls are written to the tamper-evident audit trail.
* **Information to users (Annex II (d), (e)).** Intended use, the operator-chosen destination, and foreseeable residual risk are on this page and on [Known Risks & Limitations](/7/security/known-risks-and-limitations.md).

CRA still describes a product that does not phone home to Flopsar Technology. An optional, administrator-configured model endpoint is not a manufacturer back-channel.

### DORA and NIS2 (customer)

DORA (Regulation (EU) 2022/2554) and NIS2 (Directive (EU) 2022/2555) apply to the **customer** where that customer is a financial entity or an essential/important entity. Flopsar Technology remains a supplier of on-premise software, not a hosted ICT service and not a designated critical ICT third-party. Licensing and security updates for Flopsar are unchanged by this feature. See [DORA](/7/trust-and-compliance/regulatory-compliance/dora-financial-sector-customer-considerations.md) and [NIS2](/7/trust-and-compliance/regulatory-compliance/nis2-customer-operator-considerations.md).

If the customer points the assistant at a **model vendor they contract with**, that vendor is an additional party in **the customer's** ICT-third-party or supply-chain register (DORA Articles 28–30; NIS2 Article 21(2)(d)). Flopsar Technology is not that vendor and is not a sub-processor of that vendor. If the customer runs the model on their own network, no extra ICT third party is introduced for the model.

The product supports the customer's own risk-management measures: RBAC and LDAP for access control, audit records of who asked the model and which tools ran, TLS to the endpoint they chose, and an exit path that does not depend on Flopsar Technology (disable the assistant or remove the product; monitored applications keep running).

### GDPR (customer as controller)

Flopsar Technology is neither controller nor processor of data in a customer's deployment. If prompts contain personal data and the Base URL is an external model, the **customer** is the controller of that processing and deals with that vendor under their own GDPR programme. A local model keeps that processing inside the deployment. Detail: [GDPR](/7/trust-and-compliance/regulatory-compliance/gdpr.md).

### EU AI Act

Regulation (EU) 2024/1689 (the AI Act) does not make Flopsar Technology a provider of a general-purpose AI model: the product does not ship or host a foundation model. The assistant calls the OpenAI-compatible endpoint the operator configures. Obligations that attach to a given model (for example a GPAI placed on the market by its vendor) sit with that vendor. Use of the assistant by named operators inside the Workstation, with the feature labelled as AI, is the intended professional use; it is not a consumer-facing chatbot placed on the market by Flopsar Technology. How a particular customer classifies their own use remains their assessment.

## Authorization

Three permissions, plus **View data**, control the feature. Titles match the Workstation checklist; the catalog is on [Managing Roles](/7/administrator-guide/managing-roles.md) and [Authentication, Authorization & Identity](/7/security/authentication-authorization-and-identity.md).

| Permission           | Security effect                                                                                              |
| -------------------- | ------------------------------------------------------------------------------------------------------------ |
| **View AI settings** | Read the configuration. Secrets are never returned by the API.                                               |
| **Edit AI settings** | Change provider, keys, tool policy, proxy/TLS, and reset the token counter.                                  |
| **Use AI assistant** | Open the analyst chat. Does not grant the administration page. Requires **View data**.                       |
| **View parameters**  | Required, together with **Allow call parameters**, before recorded arguments reach the model.                |
| **Query agents**     | Required, together with **Allow live agent queries**, before live JVM dumps and related queries are offered. |

**Use AI assistant** without **Enable assistant** is refused (*the AI assistant is disabled*). Role changes apply the next time that user's session token is issued (at most 12 hours), the same as every other permission.

Give analysts the smallest set that matches the policy on **Administration → AI Assistant**:

| Goal                                              | Settings                                  | Role permissions                                           |
| ------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------- |
| Chat about the current Data Analysis / stack only | Enable on; tools off                      | **Use AI assistant** + **View data**                       |
| Free-form workspace and drill-down across apps    | Enable on; tools on                       | **Use AI assistant** + **View data**                       |
| Let the model read recorded arguments             | Tools on; **Allow call parameters** on    | plus **View parameters**                                   |
| Let the model dump / histogram a live JVM         | Tools on; **Allow live agent queries** on | plus **Query agents**                                      |
| See plugin source or profile rules in answers     | Tools on                                  | plus **View plugins source** / **View profiles** as needed |
| Configure the feature                             | —                                         | **View AI settings** and **Edit AI settings**              |

Banned applications on the user or role always apply, including to `list_applications` and every scoped tool.

Defaults that matter for least privilege: tools **on**, call parameters **off**, live agent queries **off**, request logging **off**, certificate verification **on**. Factory values for every field are in the [administrator settings](/7/administrator-guide/ai-assistant.md#defaults-factory).

## Secrets at rest and in transit

The provider **API key** and optional **proxy password** are sealed with the deployment **master key** using XChaCha20-Poly1305, stored in the server database, and unsealed into process memory while the server runs. Associated data is `AI_API_KEY` and `AI_PROXY_PASSWORD` respectively, so a ciphertext cannot be substituted for a PSK or for the other secret. The Workstation never displays the plaintext; an empty field on Save means “keep the stored value.” Clearing the proxy user name also removes the stored proxy password.

Losing or rotating the master key without re-entering these credentials leaves the assistant unable to authenticate to the provider or the proxy. Back up `master.key` separately from the database, the same way as for agent PSKs. Details: [Cryptography & Key Management](/7/security/cryptography-and-key-management.md).

Settings live in the server database, not in `settings.toml`. Prompt bodies in transit to the provider are protected only by TLS to that host (or not at all if you choose plain HTTP to a local model).

## TLS to the provider

Used when the Base URL is `https://`. **Skip certificate verification** accepts any certificate, including mismatched and self-signed. The channel is then encrypted against passive eavesdropping but **not** against an active man-in-the-middle. The server logs a warning when this is on. Use it only to unblock a lab gateway.

**CA certificate (PEM)** is added to the operating-system trust store, not used instead of it. Prefer that field for an internal HTTPS gateway or a TLS-inspecting proxy. These controls do not affect the Workstation certificate, agent PSK crypto, LDAP `skip_verify`, or OTLP.

SOCKS proxies are not supported. An empty **Proxy address** follows `HTTPS_PROXY` / `NO_PROXY` of the server process; the proxy applies only to assistant traffic.

## Request log (`llm.log`)

**Log model requests** is off by default. When on, every `POST /chat/completions` the server sends — conversations, **Test Connection**, and the tool-calling probe — is appended to `<server_home>/logs/llm.log`.

Each entry is two lines: a grep-friendly header `>>> LLM POST <url>` and a JSON object with UTC timestamp, `method`, `url`, and `body`. **`body` is the exact JSON sent on the wire** — system prompt, user text, view snapshot, tool results, and tool declarations.

The API key, `Authorization` header, and proxy password are **not** written. Failure to write the file does not fail the conversation. When the file would exceed 50 MB it is renamed to `llm.log.1`.

This file is **not** the tamper-evident audit trail. Treat it as sensitive, restrict filesystem permissions, and turn the switch off when you no longer need it. How to enable it is on the [administrator page](/7/administrator-guide/ai-assistant.md#log-model-requests).

## Audit trail

When auditing is enabled (default), these actions are appended to `audit.log`. Field `action` is snake\_case:

| `action`               | When                                                                                                                                                                                                                                      |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ai_config_update`     | Save of AI settings (success or failure). Success `target` includes provider and model.                                                                                                                                                   |
| `ai_token_usage_reset` | Reset of the global token-usage counter.                                                                                                                                                                                                  |
| `ai_query`             | A chat request (`target` like `AI analysis: analytics` / `call_stack` / `aggregated_tree` / `explore`); **Test Connection** (`test AI provider connection`); each tool start (`AI tool {name}: {arguments}` truncated to 500 characters). |

Listing models is not written as its own audit action. `llm.log` is not a substitute for `audit.log`. See [Logging, Monitoring & Audit Trail](/7/security/logging-monitoring-and-audit-trail.md).

## Recommended postures

**Public API, production telemetry stays coarse.** Enable the assistant, tools on, call parameters **off**, live agent queries **off**. Use `https://` with certificate verification. Restrict **Use AI assistant** to the incident-response role. Assume class and method names will reach the vendor.

**Public API, argument-level diagnosis.** Same, plus **Allow call parameters** and **View parameters** for a **small** role. Complete a privacy review first. Data masking still applies to stored values but is pattern-based, not a guarantee.

**Local model, no Internet egress.** Provider Ollama, vLLM, or Custom pointing at an internal URL. Leave the API key empty if unused. **Test Connection** must succeed from the server, not from your laptop.

**Corporate HTTPS proxy.** Set **Proxy address** (and credentials if required). Put the local model host in **Bypass hosts**. Paste the proxy-inspecting CA in **CA certificate (PEM)** if the proxy intercepts TLS; do **not** leave **Skip certificate verification** on once that CA is trusted.

**Air-gapped.** Do not use a public preset. Run the model on the server network. The product does not need any other outbound Internet path for the assistant.

## Residual risk

After the controls above, the remaining risk is the operator's choice of destination and of how deep the tools may go. A public provider will see identifiers and aggregates you allow into the prompt. A local model keeps that traffic on-network but still concentrates telemetry in the model process. Skipping TLS verification, logging full request bodies, or granting **Query agents** together with live agent queries widens that surface.

**Mitigation.** Leave the assistant disabled if the disclosure is unacceptable. Prefer a local OpenAI-compatible server when telemetry must stay inside the deployment. Leave **Allow call parameters** and **Allow live agent queries** off unless a specific investigation needs them. Restrict **Use AI assistant**, **View parameters**, and **Query agents** accordingly. Do not leave **Skip certificate verification** or **Log model requests** on in production. Review the chosen provider's terms; they — not Flopsar Technology — may be a processor of what you send.