Security whitepaper

1. Architecture Overview

MikroTik Manager is a fully self-hosted network management application distributed as a Docker container. It runs entirely within the customer's own infrastructure. This document describes that software. The analytics this website itself uses are a separate matter, set out in the Cookie Policy.

2. Data Residency & Privacy

3. Authentication & Authorization

3.1 User Authentication

• JWT-based authentication — short-lived access tokens (15 min) + refresh tokens (7 days)
• bcrypt password hashing — passwords are never stored in plaintext
• Automatic token refresh on expiration
• Two-factor authentication (TOTP) — optional per-user RFC 6238 TOTP via any authenticator app (Google Authenticator, Authy, 1Password, Microsoft Authenticator). Secrets are encrypted at rest with AES-256-GCM; 8 single-use backup codes (bcrypt-hashed) are issued at enrolment. Admin reset endpoint clears 2FA on lost devices
• Passkey / WebAuthn / FIDO2 (v1.28.0+) — additive second factor alongside TOTP. Apple/Google passkey, Touch ID, Face ID, Windows Hello, YubiKey. Multi-credential per user (each named at registration, with last-used timestamp). Counter regression check on every assertion (any non-zero counter decrease fails closed — possible cloned authenticator). Stored public keys only, no secrets. Admin reset endpoint clears all of a user's passkeys. Requires HTTPS on a real domain — the WebAuthn spec forbids IP addresses as RP IDs, so LAN-IP installs explicitly show the feature as Unavailable with a configuration hint rather than failing silently
• Refresh tokens invalidated on password change — refresh tokens carry the password-change timestamp; the refresh endpoint rejects any token issued before the user's most recent password update
• Auto-generated secrets on fresh installs — JWT_SECRET and ENCRYPTION_KEY are auto-generated and persisted to data/.secrets.json (file mode 0600) when not supplied via environment, eliminating the public-default risk
• Admin auto-seed only on empty database — the default admin/admin user is created once on first install; deleting it does not re-seed on the next restart

3.2 API Key Authentication

• Machine-to-machine API keys (v1.37.0+) — long-lived bearer tokens for scripts, monitoring, and CI to call the REST API without a user login or token-refresh loop. Sent via an X-API-Key header or Authorization: Bearer mikr_…
• Hashed at rest — only a SHA-256 hash of the token is stored; the plaintext is shown exactly once at creation and is never recoverable afterwards
• Role + per-site scope — each key carries a role and an optional site allowlist, enforced through the same server-side RBAC checks as a user. A key can never hold the Super Admin role, so it cannot manage users or other keys (privilege-escalation cap)
• Revocable and expirable — keys can be revoked instantly or given an expiry date; revoked/expired keys are rejected at authentication
• Audited — key creation, revocation, and deletion are recorded in the activity log, and API calls made with a key are attributed to it (apikey:<name>)
• Managed by Super Admins only, from a dedicated API Keys page

3.3 Role-Based Access Control

Each non–Super Admin role can additionally be scoped to specific sites (per-site RBAC, v1.33.0+): the role decides what a user can do, the assigned site list decides where. A scoped user only ever sees and acts on their sites — across the dashboard, device list, sites, logs, backups, live status updates, and bulk commands/upgrades — enforced server-side at the data and WebSocket layers, not just in the UI. Users with no scope restriction retain full-fleet access.

3.4 Device Credential Security

• Device passwords encrypted at rest using AES-256-GCM
• Each encrypted value uses a unique initialization vector (IV)
• Encryption key configurable via environment variable
• Credentials decrypted only in memory at the moment of device communication

Recommended: create a dedicated MikroTik user group with minimal policies:

/user/group/add name=manager-group policy=ssh,reboot,read,write,sensitive,rest-api,policy,!local,!telnet,!ftp,!test,!winbox,!password,!web,!sniff,api,!romon

3.5 AI Assistant Access (MCP)

• Off by default (v1.73.0+) — the read-only Model Context Protocol endpoint at /mcp exists only after an admin enables it. While it is off the path returns 404 to authenticated and anonymous callers alike, so an install that has not enabled it does not advertise it
• Read-only by construction, not by policy — there is no tool for upgrading, rebooting, running a command or changing a setting, and the module behind the endpoint has no code path that issues anything but a read request
• Authenticated with the same API keys — an assistant carries a key and inherits its role and site scope; every read it performs passes through the same server-side checks a browser session goes through, so it sees exactly what that key's owner would see
• Browser-based clients sign in over OAuth (v1.74.0+) — a client running in a browser has no config file to read a key from, so it is sent to a consent screen served by the Manager. That screen asks for an API key and nothing else: there is no username-and-password path, and no user session is created
• Tokens are anchored to the key, not independent of it — they are opaque strings stored as a SHA-256 hash, deliberately not self-contained tokens that would keep working after the key behind them is gone. Revoking the key stops every token issued from it on the very next request; changing the key's role or its site list applies just as immediately, with nothing to reauthorise
• Short-lived, rotating, revocable — access tokens last one hour and refresh tokens are rotated on every use, as the OAuth 2.1 profile requires of public clients. A refresh token presented twice is treated as a replay and the entire authorisation is revoked. Each token is bound to /mcp and is refused anywhere else, including the rest of the REST API
• Visible and severable — connected clients are listed on the API Keys page with the key each one used, when it connected and when it last read anything, and can be disconnected individually. Authorising a client is recorded in the activity log alongside key creation and revocation
• Public exposure is opt-in and separate — the OAuth flow needs the Manager to be reachable over HTTPS from the browser signing in, so it is served only when an admin fills in a public URL. Left empty, every OAuth path answers 404 and an install on a private network is unaffected. This is the one feature in the product that asks for inbound access from outside; assistants running on your own machine need none of it

