Zedmos را از هر جا هدایت کنید.
هر قابلیت Zedmos که رابط کنسول نشان میدهد یک نقطه پایانی REST است. این راهنما دو راه امنی را که یک سیستم راه دور میتواند به آنها برسد پوشش میدهد — کلید API مستقیم، یا پروکسی WebSocket در zedmos-console — بهعلاوه مرجع کامل و دستهبندیشده نقاط پایانی.
API مستقیم، یا پروکسی WebSocket
هر دو مسیر در نهایت به همان کنترلرهای /api/zedmos/* میرسند — فقط انتقال و اعتبارنامهها متفاوت است. برای هر یکپارچهسازی یکی را انتخاب کنید.
- در معرض میگذارد
- خود فایروال OPNsense (وبسرورش). روی pfSense محافظ معادل فقط loopback است — به جایش از پروکسی WebSocket استفاده کنید.
- انتقال
- HTTPS مستقیم به رابط مدیریت فایروال.
- اعتبارنامه
- کلید + راز API در OPNsense (احراز هویت HTTP Basic). pfSense از کلید + راز تولیدشده محلی استفاده میکند که فقط روی loopback پذیرفته میشود.
- محدودسازی دامنه
- یک ACL واحد OPNsense — page-services-zedmos — هر نقطه پایانی را دروازهبانی میکند (خواندن و نوشتن). دامنه فقطخواندنی توکار وجود ندارد. روی pfSense دروازه معادل امتیاز Zedmos ACL است.
- بهترین برای
- شریکی روی بخش قابل اعتماد / VPN سایت به سایت، یا کسی که میتوانید با IP محدودش کنید.
- در معرض میگذارد
- هاب ابری Zedmos (zedmos-backend). فایروال به سمت آن تماس میگیرد.
- انتقال
- فایروال یک تونل خروجی wss:// به هاب باز میکند؛ شریک API REST هاب را فراخوانی میکند.
- اعتبارنامه
- توکن نشست کنسول هاب (Bearer). فایروال با tenant_id + node_id + agent_secret (HMAC) ثبتنام شده است.
- محدودسازی دامنه
- پیشتنظیم فهرست مجاز به ازای هر مسیر روی عامل، بهعلاوه ACL کلید API محلی، بهعلاوه جداسازی مستأجر هاب.
- بهترین برای
- مدیریت SaaS / چندمستأجری، فایروالهای پشت NAT، یا هر چیزی که نباید ورودی در معرض بگذارید.
شروع سریع
روی OPNsense، API مستقیم از کلید + راز API در OPNsense روی HTTP Basic استفاده میکند. فراخوانیهای بدون احراز هویت HTTP 302 (هدایت به ورود) میگیرند، نه 401. فراخوانیهای با کلید API از CSRF معافند. روی pfSense محافظ API محلی فقط loopback است، پس یکپارچهسازیهای راه دور از پروکسی 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 ببرید و پورت مدیریت را با قاعده فایروال به IPهای مبدأ شریک محدود کنید.
برای اشخاص ثالث پروکسی WS را ترجیح دهید
هیچ پورت ورودیای باز نمیکند، دقیقاً محدود میکند شریک چه مسیرهایی را میتواند فراخوانی کند (فهرست مجاز)، مستأجرها را جدا میکند، و مرکزی قابل ابطال است (tombstone امضاشده). کانال توصیهشده برای یکپارچهسازان غیرقابل اعتماد.
توصیه
پروکسی WS برای اشخاص ثالث غیرقابل اعتماد. API مستقیم فقط پشت HTTPS + قاعده فایروال پورت مدیریت محدود به IPهای مبدأ شریک، با یک کاربر سرویس اختصاصی که فقط 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: کاربر نشست، یا loopback/همان میزبان). پیکربندی در notifications.json.
/api/zedmos/reportsنقاط پایانی نمودار فقطخواندنی روی DB جریان. همه در dispatch() به POST وادار میشوند تا رابط بتواند XHR-GET کند؛ با کلید API هر دو متد را فراخوانی کنید. پارامترهای رایج: hours(1-168)، since/until(ms)، mode(session/packet/volume). بیشترشان {labels, values} برمیگردانند.
/api/zedmos/liveفیدهای نزدیک به زمان واقعی. با یک نشانگر since پول کنید (رابط از پولینگ استفاده میکند — روی جعبه WebSocket/SSE نیست). پارامترهای رایج: hours(6)، since(ms)، limit(1000، 10-2000)، بهعلاوه فیلترهای هوشمند (filters_<ep>، sf_*).
/api/zedmos/dashboardKPIهای تجمیعی، تلهمتری سیستم (CPU/دما/دیسک)، وضعیت ویژگیها، و کنترل سرویس / بهروزرسانی.
/api/zedmos/deviceفهرست دستگاهها + چرخه عمر. برای اقدامهای <id> از آرگومانهای مسیر موقعیتی استفاده میکند، مثلاً /device/trust/42.
/api/zedmosکنترلرهای اضافی، خلاصهشده. هر یک همان قرارداد /api/zedmos/<slug>/<command> و همان احراز هویت را دنبال میکند.
مسیر B، به تفصیل
فایروال به سمت هاب تماس میگیرد؛ شریک API REST هاب را فراخوانی میکند که فراخوانی را از طریق سوکت پایین میفرستد. عامل پیش از دست زدن به API محلی فهرست مجاز به ازای هر درخواست را اعمال میکند.
API REST هاب — آنچه شریک فراخوانی میکند
پیشتنظیمهای فهرست مجاز (مرز به ازای هر درخواست)
core-read-only~364 نقطه پایانی GET فقطخواندنی در 24 ماژول. پیشفرض امن.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 در مخزن.