Jarvis

Bitte setze ein neues Kennwort. Es muss mindestens 8 Zeichen, einen Großbuchstaben, einen Kleinbuchstaben und eine Ziffer enthalten.

Aktuelles Kennwort

Neues Kennwort

Kennwort bestätigen

SSL-Zertifikat installieren

Damit Browser diese Verbindung als sicher einstufen, muss das Zertifikat importiert werden.

Zertifikat herunterladen (jarvis.cer)

Lade die Datei jarvis.cer herunter.
Rechtsklick auf die Datei → "Zertifikat installieren".
Wähle "Lokaler Computer" (nicht "Aktueller Benutzer").
Wähle "Alle Zertifikate in folgendem Speicher speichern".
Klicke auf "Durchsuchen" und wähle "Vertrauenswürdige Stammzertifizierungsstellen".
Bestätigen und Fertigstellen.
Browser komplett neu starten (alle Tabs schließen).

# jarvis.cer liegt im DER-Format vor -> nach PEM konvertieren
openssl x509 -inform DER -in jarvis.cer -out jarvis-ca.crt

# 1) System-CA-Store (fuer curl/wget/git etc.) – .crt-Endung ist Pflicht
sudo cp jarvis-ca.crt /usr/local/share/ca-certificates/jarvis-ca.crt
sudo update-ca-certificates

# 2) Chrome/Chromium nutzen einen EIGENEN Store (NSS) – Pflicht fuer Autofill
sudo apt install -y libnss3-tools   # falls 'certutil' fehlt
mkdir -p $HOME/.pki/nssdb
certutil -d sql:$HOME/.pki/nssdb -A -t "C,," -n "Jarvis CA" -i jarvis-ca.crt

# danach Chrome komplett neu starten

Wichtig: Chrome/Chromium unter Linux vertrauen NUR dem NSS-Store (Schritt 2) – der System-Store allein reicht fuer das Passwort-Autofill nicht. Firefox: siehe Tab "Browser-Import".

Falls die System-Installation nicht greift (z.B. Firefox):

Öffne die Einstellungen deines Browsers.
Suche nach "Zertifikate" oder "Zertifikate verwalten".
Klicke auf "Importieren..." im Reiter "Zertifizierungsstellen" (Authorities).
Wähle die Datei jarvis.cer aus.
Setze den Haken bei "Dieser CA vertrauen, um Websites zu identifizieren".

Der Support-Assistent ist auch ohne Web-Oberfläche per REST erreichbar – z. B. aus Ticketsystemen, Skripten oder anderen Anwendungen. Basis-URL ist dein Jarvis-Host (https://DEIN-JARVIS-HOST). Alle Bodies sind JSON (Content-Type: application/json).

Authentifizierung

Angemeldeter Benutzer (Browser/Sitzung): Header Authorization: Bearer <token>
Externe Anwendung: Header X-API-Key: <API-Key> – API-Keys werden in den Einstellungen verwaltet. /query, /summarize sowie die CRM-Lookups (/api/jira/phonenumber, /api/jira/crm-number) akzeptieren API-Keys; die übrigen Endpunkte erfordern ein Benutzer-Token.

Endpunkte

Methode	Pfad	Zweck	Auth
`POST`	`/api/support/query`	Suche über RAG + Jira + Confluence, optional KI-Zusammenfassung	Token oder API-Key
`POST`	`/api/support/summarize`	KI-Zusammenfassung eines einzelnen Jira-Tickets – ODER Freitext mit Ticket-Key (z. B. `CRM-10550`) wird wie `/query` beantwortet	Token oder API-Key
`GET`	`/api/support/status`	Aktive Quellen + Maxima (Zeilen, Ticketanzahl)	Token
`GET/POST`	`/api/support/instructions`	Persönliche Anweisungen lesen/speichern (Markdown)	Token
`GET/DELETE`	`/api/support/history`	Suchverlauf des Benutzers lesen/löschen	Token
`GET`	`/api/jira/phonenumber`	CRM-Kundennummer (`CRM-xxxxxx`) zu einer Telefonnummer ermitteln	Token oder API-Key
`GET`	`/api/jira/crm-number`	Alle Tickets zu einer dedizierten CRM-Kundennummer finden	Token oder API-Key
`GET`	`/api/jira/passende-tickets`	Passende Tickets eines CRM-Kunden zu 2-5 Schlagworten (offen + abgeschlossen)	Token oder API-Key

Beispiel 1 – Suche mit KI-Zusammenfassung

Durchsucht Wissensdatenbank und (nur offene) Jira-Tickets, holt bis zu 10 Tickets und lässt eine KI-Gesamtzusammenfassung erstellen.

curl -sk https://DEIN-JARVIS-HOST/api/support/query \
  -H "X-API-Key: DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "text": "Drucker im 2. OG offline",
        "rag": true,
        "confluence": false,
        "ai": true,
        "jira_all": false,
        "jira_open": true,
        "jira_limit": 10,
        "summary_lines": 5,
        "prompt": "Antworte in Stichpunkten mit konkreten Lösungsschritten.",
        "lang": "de"
      }'

Antwort (gekürzt):

{
  "ok": true,
  "query": "Drucker im 2. OG offline",
  "ai_summary": "Mögliche Ursache ist ein Netzwerk-Timeout des Druckers …",
  "jira_total": 7,
  "blocks": [
    { "source": "JIRA",   "key": "SUP-1234", "title": "SUP-1234",
      "score": 92, "summary": "Drucker reagiert nicht …" },
    { "source": "WISSEN", "title": "Drucker-Reset Anleitung",
      "score": 80, "summary": "Schritt 1: …" }
  ]
}

Request-Felder `/api/support/query`

Alle Felder außer text sind optional. Die Maxima (*_max) stammen aus der Skill-Konfiguration und lassen sich über GET /api/support/status abfragen.

Feld	Typ	Default	Beschreibung
`text` (Alias `query`)	string	Pflicht	Die Suchanfrage / der Freitext. Leer → `400`. Enthält der Text einen Vorgangs-/CRM-Key (Muster `ABC-123`, z. B. `CRM-10550`), wird Jira unabhängig von den Jira-Flags immer durchsucht.
`rag`	bool	`true`	Wissensdatenbank einbeziehen (RAG – TF-IDF/Vektor-Suche).
`confluence`	bool	`true`	Confluence-Seiten durchsuchen (nur wirksam, wenn der Confluence-Skill aktiv ist).
`ibs`	bool	`false`	Kundenverwaltung (IBS) durchsuchen – Ticket-/Ereignissuche über die API-Funktion „getMatchingEvents" (nur wirksam, wenn URL und API-Key der Kundenverwaltung hinterlegt sind).
`ai`	bool	`true`	KI-Gesamtzusammenfassung (`ai_summary`) über alle Treffer erzeugen.
`jira_all`	bool	`false`	„Alle Jira-Tickets" (offen + geschlossen) durchsuchen.
`jira_open`	bool	`false`	„Nur offene Jira-Tickets" durchsuchen. Sind `jira_all` und `jira_open` beide `true`, gewinnt `jira_all`.
`jira_limit`	int	`ticket_count_default` (12)	Max. Anzahl geladener Jira-Tickets, begrenzt auf 1 … `ticket_count_max` (Admin-Maximum, Standard 50).
`summary_lines`	int	`summary_lines_max` (5)	Max. Satzanzahl der KI-Gesamtzusammenfassung, begrenzt auf 2 … `summary_lines_max`. Nur wirksam bei `ai:true`.
`prompt` (Alias `instruction`)	string	–	Ad-hoc-Anweisung nur für diesen Aufruf; wird zusätzlich zum Admin-Prompt und den persönlichen Anweisungen an die KI-Gesamtzusammenfassung gehängt (z. B. Fokus, Tonfall, Format). Nur wirksam bei `ai:true`.
`lang`	string	`"de"`	Sprache der KI-Zusammenfassung: `de` oder `en`.

Antwort-Felder `/api/support/query`