4. Network Security

4.1 Transport Encryption

• HTTPS/TLS — optional TLS server on port 3443
• WebSocket Secure (WSS) — automatic over HTTPS
• Supports custom certificates or auto-generated self-signed
• HTTP and HTTPS can run in parallel for migration

4.2 Device Communication

4.3 Network Exposure

• No inbound connections required from outside your network. Three things listen, and all three are meant for your own network: the web interface (3000 HTTP, 3443 HTTPS), the syslog receiver (5514 UDP and TCP, on by default), and — only if you enable it — the Prometheus scrape endpoint on the web port
• The syslog receiver accepts what reaches it. Syslog carries no authentication anywhere, from any vendor, so the control is the network: let your devices reach 5514 and nothing else. Set SYSLOG_ENABLED=false, or simply do not publish the port, if you collect logs elsewhere
• Reaching the Manager from a browser outside the network is optional and off unless configured — signing in a browser-based AI assistant (section 3.5) requires it
• No outbound connection sends your data to us. The Manager reaches the internet in four places: three read-only public feeds that carry nothing of yours (below), and — if you configure them — webhooks and cell tower lookups, which go to destinations you choose and stay off until you set them up
• Read-only public-feed checks (RouterOS CVE feed from NVD, latest RouterOS version from MikroTik, Manager update from GitHub Releases) — GET-only, no request body, degrading gracefully when offline. The CVE feed can be switched off in settings; the MikroTik and GitHub checks have no setting, so block them at the network level if you do not want them
• Designed to run behind a reverse proxy for production

5. Data Protection

Encryption at Rest

Encryption in Transit

6. Container Security

• Base image: node:22-alpine — minimal attack surface
• Multi-stage build — build dependencies excluded from final image
• Non-root execution — runs as non-privileged user
• Minimal packages — Alpine-based with no extras
• No privileged flags — no host network access required
• Only required ports exposed — 3000 HTTP and 3443 HTTPS for the interface, 5514 UDP and TCP for the syslog receiver. The compose file publishes all four; drop the syslog lines if you do not collect logs here
• Data persistence via Docker volume mount

7. Dependency Management

• Runtime dependencies pinned in package-lock.json
• No third-party SaaS, SDK, or tracking dependencies — core operation is fully self-contained. The only outbound traffic is the read-only public-feed checks described in §2 / §4.3 (NVD, MikroTik, GitHub Releases), which carry none of your data; the CVE feed is switched off in settings, the other two at the network level
• Key dependencies: express, better-sqlite3, node-ssh, net-snmp, jsonwebtoken, bcrypt, ws

8. Supply Chain Security

MikroTik Manager minimizes supply chain risk through controlled dependencies, reproducible builds, and a fully self-contained distribution model.

8.1 Docker Image Integrity

• Official base image — built on node:22-alpine from Docker Hub official library
• Multi-stage build — build tools and dev dependencies are excluded from the final image
• Immutable tags — each release is tagged with a specific version (e.g., v1.17.0), never overwritten
• GitHub distribution — images distributed via GitHub Container Registry (ghcr.io), tied to the official repository

8.2 Dependency Controls

• Locked dependencies — package-lock.json ensures reproducible installs with exact versions and integrity hashes
• Minimal dependency tree — only essential runtime packages, no unnecessary transitive dependencies
• No post-install scripts — no npm lifecycle scripts that execute arbitrary code during installation
• No CDN or external assets — all frontend assets bundled locally, no runtime fetches from third-party servers

8.3 Build Process

• Reproducible builds — identical source + lockfile produces identical output
• No remote code execution — the build process does not download or execute code outside of pinned npm packages
• Single author — all code written and reviewed by the maintainer, no external contributors with commit access

8.4 Runtime Isolation

• No auto-updates — the application never downloads or applies updates by itself
• No plugin system — no mechanism for loading external code at runtime
• No outbound connections of its own — the container calls out only where you have switched something on: the three public feeds, and any webhook or cell tower lookup you configure. Nothing else initiates a connection, and none of it is required to run

9. OWASP Top 10 Coverage

10. Deployment Recommendations

11. Compliance Notes

12. Vulnerability Reporting

To report a security vulnerability, contact: security@mikr.app

We take security reports seriously and will respond within 48 hours.

The same contact is published in machine-readable form at /.well-known/security.txt, per RFC 9116.

The software is self-hosted, so every install runs on its operator's own server and there is no fleet of ours to probe. Please do not test against a server you do not run.