@eyeauras/insight-cli 0.2.0 → 0.2.1

package/skills/insight-tshark/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: insight-tshark
+description: Inspect an offline PCAP or PCAPNG with insight-cli tshark to identify protocols, HTTP/DNS/TLS fields, packet evidence and reconstructed TCP/UDP streams. Use for captured traffic questions; live acquisition and TLS decryption are separate tasks.
+---
+
+# Insight TShark 0.2.1
+
+If local help/status reports AppData or IPC access denied, retry that **read-only probe**
+with the agent host's normal permission escalation, then use that route for later authorized
+CLI calls too. An explicit **no command was sent** denial is known undispatched and can be
+retried through that route. Keep HOME, profile and owner state; see
+[host execution permissions](references/agent-execution.md). A lost mutation reply needs
+request/status recovery, never blind retry.
+
+Keep the project's evidence format. This tool reads an immutable capture; it does not
+start packet capture, install BPF helpers, change network settings or contact DNS servers.
+The delivered native profile is macOS ARM64, macOS 14+.
+
+1. `insight-cli tshark status --json` checks readiness. `tshark install` delivers the
+   pinned console subset and full notices from our GitHub Release. `download` caches it;
+   `install --archive tshark-4.6.9-macos-console.tgz --offline` uses local bytes.
+   `install --executable /Applications/Wireshark.app/Contents/MacOS/tshark` accepts the
+   exact pinned 4.6.9 runtime. It copies only known console/data files into owned storage,
+   excluding external GUI/plugins; it fingerprints the original and owned family.
+   Uninstall preserves the external distribution, original capture and saved research.
+2. Start with `tshark inspect traffic.pcap --json`. The returned target identifies the
+   captured bytes. Overview counts protocols and streams. `--view packets --filter
+   'http.request' --limit 20` returns actual frame numbers and selected protocol fields;
+   `--view streams` returns native TCP/UDP stream IDs and participating IPs/frame numbers.
+   Address lists may include encapsulated layers; they are not asserted endpoint pairs.
+3. Follow evidence with `tshark inspect --target TARGET --view packet --frame 4 --json`
+   for full native packet JSON, or `--view follow --transport tcp --stream 0 --json` for
+   ordered native reassembly chunks. Follow returns endpoint labels, chunk direction and
+   hex bytes. Decode bytes with any suitable external tool and keep the frame/stream and
+   input SHA alongside the conclusion. Stream IDs belong to one capture revision.
+4. Inventory/filters/follow inspect at most the first 10000 frames of an input up to
+   64 MiB. `complete: false` means later frames and absent matches remain unknown.
+   Pagination applies after the display filter; it does not extend that read boundary.
+   Packet view reads up to its explicit frame (maximum one million), without claiming
+   whole-capture coverage. Follow has no display filter; use its native stream ID.
+   Native output/deadlines remain bounded. Encrypted or missing traffic is not evidence
+   of absent application behavior; no arbitrary tap, Lua script or TLS key is executed.
+5. `--output research/protocol.json` saves the full bounded view to a new ordinary file;
+   existing files are preserved. Use `artifacts save` when a checkpoint is useful.
+   `tools processes --tool tshark --all` retains native run diagnostics. Stop/kill only
+   owned process records; a failed read is not automatically replayed or recollected.
+
+Generated `tshark inspect --help` owns exact flags. For packet filters, Wireshark's display
+filter language applies; it is not a capture/BPF filter.

package/skills/insight-tshark/references/agent-execution.md

@@ -0,0 +1,36 @@
+# Agent host execution permissions
+
+Keep the user/project host policy and the selected profile. A sandbox can deny writes
+to runtime AppData or access to the local IPC endpoint, including during local help.
+This is a host execution boundary, not evidence that the tool or its inputs are absent.
+
+First retry only `insight-cli --help`, `tools list`, `skill`, or the selected application's
+read-only `status` using the host's normal permission escalation. In Codex, use the
+execution tool's `sandbox_permissions: "require_escalated"` with a scoped explanation
+that the installed CLI needs its existing profile storage/local IPC. Automatic approval
+review or the user decides that request; do not disable the sandbox or approval policy.
+
+Do not work around this by changing HOME/AppData/profile paths, creating another host,
+deleting owner/endpoint files, killing unrelated processes or claiming a missing runtime.
+After the read-only probe succeeds, use the approved execution route for the intended
+public CLI commands. An access refusal explicitly stating **no command was sent** is
+known not dispatched; it is safe to submit that authorized command through the approved
+route. This includes a mutation refused before dispatch. Do not mistake that definite
+pre-dispatch refusal for an unknown execution outcome. Downloads still require their explicit
+network access.
+
+A lost mutation response is different from a denied startup probe: inspect retained
+request/status/recovery evidence and use its request ID when supported. Never blindly
+repeat a publication, script or program run whose outcome is unknown. External-tool
+fallback is allowed by project rules, but record that the intended facade was not used
+and do not invent a successful checkpoint or native result.
+
+## Wait for the original execution
+
+A tool operation may outlast the host execution tool's initial wait. A returned running
+session/cell ID means that command is still in progress, not that the CLI returned no data.
+Use the host's session poll/wait facility until terminal exit and consume stdout/stderr
+before issuing a dependent command. In Codex, an `exec_command` session is continued with
+`write_stdin`; a yielded execution cell uses that host's cell wait. Do not launch a second
+open/install or repeat a CPU action just because the first chunk was empty. If the execution
+really loses its terminal result, use the CLI's request/status recovery as described above.

