SealBox'ı adım adım öğren

1. 5 dakikada başla

SealBox bir komut satırı aracı. Kurduktan sonra proje klasöründe birkaç komut çalıştırman yeterli.

Kur

$ pip install sealbox        # ya da: pipx install sealbox
$ sealbox -V                 # sürümü göster: sealbox 0.3.0

Projeni kontrol et

init hiçbir dosyayı değiştirmez. Projeye bakar ve sıradaki adımları sırayla söyler:

$ cd projem
$ sealbox init
sealbox 0.3.0 · proje: C:\projem

  ✓ Kasa: henüz yok
  · Ekip kurulmamış (tek kişi)  → sealbox team init --github <ad>
  ⚠ 3 dosyada açık sır var       → sealbox seal

Sıradaki adımlar:
  1) sealbox seal
  2) sealbox recovery setup

Mühürle, yedekle, çalıştır

$ sealbox seal                     # sırları kasaya taşı
$ sealbox recovery setup           # kurtarma kodu (bir kez)
$ sealbox exec -- python app.py    # programı sırlarla çalıştır
$ git add .sealbox
$ git commit -m "kasa"

2. Temel kavramlar

SealBox'ı anlamak için beş kavram yeter. Hepsini evden bir benzetmeyle anlatıyoruz.

Ne nereye gider?

3. İlk projeni mühürle

Önce sadece bak

--check hiçbir şeye dokunmaz. Açık sır varsa çıkış kodu 1 döner, böylece CI'da da kullanılabilir.

$ sealbox seal --check
.env → .env.sealed: 1 değer kasaya taşındı (DB_PASSWORD)
3 dosya tarandı (0.0 sn).
Diskte karalanmamış sır var. 'sealbox seal' çalıştırın.

Mühürle

$ sealbox seal                     # tüm proje
$ sealbox seal src/config.py       # yalnızca bir dosya

Dosyalarına ne olur?

Her dil, sırrı kendi standart yoluyla okur. Kodun mantığı değişmez:

# önce
KEY = "sk_live_51N…"
# sonra
KEY = os.environ["KEY"]

// önce
const key = "sk_live_51N…"
// sonra
const key = process.env.KEY

// önce
String key = "sk_live_51N…";
// sonra
String key = System.getenv("KEY");

Aynı dosyayı geri alıp tekrar mühürlemek kasada kopya oluşturmaz, çünkü aynı değer her zaman aynı kayda bağlanır.

4. Programı kasayla çalıştır

$ sealbox exec -- python app.py        # Python
$ sealbox exec -- npm start            # Node.js
$ sealbox exec -- java Main.java       # Java
$ sealbox exec -- mvn spring-boot:run  # Maven / Gradle

• -- işaretinden sonraki her şey senin normal komutun.
• Önce onay penceresi açılır. Onayı atlatan bir bayrak ya da ortam değişkeni bilerek yok.
• Programın çıktısında bilinen bir sır geçerse [GİZLİ:..] olarak basılır.

Karalanmış veriyi program kullanıyorsa

E-posta ya da TCKN gibi veriler etiketle karalanır, çünkü çoğu zaman çalışma anında gerekmez. Program gerçekten kullanıyorsa onu ortam değişkenine çevir:

$ sealbox vault expose __SECURE_EMAIL_8f2c…__
$ sealbox vault expose __SECURE_EMAIL_8f2c…__ --as ADMIN_EMAIL

5. Kasadaki değerleri yönet

Değerler hiçbir zaman terminale kendiliğinden yazılmaz. Göstermek ve silmek onay ister.

$ sealbox vault list                       # adlar ve etiketler (değer yok)
$ sealbox vault reveal DB_PASSWORD         # onay penceresinde göster
$ sealbox vault reveal __SECURE_TCKN_…__   # karalanmış veriye bak
$ sealbox vault set DB_PASSWORD            # değiştir ya da ekle
$ sealbox vault remove --unused            # kullanılmayanları sil

Geri almak kasadan silmez. Değer değiştiyse eskisi sahipsiz kalır, vault remove --unused temizler. Bir dosya etiketi ya da değişken adını hâlâ kullanıyorsa kayıt silinmez (zorlamak için --force).

6. Ekip arkadaşını ekle

Ön hazırlık (herkes, bir kez)

Bilgisayarında şifreli bir SSH anahtarı olmalı ve açık kısmı GitHub hesabına eklenmiş olmalı. Şifresiz anahtar reddedilir, çünkü bilgisayardaki herhangi bir program (ajanlar dahil) onu okuyabilir.

$ ssh-keygen -t ed25519              # sorulunca şifre koy
$ ssh-keygen -p -f ~/.ssh/id_ed25519 # var olan anahtara sonradan şifre ekle
# ~/.ssh/id_ed25519.pub içeriğini GitHub → Settings → SSH keys'e ekle

Sen (sahip)

$ sealbox team init --github benim-adim   # ekibi kur, sahip sensin
$ sealbox team add arkadasim              # github.com/arkadasim.keys
$ sealbox team add ayse --owner           # o da kişi ekleyip çıkarabilsin
$ git add .sealbox
$ git commit -m "ekibe arkadasim eklendi"
$ git push

