# Security model

## Trust boundaries

1. **Ticket content is untrusted.** It can contain prompt injection, HTML, links and attacker-controlled instructions.
2. **Knowledge files are trusted operator content.** Only reviewed files should be mounted into `knowledge/`.
3. **The LLM is advisory.** It never receives a callable GLPI tool. All writes are performed by deterministic Go code after policy checks.
4. **GLPI is the source of truth.** The ticket and followups are re-read immediately before writes.
5. **Operational context is read-only and treated as data.** Change descriptions, incident text, asset names and monitoring messages may still contain untrusted text and never become executable instructions.
6. **Uptime Kuma credentials stay in the connector.** API keys are used only for the HTTP request and are never included in the LLM prompt or audit payload.

## Auto-reply gates

An automatic response is only possible when all of these are true:

- `DRY_RUN=false`
- `AUTO_REPLY=true`
- no followup existed at the first check
- the model explicitly selects a knowledge ID
- the knowledge ID was in the retrieval result
- `knowledge.auto_reply=true`
- global and per-document similarity thresholds pass
- configured category restrictions pass
- reply confidence passes
- the ticket has not changed during inference (including requester/item relations relevant to context)
- enabled context sources completed successfully when `CONTEXT_BLOCK_AUTO_REPLY_ON_ERRORS=true`
- no relevant central Major Incident/Uptime outage is present when `CONTEXT_BLOCK_AUTO_REPLY_ON_INCIDENT=true`
- a second followup check immediately before POST is still empty

The actual user-facing answer comes from the reviewed knowledge JSON, not generated free text.

## Known concurrency boundary

Without a GLPI API primitive that atomically combines "no followup exists" and "create followup", a small race remains between the final GET and POST. The application minimizes this using a per-ticket process lock and a final followup recheck. Run one active application replica unless you replace the local queue/state/lock with distributed coordination.

## Deployment checklist

- Use a dedicated GLPI service account and least privileges.
- Use HTTPS for GLPI; plain HTTP requires an explicit unsafe override.
- Keep the dashboard bound to localhost/private networks behind TLS.
- Use strong Basic Auth credentials or put the dashboard behind your SSO reverse proxy.
- Keep `/metrics` and health endpoints on a trusted network.
- Keep `.env` outside source control and restrict filesystem permissions.
- Start with `DRY_RUN=true`, then category-only, then explicitly approved auto-replies.
- Review `data/runs.jsonl` and GLPI audit logs regularly.


## Kommunikations- und Quellenpolicy

- `KNOWLEDGE_ALLOWED_SOURCES` ist eine fail-closed Allowlist. Nur Dokumente mit einem dort genannten `source`-Label werden geladen, indexiert oder an das LLM übergeben.
- `KNOWLEDGE_AUTO_REPLY_SOURCES` ist eine zusätzliche Teilmengen-Allowlist für automatische Antworten. Eine Quelle darf also recherchierbar sein, ohne Schreibrechte auszulösen.
- Knowledge-Dokumente ohne `source` werden beim Start abgelehnt.
- Auto-Replies erfordern passende `language`- und `communication_style`-Metadaten. Die sicheren Defaults sind `de-DE` und `formal`.
- Anrede, Grußformel und Signatur werden außerhalb des LLM in der Go-Policy zusammengesetzt. Das Modell kann diese Werte nicht verändern.
- Die Metadaten sind eine fachliche Freigabeerklärung. Ein falsch als `de-DE/formal` gekennzeichneter Text wird nicht semantisch durch einen zweiten externen Dienst überprüft; deshalb müssen Auto-Reply-Dokumente weiterhin redaktionell geprüft werden.


## Operational context policy

- Change Calendar, Major Incident, Uptime Kuma and user/device integrations are **read-only**. They do not expand GLPI write capabilities.
- A configured context-source failure is fail-closed for automatic replies by default. This prevents the agent from sending an individual troubleshooting answer while central-service context is unavailable.
- Relevant Major Incidents and Uptime Kuma outages suppress normal Auto-Replies by default. They do not automatically close, merge or reassign tickets.
- `GLPI_MAJOR_INCIDENT_FILTER` is operator-controlled. Keep `MAJOR_INCIDENTS_ENABLED=false` until the query has been verified against the target GLPI instance.
- Asset lookup paths and filters are operator-controlled and validated where possible against GLPI's generated OpenAPI route list. Field/filter semantics still need Shadow-Mode verification on the real instance.
- Prefer Uptime Kuma `UPTIME_KUMA_MODE=metrics` for private monitoring. Store `UPTIME_KUMA_API_KEY` as a secret and give the key only the access needed for metrics. `status_page` mode should be used only for information safe to publish on that status page.
- Do not place passwords, tokens, personal secrets or raw diagnostic dumps into Change/Incident descriptions merely because the agent can read them; relevant text may be passed to the local Ollama model.

## Dashboard-Schreibfunktionen

`KNOWLEDGE_WEB_EDIT_ENABLED=true` darf nicht zusammen mit `WEB_ALLOW_ANONYMOUS=true` verwendet werden; die Konfiguration wird beim Start abgelehnt. Mutierende Dashboard-Endpunkte verlangen zusätzlich den Same-App-Request-Header `X-Requested-With: GLPI-AI-Agent`. Statische Knowledge-Dateien aus `KNOWLEDGE_DIR` bleiben read-only; Web-Inhalte werden ausschließlich unter `DATA_DIR/knowledge-managed/` persistiert.

Kategorie-Lernen ist Human-in-the-loop: Nur eine ausdrückliche Bestätigung/Korrektur im Dashboard wird als Lernbeispiel gespeichert. Der Agent übernimmt seine eigenen KI-Empfehlungen oder automatisch geschriebenen Kategorien niemals selbständig in den Lernbestand.

## GLPI Knowledge Base Connector

`GLPI_KB_ENABLED=true` creates a read-only synchronization path from the GLPI knowledge base into the local RAG store. The connector never creates, updates or deletes GLPI knowledge articles. GLPI's own authorization for the OAuth service account is the first visibility boundary; only articles returned to that account can enter the local cache/index.

Synchronized GLPI articles are read-only in the agent dashboard. Automatic replies from this source remain disabled unless all of the following are explicitly configured: the source is in `KNOWLEDGE_AUTO_REPLY_SOURCES`, `GLPI_KB_AUTO_REPLY=true`, and the article belongs to a GLPI Knowledge Base category listed in `GLPI_KB_AUTO_REPLY_CATEGORY_IDS`. In addition, the connector requires a GLPI KB-category -> ITIL-category mapping before marking an imported article as auto-reply eligible.

The normalized cache is stored in `DATA_DIR/glpi-kb-cache.json`; embeddings remain in `DATA_DIR/embeddings.json`. Treat both as potentially sensitive support data and protect/backup `DATA_DIR` accordingly.