r3v3rs3'ü script ile yönetme

WebUI'da, WebUI'ın kendisinin kullanmadığı hiçbir düğme yoktur. Yaptığı her şey /api altındaki yönetim API'si üzerinden gider, yani bir script de aynısını yapabilir. Bu rehber giriş yapar, port ve proxy oluşturur, durum bilgisini okur, deploy işinden sonra cache temizler ve o işten başka hiçbir şey yapamayan bir hesap verir.

Örnekler curl ile http://localhost:46492 adresine gider. Bu, yönetim panelinin varsayılan adresidir.

Adım 1: Giriş yapın

POST /api/login bir oturum cookie'si döner:

$ curl -s -c cookies.txt \
    -H 'Content-Type: application/json' \
    -d '{"username":"admin","method":"password","password":"passw0rd"}' \
    http://localhost:46492/api/login
"success"

Yanıt cookie'yi taşır:

set-cookie: token=QWZ1uBQz5A9gAnmK2b18EZ7tD7CpkJ9I; HttpOnly; SameSite=Strict

Sunucu Secure özelliğini HTTPS bağlantılarında ve güvenilen ters proxy'lerde otomatik olarak ekler, yerel loopback HTTP bağlantılarında ise kapalı tutar.

TOTP'si olan bir hesapta ilk yanıt "totp_required" olur. Kodu, ilk isteğin cookie'si ile ikinci bir istekte gönderin:

$ curl -s -b cookies.txt -c cookies.txt \
    -H 'Content-Type: application/json' \
    -d '{"username":"admin","method":"totp","token":"123456"}' \
    http://localhost:46492/api/login
"success"

Diğer her endpoint bu cookie'yi ister:

$ curl -s -b cookies.txt http://localhost:46492/api/ports
[{"id":"dpv-ylj","name":"web","listen":"/ip4/127.0.0.1/tcp/8473/http"}]
$ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:46492/api/ports
401

Yanlış parola 400 döner:

{"message":"invalid login credentials","error":{"message":"invalid_login_credentials"}}

Aynı IP adresinden yapılan ardışık hatalı giriş denemeleri, kullanıcı adından bağımsız olarak geçici brute-force engellemesini (fail2ban benzeri katman) tetikler (429 ip_banned döner). Yöneticiler aktif engelleri GET /api/banned-ips ve DELETE /api/banned-ips/{ip} uç noktalarından veya Ayarlar sayfasındaki "Engellenen IP Adresleri" kartından inceleyip kaldırabilir.

GET /api/session kim olduğunuzu söyler, POST /api/logout oturumu bitirir. Çıkıştan sonra cookie işe yaramaz:

$ curl -s -b cookies.txt http://localhost:46492/api/session
{"username":"admin","role":"admin","cert_expiry_warning":"14days"}

Oturumlar bellekte tutulur. r3v3rs3 yeniden başlayınca her oturum biter, bu yüzden uzun süre çalışan bir script 401 alınca yeniden giriş yapmalıdır.

Adım 2: API dokümanını okuyun

r3v3rs3 OpenAPI dokümanını sunucu kodundan üretir, yani doküman her zaman çalışan sürümü anlatır:

• OpenAPI dokümanı: http://localhost:46492/api/openapi.json
• Swagger UI: http://localhost:46492/api/docs/

İkisi de oturum cookie'si ister. WebUI'a giriş yaptığınız tarayıcıda açın; WebUI'ın alt kısmındaki API bağlantısı Swagger UI'ı açar.

$ curl -s -b cookies.txt http://localhost:46492/api/openapi.json | jq '.info.version, (.paths | length)'
"2.6.7"
201

Dokümanı bir istemci üretmek için veya bir endpoint'in gövdesini tahmin etmek yerine görmek için kullanın.

Adım 3: Port oluşturun

Port bir ad ve bir multiaddr alır:

$ curl -s -b cookies.txt -X POST http://localhost:46492/api/ports \
    -H 'Content-Type: application/json' \
    -d '{"name":"api-demo","listen":"/ip4/127.0.0.1/tcp/8475/http"}'
null

null başarılı yanıtın gövdesidir. Id'yi listeden okuyun:

$ curl -s -b cookies.txt http://localhost:46492/api/ports | jq -r '.[] | select(.name=="api-demo") | .id'
smc-gzh

Id'yi r3v3rs3 üretir. Elle id yazmayın: var olmayan bir id ile yapılan PUT isteği 404 id_not_found döner.

PUT /api/ports/{id} bir portu değiştirir, DELETE /api/ports/{id} siler, GET /api/ports/{id}/status socket'in dinleyip dinlemediğini söyler.

Adım 4: Proxy oluşturun

Proxy; çalıştığı portları, protokolünü ve route'larını taşır:

$ curl -s -b cookies.txt -X POST http://localhost:46492/api/proxies \
    -H 'Content-Type: application/json' \
    -d '{
      "name": "api-demo-app",
      "ports": ["smc-gzh"],
      "protocol": "http",
      "vhosts": ["demo.example.com"],
      "routes": [{ "path": "/", "servers": [{ "url": "http://127.0.0.1:9000/" }] }]
    }'
