MagicMirror Projesi: araç köprüsü ve kontrollü modül komutları

MagicMirror Projesi’nde asistanın modüllerle iletişimi için belirli araç ve bildirimlere dayanan bir köprü geliştirdik. Müzik kontrolü, hafıza ve bilgi sorgusu gibi işlemler bu köprüde ayrılıyor. Bu yazıda özel hesaplar, yapılandırma sırları ve kişisel araç sonuçları yok; kaynakta bulunan sınırların çalışma biçimi ve incelenmesi gereken noktalar anlatılıyor.

Projede yaptığımız düzenleme

Müzik komutlarını oynat, duraklat, sonraki parça ve ses düzeyi gibi belirli modül bildirimlerine eşleyen yollar ekledik. Sesli komut ayrıştırıcısı ile modül bildirimi arasındaki bu eşleme, serbest bir metni doğrudan kabuk komutuna dönüştürmekten farklıdır. Bununla birlikte bildirimlerin sınırlı olması bütün araçların güvenlik denetiminden geçtiğini göstermez; parametre ve oturum kapsamı ayrıca incelenmelidir.

Çalışan hava, haber ve müzik modüllerinden gelen durum bildirimlerini asistanın kullanabileceği sınırlı anlık görüntülere dönüştürdük. Kaynakta görülen uygulama adımlarıyla aşağıdaki güvenlik kabul önerilerini ayırıyoruz. Örneğin tekrar eden durum değişikliğinin etkisizleştirilmesi ve hassas onayın tek kullanımlı doğrulanması burada uygulanmış bir sonuç olarak iddia edilmiyor; yürütücü sınırında ayrıca kontrol edilecek konular olarak açıklanıyor.

Araç adını kabul etmek yeterli değildir

Bir aracı izin listesine eklemek, o aracın bütün parametrelerine izin vermek anlamına gelmemeli. Ses düzeyi değiştiren örnekte beklenen veri tipi, kabul edilen aralık, hedef oynatıcı ve işlemin hangi oturumda yapılabileceği ayrıca belirlenir. Beklenmeyen alanı sessizce geçirmek yerine reddetmek, genişleyen bir arayüzün fark edilmesini kolaylaştırır. Serbest metni kabuk komutuna veya sınırsız modül bildirimine dönüştürmeyin.

MagicMirror belgeleri modüllerin bildirim gönderebildiğini açıklar. Bu iletişim özelliği kendi başına hassas işlem yetkilendirmesi sağlamaz. Köprü hangi bildirimin hangi araçtan üretilebileceğini ve hangi hedefe gideceğini sınırlandırmalıdır. İç ağda bulunmak veya aynı uygulama sürecinde çalışmak bütün girdileri güvenilir yapmaz. Tarayıcı tarafına eklenen bir düğme de sunucu tarafındaki kontrolün yerine geçmez.

1. Önerilen aracı al
2. Araç ve parametreyi doğrula
3. Oturum yetkisini denetle
4. Sınırlı işlemi yürüt
5. Sonucu ve tekrar riskini kaydet

Yetkiyi modelin cevabından çıkarmayın

OWASP ajan güvenliği rehberi yetkilendirmenin yürütme bileşeninde uygulanmasını önerir. Modelin işlemin güvenli olduğunu söylemesi, kullanıcının o hedefte işlem yapmaya yetkili olduğunu göstermez. Oturum sahibi, araç kapsamı ve hedef kaynağın ilişkisi uygulamada doğrulanmalıdır. Kalıcı not okuma ile ortak ekrandaki saati gösterme aynı yetki sınıfında ele alınmamalıdır. Hassas işlemler için gereken kullanıcı onayı tam hedef ve parametrelere bağlı olmalıdır.

Asistanın okuduğu haber, belge veya araç sonucu içinde komut gibi görünen metin bulunabilir. Bu içerik uygulama tarafından yeni kullanıcı talimatı kabul edilmemelidir. Prompt injection savunmasında yalnız yasak kelime listesine güvenmek yetersizdir. Köprünün bağımsız yetki ve parametre denetimleri, modelin hatalı önerisi durumunda da çalışmalıdır. Kaynak metne eklenen bir uyarı güvenlik sınırı oluşturmaz.

Tekrar, zaman aşımı ve sonuç doğrulaması

Bir araç çalıştıktan sonra yanıt kaybolursa asistan aynı isteği tekrar önerebilir. Okuma isteğinin tekrarıyla yeni hatırlatıcı oluşturmanın tekrarı aynı sonucu üretmez. Durum değiştiren araçlarda işlem kimliği ve yinelenen istek davranışı tasarlanmalıdır. Aynı kimliğin farklı parametreyle kullanılması ayrıca reddedilecek bir durumdur. Tekrar korumasının süresi ve kayıt saklaması da gereksiz kişisel veri biriktirmeden belirlenmelidir.

