diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 11d66228..a1a212d1 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -93,6 +93,18 @@ holds no credentials. - Do not add GUI-only, TUI-only, CLI-only, or MCP-only network logic. Interfaces should call `netscli-core` or add a missing operation to `Ops`. - Do not weaken safety limits in `ops/` or MCP validation without a separate review. +## Adding A Network Capability + +Moved here from the public docs page `core-library.md`, which is for library +users rather than contributors. + +1. Add the behavior and tests in `netscli-core`. +2. Expose it through `Ops`. +3. Add CLI handling and structured output. +4. Add TUI and desktop app presentation if the workflow fits those interfaces. +5. Add MCP exposure only when an agent use case is clear and safe. +6. Update the result-model docs when output fields change. + ## Contribution Gates Run the narrowest relevant checks while iterating, then the full gate before shipping cross-cutting changes: diff --git a/site/src/content/docs/docs/cli.md b/site/src/content/docs/docs/cli.md index 5e1fbcfb..4b285154 100644 --- a/site/src/content/docs/docs/cli.md +++ b/site/src/content/docs/docs/cli.md @@ -6,7 +6,7 @@ head: content: Command-line network scanner (CLI) | NetsCLI docs --- -The CLI is the best interface for repeatable diagnostics, automation, and machine-readable output. +Use the CLI for repeatable diagnostics, automation, and machine-readable output. ## Common commands @@ -52,10 +52,7 @@ netscli discover --json | jq '.[].ip' ### CSV and Markdown -Commands that return a list also take `--csv`, for a spreadsheet or a script -that wants columns, and `--md`, for a Markdown table to paste into an issue -or a wiki: `discover`, `scan`, `sweep`, `dns`, `ping`, `arp`, `interfaces`, -`mdns` and `pcap`. +Commands that return a list also take `--csv`, for a spreadsheet or a script that wants columns, and `--md`, for a Markdown table to paste into an issue or a wiki. They are `discover`, `scan`, `sweep`, `dns`, `ping`, `arp`, `interfaces`, `mdns` and `pcap`. ```bash netscli discover 192.168.1.0/24 --csv > hosts.csv @@ -93,8 +90,7 @@ $ netscli dns netscli.com --record MX --md ## Example output -Captured from a real run against loopback, so every port reads `filtered` — -nothing is listening on 127.0.0.1 for these ports. A host with services up +Captured from a real run against loopback, so every port reads `filtered`, because nothing is listening on 127.0.0.1 for these ports. A host with services up returns `open` with latency, and a banner where one was offered. ```console @@ -121,8 +117,7 @@ $ netscli scan 127.0.0.1 -p 22,80,443 --json ] ``` -`open` is the compatibility boolean older consumers already read; `status` -carries the four-way answer. Both are present, so a script written against +`open` is the compatibility boolean older consumers already read, and `status` carries the full answer, including `open|filtered` for UDP. Both are present, so a script written against either keeps working. ```console @@ -167,7 +162,7 @@ The CLI exposes shared network operations plus command-line maintenance workflow | --- | --- | | `discover` | Find reachable hosts on a subnet. | | `scan` | Scan TCP ports on one host, or UDP services with `--udp`. | -| `inspect` | Build a host profile from reachability, reverse DNS, and optional ports. | +| `inspect` | Build a host profile with reachability, reverse DNS, MAC address and maker, an OS hint, and optional ports. | | `sweep` | Discover hosts and scan selected ports across them. | | `ping` | Measure reachability and packet loss. | | `trace` | Show route hops to a host. | @@ -194,7 +189,7 @@ netscli dns --help `--concurrency` / `-j` is a global option for limiting in-flight network work. It is useful on fragile gateways or when scanning larger local ranges. -The help output is the source of truth for flags. The docs explain workflow and intent; the binary explains exact syntax. +The help output is the source of truth for flags. The docs explain workflow and intent, and the binary explains exact syntax. ## CLI-only workflows @@ -204,10 +199,9 @@ Some workflows intentionally stay in the command-line interface: - `serve` and `mcp-service` for MCP server launch and supported service management. - Shell completions and manpage generation. -The desktop app exposes shared network operations and result exploration. It does not duplicate maintenance workflows unless they become shared core operations with a clear interactive use case. ## Permissions and limits Raw ICMP, traceroute, and packet capture can require elevated permissions depending on the platform. Port scans and DNS lookups normally do not. -The core library enforces safety limits for subnet size, port count, concurrency, and timeouts. Interface-specific code does not bypass those limits. +Limits on subnet size, port count, concurrency, and timeouts apply the same way in every interface. diff --git a/site/src/content/docs/docs/core-library.md b/site/src/content/docs/docs/core-library.md index 0df2f4e4..bbc13970 100644 --- a/site/src/content/docs/docs/core-library.md +++ b/site/src/content/docs/docs/core-library.md @@ -3,7 +3,7 @@ title: Core library and crates description: NetsCLI Rust crate ownership, core library boundaries, and integration rules. --- -NetsCLI is split into Rust crates and interface apps. `netscli-core` owns network behavior; the CLI, TUI, desktop app, and MCP server call into it rather than carrying separate implementations. +NetsCLI is split into Rust crates and interface apps. `netscli-core` owns network behavior, and the CLI, TUI, desktop app, and MCP server call into it rather than carrying separate implementations. Interface layers use the core `Ops` facade instead of implementing their own probes, packet parsing, DNS behavior, or scan safety logic. @@ -34,17 +34,7 @@ Dependency flow stays one-way: Interface crates may depend on the core. The core must not depend on a UI layer, MCP protocol layer, or desktop runtime. The CLI additionally depends on `netscli-mcp`, because `netscli serve` runs -the MCP server in-process — the one edge between two interface crates. The -diagram previously showed all three as siblings, which made `netscli serve` -look impossible. - -## Ownership rules - -- Put scan, discovery, ping, DNS, ARP, sweep, inspect, stats, database, and packet capture logic in `netscli-core`. -- Expose missing operations through `Ops` so CLI, TUI, desktop app, and MCP all benefit. -- Keep public structures additive when possible. -- Keep safety limits centralized. -- Add core tests when behavior changes. +the MCP server in-process. It is the one dependency between two interface crates. ## Public facade @@ -56,9 +46,6 @@ Most consumers start from `Ops`. | `OpsConfig` | Runtime defaults for scan, ping and DNS timeouts, plus probe concurrency. | | Result structs | Shared data returned by scans, discovery, DNS, ARP, interfaces, sweep, inspect, and packet capture. | -Expose new behavior through the facade so every interface gets the -same capability and the same safety behavior. - Typical integration shape: ```rust @@ -82,9 +69,9 @@ Exact method signatures can change as operations gain richer structured data. Pr | Module | Owns | | --- | --- | -| `scan` | TCP port scanning, status classification, latency, banner, HTTP, and TLS probing. | +| `scan` | TCP and UDP port scanning, status classification, latency, banner, HTTP and TLS probing, and service versions. | | `discover` | Host discovery over a subnet. | -| `inspect` | Host profile data built from reachability, reverse DNS, and port checks. | +| `inspect` | Host profile data built from reachability, reverse DNS, MAC address, port checks, and the OS hint. | | `sweep` | Discovery plus per-host port checks. | | `ping` | Reachability probing, with the ICMP and TCP-connect backends. | | `trace` | Route hops, over the platform trace tool. | @@ -96,36 +83,18 @@ Exact method signatures can change as operations gain richer structured data. Pr | `db` | SQLite persistence for host records and scan history. | | `ops` | Cross-interface operation orchestration and limits. | -## Interface responsibilities - -- CLI: parse arguments and format text, JSON, or YAML. -- TUI: present terminal state and keyboard interactions. -- Desktop app: render app state, tables, settings, details, exports, and Tauri command calls. -- MCP: expose core operations through JSON-RPC tools. -- Tauri backend: bridge desktop app commands to `netscli-core`. - -When adding a new network capability: - -1. Add the behavior and tests in `netscli-core`. -2. Expose it through `Ops`. -3. Add CLI handling and structured output. -4. Add TUI and desktop app presentation if the workflow fits those interfaces. -5. Add MCP exposure only when an agent use case is clear and safe. -6. Update result-model docs when output fields change. - ## Safety limits NetsCLI intentionally limits expensive operations: -- Maximum subnet size: `/16`. -- Maximum ports per scan: `4096`. -- Default concurrency: `256`. -- Default scan timeout: `500 ms`. +- Subnets up to `/16`. +- Up to `4096` ports per scan. +- `256` probes in flight by default. +- A `500 ms` scan timeout by default. -## Compatibility rules +## Contributing -- Change public result structures additively where possible. -- Avoid renaming CLI flags without a breaking-release note. -- Keep MCP tool names and input schemas stable. -- SQLite schema changes require migration planning. -- Desktop-app-only network behavior is not allowed; network logic belongs in the core. +The rules for where new code goes, how a new operation reaches every +interface, and what has to stay compatible are in +[ARCHITECTURE.md](https://github.com/fstubner/netscli/blob/main/docs/ARCHITECTURE.md) +in the repository. diff --git a/site/src/content/docs/docs/desktop.md b/site/src/content/docs/docs/desktop.md index cbf7f9e6..96a4ea45 100644 --- a/site/src/content/docs/docs/desktop.md +++ b/site/src/content/docs/docs/desktop.md @@ -51,7 +51,7 @@ Use the CLI instead when you need setup, doctor, shell completions, manpages, se ## Operation tabs -Tabs show the operation name and a short identifier such as host, subnet, interface, or record name. They do not show the full command; the command preview lives in the command bar. +Tabs show the operation name and a short identifier such as host, subnet, interface, or record name. They do not show the full command. The command preview lives in the command bar. Supported operations include: @@ -98,7 +98,7 @@ The details pane changes when multiple rows are selected. Instead of duplicating The details pane is operation-specific: - Scan rows explain open, closed, filtered, and error states. -- Inspect shows a host overview, checked ports, and raw data. +- Inspect shows a host overview, the MAC address and maker, an OS hint with its clues, checked ports, and raw data. - Discover and Sweep summarize device inventory and exposed services. - DNS shows record values and metadata such as TTL or resolver source when available. - Interfaces shows state, addresses, MAC, selected/default hints, and loopback or virtual hints. @@ -137,12 +137,9 @@ Settings control: ## Updates When the app opens, it checks GitHub for a newer release. If there is one, a -notice appears in the corner. The check fetches one small file and nothing -else; turn it off under **Settings → Release Notifications**. +notice appears in the corner. The check fetches one small file and nothing else. You can turn it off under **Settings → Release Notifications**. -Where the app can update itself, the notice opens a dialog with the new -version's release notes and three choices: **Install and restart**, **Later** -or **Skip this version**. Nothing downloads until you choose to install. The +Where the app can update itself, the notice opens a dialog with the new version's release notes and three choices, **Install and restart**, **Later** or **Skip this version**. Nothing downloads until you choose to install. The update is checked against NetsCLI's signing key before it is installed. On Windows the installer shows a progress bar and may ask for administrator permission, then the app reopens. @@ -156,9 +153,9 @@ These installs update themselves: These installs belong to a package manager, so the notice links to the release page instead and the package manager does the update: -- Scoop: `scoop update netscli-gui` -- The AUR package: your AUR helper -- A `.deb`: install the newer `.deb` +- Scoop updates with `scoop update netscli-gui` +- The AUR package updates through your AUR helper +- A `.deb` updates by installing the newer `.deb` ## Build and runtime availability @@ -166,5 +163,5 @@ Most desktop tools are available in the standard desktop build. Packet capture i - Packet Capture stays in the tool list in every build. Running a capture needs a build that includes packet-capture support, plus Npcap on Windows or libpcap on Linux/macOS. Without those, the tab opens and shows setup guidance instead of running. - mDNS Discovery is included in the standard published desktop build. -- A tool whose feature is genuinely absent from the build is hidden. That applies to mDNS Discovery; Packet Capture is the deliberate exception, because the published installers ship without it and a hidden tab explained nothing. +- In a custom build without mDNS support, mDNS Discovery is hidden. - If a required runtime library is missing, only that feature is unavailable. The rest of the desktop app keeps working and shows setup guidance for the missing dependency. diff --git a/site/src/content/docs/docs/index.md b/site/src/content/docs/docs/index.md index 34ccfe20..dd71d1ad 100644 --- a/site/src/content/docs/docs/index.md +++ b/site/src/content/docs/docs/index.md @@ -3,7 +3,7 @@ title: Overview description: NetsCLI documentation for the shared Rust core, CLI, TUI, desktop app, and MCP server. --- -NetsCLI is a cross-platform network scanner written in Rust. It is built around one shared core library and several interfaces: a desktop app, terminal UI, command-line interface, and MCP server. +NetsCLI is a cross-platform network scanner written in Rust. It is built around one shared core library and four interfaces, a desktop app, a terminal UI, a command-line interface, and an MCP server. The goal is consistency. A port scan, DNS lookup, host inspection, or ARP cache read means the same thing whether you run it from the desktop app, a shell script, the TUI, or an AI agent. @@ -14,8 +14,8 @@ NetsCLI focuses on practical network inspection tasks: | Task | Use this when | | --- | --- | | Discover hosts | You want to find reachable devices on a subnet. | -| Scan TCP ports | You know a host and want port status, latency, service guesses, and optional banner data. | -| Inspect a host | You want a host profile combining reachability, reverse DNS, and optional port checks. | +| Scan ports | You know a host and want TCP or UDP port status, latency, the software and version where a service names itself, and banner data. | +| Inspect a host | You want a host profile with reachability, reverse DNS, MAC address and maker, an OS hint, and optional port checks. | | Sweep a subnet | You want discovery plus exposed services across discovered hosts. | | Query names | You need DNS, reverse DNS, or local mDNS service information. | | Review local inventory | You need local interfaces or the operating system ARP neighbor cache. | @@ -25,13 +25,13 @@ NetsCLI is not intended to replace tools such as nmap or Wireshark for advanced ## Interface model -The core library owns network behavior. Interface layers present the data and workflow that fit their environment instead of reimplementing probes, parsers, or safety limits. +Every interface runs the same core library, so results and limits are the same whichever you use. Each one presents them in the way that suits it. | Interface | Best fit | | --- | --- | | Desktop app | Tabbed workflows, filtering, row details, history, exports, and result review. | | Terminal UI | Keyboard-first interactive diagnostics inside a terminal session. | -| CLI | Repeatable commands, scripts, JSON/YAML output, setup, doctor, and shell workflows. | +| CLI | Repeatable commands, scripts, JSON, YAML, CSV and Markdown output, setup, doctor, and shell workflows. | | MCP server | Structured tools for AI agents that need local network operations. | | Rust core | Applications that want the shared operations directly. | @@ -49,10 +49,10 @@ Interfaces may add confirmations or guidance, but they do not bypass the core li ## Useful starting points -- New to NetsCLI: read [Operations](/docs/operations/) first. -- Installing on Windows, macOS, or Linux: read [Installation](/docs/install/). -- Comparing desktop app, TUI, CLI, and MCP coverage: read [Interface coverage](/docs/interface-coverage/). -- Using the desktop app: read [Desktop app](/docs/desktop/). -- Automating scans or exporting JSON/YAML: read [CLI](/docs/cli/). -- Integrating with agents: read [MCP server](/docs/mcp/). -- Building on the Rust crates: read [Core library and crates](/docs/core-library/). +- If you are new to NetsCLI, start with [Operations](/docs/operations/). +- [Installation](/docs/install/) covers Windows, macOS and Linux. +- [Interface coverage](/docs/interface-coverage/) compares the desktop app, TUI, CLI and MCP server. +- [Desktop app](/docs/desktop/) is the guide to the desktop app. +- [CLI](/docs/cli/) covers automating scans and exporting JSON, YAML, CSV or Markdown. +- [MCP server](/docs/mcp/) covers connecting AI agents. +- [Core library and crates](/docs/core-library/) is for building on the Rust crates. diff --git a/site/src/content/docs/docs/install.md b/site/src/content/docs/docs/install.md index 6a8ce12e..835e368e 100644 --- a/site/src/content/docs/docs/install.md +++ b/site/src/content/docs/docs/install.md @@ -1,6 +1,6 @@ --- title: Installation -description: Install NetsCLI through package managers, direct release artifacts, scripts, or Cargo. +description: Install NetsCLI through package managers, direct downloads, scripts, npm, or Cargo. head: - tag: title content: Install NetsCLI on Windows, macOS and Linux | NetsCLI docs @@ -15,7 +15,9 @@ NetsCLI publishes command-line binaries and desktop installers through GitHub Re | Windows | `winget install netscli` | CLI and TUI | | Windows | `winget install netscli-gui` | Desktop app | | macOS | Homebrew or install script | CLI and TUI | -| Linux | Install script, Homebrew, AUR, or release artifact | CLI and TUI | +| macOS | `brew install --cask fstubner/tap/netscli-gui` | Desktop app | +| Linux | Install script, Homebrew, AUR, or release download | CLI and TUI | +| Linux | `.deb`, AppImage, or `yay -S netscli-gui-bin` | Desktop app | | Rust users | `cargo install netscli` | CLI and TUI from crates.io | | Node users | `npx netscli` | CLI and TUI from npm, no install step | @@ -33,9 +35,8 @@ The desktop app is distributed separately: winget install netscli-gui ``` -Both short names resolve today. The full identifiers are `fstubner.netscli` -and `fstubner.netscli.gui`, and they cannot become ambiguous — use those if a -short name ever matches more than one package in the catalog. +If a short name ever matches more than one package, use the full +identifiers, `fstubner.netscli` and `fstubner.netscli.gui`. Scoop is also supported, for both the CLI and the desktop app: @@ -45,17 +46,18 @@ scoop install netscli scoop install netscli-gui ``` -Or the PowerShell install script, which picks the right asset for your machine: +Or the PowerShell install script, which picks the right download for your machine: ```powershell iwr -useb https://netscli.com/install.ps1 | iex ``` -Direct Windows downloads are attached to GitHub Releases. From 0.3.3 on, both -`.exe` builds and the `.msi` installer are Authenticode-signed, so Windows shows -a named publisher rather than an unknown one. Releases before 0.3.3 are -unsigned. A new certificate still has to build reputation with SmartScreen, -so you may see a warning for a while regardless. +Direct Windows downloads are on the +[releases page](https://github.com/fstubner/netscli/releases/latest). From +0.3.3 on, the `.exe` downloads and the `.msi` installer are signed, so Windows +names the publisher instead of showing an unknown one. From 0.3.4 the desktop +app inside the installer is signed too. While the certificate is new, +SmartScreen may still show a warning the first time you run one. ## macOS @@ -71,7 +73,19 @@ Or use the install script: curl -fsSL https://netscli.com/install.sh | bash ``` -Desktop `.dmg` artifacts are attached to GitHub Releases where the release workflow publishes them. macOS may require the usual first-run approval for unsigned or independently distributed apps. +For the desktop app, use the Homebrew cask: + +```bash +brew install --cask fstubner/tap/netscli-gui +``` + +Or download the `.dmg` for Apple Silicon or Intel from the +[releases page](https://github.com/fstubner/netscli/releases/latest). + +The desktop app is not notarized by Apple, so macOS blocks its first launch, +whichever way you installed it. Open it once, then go to **System Settings → +Privacy & Security** and click **Open Anyway**. You only need to do this once. +(Right-click → Open no longer does this on macOS 15 and later.) ## Linux @@ -93,40 +107,48 @@ On Arch-based systems with an AUR helper: yay -S netscli-bin ``` -Release artifacts may include Linux CLI binaries and desktop packages such as `.deb` or `.AppImage`, depending on the release. +For the desktop app, download the `.deb` (Debian, Ubuntu and derivatives) or +the AppImage (any distribution) from the +[releases page](https://github.com/fstubner/netscli/releases/latest): + +```bash +sudo apt install ./netscli-gui-linux-x86_64.deb +``` + +```bash +chmod +x netscli-gui-linux-x86_64.AppImage +./netscli-gui-linux-x86_64.AppImage +``` + +On Arch-based systems: + +```bash +yay -S netscli-gui-bin +``` ### If the desktop window opens black or blank -On some hosts the window appears but never paints anything. This is -WebKitGTK's hardware compositing failing against a driver that only partly -supports it, and it fails silently, so there is nothing on stderr to go on. -It has been seen on virtual machines using the `vmwgfx` driver. +On some Linux machines the desktop app's window opens but stays black or +blank. It is a graphics driver problem, and has been seen on virtual machines. -**The app should recover by itself.** It notices that a launch never drew -anything and turns hardware compositing off on the next one, so closing the -blank window and opening it again is usually enough. It prints the reason to -stderr when it does this. +**Close the window and open the app again.** The app notices the blank launch +and switches to a safer drawing mode the next time, so the second launch +usually works. -To skip the failed launch, or if the automatic recovery does not fire: +If it is still blank, start it once with: ```bash netscli-gui --disable-gpu-compositing ``` -That is remembered, so later launches from the desktop icon keep it. To undo -it and go back to hardware compositing: +The app remembers this, so later launches from the desktop icon keep working. +To go back to the default: ```bash netscli-gui --gpu-compositing ``` -Compositing is not disabled by default because it costs hardware compositing -for everyone, including the large majority whose drivers handle it correctly. -The `WEBKIT_DISABLE_COMPOSITING_MODE=1` environment variable also still works, -and overrides everything above for that one run. - -This applies to Linux only. Windows and macOS use a different web engine that -has neither the fault nor the setting. +Windows and macOS are not affected, and the two options do nothing there. ## Cargo @@ -163,8 +185,7 @@ What the npm build leaves out: cannot arrange. Use a package from the sections above if you need it. - **The desktop app.** npm installs the CLI and TUI only. -If you mainly want the MCP server, see [MCP server](/docs/mcp/) — the npm -package is one of three ways to connect it. +If you mainly want the MCP server, see [MCP server](/docs/mcp/). The npm package is one of three ways to connect it. ## Updating @@ -188,9 +209,7 @@ Update a Homebrew install: brew upgrade netscli ``` -The desktop app can also update itself from 0.3.4 on. It checks for a new -release when it opens and offers to install it; see -[Updates](/docs/desktop/#updates) for which installs can do this. +The desktop app can also update itself from 0.3.4 on. It checks for a new release when it opens and offers to install it. See [Updates](/docs/desktop/#updates) for which installs can do this. Update a global npm install: @@ -201,7 +220,7 @@ npm update -g netscli `npx netscli` may reuse a copy it has cached. To be sure you get the newest release, run `npx netscli@latest`. -For direct release artifacts, download the [latest GitHub release](https://github.com/fstubner/netscli/releases/latest) and replace the previous install with the matching package for your platform. +For a direct download, get the [latest GitHub release](https://github.com/fstubner/netscli/releases/latest) and replace the previous install with the matching package for your platform. ## Verifying a download @@ -212,8 +231,7 @@ checked before you run anything. Each asset ships a `.sha256` sidecar next to it on the release page. The install scripts fetch and check it for you, and refuse to install if it is -missing — a failed checksum request is not treated as permission to skip -verification. To check a manual download yourself: +missing. To check a manual download yourself: ```bash # Linux / macOS @@ -234,10 +252,10 @@ A checksum only proves the file matches its own sidecar, and both come from the same place. The signature is what ties the asset to the workflow run that built it. -Every asset is signed keylessly with [Sigstore -cosign](https://docs.sigstore.dev/cosign/overview/) in CI, using the GitHub -Actions OIDC identity — no key management, and the signature is bound to the -exact run. Each asset ships a `.sig` and a `.pem` beside it: +Every asset is signed with [Sigstore +cosign](https://docs.sigstore.dev/cosign/overview/) by the release workflow, +and the signature is tied to the exact run that built it. Each asset ships a +`.sig` and a `.pem` beside it: ```bash cosign verify-blob \ @@ -248,22 +266,19 @@ cosign verify-blob \ netscli-linux-x86_64 ``` -Substitute the asset name you downloaded — the same command works for the -desktop `.msi`, `.dmg`, `.deb` and `.AppImage`. It needs the [cosign +Substitute the asset name you downloaded. The same command works for the desktop `.msi`, `.dmg`, `.deb` and `.AppImage`. It needs the [cosign CLI](https://docs.sigstore.dev/cosign/system_config/installation/). A pass confirms the asset was built and signed by this repository's release workflow and has not been altered since. -This is separate from platform code signing. From 0.3.3 on, the Windows -executables and installer also carry an Authenticode signature. The macOS -`.dmg` is not notarized yet. See the Windows and macOS sections above for -what your OS will say on first run. +This is separate from the code signing Windows and macOS check. The Windows +downloads carry a Windows signature from 0.3.3 on, and the macOS app is not +notarized. See the Windows and macOS sections above for what your system will +say on first run. ## Packet capture -**None of the installs above include packet capture.** It is a compile-time feature, and the default builds — the desktop installers, the standard CLI release assets, and `cargo install netscli` — are built without it. That keeps the default install free of any libpcap/Npcap dependency and avoids redistributing Npcap. - -Getting it is a deliberate extra step, and the rest of this section is how. +**None of the installs above include packet capture.** The desktop installers, the standard CLI downloads, and `cargo install netscli` are all built without it, so none of them needs libpcap or Npcap. The rest of this section is how to get a build that has it. Normal scan, discovery, DNS, ARP, ping, trace, and interface workflows are unaffected and need none of this. @@ -271,7 +286,7 @@ If you do want packet capture, you need **both** a build that has the feature co ### CLI with packet capture -The install script does both at once — it selects the `-pcap` build *and* installs the system library: +The install script does both at once. It selects the `-pcap` build *and* installs the system library. ```bash curl -fsSL https://netscli.com/install.sh | NETSCLI_PCAP=1 bash @@ -283,7 +298,7 @@ $env:NETSCLI_PCAP=1; iwr -useb https://netscli.com/install.ps1 | iex On Windows this runs the Npcap installer, which needs administrator rights. Add `NETSCLI_SKIP_NPCAP=1` (or `NETSCLI_SKIP_LIBPCAP=1` on Unix) if you manage the capture library yourself. -Alternatively, download the `-pcap` asset directly from the [latest release](https://github.com/fstubner/netscli/releases/latest) — `netscli-linux-x86_64-pcap`, `netscli-macos-aarch64-pcap`, `netscli-windows-x86_64-pcap.exe`, and so on — and install the capture library separately. There is no `-pcap` musl build. +Alternatively, download the `-pcap` asset directly from the [latest release](https://github.com/fstubner/netscli/releases/latest) (`netscli-linux-x86_64-pcap`, `netscli-macos-aarch64-pcap`, `netscli-windows-x86_64-pcap.exe`, and so on) and install the capture library separately. There is no `-pcap` musl build. Or build it yourself, which needs the development headers (`libpcap-dev` on Debian/Ubuntu, or the [Npcap SDK](https://npcap.com/#download) on Windows): @@ -305,7 +320,7 @@ npm run tauri build -- --features pcap | Platform | Requirement | | --- | --- | -| Windows | Npcap installed. `wpcap.dll` lives in `C:\Windows\System32\Npcap\`, which is not on `PATH` by default — add it, or let `NETSCLI_PCAP=1` do it. | +| Windows | Npcap installed. `wpcap.dll` lives in `C:\Windows\System32\Npcap\`, which is not on `PATH` by default. Add it, or let `NETSCLI_PCAP=1` do it. | | Linux | libpcap installed, plus capture permissions (`CAP_NET_RAW` or root). | | macOS | libpcap available, plus capture permissions where required. | @@ -317,4 +332,4 @@ npm run tauri build -- --features pcap netscli doctor ``` -Note that `netscli pcap --check` only exists on builds that were compiled with the feature — on a standard build the subcommand is absent entirely and you will get an "unrecognized subcommand" error rather than a useful message. Use `doctor` to find out which build you have. +Note that `netscli pcap --check` only exists on builds that were compiled with the feature. On a standard build the subcommand is absent entirely, and you will get an "unrecognized subcommand" error rather than a useful message. Use `doctor` to find out which build you have. diff --git a/site/src/content/docs/docs/interface-coverage.md b/site/src/content/docs/docs/interface-coverage.md index ad0a2ca3..921da621 100644 --- a/site/src/content/docs/docs/interface-coverage.md +++ b/site/src/content/docs/docs/interface-coverage.md @@ -3,20 +3,17 @@ title: Interface coverage description: What NetsCLI exposes in the desktop app, CLI, TUI, MCP server, and packet-capture builds. --- -One Rust core library sits under everything NetsCLI offers. Shared network -behaviour belongs in the core; each surface exposes the parts that suit how -it is used. +All four NetsCLI interfaces run the same network code, so a scan means the +same thing in each. Each one exposes the parts that suit how it is used. -## What the surfaces actually are +## What the four interfaces are **Three of the four are the same binary.** `netscli` with a command is the CLI, `netscli` with no command opens the terminal UI, and `netscli serve` starts the MCP server. Installing the CLI installs all three. The desktop app is a separate download built on the same core. -That matters when reading the table below: a dash in the MCP column does not -mean you need another install to get that capability, only that the MCP -server does not expose it as a tool. +So a dash in the MCP column of the table below does not mean you need another install to get that capability, only that the MCP server does not expose it as a tool. ## Coverage matrix @@ -49,47 +46,38 @@ server does not expose it as a tool. ### Notes on the dashes -- **Trace route** has no MCP tool. Everything else it needs is in the core, - so this is a gap rather than a decision. +- **Trace route** has no MCP tool yet. - **Reverse DNS** on the MCP server means asking `dns_lookup` for a `PTR` record, which works but wants the `in-addr.arpa` name rather than an address. The other three take an address directly. - **Changing the ARP table** needs administrator rights and edits machine - state, which is not something to hand an agent. The desktop app offers - clearing only; the CLI and TUI also add and delete single entries. + state, which is not something to hand an agent. The desktop app offers clearing only, and the CLI and TUI also add and delete single entries. - **Result bundles** are the desktop app's own save format, for reopening a - run later. The equivalent elsewhere is structured output: `--json`, - `--yaml`, `--csv` and `--md` on the CLI, `/export` in the TUI, JSON-RPC results - over MCP. + run later. The equivalent elsewhere is structured output, meaning `--json`, `--yaml`, `--csv` and `--md` on the CLI, `/export` in the TUI, and JSON-RPC results over MCP. - **First-run setup** (`netscli setup`) and **diagnostics** - (`netscli doctor`) are two different commands and used to share a row here. - Setup is an interactive wizard; doctor is a headless report that works on - every build and is the way to find out what your build can do. + (`netscli doctor`) are two different commands. Setup is an interactive + wizard. Doctor is a report that works on every build and tells you what + your build can do. ### Notes on the ticks -- **Packet capture** needs a build compiled with the feature *and* the system - capture library — Npcap on Windows, libpcap elsewhere. No *default* install - has it: the desktop installers, the standard CLI assets and - `cargo install netscli` are all built without it. Each release does publish +- **Packet capture** needs a build compiled with the feature *and* the system capture library (Npcap on Windows, libpcap elsewhere). No *default* install has it. The desktop installers, the standard CLI assets and `cargo install netscli` are all built without it. Each release does publish separate `-pcap` CLI assets that have it compiled in. See [Installation](/docs/install/#packet-capture). -- **Structured output** means something different on each surface, which is - why it is one row rather than four: the desktop app exports files and +- **Structured output** means something different on each interface. The + desktop app exports files and result bundles, the CLI takes `--json`, `--yaml`, `--csv` and `--md`, the TUI exports a session with `/export`, and the MCP server returns JSON-RPC results. ## Desktop app -Interactive network work: tabs, filtering, row selection, a details pane, -history, exports, and local status indicators. It exposes the shared +Interactive network work, with tabs, filtering, row selection, a details pane, history, exports, and local status indicators. It exposes the shared operations where a table or a details pane earns its place. -Shell maintenance — setup, doctor, completions, man pages, MCP service -management — stays in the CLI, because none of it benefits from a window. +Shell maintenance (setup, doctor, completions, man pages, MCP service management) stays in the CLI, because none of it benefits from a window. -## CLI — `netscli ` +## CLI (`netscli `) Every shared network operation, plus the workflows that only make sense at a prompt: @@ -102,7 +90,7 @@ prompt: manage it as a system service where that is supported. - `netscli completions` and `netscli man`. -## TUI — `netscli` with no command +## TUI (`netscli` with no command) The same operations, driven from a terminal with slash commands (`/discover`, `/scan`, `/inspect`, and the rest) rather than arguments. It favours readable @@ -112,13 +100,12 @@ JSON with `/export`. It is the same binary as the CLI, so anything installed for one is installed for the other. -## MCP server — `netscli serve` +## MCP server (`netscli serve`) Exposes the shared operations to AI-agent clients as MCP tools. Also the same binary. -Results are bounded before they reach a model: the full probe response is -dropped, banners and packet summaries are truncated, and an oversized result +Results are bounded before they reach a model. The full probe response is dropped, banners and packet summaries are truncated, and an oversized result is cut with a count of what was left out. A scanned host's banner is bytes that host chose, and a model reads tool output as instructions. @@ -128,5 +115,5 @@ Most NetsCLI operations work in the standard published builds. A few capabilitie - Packet capture runs only on builds that include packet-capture support, and also needs Npcap on Windows or libpcap on Linux/macOS. On the CLI the `pcap` subcommand is absent from standard builds. - mDNS discovery is included in the published CLI, desktop app, and MCP server. Library consumers can still build `netscli-core` without the `mdns` feature if they need a leaner dependency set. -- The desktop app keeps Packet Capture visible in builds without capture support — greyed, with an explanation of what it needs — rather than hiding it. A tool that vanishes leaves nowhere to explain why. +- The desktop app keeps Packet Capture in its tool list in builds without capture support, with a note saying what it needs. Opening it shows setup guidance, and it cannot be run. - If a runtime dependency is missing, NetsCLI keeps the rest of the app usable and explains what to install for that feature. diff --git a/site/src/content/docs/docs/mcp.md b/site/src/content/docs/docs/mcp.md index b1a800da..d1d806de 100644 --- a/site/src/content/docs/docs/mcp.md +++ b/site/src/content/docs/docs/mcp.md @@ -29,8 +29,7 @@ Point the client at the binary you have. ``` This is the one to prefer. You get the version you installed rather than -whatever is newest, there is no second copy of the binary, and packet -capture works — the other two routes cannot offer it. +whatever is newest, there is no second copy of the binary, and packet capture works, which the other two routes cannot offer. If the client cannot find `netscli`, give the full path instead. A GUI client often has a different PATH from your shell. @@ -49,9 +48,8 @@ client often has a different PATH from your shell. ``` npm fetches the prebuilt binary for your platform on first launch. You need -Node 18 or newer. Which version runs is up to npx: it may pick up a newer -release or reuse one it has cached, so the version can differ from the one -you have elsewhere. Write `netscli@0.3.3` in the args to pin one. The npm +Node 18 or newer. Which version runs is up to npx. It may pick up a newer release or reuse one it has cached, so the version can differ from the one +you have elsewhere. Write `netscli@` in the args to pin one. The npm builds leave out packet capture, because it needs libpcap or Npcap present on the machine. @@ -59,16 +57,13 @@ the machine. Download the `.mcpb` bundle for your platform from the [latest release](https://github.com/fstubner/netscli/releases/latest) and -open it with a client that supports MCP bundles. The bundle carries the -binary, so nothing else is needed — no PATH entry, no Node. +open it with a client that supports MCP bundles. The bundle carries the binary, so nothing else is needed, no PATH entry and no Node. -Bundles are named `netscli---.mcpb`. Pick the one -matching your machine; the format has no way to check that for you, and the +Bundles are named `netscli---.mcpb`. Pick the one matching your machine. The format has no way to check that for you, and the wrong architecture will simply fail to start. The install prompt includes a switch for scanning beyond your local -networks. Leave it off unless you know you need it — see -[Reaching past your local network](#reaching-past-your-local-network). +networks. Leave it off unless you know you need it. See [Reaching past your local network](#reaching-past-your-local-network). ## Run it yourself @@ -88,7 +83,7 @@ there is nothing to look at until a client connects. | `ping_host` | Check reachability and latency. | | `dns_lookup` | Query DNS records. | | `get_arp_table` | Read the local ARP neighbor cache. | -| `inspect_host` | Build a host profile from reachability, DNS, and ports. | +| `inspect_host` | Build a host profile with reachability, DNS, MAC address and maker, an OS hint, and ports. | | `sweep_network` | Discover hosts and scan selected ports. | | `list_network_interfaces` | List local network interfaces. | | `discover_mdns` | Discover local mDNS/DNS-SD services. | @@ -101,9 +96,7 @@ Tool inputs stay stable. Structured output may gain additive fields as the share ## A request and its response -Captured from a real session against loopback. The client writes one JSON -object per line to stdin; the server answers on stdout. Most clients do this -for you — this is what they are exchanging. +Captured from a real session against loopback. The client writes one JSON object per line to stdin, and the server answers on stdout. Most clients do this for you, and this is what they are exchanging. Opening the connection: @@ -148,7 +141,7 @@ server down, which is why a client that exits mid-scan leaves nothing behind. Packet-capture tools appear only in MCP builds that include packet-capture support. Captures also need Npcap on Windows or libpcap on Linux/macOS. Supported builds expose two packet-capture styles. -Use the job-style flow by default: start the capture, poll status, then fetch the completed result. This avoids MCP client and stdio transport timeouts when captures run longer than expected. +Use the job-style flow by default. Start the capture, poll status, then fetch the completed result. This avoids MCP client and stdio transport timeouts when captures run longer than expected. | Flow | Use this when | | --- | --- | @@ -165,15 +158,12 @@ Because an MCP client can trigger local network operations, connect it only to c ### Reaching past your local network -By default this server refuses any target outside your own networks — -private ranges, loopback, link-local, and carrier-grade NAT, which covers -Tailscale and similar overlays. Ask it to scan a public address and it +By default this server refuses any target outside your own networks. That means private ranges, loopback, link-local, and carrier-grade NAT, which covers Tailscale and similar overlays. Ask it to scan a public address and it returns an error rather than sending packets. Every other part of netscli does what you type. This one is driven by a model, which may be reading a web page, an issue comment, or a file someone -else wrote, so the instruction to scan a stranger can arrive from outside -you entirely — and the packets still leave from your machine and your IP. +else wrote, so the instruction to scan a stranger can arrive from outside you entirely, and the packets still leave from your machine and your IP. Scanning public hosts you are responsible for is a fair reason to lift it: @@ -185,13 +175,11 @@ In a client config, set it in the server's `env` block. In an `.mcpb` bundle it is the switch shown when you install. This is a policy layer, not a security boundary. It stops a model being -steered into scanning strangers. It does not stop you, and it is not meant -to — the size limits on subnets, ports and concurrency are separate and -still apply either way. +steered into scanning strangers. It does not stop you, and it is not meant to. The size limits on subnets, ports and concurrency are separate and still apply either way. ## What stays CLI-only -MCP service installation, environment checks, setup, doctor, shell completions, and manpage generation are CLI workflows. They are not exposed in NetsCLI Desktop and do not need MCP tools unless they become shared core operations with a clear agent use case. +MCP service installation, environment checks, setup, doctor, shell completions, and manpage generation are CLI workflows. They are not available as MCP tools or in NetsCLI Desktop. ## Troubleshooting diff --git a/site/src/content/docs/docs/operations.md b/site/src/content/docs/docs/operations.md index a2f7bd51..6d051a4f 100644 --- a/site/src/content/docs/docs/operations.md +++ b/site/src/content/docs/docs/operations.md @@ -31,11 +31,11 @@ Use `discover` when you want an inventory of reachable hosts on a subnet. netscli discover 192.168.1.0/24 ``` -Discovery focuses on host-level data: IP address, hostname when available, MAC address, vendor, and response time. It does not scan service ports. Use `sweep` when you also need exposed services. +Discovery focuses on host-level data, meaning IP address, hostname when available, MAC address, vendor, and response time. It does not scan service ports. Use `sweep` when you also need exposed services. ## Scan -Use `scan` when you already know the host and want TCP port status. +Use `scan` when you already know the host and want TCP port status. For UDP, see below. ```bash netscli scan 192.168.1.1 -p 22,80,443 @@ -47,18 +47,16 @@ Port statuses are: | Status | Meaning | | --- | --- | -| `open` | TCP connect succeeded. NetsCLI may attempt bounded banner, HTTP, or TLS enrichment. | +| `open` | TCP connect succeeded. NetsCLI then reads what the service sends back (a banner, an HTTP response, TLS details) and, where the service names itself, its software and version. | | `closed` | The host actively refused the TCP connection. | | `filtered` | The TCP connect attempt timed out or was blocked before connect. | | `error` | NetsCLI hit an unexpected probe error. | -`filtered` is intentionally technical. It usually means a firewall, router, host policy, or dropped packet prevented a definitive open or closed answer. +`filtered` usually means a firewall, router, host policy, or dropped packet prevented a definitive open or closed answer. ### UDP -Add `--udp` to probe UDP instead. With no port list it checks the services -that answer an unauthenticated request on most networks: DNS (53), NTP (123), -NetBIOS (137), SSDP (1900) and mDNS (5353). +Add `--udp` to probe UDP instead. With no port list it checks the services that answer an unauthenticated request on most networks, DNS (53), NTP (123), NetBIOS (137), SSDP (1900) and mDNS (5353). ```bash netscli scan 192.168.1.254 --udp @@ -66,8 +64,7 @@ netscli scan 192.168.1.254 --udp -p 53,123 ``` UDP has no handshake, so a port only answers a request its service -understands. Each of those ports gets the request its service expects; any -other port you list gets an empty datagram. Ports read as `53/udp`, and the +understands. Each of those ports gets the request its service expects, and any other port you list gets an empty datagram. Ports read as `53/udp`, and the statuses mean something slightly different:
@@ -79,8 +76,7 @@ statuses mean something slightly different: | `open\|filtered` | No reply and no refusal. The service may be there and ignored the probe, or a firewall dropped it. UDP can't tell those apart. | | `error` | NetsCLI hit an unexpected probe error. | -UDP scanning needs no administrator rights. SNMP isn't probed: getting an -answer means sending the default community string `public`, which some +UDP scanning needs no administrator rights. SNMP isn't probed, because getting an answer means sending the default community string `public`, which some networks log as a login attempt. ## Inspect @@ -118,17 +114,15 @@ OS: Windows 11 or Server 2025 (build 26100) (hint) | Clue | What it says | | --- | --- | -| SMB | A Windows host states its exact version, build and computer name at the start of an SMB connection, before any login. Inspect asks port 445 for it whether or not 445 is in your port list; no credentials are sent. | -| SSH banner | OpenSSH usually names the distribution: `Ubuntu`, `Debian`, `Raspbian`, `FreeBSD`, or `for_Windows`. | +| SMB | A Windows host states its exact version, build and computer name at the start of an SMB connection, before any login. Inspect asks port 445 for it whether or not 445 is in your port list. No credentials are sent. | +| SSH banner | OpenSSH usually names the distribution, such as `Ubuntu`, `Debian`, `Raspbian`, `FreeBSD`, or `for_Windows`. | | HTTP server | `(Ubuntu)`, `(Debian)` and similar in a `Server` header, or IIS, which only runs on Windows. | | Open ports | 135 and 445 together are Windows' RPC and file sharing. | | MAC vendor | An Apple or Raspberry Pi network card. | | Ping TTL | Hosts start at 64 (Linux, macOS, most Unix), 128 (Windows) or 255 (network equipment). Only Windows reports the TTL today. | The strongest clue sets the family and the rest are listed under it, including -any that disagree. It is a hint, not a fingerprint: nmap's `-O` sends crafted -packets and needs administrator rights; this needs neither, and a host can -still run anything behind any of these clues. +any that disagree. It is a hint, not a fingerprint. nmap's `-O` sends crafted packets and needs administrator rights. This needs neither, and a host can still run anything behind any of these clues. ## Sweep @@ -150,7 +144,7 @@ Use `ping` for a quick reachability and packet-loss summary. netscli ping 192.168.1.1 --count 4 ``` -The result summarizes sent packets, received packets, packet loss, and RTT values. Raw ICMP may require elevated permissions on some platforms; NetsCLI can fall back to TCP-based reachability where appropriate. +The result summarizes sent packets, received packets, packet loss, and RTT values. Raw ICMP may require elevated permissions on some platforms. Without them, NetsCLI checks reachability with a TCP connection instead. ## Trace route @@ -210,4 +204,4 @@ Packet capture is optional and requires a build with packet-capture support plus netscli pcap --interface "Eth 2.5G" --duration 5 --max-packets 1000 ``` -NetsCLI can summarize captured packets into practical rows: number, time, source, destination, protocol, length, and info. It is not a Wireshark replacement, but it gives enough structure to inspect small captures from the CLI or desktop app. +NetsCLI can summarize captured packets into practical rows with number, time, source, destination, protocol, length, and info. It is not a Wireshark replacement, but it gives enough structure to inspect small captures from the CLI or desktop app. diff --git a/site/src/content/docs/docs/packet-capture.md b/site/src/content/docs/docs/packet-capture.md index 4e0f6890..db25277f 100644 --- a/site/src/content/docs/docs/packet-capture.md +++ b/site/src/content/docs/docs/packet-capture.md @@ -6,7 +6,7 @@ description: NetsCLI packet capture support, runtime requirements, output format Packet capture is optional. It needs a build with packet-capture support and a system packet-capture library. :::caution[The default builds have no packet capture] -It is a compile-time feature. The desktop installers, the standard CLI release assets, and `cargo install netscli` are all built without it, so nothing on this page will work until you install a capture-capable build. The `-pcap` CLI assets on each release *are* built with it — see [Packet capture in the install guide](/docs/install/#packet-capture) for the three ways to get one. +The desktop installers, the standard CLI downloads, and `cargo install netscli` are all built without it, so nothing on this page will work until you install a capture-capable build. The `-pcap` CLI assets on each release *are* built with it. See [Packet capture in the install guide](/docs/install/#packet-capture) for the three ways to get one. Run `netscli doctor` to check which build you have. It works on every build, unlike `netscli pcap --check` below. ::: @@ -25,7 +25,7 @@ The Packet Capture tool stays visible in the desktop app either way. If the buil ## CLI Capture -List available capture devices. This subcommand only exists on capture-capable builds — on a standard build clap reports an unrecognized subcommand, so use `netscli doctor` if you are checking which build you have: +List available capture devices. This subcommand only exists on capture-capable builds. A standard build answers with an "unrecognized subcommand" error, so use `netscli doctor` if you are checking which build you have. ```bash netscli pcap --check @@ -84,7 +84,7 @@ Expected workflow: 5. Inspect selected packet fields and raw preview in the details pane. 6. Open the capture file or containing folder when a file was written. -Save behavior follows the global save settings: default save folder or ask where to save. +Save behavior follows the global save settings, either the default save folder or asking where to save. ## What it is not diff --git a/site/src/content/docs/docs/result-model.md b/site/src/content/docs/docs/result-model.md index 1d776757..5f886614 100644 --- a/site/src/content/docs/docs/result-model.md +++ b/site/src/content/docs/docs/result-model.md @@ -23,12 +23,12 @@ Port scans include the existing compatibility fields plus richer status data. | Field | Meaning | | --- | --- | | `port` | Port number. | -| `protocol` | `tcp` or `udp`. Results from before UDP scanning have no other kind. | +| `protocol` | `tcp` or `udp`. | | `open` | Compatibility boolean for older consumers. | | `service` | Best-effort service guess, from the port number. | -| `product` | The software on the port, when it named itself: from the SSH identification line, an HTTP `Server` header, an FTP or mail greeting, or MySQL's connection greeting; or when it answered the one read-only question netscli asks Redis (`INFO server`) and Memcached (`version`). Omitted otherwise. | +| `product` | The software on the port, when it named itself in the SSH identification line, an HTTP `Server` header, an FTP or mail greeting, or MySQL's connection greeting, or when it answered the one read-only question netscli asks Redis (`INFO server`) and Memcached (`version`). Omitted otherwise. | | `version` | That software's version, when it gave one (`9.6p1` for OpenSSH). Omitted otherwise. | -| `status` | `open`, `closed`, `filtered`, or `error`; for UDP also `open\|filtered`, meaning no reply and no refusal. | +| `status` | `open`, `closed`, `filtered`, or `error`, and for UDP also `open\|filtered`, meaning no reply and no refusal. | | `latency_ms` | TCP connect/probe latency where available. | | `banner` | Bounded plaintext banner when captured. | | `http` | HTTP status/header data when a HTTP-like probe succeeds. | @@ -41,9 +41,7 @@ Port scans include the existing compatibility fields plus richer status data. Banner, HTTP, TLS, and raw preview data are probe results. They are useful diagnostics, not proof that a service is trustworthy. `product` and `version` come only from what the service said about itself, -so they are exactly as trustworthy as that: a server -can claim any name, and many hide their version on purpose. A port with no -`product` didn't name itself; it doesn't mean nothing is there. +so they are exactly as trustworthy as that. A server can claim any name, and many hide their version on purpose. A port with no `product` didn't name itself, which doesn't mean nothing is there. ## Host inventory @@ -56,7 +54,7 @@ Discovery and sweep results describe hosts. A host row carries: | `ip` | Host address. | | `hostname` | Reverse DNS, LLMNR/NetBIOS, or the host's own mDNS name when available. | | `mac` | MAC address when present in ARP/vendor data. | -| `vendor` | OUI vendor lookup. | +| `vendor` | Network card maker, looked up from the MAC address. | | `rtt_ms` | Reachability latency. | | `found_by` | Which probe found the host. | | `hostname_source` | Where `hostname` came from: `reverse` or `mdns`. Absent when the host has no name. | @@ -87,10 +85,6 @@ the ports found open on it, so the host fields are one level down: netscli sweep 192.168.1.0/24 -p 22,80,443 --json | jq '.[].host.ip' ``` -This page used to list `open_ports` in the table above as a "sweep-only" -field, which read as though it sat beside `ip`. It does not, on any surface — -the CLI and the MCP `sweep_network` tool both serialize the nested form. - ## DNS records DNS records expose type and value first, then additive metadata when the resolver provides it. @@ -118,7 +112,7 @@ Inspect is a host profile. It combines host-level data with optional port scan d | `host` | Original target. | | `ip` | Resolved IP address. | | `hostname` | Reverse DNS name when available. | -| `ping` | Reachability object with `alive`, `method`, `rtt_ms`, `seq`, and optional `error` and `ttl` (the reply's time-to-live, where the platform reports it; Windows does). | +| `ping` | Reachability object with `alive`, `method`, `rtt_ms`, `seq`, and optional `error` and `ttl` (the reply's time-to-live, where the platform reports it, which Windows does). | | `ports` | Port scan rows using the same model as `scan`. | | `open_ports` | Convenience list containing only open port rows. | | `mac`, `vendor` | From the local ARP table, so only for a host on the same network segment. | @@ -143,8 +137,7 @@ mDNS/DNS-SD returns service announcements rather than generic host rows. A singl Interface rows describe local network interfaces. ARP rows describe the local neighbor cache. These are two different shapes, and unlike everywhere else on -this page, the desktop app does not show them under the field names the data -carries — so both are given here. +this page, the desktop app does not show them under the field names the data carries, so both are given here. ### Interfaces @@ -156,11 +149,10 @@ carries — so both are given here. | `ips` | Addresses | Addresses, with prefix length. | | `mac` | MAC | MAC address when available. | | `is_up` | State | Whether the interface is up. | -| `is_loopback` | — | Whether the interface is loopback. | +| `is_loopback` | None | Whether the interface is loopback. | `is_up` and `is_loopback` are booleans in the data. The desktop app renders -the first as `up` or `down`, and has no column for the second — it feeds the -**Kind** column instead, which has no field of its own and shows `loopback`, +the first as `up` or `down`, and has no column for the second. It feeds the **Kind** column instead, which has no field of its own and shows `loopback`, `virtual`, `vpn` or `physical`, derived from `is_loopback` and the name. ### ARP entries @@ -172,18 +164,11 @@ the first as `up` or `down`, and has no column for the second — it feeds the | `ip` | IP | Neighbor address. | | `mac` | MAC | Neighbor MAC address. | | `interface` | Interface | Interface it was learned on. | -| `vendor` | Vendor | OUI vendor lookup for the MAC. | +| `vendor` | Vendor | Network card maker, looked up from the MAC address. | Take the first column when reading `--json`, `--yaml` or MCP output, and the second when reading the desktop table. -This section previously merged the two shapes into one list and gave -`addresses`, `state` and `loopback` as field names. None of the three is a -field: `addresses` is a column *header* over `ips`, `state` is a desktop row -key derived from `is_up`, and `loopback` is a desktop row key that is not even -shown as a column. `vendor` was also listed as though it applied to -interfaces, which it does not. - ARP is not full discovery. It reports entries already known to the operating system. ## Packet capture results diff --git a/site/src/content/docs/docs/tui.md b/site/src/content/docs/docs/tui.md index de135877..c904d5be 100644 --- a/site/src/content/docs/docs/tui.md +++ b/site/src/content/docs/docs/tui.md @@ -21,7 +21,7 @@ Use the TUI when: - You want command history, autocomplete, and readable summaries in one screen. - You are iterating on targets and ports by hand. -Use the CLI when a script needs JSON/YAML. Use the desktop app when you need richer tables, filtering, multi-tab review, or row details. +Use the CLI when a script needs JSON, YAML, CSV or Markdown. Use the desktop app when you need richer tables, filtering, multi-tab review, or row details. ## Start the TUI