null

Proxy yeniden başlatma olmadan, hemen yanıt verir:

$ curl -s -o /dev/null -w '%{http_code}\n' -H 'Host: demo.example.com' http://127.0.0.1:8475/
200

protocol alanı proxy türünü seçer: http, tcp veya udp. TCP ve UDP proxy'de routes yerine upstream_servers bulunur.

GET /api/proxies/{id}/status upstream sunucuları gösterir:

$ curl -s -b cookies.txt http://localhost:46492/api/proxies/jzr-pgf/status
{"state":"active","upstreams":[{"addr":"http://127.0.0.1:9000/","weight":1,"healthy":true,"failures":0}]}

Adım 5: Deploy sonrası cache'i temizleyin

Statik dosyaları değiştiren bir deploy, HTTP cache'inde eski gövdeler bırakır. Tek bir çağrı bir proxy'nin cache'ini temizler:

$ curl -s -b cookies.txt -X DELETE http://localhost:46492/api/proxies/jzr-pgf/cache
null

Deploy işinin tamamı üç satırdır:

#!/bin/sh
set -eu
curl -sf -c "$PWD/j.txt" -H 'Content-Type: application/json' \
  -d "{\"username\":\"$R3_USER\",\"method\":\"password\",\"password\":\"$R3_PASS\"}" \
  "$R3_URL/api/login" > /dev/null
curl -sf -b "$PWD/j.txt" -X DELETE "$R3_URL/api/proxies/$R3_PROXY/cache" > /dev/null
curl -sf -b "$PWD/j.txt" -X POST "$R3_URL/api/logout" > /dev/null

Parolayı CI'ın secret deposunda tutun, repository'de değil. -f seçeneği, 4xx veya 5xx durum kodunda curl'ün işi başarısız yapmasını sağlar.

Adım 6: İşe kendi hesabını verin

Deploy işine admin parolasını vermeyin. İşin ihtiyacı olan role sahip bir hesap oluşturun:

$ curl -s -b cookies.txt -X POST http://localhost:46492/api/accounts \
    -H 'Content-Type: application/json' \
    -d '{"username":"ci","password":"uzun-bir-parola","role":"editor"}'

Üç rol vardır:

viewer rolü proxy listesini okur, ama hiçbir şeyi değiştiremez. viewer.txt dosyasında bir viewer hesabının cookie'si ile:

$ curl -s -b viewer.txt -X DELETE http://localhost:46492/api/proxies/jzr-pgf/cache
{"message":"the role of the account does not allow this action","error":{"message":"forbidden"}}

Bu istek 403 döner. Cache temizleme en az editor rolü ister. editor rolü denetim kaydını ve hesapları okuyamaz, ikisi de 403 döner. Hesap başına proxy listesi ve TOTP için Hesaplar sayfasına bakın.

Adım 7: Denetim kaydını okuyun

WebUI veya API üzerinden yapılan her değişiklik kaydedilir. Kaydı yalnız admin hesabı okuyabilir:

$ curl -s -b cookies.txt 'http://localhost:46492/api/audit?limit=5' | jq -c '.[]'
{"time":1789647517635,"username":"admin","client":"127.0.0.1","action":"purge_proxy_cache","resource_id":"jzr-pgf"}
{"time":1789647512463,"username":"admin","client":"127.0.0.1","action":"add_proxy","resource_id":"jzr-pgf","summary":"api-demo-app"}
{"time":1789647508125,"username":"admin","client":"127.0.0.1","action":"add_port","resource_id":"smc-gzh","summary":"api-demo /ip4/127.0.0.1/tcp/8475/http"}
{"time":1789647489459,"username":"admin","client":"127.0.0.1","action":"login"}

time alanı Unix epoch'tan bu yana milisaniyedir. Özet hiçbir zaman parola, token veya key taşımaz. Sorgu parametreleri için Denetim kaydı bölümüne bakın.

Adım 8: Değişiklikleri izleyin

GET /api/events, WebUI'ın kendini yenilemek için kullandığı bir server-sent event stream'idir. Her değişiklik bir satır gönderir:

$ curl -N -b cookies.txt http://localhost:46492/api/events
data: {"event":"proxies_updated","entries":[...]}

data: {"event":"proxy_status_updated","id":"pdb-khh","status":{"state":"active"}}

data: {"event":"port_table_updated","entries":[...]}

data: {"event":"port_status_updated","id":"dpv-ylj","status":{"state":{"socket":"listening","tls":null}}}

Durum endpoint'lerini döngüde sormak yerine bir izleme paneli veya alarm için bunu kullanın.

Referans

• Yönetim API'si: doküman adresi ve giriş.
• Denetim kaydı: alanlar ve saklama süresi.
• Hesaplar: roller, proxy listeleri ve TOTP.

Sonraki adımlar

• Yük dengeleme ve sağlık kontrolü: durum endpoint'inin kullanımı.
• Cache ve sıkıştırma: cache temizlemenin neyi sildiği.