Feld	Typ	Beschreibung
`ok`	bool	Erfolgskennzeichen. Bei Fehlern `false` plus `error`.
`query`	string	Die ausgewertete Anfrage.
`blocks`	array	Alle Treffer, nach `score` absteigend (Felder siehe unten).
`ai_summary`	string	KI-Gesamtzusammenfassung (leer bei `ai:false` oder ohne Treffer).
`jira_total`	int \| null	Gesamtzahl gefundener Jira-Treffer vor der `jira_limit`-Deckelung (`null`, wenn Jira nicht abgefragt wurde).
`open_only`	bool	Ob nur offene Tickets berücksichtigt wurden.
`jira_active`, `confluence_active`	bool	Ob die jeweilige Quelle serverseitig aktiv ist.
`jira_base`	string	Basis-URL der Jira-Instanz (zum Bauen von Ticket-Links).
`summary_lines_max`	int	Maximale Satzanzahl der KI-Zusammenfassung. Der Treffer-Text wird vollständig geliefert (keine Zeilen-Begrenzung).
`took_ms`	int	Server-Laufzeit der Anfrage in Millisekunden.

Jedes Element in blocks[] hat: source (WISSEN | JIRA | CONFLUENCE), title, summary (Kurzfassung), score (Relevanz in %), source_label und link (URL bzw. interner Abruf-Link). Quellenspezifisch zusätzlich: key, created (Erstellungsdatum) und updated (letzte Änderung) – jeweils nur JIRA, ISO-8601, doc + doc_name (nur WISSEN – Quelldokument), full_text (nur CONFLUENCE – gekappter Volltext).

Beispiel 2 – Einzelnes Ticket zusammenfassen

Lädt ein konkretes Jira-Ticket (Beschreibung + Kommentare) und fasst es in wenigen Sätzen zusammen.

curl -sk https://DEIN-JARVIS-HOST/api/support/summarize \
  -H "X-API-Key: DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "source": "JIRA", "key": "SUP-1234", "lang": "de" }'

Antwort:

{
  "ok": true,
  "key": "SUP-1234",
  "summary": "Das Ticket beschreibt einen Druckerausfall im 2. OG …"
}

Request-Felder `/api/support/summarize`

Modus A – Einzel-Ticket (key gesetzt, kein Ticket-Key im Freitext):

Feld	Typ	Default	Beschreibung
`key`	string	Pflicht	Jira-Ticket-Key, z. B. `SUP-1234`. Beschreibung + letzte Kommentare werden nachgeladen und zusammengefasst.
`source`	string	`"JIRA"`	Aktuell wird nur `JIRA` unterstützt (anderer Wert → `400`).
`lines`	int	`summary_lines_max` (5)	Satzanzahl der Zusammenfassung, begrenzt auf 2 … `summary_lines_max` (Admin-Maximum).
`lang`	string	`"de"`	Sprache der Zusammenfassung: `de` oder `en`.

Antwort: { "ok": true, "key": "…", "summary": "…", "jira_base": "…" }.

Modus B – Freitext mit Ticket-Key: Enthält text/query einen Vorgangs-/CRM-Key (z. B. { "text": "Status zu CRM-10550?" }), wird die Anfrage exakt wie /api/support/query beantwortet – volle Pipeline inkl. KI-Gesamtzusammenfassung, gleiche Antwortstruktur. In diesem Modus gelten alle oben genannten /query-Felder (inkl. prompt, jira_limit, …).

Fehler & Status-Codes

