Skip to content
OpenSmartRoute
Skillv1.0.0

nsm-session-pivot

Pivot through Zeek session and protocol metadata from a packet capture (read-only) — connection listing, service filtering, and following a connection uid into dns/http/ssl logs. Use when reconstructi

by automateyournetwork(0) 0 installs
Free
Sign in to install

Free account. Installing gives you the manifest plus copy-paste snippets.

See reviews

About

Imported from automateyournetwork/netclaw (workspace/skills/nsm-session-pivot/SKILL.md). Install upstream with npx skills add automateyournetwork/netclaw --skill nsm-session-pivot. Copyright stays with the author (Apache-2.0).

NSM Session Pivot (read-only)

MCP Server

  • Server: nsm-mcp (NetClaw-authored, spec 091)
  • Tools: nsm_status, nsm_analyze, nsm_sessions, nsm_protocol_log
  • Engine: Zeek 8.2.1, pinned by image digest
  • Input: a .pcap/.pcapng file already on disk. Nothing sniffs an interface.

The rule that matters most here

A missing protocol log does not mean there was no such traffic.

Zeek discards packets with invalid TCP checksums by default. Measured on a reference capture: with validation on, Zeek produced no http.log at all — the HTTP request was invisible — and a conn.log that was also wrong, 3 rows instead of the correct 2, because discarded packets fragment the flow. The only signal is a warning on stderr.

Captures from a NIC with checksum offloading routinely have invalid checksums, including the ones NetClaw's own cml-packet-capture and gns3-packet-capture skills produce.

So nsm-mcp defaults ignore_checksums=true, the opposite of Zeek's own default, and attaches zeek_posture to every response:

state What it means
IGNORING_CHECKSUMS all packets analysed — the correct setting for offloaded captures
PACKETS_DISCARDED packets were dropped; protocol logs may be missing and conn.log may be wrong
VALIDATING validation on, nothing flagged

If you see PACKETS_DISCARDED, re-run with ignore_checksums=true before drawing any conclusion. Reporting "no HTTP in this capture" from a discarded run is a wrong answer that looks like a finding.

Workflow: reconstruct what happened

  1. nsm_analyze — which Zeek logs did this capture produce, and how many connections?
  2. nsm_sessions — the connection table. Note service, conn_state, byte counts
  3. Pick the connection of interest and record its uid
  4. nsm_protocol_log with log="dns" / "http" / "ssl" and that uid — every Zeek log shares uid with conn.log, which is what makes the pivot exact rather than heuristic
  5. nsm_protocol_log with log="weird" — protocol anomalies Zeek could not classify
  6. Report the session narrative, stating the checksum posture you worked under

Workflow: follow an IDS alert to its session

Given an alert from nsm-ids-triage:

  1. nsm_sessions filtered by the alert's service, or scanned for its IP pair
  2. Match on id.orig_h/id.resp_h/id.resp_p to find the uid
  3. nsm_protocol_log for the relevant protocol with that uid
  4. Report the alert with its session: duration, bytes each way, conn_state
  5. conn_state is evidence: S0 (no reply) is a very different story from SF (completed)

Reading results honestly

  • Ask which logs exist before concluding one is empty. nsm_protocol_log returns the available log list when you request one Zeek did not write — use it rather than reporting absence.
  • truncated: true means you are looking at a page, not the total.
  • Zeek infers service from behaviour, not port. HTTP on 8443 is labelled http; trust the field over the port number, and say which you used.
  • weird.log is not an alert log. It records protocol oddities, many of them benign.

Important Rules

  • No writes, no live capture. This analyses a file.
  • Always state the checksum posture in any conclusion about absent traffic.
  • Record in GAIT — log every pivot, including the posture and connection count.

Integration with Other Skills

Skill How They Work Together
nsm-ids-triage Suricata alerts that this skill puts into session context
packet-analysis Individual packet decode (tshark) once a session is identified
cml-packet-capture / gns3-packet-capture Produce the capture this skill analyses
gait-session-tracking Record all pivots

Environment Variables

  • NSM_HOME — analysis and ruleset directory (default ~/.openclaw/nsm)
  • NSM_TIMEOUT — per-container timeout in seconds (default 600)

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml
targets:
  - https://api.opensmartroute.ai/api/v1/registry/automateyournetwork-netclaw-nsm-session-pivot/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

automateyournetwork-netclaw-nsm-session-pivot.ocm.jsonjson
{
  "ocm": "1",
  "id": "automateyournetwork-netclaw-nsm-session-pivot",
  "kind": "skill",
  "name": "nsm-session-pivot",
  "description": "Pivot through Zeek session and protocol metadata from a packet capture (read-only) — connection listing, service filtering, and following a connection uid into dns/http/ssl logs. Use when reconstructing what sessions occurred in a capture, following a connection across protocols, or investigating retrospectively",
  "publisher": "automateyournetwork",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "security",
      "nsm",
      "zeek",
      "pcap",
      "sessions",
      "forensics",
      "read-only",
      "github"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Pivot through Zeek session and protocol metadata from a packet capture (read-only) — connection listing, service filtering, and following a connection uid into dns/http/ssl logs. Use when reconstructing what sessions occurred in a capture, following a connection across protocols, or investigating retrospectively"
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "github",
      "repository": "https://github.com/automateyournetwork/netclaw",
      "path": "workspace/skills/nsm-session-pivot/SKILL.md",
      "ref": "7599220c0290184d3c9ff31662969abfecbe55f3",
      "url": "https://github.com/automateyournetwork/netclaw/blob/7599220c0290184d3c9ff31662969abfecbe55f3/workspace/skills/nsm-session-pivot/SKILL.md",
      "key": "automateyournetwork/netclaw/workspace/skills/nsm-session-pivot/SKILL.md"
    },
    "license": "Apache-2.0"
  },
  "instructions": "# NSM Session Pivot (read-only)\n\n## MCP Server\n\n- **Server**: `nsm-mcp` (NetClaw-authored, spec 091)\n- **Tools**: `nsm_status`, `nsm_analyze`, `nsm_sessions`, `nsm_protocol_log`\n- **Engine**: Zeek 8.2.1, pinned by image digest\n- **Input**: a `.pcap`/`.pcapng` file already on disk. Nothing sniffs an interface.\n\n## The rule that matters most here\n\n**A missing protocol log does not mean there was no such traffic.**\n\nZeek **discards packets with invalid TCP checksums by default**. Measured on a reference\ncapture: with validation on, Zeek produced **no `http.log` at all** — the HTTP request was\ninv",
  "cost": {
    "context_tokens": 1003
  }
}

Fetch it by URL: GET /api/v1/registry/automateyournetwork-netclaw-nsm-session-pivot/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.