Zedmos
DÉVELOPPEURS · API

Pilotez Zedmos depuis n'importe où.

Chaque capacité Zedmos exposée par l'interface de la console est un point de terminaison REST. Ce guide couvre les deux façons sûres pour un système distant de les atteindre — une clé d'API directe, ou le proxy WebSocket zedmos-console — ainsi qu'une référence complète par catégorie.

OPNsense 26.1pfSense CE 2.8REST + WSSVérifié en laboratoire
DEUX VOIES D'ENTRÉE

API directe, ou proxy WebSocket

Les deux voies aboutissent aux mêmes contrôleurs /api/zedmos/* — seuls le transport et les identifiants diffèrent. Choisissez-en une par intégration.

AAPI REST directe
Expose
Le pare-feu OPNsense lui-même (son serveur web). Sur pfSense, la protection équivalente est limitée à la boucle locale — utilisez plutôt le proxy WebSocket.
Transport
HTTPS directement vers l'interface d'administration du pare-feu.
Identifiant
Clé d'API OPNsense + secret (authentification HTTP Basic). pfSense utilise une clé + un secret générés localement, acceptés uniquement sur la boucle locale.
Délimitation
Une seule ACL OPNsense — page-services-zedmos — contrôle tous les points de terminaison (lecture ET écriture). Aucune portée en lecture seule intégrée. Sur pfSense, la protection équivalente est le privilège d'ACL Zedmos.
Idéal pour
Un partenaire sur un segment de confiance ou un VPN site à site, ou que vous pouvez restreindre par IP.
https://<firewall>/api/zedmos/...
BProxy WebSocket (zedmos-console)
Expose
Le hub cloud Zedmos (zedmos-backend). Le pare-feu s'y connecte en sortie.
Transport
Le pare-feu ouvre un tunnel wss:// sortant vers le hub ; le partenaire appelle l'API REST du hub.
Identifiant
Jeton de session de la console du hub (Bearer). Le pare-feu est enrôlé avec tenant_id + node_id + agent_secret (HMAC).
Délimitation
Liste d'autorisation par chemin sur l'agent, PLUS l'ACL de la clé d'API locale, PLUS l'isolation des locataires du hub.
Idéal pour
Gestion SaaS / multi-locataire, pare-feu derrière NAT, ou tout ce que vous ne devez pas exposer en entrée.
POST https://<hub>/api/agent/proxy/http → { url: "/api/zedmos/..." }
AUTHENTIFICATION

Démarrage rapide

Sur OPNsense, l'API directe utilise une clé d'API OPNsense + un secret via HTTP Basic. Les appels non authentifiés reçoivent un HTTP 302 (redirection vers la connexion), pas un 401. Les appels par clé d'API sont exemptés de CSRF. Sur pfSense, la protection de l'API locale est limitée à la boucle locale : les intégrations distantes passent donc par le proxy WebSocket.

API REST directe — 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"}
API REST directe — 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" },
});
Via le proxy WebSocket du hub — 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}}
SÉCURITÉ

La façon la plus sûre de l'exposer

Pour une entreprise extérieure que vous ne contrôlez pas entièrement, préférez le proxy WebSocket : aucun port entrant, liste d'autorisation par chemin, isolation des locataires, révocation centralisée. N'utilisez l'API directe que sur un segment de confiance ou un VPN, toujours durcie.

Une seule ACL contrôle tout

page-services-zedmos couvre chaque point de terminaison /api/zedmos/*, en lecture comme en écriture. Il n'existe pas de privilège Zedmos par point de terminaison ni en lecture seule. Délimitez plutôt un partenaire par des règles réseau ou par la liste d'autorisation du proxy WS.

Les clés d'API contournent le CSRF

Les appels par clé d'API sont exemptés du jeton anti-CSRF (seules les sessions navigateur en ont besoin hors GET). Certains points de terminaison modifient aussi l'état sur GET sans protection de méthode — sans risque avec des clés, mais verrouillez les méthodes sur un proxy inverse si vous les exposez.

Toujours en HTTPS, toujours restreint par IP

L'API écoute sur toutes les interfaces (*:80 en laboratoire). Pour un usage distant, passez l'interface web en HTTPS avec un certificat valide et limitez le port d'administration par une règle de pare-feu aux IP source du partenaire.

Préférez le proxy WS pour les tiers

Il n'ouvre aucun port entrant, restreint exactement les chemins que le partenaire peut appeler (liste d'autorisation), isole les locataires et se révoque depuis un point central (pierre tombale signée). C'est le canal recommandé pour les intégrateurs non fiables.

Recommandation

Proxy WS pour les tiers non fiables. API directe uniquement derrière HTTPS et une règle de pare-feu sur le port d'administration limitée aux IP source du partenaire, avec un compte de service dédié ne détenant que page-services-zedmos.

POLICIES.JSON · CHAMPS

Le schéma policies.json

Chaque clé que le partenaire peut lire par /policies/get et écrire par /policies/groupsave ou /policies/save. Schéma 1.1.0. Les valeurs admises et les valeurs par défaut viennent de la documentation intégrée du document lui-même.

Structure du document

Champ
Type
Valeurs / défaut
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 — ordre d'évaluation

eval
Champ
Type
Valeurs / défaut
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[] — l'objet groupe de politique

Identity

groups[]
Champ
Type
Valeurs / défaut
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.

Champ
Type
Valeurs / défaut
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
Champ
Type
Valeurs / défaut
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.

Champ
Type
Valeurs / défaut
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.

Champ
Type
Valeurs / défaut
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
Champ
Type
Valeurs / défaut
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.

Champ
Type
Valeurs / défaut
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
Champ
Type
Valeurs / défaut
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.

Champ
Type
Valeurs / défaut
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
Champ
Type
Valeurs / défaut
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.

Champ
Type
Valeurs / défaut
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
Champ
Type
Valeurs / défaut
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
Champ
Type
Valeurs / défaut
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}
Champ
Type
Valeurs / défaut
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.

Champ
Type
Valeurs / défaut
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
Champ
Type
Valeurs / défaut
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.

Champ
Type
Valeurs / défaut
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 — valeurs par défaut, catalogues, réglages du moteur

Engine knob registry

globals.engine

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

Champ
Type
Valeurs / défaut
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}
Champ
Type
Valeurs / défaut
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"] }
  ]
}
RÉFÉRENCE DES POINTS DE TERMINAISON

Toutes les catégories

Regroupées exactement comme dans la console : Politiques d'abord, puis Réglages, Notifications, Rapports, Direct et le reste. Les chemins sont relatifs à la base de chaque catégorie.

GET lecturePOST écriture (POST)GET+POST lecture + écritureGET* modifie sur GET (aucune protection de méthode) modifie l'état
Policies/api/zedmos/policies

La surface principale. Pilote policies.json — groupes, réglages globaux, catalogue de sécurité, catégories d'applications, préréglages DLP et renseignement sur les menaces.

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

La plus grande surface (environ 62 actions) : TLS/CA, interfaces et processus, IDS/ETA/TI, writerd et stockage, AD/identité, console cloud, reconnaissance des appareils et contrôle du trafic.

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

Flux d'alertes + répartiteur. Le seul contrôleur doté de sa propre barrière d'autorisation (canModify : utilisateur de session, ou boucle locale / même hôte). Configuration dans 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

Points de terminaison de graphiques en lecture seule sur la base de flux. Tous forcés en POST dans dispatch() pour que l'interface puisse les appeler en XHR-GET ; avec une clé d'API, l'une ou l'autre méthode fonctionne. Paramètres courants : hours(1-168), since/until(ms), mode(session/packet/volume). La plupart renvoient {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

Flux quasi temps réel. Interrogez avec un curseur since (l'interface fait du sondage — il n'y a ni WebSocket ni SSE sur la machine). Paramètres courants : hours(6), since(ms), limit(1000, 10-2000), plus des filtres intelligents (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

Indicateurs agrégés, télémétrie système (CPU/température/disque), état des fonctionnalités, et contrôle des services et des mises à jour.

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

Inventaire des appareils et cycle de vie. Utilise des arguments de chemin positionnels pour les actions <id>, par exemple /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

Contrôleurs supplémentaires, résumés. Chacun suit la même convention /api/zedmos/<slug>/<command> et la même authentification.

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…).
PROXY WEBSOCKET

La voie B, en détail

Le pare-feu se connecte vers le hub ; le partenaire appelle l'API REST du hub, qui relaie l'appel dans la socket. L'agent applique une liste d'autorisation par requête avant de toucher à l'API locale.

API REST du hub — ce que le partenaire appelle

POST
/api/agent/proxy/http
Relaie un appel d'API vers un pare-feu nommé. L'url doit être relative et commencer par /api/ (protection SSRF) ; méthode ∈ GET/POST/PUT/PATCH/DELETE ; url ≤ 2048 o, corps ≤ 256 Ko. Erreurs : 503 non connecté, 504 délai dépassé, 429 trop d'appels en attente.auth: Bearer console ou x-admin-token
GET
/api/agent/proxy/status
Agents connectés dans les locataires de l'appelant.auth: Bearer console
GET
/api/agent/proxy/metrics
Métriques Prometheus.auth:
POST
/api/agent/enroll
Échange du jeton d'installation → tenant_id, node_id, agent_secret, jwt, refresh_token.auth: jeton d'installation à usage unique

Préréglages de liste d'autorisation (la frontière par requête)

core-read-onlyEnviron 364 points de terminaison GET en lecture seule répartis sur 24 modules. Valeur par défaut sûre.
firewall-adminfirewall/* en lecture et écriture complètes + core/diag/interfaces en lecture seule.
network-admininterfaces/*, routes/*, routing/* complets + core/diag en lecture seule.
vpn-adminipsec/*, openvpn/*, wireguard/* complets (sur disque ; à sélectionner via personnalisé).
ids-monitorids/* complet + core/diag en lecture seule (sur disque ; à sélectionner via personnalisé).
full-adminTout, tous les modules. « Équivaut à un contournement. » Ne le donnez pas à des partenaires.

Aucun des préréglages livrés n'inclut /api/zedmos/*. Pour une intégration aux politiques, utilisez une liste d'autorisation personnalisée :

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/*

Protocole de messages (référence)

ws framesyaml
Hub → agent : {"type":"http","requestId","method","url","body","timeoutMs"}
Agent → hub : {"type":"httpResponse","requestId","status","body","error"}
Établissement de session : le hub envoie un nonce de défi ; l'agent répond par HMAC-SHA256(agent_secret, "tenant|node|ts|nonce") ; le hub répond hello_ack. Révocation par une pierre tombale signée.

Référence rédigée complète, avec chaque point de terminaison et chaque paramètre : docs/ZEDMOS_API_REFERENCE.md dans le dépôt.