helmsight

Tüm sunucularınızı tek ekrandan izleyin. Sunuculara hiçbir şey kurmayın.

helmsight, Linux sunucu filoları için ajansız (agentless) ve kendi altyapınızda çalışan bir web paneli. Merkezdeki bir makinede çalışan tek bir program, sunucularınıza sıradan SSH ile bağlanır; metrikleri ve envanteri yalnızca okuma yapan komutlarla toplar, geçmişi gömülü bir SQLite veritabanında saklar ve hızlı bir web arayüzü sunar. İzlenen sunuculara hiçbir şey kurulmaz, kopyalanmaz ve yazılmaz.

Durum: erken geliştirme aşaması (0.x). helmsight yeni bir proje. Debian, Ubuntu, Rocky, Fedora, openSUSE ve Alpine üzerinde test ediliyor; ancak üretim ortamında henüz az kullanıldı ve bağımsız bir güvenlik denetiminden geçmedi. Yapılandırma seçenekleri, API ve veritabanı biçimi 0.x sürümleri arasında değişebilir. Önce kritik olmayan sunucularda deneyin, veri dizininin yedeğini alın ve yaygın olarak kullanmadan önce güvenlik modelini ve toplama betiğini inceleyin. Veri toplama yalnızca okuma yapar; isteğe bağlı Eylemler (Actions) özelliği ise sizin yapılandırdığınız komutları çalıştırır, bu yüzden dikkatle etkinleştirin. helmsight MIT lisansı altında, olduğu gibi ve hiçbir garanti verilmeden sunulur. Kullanımdan doğan sorumluluk kullanıcıya aittir.

Neler sunar

• Filo görünümü: her sunucu için durum, CPU, bellek, yük, en dolu disk, ağ trafiği, çalışma süresi ve alarmlar; gruplar, etiketler, arama ve küçük eğilim grafikleri (sparkline).
• Sunucu ayrıntısı: canlı ve geçmişe dönük grafikler, çekirdek başına CPU ısı haritası, süreçler, dinlenen portlar, servisler, konteynerler ve sistem bilgileri.
• Geçmiş: otomatik özetlemeyle (rollup) 90 güne kadar veri.
• Sapma (drift) takibi: dünden beri ne değişti; paketlerin, portların, servislerin, çekirdeğin ve işletim sisteminin sunucudan sunucuya ve referans sunucuya (baseline) göre karşılaştırılması.
• Güvenlik görünümü: başarısız SSH girişleri, bekleyen güvenlik güncellemeleri, beklenmeyen portlar, yeniden başlatma gerektiren sunucular ve TLS sertifikalarının bitiş tarihleri.
• Alarmlar: süre ve kapsam tanımlı kurallar, onaylama (acknowledge), susturma (silence), webhook, Slack veya e-posta ile bildirim.
• Eylemler (isteğe bağlı): önceden onaylanmış komutlar; onay penceresi ve yalnızca eklenebilen (append-only) bir denetim kaydı ile.
• Kullanıcılar ve roller, TOTP ile iki adımlı doğrulama, OpenID Connect ile tek oturum açma (SSO).
• Duvar ekranı (NOC ekranları için), OpenAPI belgeli JSON API, sunucu gönderimli olaylar (SSE) ve Prometheus uç noktası.

Nasıl çalışır

1. helmsight her sunucuyla kalıcı bir SSH oturumu açar. Her birkaç saniyede bir bu oturum üzerinde sh -s çalıştırır ve kısa bir POSIX kabuk betiğini standart girdi üzerinden gönderir. Betik uzak sunucuda bir dosyaya yazılmaz ve süreç listesinde görünmez.
2. Betik yalnızca okuma yapar: /proc dosyaları, df, ps, ss, systemctl, paket veritabanı gibi kaynaklar. Bir araç eksikse ya da izin yoksa hata vermek yerine gerekçesiyle birlikte “n/a” (veri yok) döndürür.
3. Çıktı merkezde, boyutu sınırlandırılarak Rust kodu ile ayrıştırılır ve SQLite’a yazılır. Eski veriler dakikalık ve beş dakikalık özetlere dönüştürülür.
4. Web arayüzü programın içine gömülüdür. Tarayıcı yalnızca helmsight’ın sunduğu kodu çalıştırır; uzak sunuculardan gelen metin hiçbir zaman HTML olarak gösterilmez.

Ağır sayılabilecek kontroller (bekleyen güncellemeler, paket envanteri) daha seyrek aralıklarla çalışır. Hangi verinin ne sıklıkla toplandığı güvenlik modeli sayfasında komut komut listelenmiştir.

Tasarım ilkeleri

1. Ajansız. İzlenen sunuculara hiçbir şey kurulmaz veya yazılmaz.
2. Varsayılan olarak salt okunur. Bir sunucuyu yalnızca isteğe bağlı Eylemler özelliği değiştirebilir ve yalnızca bir yöneticinin yapılandırma dosyasına yazdığı komutlarla.
3. Rastgele komut çalıştırma yok. Terminal yok, komut kutusu yok.
4. Varsayılan olarak güvenli. Sunucu anahtarları doğrulanır, sunucu yalnızca yerel adreste (loopback) dinler, gizli değerler şifreli saklanır.
5. Uzak çıktıya güvenilmez. Boyutu sınırlanır, Rust ile ayrıştırılır ve asla HTML olarak işlenmez.
6. Düşük yük. Sunucu başına tek kalıcı SSH oturumu ve birkaç saniyede bir kısa bir kabuk betiği.
7. Taşınabilir. Debian, Ubuntu, RHEL/Rocky/Alma, Fedora, openSUSE ve Alpine (BusyBox).
8. Tek dosya. Web arayüzü gömülüdür; kurulum tek bir dosyayı kopyalamaktan ibarettir.

Bu belgeler hakkında

Belgeler Türkçe ve İngilizce olarak sunulur; her sayfanın üst çubuğundaki bağlantı aynı sayfayı diğer dilde açar. helmsight’ın arayüzü İngilizcedir. Menü ve düğme adları arayüzde göründükleri gibi, kalın yazıyla ve gerektiğinde Türkçe karşılıklarıyla verilir; örneğin Host keys (sunucu anahtarları). Yapılandırma anahtarları, komutlar ve API yolları değişmeden, kod olarak yazılır.

Devam etmek için Kurulum sayfasına geçin veya doğrudan Hızlı başlangıç ile başlayın.

Kurulum

helmsight tek bir statik çalıştırılabilir dosyadır. Yalnızca merkezdeki makinede çalışır; izlenen sunucularda bir SSH sunucusu ve POSIX uyumlu bir kabuktan (/bin/sh) başka bir şey gerekmez.

Gereksinimler

Disk ihtiyacı sunucu sayısı ve saklama süreleriyle orantılıdır; saklama süreleri [retention] bölümünden ayarlanır.

Kurulum betiği

systemd kullanan bir Linux sunucuda kurulum betiği her şeyi tek seferde hazırlar:

curl -fsSLO https://enderkus.github.io/helmsight/install.sh
less install.sh            # root olarak çalıştırmadan önce okuyun
sudo sh install.sh

Betik birkaç soru sorar (web arayüzünün adresi, dış adres, izlenen sunuculardaki hesap, bu sunucunun adresi, ilk yönetici ve parolası), yapacaklarını listeler ve onay ister. Ardından:

1. bu makinenin mimarisine uygun sürüm arşivini indirir ve SHA-256 sağlama toplamını SHA256SUMS ile doğrular; uyuşmazsa durur;
2. /usr/local/bin/helmsight dosyasını kurar ve helmsight sistem kullanıcısını oluşturur;
3. helmsight init çalıştırır; bu da /etc/helmsight/helmsight.toml dosyasını yazar, /etc/helmsight/id_ed25519 SSH anahtarını, veri dizini /var/lib/helmsight’ı ve ilk yöneticiyi oluşturur;
4. sıkılaştırılmış systemd servisini kurar ve başlatır;
5. arayüzün adresini ve izlenen her sunucuyu hazırlayan komutu yazdırır (bkz. Sunucuları izlemeye almak).

Güvenlik duvarına, TLS sertifikalarına veya ters vekil sunucuya dokunmaz; mevcut bir yapılandırmanın, anahtarın veya veritabanının üzerine asla yazmaz.

--yes ile parola sorulmaz: servis ilk yönetici için tek kullanımlık bir kurulum bağlantısı yazdırır, betik de bunu sonda gösterir. Bu kullanım cloud-init gibi otomasyonlarda da çalışır:

sh install.sh --yes --listen 0.0.0.0:8443 --public-url https://monitor.example.com --from 10.0.0.5

Betiği kurulu bir makinede yeniden çalıştırmak programı yükseltir, servisi yeniden başlatır, yapılandırmayı ve veriyi korur. systemd olmayan sistemlerde (ör. Alpine) programı ve yapılandırmayı kurar ve helmsight’ı nasıl başlatacağınızı söyler.

Hazır derlenmiş dosyalar

Her sürümde x86_64 ve aarch64 için statik Linux dosyaları ve bunların SHA-256 sağlama toplamları yayımlanır:

curl -LO https://github.com/enderkus/helmsight/releases/latest/download/helmsight-x86_64-unknown-linux-musl.tar.gz
curl -LO https://github.com/enderkus/helmsight/releases/latest/download/SHA256SUMS
sha256sum --check --ignore-missing SHA256SUMS
tar xzf helmsight-x86_64-unknown-linux-musl.tar.gz
sudo install -m 0755 helmsight-x86_64-unknown-linux-musl/helmsight /usr/local/bin/
helmsight --version

ARM sunucularda (ör. AWS Graviton, Raspberry Pi 4/5 üzerinde 64 bit Linux) x86_64 yerine aarch64 kullanın.

sha256sum --check satırı indirilen arşivin bozulmadığını ve sürüm sayfasındaki dosyayla aynı olduğunu doğrular; OK çıktısını görmeden devam etmeyin.

Konteyner imajı

docker run -d --name helmsight -p 8443:8080 \
  -v helmsight:/var/lib/helmsight \
  -v /etc/helmsight:/etc/helmsight:ro \
  ghcr.io/enderkus/helmsight

Konteynerde /etc/helmsight/helmsight.toml dosyasında listen = "0.0.0.0:8080" ve data_dir = "/var/lib/helmsight" ayarlayın. Yerel olmayan bir adreste dinlediği için TLS kendiliğinden açılır; siz bir sertifika vermezseniz kendinden imzalı (self-signed) bir sertifika üretilir ve parmak izi başlangıçta günlüğe yazılır. Tarayıcıda https://<makine>:8443 adresini açın.

İmajda yalnızca program ve CA sertifikaları bulunur (kabuk bile yoktur). Bu nedenle --local kipi konteynerde kullanılamaz ve komutları docker exec helmsight /helmsight <komut> biçiminde çalıştırmanız gerekir, örneğin:

docker exec -it helmsight /helmsight user add alice --role admin
docker exec -it helmsight /helmsight hosts test --trust

SSH anahtarını ve yapılandırmayı /etc/helmsight altına koyup salt okunur bağlamak, veritabanını ise adlandırılmış bir birimde (helmsight) tutmak önerilir. İmaj UID 65532 olan yetkisiz bir kullanıcıyla çalışır; bağlanan dosyaların bu kullanıcı tarafından okunabilir olması gerekir.

Kaynaktan derleme

Gereksinimler: Rust (stable), Node.js 22 ve npm.

git clone https://github.com/enderkus/helmsight.git
cd helmsight
(cd web && npm ci && npm run build)
cargo build --release
./target/release/helmsight --version

Web arayüzü derleme sırasında programın içine gömülür; bu yüzden önce web dizininde arayüzü derlemeniz gerekir. Arayüz derlenmeden yapılan bir cargo build uyarı verir ve yerine basit bir yer tutucu sayfa koyar.

Başka bir platformda (ör. macOS) statik bir Linux dosyası üretmek için konteyner imajını derleyip dosyayı içinden kopyalayabilirsiniz:

docker build --platform linux/amd64 -t helmsight .
docker create --name hs helmsight
docker cp hs:/helmsight ./helmsight && docker rm hs

Servis olarak çalıştırma

Depoda güvenlik açısından sıkılaştırılmış bir systemd birimi bulunur: examples/helmsight.service.

