init

SECURITY.md

@@ -0,0 +1,66 @@
+# 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.