Araç sonucu açık bir başarı veya hata biçimi taşısın. Komutun gönderilmiş olması hedef uygulamanın işlemi tamamladığını kanıtlamaz. Arayüz, gerçek sonuç gelmeden kesin başarı mesajı üretmemelidir. Zaman aşımında belirsiz sonucu ayrı göstermek, körlemesine tekrar çalıştırmaktan daha anlaşılırdır. Günlüklerde tam özel parametreleri tutmak yerine araç türü, anonim işlem kimliği ve karar nedeni kaydedilebilir.

Kontrollü kabul ve geri dönüş

Kabul testinde gerçek hesaplara dokunmayan sahte araçlar kullanın. Bilinmeyen ad, yanlış veri tipi, kapsam dışı hedef, süresi dolmuş oturum ve aynı isteğin tekrarı için ayrı satırlar açın. İzin verilen örneğin çalışması kadar reddedilen örneğin hiç yürütülmediğini göstermek de önemlidir. Arayüzde hata görünmesi, arka planda yan etki oluşmadığının tek kanıtı değildir; sahte yürütücünün kayıtlarıyla karşılaştırın.

Geri dönüşte köprünün önceki onaylı sürümünü ve onun araç sözleşmesini birlikte geri alın. Yeni alanları eski yürütücüye kontrolsüz taşımayın. Eski oturumları ve bekleyen çağrıları yeniden değerlendirin; bir sürüm geri dönüşü tüketilmiş onayları tekrar kullanılabilir yapmamalıdır. Bu plan bir güvenlik sertifikası değildir. Tanımlı araç sınırlarının, açık testlerle ve gerçek sonuç kanıtıyla incelenmesine yardımcı olur.

Serinin bütün çalışmaları: MagicMirror Projesi.

Nasıl yapılır: ayrıntılı uygulama

Ortam ve ön koşullar: Araç köprüsü eylem doğrulama örneği — Kimlik/yetki denetimi ve mevcut modül sözleşmesi ayrıca tanımlanmalı.

1. Bildirim sözleşmesini ve yetki sınırını yazın
2. Çalışan minimal modül dosyasını oluşturun
3. Config ve sözdizimini bağlayın
4. İstek/onay ve ret testini yapın
5. Tekillik ve geri dönüşü doğrulayın

1. Bildirim sözleşmesini ve yetki sınırını yazın

MagicMirror içi notification köprüsü internete açık güvenilir authentication gateway değildir. Kaynak kimlik, izinli action/target, request ID, süre aşımı ve modül onayı ayrı tanımlanır; serbest metin shell’e verilmez.

2. Çalışan minimal modül dosyasını oluşturun

Aşağıdaki örneği yeni modules/MMM-BatuhanyaziciBridge/MMM-BatuhanyaziciBridge.js dosyasına kaydedin. Bu öğretici modül yalnız status kabul eder; projenin özel köprüsü veya müzik komutlarının tamamı olduğu iddia edilmez.

Module.register("MMM-BatuhanyaziciBridge", {
  notificationReceived(notification, payload, sender) {
    if (notification !== "BATUHANYAZICI_REQUEST" || !sender) return;
    if (!payload || payload.action !== "status" ||
        typeof payload.id !== "string" || payload.id.length > 80) {
      return;
    }
    this.sendNotification("BATUHANYAZICI_RESULT", {
      id: payload.id, ok: true, state: "ready"
    });
  },
  getDom() {
    const el = document.createElement("div");
    el.textContent = "batuhanyazici.com · status köprüsü";
    return el;
  }
});

3. Config ve sözdizimini bağlayın

config/config.js modules dizisine {module:"MMM-BatuhanyaziciBridge", position:"bottom_left"} nesnesini ekleyin; config dosyasının tamamını ezmeyin. Sözdizimi kontrolü gerçek module boot/izin testinin yerine geçmez.

node --check modules/MMM-BatuhanyaziciBridge/MMM-BatuhanyaziciBridge.js
node --check config/config.js

4. İstek/onay ve ret testini yapın

Aynı MagicMirror test modülünden sendNotification("BATUHANYAZICI_REQUEST", {id:"batuhanyazici-test-1",action:"status"}) gönderin; result aynı ID ile dönmeli. İzin dışı action ve geçersiz payload sonuç üretmemeli. Gerçek server köprüsünde ret açık hata ve timeout ile bildirilir; sessiz örnek handler haricî API olarak yayımlanmaz.

5. Tekillik ve geri dönüşü doğrulayın

Gerçek modüle komut eklenecekse her action’ın payload şeması/authorization ve acknowledgment’u daraltılır. Aynı request ID tekrarında yan etki tekrarlanmamalı; örnek status salt okumadır. Yeni module/config nesnesini önceki sürüme geri alın; shell execute yetkisi eklemeyin.

Beklenen sonuç: İzin dışı eylem reddedilir; izinli eylemin uygulanması ve onayı ayrı izlenir.

Sonuç farklıysa: Allowlist, kimlik doğrulama veya yetkilendirme yerine geçmez.

Geri dönüş: Önceki onaylı eylem listesini ve uyumlu modül sürümünü birlikte geri alın.