# Ayrı bir sistem kullanıcısı
sudo useradd --system --home-dir /var/lib/helmsight --shell /usr/sbin/nologin helmsight

# Yapılandırma ve SSH anahtarı: root'a ait, helmsight grubu okuyabilir
sudo install -d -m 0750 -o root -g helmsight /etc/helmsight
sudo install -m 0640 -o root -g helmsight helmsight.toml /etc/helmsight/
sudo install -m 0640 -o root -g helmsight id_ed25519 /etc/helmsight/

sudo cp helmsight.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now helmsight
journalctl -u helmsight -f

Bu birim helmsight’ı yetkisiz bir kullanıcıyla, salt okunur bir dosya sistemiyle, yalnızca kendisine ait bir durum dizini (/var/lib/helmsight) ve kısıtlı bir sistem çağrısı kümesiyle çalıştırır. Yapılandırmada data_dir = "/var/lib/helmsight" kullanın.

İlk kullanıcıyı oluşturmak için ya servis günlüğünde yazan kurulum bağlantısını açın ya da şunu çalıştırın:

sudo -u helmsight helmsight --config /etc/helmsight/helmsight.toml user add alice --role admin

Güncelleme

1. Yeni sürümün değişiklik günlüğünü okuyun; 0.x sürümlerinde uyumsuz değişiklikler olabilir.
2. Veri dizininin yedeğini alın (aşağıya bakın).
3. Yeni dosyayı eskisinin üzerine kurun ve servisi yeniden başlatın: sudo systemctl restart helmsight. Veritabanı şeması gerekiyorsa başlangıçta kendiliğinden güncellenir.

Konteyner kullanıyorsanız yeni imajı çekip konteyneri aynı birimlerle yeniden oluşturmanız yeterlidir.

Yedekleme

Veri dizininde şunlar bulunur:

Tutarlı bir veritabanı yedeği için servisi kısa süreliğine durdurup dosyaları kopyalayın ya da çalışırken SQLite’ın yedekleme komutunu kullanın:

sqlite3 /var/lib/helmsight/helmsight.db ".backup '/yedek/helmsight.db'"

secret.key dosyasını veritabanından ayrı bir yerde saklayın: bu anahtar olmadan saklanan gizli değerler çözülemez, ikisi birlikte ele geçirilirse de gizli değerler açığa çıkar.

Kaldırma

helmsight izlenen sunuculara hiçbir şey kurmadığı için kaldırma yalnızca merkez makinede yapılır: servisi durdurun, programı, /etc/helmsight dizinini ve veri dizinini silin. Sunuculardaki izleme hesabını ve authorized_keys satırını da kaldırabilirsiniz.

Hızlı başlangıç

Bu sayfa helmsight’ı birkaç dakikada çalışır hâle getirmenin iki yolunu anlatır: tek bir makinede SSH olmadan denemek ve SSH ile gerçek sunucuları izlemek.

Tek bir makinede denemek

Bir Linux makinede yerel kip (local mode), /proc dosyalarını doğrudan okuyarak makinenin kendisini izler. SSH’ye ve yapılandırma dosyasına gerek yoktur:

./helmsight serve --local

helmsight tek kullanımlık bir kurulum bağlantısı yazdırır:

  No users exist yet. Create the first administrator:

    http://127.0.0.1:8080/setup#token=…

Bağlantıyı açın, bir kullanıcı adı ve en az 12 karakterlik bir parola seçin; ardından panele girersiniz. Veriler ~/.local/share/helmsight dizininde (root olarak çalıştırıldığında /var/lib/helmsight) saklanır.

Bağlantıdaki belirteç (token) adres çubuğunun # işaretinden sonraki kısmındadır; bu kısım tarayıcıdan sunucuya gönderilmez ve günlüklere yazılmaz. Henüz hiç kullanıcı yoksa helmsight her başlangıçta yeni bir bağlantı üretir.

Yerel kip /proc okuduğu için yalnızca Linux’ta çalışır. Diğer platformlarda aşağıda anlatıldığı gibi sunucuları SSH ile izleyin.

Bir sunucuya kurmak

systemd kullanan bir Linux sunucuda kurulum betiği helmsight’ı servis olarak kurar; yapılandırmayı, SSH anahtarını ve ilk yöneticiyi oluşturur ve sonraki adımları yazdırır:

curl -fsSLO https://enderkus.github.io/helmsight/install.sh
sudo sh install.sh

Bu sayfanın geri kalanı aynı adımları elle anlatır.

Sunucuları SSH ile izlemek

Dört adım yeterlidir:

./helmsight init                    # yapılandırma dosyası, anahtar dosyası, ilk yönetici
$EDITOR helmsight.toml              # [[hosts]] kayıtlarını ekleyin
./helmsight hosts test --trust      # SSH'yi deneyin ve sunucu anahtarlarını onaylayın
./helmsight serve

1. init size birkaç soru sorar (dinleme adresi, veri dizini, SSH kullanıcısı, SSH özel anahtarının yolu, ilk yöneticinin adı ve parolası). Ardından yorum satırlarıyla açıklanmış bir helmsight.toml yazar, veri dizinini ve gizli değerleri şifreleyen secret.key dosyasını oluşturur. SSH anahtarını kendisi üretmez; nasıl üreteceğiniz bir sonraki sayfada anlatılıyor.

2. helmsight.toml dosyasına izlenecek sunucuları ekleyin:

   [[hosts]]
   name = "web-1"
   address = "10.0.0.11"
   groups = ["web"]
   

3. hosts test --trust her sunucuya bağlanır, ilk kez görülen sunucu anahtarlarının parmak izini gösterip onayınızı ister ve sonucu tek satırda yazar. Bu adımdan önce her sunucuda izleme hesabını oluşturmuş olmanız gerekir, örneğin helmsight hosts bootstrap --from <bu sunucunun adresi> | ssh root@web-1 sh ile; ayrıntılar Sunucuları izlemeye almak sayfasında.

4. serve web sunucusunu ve veri toplayıcıları başlatır.

Tarayıcıda http://127.0.0.1:8080 adresini açın ve init sırasında oluşturduğunuz yöneticiyle giriş yapın. Sunucular ilk veri toplanana kadar birkaç saniye Pending (bekliyor) durumunda görünür.

Arayüze başka makinelerden erişmek

helmsight varsayılan olarak yalnızca 127.0.0.1 adresinde dinler; yani arayüze yalnızca aynı makineden erişilebilir. Başka makinelere açmanın iki yolu var:

1. Doğrudan dinlemek. [server] bölümünde listen = "0.0.0.0:8443" ayarlayın. TLS kendiliğinden açılır: ya [server.tls] mode = "files" ile kendi sertifikanızı verin ya da helmsight’ın kendinden imzalı bir sertifika üretmesine izin verin. Üretilen sertifikanın parmak izi başlangıçta günlüğe yazılır; tarayıcının uyarısını geçmeden önce bu parmak iziyle karşılaştırın.

[server]
listen = "0.0.0.0:8443"
public_url = "https://monitor.example.com:8443"

[server.tls]
mode = "files"
cert = "/etc/helmsight/tls/fullchain.pem"
key = "/etc/helmsight/tls/privkey.pem"

2. Ters vekil sunucu (reverse proxy) arkasında. helmsight loopback adresinde kalır, TLS’i nginx, Caddy veya Traefik gibi bir vekil sunucu sonlandırır. Bu durumda public_url ve trusted_proxies ayarlayın:

[server]
listen = "127.0.0.1:8080"
public_url = "https://monitor.example.com"
trusted_proxies = ["127.0.0.1"]

Örnek bir nginx yapılandırması (sunucu gönderimli olaylar için tamponlamayı kapatmak önemlidir):

server {
    listen 443 ssl;
    server_name monitor.example.com;
    # ssl_certificate ... ; ssl_certificate_key ... ;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_http_version 1.1;
        proxy_buffering off;
        proxy_read_timeout 1h;
    }
}

public_url OpenID Connect için zorunludur; ayrıca bildirimlerdeki bağlantılarda ve başka sitelerden gelen istekleri reddeden köken (origin) denetiminde kullanılır.

Sonraki adımlar

• Sunucuları izlemeye almak: izleme hesabı, sunucu listesi ve anahtar onayı.
• Alarmlar ve bildirimler: disk doluluğu gibi kurallar ve Slack/e-posta bildirimleri.
• Güvenlik modeli: helmsight’ın sunucularda tam olarak ne çalıştırdığı.

Sunucuları izlemeye almak

Bu sayfa bir sunucu filosunu baştan sona izlemeye almayı adım adım anlatır. Örneklerde helmsight’ın çalıştığı makinenin adresi 10.0.0.5, izleme hesabının adı monitor’dür.

1. helmsight için bir anahtar oluşturun

Kurulum betiğini veya helmsight init --generate-key komutunu kullandıysanız anahtar zaten vardır (/etc/helmsight/id_ed25519); 2. adımla devam edin.

helmsight’ın çalıştığı makinede (komutlar Kurulum sayfasındaki helmsight sistem kullanıcısının oluşturulduğunu varsayar):

sudo install -d -m 0750 -o root -g helmsight /etc/helmsight
sudo ssh-keygen -t ed25519 -f /etc/helmsight/id_ed25519 -N "" -C helmsight
sudo chgrp helmsight /etc/helmsight/id_ed25519
sudo chmod 0640 /etc/helmsight/id_ed25519

Yalnızca helmsight’a ayrılmış bir ed25519 anahtarı kullanın. RSA anahtarları da çalışır; ancak kullanılan RSA kütüphanesinde bilinen bir zamanlama yan kanalı bulunduğu için ed25519 tercih edilmelidir (ayrıntılar güvenlik modelinde). Parolalı anahtarlar ssh-agent’a yüklenmelidir (ssh.use_agent = true).

2. Her sunucuda izleme hesabını oluşturun

helmsight hosts bootstrap ile

helmsight, aşağıdaki adımların hepsini bir sunucuda yapan bir betik yazdırır: hesabı oluşturur, açık anahtarı restrict,from= ile kurar, Alpine’de anahtarla girişin önündeki kilidi açar ve hesabı günlük grubuna ekler. Yeniden çalıştırmak güvenlidir.

helmsight hosts bootstrap --from 10.0.0.5 | ssh root@web-1 sh

--from, helmsight sunucusunun izlenen sunucunun gördüğü adresidir (birden çok adres veya ağ virgülle ayrılabilir, ör. 10.0.0.5,10.1.0.0/16). Verilmezse anahtar her adresten kabul edilir ve bir uyarı yazdırılır. Betiği çalıştırmadan önce incelemek için bir dosyaya kaydedin:

helmsight hosts bootstrap --from 10.0.0.5 > monitor-account.sh

Elle

İzlenecek her sunucuda root olarak:

useradd --create-home --shell /bin/sh monitor
install -d -m 700 -o monitor -g monitor ~monitor/.ssh
echo 'restrict,from="10.0.0.5" ssh-ed25519 AAAA… helmsight' > ~monitor/.ssh/authorized_keys
chown monitor:monitor ~monitor/.ssh/authorized_keys
chmod 600 ~monitor/.ssh/authorized_keys

• ssh-ed25519 AAAA… helmsight yerine /etc/helmsight/id_ed25519.pub dosyasının içeriğini yazın.
• 10.0.0.5 yerine helmsight sunucusunun, izlenen sunucunun gördüğü adresini yazın. NAT arkasındaysanız bu, çevrilmiş adrestir. from= sayesinde anahtar çalınsa bile başka bir makineden kullanılamaz.
• restrict port, ajan ve X11 yönlendirmesini ve terminal (PTY) ayırmayı kapatır. helmsight bunların hiçbirine ihtiyaç duymaz.
• Hesabın kabuğu çalışan bir POSIX kabuğu olmalıdır (/bin/sh); /usr/sbin/nologin ile veri toplanamaz.

Alpine’de useradd yerine adduser -D -s /bin/sh monitor kullanın. Alpine yeni hesapları kilitli (!) oluşturur ve OpenSSH kilitli hesaplara anahtarla girişi de reddeder. Hesabı parolayla giriş yapılamayacak ama kilitli de sayılmayacak hâle getirin:

sed -i 's/^monitor:!/monitor:*/' /etc/shadow

passwd -u kullanmayın: BusyBox’ta boş parolalı bir hesap bırakabilir.

