Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions .github/ISSUE_TEMPLATE/tool-request.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
---
name: Tool request
about: Suggest a report or tool for the toolbox
title: "Tool request: "
labels: tool-request
---

## What should it report?

<!-- The question you are trying to answer, e.g. "which APs rebooted this week and why". -->

## Level

<!-- One site, the whole org, one device or one client? -->

## Mist data it would need, if you know

<!-- API endpoints, or where you see this in the Mist portal. -->

## Anything existing to start from?

<!-- A script you already use (Python, Node or PowerShell) can be converted. Remove any real data before pasting it. -->
13 changes: 13 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
## What this adds or changes

<!-- One tool per PR. What does it report, and who is it for? -->

## Checklist

- [ ] The file is `mist-toolbox/community/<tool-id>.js`, named after the tool's `id`
- [ ] I installed it with **Manage tools → Install** and ran it against a real org
- [ ] It only reads (GET) and calls Mist only through `ctx`
- [ ] Its header comment lists every Mist endpoint it reads
- [ ] It has a row in `mist-toolbox/community/README.md`
- [ ] No real data in the file, screenshots or this PR: no org/site IDs, tokens, hostnames, MACs, IPs or customer names
- [ ] I agree that this contribution is released under the repository's MIT licence
23 changes: 23 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
name: test

on:
push:
branches: [main]
pull_request:

permissions:
contents: read

jobs:
test:
runs-on: ubuntu-latest
defaults:
run:
working-directory: mist-toolbox
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
# No npm dependencies, by design: the suite runs on Node's built-in test runner.
- run: npm test
6 changes: 6 additions & 0 deletions ADDING_TOOLS.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,3 +113,9 @@ helper, the form field types, the `scope: "site"` option and the result format.
starting point is [`tool-template.js`](mist-toolbox/docs/tool-template.js). Without the
**Manage tools** button: copy the file into `mist-toolbox/tools/`, run `npm run scan` (or add
its filename to `tools/tools.json`), and reload the extension.

## Share it

If your tool could help other Mist admins, contribute it to the
[community tools](mist-toolbox/community/README.md): add the file to `mist-toolbox/community/`
and open a pull request. [CONTRIBUTING.md](CONTRIBUTING.md) has the steps and the checklist.
61 changes: 61 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
# Contributing a tool

The toolbox grows by people sharing the reports they wrote for themselves. Contributed tools live
in [`mist-toolbox/community/`](mist-toolbox/community/README.md). They are reviewed and tested
like any other code, but they are not built in: people install the ones they want with
**Manage tools → Install**.

## 1. Write the tool

A tool is one JavaScript file that default-exports a tool object. You don't have to write it by
hand:

- **With an AI assistant**: **Manage tools → Copy AI prompt**, paste it into any assistant, then
add your script or a description of the report you want. The full walkthrough is in
[ADDING_TOOLS.md](ADDING_TOOLS.md).
- **By hand**: start from [`tool-template.js`](mist-toolbox/docs/tool-template.js). The reference
is the [authoring guide](mist-toolbox/docs/TOOL_GUIDE.md).

## 2. Try it in your own toolbox

Install it with **Manage tools → Install** and run it against your org. The installer runs the
same checks CI runs, so a tool that installs cleanly will usually pass.

## 3. Open a pull request

1. Fork this repository.
2. Add your file as `mist-toolbox/community/<tool-id>.js`. The filename must match the tool's
`id`. For example, `id: "ap-uptime"` goes in `ap-uptime.js`.
3. Add one row for it to the table in
[`mist-toolbox/community/README.md`](mist-toolbox/community/README.md), linking the file as
`[ap-uptime.js](ap-uptime.js)`.
4. Optional: run `npm test` in `mist-toolbox/`. It needs Node 20 or later and no `npm install`.
5. Open the pull request and fill in the checklist.

One tool per pull request, please. If you're changing an existing community tool, say what
changed and why.

## The rules

CI enforces most of these, and a reviewer checks the rest:

| Rule | Why |
|---|---|
| Mist calls only through `ctx.getAll`, `ctx.searchAll`, `ctx.mistGet` | They only talk to the region the user picked |
| Read-only: GET only, no POST/PUT/DELETE | The toolbox never changes anyone's network |
| No `fetch`, `XMLHttpRequest`, `WebSocket` or other network access | The token must not leave the Mist API |
| No browser storage, cookies, `console.*`, `eval` or dynamic `import()` | Nothing is persisted; the extension's security policy blocks the rest |
| Imports only from `../lib/`, `../engine/` or `../mist.js` | There is no npm in the browser |
| A header comment listing every Mist endpoint the tool reads | Reviewers and users can see what it touches |
| **No real data**: no org or site IDs, tokens, hostnames, MACs, IPs or customer names, in the file or in the PR | The repository is public |

