LLM Healing Security Model / LLM Healing Güvenlik Modeli

English

Scope and trust boundary

LLM healing is opt-in. It runs only when heuristic resolution is not confident and at least one configured provider is available. The resolver sends each available provider the same bounded shortlist in parallel; retries send the same prompt to that provider again. Configuring several providers therefore discloses the prompt to several separate data processors—it is not one shared private computation.

Treat every value captured from a DOM or desktop accessibility tree as untrusted input. Element text can contain personal data, secrets, customer content, or deliberate prompt-injection instructions. TestIntent is application-authored but may carry the same kinds of sensitive data. Neither source becomes trusted merely because it is serialized into a structured prompt.

The deterministic heuristic path does not call an LLM provider. To guarantee that UI content does not leave the process through this feature, do not configure LLM providers and do not pass provider instances to ResolveAsync.

What reaches a provider

The provider does not receive a screenshot or the full DOM/UI tree. The prompt contains:

• the target platform;
• the last known element’s ControlType, Name, ClassName, bounding rectangle, parent control type, sibling index/count, and TestIntent;
• up to MaxCandidatesForLlm candidates (20 by default), including each candidate’s synthetic CandidateId, AutomationId, ControlType, Name, total heuristic score, and component scores; and
• instructions requesting a candidate ID, confidence value, and one-sentence reasoning.

The stale target AutomationId is deliberately omitted to reduce semantic anchoring. Candidate AutomationId values are still included. TestIntent appears in both the serialized target snapshot and a human-readable intent block when it is non-empty.

By default, a built-in redactor masks common sensitive patterns (see “PII, secrets, and operator controls” below) in this text before transmission. There is no classifier, allow-list, or secret scanner beyond that pattern-based redaction, and it can be disabled per caller. Bounding the shortlist limits volume and cost; neither the redaction pass nor the bounding makes the remaining content anonymous or safe to disclose.

Named risks, current mitigations, and residual risk

The candidate-ID protocol, prompt boundary tags, and security directives form an instruction/data separation and output-integrity boundary. Untrusted DOM text is enclosed within <target_element>, <candidate_shortlist>, and <test_intent> XML tags, and guarded with explicit security directives prohibiting the LLM from executing or following instructions embedded inside element names or attributes. Furthermore, the Hallucination Guard strictly enforces that returned candidate IDs must belong to the pre-scored shortlist, and the multi-model consensus quorum requires independent agreement across multiple provider architectures.

This boundary reduces the risk that embedded UI text hijacks locator selection, but it is not a disclosure control: every field sent in <target_element> and <candidate_shortlist> is still readable by each configured provider. Do not use LLM healing on screens whose captured fields cannot be disclosed to every configured provider.

Independent agreement also remains a locator-selection quorum—not a security review, fact check, or correctness guarantee. The measured limitations are documented in the benchmark guide.

PII, secrets, and operator controls

By default, the library applies a built-in sensitive data redaction pass (SensitiveDataSanitizer.Redact) across all DOM/UI-tree and test intent text before constructing LLM prompts (LlmHealingPrompt.Build and LlmIntentPlanningPrompt.Build). Common patterns such as email addresses, credit/debit card numbers, bearer tokens, prefixed API keys/JWTs (including Stripe sk_live_/pk_test_/rk_live_ keys and Google/GCP AIza keys), key-value secrets (e.g. password: ..., api_key = ...), and US Social Security Numbers are automatically masked with standard replacement tokens ([REDACTED_EMAIL], [REDACTED_CARD], [REDACTED_SECRET], [REDACTED_SSN]).

Redaction is opt-out: operators who require raw, unmasked text can pass SensitiveDataSanitizer.PassThrough (or text => text) to HttpLlmHealingProvider.TextSanitizer, LlmHealingPrompt.Build, or LlmIntentPlanner.TextSanitizer. Custom sanitizers can also be supplied via the same hook (Func<string, string>).

