hermes-windows-ports

Answer "who holds this port" on Windows. win_port_owners reads the TCP and UDP owner tables through iphlpapi (the same rows netstat -ano prints, with the owning PID attached) and resolves each PID to its image name and path, returning one structured record per endpoint. Filters cover one port, several ports, a process substring, the protocol (tcp, udp or both), the TCP state (listen, established, any state name, or all; UDP rows report bound) and IPv6 inclusion, with a record cap and a per-process summary of the rows returned. Built for the failure mode that stalls agents on Windows: a gateway, backend or bridge that cannot bind, where the error names a port but not the process holding it. netstat -ano prints columns, not fields, and its PID still needs a second command (tasklist, or a PowerShell round-trip) to become an image name; this tool is one in-process call instead of a shell parse plus a join, with no child process and no dependency on PowerShell being installed or allowed by execution policy. A protected process whose image cannot be queried keeps its PID and reports a null process name instead of failing the call. Disclosure - the tool reports the local and remote addresses, ports, PIDs and process image paths that netstat -ano and Task Manager already show, and those values reach the model; treat the output like any other local diagnostic listing. Read-only: no socket is opened, bound or connected, the only process access is QueryFullProcessImageName with PROCESS_QUERY_LIMITED_INFORMATION to read an image name, and there is no memory reading, no handle inheritance and no injection. Stdlib-only (ctypes): no Python dependencies, no child processes, no network calls, no file writes, no self-update. Windows only.

Yicheng-MarkToolsv0.1.0Updated 12 days ago

About

hermes-windows-ports

Answer "who holds this port" on Windows, from inside Hermes.

win_port_owners({"port": 3000})
win_port_owners({"state": "listen", "process": "hermes"})
win_port_owners({"protocol": "tcp", "state": "established", "limit": 20})

win_port_owners reads the same tables netstat -ano prints — GetExtendedTcpTable /
GetExtendedUdpTable with the owning PID attached — and resolves each PID to its image name
through QueryFullProcessImageName. The result is structured JSON, not localized console
text, so it does not depend on the machine's display language.

{
  "ok": true,
  "matched": 8,
  "listeners": 8,
  "total_endpoints": 121,
  "entries": [
    {"protocol": "tcp", "address": "127.0.0.1", "port": 8086, "state": "listen",
     "pid": 496, "process": "fc-core.exe", "path": "C:\\...\\fc-core.exe",
     "remote_address": "0.0.0.0", "remote_port": 0}
  ],
  "by_process": {"fc-core.exe": 4, "System": 1},
  "notes": ["8 endpoint(s) matched out of 121 in the table"]
}

Why this exists

Port conflicts are one of the most common ways an agent stalls on Windows: a gateway, a
backend or a bridge cannot bind, and the error text names a port but not the process holding
it. The obvious workaround — running netstat -ano through the terminal tool — has two
problems: its output is localized (so parsing column headers breaks on a non-English machine),
and the PID it prints has to be resolved to a name by a second command whose output is
localized in the same way.

This plugin does the lookup once, in-process, and returns fields instead of columns. It is the
read-only half of the same question whether you are debugging EADDRINUSE, hunting a stale
process that survived a crash, or checking that only 127.0.0.1 is listening.

Requirements

Windows 10 or 11.
Hermes 0.21.4 or newer.
Nothing else: stdlib only (ctypes), no Python dependencies, no child processes, no network.

Install

git clone --depth 1 https://github.com/Yicheng-Mark/hermes-windows-plugins /tmp/hermes-windows-plugins
cp -r /tmp/hermes-windows-plugins/windows-ports ~/.hermes/plugins/hermes-windows-ports
hermes plugins enable hermes-windows-ports

Filters

| Argument | Meaning |
|---|---|
| port / ports | One port or several, matched on the local endpoint |
| process | Case-insensitive substring of the image name or path |
| protocol | tcp, udp or both (default) |
| state | listen, established, any TCP state name, or all (default); UDP rows report bound |
| include_ipv6 | Read the IPv6 tables too (default true) |
| limit | Maximum endpoints returned (default 100, max 500) |