Arkadaşın

$ git pull
$ sealbox exec -- python app.py   # ilk açılışta SSH şifresi pencerede sorulur

İlk açılıştan sonra anahtar Windows deposunda önbelleğe alınır, bir daha sorulmaz.

Birini çıkarmak

$ sealbox team remove arkadasim   # kasa anahtarı yenilenir
$ sealbox team list               # üyeler ve SSH parmak izleri

7. Anahtarı kaybedersen

Bugün, her şey yolundayken (bir kez)

$ sealbox recovery setup                    # kod pencerede gösterilir, bir yere yaz
$ sealbox recovery shares                   # isteğe bağlı: 2-of-3 parçaya böl
$ sealbox recovery export D:\proje.sapkit   # isteğe bağlı: USB / bulut kiti

Kod ve parçalar terminale hiçbir zaman yazılmaz, yalnızca pencerede gösterilir. Kurtarma kopyaları ~/.sealbox/recovery/ altında durur, yani repoya girmez. Kod kullanıcı başına bir tanedir. Yeni projeler de sana kod sorulmadan bu kurtarmaya bağlanır.

Kötü gün geldiğinde

8. VS Code ile çalışmak

Eklenti işi kendisi yapmaz. Düğmeleri sealbox komutuna bağlar. O yüzden önce komutun kurulu olması gerekir.

Kurulum

1. pip install sealbox (ya da projenin .venv'ine kur).
2. VS Code'da Eklentiler (Ctrl+Shift+X) → SealBox ara → Yükle. Ya da Marketplace sayfası. Cursor, Windsurf ya da VSCodium'da Open VSX'ten gelir.
3. Elinde .vsix dosyası varsa: code --install-extension sealbox-0.3.0.vsix

Eklenti önce proje klasöründeki ve üstündeki .venv içinde arar, sonra PATH'e bakar. Başka bir yerdeyse ayarlardan sealbox.executable değerine yolunu yaz.

Günlük akış

1. Yaz. Bir dosyaya parola yazıp kaydettiğinde o yer sarı çizilir.
2. Ampule tıkla. "Bu dosyadaki sırları kasaya taşı" de. Değer kasaya gider, kod os.environ[...] olur.
3. Üzerine gel. __SECURE_..__ etiketi ya da os.environ["X"] üzerinde "Değeri göster" çıkar. Onay penceresinden sonra görünür. "Kopyala" dersen pano 30 saniye sonra temizlenir.
4. Çalıştır. Komut paletinden "SealBox: Programı kasayla çalıştır" de. Düz ▶ ile çalıştırıp KeyError alırsan eklenti bunu kendisi önerir.
5. Durum çubuğuna bak. 🔒 3 sır kasada · 👥 2 kişi. Kurtarma kodu yoksa ⚠ yedeksiz yazar. Tıklayınca menü açılır.

Komut paleti (Ctrl+Shift+P → "SealBox")

9. CI'da açık sır kontrolü

seal --check açık sır bulursa çıkış kodu 1 döner. Bunu pull request'lerde bekçi olarak kullan:

name: sealbox
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install sealbox
      - run: sealbox seal --check

Bu adım kasayı açmaz, anahtar gerektirmez. Yalnızca diskte karalanmamış sır olup olmadığına bakar. Makinenin okuyabileceği rapor için --json ekle.

10. Sık sorulanlar

SealBox bir proxy mi?

Hayır. Ajanlar dosyaları doğrudan diskten okur, aradaki bir proxy bunu göremez. SealBox sırları dosyalardan kalıcı olarak çıkarır.

Kasayı repoya koymak güvenli mi?

Evet, bunun için tasarlandı. project.vault AES-256-GCM ile şifreli. Anahtarı repoda değil. .sealbox/.gitignore, yedekleri ve kilit dosyalarını dışarıda bırakır.

Daha önce commit ettiğim sırlar ne olacak?

Git geçmişinde kalırlar; SealBox geçmişi silmez. sealbox history, kasadaki hangi değerlerin eski commit'lerde geçtiğini ve push'lanıp push'lanmadığını söyler. O değerleri servislerinden değiştir, bir daha olmaması için sealbox hook install çalıştır.

Her sırrı bulur mu?

Hayır. Regex; parçalanmış, kodlanmış (\u0040, hex, ROT13) ya da düz yazı içindeki sırları kaçırabilir. Raporu incele, gerekirse custom_rules ekle. İsimler için person_names listesini kullan.

İngilizce kullanabilir miyim?

sealbox --lang en … ya da SEALBOX_LANG=en. Varsayılan dil bilgisayarın dilidir. Eklenti de VS Code'un dilini izler.

Eski adla (secure-ai-proxy) kurmuştum.

Hiçbir şey yapmana gerek yok. Eski .secure_proxy/ klasörleri ve secure_proxy.toml okunur. Kimlik deposundaki eski kayıt ilk açılışta yeni ada taşınır.