[!CAUTION] Pattern-based sanitization is a defence-in-depth layer, not a substitute for data isolation or access controls. It cannot detect proprietary, unstructured, or domain-specific confidential information. Do not send production or highly sensitive screens to third-party LLM providers.

Suitable controls include:

1. Rely on default built-in redaction, or configure a custom TextSanitizer delegate (e.g. domain-specific proprietary ID masking) on provider instances or intent planners.
2. Use SensitiveDataSanitizer.PassThrough only in isolated, synthetic test environments where masking is undesirable.
3. Use heuristic-only resolution for authenticated, financial, health, production-data, or other sensitive screens.
4. Capture synthetic or scrubbed test data, and keep secrets out of element names, accessibility labels, IDs, and TestIntent.
5. Configure only providers and regions approved by the application’s data owner. A multi-provider quorum requires disclosure to multiple providers.
6. If local processing is required, use an Ollama daemon on a controlled host and verify OLLAMA_HOST. Ollama Cloud is remote, and a non-local OLLAMA_HOST is remote even though the provider class is named OllamaHealingProvider.
7. Treat custom OpenAI-compatible endpoints as separate processors. Their transport, logging, retention, subprocessors, and training policies are entirely operator-owned.

Provider telemetry and retention

Automation Sandbox cannot enforce provider-side logging, training, regional processing, abuse monitoring, or deletion. These policies can differ by account tier, endpoint, region, feature, and contract, and they can change independently of this repository. Review the terms that apply to the exact account and endpoint before enabling it:

For example, the linked OpenAI documentation distinguishes abuse-monitoring retention from application-state storage and describes account eligibility for modified or zero data retention. Do not generalize one provider’s or one endpoint’s policy to another. No retention assumption for Kimi/Moonshot, Ollama Cloud, or custom endpoints is encoded in this library either.

Local telemetry is sensitive too

When healing reports are enabled, JSON and rendered HTML can persist captured snapshots, candidate names and automation IDs, model reasoning, provider names and attempt counts, and provider error details. A response parse failure appends up to 4096 characters of the raw HTTP response body to the provider error. A model may echo prompt content there.

Healing reports are not encrypted or automatically expired by the library. Store them as sensitive test artifacts, restrict access, define a deletion period, and review them before attaching them to issues or CI artifacts. See the healing report guide.

Availability and retry design is tracked separately in issues #109, #110, #127, and #129. Those controls limit operational failure; they do not change this confidentiality model.

Türkçe

Kapsam ve güven sınırı

LLM healing isteğe bağlıdır. Yalnızca sezgisel çözüm yeterince güvenli olmadığında ve en az bir yapılandırılmış sağlayıcı bulunduğunda çalışır. Resolver aynı sınırlı aday listesini kullanılabilir tüm sağlayıcılara paralel gönderir; retry aynı prompt’u o sağlayıcıya yeniden gönderir. Bu nedenle birden fazla sağlayıcı yapılandırmak, prompt’u tek bir ortak özel hesaplamaya değil birden fazla ayrı veri işleyene açıklamak demektir.

DOM veya masaüstü erişilebilirlik ağacından yakalanan her değeri güvenilmeyen girdi olarak kabul edin. Eleman metni kişisel veri, sır, müşteri içeriği veya kasıtlı prompt injection talimatı içerebilir. TestIntent uygulama tarafından yazılır fakat aynı tür hassas verileri taşıyabilir. Bu kaynaklar yapılandırılmış bir prompt içine serialize edilince güvenilir hâle gelmez.

Deterministik sezgisel yol hiçbir LLM sağlayıcısını çağırmaz. UI içeriğinin bu özellik üzerinden süreç dışına çıkmamasını garanti etmek için LLM sağlayıcısı yapılandırmayın ve ResolveAsync metoduna sağlayıcı örneği vermeyin.

Sağlayıcıya hangi veriler gider

Sağlayıcı ekran görüntüsünü veya DOM/UI ağacının tamamını almaz. Prompt şunları içerir:

• hedef platform;
• son bilinen elemanın ControlType, Name, ClassName, bounding rectangle, üst eleman türü, kardeş indeksi/sayısı ve TestIntent değerleri;
• en fazla MaxCandidatesForLlm aday (varsayılan 20); her adayın sentetik CandidateId, AutomationId, ControlType, Name, toplam sezgisel skor ve bileşen skorları; ve
• aday kimliği, confidence değeri ve tek cümlelik reasoning isteyen talimatlar.

Eski hedef AutomationId, semantik çapalamayı azaltmak için bilerek çıkarılır. Adayların AutomationId değerleri ise gönderilir. Boş değilse TestIntent hem serialize edilmiş hedef snapshot’ında hem de okunabilir intent bloğunda yer alır.

Varsayılan olarak yerleşik bir redactor, gönderim öncesinde bu metin içindeki yaygın hassas verileri maskeler (aşağıdaki “PII, sırlar ve operatör kontrolleri” bölümüne bakın). Bu desen tabanlı maskeleme dışında bir sınıflandırıcı, allow-list veya secret scanner yoktur ve çağıran taraf bunu devre dışı bırakabilir. Aday listesini sınırlamak hacmi ve maliyeti sınırlar; ne maskeleme ne de bu sınırlama kalan içeriği anonim veya açıklanması güvenli hâle getirir.

Adlandırılmış riskler, mevcut önlemler ve kalan risk

Aday-kimliği protokolü, prompt sınır etiketleri ve güvenlik direktifleri bir talimat/veri ayrımı ve çıktı bütünlüğü sınırı oluşturur. Güvenilmeyen DOM metni <target_element>, <candidate_shortlist> ve <test_intent> XML etiketleri içine alınır ve LLM’in eleman adları veya öznitelikleri içine gömülmüş talimatları yürütmesini ya da takip etmesini engelleyen açık güvenlik direktifleriyle korunur. Ayrıca Hallucination Guard, döndürülen aday kimliklerinin önceden skorlanmış aday listesine ait olmasını zorunlu kılar ve çoklu model uzlaşma quorum’u birden fazla sağlayıcı mimarisinde bağımsız anlaşma gerektirir.

Bu sınır, gömülü UI metninin locator seçimini ele geçirme riskini azaltır; ancak bir ifşa kontrolü değildir: <target_element> ve <candidate_shortlist> içinde gönderilen her alan yapılandırılmış her sağlayıcı tarafından hâlâ okunabilir. Yakalanan alanları tüm yapılandırılmış sağlayıcılara açıklayamayacağınız ekranlarda LLM healing kullanmayın.

Bağımsız uzlaşma da yalnızca locator seçimi quorum’udur; güvenlik incelemesi, doğrulama veya doğruluk garantisi değildir. Ölçülmüş sınırlar benchmark rehberinde belgelenmiştir.

PII, sırlar ve operatör kontrolleri

Varsayılan olarak kütüphane, LLM prompt’ları (LlmHealingPrompt.Build ve LlmIntentPlanningPrompt.Build) oluşturulmadan önce tüm DOM/UI ağacı ve test intent metinleri üzerinde yerleşik bir hassas veri maskeleme adımı (SensitiveDataSanitizer.Redact) uygular. E-posta adresleri, kredi/banka kartı numaraları, bearer token’ları, ön ekli API anahtarları/JWT’ler (Stripe sk_live_/pk_test_/rk_live_ ve Google/GCP AIza anahtarları dahil), anahtar-değer sırları (ör. password: ..., api_key = ...) ve ABD Sosyal Güvenlik Numaraları standart maskeleme belirteçleriyle ([REDACTED_EMAIL], [REDACTED_CARD], [REDACTED_SECRET], [REDACTED_SSN]) otomatik olarak maskelenir.

Maskeleme opt-out (varsayılan olarak açık) olarak çalışır: ham metnin filtrelenmeden iletilmesini isteyen operatörler HttpLlmHealingProvider.TextSanitizer, LlmHealingPrompt.Build veya LlmIntentPlanner.TextSanitizer üzerine SensitiveDataSanitizer.PassThrough (veya text => text) geçebilir. Özel temizleyiciler de aynı kanca (Func<string, string>) üzerinden sağlanabilir.