Çok sayıda sunucu için bu adımları Ansible, Salt veya bulut-init (cloud-init) gibi mevcut araçlarınızla dağıtabilirsiniz. Örnek bir Ansible görevi:

- name: helmsight izleme hesabı
  ansible.builtin.user:
    name: monitor
    shell: /bin/sh
    create_home: true

- name: helmsight anahtarı
  ansible.posix.authorized_key:
    user: monitor
    key: "{{ lookup('file', 'files/helmsight.pub') }}"
    key_options: 'restrict,from="10.0.0.5"'
    exclusive: true

İsteğe bağlı grup üyelikleri

Bazı veriler ek izin gerektirir. Bu izinler olmadan helmsight ilgili görünümde “n/a” ve nedenini gösterir; başka hiçbir şey etkilenmez.

usermod -aG systemd-journal monitor

Sunucuya bunun dışında hiçbir şey kurulmaz.

3. Sunucularınızı tanımlayın

helmsight.toml içinde:

[ssh]
user = "monitor"
identity_files = ["/etc/helmsight/id_ed25519"]

[[hosts]]
name = "web-1"
address = "10.0.0.11"
groups = ["web"]
tags = ["env:prod", "role:web"]

[[hosts]]
name = "web-2"
address = "10.0.0.12"
groups = ["web"]
tags = ["env:prod", "role:web"]
baseline = "web-1"    # sapma ve yeni portlar web-1'e göre karşılaştırılır

[[hosts]]
name = "db-1"
address = "db-1.internal"
port = 2222
user = "observer"     # bu sunucu için farklı hesap
groups = ["db"]

Gruplar ve etiketler nasıl seçilir? Gruplar filoyu kabaca böler (web, db, edge) ve filtrelerde, alarm kurallarında, eylemlerde, bildirim kanallarında ve duvar ekranı belirteçlerinde kapsam olarak kullanılır. Etiketler serbest biçimlidir ve genellikle anahtar:değer şeklinde yazılır (env:prod, dc:ist-1, team:payments). Bir sunucu birden çok gruba ve etikete sahip olabilir.

Referans sunucu (baseline) aynı işi yapan sunucular arasındaki farkları yakalamak içindir. web-2 için baseline = "web-1" yazdığınızda Compare (karşılaştır) görünümü iki sunucu arasındaki paket, port, servis, çekirdek ve işletim sistemi farklarını; güvenlik sayfası da web-2’de dinlenen ama web-1’de bulunmayan portları gösterir.

Sunucu listesini ayrı tutmak

Sunucular ayrı bir dosyada da tutulabilir (yapılandırma dosyasına göre göreli yol):

hosts_file = "hosts.toml"

hosts.toml yalnızca [[hosts]] kayıtlarından oluşur. Bu, sunucu listesini bir envanter aracından üretmeyi kolaylaştırır.

~/.ssh/config dosyasından içe aktarmak

[ssh_config_import]
path = "~/.ssh/config"
hosts = ["web-*", "db-*"]
tags = ["source:ssh-config"]

HostName, User, Port ve IdentityFile dikkate alınır. Aynı adla açıkça yazılmış bir [[hosts]] kaydı önceliklidir. ProxyJump kullanan sunucular uyarıyla atlanır.

Yapılandırmayı helmsight config check ile doğrulayın. Her hata dosyayı, satırı ve anahtarı belirtir:

error: helmsight.toml:23:1: `hosts[1].name`: duplicate host name `web-1`

4. Sunucu anahtarlarını onaylayın

helmsight tanımadığı sunucu anahtarlarını reddeder. Bunları bir kez onaylayın:

helmsight hosts test --trust

HOST        STATUS             DETAIL
web-1       host key unknown   ssh-ed25519 SHA256:ldBw6qzC… ([10.0.0.11]:22)
  Trust this key? Compare with `ssh-keygen -lf` on the host (y/N) [N]: y
  trusted; retrying
web-1       ok                 Debian GNU/Linux 12 (bookworm); user monitor (72 ms)

Onaylamadan önce parmak izini sunucunun kendisinde karşılaştırın:

ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

Anahtarlar arayüzde Host keys (sunucu anahtarları) sayfasından da onaylanabilir; burada yönetici, sunucuda yazdırılan parmak izini yapıştırır ve onay ancak sunulan anahtarla eşleşirse kabul edilir. Daha sonra değişen bir anahtar veri toplamayı durdurur ve bir yönetici inceleyene kadar kritik bir alarm üretir.

Sunucuların çok olduğu ve ağın güvenilir olduğu ortamlarda ssh.accept_new_host_keys = true ile ilk görülen anahtarlar otomatik onaylanabilir (OpenSSH’deki accept-new gibi). Değişen anahtarlar bu ayarda da her zaman reddedilir.

5. Sunucuyu başlatın

helmsight serve

Sunucular ilk veri toplanana kadar, birkaç saniye boyunca Pending (bekliyor) olarak görünür. Bir sunucu Down, Auth failed veya Key not trusted durumunda kalırsa Sorun giderme sayfasına bakın.

helmsight neleri okur

Her turda mevcut SSH oturumu üzerinden tek bir POSIX kabuk betiği çalışır: /proc dosyaları, df, ps, ss, systemctl, paket veritabanı ve benzeri salt okunur kaynaklar. Tam liste ve verilen güvenceler güvenlik modelinde yer alır.

Web arayüzü

Arayüz işletim sisteminin açık veya koyu tema tercihine uyar; üst çubuktan değiştirebilirsiniz. Her görünüm verisinin en son ne zaman güncellendiğini gösterir; bayatlamış veri soluklaştırılır ve etiketlenir. Arayüz canlıdır: sunucu durumları ve alarmlar sayfayı yenilemeden, sunucu gönderimli olaylarla (SSE) güncellenir.

Kullanıcının rolüne göre görünenler değişir:

Filo (Fleet)

Filo görünümü her sunucuyu durumu, CPU ve bellek eğilim grafikleri, yükü, en dolu dosya sistemi, ağ trafiği, çalışma süresi ve etkin alarmlarıyla listeler. Tablo veya kart ızgarası olarak kullanılabilir.

• Durum çipleri duruma göre süzer. Needs attention (ilgi bekleyenler) OK olmayan, kısmen toplanan veya bayatlamış her şeyi bir arada gösterir.
• Arama (/ tuşu) ad, adres, işletim sistemi, grup ve etiketlerde eşleşme arar; group:web ve tag:env:prod biçimleri birebir eşleşir.
• Durumlar farklı sorunları birbirinden ayırır:

Bu ayrım bilinçlidir: “erişilemiyor” bir ağ veya donanım sorunu, “kimlik doğrulama başarısız” bir hesap veya anahtar sorunu, “anahtar değişti” ise olası bir güvenlik olayıdır. Her biri farklı bir ekibin farklı bir müdahalesini gerektirir. Çözüm önerileri için Sorun giderme sayfasına bakın.

Sunucu ayrıntısı

Filo listesinde bir sunucuya tıklayınca açılır. Sekmeler:

• Overview (genel bakış): önce özet değerler, ardından CPU (user, system, iowait, steal), çekirdek başına ısı haritası, bellek ve swap, yük, bağlama noktası başına disk doluluğu, aygıt başına disk G/Ç, arayüz başına ağ trafiği ve TCP bağlantıları grafikleri. 15 dakikadan 30 güne kadar bir aralık ya da özel bir aralık seçin; imleç tüm grafiklerde eş zamanlı hareket eder. Her grafiğin bir tablo görünümü de vardır.
• Processes (süreçler): CPU ve bellek kullanımına göre en üstteki süreçler.
• Network (ağ): dinlenen portlar ve bunlara sahip süreçler, arayüz hızları ve TCP durumları.
• Services (servisler): önce başarısız birimler, ardından çalışan servisler.
• Containers (konteynerler): Docker veya Podman konteynerleri, durumları ve kaynak kullanımları.
• System (sistem): işletim sistemi, çekirdek, donanım, oturum açmış kullanıcılar ve veri toplama ayrıntıları.
• Changes (değişiklikler): paketlerde, portlarda, birimlerde, çekirdekte ve işletim sisteminde neyin değiştiği.
• Security (güvenlik): başarısız SSH girişleri, bekleyen güncellemeler ve referans sunucuda bulunmayan portlar.

Grafikleri okumak

• CPU grafiğinde iowait diskin, steal ise sanallaştırma katmanının (hipervizör başka misafirlere CPU verdiği için bekleme) yarattığı gecikmeyi gösterir. Yüksek steal genellikle sanal makinenin barındığı fiziksel sunucunun aşırı yüklü olduğuna işaret eder.
• Bellek grafiğinde “kullanılan”, geri kazanılabilir önbellek hariç tutularak hesaplanır; Linux’un boş belleği önbellek için kullanması “bellek dolu” olarak görünmez.
• Yük (load average) çekirdek sayısıyla birlikte okunmalıdır; load1_per_core metriği bunu alarm kuralları için hazır verir.
• Sunucuya ulaşılamayan dönemler grafikte boşluk olarak görünür; araya çizgi çekilmez.
• Uzun aralıklarda grafikler, aralığı kapsayan en ince çözünürlükten (ham veri, dakikalık veya beş dakikalık ortalamalar) çizilir. Bu nedenle 30 günlük bir grafikte birkaç saniyelik ani yükselmeler yumuşar; kısa olayları incelemek için daha dar bir aralık seçin.

Karşılaştırma (Compare)

Bir sunucuyu başka bir sunucuyla veya yapılandırılmış referans sunucusuyla karşılaştırın. Yalnızca farklar gösterilir: paketler (ve sürümleri), dinlenen portlar, etkin birimler, çekirdek ve işletim sistemi sürümü. Aynı rolü üstlenen sunucuların zamanla birbirinden uzaklaşmasını (configuration drift) yakalamanın en hızlı yolu budur.

Güvenlik (Security)

Filo genelindeki güvenlik sayfası şunları bir araya getirir: tüm sunucuların başarısız SSH girişlerinin zaman içindeki grafiği ve sunucu başına son 24 saatteki sayısı, bekleyen ve güvenlik güncellemeleri, yeniden başlatma gerektiren sunucular, her sunucunun referans sunucusunda bulunmayan portlar ve helmsight sunucusundan denetlenen TLS sertifikaları.

Değişiklikler (Changes)

Filo genelinde envanter değişikliklerinin zaman çizelgesi; türe ve sunucuya göre süzülebilir. “Dün gece ne değişti?” sorusunun cevabı buradadır: kurulan veya güncellenen paketler, açılan veya kapanan portlar, etkinleştirilen servisler, yeni çekirdek.

Yönetim sayfaları

Yöneticiler ek olarak şu sayfaları görür:

• Users: yerel kullanıcılar, roller ve TOTP durumu.
• Host keys: onay bekleyen ve değişmiş sunucu anahtarları.
• Wall display: duvar ekranı belirteçleri.
• Audit log: eylemlerin ve yönetim işlemlerinin değiştirilemez kaydı.

Her kullanıcı kendi parolasını ve TOTP kaydını sağ üstteki kullanıcı menüsündeki Account (hesap) sayfasından yönetir. Eylemler yapılandırılmışsa operatörler ve yöneticiler menüde Actions sayfasını da görür.

Klavye kısayolları

Alarmlar ve bildirimler

Kurallar

Kurallar yapılandırma dosyasında tanımlanır:

[[alerts.rules]]
id = "disk-full"
expr = "disk_used_pct > 90 for 10m"
severity = "critical"
summary = "Dosya sistemi neredeyse dolu"
tags = ["env:prod"]          # isteğe bağlı kapsam: hosts, groups, tags

expr şu biçimdedir: <metrik> <işleç> <eşik> [for <süre>]. Kural, koşul sürenin tamamı boyunca sağlandığında tetiklenir (firing) ve koşul artık sağlanmadığında çözülür (resolved). disk_used_pct gibi örnek başına (per-instance) metrikler her bağlama noktası için ayrı alarm üretir. Tüm metrikler yapılandırma başvurusunda listelenir; arayüzde Alerts → Rules altında da görünür.

Kural yazmak