## Becoming a built-in tool

A community tool that many people use can be promoted to `mist-toolbox/tools/`. When that
happens, a maintainer adds tests (see `mist-toolbox/tests/` for examples) and the tool ships in
the next release.

## Licence

This repository is MIT-licensed (see [LICENSE](LICENSE)). By opening a pull request you agree
that your contribution is released under the same licence.
21 changes: 21 additions & 0 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2026 InterconnectedSystems

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
23 changes: 20 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ tool you can install with one click.
Unzip it, then in Chrome or Edge: **Extensions → Developer mode → Load unpacked →** pick the
unzipped `mist-toolbox` folder. Full steps: **[INSTALL.md](INSTALL.md)**.

**[Install guide](INSTALL.md)** · **[Add your own tools](ADDING_TOOLS.md)** · [All releases](https://github.com/InterconnectedSystems/mist-toolbox/releases/latest) · [Extension README](mist-toolbox/README.md)
**[Install guide](INSTALL.md)** · **[Add your own tools](ADDING_TOOLS.md)** · [Community tools](mist-toolbox/community/README.md) · [All releases](https://github.com/InterconnectedSystems/mist-toolbox/releases/latest) · [Extension README](mist-toolbox/README.md)

![The tool menu](mist-toolbox/docs/screenshots/02-home.png)

Expand All @@ -27,6 +27,10 @@ unzipped `mist-toolbox` folder. Full steps: **[INSTALL.md](INSTALL.md)**.
- **Root-cause why one client keeps disconnecting**: RF and SNR, 802.11 reason codes, DHCP
after roam, RRM channel changes, DFS radar on the AP it was on, and Teams/Zoom call quality,
correlated into a verdict. *(Disconnect Console)*
- **Inspect one client's radio link**: RSSI, SNR and noise floor graded against design
thresholds, PHY rate against what the link could do, retries, channel load and non-Wi-Fi
interference, overlapping AP radios, Wi-Fi generation and roaming, as a colour-coded
dashboard. *(Client Wi-Fi PHY Inspector)*

### Switching
- **Audit switch software**: every switch's model, serial, firmware, status, IP, uptime and
Expand All @@ -39,6 +43,10 @@ unzipped `mist-toolbox` folder. Full steps: **[INSTALL.md](INSTALL.md)**.
- **Map your IP space**: every IRB/VLAN interface address with subnet, mask, broadcast and
usable range, with duplicate and overlapping networks flagged across sites.
*(IP Blocks / IRB Report)*
- **Check power supply redundancy**: every switch's PSUs, per Virtual Chassis member, with
failed supplies and switches running on a single supply flagged. *(Switch PSU Status)*
- **Compare additional CLI**: every "additional CLI commands" block at template, switch-rule,
site and device level, side by side, with a de-duplicated list of commands. *(Switch Additional CLI)*

### Operations
- **See what's alarming**: every alarm over the past day or week, by site and by type, with
Expand Down Expand Up @@ -78,6 +86,14 @@ assistant the tool format, the helpers, the security rules and a full working ex

The full walkthrough with screenshots is in **[ADDING_TOOLS.md](ADDING_TOOLS.md)**.

## Community tools

Written a tool others could use? Share it. Contributed tools live in
[`mist-toolbox/community/`](mist-toolbox/community/README.md): browse the list, download one
and install it with **Manage tools → Install**. Every contribution is checked in CI against the
same rules the installer enforces. To add yours, see **[CONTRIBUTING.md](CONTRIBUTING.md)**. To
ask for a tool, [open a tool request](https://github.com/InterconnectedSystems/mist-toolbox/issues/new?template=tool-request.md).

## Install

Chrome or Edge, on Windows, macOS or Linux:
Expand Down Expand Up @@ -108,7 +124,8 @@ Every screenshot with a caption: [`mist-toolbox/docs/screenshots/`](mist-toolbox

## What's in this repository

- [`mist-toolbox/`](mist-toolbox/) is the extension: tools, shared libraries, docs and 198 tests
- [`mist-toolbox/`](mist-toolbox/) is the extension: tools, shared libraries, docs and 220 tests
(`npm test`).
- The original scripts (`mist_*.py`, `site-wifi-clients.py`, `pre-post-check-gui.py`,
`mist_switch_report.js`, `site-alarms.js`) are kept for reference and for comparing output.
`mist_switch_report.js`, `site-alarms.js`, `client-wifi-phy.js`, `switch-psu-status.js`,
`switch-additional-cli.js`) are kept for reference and for comparing output.
Loading
Loading