[!CAUTION] Desen tabanlı maskeleme bir derinlemesine savunma (defence-in-depth) katmanıdır; veri yalıtımı veya erişim kontrollerinin yerine geçmez. Yapılandırılmamış, tescilli veya sektöre özel gizli bilgileri tespit edemez. Üretim ortamlarını veya yüksek derecede hassas ekranları harici LLM sağlayıcılarına göndermeyin.

Uygun kontroller şunları içerir:

1. Varsayılan yerleşik maskelemeyi kullanın veya sağlayıcılar / intent planner üzerinde özel bir TextSanitizer delegesi yapılandırın.
2. SensitiveDataSanitizer.PassThrough delegesini yalnızca maskelemenin istenmediği izole sentetik test ortamlarında kullanın.
3. Kimlik doğrulamalı, finansal, sağlık, production-data veya başka hassas ekranlarda yalnızca sezgisel çözümü kullanın.
4. Sentetik ya da temizlenmiş test verisi yakalayın; eleman adları, accessibility label, kimlik ve TestIntent içine sır koymayın.
5. Yalnızca veri sahibinin onayladığı sağlayıcıları ve bölgeleri yapılandırın. Çoklu sağlayıcı quorum’u verinin birden fazla sağlayıcıya açıklanmasını gerektirir.
6. Yerel işleme gerekiyorsa denetlenen bir host’taki Ollama daemon’unu kullanın ve OLLAMA_HOST değerini doğrulayın. Ollama Cloud uzaktır; yerel olmayan bir OLLAMA_HOST da sınıf adı OllamaHealingProvider olsa bile uzaktır.
7. Özel OpenAI-uyumlu endpoint’leri ayrı veri işleyenler olarak kabul edin. Transport, loglama, retention, alt işleyen ve eğitim politikaları tamamen operatör sorumluluğundadır.

Sağlayıcı telemetrisi ve retention

Automation Sandbox sağlayıcı tarafındaki loglama, eğitim, bölgesel işleme, abuse monitoring veya silmeyi zorlayamaz. Politikalar hesap paketi, endpoint, bölge, özellik ve sözleşmeye göre farklılaşabilir ve bu depodan bağımsız değişebilir. Bir sağlayıcıyı etkinleştirmeden önce tam olarak kullandığınız hesap ve endpoint için geçerli koşulları inceleyin:

Örneğin bağlantısı verilen OpenAI dokümanı abuse-monitoring retention ile uygulama-durumu saklamasını ayırır ve değiştirilmiş veya sıfır veri saklamaya hesap uygunluğunu açıklar. Bir sağlayıcının veya endpoint’in politikasını diğerine genellemeyin. Kimi/Moonshot, Ollama Cloud ve özel endpoint’ler için bu kütüphanede hiçbir retention varsayımı kodlanmaz.

Yerel telemetri de hassastır

Healing raporları etkinse JSON ve oluşturulan HTML; yakalanmış snapshot’ları, aday adları ve automation ID’leri, model reasoning’ini, sağlayıcı adları ve deneme sayılarını, ayrıca sağlayıcı hata ayrıntılarını kalıcılaştırabilir. Yanıt parse edilemezse ham HTTP response body’nin en fazla 4096 karakteri sağlayıcı hatasına eklenir. Model burada prompt içeriğini tekrarlayabilir.

Healing raporları kütüphane tarafından şifrelenmez veya otomatik süresi doldurulmaz. Bunları hassas test artifact’ları olarak saklayın, erişimi kısıtlayın, silme süresi belirleyin ve issue/CI artifact’ına eklemeden önce inceleyin. Healing report rehberine bakın.

Kullanılabilirlik ve retry tasarımı ayrıca #109, #110, #127 ve #129 issue’larında izlenir. Bu kontroller operasyonel arızayı sınırlar; gizlilik modelini değiştirmez.