200 / 201 – Erfolg. Fehler liefern stets { "ok": false, "error": "…" }.
400 – ungültige Eingabe (z. B. leerer text, unbekannte source).
401 – nicht authentifiziert (Token/API-Key fehlt oder ungültig).
403 – Support-Skill inaktiv oder Konto gesperrt (Antwort dann mit "account_blocked": true).
499 – Client hat die Verbindung abgebrochen (z. B. „Abbrechen"); die Anfrage wird serverseitig gestoppt.
502 – KI-Zusammenfassung fehlgeschlagen (nur /summarize, Einzel-Ticket).

Hinweis: -k (curl) akzeptiert das selbstsignierte Zertifikat – nur für Tests.

🔎 CRM-Lookups (Jira)

Direkte Nachschlage-Endpunkte für die Anbindung von Telefonanlage/CTI oder Ticketsystem: aus einer Telefonnummer die zugehörige CRM-Kundennummer bestimmen bzw. zu einer CRM-Kundennummer alle Tickets abrufen. Beide sind GET-Aufrufe und akzeptieren Benutzer-Token oder externen API-Key. Setzt einen aktiven, konfigurierten Jira-Skill voraus.

Beispiel 3 – CRM-Kundennummer zu einer Telefonnummer

Sucht die Telefonnummer im Jira-CRM-Objektschema (Insight/Assets, Objektschema CRM, Standard-Schema-ID 21) – konkret in den Telefon-Attributen der CRM-Objekte (Zentrale Rufnummer, Telefonnummer, Mobil Nummer, …). Der Objekt-Key ist die CRM-Kundennummer (CRM-xxxxxx), es werden also ausschließlich CRM-Einträge zurückgegeben.

curl -sk "https://DEIN-JARVIS-HOST/api/jira/phonenumber?phone=%2B4920562611" \
  -H "X-API-Key: DEIN_API_KEY"

Die Nummer +4920562611 wird zu reinen Ziffern-Varianten normalisiert (+ = %2B in der URL): 4920562611 (voll international), 020562611 (national mit 0), 20562611 (ohne Vorwahl). Diese werden – von der längsten (eindeutigsten) zur kürzesten – per IQL like gegen die Telefon-Attribute geprüft; die erste Variante mit Treffern gewinnt. Telefonnummern liegen im CRM-Schema international/zusammenhängend (z. B. +4920562611).

Die Treffer werden nach Objekttyp sortiert: Organisationen zuerst, dann Organisationen-Produktgruppen, dann Personen. Der erste Treffer (Feld crm) ist damit die Organisation selbst. Antwort (Namen hier anonymisiert):

{
  "ok": true,
  "phone": "+4920562611",
  "crm": "CRM-66648",
  "found": true,
  "matches": [
    { "key": "CRM-66648",  "name": "Muster Klinikum GmbH",   "type": "Organisationen" },
    { "key": "CRM-421832", "name": "Muster Produktgruppe",    "type": "Organisationen Produktgruppen" },
    { "key": "CRM-158352", "name": "Muster Ansprechpartner",  "type": "Personen" }
  ],
  "total": 8,
  "variant": "4920562611"
}

Parameter	Typ	Default	Beschreibung
`phone` (Aliase `phonenumber`, `number`)	string	Pflicht	Die Telefonnummer (beliebige Schreibweise, z. B. `+49 151 123456`, `0151/123456`). In der URL muss `+` als `%2B` kodiert werden.
`limit`	int	`25`	Max. Anzahl zurückgegebener CRM-Objekte (1 … 50).

Antwort-Felder: crm (erste gefundene CRM-Kundennummer bzw. null, nach Priorisierung die Organisation), found (bool), matches[] (alle Treffer als key + name + type = Objekttyp), total (Anzahl passender CRM-Objekte), variant (die Nummern-Variante, die getroffen hat), iql (ausgeführte IQL-Abfrage). Hinweis: Teilen sich mehrere Kunden dieselbe Rufnummer (z. B. zentrale Nummer), werden alle zugehörigen CRM-Objekte gelistet. Schema-ID, geprüfte Telefon-Attribute und die Typ-Reihenfolge sind über die Jira-Skill-Konfiguration (insight_schema_id / insight_phone_attrs / insight_type_priority) anpassbar.

Beispiel 4 – Alle Tickets zu einer CRM-Kundennummer

Sucht exakt im Insight-Organisationsfeld und liefert damit alle dem Kunden zugeordneten Tickets (nicht nur Volltext-Treffer), neueste zuerst.

curl -sk "https://DEIN-JARVIS-HOST/api/jira/crm-number?crm=CRM-10550&limit=25" \
  -H "X-API-Key: DEIN_API_KEY"

Antwort (gekürzt):

{
  "ok": true,
  "crm": "CRM-10550",
  "total": 7,
  "jql": "Organisation = \"CRM-10550\" ORDER BY updated DESC",
  "results": [
    { "key": "NXCIS-42", "summary": "Störung Drucker", "status": "Offen",
      "type": "Bug", "priority": "Hoch", "assignee": "…", "link": "https://…/browse/NXCIS-42" }
  ]
}

Parameter	Typ	Default	Beschreibung
`crm` (Aliase `crm_number`, `number`)	string	Pflicht	Die CRM-Kundennummer im Muster `CRM-xxxxxx` (z. B. `CRM-10550`). Ein anderes Format → `400`.
`limit`	int	`25`	Max. Anzahl zurückgegebener Tickets (1 … 50).

Antwort-Felder: crm (normalisierte Nummer), total (Jira-Gesamttreffer), results[] (Tickets mit key, summary, status, type, priority, assignee, created, updated, link), jql. Das Organisationsfeld ist über die Jira-Skill-Konfiguration (org_field) anpassbar.

Beispiel 5 – Passende Tickets eines CRM-Kunden zu Schlagworten

Kombiniert die exakte CRM-Kundensuche mit 2 bis 5 Schlagworten (Volltext, OR-verknüpft) und liefert offene und abgeschlossene Tickets des Kunden, neueste zuerst.

curl -sk "https://DEIN-JARVIS-HOST/api/jira/passende-tickets?crm=CRM-10550&keywords=drucker,fehler,vpn&limit=25" \
  -H "X-API-Key: DEIN_API_KEY"

Antwort (gekürzt):

{
  "ok": true,
  "crm": "CRM-10550",
  "keywords": ["drucker", "fehler", "vpn"], "match": "all",
  "total": 5, "returned": 5, "open": 2, "closed": 3,
  "jql": "Organisation = \"CRM-10550\" AND (text ~ \"drucker\" AND text ~ \"fehler\" AND text ~ \"vpn\") ORDER BY updated DESC",
  "results": [
    { "key": "NXCIS-42", "summary": "Störung Drucker", "status": "Erledigt",
      "type": "Bug", "priority": "Hoch", "resolved": true, "link": "https://…/browse/NXCIS-42" }
  ]
}

Parameter	Typ	Default	Beschreibung
`crm` (Aliase `crm_number`, `number`, `kunde`)	string	Pflicht	CRM-Kundennummer im Muster `CRM-xxxxxx`. Anderes Format → `400`.
`keywords` (Alias `q`)	string	Pflicht	2 bis 5 Schlagworte, komma- oder leerzeichengetrennt (z. B. `drucker,fehler,vpn`). Weniger als 2 oder mehr als 5 → `400`.
`match`	string	`all`	`all` = Ticket muss ALLE Schlagworte enthalten (UND); `any` = irgendeines (ODER).
`limit`	int	`25`	Max. Anzahl zurückgegebener Tickets (1 … 50).

Antwort-Felder: crm, keywords[], total (Jira-Gesamttreffer), returned (Anzahl gelieferter Tickets), open/closed (offen/abgeschlossen, bezogen auf die gelieferte Seite), results[] (Tickets zusätzlich mit resolved = abgeschlossen ja/nein), jql. Es wird KEIN Status-/Resolution-Filter gesetzt → offene wie abgeschlossene Vorgänge kommen zurück.

The support assistant is also accessible via REST without the web UI – e.g. from ticket systems, scripts or other applications. The base URL is your Jarvis host (https://YOUR-JARVIS-HOST). All bodies are JSON (Content-Type: application/json).

Authentication

Logged-in user (browser/session): header Authorization: Bearer <token>
External application: header X-API-Key: <API key> – API keys are managed in the settings. /query, /summarize and the CRM lookups (/api/jira/phonenumber, /api/jira/crm-number) accept API keys; the remaining endpoints require a user token.

Endpoints

Method	Path	Purpose	Auth
`POST`	`/api/support/query`	Search across RAG + Jira + Confluence, optional AI summary	Token or API key
`POST`	`/api/support/summarize`	AI summary of a single Jira ticket – OR free text containing a ticket key (e.g. `CRM-10550`) is answered like `/query`	Token or API key
`GET`	`/api/support/status`	Active sources + maxima (lines, ticket count)	Token
`GET/POST`	`/api/support/instructions`	Read/save personal instructions (Markdown)	Token
`GET/DELETE`	`/api/support/history`	Read/delete the user's search history	Token
`GET`	`/api/jira/phonenumber`	Determine the CRM customer number (`CRM-xxxxxx`) for a phone number	Token or API key
`GET`	`/api/jira/crm-number`	Find all tickets for a dedicated CRM customer number	Token or API key
`GET`	`/api/jira/passende-tickets`	Matching tickets of a CRM customer for 2-5 keywords (open + closed)	Token or API key

Example 1 – Search with AI summary

Searches the knowledge base and (only open) Jira tickets, fetches up to 10 tickets and has an overall AI summary generated.

curl -sk https://YOUR-JARVIS-HOST/api/support/query \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "text": "Printer on the 2nd floor offline",
        "rag": true,
        "confluence": false,
        "ai": true,
        "jira_all": false,
        "jira_open": true,
        "jira_limit": 10,
        "summary_lines": 5,
        "prompt": "Answer in bullet points with concrete solution steps.",
        "lang": "en"
      }'

Response (shortened):

{
  "ok": true,
  "query": "Printer on the 2nd floor offline",
  "ai_summary": "A likely cause is a network timeout of the printer …",
  "jira_total": 7,
  "blocks": [
    { "source": "JIRA",   "key": "SUP-1234", "title": "SUP-1234",
      "score": 92, "summary": "Printer not responding …" },
    { "source": "WISSEN", "title": "Printer reset guide",
      "score": 80, "summary": "Step 1: …" }
  ]
}

Request fields `/api/support/query`

All fields except text are optional. The maxima (*_max) come from the skill configuration and can be queried via GET /api/support/status.

Field	Type	Default	Description
`text` (alias `query`)	string	required	The search query / free text. Empty → `400`. If the text contains an issue/CRM key (pattern `ABC-123`, e.g. `CRM-10550`), Jira is always searched regardless of the Jira flags.
`rag`	bool	`true`	Include the knowledge base (RAG – TF-IDF/vector search).
`confluence`	bool	`true`	Search Confluence pages (only effective if the Confluence skill is active).
`ibs`	bool	`false`	Search customer management (IBS) – ticket/event search via the "getMatchingEvents" API function (only effective if the customer management URL and API key are configured).
`ai`	bool	`true`	Generate an overall AI summary (`ai_summary`) across all hits.
`jira_all`	bool	`false`	Search "all Jira tickets" (open + closed).
`jira_open`	bool	`false`	Search "open Jira tickets only". If `jira_all` and `jira_open` are both `true`, `jira_all` wins.
`jira_limit`	int	`ticket_count_default` (12)	Max. number of Jira tickets loaded, limited to 1 … `ticket_count_max` (admin maximum, default 50).
`summary_lines`	int	`summary_lines_max` (5)	Max. number of sentences of the overall AI summary, limited to 2 … `summary_lines_max`. Only effective with `ai:true`.
`prompt` (alias `instruction`)	string	–	Ad-hoc instruction for this call only; appended to the overall AI summary in addition to the admin prompt and the personal instructions (e.g. focus, tone, format). Only effective with `ai:true`.
`lang`	string	`"de"`	Language of the AI summary: `de` or `en`.

Response fields `/api/support/query`

Field	Type	Description
`ok`	bool	Success flag. On errors `false` plus `error`.
`query`	string	The evaluated query.
`blocks`	array	All hits, sorted by `score` descending (fields see below).
`ai_summary`	string	Overall AI summary (empty with `ai:false` or without hits).
`jira_total`	int \| null	Total number of Jira hits before the `jira_limit` cap (`null` if Jira was not queried).
`open_only`	bool	Whether only open tickets were considered.
`jira_active`, `confluence_active`	bool	Whether the respective source is active server-side.
`jira_base`	string	Base URL of the Jira instance (for building ticket links).
`summary_lines_max`	int	Maximum sentence count of the AI summary. The hit text is returned in full (no line limit).
`took_ms`	int	Server processing time of the request in milliseconds.

Each element in blocks[] has: source (WISSEN | JIRA | CONFLUENCE), title, summary (short version), score (relevance in %), source_label and link (URL or internal fetch link). Source-specific additionally: key, created (creation date) and updated (last modified) – JIRA only, ISO-8601, doc + doc_name (WISSEN only – source document), full_text (CONFLUENCE only – truncated full text).

Example 2 – Summarize a single ticket

Loads a specific Jira ticket (description + comments) and summarizes it in a few sentences.

curl -sk https://YOUR-JARVIS-HOST/api/support/summarize \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "source": "JIRA", "key": "SUP-1234", "lang": "en" }'

Response:

{
  "ok": true,
  "key": "SUP-1234",
  "summary": "The ticket describes a printer outage on the 2nd floor …"
}

Request fields `/api/support/summarize`

Mode A – single ticket (key set, no ticket key in the free text):

Field	Type	Default	Description
`key`	string	required	Jira ticket key, e.g. `SUP-1234`. Description + latest comments are fetched and summarized.
`source`	string	`"JIRA"`	Currently only `JIRA` is supported (any other value → `400`).
`lines`	int	`summary_lines_max` (5)	Number of sentences of the summary, limited to 2 … `summary_lines_max` (admin maximum).
`lang`	string	`"de"`	Language of the summary: `de` or `en`.

Response: { "ok": true, "key": "…", "summary": "…", "jira_base": "…" }.

Mode B – free text containing a ticket key: if text/query contains an issue/CRM key (e.g. { "text": "Status of CRM-10550?" }), the request is answered exactly like /api/support/query – full pipeline incl. overall AI summary, same response structure. In this mode all /query fields listed above apply (incl. prompt, jira_limit, …).

Errors & status codes

200 / 201 – success. Errors always return { "ok": false, "error": "…" }.
400 – invalid input (e.g. empty text, unknown source).
401 – not authenticated (token/API key missing or invalid).
403 – support skill inactive or account blocked (response then contains "account_blocked": true).
499 – the client aborted the connection (e.g. "Cancel"); the request is stopped server-side.
502 – AI summary failed (only /summarize, single ticket).

Note: -k (curl) accepts the self-signed certificate – for testing only.

🔎 CRM lookups (Jira)

Direct lookup endpoints for integrating a phone system/CTI or ticket system: determine the CRM customer number for a phone number, or fetch all tickets for a CRM customer number. Both are GET calls and accept a user token or an external API key. Requires an active, configured Jira skill.

Example 3 – CRM customer number for a phone number

Searches the phone number in the Jira CRM object schema (Insight/Assets, object schema CRM, default schema ID 21) – specifically in the phone attributes of the CRM objects (Zentrale Rufnummer, Telefonnummer, Mobil Nummer, …). The object key is the CRM customer number (CRM-xxxxxx), so only CRM entries are returned.

curl -sk "https://YOUR-JARVIS-HOST/api/jira/phonenumber?phone=%2B4920562611" \
  -H "X-API-Key: YOUR_API_KEY"

The number +4920562611 is normalized to digit-only variants (+ = %2B in the URL): 4920562611 (fully international), 020562611 (national with 0), 20562611 (without prefix). These are checked – from the longest (most specific) to the shortest – against the phone attributes via IQL like; the first variant with hits wins. Phone numbers are stored internationally/contiguously in the CRM schema (e.g. +4920562611).

The hits are sorted by object type: organizations first (Organisationen), then organization product groups, then persons. The first hit (field crm) is therefore the organization itself. Response (names anonymized here):

{
  "ok": true,
  "phone": "+4920562611",
  "crm": "CRM-66648",
  "found": true,
  "matches": [
    { "key": "CRM-66648",  "name": "Muster Klinikum GmbH",   "type": "Organisationen" },
    { "key": "CRM-421832", "name": "Muster Produktgruppe",    "type": "Organisationen Produktgruppen" },
    { "key": "CRM-158352", "name": "Muster Ansprechpartner",  "type": "Personen" }
  ],
  "total": 8,
  "variant": "4920562611"
}

Parameter	Type	Default	Description
`phone` (aliases `phonenumber`, `number`)	string	required	The phone number (any notation, e.g. `+49 151 123456`, `0151/123456`). In the URL, `+` must be encoded as `%2B`.
`limit`	int	`25`	Max. number of returned CRM objects (1 … 50).

Response fields: crm (first CRM customer number found or null; after prioritization the organization), found (bool), matches[] (all hits as key + name + type = object type), total (number of matching CRM objects), variant (the number variant that matched), iql (executed IQL query). Note: if several customers share the same phone number (e.g. a central number), all associated CRM objects are listed. Schema ID, checked phone attributes and the type order can be adjusted via the Jira skill configuration (insight_schema_id / insight_phone_attrs / insight_type_priority).

Example 4 – All tickets for a CRM customer number

Searches exactly in the Insight organization field and thus returns all tickets assigned to the customer (not just full-text hits), newest first.

curl -sk "https://YOUR-JARVIS-HOST/api/jira/crm-number?crm=CRM-10550&limit=25" \
  -H "X-API-Key: YOUR_API_KEY"

Response (shortened):

{
  "ok": true,
  "crm": "CRM-10550",
  "total": 7,
  "jql": "Organisation = \"CRM-10550\" ORDER BY updated DESC",
  "results": [
    { "key": "NXCIS-42", "summary": "Printer failure", "status": "Open",
      "type": "Bug", "priority": "High", "assignee": "…", "link": "https://…/browse/NXCIS-42" }
  ]
}

Parameter	Type	Default	Description
`crm` (aliases `crm_number`, `number`)	string	required	The CRM customer number in the pattern `CRM-xxxxxx` (e.g. `CRM-10550`). Any other format → `400`.
`limit`	int	`25`	Max. number of returned tickets (1 … 50).

Response fields: crm (normalized number), total (Jira total hits), results[] (tickets with key, summary, status, type, priority, assignee, created, updated, link), jql. The organization field can be adjusted via the Jira skill configuration (org_field).

Example 5 – Matching tickets of a CRM customer for keywords

Combines the exact CRM customer search with 2 to 5 keywords (full text, OR-linked) and returns the customer's open and closed tickets, newest first.

curl -sk "https://YOUR-JARVIS-HOST/api/jira/passende-tickets?crm=CRM-10550&keywords=printer,error,vpn&limit=25" \
  -H "X-API-Key: YOUR_API_KEY"

Response (shortened):

{
  "ok": true,
  "crm": "CRM-10550",
  "keywords": ["printer", "error", "vpn"], "match": "all",
  "total": 5, "returned": 5, "open": 2, "closed": 3,
  "jql": "Organisation = \"CRM-10550\" AND (text ~ \"printer\" AND text ~ \"error\" AND text ~ \"vpn\") ORDER BY updated DESC",
  "results": [
    { "key": "NXCIS-42", "summary": "Printer failure", "status": "Done",
      "type": "Bug", "priority": "High", "resolved": true, "link": "https://…/browse/NXCIS-42" }
  ]
}

Parameter	Type	Default	Description
`crm` (aliases `crm_number`, `number`, `kunde`)	string	required	CRM customer number in the pattern `CRM-xxxxxx`. Any other format → `400`.
`keywords` (alias `q`)	string	required	2 to 5 keywords, comma- or space-separated (e.g. `printer,error,vpn`). Fewer than 2 or more than 5 → `400`.
`match`	string	`all`	`all` = ticket must contain ALL keywords (AND); `any` = any of them (OR).
`limit`	int	`25`	Max. number of returned tickets (1 … 50).

Response fields: crm, keywords[], total (Jira total hits), returned (number of returned tickets), open/closed (open/closed, relative to the returned page), results[] (tickets additionally with resolved = closed yes/no), jql. No status/resolution filter is applied → both open and closed issues are returned.

Diese Sicherheitsschicht schützt den Agenten gegen Rechteausweitung, Datenabfluss und Prompt-Injection durch Netzwerk-/Domain-Benutzer. Leitprinzip: Zugriffskontrolle wird im Code am Tool-Dispatch erzwungen – nicht als Bitte im System-Prompt. Sie ist dadurch nicht per Prompt, Base64-Kodierung oder „gelernten Fakten" umgehbar.

1. Rollenmodell

Lokale Administratoren (ALLOWED_USERS = jarvis/root sowie in Sicherheit → LDAP → Administratoren freigeschaltete AD-Konten): voller Zugriff, keine Einschränkung.
Netzwerk-/Domain-Benutzer (LDAP, nicht privilegiert): unterliegen sämtlichen unten beschriebenen Beschränkungen. Erkennung in agent.py über _LOCAL_PRIVILEGED_USERS; die Prüfungen laufen in _execute_tool() pro Tool-Aufruf.

2. Dateisystem-Confinement (`filesystem`-Tool)

Umgesetzt in backend/sandbox.py → authorize_fs(action, path). Pfade werden vollständig aufgelöst (Symlinks), um Ausbrüche wie /tmp/link → /etc/shadow zu verhindern.

Aktion	Erlaubt für Domain-Benutzer
write / append / mkdir	nur `/tmp` und `data/documents` (`WRITE_ROOTS`)
read / list / exists	nur Wissens-/Arbeitsverzeichnisse (`READ_ROOTS`: `/tmp`, `/mnt/jarvis-kb`, `data/knowledge`, `data/documents`)

Immer gesperrt (is_sensitive()): Secrets (.env, settings.json, memory.json, auth_state.json, *.key/.pem/.crt/.p12, id_rsa, .ssh/, certs/), System (/root, /etc/shadow, /etc/sudoers, /boot, /proc, /sys) und App-Interna (data/settings.json, data/logs, Audit-/Konversations-Logs).

3. Shell-Härtung (`shell_execute`)

Mehrstufige Prüfung in agent.py + sandbox.authorize_shell():

Systemverändernde Befehle blockiert (_LDAP_SHELL_FORBIDDEN): rm, chmod, chown, apt/pip/npm install, systemctl, reboot, dd, mkfs, useradd, passwd, tee …
Verschleierung blockiert (SHELL_OBFUSCATION): base64 -d, xxd -r, eval, source, Pipe in bash/sh/python/perl/…. Schließt die Base64-Umgehung.
Secret-/Root-Pfade blockiert (SHELL_SECRET_PATHS) – interpreterunabhängig (greift auch bei cat oder python open()).
Schreib-Umleitungen (>) nur nach /tmp.

4. OS-Sandbox (harte Grenze)

Optional, aktiviert über die Einstellung sandbox_shell_user. Ist sie gesetzt, führt backend/tools/shell.py Shell-Befehle von Domain-Benutzern via runuser -u <user> -- /bin/bash -c … als unprivilegierter Betriebssystem-Benutzer mit Arbeitsverzeichnis /tmp aus (wrap_sandboxed()). Damit erzwingt das Betriebssystem die Grenze – unabhängig davon, wie ein Befehl formuliert oder kodiert ist (Python, Base64, …). Provisionierung: unprivilegierten Systembenutzer anlegen und Secrets per Dateirechten (chmod 600, /root = 700) unzugänglich machen. Ohne diese Einstellung greift „nur" die Code-Härtung (Punkte 2–3).

5. Keine Rechteausweitung über Sub-Agenten

Beim Start eines Sub-Agenten (z. B. coding_agent, Agent-Orchestrator) werden Benutzeridentität und Internet-Freigabe vererbt. Ein Sub-Agent eines Domain-Benutzers unterliegt denselben Confinement-Regeln; er läuft nicht mit leerem/privilegiertem Kontext.

6. Angriffserkennung (Guard)

In backend/security_guard.py, ausgewertet pro Chat-/Support-/WhatsApp-Eingabe (inspect()):

Heuristik: Regex-Signaturen bekannter Jailbreak-/Injection-Muster („ignore all previous instructions", DAN, „reveal system prompt", „bypass safety" …).
LLM-Klassifikator (optional): bewertet Eingaben zusätzlich. Hybrid (beide aktiv): der Klassifikator bestätigt jeden Heuristik-Verdacht vor der Sperre (weniger Fehlalarme).
Base64-Erkennung (decode_and_scan()): dekodiert Base64-Blöcke der Eingabe und prüft den Klartext auf Jailbreak-/Shell-/Secret-Indikatoren – schließt die Guard-Umgehung durch Kodierung.

7. Verstoß-Protokoll & automatische Sperre

Jeder im Dispatch verweigerte Zugriff wird als Verstoß protokolliert (record_violation()) – mit Tool, Klartext-Detail, auslösender Anfrage (Prompt), IP und Kanal. Ab einer Schwelle innerhalb eines Zeitfensters wird das Konto automatisch gesperrt.

Standard: 3 Verstöße in 600 s → Sperre. Konfigurierbar über security_autoblock_enabled, security_autoblock_count, security_autoblock_window.
Lokale Administratoren werden nie automatisch gesperrt (exempt).
Gesperrte Konten können sich noch anmelden, sehen aber nur den Sperr-Bildschirm samt Protokoll. Freischalten ausschließlich durch einen lokalen Benutzer (Gesperrte Konten → Freischalten).
Anzeige: „Letzte Zugriffs-Verstöße" und „Gesperrte Konten" in diesem Bereich; API: /api/security/violations, /api/security/incidents, /api/security/sandbox.
Internet-Egress-Sperre (harte Firewall-Grenze für Benutzer ohne Internet-Freigabe): Status via GET /api/security/egress (mit ?live=1 Live-Test), Ein-Klick-Einrichtung via POST /api/security/egress/setup, Deaktivierung via POST /api/security/egress/teardown. Bedienung unter Sicherheit → Berechtigungen → Harte Egress-Sperre.
OS-Sandbox (Systemschutz Netzwerk-Benutzer): Status via GET /api/security/sandbox (mit ?live=1 Isolationstest), Ein-/Ausschalten via POST /api/security/sandbox/setup bzw. /teardown. Bedienung unter Sicherheit → Berechtigungen → Systemschutz / Sandbox.
Automatische Sicherheitsupdates (System): Status via GET /api/security/unattended (mit ?live=1 Trockenlauf), Ein-/Ausschalten via POST /api/security/unattended/setup bzw. /teardown. Richtet unattended-upgrades bewusst eng ein: nur die Debian-Sicherheits-Quelle, kein automatischer Neustart, kein automatisches Aufräumen von Paketen. Beim Ausschalten bleibt die tägliche Aktualisierung des Paketindex aktiv. Bedienung unter KI & System → System-Einstellungen → Automatische Sicherheitsupdates.
Root-Broker (Trennung UI-/Ausführungsebene): Betriebsmodus via GET /api/broker/status, Ein-Klick-Umschaltung via POST /api/broker/setup (getrennter Betrieb) bzw. POST /api/broker/teardown (Alt-Betrieb), Freigabeliste via GET /api/broker/ops, Admin-Entscheidung via POST /api/broker/ops/decide (Body {key, decision: allow|deny|pending}), Eintrag löschen via POST /api/broker/ops/remove, Audit-Log via GET /api/broker/audit?n=100. Bedienung unter Sicherheit → Root-Freigaben (Root-Broker).
Zeitversetzte Auslöser (seit 2026-07-29): Zeitgesteuerte Aufträge (POST/PUT /api/cron, POST /api/cron/{id}/run) und Trigger-Watcher (POST/PUT /api/watchers) darf nur ein Administrator anlegen bzw. ändern; das Werkzeug cron_create ist für Netzwerk-Benutzer gesperrt. Grund: ein solcher Eintrag startet später selbständig einen Agenten mit vollem Werkzeugkasten – außerhalb jeder Sitzung, ohne Freigabe. Sehen und Löschen eigener Einträge bleibt erlaubt (Altbestand aufräumbar). Ausnahme: unter Sicherheit → Erinnerungen per Messenger freigegebene Absender (GET/POST /api/reminders/senders) dürfen sich einmalige Erinnerungen an sich selbst setzen – reiner Nachrichtenversand ohne Agent, gedeckelt auf 20 offene je Absender.

8. Schutz vor Kontext-Vergiftung

Lern-Filter (learning.py → _sanitize_learned()): sicherheits-/rechte-bezogene „Fakten" (z. B. „root ist erlaubt", Secrets, sudo, base64) werden vor dem Speichern verworfen – es lässt sich keine Rechteausweitung „antrainieren".
Untrusted-Rahmung: Gedächtnis/gelernte Fakten werden dem Modell als [UNTRUSTED_CONTEXT] übergeben – reine Information, keine Anweisungen.
Unveränderliche Sicherheits-Grundregel an oberster Stelle des System-Prompts: Rechte kommen nur vom System; keine kodierten Anweisungen ausführen; Domain-Benutzer sind keine Administratoren. Diese Regel ist dem Modell übergeordnet, ersetzt aber nicht die Code-Erzwingung.

9. Konfiguration

Einstellungen → Sicherheit: Sicherheitsschicht (Master), Heuristik, LLM-Klassifikator; Anzeige Sandbox-Status + Verstöße + gesperrte Konten.
sandbox_shell_user – OS-Sandbox-Benutzer (leer = OS-Sandbox aus, nur Code-Härtung).
security_autoblock_* – Auto-Sperre-Schwelle/-Fenster.

10. Trennung UI-/Ausführungsebene (Root-Broker)

Im getrennten Betrieb läuft das Backend (Web-Oberfläche, Chat, Agent) als unprivilegierter Dienst-Benutzer; alles, was root braucht, läuft über den separaten Root-Broker (jarvis-broker.service, Unix-Socket). Der Broker kennt nur benannte, validierte Operationen (Dienst-Neustart, VNC, Sandbox, Mounts, Zertifikate …). Jede Operation wird beim ersten Auftauchen als auditierbarer Eintrag registriert: Systemoperationen automatisch erlaubt (vom Admin widerrufbar), beliebige Root-Shell-Befehle des Agenten dagegen erst nach expliziter Admin-Freigabe (Status „wartet auf Freigabe"). Policy und Audit-Log gehören root und sind vom Backend nicht manipulierbar. Verwaltung unter Sicherheit → Root-Freigaben.

11. Grenzen & Restrisiko

Die Muster-Prüfungen (Regex, Guard-Heuristik) sind Defense-in-Depth. Die harte Garantie für Shell-Befehle liefert die OS-Sandbox (Punkt 4) bzw. im getrennten Betrieb der unprivilegierte Dienst-Benutzer + Root-Broker (Punkt 10). Auf Alt-Installationen ohne Trennung (Backend als root) bleibt ein prinzipielles Restrisiko, da als root ausgeführter Code Wege finden kann. Empfehlung: Rechte-Trennung einrichten (deploy/security/setup_broker.sh), OS-Sandbox aktivieren und Secrets per Dateirechten absichern.

Die Egress-Sperre stellt sicher, dass Benutzer ohne Internet-Freigabe wirklich keine Informationen aus dem Internet beziehen oder Daten dorthin abfließen lassen können – auch nicht über Umwege. Leitprinzip: Die weiche Berechtigung (wer darf ins Internet) wird durch eine harte Grenze auf Betriebssystem-Ebene ergänzt, die unabhängig von der Formulierung eines Befehls wirkt.

1. Zwei Ebenen

Tool-Ebene (im Hauptprozess): Tools, die Informationen aus dem Internet holen (search_image, browser_control, browser_cdp, google_calendar/drive/gmail sowie jedes Tool mit requires_internet = True), werden im Dispatch (agent.py → _execute_tool) für nicht freigeschaltete Benutzer blockiert. Jira/Confluence sind intern (self-hosted) und daher bewusst nicht gesperrt.
Netzwerk-Ebene (harte Grenze): shell_execute solcher Benutzer läuft als separater, per Firewall netzwerkgesperrter OS-Benutzer. Das ist der Gegenstand dieser Beschreibung.

2. Warum eine zweite Ebene nötig ist

Die vorgelagerte Egress-Heuristik (_shell_hits_internet()) erkennt gängige Wege (curl, wget, ssh, git, urllib/requests/httpx, socket.connect …) und blockt sie mit klarer Meldung. Eine Regex kann ausgehenden Verkehr aber nicht lückenlos verhindern (z. B. rohe Sockets über eine Variable, eigene Protokolle). Diese Restlücke schließt die OS-Firewall.

3. Funktionsweise der Firewall

Umgesetzt in backend/egress_guard.py. Für Benutzer ohne Internet-Freigabe wird shell_execute via runuser als dedizierter OS-Benutzer jarvis_sandbox_noinet ausgeführt (Einstellung sandbox_shell_user_noinet). Für dessen UID gilt eine eigenständige nftables-Regel (table inet jarvis_egress, meta skuid-Match):

Ziel	Regel für den gesperrten Benutzer
Loopback (`127.0.0.0/8`, `::1`)	erlaubt
Internes LAN (`10/8`, `172.16/12`, `192.168/16`, `169.254/16`)	erlaubt – z. B. internes Jira/Confluence
DNS (Port 53) zu den konfigurierten Resolvern	erlaubt (Namensauflösung)
Alles Übrige (öffentliches Internet)	verworfen (DROP)

Die Tabelle ist eigenständig und beeinflusst bestehende Regeln (Docker/NAT) nicht. Ein systemd-Dienst (jarvis-egress.service) lädt sie nach jedem Reboot. UID und Resolver werden bei der Einrichtung automatisch erkannt – die Sperre funktioniert dadurch ohne manuelle Anpassung auf jedem Server.

4. Wer ist betroffen?

Nur Benutzer ohne Internet-Freigabe (Steuerung unter Sicherheit → Berechtigungen → Internet-Zugang via ad_internet_users/ad_internet_group). Lokale Administratoren und freigeschaltete Benutzer laufen über den normalen Sandbox-Benutzer mit Internet. Die beiden Ebenen (OS-Sandbox und Egress-Sperre) sind unabhängig schaltbar.

5. Einrichtung & Verifikation (in dieser Oberfläche)

Einrichten / Reparieren (POST /api/security/egress/setup): legt den OS-Benutzer an, schreibt die nftables-Regel + den Autostart-Dienst und setzt die Einstellung. Idempotent.
Status prüfen (Live-Test) (GET /api/security/egress?live=1): führt als gesperrter Benutzer einen echten Verbindungsversuch aus und zeigt, ob öffentliches Internet blockiert ist.
Deaktivieren (POST /api/security/egress/teardown): entfernt Regel + Autostart und leert die Einstellung. Die Tool-Ebenen-Sperre bleibt aktiv.

6. Grenzen & Restrisiko

DNS zu den internen Resolvern ist erlaubt (nötig für Namensauflösung); ein theoretisches DNS-Tunneling bleibt damit möglich. Für maximale Strenge lässt sich DNS für den gesperrten Benutzer ganz sperren.
Die Einstufung „intern" für Jira/Confluence gilt nur bei self-hostetem Betrieb. Zeigen sie auf eine Cloud (*.atlassian.net), wären sie „Internet" und müssten anders eingestuft werden.
In-Prozess-Tools (Bildersuche, Browser, Google) werden nicht über die Firewall, sondern über die Tool-Ebene gesperrt (Punkt 1) – die Firewall betrifft ausschließlich shell_execute.

Problem: Das Lernsystem schreibt pro Konversation eine eigene Wissensdatei (data/knowledge/learned/JJJJ-MM/conv_<zeit>.md). Mit der Zeit sammeln sich viele Dateien mit doppelten oder widersprüchlichen Fakten an – jede Konversation lernt isoliert, niemand gleicht gegen den Bestand ab.

1. Was die Verdichtung macht

Sammelt alle Wissensdateien aus abgeschlossenen Monaten – der laufende Monat bleibt unangetastet.
Ein LLM-Lauf führt sie mit dem bisherigen konsolidierten Bestand zusammen: Duplikate werden zu einem Eintrag verschmolzen, bei Widersprüchen gewinnt der Fakt mit dem neueren Datum (das Datum steht im Kopf jeder Datei). Bei echter Unsicherheit bleiben beide Varianten mit Datum erhalten.
Das Ergebnis wird thematisch gruppiert in wenige Dateien geschrieben (learned/konsolidiert/), z. B. Server & Infrastruktur, Kunden, Vorgehensweisen.
Bei jedem weiteren Lauf werden neue Fakten gegen den Bestand abgeglichen – das Wissen konvergiert, statt jedes Mal neu geschrieben zu werden.

2. Sicherheit

Die LLM-Ausgabe läuft nochmal durch denselben Sicherheits-Filter wie das Lernen selbst (rechte-, passwort- und secret-bezogene Zeilen werden verworfen) – die Verdichtung kann den Prompt-Injection-Schutz nicht aushebeln.
Anweisungen, die innerhalb gelernter Fakten stehen, behandelt der Verdichter als Daten, nicht als Befehle.

3. Reversibel statt destruktiv

Originaldateien werden nicht gelöscht, sondern nach data/backups/learned_archiv/JJJJ-MM/ verschoben – von dort können sie jederzeit zurückgeholt werden.
Das Archiv liegt bewusst außerhalb des Wissensordners, damit die Suche es nicht erneut indexiert.
Der Vektor-Index (FAISS) wird direkt mitgepflegt: Originale raus, konsolidierte Themen-Dateien sofort rein – kein kompletter Neuaufbau nötig.
Alles-oder-nichts: Schlägt der LLM-Aufruf fehl, wird keine einzige Datei angefasst.

4. Auslösung

Manuell: Button „Verdichten" in diesem Panel. Die Anzeige daneben zeigt, wie viele Dateien beim nächsten Lauf verarbeitet würden.
Automatisch: Haken „monatlich automatisch" – ein Hintergrund-Dienst prüft dann regelmäßig, ob abgeschlossene Monate vorliegen, und verdichtet sie selbstständig (typisch: einmal pro Monatswechsel).
Die feedback_*.md-Dateien sind ausgenommen – Feedback ist Verhaltensregel, kein Faktenwissen, und wird nicht „wegverdichtet".

Leitprinzip: Die Benutzeroberfläche (Chat, Support, Agent) und die Ausführungsebene mit Root-Rechten sind getrennte Prozesse. Das Backend läuft als unprivilegierter Dienst-Benutzer – selbst wenn ein Angreifer den Agenten per Prompt-Injection zu einem Befehl verleitet, läuft dieser nicht automatisch als root. Jede Root-Aktion ist eine benannte, geprüfte und protokollierte Operation.

1. Architektur

jarvis.service (User=jarvis): Web-UI, Chat, Agent, Skills. Bindet Port 443/80 über die Linux-Capability CAP_NET_BIND_SERVICE – ganz ohne root.
jarvis-broker.service (root): kleiner, separater Dienst (backend/broker/daemon.py). Übernimmt beim Start die root-pflichtigen Systemaufgaben (Firewall-Ports, VNC/x11vnc, Bildschirmsperre) und lauscht danach auf dem Unix-Socket /run/jarvis-broker.sock.
Der Socket gehört root:jarvis mit Rechten 0660 – nur der Dienst-Benutzer kann Anfragen stellen; Netzwerkzugriff auf den Broker gibt es nicht.

2. Benannte Operationen statt „root darf alles"

Der Broker kennt ausschließlich fest definierte Operationen mit harter Argument-Validierung (backend/broker/ops.py):

systemctl – nur Whitelist-Units (jarvis, whatsapp-bridge, lightdm, egress, broker) und erlaubte Aktionen.
unlock_screen, switch_session, vnc_restart – Desktop-/VNC-Steuerung.
chpasswd – Linux-Kennwort setzen (Erst-Login-Pflichtwechsel).
sandbox_exec – Shell-Befehle von Netzwerk-Benutzern als Sandbox-OS-User (runuser); nur Benutzer mit Prefix jarvis_sandbox, nie uid 0.
sandbox_*/egress_* – Ein-Klick-Einrichtung von OS-Sandbox und Egress-Firewall.
mount_share/umount_share – Wissens-Freigaben (SMB/NFS/WebDAV), ausschließlich unterhalb /mnt/.
certbot_obtain – Let's-Encrypt-Zertifikat inkl. Renewal-Hook.
shell_root – generischer Root-Shell-Befehl. Läuft niemals sofort, siehe Punkt 3.

3. Auditierbare Freigabeliste („wenn sie auftauchen")

Jede Operation wird beim ersten Auftauchen automatisch als Eintrag in der Freigabeliste registriert (/etc/jarvis/broker-policy.json, nur für root beschreibbar):

Systemoperationen (Punkt 2, außer shell_root): automatisch erlaubt, als „Systemoperation" markiert und jederzeit per Klick widerrufbar („Ablehnen").
shell_root:<befehl>: startet immer als „wartet auf Freigabe" (pending). Der Agent erhält eine klare Meldung, der Befehl wird nicht ausgeführt. Erst nach „Erlauben" durch einen lokalen Administrator ist genau dieser Befehl (exakte Signatur) ausführbar – „Ablehnen" sperrt ihn dauerhaft.
Jeder Eintrag zeigt: Beschreibung, Status, wer ihn angefordert hat, Anzahl/Zeitpunkt der Nutzung, wer entschieden hat. Löschen (×) setzt den Eintrag zurück – er erscheint beim nächsten Auftauchen erneut.

4. Ablauf eines Root-Befehls des Agenten

1. Agent ruft shell_execute mit z. B. apt-get install … auf.
2. shell.py::_needs_root() erkennt den Root-Bedarf (sudo, systemctl, apt, mount, useradd, …; reine Lesebefehle wie systemctl status laufen weiter unprivilegiert).
3. Der Befehl geht als shell_root an den Broker → Freigabeliste: pending (neuer Eintrag) / erlaubt (Ausführung mit Live-Streaming) / abgelehnt (Verweigerung).
4. Bei „pending" informiert der Agent den Benutzer, dass ein Administrator die Anfrage unter Sicherheit → Root-Freigaben freigeben muss.

5. Audit & Manipulationsschutz

Jede Anfrage – auch verweigerte – landet im Audit-Log /var/log/jarvis-broker-audit.jsonl (Zeitpunkt, Benutzer, Operation, Entscheidung, Exit-Code, Dauer). Einsehbar über „Audit-Log anzeigen".
Policy-Datei und Audit-Log gehören root (0600) – das unprivilegierte Backend kann sie nicht verändern oder löschen; Passwörter werden vor der Protokollierung maskiert.
Die Statusanzeige oben im Bereich zeigt immer den Betriebsmodus: 🟢 getrennter Betrieb, 🟠 Alt-Betrieb (Backend noch als root, Liste+Audit aktiv, keine Prozess-Trennung), 🔴 Broker nicht erreichbar.

6. Betriebsarten & Migration

Getrennt (empfohlen): Ein-Klick-Aktivierung unter Sicherheit → Root-Freigaben („Getrennten Betrieb aktivieren / reparieren") oder manuell mit bash deploy/security/setup_broker.sh (Eigentümerschaft, systemd-Units, Dienste, Verifikation). Beide Wege sind idempotent; die Dienste starten dabei neu.
Alt-Betrieb: Nicht migrierte Installationen funktionieren unverändert – der Broker-Client führt Operationen dann lokal aus, inklusive Freigabeliste und Audit. Rückweg per Klick („Deaktivieren (Alt-Betrieb)") oder bash deploy/security/teardown_broker.sh.
API (nur lokale Administratoren): GET /api/broker/status, POST /api/broker/setup, POST /api/broker/teardown, GET /api/broker/ops, POST /api/broker/ops/decide, POST /api/broker/ops/remove, GET /api/broker/audit.

7. Grenzen & Restrisiko

Freigabe-Entscheidungen kommen über die Web-UI zum Broker: Ein vollständig kompromittiertes Backend könnte sich theoretisch selbst Freigaben erteilen. Die Trennung schützt primär davor, dass Agent-/Prompt-Injection-Code direkt mit root läuft – und macht jede Root-Aktion sichtbar und nachvollziehbar.
Ein einmal erlaubter shell_root-Befehl darf erneut ausgeführt werden, bis er widerrufen wird. Empfehlung: eng gefasste Befehle freigeben, keine „Sammel-Freigaben" (z. B. kein bash -c … mit variablem Inhalt).
Die Root-Erkennung in der Shell ist eine Heuristik: Nicht erkannte Befehle laufen unprivilegiert und scheitern dann schlicht an fehlenden Rechten („Permission denied") – es findet keine stille Rechteausweitung statt.

LLM-Profile

▶

System-Einstellungen

▶

Sprachausgabe (TTS)

Stimme

Antwort-Timeout

Timeout für LLM-Anfragen (Sekunden)

Wie lange auf die Antwort des Modells gewartet wird, bevor abgebrochen wird. Langsame lokale Modelle brauchen höhere Werte (10–1800 s). Gilt global für alle Profile.

Maximale Antwortlänge

Obergrenze der Antwort (Token)

Dieser Wert begrenzt, wie viele Token ein Modell in einer einzelnen Antwort erzeugen darf. Er ist vor allem bei Reasoning-Modellen wichtig: ohne Obergrenze kann ein Modell einen sehr langen Gedankengang produzieren und dabei das Antwort-Timeout reißen, sodass die Anfrage komplett verloren geht. Ist der Wert zu klein gewählt, wird die Antwort mitten im Satz abgeschnitten – ein typisches Anzeichen sind Antworten, die ohne Punkt enden. Bei hoher Denktiefe zählen Denk- und Antworttoken gemeinsam gegen dieses Limit, hier sind 16000 oder mehr sinnvoll. Erlaubt sind 256 bis 131072 Token; der Wert gilt global für alle Profile und wirkt bei OpenAI-kompatiblen Anbietern sowie bei Anthropic.

Vorhaltezeit erzeugter Dokumente

Dateien aufbewahren (Tage)

dauerhaft

Erzeugte Dateien (Präsentationen, Tabellen, PDFs, Bilder) liegen auf dem Server und sind über den Download-Link im Chat erreichbar. Dieser Link verfällt nicht von selbst – das Löschen der Datei ist der einzige Widerruf. Nach Ablauf der Frist werden die Dateien beim täglichen Lauf entfernt; der Chat-Verlauf bleibt erhalten, nur der Download funktioniert dann nicht mehr. Erlaubt sind 15 bis 90 Tage. Mit „dauerhaft“ wird nie automatisch gelöscht – das bedeutet, dass auch Dateien mit vertraulichem Inhalt unbegrenzt abrufbar bleiben.

Kontext-Komprimierung

Schwellwert (Gesprächseinträge)

Ab wie vielen Gesprächseinträgen der Verlauf eines Chats automatisch zusammengefasst wird, damit er in das Kontextfenster des Modells passt. Ein Eintrag ist eine Frage, eine Antwort oder ein Werkzeug-Ergebnis. Kleinere Werte sparen Token und Kosten, verlieren aber früher Details aus dem Gesprächsanfang; größere Werte behalten mehr, machen jede Anfrage aber teurer und langsamer. Erlaubt sind 4 bis 200 Einträge, Standard ist 30. Der Wert gilt global für alle Benutzer und alle Sitzungen; den aktuellen Füllstand einer Sitzung zeigt die Kontext-Anzeige im Chat.

Automatische Sicherheitsupdates (System)

Status wird geladen…

Spielt Debian-Sicherheitspatches automatisch ein (unattended-upgrades). Bewusst eng gefasst: nur die Sicherheits-Quelle – keine allgemeinen Versionssprünge unter dem laufenden Dienst, kein automatischer Neustart und kein automatisches Aufräumen von Paketen (Letzteres würde Abhängigkeiten des Agenten entfernen, etwa cmake/boost für die Gesichtserkennung, ffmpeg für die Sprachausgabe oder LibreOffice-Teile). Die tägliche Aktualisierung des Paketindex bleibt beim Ausschalten aktiv – ein veralteter Index lässt Paketinstallationen mit „404 Not Found“ scheitern.

Agent API Key

▶

HTTPS / SSL-Zertifikat

▶

Profilname

LLM Anbieter

API Base URL

KI-Modell

Temperature (Kreativität)

Die Temperature steuert, wie stark das Modell vom wahrscheinlichsten nächsten Wort abweicht: niedrige Werte liefern sachliche und gut reproduzierbare Antworten, hohe Werte mehr Abwechslung und Kreativität. Der Standard ist „auto“ – der Parameter wird dann gar nicht mitgesendet und der Anbieter entscheidet selbst; das ist nötig für aktuelle Claude-Modelle, die Temperature-Angaben mit einem Fehler ablehnen. Achtung: der Anbieter-Standard liegt bei vielen OpenAI-kompatiblen Servern und bei Gemini deutlich über 0.2, und ab etwa 0.7 zerfallen die JSON-Argumente von Werkzeugaufrufen zunehmend. Wer verlässliche Tool-Aufrufe braucht, trägt deshalb eine feste Zahl ein – 0.2 entspricht dem Verhalten vor Juli 2026. Erlaubt sind Werte von 0.0 bis 2.0; für reine Text- und Schreibaufgaben ohne Tools sind 0.7 bis 1.0 ein guter Ausgangspunkt.

Prompt-basiertes Tool-Calling Für Modelle ohne native Function-Calling-API (z.B. Liquid LFM2, Phi-3). Tools werden im System-Prompt beschrieben, Aufrufe per <tool_call>-Tag geparst.

Zugangsart

API Key Session (Pro-Abo)

API Key

Session Key

Aus dem Browser-Cookie sessionKey auf claude.ai kopieren.
Chrome: F12 → Application → Cookies → sessionKey

🚫 Konto gesperrt

Protokoll der verdächtigen Aktivitäten

Sprachausgabe (TTS)

Antwort-Timeout

Maximale Antwortlänge

Vorhaltezeit erzeugter Dokumente

Kontext-Komprimierung

Automatische Sicherheitsupdates (System)

WhatsApp Status

QR-Code scannen

Erkannt:

Log

Training abgeschlossen!

🔒 Kennwort ändern

🚫 Konto gesperrt

Protokoll der verdächtigen Aktivitäten

🔒 Sichere Verbindung einrichten

SSL-Zertifikat installieren

🔌 Support-API – REST-Zugriffe

Authentifizierung

Endpunkte

Beispiel 1 – Suche mit KI-Zusammenfassung

Request-Felder /api/support/query

Antwort-Felder /api/support/query

Beispiel 2 – Einzelnes Ticket zusammenfassen

Request-Felder /api/support/summarize

Fehler & Status-Codes

🔎 CRM-Lookups (Jira)

Beispiel 3 – CRM-Kundennummer zu einer Telefonnummer

Beispiel 4 – Alle Tickets zu einer CRM-Kundennummer

Beispiel 5 – Passende Tickets eines CRM-Kunden zu Schlagworten

Authentication

Endpoints

Example 1 – Search with AI summary

Request fields /api/support/query

Response fields /api/support/query

Example 2 – Summarize a single ticket

Request fields /api/support/summarize

Errors & status codes

🔎 CRM lookups (Jira)

Example 3 – CRM customer number for a phone number

Example 4 – All tickets for a CRM customer number

Example 5 – Matching tickets of a CRM customer for keywords

🛡️ Sicherheitsschicht – technische Funktionsanalyse

1. Rollenmodell

2. Dateisystem-Confinement (filesystem-Tool)

3. Shell-Härtung (shell_execute)

4. OS-Sandbox (harte Grenze)

5. Keine Rechteausweitung über Sub-Agenten

6. Angriffserkennung (Guard)

7. Verstoß-Protokoll & automatische Sperre

8. Schutz vor Kontext-Vergiftung

9. Konfiguration

10. Trennung UI-/Ausführungsebene (Root-Broker)

11. Grenzen & Restrisiko

🧱 Harte Egress-Sperre – technische Funktionsanalyse

1. Zwei Ebenen

2. Warum eine zweite Ebene nötig ist

3. Funktionsweise der Firewall

4. Wer ist betroffen?

5. Einrichtung & Verifikation (in dieser Oberfläche)

6. Grenzen & Restrisiko

🗜️ Wissens-Verdichtung – Funktionsweise

1. Was die Verdichtung macht

2. Sicherheit

3. Reversibel statt destruktiv

4. Auslösung

🔐 Root-Freigaben (Root-Broker) – technische Funktionsanalyse

1. Architektur

2. Benannte Operationen statt „root darf alles"

3. Auditierbare Freigabeliste („wenn sie auftauchen")

4. Ablauf eines Root-Befehls des Agenten

5. Audit & Manipulationsschutz

6. Betriebsarten & Migration

7. Grenzen & Restrisiko

Einstellungen

LLM-Profile

System-Einstellungen

Sprachausgabe (TTS)

Antwort-Timeout

Maximale Antwortlänge

Vorhaltezeit erzeugter Dokumente

Kontext-Komprimierung

Automatische Sicherheitsupdates (System)

Agent API Key

HTTPS / SSL-Zertifikat

Status & Verbindung

WhatsApp Status

QR-Code scannen

Nachrichten-Verarbeitung

Logs & Debug

Statistiken

Request-Felder `/api/support/query`

Antwort-Felder `/api/support/query`

Request-Felder `/api/support/summarize`

Request fields `/api/support/query`

Response fields `/api/support/query`

Request fields `/api/support/summarize`

2. Dateisystem-Confinement (`filesystem`-Tool)

3. Shell-Härtung (`shell_execute`)