m2ir

An evidence-backed reference for MikroTik's binary protocols and data formats.

m2ir collects hard-earned knowledge about RouterOS nv::message ("M2"), WinBox communication, and related formats in YAML that humans and tools can read directly. It brings together public research, binary analysis, and experiments against real RouterOS instances, with sources and confidence recorded alongside each finding.

The schema is the deliverable: a reusable knowledge base, with research probes and repo tooling alongside it. You can browse it without installing anything. Schema content is CC0-1.0.

• Curious about how WinBox works? Start with the WinBox profile guide. It connects the transport, authentication, messages, and management handlers.
• Decoding a packet capture? Follow the capture path in the agent map to framing, authentication, encryption, and handler evidence. The proposed dissector and session-secret export still need implementation.
• Investigating patched winbox.exe / winbox64.exe compatibility? Follow the compatibility path in the agent map through the static patch review, client analysis, and canonical YAML.
• Building a native WinBox backend? Follow the backend path in the agent map to routing, typed fields, retrieval, pagination, writes, and notification gaps, plus existing implementation references.
• Working with files or another protocol? Use the format and research index for Dude databases, CDB/WBX saved connections, MNDP, RouterOS internal files, and related protocol leads. The three WinBox paths above are examples, not the repository's scope limit.
• Sending an agent here? Use the agent reading map as a focused reading map. AGENTS.md contains contributor instructions.

RouterOS 7.25 raised the minimum supported WinBox version to 4.3, prompting community discussion and attempts to keep WinBox 3 working. If that brought you here, the collected protocol evidence should help you investigate beyond a client version check. Successful login or a working menu alone does not establish full compatibility.

Our forum discussion of possible future changes is motivation for investigation, not a confirmed account of MikroTik's roadmap. The initial lab work demonstrates authenticated native WinBox queries on RouterOS 6.49.23 and 7.25. Later attribute experiments include 7.26beta4, selected 7.26beta5 checks, and limited 7.16.2 hardware observations; each YAML entry records its own scope. This does not establish compatibility for every client, handler, device, or later RouterOS release.

The ongoing research combines WinBox client analysis with REA/Ghidra, RouterOS binary analysis, and live probes using tikoci/quickchr. Findings have landed in the canonical YAML: handshake corrections, session crypto, version-scoped process identities, GUI handler/field mappings, native retrieval and pagination semantics, the worker/shim process registry, and the on-disk persistence rules for rows created over the protocol (owner-token rows are reaped at boot; untokened rows persist). The WinBox profile guide summarizes what is known, in administrator terms. Follow the client analysis and CHR research for the investigation trail; the live probe findings record tested behavior and remaining gaps. The WinBox 3 patch review connects version gates and GUI descriptor/parser breaks to that evidence. It reviews sources statically; it does not verify patched client behavior.

That CHR-lab series (§§16–47 of the findings) is at a natural stopping point: its remaining items need real RouterBOARD hardware, LTE/CAPsMAN/PPP peers, or user credentials, or are small bounded residues. They are listed as parked in the profile guide rather than chased further here. The configuration-attribute follow-on has since produced a schema-aware experiment harness, sanitized replay fixtures, and further YAML mappings. Its handoff records completed batches and remaining work; the execution plan preserves the methodology and historical sequence.

tikoci/centrs already consumes m2ir: its shared EC-SRP5 implementation and regression vectors use this repo's authentication findings for MAC-Telnet and bandwidth-test traffic. The implementation trail pins the inspected revision and links source, tests, provenance, and status. At that revision, WinBox terminal execution is still not-started; shared authentication does not implement a native WinBox configuration backend.

Native WinBox data access is a further application of the GUI handler catalog: which handler owns a field, what its TLV (type-length-value) means, and how replies and notifications behave. Retrieval, pagination, and selected write/persistence experiments are recorded with per-handler limits; notification lifecycle and wider handler coverage remain open. Compare efficiency by measuring the target workload, including pagination, projection, and change handling.

Another goal is a better Wireshark dissector for WinBox IPC, with schema-derived field names, context-aware handler decoding, and eventually encrypted-session analysis when session secrets are available. The same dissector could serve humans in Wireshark and agents through TShark's structured output, supporting compatibility investigations and regression tests. See the dissector proposal for the evidence, suggested milestones, and open decisions. Implementation has not been committed to this repo or a separate project yet; the YAML here remains the shared source of protocol knowledge.

Coverage is incremental. A populated schema is not a claim that an entire protocol is understood. Handler IDs and field meanings can depend on the RouterOS version and context; check the evidence attached to the entry you intend to use. The format and research index also routes to material outside populated profiles: CDB/WBX sources, .x3 extraction/decoder work, store persistence evidence, and leads for MAC-WinBox, terminal access, RoMON, and other RouterOS artifacts. A research link does not imply a complete grammar, decoder, or interoperability guarantee.

The layers separate bytes (physical/), meaning in a usage context (profiles/), and shared semantic identity (concepts/). DESIGN.md explains the format and confidence levels. YAML is canonical; the original Kaitai strawman is preserved as source evidence.

Protocol explanations belong in the schema's notes:, evidence:, and revision-history: attributes. Exploratory findings and reproducible research stay in work/ until ready to promote. Contributions are most useful when they identify the tested version, preserve a source or sanitized observation, and distinguish an observation from an inference.

Issues and pull requests are welcome, including partial findings and corrections from agents. Open an issue to share an observation, unknown TLV, negative result, or reproduction you cannot yet turn into a schema change. For a concrete change, send a pull request with the evidence and proposed YAML or research update. Maintainers will reproduce or cross-check the finding against its sources and version scope before accepting it into canonical schema; a useful submission need not arrive fully proven.

Include the affected format/profile, m2ir revision, exact RouterOS and client versions (plus architecture/binary hash when relevant), numeric route/tag and wire type, observed versus expected behavior, and a public source or sanitized minimal sample with reproduction steps. Keep proposed meanings separate from observed bytes; unresolved IDs can stay unknown. Do not submit credentials, session secrets, private device data, or raw saved-connection/database files containing them.

Help with TLV collection and attribute mapping is especially welcome: start at the handler catalog's unknown fields and gaps, then the attribute handoff for completed experiments and remaining work. The candidate inventory and discovery methodology help design a bounded experiment; CLI candidates alone do not establish native field IDs. Use the harness guide and fixture guide to preserve evidence. Reports of absent fields, type/version differences, and failed hypotheses are useful too.

For other formats, use the format and research index to find the relevant schema or source lead. Keep exploratory submissions under work/; promote supported findings into YAML with confidence:, evidence:, and any corrective revision-history:. For local changes, follow AGENTS.md and the applicable path rules, run bun run lint:ci, and run relevant existing tests for changed mappings.

See BOOTSTRAP.md for Bun setup and validation, and CREDITS.md for the upstream work this reference builds on.

For downstream skills such as routeros-skills#55, use these maintained URLs, then follow their links to current details:

• README — mission, coverage, and discovery submissions.
• Agent reading map — example task paths, broader format/research discovery, evidence, and tooling.
• Format and research index — file-based formats, other protocols, placeholders, and source leads.
• WinBox profile guide — human orientation, implementation references, and limitations.

The WinBox examples should help a skill route common tasks without hiding other formats and research. Include a path back to discovery submissions when an agent learns something new. Keep field tables, patch inventories, counts, and research status here. Record the m2ir commit and exact RouterOS/client versions when using them; main links discover current knowledge but do not pin a reproduction.