Behaviour and limits

Read-only. No socket is opened or bound, no connection is made.
Some system processes (pid 4 = System, pid 0 = System Idle) are labelled; a protected
process whose image cannot be queried keeps its PID and reports process: null instead of
failing the whole call.
by_process summarises the returned rows so a caller can see at a glance that, say, four
listeners belong to one binary.
Windows only. Other platforms get a structured error.

Disclosure

Reads the local TCP/UDP tables and resolves PIDs to image paths. Output includes local
and remote addresses, ports, PIDs and process image paths — the same information
netstat -ano plus Task Manager shows. Treat it like any other local diagnostic output.
No network activity. The plugin does not open, bind or connect a socket; it only reads
the kernel's tables.
Read-only process access. QueryFullProcessImageName with
PROCESS_QUERY_LIMITED_INFORMATION — the minimum right needed to read an image name. No
memory reads, no handles inherited, no injection.
No child processes, no files written, no self-update. Stdlib only (ctypes).

Tests

python -m pytest tests -q

14 tests: filters, protocol/state handling, limits and error paths against a fake table on
every platform, plus live tests on Windows that bind a socket and find it again through the
tool, and cross-check the table size. See VALIDATION.md.

License

MIT.

README from the reviewed commit 5bad3fb; it updates when the author re-pins.

More by Yicheng-Mark

15 plugins by Yicheng-Mark in the catalog.

