Zedmos
ڈویلپرز · API

Zedmos کو کہیں سے بھی چلائیں۔

کنسول UI جو بھی Zedmos صلاحیت دکھاتا ہے وہ ایک REST اینڈ پوائنٹ ہے۔ یہ گائیڈ ان دو محفوظ راستوں کا احاطہ کرتی ہے جن سے ایک ریموٹ سسٹم ان تک پہنچ سکتا ہے — براہ راست API کی، یا zedmos-console WebSocket پراکسی — اور ساتھ ایک مکمل، زمرہ وار اینڈ پوائنٹ حوالہ۔

OPNsense 26.1pfSense CE 2.8REST + WSSلیب پر تصدیق شدہ
اندر جانے کے دو راستے

براہ راست API، یا WebSocket پراکسی

دونوں راستے بالآخر وہی /api/zedmos/* کنٹرولرز تک پہنچتے ہیں — صرف ٹرانسپورٹ اور اسناد مختلف ہیں۔ ہر انٹیگریشن کے لیے ایک چنیں۔

Aبراہ راست REST API
ظاہر کرتا ہے
خود OPNsense فائر وال (اس کا ویب سرور)۔ pfSense پر مساوی گارڈ صرف لوپ بیک ہے — اس کے بجائے WebSocket پراکسی استعمال کریں۔
ٹرانسپورٹ
HTTPS سیدھا فائر وال کے مینجمنٹ انٹرفیس تک۔
سند
OPNsense API کی + سیکرٹ (HTTP Basic توثیق)۔ pfSense مقامی طور پر بنی کی + سیکرٹ استعمال کرتا ہے، صرف لوپ بیک پر قبول۔
اسکوپنگ
ایک OPNsense ACL — page-services-zedmos — ہر اینڈ پوائنٹ (پڑھنا اور لکھنا) کو گیٹ کرتا ہے۔ کوئی بلٹ ان صرف پڑھنے کا اسکوپ نہیں۔ pfSense پر مساوی گیٹ Zedmos ACL مراعات ہے۔
بہترین برائے
قابل اعتماد سیگمنٹ / سائٹ ٹو سائٹ VPN پر پارٹنر، یا جسے آپ IP سے محدود کر سکیں۔
https://<firewall>/api/zedmos/...
BWebSocket پراکسی (zedmos-console)
ظاہر کرتا ہے
Zedmos کلاؤڈ ہب (zedmos-backend)۔ فائر وال اس کی طرف ڈائل کرتا ہے۔
ٹرانسپورٹ
فائر وال ہب کی طرف آؤٹ باؤنڈ wss:// ٹنل کھولتا ہے؛ پارٹنر ہب کا REST API کال کرتا ہے۔
سند
ہب کنسول سیشن ٹوکن (Bearer)۔ فائر وال tenant_id + node_id + agent_secret (HMAC) سے اندراج شدہ۔
اسکوپنگ
ایجنٹ پر فی راستہ الاؤ لسٹ پری سیٹ، نیز مقامی API کی ACL، نیز ہب کی ٹیننٹ الگ تھلگی۔
بہترین برائے
SaaS / ملٹی ٹیننٹ انتظام، NAT کے پیچھے فائر والز، یا کچھ بھی جسے آپ ان باؤنڈ ظاہر نہیں کر سکتے۔
POST https://<hub>/api/agent/proxy/http → { url: "/api/zedmos/..." }
توثیق

فوری آغاز

OPNsense پر براہ راست API HTTP Basic پر OPNsense API کی + سیکرٹ استعمال کرتا ہے۔ غیر توثیق شدہ کالز کو 401 نہیں بلکہ HTTP 302 (لاگ ان کی طرف ری ڈائریکٹ) ملتا ہے۔ API کی کالز CSRF سے مستثنیٰ ہیں۔ pfSense پر مقامی API گارڈ صرف لوپ بیک ہے، اس لیے ریموٹ انٹیگریشنز WebSocket پراکسی سے گزرتی ہیں۔

براہ راست REST API — curlbash
# 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"}
براہ راست REST API — Node.jsts
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" },
});
ہب WebSocket پراکسی کے ذریعے — curlbash
# 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 ہو۔

POLICIES.JSON · FIELDS

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.

دستاویز کا ڈھانچہ

Field
Type
Values / default
Description
schema_version
string
1.x | 2.x= 1.1.0
Document schema version. Engine rejects an unsupported major; bump only after the engine understands it.
updated_at
string
ISO-8601 timestamp of the last write (set by the API/UI).
source
string
Origin tag of the document (e.g. ui, console, import).
eval
object
Global evaluation controls — group ordering & match strategy (see eval section).
globals
object
Global defaults, catalogs, engine knob registry, schedules, exclusions (see globals).
groups
object[]
Ordered list of policy groups. THE core — almost every key you'll set lives inside a group.

eval — جانچ کی ترتیب

eval
Field
Type
Values / default
Description
group_order
string[]
Names of groups in evaluation order. A flow is matched against groups in this order.
default_group
string
= Default
Fallthrough group when no other group's selectors match.
match_mode
string
first_match | priority= first_match
first_match keeps configured order; priority sorts rules by their `priority` ascending.
use_effective_tags
bool
= true
Use device/identity effective tags (inherited from categories/groups) during selector matching.

groups[] — پالیسی گروپ آبجیکٹ

Identity

groups[]
Field
Type
Values / default
Description
name
string
Unique group name. Referenced from eval.group_order and overrides.schedule.
status
bool
= true
Enable/disable the whole group without deleting it.
description
string
Free-text label.

Selectors — who the group applies to

groups[].selectors

A flow joins this group when its selectors match. Empty arrays = no constraint on that axis.

Field
Type
Values / default
Description
interfaces
string[]
Interface names this group binds to (e.g. ["vtnet1"]).
vlans
int[]
VLAN IDs to scope to.
direction
string
any | in | out= any
Traffic direction.
devices
string[]
Device identifiers — use uppercase MACs (AA:BB:CC:DD:EE:FF) as stable IDs.
device_tags
string[]
Match devices carrying any of these tags.
device_categories
string[]
Match devices in these categories.
src_cidrs
string[]
Source CIDRs.
dst_cidrs
string[]
Destination CIDRs.
users
string[]
AD/identity usernames.
groups
string[]
AD/identity group names.

Overrides

groups[].overrides
Field
Type
Values / default
Description
block_all
bool
= false
Hard early-drop ALL traffic for this group (pair with a schedule for time-bound allow).
block_untrusted
bool
= false
Drop traffic from devices not marked trusted.
schedule
string
Name of a globals.schedules[] entry. Outside its window the engine SKIPS the group (falls through to the next).
security_block_maskdeprecated
int
DEPRECATED / not parsed. Use the per-catalog booleans under `security` instead.

Exclusions

groups[].exclusions

Allow-list overrides that exempt matching traffic from this group's blocks.

Field
Type
Values / default
Description
devices
string[]
Devices (MACs) exempt from this group.
macs
string[]
MAC exemptions.
src_cidrs
string[]
Source CIDR exemptions.
dst_cidrs
string[]
Destination CIDR exemptions.
domains
string[]
Domain suffix exemptions.
users
string[]
User exemptions.

Security catalogs (threat categories)

groups[].security

Each boolean enables blocking of one threat-intel catalog. basic_mode/advanced_mode are convenience presets; the `essential{}` and `advanced{}` objects mirror the flat booleans.

Field
Type
Values / default
Description
basic_mode
string
off | low | medium | high= high
Preset that toggles the essential catalogs as a group.
advanced_mode
string
off | low | medium | high= high
Preset for the advanced catalogs.
custom_ti
bool
Also evaluate the operator's custom IOC feed for this group.
malware_virus / phishing / hacking / spam / parked / first_seen / potentially_dangerous
bool
Essential catalogs — one boolean each.
botnet_cc / compromised / spyware_adware / ransomware / cryptominer / exploit_kit / banking_trojan / info_stealer / iot_botnet / ddos_amplifier / scanner / anonymizer / bulletproof_hosting / dynamic_dns / newly_registered / adult_nsfw / yara_rules / ja3 / ja4 …
bool
Advanced catalogs (under security.advanced{}) — one boolean each.

Application control (L7 app-ID)

groups[].apps
Field
Type
Values / default
Description
categories_block
string[]
nDPI category slugs to block, e.g. ["adultcontent"]. See /api/zedmos/policies/appcategories.
block
string[]
Specific application names to block (see /api/zedmos/policies/appcatalog).
custom
object[]
Custom app definitions {name, category, domains[], ports[]} so flows nDPI can't classify become matchable. domains are SNI/Host suffix-matched; ports[] is forward-compatible.

Encrypted-transport control

groups[].transport

First-install default: all 'allow'. Switch to 'block' to enforce.

Field
Type
Values / default
Description
quic_strategy
string
allow | block= allow
QUIC (HTTP/3) handling.
doh_strategy
string
allow | block= allow
DNS-over-HTTPS handling.
dot_strategy
string
allow | block= allow
DNS-over-TLS handling.
doq_strategy
string
allow | block= allow
DNS-over-QUIC handling.
starttls
object
Force STARTTLS inspection per protocol: {smtp, imap, pop3, xmpp} booleans.

TLS inspection (MITM)

groups[].tls
Field
Type
Values / default
Description
enable_inspection
bool
= false
Turn on TLS bumping for this group.
bump_mode
string
auto | force | off= force
How aggressively to bump TLS sessions.
min_version
string
off | 1.0 | 1.1 | 1.2 | 1.3= off
Minimum TLS version to allow; below it is blocked.
fail_open
bool
= true
On bump failure, allow (true) or drop (false).
ech_block
bool
= false
Block Encrypted ClientHello. Engine drops only when outer SNI is empty (avoids GREASE-ECH false positives).
ja3_block
string[]
JA3 client fingerprints to block.
ja4_block_sha256
string[]
JA4 fingerprint SHA-256s to block.
alpn_block
string[]
ALPN protocols to block.
weak_ciphers_block
string[]
Cipher suites to block.
sni_bump_sfx
string[]
SNI suffixes to force-bump.
sni_bypass_sfx
string[]
SNI suffixes to NEVER bump (cert-pinned hosts; ~33 sane defaults shipped).
pinned_hosts
string[]
Hosts known to pin certs — relayed raw.
tls_app_bypass / tls_cat_bypass
string[]
Apps / categories to exempt from bumping.

Network (L3/L4) blocks

groups[].network

Hard early-drops via fast-reject before rules[] runs. Use a rule with is_exception+action:allow to punch a hole.

Field
Type
Values / default
Description
proto_block
string[]
IP protocols to drop.
port_block
int[]
Destination ports to drop.
macs
string[]
MAC addresses to drop.
src_ip_block / dst_ip_block
string[]
IPv4 source/destination addresses to drop.
src_cidr_block / dst_cidr_block
string[]
IPv4 source/destination CIDRs to drop.
src_ip6_block / dst_ip6_block / src_cidr6_block / dst_cidr6_block
string[]
IPv6 equivalents.

Web filtering

groups[].web
Field
Type
Values / default
Description
url_allow / url_block
string[]
URL allow / block lists.
http_host_block / http_uri_block / http_method_block / http_status_block
string[]
Block by HTTP host / URI / method / response status.
doh_endpoints_block
string[]
Known DoH endpoint hosts to block.
safe_search
object
{enable:bool} — force SafeSearch on supported engines.
dlp
object
Data-loss-prevention block (see web.dlp).

AI Security & DLP

groups[].web.dlp

Per-group only — globals.web.dlp is a TEMPLATE the engine ignores. First-install default: OFF.

Field
Type
Values / default
Description
enable
bool
= false
Master DLP switch for the group.
mode
string
off | regex_only | ai_gateway | llm_all= off
regex_only = Hyperscan presets only; ai_gateway = regex + LLM verdict on matching AI routes; llm_all = LLM verdict on every matching body.
action
string
log | block | quarantine= log
What to do on a DLP hit.
presets
string[]
Hyperscan preset names (CC/IBAN/national-ID/PII) from the DLP preset library (/api/zedmos/policies/dlppresets).
patterns
string[]
Additional preset/regex names to match.
body_inspection
object
{enable, methods[], max_mb, skip_mime[]} — which request bodies to inspect (POST/PUT/PATCH; skips images/video/binary).
llm
object
LLM verdict config: {enable, provider(ollama|claude|openai|vllm|lmstudio), endpoint, api_key, model, system_prompt, max_tokens, timeout_ms, async, multimodal{}}.
ai_gateway
object
{rules[]} — each {name, paths[], domains[], apps[], categories[], llm_override{}} routes a subset of requests to the LLM. Only consulted when mode=ai_gateway.

File / AV scanning

groups[].file.scan
Field
Type
Values / default
Description
mode
string
off | detect | block= off
off = no scan; detect = scan+log; block = scan+drop infected.
action
string
log | block | quarantine= block
Action on an infected file.
fail_close
bool
= false
If the scanner is unavailable, block (true) or pass (false).
max_mb
int
Max file size to scan (MB).
engines
string[]
Scan engines to use, e.g. ["clamav"].
mime_allow / mime_deny
string[]
MIME allow / deny lists.
prefilter
bool
Cheap pre-filter before full scan.
protocols
object
Per-protocol toggles {tls_http, smtp, ftp, smb, imap, pop3, mqtt, nfs, tftp, modbus} — inherit/on/off.

DNS control

groups[].dns
Field
Type
Values / default
Description
block_domains / allow_domains
string[]
Domain block / allow lists (suffix match).
rcode_block
string[]
DNS response codes to block.
rewrite
object[]
DNS rewrite rules.
edns_client_subnet
string
EDNS Client Subnet handling.
tunnel
string
off | log | block= block
DNS-tunneling heuristic action.
malformed
string
off | log | block= block
Malformed-DNS action.
dga
string
off | log | block= block
DGA (domain-generation-algorithm) heuristic action.
poison
string
off | log | block= block
DNS-poisoning heuristic action.

ETA · Identity · Geo · Risk · TI · IDS

groups[].{eta,identity,geo,risk,ti,ids}
Field
Type
Values / default
Description
eta
object
Encrypted Traffic Analysis: {enabled, log_threshold, block_threshold}.
identity
object
{user_block[], group_block[], device_block[]} — block by AD identity.
geo
object
{country_block[]} — block by GeoIP country code.
risk
object
{labels_block[], tags_block[]} — block by risk label / device tag (works with mark_suspicious).
ti
object
{enable:bool, domain_block[], sni_block[], domain_allow[], sni_allow[]} — per-group threat-intel gate against globals.ti feeds.
ids
object
{mode: off|detect|prevent, enable, alert_max_priority(1-4), block_max_priority(1-3), wan_only}.

Action handlers

groups[].actions

Configured 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.

Field
Type
Values / default
Description
shape
object
{pps:int} — rate-limit matched flows.
redirect
object
{ip, port} — redirect the connection.
quarantine
object
{enable:bool} — quarantine the device.
tarpit
object
{enable:bool} — tarpit the connection.
rewrite_url
object
{to:string} — rewrite the request URL.
execute_script
object
{path, args, timeout_ms, env} — fork+exec via writerd after an action_event.
call_api
object
{url, method, headers, body, timeout_ms, capture_response, max_body_kb} — webhook/API call.
mark_suspicious
object
{tag, severity, ttl_sec, scope: device|flow} — inline tag for risk.tags_block on the same/next eval.

App Routing

groups[].routing
Field
Type
Values / default
Description
enabled
bool
Enable policy-based routing for this group.
default_target
string
Default route target (gateway/iface/tunnel).
routes
object[]
Each route {name, match_type, match_values[], target, fallback}. fallback used when target SLA is DOWN.

Rules (ordered, fine-grained)

groups[].rules[]

Optional per-group ordered rule list evaluated after early-drops. Each rule matches on fields and fires one action.

Field
Type
Values / default
Description
action
string
allow | log | drop | reset | shape | redirect | quarantine | tarpit | scan_content | rewrite_url | execute_script | call_api | mark_suspicious | escalate | route
What the rule does. 'alert' is NOT valid here (IDS-only) — use 'log' for non-drop observation.
mode
string
all | any= all
all = AND across listed match fields; any = OR.
is_exception
bool
= false
Exception rules evaluate BEFORE all hard early-drops — use to selectively allow traffic a coarse block list would catch.
priority
int
Used when the group/eval match_mode is 'priority' (ascending).
time
object
{start:"HH:MM", end:"HH:MM", days:["mon".."sun"]} — restrict activation window (wraps past midnight).
<match fields>
varies
src/dst/port/proto/domain/app/category/user/… matchers combined per `mode`.
example · groupsave bodyjson
// 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.engine

Operator-tunable hot-path knobs. Precedence: value here > env DG_* > hardcoded default. Atomic publish on policy reload.

Field
Type
Values / default
Description
tls
object
{ech_block_strict, decision_notify}.
ids_proxy
object
{enable, block, block_max_priority, alert_max_priority, wan_only} — IDS over decrypted HTTPS bodies.
dlp
object
{decomp_max_mb}.
flow_agg
object
{emit} — flow aggregation/telemetry.
quarantine
object
{ttl_sec, severity}.
block_page_url
string
Override block-page URL.

Global catalogs & defaults

globals.{security,ti,quarantine,schedules,exclusions}
Field
Type
Values / default
Description
security
object
{catalog[], catalog_ips[], sources[]} — the threat-intel catalog feeds the per-group security booleans draw from.
ti
object
Feed paths + block lists {ttl_seconds, domains_path, ips_path, ip_block[], domain_block[], sni_block[], ja3_block[], ja4_block[]}. Note: globals.ti.enable is DEPRECATED — use groups[].ti.enable.
quarantine
object
{persist, auto_drop, sources[], devices[]}.
schedules
object[]
Named time windows {name, start:"HH:MM", end:"HH:MM", days[]} referenced by groups[].overrides.schedule.
exclusions
object
Global allow-list {devices, macs, src_cidrs, dst_cidrs, domains}.
transport / tls / web / dns / apps / identity / geo / network / actions
object
Global default templates mirroring the group sections. NOTE: globals.web.dlp.* is TEMPLATE-ONLY — the engine ignores it; DLP enforces from groups[].web.dlp.*.
example · globals bodyjson
// 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"] }
  ]
}
اینڈ پوائنٹ حوالہ

ہر زمرہ

بالکل کنسول کی طرح گروپ کیا گیا: پہلے پالیسیاں، پھر سیٹنگز، نوٹیفکیشنز، رپورٹس، لائیو اور باقی۔ راستے ہر زمرے کی بنیاد کے نسبتی ہیں۔

GET پڑھناPOST لکھنا (POST)GET+POST پڑھنا + لکھناGET* GET پر تبدیلی کرتا ہے (میتھڈ گارڈ نہیں) حالت بدلنے والا
Policies/api/zedmos/policies

فلیگ شپ سطح۔ policies.json چلاتا ہے — گروپس، گلوبلز، سیکیورٹی کیٹلاگ، ایپ زمرے، DLP پری سیٹس اور تھریٹ انٹیل۔

GET
/get
Full policies.json document (sample-merged).
GET+POST
/groups
List groups, or create one.create=1&name=&description=&status=
GET
/groupget
One group's full object.name
POST
/groupsave
Universal write path — upsert a group or the global blacklist.full group JSON | {global_blacklist}
DELETE
/groupdel
Delete a group (refuses "Default").name
GET+POST
/globals
Global exclusions, actions, quarantine, eval flags, schedules.domains, actions, quarantine, eval, schedules…
GET+POST
/block
Add a block entry to globals and/or named groups.type(host/sni/ip/category/app), value, global, group(s)
GET+POST
/securitycatalog
Security feed catalog.catalog, sources
GET+POST
/customiocs
Manual TI feed (writes ti_domains.txt / ti_ips.set).ips[], domains[]
GET*
/securitypull
Fetch all configured security feeds now.
GET
/appcategories
nDPI category catalog with per-category counts.
GET
/appcatalog
nDPI protocol → category map.
GET
/dlppresets
DLP preset library (CC/IBAN/national-ID/PII regex).
GET
/ti
Per-group threat-intel state (POST rejected — TI is per-group).
GET
/routehealth
App Routing route SLA health (route_health.json).
GET
/whois
whois lookup (truncated 64 KB).value
POST
/validate
App Routing dry-run validator; never writes.raw policies doc (optional)
POST
/save
Replace full policies.json (deep-merge guard).raw JSON full doc; ?strict=1
POST
/consolesave
Console-facing variant of save (tolerant of double-encoding).raw/nested JSON
GET+POST
/geoipupdate
Trigger GeoIP DB update.
Settings/api/zedmos/settings

سب سے بڑی سطح (~62 ایکشنز): TLS/CA، انٹرفیسز اور ورکرز، IDS/ETA/TI، writerd اور اسٹوریج، AD/آئیڈنٹٹی، کلاؤڈ کنسول، ڈیوائس شناخت اور ٹریفک کنٹرول۔

GET
/get
TLS + LDAP + TI snapshot (secrets blanked).
GET+POST
/interfaces
Interface / worker / deployment config; reloads engine.deployment_mode, zones, *_workers, bridge_pairs
GET
/policiesInterfaces
Routing-aware interface list for policy scoping.
GET+POST
/tls
TLS-proxy config block.tls_root_ca_path, proxy_port, quic_proxy_port…
GET
/tlsstatus
Live TLS proxy status (listening, pf anchor, rdr, quic).
GET+POST
/tlscreateca
Create the MITM CA.DN fields
GET
/tlsexportca
Download CA.format(pem/der/p12)
GET
/tlsmobileconfig
Apple .mobileconfig CA profile.
GET+POST
/ids
IDS/IPS config.mode(off/detect/prevent), block_max_priority, wan_only
GET+POST
/eta
Encrypted Traffic Analysis.enabled, log_threshold, block_threshold
GET+POST
/ti
Threat-intel feed CRUD.action(save_feed/delete_feed/toggle_feed/save_output)
GET
/tistatus
TI feed download status.
GET+POST
/adsettings
Directory integration (secrets blanked on GET).full AD/Azure/SCIM config
GET*
/adsync
Run LDAP/Azure/SCIM sync now.
GET+POST
/devicerecognition
Device-ID config.os_detection, arp, dhcp, mdns, nbns…
GET+POST
/consoleconfig
Zero Trust Console config.console_url, console_node_name, console_owner_email, console_enabled
POST
/console_register
Create service user + API key, register firewall with the hub.email, node_name, console_url
GET+POST
/engine
Allowlisted zedmos-ctl engine proxy.op(status/metrics/health/reload_policy/…)
GET+POST
/writerdconfig
SIEM writer config (file/sqlite/elasticsearch/syslog).full sink config
GET+POST
/retention
DB retention window.days, months
GET
/storagedashboard
Storage KPIs (disk, growth, retention, backends, alerts).
GET+POST
/privacy
Privacy redaction flags.pii_redact, audit_extended
POST
/restartEngine
Template reload + engine restart.
POST
/uninstall
Stop services, optional data wipe, remove package.mode(pkg_only/full)
Notifications/api/zedmos/notifications

الرٹ فیڈ + ڈسپیچر۔ واحد کنٹرولر جس کا اپنا اجازت گیٹ ہے (canModify: سیشن یوزر، یا لوپ بیک/سیم ہوسٹ)۔ کنفیگ notifications.json میں۔

GET
/list
Notifications feed.window_sec, since, type, severity, limit≤1000, page, q, sort, dir
GET
/total
{total} count.
GET+POST
/ack
Mark acknowledged.ids[] | csv
GET+POST
/clear
Delete old rows.older_than_sec
GET+POST
/delete
Delete rows.ids[]
GET
/taxonomy
Channel-type / severity enums.
GET
/settingsGet
Dispatcher settings.
POST
/settingsSave
Save dispatcher config + start/stop notifyd.enabled, poll_interval_sec, retry…, quiet_hours, digest_*
GET
/channelsList
Channels (secrets masked).
POST
/channelSave
Create/update a channel (email/webhook/…).{id,name,type,enabled,params}
POST
/channelDelete
Delete a channel.{id}
GET+POST
/channelTest
Send a test through a channel.id
GET
/routesList
Routing rules.
POST
/routeSave
Create/update a routing rule.{id,name,match,channel_ids,rate_limit,quiet_hours}
GET
/deliveries
Delivery log.limit≤1000, notify_id
GET
/dispatchStatus
Dispatcher status.
POST
/emitTest
Emit a synthetic notification row.{type,severity,title,message}
POST
/dispatchControl
Control the dispatcher.op(start/stop/restart/reload/once)
Reports/api/zedmos/reports

فلو DB پر صرف پڑھنے والے چارٹ اینڈ پوائنٹس۔ سب dispatch() میں POST پر مجبور تاکہ UI انہیں XHR-GET کر سکے؛ API کی کے ساتھ کوئی بھی میتھڈ کال کریں۔ عام پیرامیٹرز: hours(1-168)، since/until(ms)، mode(session/packet/volume)۔ زیادہ تر {labels, values} لوٹاتے ہیں۔

GET+POST
/connectionsTopGeoCountries
Top remote destination countries.
GET+POST
/connectionsTopThreats
Top threats by reason.
GET+POST
/connectionsTopThreatDevices
Top threat source devices.
GET+POST
/connectionsTopBlocks
Top policy blocks by reason.
GET+POST
/connectionsTopBlockedHosts
Top blocked hosts.
GET+POST
/connectionsApps
Top applications.mode, traffic_type
GET+POST
/connectionsTopDevices
Top source devices.mode, traffic_type
GET+POST
/connectionsTopSni
Top TLS SNI.
GET+POST
/connectionsTopTlsAlpn
Top TLS ALPN.
GET+POST
/connectionsTopDnsQueries
Top DNS queries.
GET+POST
/overviewThreatsTimeline
Time-bucketed threats vs blocks.
GET+POST
/overviewIdsTopSids
Top IDS signatures.topn(5-50)
GET+POST
/overviewTiBreakdown
Threat-intel feed-hit breakdown.
POST
/bulk
Batch — run a whitelist of chart actions in one request → {results}.actions(JSON/csv) + per-action params
Live/api/zedmos/live

تقریباً حقیقی وقت کی فیڈز۔ since کرسر سے پول کریں (UI پولنگ استعمال کرتا ہے — باکس پر WebSocket/SSE نہیں)۔ عام پیرامیٹرز: hours(6)، since(ms)، limit(1000، 10-2000)، نیز اسمارٹ فلٹرز (filters_<ep>، sf_*)۔

GET+POST
/connections
Live connections ({rows}).
GET+POST
/threats
Security flows + IDS alerts + portscans.
GET+POST
/blocks
Policy blocks.
GET+POST
/web
HTTP flows.
GET+POST
/dns
DNS transactions.
GET+POST
/tls
TLS flows (SNI, ALPN, cipher, JA3/JA4).
GET+POST
/files
File-transfer flows.
GET+POST
/whois
whois lookup.query, type(ip/host)
GET+POST
/export
CSV export {filename, content}.type(connections/threats/blocks/web/dns/tls)
GET+POST
/suspiciousCreate
Mark a host suspicious.ip, mac, tag, scope, severity, ttl_sec
GET+POST
/quarantineCreate
Quarantine a host.ip, mac, iface, group, reason
Dashboard/api/zedmos/dashboard

مجموعی KPIs، سسٹم ٹیلی میٹری (CPU/درجہ حرارت/ڈسک)، فیچر حالت، اور سروس / اپ ڈیٹ کنٹرول۔

GET
/summary
{engine, traffic, files, ml, database} today aggregate (30s cache).
GET
/featurestatus
Per-feature enabled map (tls_proxy, threat_intel, eta, policies, ids_ips, file_scan, backup, siem, console, device_id, license).
GET
/aggregatestatus
Combined engine + writerd + agent status.
GET
/cpu
System + per-process CPU/mem.
GET
/disk
Disk usage of /var/log/zedmos.
POST
/enable
Set autostart (zedmos_enable).enabled
GET*
/restart
Engine restart.
GET+POST
/agent
Control the zedmos-console (Cloud Agent).op(status/start/stop/restart)
GET
/checkupdate
Check for a new package (300s cache).force
POST
/installversion
Install a specific version.version
GET
/snapshot
Bundle multiple sub-actions in one call.sections(csv)
Device/api/zedmos/device

ڈیوائس انوینٹری + لائف سائیکل۔ <id> ایکشنز کے لیے پوزیشنل پاتھ آرگومنٹس، مثلاً /device/trust/42۔

GET
/list
Device inventory {rows, total}.filter, category, q, sort, dir, limit, page
GET
/stats
Counters (total/online/trusted/hidden/quarantined…).
GET
/categories
Device categories.
GET
/detail/<id>
Device + ips + stats + events.
GET
/history
Flow history.ip, mac, limit, offset
GET+POST
/setcategory/<id>
Set device category.name
GET*
/trust/<id>
Trust toggle.flag(0/1)
GET*
/hide/<id>
Hide toggle.flag(0/1)
POST
/purge/<id>
Hard-delete across tables + policies.json.ip, mac
GET+POST
/tagadd/<id>
Add a tag.tag
GET
/export
devices.csv.
More controllers/api/zedmos

اضافی کنٹرولرز، خلاصہ۔ ہر ایک وہی /api/zedmos/<slug>/<command> کنونشن اور وہی توثیق استعمال کرتا ہے۔

GET+POST
/anomaly/settings | /advanced
ML anomaly modes + training params; mlStart/mlStop/mlRestart, summary, recent.
GET*
/av/updatedb | /start | /stop
ClamAV DB + daemon lifecycle (dbstatus, status are GET).
POST
/block_page/save | /preview | /uploadlogo
Block-page designer (get, castatus, cadownload, logoinfo, removelogo).
GET*
/cti/categories
Proxies the TiHub CTI categories (cached).
GET
/routing/validate | /targets | /health | /wgpeers
App Routing validation + health.
POST
/ssh/save | /hasshadd | /hasshremove
SSH deep-inspect config + HASSH blocklist (settings, status, hasshlist, groupsettings).
GET
/support/context
HMAC-signed support-portal redirect.
POST
/wizard/apply | /consoleRegister | /tihubEnroll
First-run wizard: sysinfo, db*, mode*, sub*, *Es, engine, writerd.
GET+POST
/agent/settings | /control
Cloud-agent config + control (status).
POST
/zedmoswg/provisionInstance | /addPeer | /writeIdentityFiles
WireGuard instance/peer management (getInstance, instanceHealth, listInstances, getIdentityUsers…).
WebSocket پراکسی

راستہ B، تفصیل سے

فائر وال ہب کی طرف ڈائل کرتا ہے؛ پارٹنر ہب کا REST API کال کرتا ہے، جو کال کو ساکٹ کے ذریعے نیچے پہنچاتا ہے۔ ایجنٹ مقامی API کو چھونے سے پہلے فی درخواست الاؤ لسٹ نافذ کرتا ہے۔

ہب REST API — پارٹنر کیا کال کرتا ہے

POST
/api/agent/proxy/http
ایک API کال کو نامزد فائر وال تک پہنچائیں۔ url نسبتی ہونا چاہیے اور /api/ سے شروع ہونا چاہیے (SSRF گارڈ)؛ method ∈ GET/POST/PUT/PATCH/DELETE؛ url ≤2048B، body ≤256KB۔ خرابیاں: 503 not-connected، 504 timeout، 429 too-many-pending۔auth: کنسول Bearer یا x-admin-token
GET
/api/agent/proxy/status
کال کرنے والے کے ٹیننٹس میں منسلک ایجنٹس۔auth: کنسول Bearer
GET
/api/agent/proxy/metrics
Prometheus میٹرکس۔auth:
POST
/api/agent/enroll
انسٹال ٹوکن کا تبادلہ ← tenant_id، node_id، agent_secret، jwt، refresh_token۔auth: ایک بار کا انسٹال ٹوکن

الاؤ لسٹ پری سیٹس (فی درخواست حد)

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 · config.json patternsini
# 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/*

پیغام پروٹوکول (حوالہ)

ws framesyaml
ہب ← ایجنٹ: {"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۔