Writing a module

A module is a folder of plain files, written to the Open Module Standard. If you can explain your own troubleshooting steps to a new hire, you can write one.

Why write one

PathWise ships with modules for DNS and Check Point today, plus built-in coverage for most of the access path. The license lets you modify PathWise for internal use, so if you run a tool it does not know about yet, you can teach it yourself.

The two files that matter

A module needs only two files to work.

• module.yml, the manifest. It states the module's name, vendor, version, which layer it reads, and a plain-language list of what it covers.
• knowledge.md, the know-how. Plain language, no code. It describes what the tool checks, what healthy looks like, what broken looks like, the order to check things in, and the common causes.

A few more files are optional: connection.yml for where the evidence comes from, evidence.yml for labeling the fields the engine reads, an examples/ folder of sample data, and a README.md for your own notes.

The manifest fields

Six required fields are yours to write: name, vendor, version, layer, covers, and author. The manifest also accepts optional fields, such as permissions, external_consent, and metadata. A starter template pre-fills those, so you never have to hand-type registry bookkeeping.

The layer your module reads

Every module declares the one layer of the access path it reads. The eight layers are fixed: device, local network, user, rights, resolution, routing, session-trust, and destination. You add a vendor by writing a module for an existing layer. You do not invent a new layer.

Where the evidence comes from

The simplest door is a file drop. You export data from your tool to a JSON or CSV file, and the engine reads it. It never writes back. This is what a module gets by default when connection.yml says nothing else.

Two live doors also work. An api source names a base URL and the name of a credential, never the credential itself, and the operator stores the real value in Settings. An mcp source names a server and an explicit list of read tools. The tools list is required: a module that omits it fails to load, because PathWise never hands the model a vendor server's whole tool surface. Declare more than one source and the engine picks in a fixed order, MCP first, then the API, then the file.

Checking your work

A verify step checks a module folder before you rely on it. From the PathWise source directory, run npm run troubleshoot -- module verify <folder>. From an installation that exposes the CLI, run troubleshoot module verify <folder> from any directory. The folder argument can be relative or absolute.

The command validates the manifest, reports the inferred tier and recognized permissions, checks the knowledge file for recommended sections, and parses any JSON under examples/exports. A valid module prints module at <folder>: OK and its tier. Errors exit with status 1.

What the engine still guarantees

Whatever a module declares, it can only gather evidence. PathWise diagnoses and never remediates. Writing a module never gives you, or the engine, a way to make a change on the network.