Zedmos
DESARROLLADORES · API

Gobierne Zedmos desde donde sea.

Cada capacidad de Zedmos que expone la interfaz de la consola es un punto final REST. Esta guía cubre las dos formas seguras de que un sistema remoto llegue a ellas —una clave de API directa o el proxy WebSocket de zedmos-console— además de una referencia completa y categorizada de puntos finales.

OPNsense 26.1pfSense CE 2.8REST + WSSVerificado en laboratorio
DOS VÍAS DE ENTRADA

API directa o proxy WebSocket

Ambas vías terminan en los mismos controladores /api/zedmos/*: solo cambian el transporte y las credenciales. Elija una por integración.

AAPI REST directa
Expone
El propio cortafuegos OPNsense (su servidor web). En pfSense, la protección equivalente solo admite la interfaz de bucle: use el proxy WebSocket.
Transporte
HTTPS directo a la interfaz de administración del cortafuegos.
Credencial
Clave y secreto de API de OPNsense (autenticación HTTP Basic). pfSense usa una clave y un secreto generados localmente, aceptados solo en la interfaz de bucle.
Ámbito
Una sola ACL de OPNsense —page-services-zedmos— controla todos los puntos finales (lectura Y escritura). No hay un ámbito de solo lectura incorporado. En pfSense la barrera equivalente es el privilegio de la ACL de Zedmos.
Ideal para
Un partner en un segmento de confianza o una VPN entre sedes, o uno al que pueda restringir por IP.
https://<firewall>/api/zedmos/...
BProxy WebSocket (zedmos-console)
Expone
El hub en la nube de Zedmos (zedmos-backend). El cortafuegos llama hacia él.
Transporte
El cortafuegos abre un túnel wss:// saliente hacia el hub; el partner llama a la API REST del hub.
Credencial
Token de sesión de la consola del hub (Bearer). El cortafuegos se inscribe con tenant_id, node_id y agent_secret (HMAC).
Ámbito
Lista de permitidos por ruta en el agente, MÁS la ACL de la clave de API local, MÁS el aislamiento por inquilino del hub.
Ideal para
Administración SaaS o multiinquilino, cortafuegos tras NAT, o cualquier cosa que no deba exponer hacia dentro.
POST https://<hub>/api/agent/proxy/http → { url: "/api/zedmos/..." }
AUTENTICACIÓN

Inicio rápido

En OPNsense, la API directa usa una clave y un secreto de API de OPNsense mediante HTTP Basic. Las llamadas sin autenticar reciben un HTTP 302 (redirección al inicio de sesión), no un 401. Las llamadas con clave de API están exentas de CSRF. En pfSense, la protección local de la API solo admite la interfaz de bucle, así que las integraciones remotas pasan por el proxy WebSocket.

API REST directa: 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 directa: 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" },
});
A través del proxy WebSocket del 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}}
SEGURIDAD

La forma más segura de exponer esto

Para una empresa externa que no controla del todo, prefiera el proxy WebSocket: sin puerto entrante, con lista de permitidos por ruta, aislamiento por inquilino y revocación central. Use la API directa solo en un segmento de confianza o una VPN, y siempre endurecida.

Una sola ACL lo controla todo

page-services-zedmos cubre todos los puntos finales /api/zedmos/*, lectura y escritura. No hay un privilegio de Zedmos por punto final ni de solo lectura. Acote a un partner con reglas de red o con la lista de permitidos del proxy WS.

Las claves de API se saltan el CSRF

Las llamadas con clave de API están exentas del token anti-CSRF (solo lo necesitan las sesiones de navegador en métodos distintos de GET). Algunos puntos finales también modifican en GET sin protección de método: es aceptable con claves, pero limite los métodos en un proxy inverso si los expone.

Siempre HTTPS, siempre restringido por IP

La API escucha en todas las interfaces (*:80 en el laboratorio). Para uso remoto, pase la interfaz web a HTTPS con un certificado válido y restrinja el puerto de administración por regla de cortafuegos a las IP de origen del partner.

Prefiera el proxy WS para terceros

No abre ningún puerto entrante, restringe exactamente qué rutas puede llamar el partner (lista de permitidos), aísla inquilinos y es revocable de forma central (con una lápida firmada). Es el canal recomendado para integradores no confiables.

Recomendación

Proxy WS para terceros no confiables. API directa solo tras HTTPS y una regla de cortafuegos en el puerto de administración limitada a las IP de origen del partner, con un usuario de servicio dedicado que solo tenga page-services-zedmos.

POLICIES.JSON · CAMPOS

El esquema de policies.json

Cada clave que el partner puede leer con /policies/get y escribir con /policies/groupsave o /policies/save. Esquema 1.1.0. Los valores permitidos y los valores por defecto proceden de la documentación integrada en el propio documento.

IdentitySelectorsOverridesExclusionsSecurity catalogsApplication controlEncrypted-transport controlTLS inspectionNetworkWeb filteringAI Security & DLPFile / AV scanningDNS controlETA · Identity · Geo · Risk · TI · IDSAction handlersApp RoutingRules

Estructura del documento

Campo
Tipo
Valores / por defecto
Descripción
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: orden de evaluación

eval
Campo
Tipo
Valores / por defecto
Descripción
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[]: el objeto de grupo de políticas

Identity

groups[]
Campo
Tipo
Valores / por defecto
Descripción
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.

Campo
Tipo
Valores / por defecto
Descripción
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
Campo
Tipo
Valores / por defecto
Descripción
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.

Campo
Tipo
Valores / por defecto
Descripción
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.

Campo
Tipo
Valores / por defecto
Descripción
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
Campo
Tipo
Valores / por defecto
Descripción
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.

Campo
Tipo
Valores / por defecto
Descripción
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
Campo
Tipo
Valores / por defecto
Descripción
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.

Campo
Tipo
Valores / por defecto
Descripción
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
Campo
Tipo
Valores / por defecto
Descripción
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.

Campo
Tipo
Valores / por defecto
Descripción
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
Campo
Tipo
Valores / por defecto
Descripción
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
Campo
Tipo
Valores / por defecto
Descripción
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}
Campo
Tipo
Valores / por defecto
Descripción
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.

Campo
Tipo
Valores / por defecto
Descripción
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
Campo
Tipo
Valores / por defecto
Descripción
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.

Campo
Tipo
Valores / por defecto
Descripción
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: valores por defecto, catálogos y ajustes del motor

Engine knob registry

globals.engine

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

Campo
Tipo
Valores / por defecto
Descripción
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}
Campo
Tipo
Valores / por defecto
Descripción
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"] }
  ]
}
REFERENCIA DE PUNTOS FINALES

Todas las categorías

Agrupadas exactamente como en la consola: primero Policies, después Settings, Notifications, Reports, Live y el resto. Las rutas son relativas a la base de cada categoría.

GET lecturaPOST escritura (POST)GET+POST lectura + escrituraGET* modifica en GET (sin protección de método) modifica el estado
Policies/api/zedmos/policies

La superficie principal. Gobierna policies.json: grupos, valores globales, catálogo de seguridad, categorías de aplicaciones, preajustes de DLP e inteligencia de amenazas.

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 superficie más grande (unas 62 acciones): TLS/CA, interfaces y procesos de trabajo, IDS/ETA/TI, writerd y almacenamiento, AD e identidad, consola en la nube, reconocimiento de dispositivos y control de tráfico.

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

Canal de alertas y despachador. El único controlador con su propia barrera de autorización (canModify: usuario de la sesión, o interfaz de bucle / mismo host). La configuración está en 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

Puntos finales de gráficos de solo lectura sobre la base de datos de flujos. Todos fuerzan POST en dispatch() para que la interfaz pueda pedirlos por XHR-GET; con una clave de API puede llamar por cualquiera de los dos métodos. Parámetros habituales: hours(1-168), since/until(ms), mode(session/packet/volume). La mayoría devuelve {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

Canales casi en tiempo real. Consúltelos con un cursor since (la interfaz usa sondeo: en la máquina no hay WebSocket ni SSE). Parámetros habituales: hours(6), since(ms), limit(1000, 10-2000), además de los filtros inteligentes (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

Indicadores agregados, telemetría del sistema (CPU, temperatura, disco), estado de las funciones y control de servicios y actualizaciones.

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

Inventario de dispositivos y su ciclo de vida. Usa argumentos posicionales en la ruta para las acciones con <id>, por ejemplo /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

Otros controladores, resumidos. Cada uno sigue la misma convención /api/zedmos/<slug>/<command> y la misma autenticación.

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 vía B, en detalle

El cortafuegos llama hacia el hub; el partner llama a la API REST del hub, que retransmite la llamada por el socket. El agente aplica una lista de permitidos por petición antes de tocar la API local.

API REST del hub: lo que llama el partner

POST
/api/agent/proxy/http
Retransmite una llamada de API a un cortafuegos concreto. url debe ser relativa y empezar por /api/ (protección contra SSRF); method ∈ GET/POST/PUT/PATCH/DELETE; url ≤ 2048 B, body ≤ 256 KB. Errores: 503 sin conexión, 504 tiempo agotado, 429 demasiadas pendientes.auth: Bearer de la consola o x-admin-token
GET
/api/agent/proxy/status
Agentes conectados en los inquilinos de quien llama.auth: Bearer de la consola
GET
/api/agent/proxy/metrics
Métricas de Prometheus.auth: —
POST
/api/agent/enroll
Canjea el token de instalación por tenant_id, node_id, agent_secret, jwt y refresh_token.auth: token de instalación de un solo uso

Preajustes de listas de permitidos (el límite por petición)

core-read-onlyUnos 364 puntos finales GET de solo lectura en 24 módulos. Valor por defecto seguro.
firewall-adminfirewall/* completo en lectura y escritura, más core/diag/interfaces en solo lectura.
network-admininterfaces/*, routes/* y routing/* completos, más core/diag en solo lectura.
vpn-adminipsec/*, openvpn/* y wireguard/* completos (en disco; se eligen con una lista propia).
ids-monitorids/* completo más core/diag en solo lectura (en disco; se elige con una lista propia).
full-adminTodo, todos los módulos. «Equivalente a saltarse la protección». No lo entregue a partners.

Ninguno de los preajustes incluidos abarca /api/zedmos/*. Para una integración de políticas, use una lista de permitidos propia:

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

Protocolo de mensajes (referencia)

ws framesyaml
Hub → agente: {"type":"http","requestId","method","url","body","timeoutMs"}\nAgente → hub: {"type":"httpResponse","requestId","status","body","error"}\nSaludo inicial: el hub envía un nonce de desafío; el agente responde con HMAC-SHA256(agent_secret, "tenant|node|ts|nonce"); el hub responde hello_ack. La revocación se hace con una lápida firmada.

Referencia completa en prosa con todos los puntos finales y parámetros: docs/ZEDMOS_API_REFERENCE.md en el repositorio.