Zedmos'u her yerden sürün.
Konsol arayüzünün sunduğu her Zedmos yeteneği bir REST uç noktasıdır. Bu kılavuz, uzak bir sistemin onlara ulaşmasının iki güvenli yolunu — doğrudan bir API anahtarı ya da zedmos-console WebSocket vekili — ve eksiksiz, kategorili bir uç nokta başvurusunu kapsar.
Doğrudan API ya da WebSocket vekili
İki yol da sonunda aynı /api/zedmos/* denetleyicilerine ulaşır — yalnızca taşıma ve kimlik bilgileri değişir. Tümleştirme başına birini seçin.
- Açtığı
- OPNsense güvenlik duvarının kendisi (kendi web sunucusu). pfSense'te eşdeğer koruma yalnızca geri döngüdedir — onun yerine WebSocket vekilini kullanın.
- Taşıma
- Doğrudan güvenlik duvarının yönetim arayüzüne HTTPS.
- Kimlik bilgisi
- OPNsense API anahtarı + gizli anahtarı (HTTP Basic kimlik doğrulama). pfSense, yalnızca geri döngüde kabul edilen, yerel olarak üretilmiş bir anahtar + gizli anahtar kullanır.
- Kapsamlama
- Tek bir OPNsense ACL'i — page-services-zedmos — her uç noktayı (hem okuma HEM yazma) denetler. Yerleşik salt okunur kapsam yoktur. pfSense'te eşdeğer kapı, Zedmos ACL yetkisidir.
- Şunun için en iyi
- Güvenilir bir segmentte / şubeler arası VPN'de olan ya da IP ile kısıtlayabileceğiniz bir iş ortağı.
- Açtığı
- Zedmos bulut merkezi (zedmos-backend). Güvenlik duvarı ona dışarı doğru bağlanır.
- Taşıma
- Güvenlik duvarı merkeze giden bir wss:// tüneli açar; iş ortağı merkezin REST API'sini çağırır.
- Kimlik bilgisi
- Merkez konsol oturum jetonu (Bearer). Güvenlik duvarı tenant_id + node_id + agent_secret (HMAC) ile kaydedilir.
- Kapsamlama
- Aracıdaki yol başına izin listesi, ARTI yerel API anahtarı ACL'i, ARTI merkezin kiracı yalıtımı.
- Şunun için en iyi
- SaaS / çok kiracılı yönetim, NAT arkasındaki güvenlik duvarları ya da gelen bağlantıya açmamanız gereken her şey.
Hızlı başlangıç
OPNsense'te doğrudan API, HTTP Basic üzerinden bir OPNsense API anahtarı + gizli anahtarı kullanır. Kimliksiz çağrılar 401 değil, HTTP 302 (oturum açmaya yönlendirme) alır. API anahtarlı çağrılar CSRF'den muaftır. pfSense'te yerel API koruması yalnızca geri döngüdedir, bu yüzden uzak tümleştirmeler WebSocket vekilinden geçer.
# OPNsense only - on pfSense use the WebSocket-proxy example below
# 1) Create an API key in OPNsense: System > Access > Users > API keys
# The user must hold the "Services: Zedmos" privilege (page-services-zedmos).
KEY='....' # OPNsense API key
SECRET='....' # OPNsense API secret
# Read — list policy groups
curl -s -u "$KEY:$SECRET" \
https://fw.example.com/api/zedmos/policies/groups
# -> {"groups":[{"name":"Default","status":true}, ...]}
# Write — block a domain globally (POST, JSON body)
curl -s -u "$KEY:$SECRET" -H 'Content-Type: application/json' \
-d '{"type":"host","value":"badsite.com","global":true}' \
https://fw.example.com/api/zedmos/policies/block
# -> {"status":"ok"}const base = "https://fw.example.com";
const auth =
"Basic " + Buffer.from(`${process.env.ZED_KEY}:${process.env.ZED_SECRET}`).toString("base64");
async function zed(path, { method = "GET", body } = {}) {
const r = await fetch(`${base}/api/zedmos${path}`, {
method,
headers: { Authorization: auth, ...(body ? { "Content-Type": "application/json" } : {}) },
body: body ? JSON.stringify(body) : undefined,
});
if (r.status === 302) throw new Error("auth failed (redirect to login)");
return r.json();
}
const groups = await zed("/policies/groups");
await zed("/policies/block", {
method: "POST",
body: { type: "category", value: "AdultContent", group: "Strict" },
});# The partner never talks to the firewall directly — it calls the hub,
# which routes the call down the firewall's outbound socket.
curl -s -X POST https://www.zedmos.com/api/agent/proxy/http \
-H "Authorization: Bearer $CONSOLE_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"tenant_id": "69fb...",
"node_id": "6a0d...",
"method": "GET",
"url": "/api/zedmos/policies/groups"
}'
# -> {"status":"ok","response":{"status":200,"body":"{\"groups\":[...]}","error":null}}Bunu açmanın en güvenli yolu
Tümüyle denetlemediğiniz dış bir şirket için WebSocket vekilini yeğleyin: gelen port yok, yol başına izin listesi, kiracı yalıtımı, merkezî iptal. Doğrudan API'yi yalnızca güvenilir bir segmentte / VPN'de ve her zaman sertleştirilmiş olarak kullanın.
Her şeyi tek bir ACL denetler
page-services-zedmos, her /api/zedmos/* uç noktasını okuma ve yazma olarak kapsar. Uç nokta başına ya da salt okunur bir Zedmos yetkisi yoktur. Bir iş ortağını onun yerine ağ kurallarıyla ya da WS vekili izin listesiyle kapsamlayın.
API anahtarları CSRF'yi atlar
API anahtarlı çağrılar CSRF karşıtı jetondan muaftır (yalnızca tarayıcı oturumlarının GET dışı isteklerde buna ihtiyacı vardır). Bazı uç noktalar ayrıca yöntem koruması olmadan GET'te değişiklik yapar — anahtarlar için sorun değil, ama dışarı açıyorsanız yöntemleri bir ters vekilde kilitleyin.
Her zaman HTTPS, her zaman IP kısıtlı
API tüm arayüzlere bağlanır (laboratuvarda *:80). Uzaktan kullanım için web arayüzünü geçerli bir sertifikayla HTTPS'e geçirin ve yönetim portunu güvenlik duvarı kuralıyla iş ortağının kaynak IP'leriyle sınırlayın.
Üçüncü taraflar için WS vekilini yeğleyin
Hiçbir gelen port açmaz, iş ortağının çağırabileceği yolları tam olarak kısıtlar (izin listesi), kiracıları yalıtır ve merkezden iptal edilebilir (imzalı mezar taşı). Güvenilmeyen tümleştiriciler için önerilen kanal.
Öneri
Güvenilmeyen üçüncü taraflar için WS vekili. Doğrudan API yalnızca HTTPS'in ardında ve iş ortağının kaynak IP'leriyle sınırlanmış bir yönetim portu kuralıyla, yalnızca page-services-zedmos yetkisini taşıyan ayrı bir hizmet kullanıcısıyla.
policies.json şeması
İş ortağının /policies/get ile okuyabileceği ve /policies/groupsave ya da /policies/save ile yazabileceği her anahtar. Şema 1.1.0. İzin verilen değerler ve varsayılanlar, belgenin kendi yerleşik belgelerinden alınmıştır.
Belge yapısı
eval — değerlendirme sırası
evalgroups[] — politika grubu nesnesi
Identity
groups[]Selectors — who the group applies to
groups[].selectorsA flow joins this group when its selectors match. Empty arrays = no constraint on that axis.
Overrides
groups[].overridesExclusions
groups[].exclusionsAllow-list overrides that exempt matching traffic from this group's blocks.
Security catalogs (threat categories)
groups[].securityEach boolean enables blocking of one threat-intel catalog. basic_mode/advanced_mode are convenience presets; the `essential{}` and `advanced{}` objects mirror the flat booleans.
Application control (L7 app-ID)
groups[].appsEncrypted-transport control
groups[].transportFirst-install default: all 'allow'. Switch to 'block' to enforce.
TLS inspection (MITM)
groups[].tlsNetwork (L3/L4) blocks
groups[].networkHard early-drops via fast-reject before rules[] runs. Use a rule with is_exception+action:allow to punch a hole.
Web filtering
groups[].webAI Security & DLP
groups[].web.dlpPer-group only — globals.web.dlp is a TEMPLATE the engine ignores. First-install default: OFF.
File / AV scanning
groups[].file.scanDNS control
groups[].dnsETA · Identity · Geo · Risk · TI · IDS
groups[].{eta,identity,geo,risk,ti,ids}Action handlers
groups[].actionsConfigured at group level; a rule references them via its `action`. Most fire only on a DROP-class decision (pair with action:drop). Placeholders $src, $dst, $rule_id.
App Routing
groups[].routingRules (ordered, fine-grained)
groups[].rules[]Optional per-group ordered rule list evaluated after early-drops. Each rule matches on fields and fires one action.
// POST /api/zedmos/policies/groupsave — Content-Type: application/json
// Upsert one group (only the keys you send are changed; rest is preserved).
{
"name": "Strict",
"status": true,
"description": "Locked-down VLAN",
"selectors": { "vlans": [30], "direction": "any" },
"overrides": { "block_all": false, "block_untrusted": true, "schedule": "work-hours" },
"security": { "basic_mode": "high", "malware_virus": true, "phishing": true },
"apps": { "categories_block": ["adultcontent", "gaming"] },
"transport":{ "quic_strategy": "block", "doh_strategy": "block" },
"tls": { "enable_inspection": true, "bump_mode": "force", "min_version": "1.2" },
"dns": { "block_domains": ["coin-hive.com"], "dga": "block", "tunnel": "block" },
"web": { "dlp": { "enable": true, "mode": "regex_only", "action": "block",
"presets": ["cc_luhn","iban","email_pii"] } },
"file": { "scan": { "mode": "block", "action": "block", "engines": ["clamav"] } },
"ids": { "mode": "prevent", "block_max_priority": 2 },
"rules": [
{ "is_exception": true, "action": "allow", "mode": "any",
"dst_domain": ["intranet.corp"], "comment": "always allow intranet" }
]
}globals — varsayılanlar, kataloglar, motor ayarları
Engine knob registry
globals.engineOperator-tunable hot-path knobs. Precedence: value here > env DG_* > hardcoded default. Atomic publish on policy reload.
Global catalogs & defaults
globals.{security,ti,quarantine,schedules,exclusions}// POST /api/zedmos/policies/globals — set global blacklists / actions
{
"exclusions": { "domains": ["windowsupdate.com"], "src_cidrs": ["10.0.0.0/8"] },
"ti": { "domain_block": ["evil.example"], "ip_block": ["203.0.113.7"] },
"schedules": [
{ "name": "work-hours", "start": "08:00", "end": "18:00",
"days": ["Mon","Tue","Wed","Thu","Fri"] }
]
}Her kategori
Tam konsoldaki gibi gruplanmış: önce Politikalar, sonra Ayarlar, Bildirimler, Raporlar, Canlı ve gerisi. Yollar her kategorinin tabanına görelidir.
/api/zedmos/policiesAmiral gemisi yüzey. policies.json'u sürer — gruplar, genel ayarlar, güvenlik kataloğu, uygulama kategorileri, DLP hazır kümeleri ve tehdit istihbaratı.
/api/zedmos/settingsEn büyük yüzey (~62 eylem): TLS/CA, arayüzler ve iş süreçleri, IDS/ETA/TI, writerd ve depolama, AD/kimlik, bulut konsolu, cihaz tanıma ve trafik denetimi.
/api/zedmos/notificationsUyarı akışı + dağıtıcı. Kendi yetkilendirme kapısı olan tek denetleyici (canModify: oturum kullanıcısı ya da geri döngü/aynı sunucu). Yapılandırma notifications.json içinde.
/api/zedmos/reportsAkış veritabanı üzerinde salt okunur grafik uç noktaları. Arayüz XHR-GET yapabilsin diye hepsi dispatch() içinde POST'a zorlanır; API anahtarıyla iki yöntemle de çağırabilirsiniz. Ortak parametreler: hours(1-168), since/until(ms), mode(session/packet/volume). Çoğu {labels, values} döner.
/api/zedmos/liveNeredeyse gerçek zamanlı akışlar. Bir since imleciyle yoklayın (arayüz yoklama kullanır — kutuda WebSocket/SSE yoktur). Ortak parametreler: hours(6), since(ms), limit(1000, 10-2000), ayrıca akıllı süzgeçler (filters_<ep>, sf_*).
/api/zedmos/dashboardToplu başarım göstergeleri, sistem telemetrisi (CPU/sıcaklık/disk), özellik durumu ve servis / güncelleme denetimi.
/api/zedmos/deviceCihaz envanteri + yaşam döngüsü. <id> eylemleri için konumsal yol argümanları kullanır, örneğin /device/trust/42.
/api/zedmosEk denetleyiciler, özetlenmiş. Her biri aynı /api/zedmos/<slug>/<command> düzenini ve aynı kimlik doğrulamayı izler.
B yolu, ayrıntılı
Güvenlik duvarı merkeze dışarı doğru bağlanır; iş ortağı merkezin REST API'sini çağırır, o da çağrıyı soketten aşağı aktarır. Aracı, yerel API'ye dokunmadan önce istek başına bir izin listesi uygular.
Merkez REST API — iş ortağının çağırdığı
İzin listesi hazır kümeleri (istek başına sınır)
core-read-only24 modülde ~364 salt okunur GET uç noktası. Güvenli varsayılan.firewall-adminTam okuma+yazma firewall/* + salt okunur core/diag/interfaces.network-adminTam interfaces/*, routes/*, routing/* + salt okunur core/diag.vpn-adminTam ipsec/*, openvpn/*, wireguard/* (diskte; özel üzerinden seçilir).ids-monitorTam ids/* + salt okunur core/diag (diskte; özel üzerinden seçilir).full-adminHer şey, her modül. "Atlatmaya eşdeğer." İş ortaklarına vermeyin.Gelen hazır kümelerin hiçbiri /api/zedmos/* içermez. Bir politika tümleştirmesi için özel bir izin listesi kullanın:
# Custom allowlist for a policies integration (config.json patterns / preset=custom)
/api/zedmos/policies/*
/api/zedmos/settings/*
# optional read-only telemetry
/api/zedmos/dashboard/*
/api/zedmos/live/*
/api/zedmos/reports/*İleti protokolü (başvuru)
Hub → agent: {"type":"http","requestId","method","url","body","timeoutMs"}
Agent → hub: {"type":"httpResponse","requestId","status","body","error"}
El sıkışma: merkez bir meydan okuma nonce'u gönderir; aracı HMAC-SHA256(agent_secret, "tenant|node|ts|nonce") ile yanıtlar; merkez hello_ack döner. İptal, imzalı bir mezar taşıyla.Her uç nokta ve parametreyle eksiksiz metin başvurusu: depoda docs/ZEDMOS_API_REFERENCE.md.