Yicheng-Markhermes-dpapi-secretsResolve Hermes environment variables at startup from a single secret file encrypted with the Windows Data Protection API, instead of keeping provider keys in plaintext in .env or auth.json. Config is secrets.dpapi.map, an ENV_VAR -> store-name mapping (bare names or dpapi:// names) plus an optional file path (default <HERMES_HOME>/secrets.dpapi). The file is one DPAPI blob keyed by the current Windows user profile, so it is unreadable by another Windows account and worthless off the machine; it is written by the bundled CLI (python -m hermes_dpapi_secrets set NAME, value read from a prompt or stdin, never from argv) and only read at runtime. Mapped names that are missing or empty are skipped with a warning; a file that is not ours, a blob this user cannot decrypt, or a payload that is not a flat string map is reported as an error with nothing injected. Disclosure - this source decrypts a file for every Hermes process that enables it: resolved values become environment variables of the Hermes process and its children, exactly like .env entries, so anything that can read that environment can see them. User-scope encryption only (the machine-wide flag is never used and is not exposed), and the at-rest protection is a bar for backups, cloud sync and dotfiles, not a boundary against code already running as the same user. Stdlib-only (ctypes): no Python dependencies, no subprocesses, no network calls, no self-update. Windows only. Applying fetched values stays the orchestrator's job; the plugin never writes os.environ itself. Disclosure — decrypts a DPAPI-encrypted secret file (default <HERMES_HOME>/secrets.dpapi) at startup for every Hermes process that enables it, and the resolved values become environment variables of Hermes and its child processes like `.env` entries; the encryption is per Windows user and protects backups, cloud sync and copied files, not against other code running as the same user. Local only: no network calls, no subprocesses.Communitytools Yicheng-Markhermes-wincredResolve Hermes environment variables from the current user's Windows Credential Manager at startup, instead of keeping provider keys in plaintext in .env or auth.json. Config is secrets.wincred.map, an ENV_VAR -> generic-credential-target mapping (bare names or wincred:// names); each value is read with CredReadW in the current user's vault and handed to the secret-source orchestrator, which applies it with the usual precedence, provenance and conflict rules. Values may be UTF-8 or UTF-16LE (cmdkey and the Credential UI write UTF-16); anything that does not decode to text, or that contains interior NULs, is skipped with a warning instead of being injected as a mangled key. Disclosure - this source reads your Windows Credential Manager: only the generic credentials named in the map, with no enumeration of the vault. Resolved values become environment variables of the Hermes process and its children, exactly like .env entries, so anything that can read that environment can see them. The package is read-only and stdlib-only (ctypes): it never creates, updates or deletes credentials, writes no files, starts no subprocesses, makes no network calls and does not self-update. Windows only. Credential Manager is user-scoped, so this raises the at-rest bar for backups, cloud sync and dotfiles; it is not a boundary against code already running as the same user. Applying fetched values stays the orchestrator's job; the plugin never writes os.environ itself. Disclosure — when enabled, reads only the Windows Credential Manager generic credentials named in secrets.wincred.map (no vault enumeration) and injects them as environment variables of the Hermes process and its children, exactly like .env entries; read-only, stdlib ctypes, no subprocesses, no network, no file writes; user-scoped at-rest protection, not a boundary against code already running as the same user.Communitytools Yicheng-Markhermes-windows-appsAnswer "what is installed on this Windows machine": the software inventory behind Apps & Features, swept straight from the four Uninstall registry keys (the machine's 64-bit and 32-bit views plus the user's), so a program is found even when the Settings page hides it - a per-user install that never shows on the machine page came from the user view on the writing machine. Each row carries version, publisher, size in MB, install date and which view it lives in; the same DisplayName in two views is a 32/64-bit dual install, marked instead of listed twice. Entries the publisher asked to hide (runtime packages, update rollups) are filtered out unless asked for. Details one program with every field its publisher wrote and a reading of the uninstall command (MSI product code, setup executable, appx, script) so the next step is known before anything is run; the install folder is checked against disk. Use it for "what did that installer actually register", for inventory before a cleanup, and for "which of the two installs does uninstalling remove". Read-only: registry keys are enumerated and uninstall strings are reported, never run; no network, no file writes, no elevation. The sweep is pure registry - 102 entries in seven milliseconds on the writing machine, the whole table in ten, no PowerShell, no WMI. The plugin declares no Python dependencies. Windows only. Disclosure - the tools report program names, versions, publishers, sizes, install folders and uninstall commands, and what is hidden from Apps & Features, to the model; treat the output like the machine's own Apps & Features page.Communitytools Yicheng-Markhermes-windows-devicesAnswer "which device on this Windows machine is unhappy, and what does it need" on Windows: win_device_table lists every present PnP device with its class (System, Net, HIDClass, Display), its status, its manufacturer, its stable device id, and its problem code in words - 28 is one with no driver installed, 10 one that cannot start, 43 one Windows stopped after it reported a failure, 22 one the person switched off on purpose and is not broken - filtering by name or id substring, by class, or to the devices that need attention; devices no longer plugged in are history, left out unless asked for. win_device_detail takes one device by id or name substring and adds the driver behind it from the signed-driver table - name, version, date, provider, signer, INF file, signed or not - or the absence of one, which for code 28 is the same fact said twice; a disabled device gets a note saying it is on purpose, not an alarm. Use it for the Device Manager yellow-mark question without opening Device Manager, for finding what an uninstalled program left behind, and for what changed after an update. Read-only: nothing is enabled, disabled, updated or reinstalled. Both answers come from CIM (Win32_PnPEntity and Win32_PnPSignedDriver, joined by device id), whose property names, enum values and ids do not change with the display language; the human-facing device names localize and are carried through as data, never parsed. The plugin declares no Python dependencies; there is no network call and no file write. Windows only. Disclosure — the tools report device names, manufacturers, device ids and driver versions to the model, and those reveal the machine's hardware inventory and what is plugged into it; treat the output like a Device Manager window opened on their machine.Communitytools

All 15 by Yicheng-Mark

Developer Mode

Explore built-in Hermes toolsets and actions.

HermesAgent

Developer?

Create a Hermes extension for Desktop or agent workflows.

Developer Section