• İşleçler: >, >=, <, <=, ==, !=.
• Eşik birimleri: K, M, G, T (1000’in kuvvetleri) ve Ki, Mi, Gi, Ti (1024’ün kuvvetleri). Örneğin net_rx_bytes > 100M saniyede 100 MB demektir.
• Süre (for) kısa dalgalanmalarda gereksiz alarmı önler. Süre verilmezse koşul ilk sağlandığında alarm tetiklenir.
• Kapsam: hosts, groups ve tags listelerinden herhangi biriyle eşleşen sunucular kurala dahil olur. Hiçbiri yazılmazsa kural tüm sunuculara uygulanır.
• Önem derecesi: info, warning (varsayılan) veya critical.

Bir sunucuya ulaşılamadığı sürece onun metrik alarmları çözülmez, durumlarını korur. Böylece kesinti sırasında “disk dolu” alarmı yanlışlıkla kapanıp yeniden açılmaz.

Örnek kurallar

# CPU 15 dakika boyunca %90'ın üstünde
[[alerts.rules]]
id = "cpu-high"
expr = "cpu_pct > 90 for 15m"

# Çekirdek başına yük 2'nin üstünde
[[alerts.rules]]
id = "load-high"
expr = "load1_per_core > 2 for 10m"

# Bellek ve swap baskısı
[[alerts.rules]]
id = "mem-high"
expr = "mem_used_pct > 95 for 5m"
severity = "critical"

# Inode tükenmesi (disk doluluğundan bağımsız olarak dosya oluşturmayı engeller)
[[alerts.rules]]
id = "inodes"
expr = "disk_inodes_used_pct > 90 for 10m"

# Sanal makinede CPU çalınması (hipervizör aşırı yüklü)
[[alerts.rules]]
id = "steal"
expr = "cpu_steal_pct > 10 for 15m"

# Bekleyen güvenlik güncellemesi olan üretim sunucuları
[[alerts.rules]]
id = "security-updates"
expr = "pending_security_updates > 0"
severity = "info"
tags = ["env:prod"]

# Yeniden başlatma gerektiren sunucular
[[alerts.rules]]
id = "reboot"
expr = "reboot_required == 1 for 1d"
severity = "info"

# Kaba kuvvet SSH denemeleri
[[alerts.rules]]
id = "ssh-attempts"
expr = "ssh_failed_logins_1h > 50"

# Saat kayması (TLS, Kerberos ve günlük sıralamasını bozar)
[[alerts.rules]]
id = "clock-skew"
expr = "clock_skew_secs > 30"

# Durmuş konteynerler
[[alerts.rules]]
id = "containers"
expr = "containers_not_running > 0 for 5m"
groups = ["app"]

Yerleşik kurallar

Yapılandırma gerektirmeyen yerleşik kurallar şunları kapsar:

Alarmlarla çalışmak

• Acknowledge (onayla, operatör): alarmla birinin ilgilendiğini gösterir; alarm çözülene kadar hatırlatmalar durur.
• Silence (sustur, operatör): bir kuralı, bir sunucuyu veya ikisini belirli bir süre için, bir gerekçeyle susturur. Susturulan alarmlar yine kaydedilir ama bildirilmez. Planlı bakım çalışmalarında kullanışlıdır.
• Çözülen alarmlar arayüzde yedi gün, veritabanında ise retention.events süresince görünür kalır.

Bildirimler

[[notify]]
id = "ops"
type = "slack"                 # webhook, slack veya email
url = "secret:slack-webhook"   # şifreli saklanır: helmsight secret set slack-webhook
min_severity = "warning"

Bildirimler bir alarm tetiklendiğinde, çözüldüğünde ve onaylanmadığı sürece her alerts.repeat_interval (varsayılan 4 saat) aralığında hatırlatma olarak gönderilir. Teslimatlar başarısız olursa yeniden denenir ve her alarmla birlikte kaydedilir. Yöneticiler POST /api/v1/notify/<id>/test ile deneme bildirimi gönderebilir.

Kanal örnekleri

Slack (veya Slack uyumlu webhook kabul eden Mattermost, Rocket.Chat gibi araçlar):

helmsight secret set slack-webhook     # Webhook adresini girin

[[notify]]
id = "slack-ops"
type = "slack"
url = "secret:slack-webhook"
min_severity = "warning"

E-posta:

[[notify]]
id = "mail-oncall"
type = "email"
smtp_host = "smtp.example.com"
smtp_port = 587
smtp_security = "starttls"
smtp_username = "helmsight@example.com"
smtp_password = "secret:smtp"
from = "helmsight@example.com"
to = ["oncall@example.com"]
min_severity = "critical"

Genel webhook (kendi otomasyonunuz, olay yönetim araçları):

[[notify]]
id = "hook"
type = "webhook"
url = "https://hooks.example.com/helmsight"
headers = { Authorization = "secret:hook-token" }
groups = ["db"]                # yalnızca db grubunun alarmları

Webhook’a gönderilen JSON belgesi yapılandırma başvurusunda açıklanmıştır.

Bir kanala hosts, groups veya tags eklerseniz yalnızca o sunucuların alarmları gönderilir. Sertifika alarmları gibi bir sunucuya bağlı olmayan alarmlar yalnızca kapsamsız kanallara gider.

Eylemler (Actions)

Eylemler, operatörlerin kabuk erişimi olmadan küçük ve önceden onaylanmış bir dizi işi yapmasını sağlar; örneğin nginx’i yeniden başlatmak. Siz yapılandırana kadar kapalıdır; hiç eylem tanımlanmamışsa eylemlerle ilgili arayüz tamamen gizlenir.

Eylemler helmsight’ın izlenen sunucuları değiştirebilen tek özelliğidir. Bu yüzden etkinleştirmeden önce bu sayfanın tamamını okuyun.

[[actions]]
id = "restart-nginx"
label = "Restart nginx"
description = "Web sunucusunu yeniden başlatır. Yaklaşık iki saniye sürer."
command = "sudo -n /usr/bin/systemctl restart nginx.service"
groups = ["web"]       # zorunlu: hosts, groups ve/veya tags
role = "operator"      # operator veya admin
timeout = "60s"

• Komut sabittir. Arayüz yalnızca bir eylem ve bir sunucu seçebilir; argüman geçiremez, komutta şablon veya değişken yoktur.
• Her eylem hedef sunucularını, gruplarını veya etiketlerini açıkça belirtmelidir; “tüm sunucular” varsayılanı yoktur.
• Çalıştırmadan önce bir pencere tam komutu ve sunucuyu gösterir ve onay ister.
• Çıktı (en fazla 64 KiB) arayüzde gösterilir; ilk 4 KiB’ı denetim kaydına da yazılır.
• Yetki gerektiren komutlar sudo -n ile başlamalıdır ve her sunucuda yalnızca o komuta izin veren bir sudoers kuralı bulunmalıdır:

Cmnd_Alias HELMSIGHT_ACTIONS = /usr/bin/systemctl restart nginx.service
monitor ALL=(root) NOPASSWD: HELMSIGHT_ACTIONS

Bu kuralı visudo -f /etc/sudoers.d/helmsight ile ekleyin; visudo sözdizimi hatalı bir dosyanın kaydedilmesini engeller. Örnek dosya: examples/sudoers.

-n seçeneği sudo’nun parola sormasını engeller: kural yoksa komut beklemek yerine hemen hata verir.

Güvenli eylem tasarımı

• sudoers’ta asla kabuk (/bin/sh, bash), düzenleyici (vi, nano), sayfalayıcı (less), joker karakter (*) veya ALL izni vermeyin. Bunların her biri tam root erişimi anlamına gelir.
• systemctl restart nginx.service gibi tam yollu, argümanları sabit komutlar yazın. systemctl restart * gibi kurallar her servisi yeniden başlatmaya izin verir.
• Yeniden başlatma, önbellek temizleme veya bir durum sorgusu gibi geri alınabilir ve etkisi sınırlı işleri eyleme dönüştürün. Veri silen veya yapılandırma değiştiren işler için mevcut değişiklik yönetimi süreçlerinizi kullanın.
• Riskli eylemler için role = "admin" kullanın.
• İzleme hesabının sudo yetkisi yalnızca eylem tanımlanan sunucularda olmalıdır. Salt izleme yapılan sunucularda sudoers kuralı gerekmez.

Örnek, yetki gerektirmeyen bir eylem:

[[actions]]
id = "disk-usage"
label = "Show disk usage"
description = "Dosya sistemlerinin doluluğunu gösterir."
command = "df -h"
groups = ["web", "db"]

Denetim kaydı (Audit log)

Her çalıştırma, başladığında ve bittiğinde denetim kaydına yazılır: kullanıcı, sunucu, komut, çıkış kodu ve çıktının ilk 4 KiB’ı. Yöneticiler kaydı Audit log sayfasında okur. Kullanıcı, sunucu anahtarı, susturma, duvar ekranı belirteci ve gizli değer değişiklikleri de kaydedilir.

Kayıt yalnızca eklenebilir (append-only): veritabanı güncelleme ve silme işlemlerini reddeder ve her kayıt bir öncekine zincirlenen bir SHA-256 özeti taşır. Arayüzdeki Verify integrity (bütünlüğü doğrula) düğmesi veya helmsight audit verify komutu, kayıtlarla oynanıp oynanmadığını tespit eder.

Bu zincir, veritabanı dosyasına doğrudan erişen birinin geçmiş bir kaydı sessizce değiştirmesini veya silmesini fark edilir kılar; ancak merkez sunucuda root yetkisi olan birinin kaydı tamamen yeniden yazmasını engelleyemez. Denetim gereksinimleriniz sıkıysa kaydı düzenli olarak dışarıya (ör. API üzerinden) aktarın.

Duvar ekranı

Duvar ekranı, TV ve NOC ekranları için tam ekran, salt okunur bir görünümdür: sunucu gruplarına göre düzenlenmiş büyük durum kutucukları, etkin alarmlar ve bir saat; gezinme menüsü yoktur. Filo ekrana sığmadığında gruplar arasında 20 saniyede bir döner. Durum yalnızca renkle değil, metin ve simgeyle de gösterilir; uzaktan ve renk körlüğü olan kişiler tarafından okunabilir.

Oturum açmışken /display adresini açın ya da ekranın bir hesaba ihtiyaç duymaması için bir duvar ekranı belirteci (token) kullanın:

1. Yönetici olarak Wall display sayfasını açın ve bir belirteç oluşturun; ekranın görebileceği grupları (veya tüm sunucuları) seçin.
2. Yalnızca bir kez gösterilen adresi kopyalayın, örneğin https://monitor.example.com/display#token=hsd_…, ve ekranda açın.

Belirteç adresin # işaretinden sonraki kısmında (URL fragment) durur; bu kısım web sunucularına gönderilmez ve günlüklerine yazılmaz. Belirteç yalnızca seçilen gruplara okuma erişimi verir ve istendiği an iptal edilebilir; iptal edildiğinde ekran belirtecin artık geçerli olmadığını gösterir.

Belirteç kalıcıdır: ekranın tarayıcısı yeniden başlasa da aynı adres çalışmaya devam eder. Bir ekran çalınır veya el değiştirirse yalnızca o ekranın belirtecini iptal edin; diğer ekranlar etkilenmez. Her ekran için ayrı bir belirteç oluşturmak bu yüzden iyi bir alışkanlıktır.

Seçenekler

Adresin # kısmına & ile eklenir:

Örnek: https://monitor.example.com/display#token=hsd_…&rotate=30&theme=dark

Ekran kurulumu için ipuçları

• Tarayıcıyı kiosk kipinde açın, örneğin chromium --kiosk --noerrdialogs "https://monitor.example.com/display#token=…".
• Ekranın uyku kipine geçmesini ve ekran koruyucuyu kapatın.
• Kendinden imzalı sertifika kullanıyorsanız ekran tarayıcısının sertifikaya güvenmesini sağlayın; aksi hâlde her yeniden başlatmada uyarı sayfası açılır.
• Bağlantı koparsa ekran verinin bayatladığını gösterir ve bağlantı geldiğinde kendiliğinden toparlanır.

Yapılandırma başvurusu

helmsight tek bir TOML dosyası okur. Aşağıdakilerden ilk bulunan kullanılır:

1. --config <yol>
2. $HELMSIGHT_CONFIG
3. /etc/helmsight/helmsight.toml
4. ./helmsight.toml

English version

examples/helmsight.toml her seçeneği yorumlarıyla gösteren bir örnektir. Bir dosyayı helmsight config check ile doğrulayın; hatalar dosyayı, satırı, sütunu ve anahtarı gösterir:

error: helmsight.toml:23:1: `hosts[1].name`: duplicate host name `web-1`
error: helmsight.toml:41:8: `alerts.rules[0].expr`: unknown operator `=>` (use > >= < <= == !=)

Bilinmeyen anahtarlar hatadır; böylece yazım yanlışları sessizce geçmez.

Süreler "500ms", "30s", "5m", "1h30m", "7d", "2w" gibi metinlerdir (ms milisaniye, s saniye, m dakika, h saat, d gün, w hafta).

Gizli değerler düz metin olarak yazılabilir, ancak başvuru kullanmak tercih edilir:

env: systemd’nin EnvironmentFile= veya konteynerin ortam değişkenleriyle, file: ise Docker/Kubernetes gizli dosyalarıyla (/run/secrets/...) iyi çalışır.

Yapılandırma değişiklikleri yeniden başlatmadan sonra geçerli olur.

Tam bir örnek

# En üst düzey anahtarlar herhangi bir [bölüm] başlığından önce gelmelidir.
hosts_file = "hosts.toml"

[server]
listen = "127.0.0.1:8080"
data_dir = "/var/lib/helmsight"
public_url = "https://monitor.example.com"
trusted_proxies = ["127.0.0.1"]

[auth]
require_totp_for_admins = true

[ssh]
user = "monitor"
identity_files = ["/etc/helmsight/id_ed25519"]

[[alerts.rules]]
id = "disk-full"
expr = "disk_used_pct > 90 for 10m"
severity = "critical"

[[notify]]
id = "ops"
type = "slack"
url = "secret:slack-webhook"

[[certs]]
endpoint = "www.example.com:443"

TOML kuralları gereği bir [bölüm] başlığından sonra yazılan her anahtar o bölüme ait sayılır. hosts_file gibi en üst düzey anahtarları bu yüzden dosyanın en başına yazın; yanlış yere yazılırsa config check bunu bilinmeyen anahtar olarak bildirir.

[server]

trusted_proxies istemci adresinin doğru belirlenmesi için önemlidir: oturum açma hız sınırlaması istemci adresine göre çalışır. Vekil sunucu arkasında bu ayar yapılmazsa bütün kullanıcılar vekil sunucunun adresinden geliyormuş gibi görünür.

[server.tls]

Let’s Encrypt sertifikası kullanıyorsanız cert için fullchain.pem, key için privkey.pem dosyasını gösterin ve sertifika yenilendikten sonra helmsight’ı yeniden başlatın (ör. certbot’un --deploy-hook seçeneğiyle).

[auth]

[auth.oidc]

Kimlik sağlayıcıda yönlendirme adresi (redirect URI) olarak <public_url>/api/v1/auth/oidc/callback kaydedin. Roller her oturum açılışında alandan yeniden okunur; yani kimlik sağlayıcıda bir kullanıcının grubunu değiştirmek bir sonraki girişte rolünü de değiştirir.

Örnek (Keycloak):

[auth.oidc]
issuer = "https://sso.example.com/realms/ops"
client_id = "helmsight"
client_secret = "secret:oidc"
role_claim = "realm_access.roles"
role_map = { "helmsight-admin" = "admin", "sre" = "operator", "dev" = "viewer" }
label = "Şirket hesabıyla giriş"

Yerel yönetici hesabını acil durum girişi olarak tutmanız önerilir; SSO çalışmadığında arayüze erişimi kaybetmemek için disable_local_login ayarını dikkatle kullanın.

[ssh]

[collect]

Başarısız sunucular artan aralıklarla yeniden denenir: ulaşılamadığında 5 dakikaya kadar üstel olarak, kimlik doğrulama hatalarından sonra (saldırı önleme sistemlerini tetiklememek için) 1 ila 5 dakika arasında ve sunucu anahtarı sorunlarında dakikada bir.

interval değerini düşürmek grafiklerin çözünürlüğünü artırır ama hem sunuculardaki hem de veritabanındaki yükü orantılı olarak artırır. Çok sayıda sunucuda 10–15 saniye makul bir başlangıçtır.

[retention]

Grafikler istenen aralığı kapsayan en ince çözünürlüğü seçer. Süreleri uzatmak veritabanını orantılı olarak büyütür. Süresi dolan veriler saatte bir kendiliğinden silinir; özetler dakikada bir hesaplanır.

Sunucular

[[hosts]]

hosts_file

En üst düzeydeki hosts_file = "hosts.toml" başka bir dosyadan (yapılandırma dosyasına göre göreli) ek [[hosts]] kayıtları yükler.

[ssh_config_import]

HostName, User, Port ve IdentityFile dikkate alınır; eşleşen Host blokları arasında OpenSSH’nin “ilk değer kazanır” kuralı geçerlidir. Aynı adla açıkça yazılmış [[hosts]] kayıtları önceliklidir. ProxyJump olan sunucular uyarıyla atlanır; Match ve Include değerlendirilmez.

Alarmlar

[alerts]

Yerleşik kurallar: host_unreachable (critical; kimlik doğrulama hataları için de), host_key_changed (critical), host_key_unknown (warning), failed_units (warning, birim başına bir alarm), cert_expiry (kalan güne göre warning veya critical; denetim başarısız olursa warning).

[[alerts.rules]]

İşleçler: >, >=, <, <=, ==, !=. Eşikler K, M, G, T (1000’in kuvvetleri) ve Ki, Mi, Gi, Ti (1024’ün kuvvetleri) soneklerini kabul eder. Örnek başına metrikler her örnek için (ör. her bağlama noktası için) ayrı alarm üretir. Bir sunucuya ulaşılamadığı sürece onun metrik alarmları çözülmez, durumlarını korur.

Kurallarda kullanılabilen metrikler

[[notify]]

Bildirimler bir alarm tetiklendiğinde, çözüldüğünde (tetiklenme bildirimi gönderilmişse) ve hatırlatma olarak gönderilir. Susturulmuş alarmlar kaydedilir ama bildirilmez. Başarısız teslimatlar üç kez yeniden denenir ve alarmla birlikte listelenir. API’den deneme gönderin: POST /api/v1/notify/<id>/test.

Webhook gövdesi:

{
  "version": 1,
  "source": "helmsight",
  "status": "firing",
  "alert": {
    "id": 42,
    "rule": "disk-full",
    "host": "web-1",
    "instance": "/var",
    "severity": "critical",
    "summary": "disk_used_pct on /var is 93.1% (> 90.0%)",
    "value": 93.1,
    "started_at": "2026-09-30T16:56:12Z",
    "resolved_at": null,
    "acknowledged_by": null
  },
  "url": "https://monitor.example.com/alerts?id=42"
}

status değeri firing, resolved, reminder veya test olur.

[[certs]]

Sertifika doğrulanmasa bile okunur; güven sorunları bağlantı hatalarından ayrı gösterilir. Denetim helmsight sunucusundan yapılır; yani yalnızca helmsight’ın erişebildiği uç noktalar denetlenebilir.

[[actions]]

[prometheus]

scrape_configs:
  - job_name: helmsight
    scheme: https
    authorization:
      credentials_file: /etc/prometheus/helmsight.token
    static_configs:
      - targets: ["monitor.example.com"]

Sunulan metrikler helmsight_ önekini taşır: host_up, host_alerts_firing, cpu_percent{mode}, memory_*_bytes, load1/5/15, filesystem_{size,used,avail}_bytes{mount}, disk_{read,written}_bytes_per_second{device}, network_{receive,transmit}_bytes_per_second{interface}, tcp_connections{state}, pending_updates, pending_security_updates, reboot_required ve daha fazlası; hepsi host etiketiyle.

Komut satırı

Genel seçenekler: --config <yol>, --data-dir <dizin> (server.data_dir değerini geçersiz kılar; yapılandırma dosyası olmadan komutlar yerel kipin varsayılanı olan ~/.local/share/helmsight dizinini, root için /var/lib/helmsight dizinini kullanır), --log-format text|json.

