Zedmos کو کہیں سے بھی چلائیں۔
کنسول UI جو بھی Zedmos صلاحیت دکھاتا ہے وہ ایک REST اینڈ پوائنٹ ہے۔ یہ گائیڈ ان دو محفوظ راستوں کا احاطہ کرتی ہے جن سے ایک ریموٹ سسٹم ان تک پہنچ سکتا ہے — براہ راست API کی، یا zedmos-console WebSocket پراکسی — اور ساتھ ایک مکمل، زمرہ وار اینڈ پوائنٹ حوالہ۔
براہ راست API، یا WebSocket پراکسی
دونوں راستے بالآخر وہی /api/zedmos/* کنٹرولرز تک پہنچتے ہیں — صرف ٹرانسپورٹ اور اسناد مختلف ہیں۔ ہر انٹیگریشن کے لیے ایک چنیں۔
- ظاہر کرتا ہے
- خود OPNsense فائر وال (اس کا ویب سرور)۔ pfSense پر مساوی گارڈ صرف لوپ بیک ہے — اس کے بجائے WebSocket پراکسی استعمال کریں۔
- ٹرانسپورٹ
- HTTPS سیدھا فائر وال کے مینجمنٹ انٹرفیس تک۔
- سند
- OPNsense API کی + سیکرٹ (HTTP Basic توثیق)۔ pfSense مقامی طور پر بنی کی + سیکرٹ استعمال کرتا ہے، صرف لوپ بیک پر قبول۔
- اسکوپنگ
- ایک OPNsense ACL — page-services-zedmos — ہر اینڈ پوائنٹ (پڑھنا اور لکھنا) کو گیٹ کرتا ہے۔ کوئی بلٹ ان صرف پڑھنے کا اسکوپ نہیں۔ pfSense پر مساوی گیٹ Zedmos ACL مراعات ہے۔
- بہترین برائے
- قابل اعتماد سیگمنٹ / سائٹ ٹو سائٹ VPN پر پارٹنر، یا جسے آپ IP سے محدود کر سکیں۔
- ظاہر کرتا ہے
- Zedmos کلاؤڈ ہب (zedmos-backend)۔ فائر وال اس کی طرف ڈائل کرتا ہے۔
- ٹرانسپورٹ
- فائر وال ہب کی طرف آؤٹ باؤنڈ wss:// ٹنل کھولتا ہے؛ پارٹنر ہب کا REST API کال کرتا ہے۔
- سند
- ہب کنسول سیشن ٹوکن (Bearer)۔ فائر وال tenant_id + node_id + agent_secret (HMAC) سے اندراج شدہ۔
- اسکوپنگ
- ایجنٹ پر فی راستہ الاؤ لسٹ پری سیٹ، نیز مقامی API کی ACL، نیز ہب کی ٹیننٹ الگ تھلگی۔
- بہترین برائے
- SaaS / ملٹی ٹیننٹ انتظام، NAT کے پیچھے فائر والز، یا کچھ بھی جسے آپ ان باؤنڈ ظاہر نہیں کر سکتے۔
فوری آغاز
OPNsense پر براہ راست API HTTP Basic پر OPNsense API کی + سیکرٹ استعمال کرتا ہے۔ غیر توثیق شدہ کالز کو 401 نہیں بلکہ HTTP 302 (لاگ ان کی طرف ری ڈائریکٹ) ملتا ہے۔ API کی کالز CSRF سے مستثنیٰ ہیں۔ pfSense پر مقامی API گارڈ صرف لوپ بیک ہے، اس لیے ریموٹ انٹیگریشنز WebSocket پراکسی سے گزرتی ہیں۔
# 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}}اسے ظاہر کرنے کا محفوظ ترین طریقہ
ایسی بیرونی کمپنی کے لیے جسے آپ مکمل کنٹرول نہیں کرتے، WebSocket پراکسی کو ترجیح دیں: کوئی ان باؤنڈ پورٹ نہیں، فی راستہ الاؤ لسٹ، ٹیننٹ الگ تھلگ، مرکزی منسوخی۔ براہ راست API صرف قابل اعتماد سیگمنٹ / VPN پر، ہمیشہ سخت کر کے استعمال کریں۔
ایک ACL سب کچھ گیٹ کرتا ہے
page-services-zedmos ہر /api/zedmos/* اینڈ پوائنٹ کو ڈھانپتا ہے، پڑھنا اور لکھنا۔ فی اینڈ پوائنٹ یا صرف پڑھنے کی کوئی Zedmos مراعات نہیں۔ پارٹنر کو نیٹ ورک اصولوں یا WS پراکسی الاؤ لسٹ سے محدود کریں۔
API کیز CSRF بائی پاس کرتی ہیں
API کی کالز اینٹی CSRF ٹوکن سے مستثنیٰ ہیں (صرف براؤزر سیشنز کو غیر GET پر اس کی ضرورت ہے)۔ کچھ اینڈ پوائنٹس GET پر بھی بغیر میتھڈ گارڈ تبدیلی کرتے ہیں — کیز کے لیے ٹھیک، مگر ظاہر کرنے پر ریورس پراکسی پر میتھڈز محدود کریں۔
ہمیشہ HTTPS، ہمیشہ IP محدود
API تمام انٹرفیسز پر بائنڈ ہوتا ہے (لیب پر *:80)۔ ریموٹ استعمال کے لیے WebGUI کو درست سرٹیفکیٹ کے ساتھ HTTPS پر لے جائیں اور مینجمنٹ پورٹ کو فائر وال اصول سے پارٹنر کے سورس IPs تک محدود کریں۔
فریقِ ثالث کے لیے WS پراکسی کو ترجیح دیں
یہ کوئی ان باؤنڈ پورٹ نہیں کھولتا، بالکل طے کرتا ہے پارٹنر کون سے راستے کال کر سکتا ہے (الاؤ لسٹ)، ٹیننٹس الگ رکھتا ہے، اور مرکزی طور پر منسوخ ہو سکتا ہے (دستخط شدہ tombstone)۔ غیر قابل اعتماد انٹیگریٹرز کے لیے تجویز کردہ چینل۔
سفارش
غیر قابل اعتماد فریقِ ثالث کے لیے WS پراکسی۔ براہ راست API صرف HTTPS + پارٹنر کے سورس IPs تک محدود مینجمنٹ پورٹ فائر وال اصول کے پیچھے، ایک مخصوص سروس یوزر کے ساتھ جس کے پاس صرف page-services-zedmos ہو۔
The policies.json schema
Every key the partner can read via /policies/get and write via /policies/groupsave or /policies/save. Schema 1.1.0. Allowed values and defaults are taken from the document's own built-in docs.
دستاویز کا ڈھانچہ
eval — جانچ کی ترتیب
evalgroups[] — پالیسی گروپ آبجیکٹ
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 — ڈیفالٹس، کیٹلاگ، انجن نوبز
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"] }
]
}ہر زمرہ
بالکل کنسول کی طرح گروپ کیا گیا: پہلے پالیسیاں، پھر سیٹنگز، نوٹیفکیشنز، رپورٹس، لائیو اور باقی۔ راستے ہر زمرے کی بنیاد کے نسبتی ہیں۔
/api/zedmos/policiesفلیگ شپ سطح۔ policies.json چلاتا ہے — گروپس، گلوبلز، سیکیورٹی کیٹلاگ، ایپ زمرے، DLP پری سیٹس اور تھریٹ انٹیل۔
/api/zedmos/settingsسب سے بڑی سطح (~62 ایکشنز): TLS/CA، انٹرفیسز اور ورکرز، IDS/ETA/TI، writerd اور اسٹوریج، AD/آئیڈنٹٹی، کلاؤڈ کنسول، ڈیوائس شناخت اور ٹریفک کنٹرول۔
/api/zedmos/notificationsالرٹ فیڈ + ڈسپیچر۔ واحد کنٹرولر جس کا اپنا اجازت گیٹ ہے (canModify: سیشن یوزر، یا لوپ بیک/سیم ہوسٹ)۔ کنفیگ notifications.json میں۔
/api/zedmos/reportsفلو DB پر صرف پڑھنے والے چارٹ اینڈ پوائنٹس۔ سب dispatch() میں POST پر مجبور تاکہ UI انہیں XHR-GET کر سکے؛ API کی کے ساتھ کوئی بھی میتھڈ کال کریں۔ عام پیرامیٹرز: hours(1-168)، since/until(ms)، mode(session/packet/volume)۔ زیادہ تر {labels, values} لوٹاتے ہیں۔
/api/zedmos/liveتقریباً حقیقی وقت کی فیڈز۔ since کرسر سے پول کریں (UI پولنگ استعمال کرتا ہے — باکس پر WebSocket/SSE نہیں)۔ عام پیرامیٹرز: hours(6)، since(ms)، limit(1000، 10-2000)، نیز اسمارٹ فلٹرز (filters_<ep>، sf_*)۔
/api/zedmos/dashboardمجموعی KPIs، سسٹم ٹیلی میٹری (CPU/درجہ حرارت/ڈسک)، فیچر حالت، اور سروس / اپ ڈیٹ کنٹرول۔
/api/zedmos/deviceڈیوائس انوینٹری + لائف سائیکل۔ <id> ایکشنز کے لیے پوزیشنل پاتھ آرگومنٹس، مثلاً /device/trust/42۔
/api/zedmosاضافی کنٹرولرز، خلاصہ۔ ہر ایک وہی /api/zedmos/<slug>/<command> کنونشن اور وہی توثیق استعمال کرتا ہے۔
راستہ B، تفصیل سے
فائر وال ہب کی طرف ڈائل کرتا ہے؛ پارٹنر ہب کا REST API کال کرتا ہے، جو کال کو ساکٹ کے ذریعے نیچے پہنچاتا ہے۔ ایجنٹ مقامی API کو چھونے سے پہلے فی درخواست الاؤ لسٹ نافذ کرتا ہے۔
ہب REST API — پارٹنر کیا کال کرتا ہے
الاؤ لسٹ پری سیٹس (فی درخواست حد)
core-read-only24 ماڈیولز میں ~364 صرف پڑھنے والے GET اینڈ پوائنٹس۔ محفوظ ڈیفالٹ۔firewall-adminمکمل پڑھنا+لکھنا firewall/* + صرف پڑھنا core/diag/interfaces۔network-adminمکمل interfaces/*، routes/*، routing/* + صرف پڑھنا core/diag۔vpn-adminمکمل ipsec/*، openvpn/*، wireguard/* (ڈسک پر؛ custom کے ذریعے چنیں)۔ids-monitorمکمل ids/* + صرف پڑھنا core/diag (ڈسک پر؛ custom کے ذریعے چنیں)۔full-adminسب کچھ، ہر ماڈیول۔ "بائی پاس کے مساوی۔" پارٹنرز کو نہ دیں۔بھیجے گئے پری سیٹس میں سے کوئی بھی /api/zedmos/* شامل نہیں کرتا۔ پالیسیوں کی انٹیگریشن کے لیے کسٹم الاؤ لسٹ استعمال کریں:
# 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/*پیغام پروٹوکول (حوالہ)
ہب ← ایجنٹ: {"type":"http","requestId","method","url","body","timeoutMs"}\nایجنٹ ← ہب: {"type":"httpResponse","requestId","status","body","error"}\nہینڈشیک: ہب ایک چیلنج nonce بھیجتا ہے؛ ایجنٹ HMAC-SHA256(agent_secret, "tenant|node|ts|nonce") سے جواب دیتا ہے؛ ہب hello_ack سے جواب دیتا ہے۔ منسوخی دستخط شدہ tombstone کے ذریعے۔ہر اینڈ پوائنٹ اور پیرامیٹر کے ساتھ مکمل تحریری حوالہ: ریپو میں docs/ZEDMOS_API_REFERENCE.md۔