package/skills/insight-windbg/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: insight-windbg
+description: Investigate Windows native user-mode minidumps using bounded stacks, threads, registers, modules, memory and disassembly through insight-cli windbg. Use on Windows x64 when a captured runtime state needs native debugger evidence.
+---
+
+# Insight WinDbg 0.2.1
+
+If local help/status reports AppData or IPC access denied, retry that **read-only probe**
+with the agent host's normal permission escalation, then use that route for later authorized
+CLI calls too. An explicit **no command was sent** denial is known undispatched and can be
+retried through that route. Keep HOME, profile and owner state; see
+[host execution permissions](references/agent-execution.md). A lost mutation reply needs
+request/status recovery, never blind retry.
+
+Keep the project's RE and evidence conventions. This facade reads a captured Windows
+user-mode minidump; it does not run or attach the original application. Dump contents
+can include private memory. Store evidence under the project's normal rules.
+
+1. Check `insight-cli windbg status --json`. On Windows x64, `windbg install --vendor-direct`
+   downloads Microsoft's pinned WinDbg bundle, prepares the CDB console runtime and probes it.
+   Microsoft terms prohibit our redistribution; this explicit acquisition uses Microsoft,
+   SHA256 and our local cache. `download --vendor-direct` stages the archive first.
+   `install --archive FILE --offline` accepts the matching local MSIX bundle.
+   `install --executable C:\tools\windbg\amd64\cdb.exe` selects an existing CDB 10.x family;
+   adjacent runtime bytes are fingerprinted. `doctor` probes it again; uninstall removes only
+   owned software and preserves research and external files.
+2. `insight-cli windbg inspect crash.dmp --symbols native.pdb --json` captures immutable inputs
+   and shows the dump environment, threads, current stack, registers and modules. A local
+   matching PDB improves correspondence; missing/mismatched symbols remain warnings.
+   Network symbol lookup and inherited debugger initialization are disabled.
+3. Drill down with `--view stack --frames 32`, `--view registers`, `--view threads` or
+   `--view modules`. `--thread N` selects the dump's decimal thread index. A runtime address
+   from this same dump enables `--view memory --address 0xADDRESS --count 64` or
+   `--view disassembly --address 0xADDRESS --count 16`. Addresses are runtime values affected
+   by ASLR, not file offsets. Missing pages do not mean zero or absent behavior.
+4. `--target ID` reuses a captured dump. `--limit`/`--offset` page native lines;
+   `--output research/native-state.json` saves the full bounded result to a new ordinary file.
+   Preserve useful evidence with `artifacts save` if appropriate. A `partial` response includes
+   warnings; retain them in conclusions. One dump proves one captured state, not every path.
+5. The owned debugger runs inside a Windows Job Object, bounded by `--timeout-seconds`
+   (default 30, maximum 600). Owner loss or launcher termination closes its process tree.
+   `tools processes --tool windbg --all` shows retained jobs. Lost or missing result receipts
+   mean an unknown result; inspect diagnostics before choosing a new query. No automatic
+   replay or arbitrary debugger-command gateway is exposed.
+
+Generated `windbg inspect --help` owns exact syntax. No Ghidra session or merge is needed.

package/skills/insight-windbg/references/agent-execution.md

@@ -0,0 +1,36 @@
+# Agent host execution permissions
+
+Keep the user/project host policy and the selected profile. A sandbox can deny writes
+to runtime AppData or access to the local IPC endpoint, including during local help.
+This is a host execution boundary, not evidence that the tool or its inputs are absent.
+
+First retry only `insight-cli --help`, `tools list`, `skill`, or the selected application's
+read-only `status` using the host's normal permission escalation. In Codex, use the
+execution tool's `sandbox_permissions: "require_escalated"` with a scoped explanation
+that the installed CLI needs its existing profile storage/local IPC. Automatic approval
+review or the user decides that request; do not disable the sandbox or approval policy.
+
+Do not work around this by changing HOME/AppData/profile paths, creating another host,
+deleting owner/endpoint files, killing unrelated processes or claiming a missing runtime.
+After the read-only probe succeeds, use the approved execution route for the intended
+public CLI commands. An access refusal explicitly stating **no command was sent** is
+known not dispatched; it is safe to submit that authorized command through the approved
+route. This includes a mutation refused before dispatch. Do not mistake that definite
+pre-dispatch refusal for an unknown execution outcome. Downloads still require their explicit
+network access.
+
+A lost mutation response is different from a denied startup probe: inspect retained
+request/status/recovery evidence and use its request ID when supported. Never blindly
+repeat a publication, script or program run whose outcome is unknown. External-tool
+fallback is allowed by project rules, but record that the intended facade was not used
+and do not invent a successful checkpoint or native result.
+
+## Wait for the original execution
+
+A tool operation may outlast the host execution tool's initial wait. A returned running
+session/cell ID means that command is still in progress, not that the CLI returned no data.
+Use the host's session poll/wait facility until terminal exit and consume stdout/stderr
+before issuing a dependent command. In Codex, an `exec_command` session is continued with
+`write_stdin`; a yielded execution cell uses that host's cell wait. Do not launch a second
+open/install or repeat a CPU action just because the first chunk was empty. If the execution
+really loses its terminal result, use the CLI's request/status recovery as described above.

package/dist/src/runtime-archives.d.ts

@@ -1,5 +0,0 @@
-import type { RuntimeArtifact } from './runtime-catalog.js';
-export declare function fileSha256(path: string): Promise<string>;
-export declare function archiveName(name: string): string;
-export declare function extractArchive(file: string, destination: string, format: 'tgz' | 'zip'): Promise<void>;
-export declare function cacheArtifact(artifact: RuntimeArtifact, cache: string, fetcher: typeof fetch, signal: AbortSignal, offline?: boolean): Promise<string>;