Hiç kullanıcı yokken serve, ilk yöneticiyi tarayıcıda oluşturmak için tek kullanımlık bir kurulum bağlantısı (/setup#token=...) yazdırır.

Ortam değişkenleri

HTTP API

Web arayüzü, /api/v1 altındaki sürümlü JSON API’nin aynısını kullanır. OpenAPI belgesi /api/v1/openapi.json adresinde sunulur. Kimlik doğrulama için POST /api/v1/auth/login ile alınan oturum çerezini kullanın; durum değiştiren istekler GET /api/v1/auth/me yanıtında dönen X-CSRF-Token başlığını gerektirir. Canlı güncellemeler /api/v1/events adresinde sunucu gönderimli olaylar olarak sunulur. Duvar ekranları /api/v1/display/state adresini Authorization: Bearer <belirteç> başlığıyla çağırır. /healthz kimlik doğrulama olmadan ok döndürür.

Komut satırı

helmsight [--config <yol>] [--data-dir <dizin>] [--log-format text|json] <komut>

Her komutun ayrıntılı yardımı için helmsight <komut> --help kullanın.

init seçenekleri

init, seçenek olarak verilmeyen her değeri sorar. --non-interactive ile hiçbir şey sormaz ve geri kalanlar için varsayılanları kullanır; bu durumda ilk yönetici yalnızca --password-stdin ile oluşturulur.

Genel --data-dir seçeneği yapılandırmaya yazılacak veri dizinini belirler. Etkileşimli kipte anahtar dosyası yoksa init onu oluşturmayı önerir.

printf '%s\n' "$PAROLA" | helmsight --config /etc/helmsight/helmsight.toml \
  --data-dir /var/lib/helmsight init --non-interactive \
  --ssh-key /etc/helmsight/id_ed25519 --generate-key --admin alice --password-stdin

Yapılandırma dosyasının bulunması

Yapılandırma dosyası şu sırayla aranır: --config, $HELMSIGHT_CONFIG, /etc/helmsight/helmsight.toml, ./helmsight.toml. Yapılandırma dosyası olmadan (yerel kip) --data-dir ya da yerel kipin varsayılan dizini (~/.local/share/helmsight, root için /var/lib/helmsight) kullanılır.

Sık kullanılan örnekler

# Parolayı betikten vererek kullanıcı oluşturma (ör. otomasyon)
printf '%s\n' "$PAROLA" | helmsight user add alice --role operator --password-stdin

# TOTP cihazını kaybeden kullanıcı
helmsight user reset-password alice --reset-totp

# Yalnızca iki sunucuyu denemek
helmsight hosts test web-1 db-1

# Yeni bir izlenen sunucuyu hazırlamak
helmsight hosts bootstrap --from 10.0.0.5 | ssh root@web-3 sh

# Slack webhook adresini şifreli saklamak
helmsight secret set slack-webhook

# Gizli değeri bir dosyadan okumak
helmsight secret set smtp --stdin < /run/secrets/smtp

# Geçici olarak farklı bir adreste çalıştırmak
helmsight serve --listen 127.0.0.1:9090

--password-stdin ve --stdin seçenekleri parolanın kabuk geçmişine veya süreç listesine düşmemesini sağlar; parolaları komut satırı argümanı olarak vermenin bir yolu bilerek sunulmaz.

Çıkış kodları

Komutlar başarıda 0, hata durumunda sıfırdan farklı bir kodla çıkar. hosts test en az bir sunucuya bağlanamazsa, config check yapılandırmada hata bulursa, audit verify zincirde bir kırılma bulursa başarısız olur. Bu sayede komutlar betiklerde ve CI hatlarında denetim olarak kullanılabilir.

Günlükler

Günlük ayrıntısı HELMSIGHT_LOG ile ayarlanır, örneğin HELMSIGHT_LOG=debug veya HELMSIGHT_LOG=info,server=debug. --log-format json günlükleri, bir günlük toplama sistemine aktarmaya uygun JSON satırları olarak yazar. Günlüklerde hiçbir zaman gizli değer, parola, oturum belirteci veya toplanan çıktı bulunmaz.

API ve entegrasyonlar

JSON API

Web arayüzü, /api/v1 altındaki sürümlü API’nin aynısını kullanır; yani arayüzde görebildiğiniz her şeye API’den de ulaşabilirsiniz. Koddan üretilen OpenAPI belgesi /api/v1/openapi.json adresinde sunulur ve Swagger UI, Postman veya bir istemci üreteci ile kullanılabilir.

Kimlik doğrulama, POST /api/v1/auth/login ile alınan oturum çerezi (cookie) ile yapılır. Durum değiştiren istekler, GET /api/v1/auth/me yanıtında dönen X-CSRF-Token başlığını göndermelidir:

curl -c cookies -H 'Content-Type: application/json' \
  -d '{"username":"alice","password":"…"}' https://monitor.example.com/api/v1/auth/login
curl -b cookies https://monitor.example.com/api/v1/hosts

Otomasyon için ayrı bir viewer (veya gerekiyorsa operator) kullanıcısı oluşturun; kişisel hesapları betiklerde kullanmayın.

Sık kullanılan uç noktalar:

Tam liste ve şemalar için OpenAPI belgesine bakın.

Örnek: kritik alarmları listelemek

curl -sb cookies https://monitor.example.com/api/v1/alerts \
  | jq '.[] | select(.severity == "critical" and .state == "firing") | {host, rule_id, summary}'

Yanıtın tam biçimi için OpenAPI belgesindeki alerts şemasına bakın.

Sunucu gönderimli olaylar (SSE)

GET /api/v1/events bir olay akışı sunar: host olayları (bir sunucunun özeti her değiştiğinde) ile istemcinin veriyi yeniden çekmesi gerektiğini bildiren alerts, changes ve hostkeys olayları. resync olayı istemcinin geride kaldığını ve sayfayı yeniden yüklemesi gerektiğini belirtir.

curl -Nb cookies https://monitor.example.com/api/v1/events

Ters vekil sunucu kullanıyorsanız bu yol için tamponlamayı kapatın (nginx’te proxy_buffering off), aksi hâlde olaylar gecikmeli gelir.

Prometheus

[prometheus]
enabled = true
token = "secret:prometheus"

Bu ayarla /metrics, Authorization: Bearer <token> başlığı taşıyan isteklere toplanan sunucu metriklerini Prometheus metin biçiminde sunar. Metrik adları yapılandırma başvurusunda listelenir.

Bu, helmsight’ı mevcut bir Prometheus + Grafana kurulumuna veri kaynağı olarak eklemeyi sağlar: sunuculara node_exporter kurmadan temel sistem metriklerini Prometheus’ta toplayabilir, uzun süreli saklamayı ve panoları orada yapabilirsiniz.

Webhook’lar

Webhook kanalları her bildirim için bir JSON belgesi alır; belge biçimi yapılandırma başvurusunda açıklanmıştır.

Güvenlik modeli

Bu belge helmsight’ın izlenen sunucularda ne yaptığını, neyi yapamayacağını, en az yetkiyle nasıl çalıştırılacağını ve bir güvenlik açığının nasıl bildirileceğini anlatır.

English version

Tehdit modeli

helmsight’ta üç taraf vardır:

1. Merkez sunucu helmsight programını çalıştırır. SSH özel anahtarlarını, veritabanını (metrikler, envanter, kullanıcılar, oturumlar, denetim kaydı) ve saklanan gizli değerleri şifreleyen bir anahtar dosyasını tutar.
2. İzlenen sunuculara SSH ile bağlanılır. Çıktılarına güvenilmez: ele geçirilmiş bir sunucu ya da bir süreç adını, bir günlük satırını veya bir dosya adını kontrol eden yetkisiz bir yerel kullanıcı, helmsight’a kötü niyetli veri göndermeye çalışabilir.
3. Kullanıcılar web arayüzüne HTTP(S) üzerinden bir rolle erişir: viewer (izleyici), operator (operatör) veya admin (yönetici). Duvar ekranları iptal edilebilir, salt okunur belirteçler kullanır.

helmsight şu güvenceleri verecek şekilde tasarlanmıştır:

• Ele geçirilmiş bir izlenen sunucu tarayıcıya veya merkez sunucuya saldıramaz. Çıktının boyutu sınırlanır (çalıştırma başına 16 MiB) ve bozuk girdide asla çökmeyen (panic) Rust koduyla ayrıştırılır. Bu, gerçek çıktının kesilmiş ve bozulmuş hâlleriyle çalışan fuzz benzeri testlerle denetlenir. Değerler HTML olarak değil, her zaman metin olarak gösterilir. Tarayıcı yalnızca programın sunduğu kodu çalıştırır; İçerik Güvenliği Politikası (Content-Security-Policy) satır içi betikleri, satır içi stilleri, çerçeveye alınmayı ve üçüncü taraf kaynakları yasaklar. Betik çıktısındaki bölüm işaretleri, uzak süreç listesinde hiçbir zaman görünmeyen ve her çalıştırmada değişen rastgele bir değer (nonce) içerir; böylece bir süreç veya günlük satırı sahte bir bölüm üretemez.
• Ele geçirilmiş bir izlenen sunucu diğer sunuculara ulaşamaz. Her sunucunun kendi SSH oturumu vardır; hiçbir şey yönlendirilmez (ajan yönlendirme yok, port yönlendirme yok).
• Bir arayüz kullanıcısı rastgele komut çalıştıramaz. Terminal, dosya yöneticisi veya komut girişi yoktur. Eylemler yapılandırma dosyasındaki sabit komut metinleridir; API yalnızca bir eylem kimliği ve bir sunucu adı kabul eder ve kullanıcının rolünün ve sunucunun buna izin verdiğini denetler.
• Ağdaki bir saldırgan bir sunucunun kimliğine bürünemez. SSH sunucu anahtarları OpenSSH known_hosts kurallarıyla doğrulanır. Bilinmeyen anahtarlar, bir yönetici parmak izini onaylayana kadar (veya accept_new_host_keys açık değilse) reddedilir. Değişen bir anahtar her zaman veri toplamayı durdurur, kritik bir alarm üretir ve yeni parmak izinin bir yönetici tarafından doğrulanmasını gerektirir.

Kapsam dışı: merkez sunucuda root yetkisi elde eden bir saldırgan SSH anahtarlarını ve veritabanını okuyabilir. O makineyi buna göre koruyun.

Pratikte ne anlama gelir

• helmsight’ın izleme anahtarı çalınırsa saldırgan yalnızca yetkisiz monitor hesabıyla ve (from= kullandıysanız) yalnızca helmsight sunucusunun adresinden giriş yapabilir. Bu yüzden restrict,from= seçeneklerini atlamayın.
• Bir sunucu ele geçirilirse en kötü ihtimalle o sunucuya ait yanlış metrikler gösterilir; saldırgan bunu helmsight’a veya diğer sunuculara sıçramak için kullanamaz.
• Merkez sunucu filonun tamamına okuma erişimi olan bir makinedir; bir sıçrama sunucusu (bastion) kadar özenle korunmalıdır: güncel tutun, yalnızca gerekli portları açın ve arayüze erişimi sınırlayın.

helmsight’ın izlenen sunucularda çalıştırdıkları

helmsight her turda sunucunun kalıcı SSH oturumunda bir kanal açar ve sh -s çalıştırır; toplama betiği standart girdi üzerinden gönderilir. Betik crates/collect/src/remote.sh dosyasındadır; kullanmadan önce inceleyin. Yalnızca okuma işlemleri içerir:

Betiğin özellikleri:

• Yalnızca POSIX sh; dash, bash ve BusyBox ash altında çalışır.
• Bütün çıktı yönlendirmeleri /dev/null’a gider (bir birim testi bunu zorunlu kılar).
• Eksik veya izin verilmeyen araçlar hata değil, gerekçesiyle birlikte “n/a” üretir.
• Uzun sürebilecek komutlar, varsa timeout ile sınırlandırılır.
• Betik uzak sunucuda bir dosyaya kaydedilmez; standart girdiden okunur ve süreç listesinde yalnızca sh -s olarak görünür.

Sunucuda neler yazılır

helmsight’ın komutları hiçbir şey yazmaz. Entegrasyon test takımı Debian, Ubuntu, Rocky, Fedora, openSUSE ve Alpine üzerinde yetkisiz bir kullanıcı olarak oturum açar, tüm toplama gruplarını çalıştırır ve /proc, /sys, /dev, /run ve /var/log dışında hiçbir dosyanın değişmediğini doğrular.

Her SSH girişinde olduğu gibi, oturum açmanın yan etkisi olarak yine de şunlar olur:

• Sunucunun giriş kayıtları oturumu kaydeder (wtmp, lastlog, journal veya syslog).
• Ubuntu’da pam_motd, izleme hesabının ilk girişinde ev dizininde ~/.cache/motd.legal-displayed dosyasını oluşturur.

Sizin denetiminizdeki istisnalar:

• dnf/yum: dnf ve yum her zaman kendi günlük dosyalarını ve yetkisiz kullanıcılar için /var/tmp altında bir önbellek yazar. Bu yüzden RHEL ailesindeki sunucularda bekleyen güncellemeler yalnızca collect.dnf_updates = true olduğunda listelenir.
• root olarak apt: root hesabıyla izleme yapıyorsanız (önerilmez), apt-get -s /var/cache/apt altındaki ikili paket önbelleğini yenileyebilir.
• Eylemler tam olarak bir yöneticinin yapılandırdığı komutları çalıştırır ve bunlar sunucuyu değiştirebilir. Yapılandırılmadıkça kapalıdır.

İzleme hesabını oluşturmak

helmsight hosts bootstrap --from 10.0.0.5 bir sunucuda aşağıdakileri yapan (ve Alpine’de anahtarla girişin önündeki kilidi açan) bir betik yazdırır; bunu ssh root@<sunucu> sh komutuna aktarın veya önce inceleyin. Elle yapmak için izlenen her sunucuda:

# authorized_keys için ev dizini olan yetkisiz bir hesap.
useradd --create-home --shell /bin/sh monitor
install -d -m 700 -o monitor -g monitor ~monitor/.ssh

# Anahtarı kısıtlayın: PTY yok, yönlendirme yok, yalnızca helmsight sunucusundan.
echo 'restrict,from="10.0.0.5" ssh-ed25519 AAAA... helmsight' \
  > ~monitor/.ssh/authorized_keys
chown monitor:monitor ~monitor/.ssh/authorized_keys
chmod 600 ~monitor/.ssh/authorized_keys

restrict port, ajan ve X11 yönlendirmesini ve PTY ayırmayı kapatır; helmsight bunların hiçbirine ihtiyaç duymaz. 10.0.0.5 yerine helmsight sunucusunun adresini yazın.

Hesaba parola atamayın; giriş yalnızca anahtarla yapılmalıdır. Sunucularınızda sshd_config içinde PasswordAuthentication no kullanmanız da önerilir.

İsteğe bağlı grup üyelikleri; her biri görünürlüğü artırır:

Bunlar olmadan helmsight ilgili görünümde gerekçesiyle birlikte “n/a” gösterir.

helmsight’ın kullandığı SSH anahtarı yalnızca ona ayrılmalı ve ed25519 türünde olmalıdır (ssh-keygen -t ed25519 -f /etc/helmsight/id_ed25519 -N ""). RSA anahtarları da çalışır; ancak kullanılan RSA kütüphanesinde özel anahtar işlemlerinde bilinen bir zamanlama yan kanalı vardır (RUSTSEC-2023-0071), bu yüzden ed25519’u tercih edin. Anahtarlar dosyalardan (ssh.identity_files, yalnızca helmsight kullanıcısının okuyabileceği şekilde) veya ssh-agent’tan yüklenebilir. Parolalı anahtarlar ssh-agent’a yüklenmelidir.

Sunucu anahtarlarına güvenmek

Yeni sunucular, anahtarlarına güvenilene kadar reddedilir. İki yol vardır:

• her parmak izini gösterip onay isteyen helmsight hosts test --trust komutunu çalıştırın; veya
• anahtarı arayüzde Host keys sayfasından onaylayın. Yönetici, sunucuda ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub komutunun yazdırdığı parmak izini yapıştırmalıdır; onay ancak sunulan anahtarla eşleşirse gerçekleşir.

Onaylanan anahtarlar <data_dir>/known_hosts dosyasında saklanır. Mevcut OpenSSH dosyaları ssh.known_hosts_files ile salt okunur olarak kullanılabilir. Sunucularınızın anahtarlarını zaten bir yapılandırma yönetim aracıyla dağıtıyorsanız bu dosyayı göstermek en güvenli yoldur.

Eylemler

Eylemler izlenen sunucuları değiştiren tek özelliktir ve yapılandırılmadıkça kapalıdır.

• Komutları bir yönetici yapılandırma dosyasına yazar. Arayüz argüman geçiremez ve şablon kullanılmaz.
• Her eylem hedef sunucularını, gruplarını veya etiketlerini açıkça listelemelidir.
• Arayüz, tam komutu ve sunucuyu bir onay penceresinde gösterir.
• Yetki gerektiren komutlar sudo -n kullanmalıdır. sudoers’ta tam olarak bu komutlara izin verin (examples/sudoers); asla kabuk, düzenleyici, joker karakter veya ALL izni vermeyin.
• Her çalıştırma denetim kaydına iki kez yazılır: başlamadan önce ve çıkış kodu ile kısaltılmış çıktısıyla birlikte bittiğinde.
• Denetim kaydı yalnızca eklenebilir. Veritabanı tetikleyicileri güncelleme ve silmeyi reddeder; her kayıt bir öncekine zincirlenmiş bir SHA-256 özeti taşır. helmsight audit verify (veya arayüzdeki Verify integrity) kayıtlarla oynanıp oynanmadığını tespit eder.

Merkez sunucu

• helmsight’ı ayrı bir sistem kullanıcısıyla, examples/helmsight.service dosyasındaki sıkılaştırılmış systemd birimiyle çalıştırın.
• Veri dizini 0700, veritabanı, anahtar dosyası ve kendinden imzalı TLS anahtarı 0600 izinleriyle oluşturulur. helmsight başka kullanıcıların okuyabildiği bir anahtar dosyasını kullanmayı reddeder.
• Yapılandırmadaki gizli değerler düz metin yerine başvuru olarak yazılabilir (secret:<ad>, env:<DEĞİŞKEN>, file:<yol>). Saklanan gizli değerler ve TOTP tohumları, ilk çalıştırmada oluşturulan <data_dir>/secret.key ile XChaCha20-Poly1305 kullanılarak şifrelenir. Anahtar dosyasını veritabanından ayrı yedekleyin.
• helmsight gizli değerleri, parolaları, oturum belirteçlerini veya veri toplama çıktılarını hiçbir zaman günlüğe yazmaz.

Web uygulaması güvenliği

• Varsayılan olarak 127.0.0.1 adresinde dinler. Başka adreslerde TLS kendiliğinden açılır: verilen sertifikalarla veya SHA-256 parmak izi başlangıçta günlüğe yazılan kendinden imzalı bir sertifikayla. Herkese açık bir adreste düz HTTP kullanmak server.tls.allow_insecure_http = true gerektirir; bu, TLS’i sonlandıran bir ters vekil sunucunun arkasındaki kurulumlar içindir (server.public_url değerini vekil sunucunun https:// adresine, server.trusted_proxies değerini de onun adresine ayarlayın).
• Parolalar Argon2id ile özetlenir (19 MiB, 2 yineleme); var olmayan kullanıcılar yanlış parolalarla aynı sürede yanıtlanır, böylece kullanıcı adları yanıt süresinden tahmin edilemez. En kısa parola 12 karakterdir.
• İsteğe bağlı TOTP (RFC 6238); kodlar ikinci kez kullanılamaz. Yöneticilerin TOTP kaydı zorunlu tutulabilir (auth.require_totp_for_admins).
• OpenID Connect, PKCE, state ve nonce ile yetkilendirme kodu akışını kullanır. Roller yapılandırılabilir bir alandan (claim) okunur; eşleşen rolü olmayan kullanıcılar, default_role ayarlanmadıkça reddedilir.
• Oturum çerezleri rastgele 256 bitlik belirteçlerdir; özetlenmiş olarak saklanır, HttpOnly, SameSite=Strict, TLS ile Secure ve __Host- önekiyle gönderilir. Oturumlar auth.session_ttl sonunda ve auth.idle_timeout kadar hareketsizlikten sonra sona erer.
• Durum değiştiren istekler oturuma özgü X-CSRF-Token başlığını gerektirir ve Origin başlığı başka bir siteyi gösterdiğinde reddedilir.
• Oturum açma denemeleri kullanıcı adı ve istemci adresi başına sınırlandırılır.
• Yanıtlar Content-Security-Policy (satır içi kod yok, çerçeveye alma yok), X-Content-Type-Options, Referrer-Policy: no-referrer, Cross-Origin-Opener-Policy, Permissions-Policy ve TLS kullanıldığında HSTS başlıklarını taşır. API yanıtları önbelleğe alınmaz.
• Duvar ekranı belirteçleri özetlenmiş olarak saklanır, yalnızca sabit bir grup kümesine okuma erişimi verir, adresin # kısmında taşınır (sunuculara ve günlüklere gönderilmez) ve her an iptal edilebilir.
• Prometheus uç noktası, bir taşıyıcı belirteç (bearer token) yapılandırılmadıkça kapalıdır.

Kurulum öncesi güvenlik kontrol listesi

• helmsight ayrı bir sistem kullanıcısıyla, systemd birimiyle veya konteynerde çalışıyor.
• İzleme anahtarı yalnızca helmsight’a ait bir ed25519 anahtarı ve dosyası başkaları tarafından okunamıyor.
• authorized_keys satırında restrict,from="…" var.
• İzleme hesabı docker grubunda değil (ya da bunun root’a eşdeğer olduğu bilinerek eklendi).
• Sunucu anahtarları parmak izi karşılaştırılarak onaylandı; accept_new_host_keys yalnızca güvenilir bir ağda açık.
• Arayüz loopback’te ve bir TLS vekil sunucusunun arkasında ya da doğrudan TLS ile sunuluyor; public_url ayarlı.
• Yöneticiler için TOTP zorunlu (auth.require_totp_for_admins = true) veya giriş SSO ile yapılıyor.
• Gizli değerler secret:, env: veya file: başvurularıyla yazılmış; yapılandırma dosyasında düz metin parola yok.
• secret.key veritabanından ayrı yedekleniyor.
• Eylemler kullanılıyorsa sudoers yalnızca tam komutlara izin veriyor.

Güvenlik açığı bildirmek

Güvenlik sorunlarını lütfen deponun Security sekmesindeki GitHub Report a vulnerability düğmesiyle gizli olarak bildirin. Herkese açık bir kayıt (issue) açmayın. Sürümü (helmsight --version), bir açıklamayı ve sorunu yeniden üretme adımlarını ekleyin. Bildirimler Türkçe veya İngilizce yapılabilir.

Bildirimleri üç iş günü içinde yanıtlamayı ve düzeltmeyi ve güvenlik duyurusunu olabildiğince çabuk yayımlamayı hedefliyoruz. Bildirenler, aksini tercih etmedikçe duyuruda anılır.

Sık sorulan sorular

Neden ajan (agent) kullanılmıyor? Ajanların her sunucuya kurulması, güncellenmesi, yapılandırılması ve güvenilmesi gerekir; ayrıca saldırı yüzeyini genişletirler. SSH zaten her sunucuda vardır, zaten sıkılaştırılmıştır ve zaten denetlenmektedir. helmsight buna yalnızca okuma yapan bir oturum ekler.

Sunucuya ne kadar yük bindirir? Her 5 saniyede bir, /proc altındaki dosyaları okuyan ve birkaç hafif aracı çalıştıran kısa bir kabuk betiği: birkaç milisaniyelik CPU zamanı. Bekleyen güncellemeler gibi pahalı denetimler 6 saatte bir çalışır. Aralıklar [collect] bölümünden değiştirilebilir.

Merkez sunucu ne kadar kaynak ister? helmsight tek bir süreçtir; sunucu başına bir kalıcı SSH oturumu ve kompakt metrik satırları tutar. Birkaç yüz sunucunun küçük bir sanal makinede rahatça izlenmesi beklenir.

root yetkisi gerekir mi? Hayır. Yetkisiz, yalnızca bu işe ayrılmış bir hesap kullanın. Birkaç ayrıntı grup üyeliği gerektirir (başarısız girişler için günlük erişimi, konteynerler için Docker soketi); helmsight okuyamadığı her şey için gerekçesiyle birlikte “n/a” gösterir.

Sunuculara gerçekten hiçbir şey yazmıyor mu? helmsight’ın komutları hiçbir şey yazmaz; bunu altı dağıtımda çalışan bir entegrasyon testi denetler. SSH girişleri sunucu tarafından her zamanki gibi kaydedilir (wtmp, lastlog, journal ve Ubuntu’da hesabın ev dizininde bir kerelik pam_motd işareti). dnf ve yum her zaman günlük dosyası yazdığı için RHEL ailesindeki sunucularda bekleyen güncellemeler yalnızca collect.dnf_updates = true ile listelenir.

Hangi dağıtımlar destekleniyor? Debian, Ubuntu, RHEL ve türevleri (Rocky, Alma), Fedora, openSUSE ve Alpine. SSH sunucusu ve POSIX kabuğu olan her Linux’ta çalışması beklenir; eksik araçlar “n/a” olarak görünür.

Linux dışı sistemleri (BSD, macOS, Windows) izleyebilir miyim? Hayır. Toplama betiği Linux’un /proc dosya sistemine dayanır.

Atlama sunucusu (jump host / bastion) kullanabilir miyim? Henüz değil. İçe aktarılan SSH yapılandırmasında ProxyJump olan sunucular uyarıyla atlanır.

Kaç sunucuyu kaldırabilir? Veri toplama eşzamanlıdır ve sunucu başına bir kalıcı oturum kullanır; aynı anda toplanan sunucu sayısı collect.max_parallel ile sınırlanır. Depolama her örnek için sunucu başına tek ve kompakt bir satır kullanır.

Veriler nerede? Veri dizininde: helmsight.db (SQLite), secret.key, known_hosts ve tls/. Anahtar dosyasını veritabanından ayrı yedekleyin; saklanan gizli değerler onsuz çözülemez. Ayrıntılar için Kurulum → Yedekleme.

Verileri dışarıya aktarabilir miyim? Evet: JSON API ve OpenAPI belgesi, Prometheus uç noktası ve alarmlar için webhook’lar var. Bkz. API ve entegrasyonlar.

Koyu tema var mı? Evet. Arayüz işletim sisteminin tercihine uyar; üst çubuktan değiştirebilirsiniz.

Arayüz Türkçe mi? Hayır, arayüz şimdilik İngilizcedir. Bu belgeler arayüzdeki adları Türkçe karşılıklarıyla birlikte verir.

Üretimde kullanabilir miyim? helmsight 0.x sürümündedir: test edilmiştir, ancak üretimde henüz az kullanılmıştır ve bağımsız bir güvenlik denetiminden geçmemiştir. Önce kritik olmayan sunucularda deneyin, güvenlik modelini okuyun ve sorumluluğun kullanıcıda olduğunu unutmayın.

Bir hata veya güvenlik açığı buldum. Hataları GitHub Issues üzerinden bildirin. Güvenlik açıklarını ise herkese açık bir kayıt açmadan, güvenlik modelinde anlatıldığı gibi gizli olarak bildirin.

Sorun giderme

İşe helmsight config check ve helmsight hosts test ile başlayın. İlki yapılandırmayı doğrular; ikincisi her sunucuya bağlanır ve her sunucu için, arayüzdeki durumlarla aynı olan tek satırlık bir sonuç yazar.

Sunucu “Down” görünüyor

helmsight, ssh.connect_timeout süresi içinde bir TCP bağlantısı açamadı veya SSH el sıkışmasını tamamlayamadı.

• helmsight sunucusundan ssh -p <port> monitor@<adres> true komutunu deneyin.
• İki makine arasındaki güvenlik duvarlarını ve sunucunun address ile port değerlerini denetleyin.
• Ulaşılamayan sunucular 5 dakikaya kadar artan aralıklarla yeniden denenir; düzelen bir sunucunun geri gelmesi birkaç dakika sürebilir.

Sunucu “Auth failed” görünüyor

SSH sunucusu helmsight’ın sunduğu bütün anahtarları reddetti.

• Açık anahtar sunucuda ~monitor/.ssh/authorized_keys dosyasında mı? Dosyanın izinleri 600 ve sahibi hesabın kendisi mi?
• from="…" seçeneği, sunucunun gördüğü adresle eşleşiyor mu? NAT arkasında bu, çevrilmiş adrestir.
• Hesap kilitli mi veya kabuğu /usr/sbin/nologin mi? helmsight çalışan bir POSIX kabuğuna (/bin/sh) ihtiyaç duyar. Alpine’de adduser -D ile oluşturulan hesaplar kilitlidir; bkz. Sunucuları izlemeye almak.
• helmsight süreci anahtar dosyasını okuyabiliyor mu? systemd birimiyle çalışırken dosyanın helmsight grubu tarafından okunabilir olması gerekir.
• Sunucudaki SSH günlüğü genellikle nedeni açıkça yazar: journalctl -u ssh -u sshd --since "10 min ago" veya /var/log/auth.log, /var/log/secure.
• Kimlik doğrulama hatalarından sonra helmsight yeniden denemeden önce 1–5 dakika bekler; böylece fail2ban gibi araçları tetiklemez.

“Key not trusted” veya “Key changed”

• Key not trusted: sunucu yeni. helmsight hosts test --trust çalıştırın veya parmak izini sunucuda ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub ile karşılaştırdıktan sonra arayüzde Host keys sayfasından onaylayın.
• Key changed: veri toplama bilerek durduruldu. Sunucu yeniden kurulduysa veya anahtarları yenilendiyse yeni parmak izini sunucuda doğrulayın ve Host keys sayfasından onaylayın. Değişikliği açıklayamıyorsanız olası bir ortadaki adam (man-in-the-middle) saldırısı olarak ele alın.

Bir görünümde “n/a” yazıyor

“n/a” her zaman sunucunun bildirdiği nedenle birlikte gösterilir. Sık görülenler:

Dinlenen portların sahibi olan süreçler yalnızca izleme hesabının kendi süreçleri için görünür; bu, yetkisiz kullanıcılar için çekirdeğin koyduğu bir kısıttır.

Rocky, Alma, RHEL veya Fedora’da bekleyen güncelleme görünmüyor

dnf ve yum salt okunur sorgularda bile günlük dosyası yazdığı için helmsight bunları siz collect.dnf_updates = true ayarlamadıkça çalıştırmaz. Güncellemeler 6 saatte bir denetlenir (collect.updates_interval).

Kurulum bağlantısını kaybettim

Hiç kullanıcı olmadığı sürece helmsight serve her başlangıçta yeni bir kurulum bağlantısı yazdırır. Ya da yöneticiyi komut satırından oluşturun:

helmsight user add alice --role admin

Parolamı unuttum veya TOTP cihazımı kaybettim

helmsight user reset-password alice --reset-totp

Bu komut yeni bir parola belirler, TOTP kaydını kaldırır ve kullanıcının oturumlarını sonlandırır.

Girişte “Cross-origin request refused” hatası

Tarayıcının gönderdiği Origin, helmsight’ın gördüğü adresle eşleşmiyor. Ters vekil sunucu arkasındaysanız server.public_url değerini tam dış adres olarak ayarlayın (ör. https://monitor.example.com) ve vekil sunucunun Host başlığını korumasını sağlayın.

Tek oturum açma (SSO) çalışmıyor

• server.public_url ayarlanmış olmalı ve <public_url>/api/v1/auth/oidc/callback kimlik sağlayıcıda yönlendirme adresi (redirect URI) olarak kayıtlı olmalıdır.
• role_map içinde eşleşen bir değeri olmayan kullanıcılar, default_role ayarlanmadıkça reddedilir. Kimlik sağlayıcının belirtecinde role_claim ile belirtilen alanı denetleyin.

Port kullanımda

Başlangıçta adresin kullanımda olduğuna dair bir hata alırsanız aynı portu başka bir süreç (veya çalışmaya devam eden eski bir helmsight) kullanıyordur:

sudo ss -ltnp 'sport = :8080'

Ya o süreci durdurun ya da --listen veya server.listen ile başka bir port seçin.

Daha fazla ayrıntı almak

Sunucuyu daha ayrıntılı günlükle çalıştırın:

HELMSIGHT_LOG=debug helmsight serve

Günlüklerde gizli değerler ve toplanan çıktı hiçbir zaman bulunmaz. Bir sorun bildirirken helmsight --version çıktısını, etkilenen sunucunun dağıtımını ve helmsight hosts test <ad> çıktısını ekleyin.

Katkıda bulunmak

Yardımınız için teşekkürler. Bu belge geliştirme ortamını, her değişikliğin geçmesi gereken denetimleri ve helmsight’ı güvenli tutan kuralları anlatır.

English version

Sorular, hata bildirimleri ve önerilerinizi Türkçe veya İngilizce olarak GitHub Issues üzerinden iletebilirsiniz. Kod, kod yorumları ve commit mesajları İngilizce yazılır.

Geliştirme ortamı

Gereksinimler: Rust stable (bkz. rust-toolchain.toml), Node.js 22, npm ve entegrasyon testleri için Docker.

(cd web && npm ci && npm run build)   # program web/dist dizinini gömer
cargo build
./target/debug/helmsight serve --local --data-dir /tmp/helmsight-dev

Arayüz üzerinde çalışırken arka ucu ve Vite geliştirme sunucusunu yan yana çalıştırın; Vite /api isteklerini http://127.0.0.1:8080 adresine yönlendirir (HELMSIGHT_DEV_BACKEND ile değiştirilebilir):

cargo run -- serve --config dev.toml
(cd web && npm run dev)

Arayüz derlenmemişse cargo build yerine basit bir yer tutucu sayfa gömer ve uyarı verir; böylece yalnızca Rust tarafında çalışmak için Node.js gerekmez.

Proje yapısı

Denetimler

Her commit şunları geçmelidir:

cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo deny check
(cd web && npm run check && npm run lint && npm test && npm run build)

Entegrasyon testleri sshd konteynerleri başlatır ve veri toplamayı uçtan uca doğrular; izlenen sunucuya hiçbir şey yazılmadığı da buna dahildir:

HELMSIGHT_DOCKER_TESTS=1 cargo test -p transport --test docker
# altı dağıtımın hepsi:
HELMSIGHT_DOCKER_TESTS=1 HELMSIGHT_DOCKER_DISTROS="debian ubuntu rocky fedora opensuse alpine" \
  cargo test -p transport --test docker

Ayrıştırıcı örnek çıktıları

crates/collect/tests/fixtures dizini Debian, Ubuntu, Rocky, Fedora, openSUSE ve Alpine’den root ve yetkisiz kullanıcı olarak alınmış gerçek betik çıktılarını içerir. remote.sh dosyasını değiştirdikten sonra bunları yeniden üretin:

scripts/capture-fixtures.sh            # tüm dağıtımlar
scripts/capture-fixtures.sh alpine     # yalnızca biri

Örnek çıktılardaki farkı gözden geçirin; bunlar test takımının bir parçasıdır.

Kod kuralları

• Uzak çıktıya güvenilmez. Ayrıştırıcılar rastgele baytları kabul etmeli, asla çökmemeli (collect crate’i unwrap, panic ve indekslemeyi yasaklar), sakladıklarının boyutunu sınırlamalı ve gerekçesiyle “n/a” durumuna düşmelidir. Gerçek çıktıyla bir test ekleyin ve tests/fuzz.rs içindeki özellik tabanlı testlerin kapsamasını sağlayın.
• Uzak betik salt okunurdur. Yalnızca POSIX sh, geçici dosya yok, her yönlendirme /dev/null’a (bir birim testi bunu zorunlu kılar), her araç isteğe bağlı. shellcheck -s sh ile denetleyin.
• Rastgele komut yok. Bir sunucuda çalıştırılmak üzere komut, argüman veya yol kabul eden bir API asla eklemeyin.
• Uzak veriyi asla HTML olarak işlemeyin. {@html} yok, innerHTML yok; ESLint ikisini de reddeder. Arayüzü sıkı CSP ile uyumlu tutun: satır içi betik veya style="..." özniteliği yok (sınıflar veya style: yönergeleri kullanın).
• Gizli değerleri asla günlüğe yazmayın: parolalar, belirteçler veya toplanan çıktı dahil.
• Arayüz metinleri kısa, olgusal ve tekniktir. Hata mesajları ne olduğunu ve sonra ne yapılacağını söyler. Durum hiçbir zaman yalnızca renkle anlatılmaz.

Commit’ler ve pull request’ler

• Conventional Commits kullanın: feat(collect): parse /proc/pressure, fix(ui): keep table header sticky.
• Commit’leri küçük ve derlenebilir tutun; her commit yukarıdaki denetimleri geçer.
• Kullanıcıyı etkileyen değişiklikler için CHANGELOG.md dosyasında “Unreleased” başlığını, davranış veya yapılandırma değiştiğinde de belgeleri güncelleyin. Belgelerde bir değişiklik yaptığınızda İngilizce ve Türkçe sürümleri birlikte güncellemeye çalışın; Türkçesini yazamıyorsanız pull request’te belirtmeniz yeterlidir.

Projeyi yeniden adlandırmak

Ürün adı üç yerde tanımlıdır: crates/helmsight/Cargo.toml içindeki program crate’inin adı (ve [[bin]] adı), crates/common/src/lib.rs içindeki PRODUCT_NAME (çerez adları, veritabanı dosyasının adı, Prometheus metrik önekleri) ve web/src/lib/brand.ts içindeki PRODUCT_NAME.

Güvenlik sorunlarını bildirmek

Güvenlik açıkları için lütfen herkese açık kayıt açmayın; bkz. güvenlik modeli.

Değişiklik günlüğü

Değişiklik günlüğü yalnızca İngilizce tutulur. Sürüm notları GitHub’daki sürümler sayfasında da yayımlanır. Biçim Keep a Changelog kurallarına, sürüm numaraları Anlamsal Sürümleme kurallarına uyar. 0.x sürümleri arasında yapılandırma, API ve veritabanı biçimi değişebilir; yükseltmeden önce ilgili sürümün notlarını okuyun.

Unreleased

0.2.0 - 2026-10-01

Added

• An installation script (install.sh, published on the website and with each release) that verifies the download, installs the binary and a hardened systemd service, and creates the configuration, an SSH key and the first administrator. Running it again upgrades an installation; --uninstall removes it and keeps the data.
• helmsight hosts bootstrap prints a script that creates the monitoring account on a host, with the public key restricted by restrict,from=.
• helmsight init accepts its answers as options (--listen, --public-url, --ssh-user, --ssh-key, --admin), runs without questions with --non-interactive, reads the administrator’s password with --password-stdin and creates an ed25519 key with --generate-key.
• Turkish documentation: README.tr.md, docs/tr/ and a Turkish website and documentation under /tr/, with language links between them.
• A troubleshooting page in the documentation.
• More detailed documentation in both languages: requirements, upgrades, backups, reverse proxy setup, example alert rules and notification channels, safe action design and a security checklist.

Fixed

• The README quick start now changes into the directory unpacked from the release archive before running the binary.

0.1.1 - 2026-10-01

Fixed

• Sign-in and every other state-changing request were refused as cross-origin when the web UI was served over TLS with HTTP/2.

0.1.0 - 2026-10-01

Added

• Agentless collection over SSH with one persistent session per host and a single read-only POSIX shell script per tick, tested on Debian, Ubuntu, Rocky, Fedora, openSUSE and Alpine.
• Local mode (serve --local) that monitors the machine it runs on.
• Fleet overview with groups, tags, search, sparklines and distinct states for unreachable hosts, authentication failures, host key problems and partial collections.
• Host detail with live and historical charts, per-core CPU heatmap, top processes, listening ports, services, containers and system information.
• History in SQLite with 1-minute and 5-minute rollups and configurable retention.
• Inventory snapshots, change timeline and host-to-host or baseline comparison.
• Security overview: failed SSH logins, pending and security updates, reboot-required flags, ports not on the baseline and TLS certificate expiry.
• Alert rules with durations and scopes, built-in rules, acknowledgements, silences, reminders, and webhook, Slack and email notifications.
• Opt-in actions with confirmation and a hash-chained, append-only audit log.
• Viewer, operator and admin roles; Argon2id passwords; TOTP; OpenID Connect single sign-on with role mapping.
• Wall display mode with revocable, group-scoped display tokens.
• Versioned JSON API with OpenAPI document, server-sent events and a Prometheus endpoint.
• TLS with provided certificates or a generated self-signed certificate.
• Secrets encrypted at rest with XChaCha20-Poly1305.
• CLI: serve, init, user, hosts test, config check, secret, audit verify.