Repository navigation
Installation TR
Üç desteklenen çalıştırma yolu var. Hepsi aynı konteyner imajını ve aynı yapılandırma dosyalarını kullanır; birini seçin ve Yapılandırma sayfasıyla devam edin. Demodan kendi Wazuh'unuzdan alınmış, denetlenmiş bir rapora kadar adım adım ilk çalıştırma için Başlangıç sayfasını izleyin.
| Yol | Ne zaman | Süre |
|---|---|---|
| Docker Compose | VM, all-in-one Wazuh veya ilk deneme | 5–15 dk |
| Kubernetes (Helm veya Kustomize) | Wazuh zaten kümede çalışıyorsa | 15–30 dk |
| Yerel Python | geliştirme veya kodu hızlıca görmek | 5 dk |
- Wazuh erişimi. Indexer (9200) zorunlu; Wazuh API (55000) isteğe bağlıdır ama ajan, servis, kural ve logtest kontrollerini açar. docs/permissions.md sayfasındaki salt okunur hesapları oluşturun — admin kimlik bilgisi kullanmayın.
-
Model. Anthropic anahtarı, OpenAI uyumlu herhangi bir uç nokta veya yerel model (Ollama, vLLM, LM Studio).
LLM_PROVIDER=mockyalnızca demo içindir. - TLS. Arayüzde parola ve imzalı çerez var; HTTPS arkasında yayınlayın, paylaşılan ağda düz HTTP kullanmayın.
-
Ağ. Konteyner Indexer ve API'ye, ayrıca model uç noktasına HTTPS ile erişebilmelidir. Wazuh kendinden
imzalı sertifika kullanıyorsa CA'yı
./config/certs/altına kopyalayıpca_fileayarlayın.
git clone https://github.com/occultera/occultera.git
cd occultera
cp .env.demo .env
docker compose up -d --build.env.demo yalnızca demonun ihtiyacını içerir (WDT_DEMO=true, LLM_PROVIDER=mock, bir demo parolası).
Bunun yerine .env.example kopyasına WDT_DEMO=true eklemeyin: .env içinde bir değişken iki kez geçerse
son satır geçerlidir. http://127.0.0.1:8080 adresini açın, demo-password-change-me ile giriş yapın ve
bir kez Run check now düğmesine basın. Demo her sayfada örnek veriyle açılır: tamamlanmış bir rapor, açık Nöbet ve son 24 saatin AI turunda
değerlendirilmiş altı olayı (başarısız denemelerden sonra başarılı SSH girişi, Active Response engellemesi, kopan
ajan …), Ayarlar'da bekleyen iki öneri ve tek özel algılayıcılı bir maskeleme profili. WDT_DEMO_SEED=false
ile boş açılır. Demo
config/demo.yaml ve sentetik veri kullanır; Wazuh'a bağlanmaz. WDT_DEMO=true ile
ENVIRONMENT=production birlikte kullanılamaz — uygulama açılmaz. (Hazır 0.7.0 imajı ayrıca
WDT_CONFIG=config/demo.yaml istiyordu; 0.8.0'da düzeltildi.)
docker-compose.yml portu yalnızca 127.0.0.1 üzerinde yayınlar, ./config dizinini salt okunur bağlar ve
denetim kaydını audit adlı volume'da tutar (docker compose cp triage:/app/logs/audit.jsonl . ile dışarı alınır). Örnek dosyadan başlayın:
cp .env.example .env
openssl rand -hex 32 # APP_SECRETAsgari .env:
ENVIRONMENT=production
APP_PASSWORD=<güçlü ve benzersiz parola>
APP_SECRET=<openssl çıktısı>
COOKIE_SECURE=true
FORWARDED_ALLOW_IPS=172.16.0.0/12
LLM_PROVIDER=anthropic
LLM_MODEL=<model kimliği>
LLM_API_KEY=<anahtar>
WAZUH_ENV_NAME=Production
WAZUH_INDEXER_URL=https://wazuh-indexer.example.internal:9200
WAZUH_INDEXER_USER=daily-triage
WAZUH_INDEXER_PASSWORD=<indexer parolası>
WAZUH_API_URL=https://wazuh-manager.example.internal:55000
WAZUH_API_USER=daily-triage
WAZUH_API_PASSWORD=<api parolası>
WAZUH_CA_FILE=/app/config/certs/root-ca.pemFORWARDED_ALLOW_IPS, konteynerin proxy'yi gördüğü adres olmalıdır. Host üzerindeki bir proxy, yayınlanan
127.0.0.1:8080 adresine bağlandığında konteynere 127.0.0.1'den değil Docker köprü ağ geçidinden (ör.
172.18.0.1) gelir; docker network inspect <proje>_default ile bakıp aralığı bu adrese daraltın. Yanlışsa
yönlendirme başlıkları yok sayılır: giriş sınırlaması ve denetim kaydında herkes tek IP görünür. Asla *
kullanmayın.
CA'yı kopyalayın:
mkdir -p config/certs
cp /yol/root-ca.pem config/certs/root-ca.pemSonra:
docker compose up -d
docker compose exec triage python -m app.checkpython -m app.check [ortam…] [--no-llm] (veya ortamın Raporlar sayfasındaki Test connections) Indexer'ı (alarm,
zafiyet ve depolama indeksleri), API'yi, yapılandırılmış ek kaynakları ve modeli koşu başlatmadan doğrular.
Bildirimlerin kendi Bildirim testi düğmesi vardır.
.enviçindeki yorumlar kendi satırında olmalıdır:docker compose, değer satırında#sonrasını değerin parçası sayar.
Üretimde imajı sabitleyin.
docker-compose.ymldemoyu kolaylaştırmak için:latestkullanır. Üretimdeghcr.io/occultera/occultera:0.12.1(veya kendi digest'inizi) yazın; böylece yükseltme bilinçli bir adım olur.
YAML dosyasını oluşturun; konteyner ./config dizinini zaten bağlar:
cp config/environments.example.yaml config/environments.yaml
mkdir -p config/context config/seed
cp config/context/example.md config/context/prod.md
vi config/environments.yamlconfig/environments.yaml varsa WAZUH_* tek-ortam değişkenleri yok sayılır ve tüm ortamlar YAML'dan gelir.
Parolalar .env içinde ${DEGISKEN} olarak kalır ve açılışta genişletilir. Tam şema için
Yapılandırma sayfasına bakın.
docker-compose.yml isteğe bağlı bir Ollama profili içerir:
docker compose --profile ollama up -d
docker exec -it ollama ollama pull qwen3:14b# .env
LLM_PROVIDER=openai
LLM_BASE_URL=http://ollama:11434/v1
LLM_MODEL=qwen3:14bSonra triage konteynerini yeniden başlatın. Rapor kalitesi modele bağlıdır: küçük modeller araç çağrılarını
atlamaya ve daha zayıf bulgular üretmeye eğilimlidir; istemleri ayarlamadan önce daha büyük bir model deneyin.
Yerel modelde alarm içeriği ana makineden çıkmaz — düzenlemeye tabi ortamlarda genellikle belirleyici olan budur.
Helm chart ve Kustomize temeli aynı sertleştirilmiş podu kurar: tek replika, root olmayan kullanıcı, salt
okunur kök dosya sistemi, PVC yok (durum Wazuh Indexer'da), /healthz liveness ve /readyz readiness.
helm repo add occultera https://occultera.github.io/occultera
helm repo updatemy-values.yaml:
secret:
APP_PASSWORD: "..."
APP_SECRET: "..." # openssl rand -hex 32
LLM_API_KEY: "..."
INDEXER_PASSWORD: "..."
API_PASSWORD: "..."
app:
cookieSecure: true
forwardedAllowIPs: "10.0.0.0/8" # ingress denetleyicisinin pod CIDR'ı, asla "*"helm install occultera occultera/occultera \
--version 0.4.1 -f my-values.yamlDepodan doğrudan: helm install occultera ./deploy/helm/occultera -f my-values.yaml.
secret: altındaki her anahtar podda ortam değişkenine dönüşür; VIEWER_PASSWORD, MCP_TOKEN ve
METRICS_TOKEN da oraya gider. Gizli olmayan anahtarlar (AUTH_DISABLED, LOG_LEVEL, ADMIN_ENVS, …)
env: altına yazılır. Uygulama yapılandırması (config.environments) ${VAR} yer tutucuları içeren tam bir
environments.yaml'dır.
cp -r deploy/kubernetes/example ~/triage-overlay
cd ~/triage-overlay
# depo dışında göreli "../base" çözülmez — sürümü sabitlenmiş uzak base'i gösterin:
sed -i 's#^ - ../base.*# - https://github.com/occultera/occultera//deploy/kubernetes/base?ref=v0.12.1#' kustomization.yaml
cp secret.env.example secret.env
vi secret.env environments.yaml context.md
kubectl apply -k .
kubectl -n wazuh-daily-triage rollout status deploy/wazuh-daily-triage
kubectl -n wazuh-daily-triage exec deploy/wazuh-daily-triage -- python -m app.checkdeploy/kubernetes/components/ altındaki isteğe bağlı bileşenler: networkpolicy, ingress-nginx,
ingress-traefik-authentik, rbac-readonly. Ayrıntılar:
deploy/kubernetes/README.md.
Yalnızca tek replika. Zamanlayıcı süreç içinde çalışır; ikinci replika her kontrolü iki kez çalıştırır. Deployment bu yüzden
Recreatestratejisini kullanır. Ek replikaları yalnızca erişilebilirlik için çalıştıracaksanızWDT_SCHEDULER=falseayarlayın.
python -m venv .venv
. .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
# demo
WDT_DEMO=true APP_PASSWORD=demo uvicorn app.main:app --reload
# gerçek yapılandırma
WDT_CONFIG=config/environments.yaml APP_PASSWORD=... uvicorn app.main:app --reloadUygulama .env dosyasını kendisi okumaz; değişkenleri dışa aktarın (veya env_file ile geçen Docker'ı
kullanın). Python 3.11–3.15 desteklenir; tzdata saat dilimi veritabanını kurar, böylece slim imajlarda da
TZ çalışır.
Önüne TLS sonlandıran herhangi bir vekil koyun; uygulama konteyner içinde 0.0.0.0:8080 dinler, compose onu
loopback'e yayınlar.
triage.example.com {
reverse_proxy 127.0.0.1:8080
}server {
listen 443 ssl;
server_name triage.example.com;
# ssl_certificate ...;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}Sonra:
COOKIE_SECURE=true
FORWARDED_ALLOW_IPS=<vekil adresi veya CIDR>FORWARDED_ALLOW_IPS uvicorn (--proxy-headers) tarafından okunur. Yalnızca vekili yazın: *, her istemcinin
X-Forwarded-For uydurmasına izin verir. Uygulamanın önüne SSO koyacaksanız
SSO proxy kimlik doğrulama sayfasıyla devam edin.
curl -fsS http://127.0.0.1:8080/healthz # liveness: süreç ayakta
curl -fsS http://127.0.0.1:8080/readyz # readiness: açılış ve yapılandırma tamam
curl -fsS http://127.0.0.1:8080/metrics # admin oturumu veya METRICS_TOKEN gerekir-
/healthzWazuh'a hiç dokunmaz; Indexer arızası konteyneri yeniden başlatmamalıdır. -
/readyzde bilinçli olarak Indexer çağrısı yapmaz; böylece kesinti, kesintiyi açıklayan arayüzü ortadan kaldırmaz. - İkisi de kimlik doğrulaması istemez ve probe'lar için güvenlidir.
- İlk giriş
APP_PASSWORDile yapılır; salt okunur rol açıksa giriş sayfasıVIEWER_PASSWORD'dan söz eder.
Ardından:
- Kenar çubuğundan ortamın Raporlar sayfasını açıp Test connections düğmesine basın.
- Run check now ile (veya zamanlamayı bekleyerek) bir raporun oluştuğunu doğrulayın.
- Bir bulguyu onaylayın veya reddedin; Knowledge base sayfasında kararın saklandığını görün.
- Denetim kaydında kararı kontrol edin (
docker compose exec triage tail logs/audit.jsonl). - Ayarlar → Depolama güvenliği bölümünü açın: önek OK olmalı; ISM okuma yetkisi varsa tablo, bir silme politikasının uygulamanın indekslerini silip silmeyeceğini gösterir.
Başarılı açılış; ortamları, zamanlamayı, denetim dosyasını ve güvenlik uyarılarını loglar. Üretimde
app/security.py şu durumlarda açılmayı reddeder: WDT_DEMO=true, eksik veya örnek APP_PASSWORD, eksik
APP_SECRET, VIEWER_PASSWORD'ın admin parolasıyla aynı olması, COOKIE_SECURE=false, bir uç noktada TLS
doğrulamasının kapatılması veya rule_deploy.enabled için kimlik bilgisi eksikliği. İki bilinçli laboratuvar
istisnası için docs/security-exceptions.md.
Ön denetimler, geri dönüşün sınırları ve sürüm notlarıyla birlikte prosedür Yükseltme sayfasındadır.
Uygulama durumsuzdur: raporlar ve bilgi tabanı Wazuh Indexer'daki (daily-triage-*) belgelerdir. Veritabanı
geçişi yoktur.
# Docker Compose (sabitlenmiş etiketle)
docker compose pull
docker compose up -d
docker compose exec triage python -m app.check
# Helm
helm upgrade occultera occultera/occultera \
--version 0.4.1 -f my-values.yaml
helm rollback occultera 1 # gerekirse- İlk açılışta iki indeks oluşturulur:
<önek>-eventsve<önek>-settings.<önek>-*üzerindeki bir indexer rolü bunları kapsar;-runsve-knowledgeadlarını tek tek sayan bir rol kapsamaz. - Nöbet Ayarlar'dan açılana kadar davranış değişmez.
-
SSO (
AUTH_DISABLED=true): kullanıcı başlığı olmayan istekler artık 401 alır. Proxy'ninUSER_HEADERbaşlıklarından birini ilettiğinden emin olun (SSO proxy kimlik doğrulama). -
Helm:
networkPolicy.enabledartıktrue;networkPolicy.ingressNamespacedeğerini ayarlayın. -
Docker Compose: denetim kaydı
./logsyerineauditadlı volume'da. - İlk yedeği alın (Ayarlar → Yedekleme) — hatırlatma yükseltme tarihinden itibaren sayılır.
Yükseltmeden önce CHANGELOG.md okuyun: yapılandırma anahtarları zaman zaman değişir.
Mevcut koşular aranabilir kalır; run_retention_days (YAML) yalnızca eski koşu belgelerini siler, bilgi tabanına
dokunmaz.
En sık kurulum sorunları aşağıdadır; alanlara göre tam liste Sorun giderme sayfasındadır.
| Belirti | Neden ve çözüm |
|---|---|
Konteyner refusing to start in production ile çıkıyor |
Mesaj değişkeni söyler. Gerçek APP_PASSWORD, APP_SECRET, COOKIE_SECURE=true ayarlayın veya TLS doğrulamasını düzeltin. |
FileNotFoundError: no configuration: … does not exist and WAZUH_INDEXER_URL is not set |
Ne YAML dosyası ne de WAZUH_INDEXER_URL var. Demo için: cp .env.demo .env — .env içinde başka bir WDT_DEMO= satırının üstüne eklenen WDT_DEMO=true ezilir (son satır geçerlidir). |
127.0.0.1:8080'de ERR_EMPTY_RESPONSE
|
Konteyner yeniden başlıyor: nedenini docker compose logs triage gösterir (genellikle üstteki satır). |
401 "did not come through the authenticating proxy" |
Kullanıcı başlığı olmadan SSO modu (AUTH_DISABLED=true). Proxy'den X-Forwarded-User / X-authentik-username iletin ya da TRUSTED_PROXIES / PROXY_SECRET ayarını kontrol edin. |
Bir düğmede 403 "cross-origin request refused" |
Tarayıcının Origin değeri uygulamanın gördüğü host değil. WDT_TRUSTED_ORIGINS=https://dis.adresiniz ayarlayın. |
503 "audit trail is not writable" |
Üretim modu denetim kaydı olmadan yazma işlemini reddeder. AUDIT_LOG_FILE yolunu yazılabilir yapın (audit volume'u) ya da AUDIT_STRICT=false. |
| Kırmızı uyarı "… indeksi yoktu" | Bir silme politikası ya da biri uygulama verisini sildi. Ayarlar → Yedekleme → İçe aktar ya da Ayarlar'dan onaylayın. Bkz. Yedekleme. |
| Nöbet hiçbir şey bildirmiyor | Nöbet kapalı, kanal seçili/tanımlı değil, sessiz saatler ya da olay susturulmuş / bilinen gürültü — Nöbet sayfası her olayın durumunu gösterir. |
Vekilden 502, konteyner sağlıklı |
Vekil yanlış porta (8080) ya da hosta gidiyor; docker compose ps kontrol edin. |
Giriş sürekli /login'e dönüyor |
Düz HTTP üzerinde COOKIE_SECURE=true veya vekil çerezleri siliyor. HTTPS kullanın; yerel testte geçici olarak COOKIE_SECURE=false. |
ZoneInfoNotFoundError / bilinmeyen saat dilimi |
TZ'yi IANA adı yapın (Europe/Istanbul) ve tzdata kurulu kalsın. |
| Wazuh'a TLS hatası | CA'yı config/certs/ altına koyup ca_file (veya WAZUH_CA_FILE) ayarlayın; üretimde verify_tls: false kullanmayın. |
| Zamanlanan saatte rapor yok | Konteyner çalışıyor olmalı (zamanlayıcı süreç içinde), schedule.enabled açık olmalı ve saat dilimi TZ ile uyuşmalı. |
| Rapor içinde model hataları |
Test connections çalıştırın; LLM_*, base URL ve token bütçesini (max_tokens) kontrol edin. |
Sonraki: Yapılandırma · SSO proxy kimlik doğrulama · Görüntüleyici modu · MCP sunucusu