Skip to main content

Installing the Capture Advisor

The Capture Advisor (advisor service, /advisor/v1) does three things from what Spider has already captured:

  • Capture setup: from a namespace's network usage it plans which workloads to attach, which ports and protocols to parse, and the whisperer configuration changes; it can probe unknown ports, apply the plan and observe it for a window, and undo it.
  • Template and tag suggestions for a whisperer, validated against the parser's own playground, then applied to the whisperer configuration.
  • Link ids: tag rules that follow one business id across protocols or between services. See Linking ids across protocols and services.

It is reached from the Analysis UI (capture-setup wizard, Suggest buttons, Link ids), from the Spider CLI (spider capture, spider templates) and from the MCP server. This page covers what an operator has to set up.

Requirements​

RequirementDetail
Helm flagglobal.flips.advisor: true. Off by default; it deploys the advisor service and its gateway route /advisor/v1.
LicenceThe ADVISOR capability, granted at the TEAM tier and above. Without it every /advisor/v1 route answers 403 with code LIC-GATE-001, and the service logs the warning ADVS-INIT-005 at boot.
Controller3.2.1 or later: the attachments made by a probe carry a time-to-live, and an attachment past it is only detached from 3.2.1. 3.4.0 or later is recommended: it answers the workload details (images, container ports, Service ports and their appProtocol) the planner uses to tell which protocol a port speaks. With an older Controller the plan is still produced, from the port number and transport only.
WhispererAn INTERFACE whisperer (existing, or created by the Advisor). A plan against another capture mode is refused with 422.

Capture setup attaches the whisperer by injecting ephemeral containers, as the UI does, so the Controller of the cluster must be connected to Spider.

Helm values​

global:
flips:
advisor: true

# Optional: only to change the defaults below
advisor:
probe:
defaultTtl: PT5M
maxTtl: PT15M
finalizeGrace: PT10M
resultTtl: P1D
apply:
defaultWindow: PT30M
maxWindow: PT2H
effectiveDelay: PT5M
minWindow: PT5M
enoughComs: 200
finalizeGrace: PT10M

The advisor block is a top-level Helm key (not under global). Only advisor.probe and advisor.apply are passed through; they are merged over the defaults shipped in the Config service, so a partial block is fine and each missing key keeps its default.

KeyDefaultMeaning
advisor.probe.defaultTtl / maxTtlPT5M / PT15MLifetime of the attachments made by a probe. The service never accepts more than PT15M.
advisor.probe.minSessions3A probe ends early once every probed port has this many sessions.
advisor.probe.maxSessionsPerPort5Sessions read per port.
advisor.probe.payloadBytes512First bytes of each direction used to classify the protocol.
advisor.probe.maxPortsPerTarget20Ports probed on one workload.
advisor.probe.reaperIntervalPT30SHow often abandoned runs are looked for.
advisor.probe.finalizeGracePT10MAfter a probe's deadline, how long a client has to read the run before the Advisor restores it by itself.
advisor.probe.resultTtlP1DHow long a probe or apply run stays readable.
advisor.apply.defaultWindow / maxWindowPT30M / PT2HObservation window of an apply when the caller gives none, and the longest accepted.
advisor.apply.effectiveDelayPT5MThe window starts this long after the configuration write, because parsers cache a whisperer's configuration for up to 5 minutes. When tuning.whispConfigTtl shortens that cache (for example PT10S), an unset value becomes that TTL plus 20 seconds (PT30S). An explicit value always wins.
advisor.apply.minWindowPT5MShortest window.
advisor.apply.enoughComs200The window ends early (never before minWindow) once every planned protocol has this many communications with content.
advisor.apply.finalizeGracePT10MSame role as the probe one, for an apply run.

The service refuses to start on an inconsistent block. In particular advisor.probe.resultTtl must be at least maxTtl + finalizeGrace + 2 x reaperInterval for probes, and at least apply.maxWindow + effectiveDelay + finalizeGrace + 2 x reaperInterval for applies, so a run document outlives the run; apply.finalizeGrace must be at least probe.finalizeGrace, and apply.minWindow at most apply.defaultWindow.

Other limits live in the advisor document of the Config service and are not exposed as Helm values:

KeyDefaultMeaning
advisor.capturePlan.maxAttachments50Workloads one plan may attach (1 to 50). An apply asking for more than 400 attachments is refused.
advisor.capturePlan.maxWindowPT24HLongest span of network usage a plan reads.
advisor.capturePlan.minEdgeBytes1024Traffic between two actors below this over the window is ignored as noise.
advisor.capturePlan.probeThreshold0.7A port whose protocol prior is below this confidence is flagged as needing a probe.
advisor.suggest.defaultMaxComs / maxComs2000 / 5000Communications read for one suggestion request (also max_coms/--max-coms). Requests are synchronous behind the gateway timeout and hold the communications in memory.

The Helm chart sets advisor.capturePlan.ignoreNamespaces to Spider's own namespace: its traffic is never planned, and that namespace cannot be planned. The link-ids pass has no operator setting: it reads at most 1000 communications per protocol, and the server caps max_coms.

Run store​

Probe and apply runs are kept in Redis, selected by cacheNodes.advisorRuns (default redis-shared, database 1, keys advisor:*). Nothing is stored in Elasticsearch. The Mcp service keeps its team-token cache in the same database under other keys, so never flush it.

What the Advisor is allowed to do​

  • Every call to the other Spider services is made with the caller's own token. The Advisor widens no right: whisperer ownership and payload access are enforced downstream, and the suggestions and link-ids values are returned only to accounts with payload access.
  • It never removes a rule from a whisperer configuration.
  • One exception is a service token, used only by the reaper when a client abandons a run: Whisps grants it a restore-only right on the observation settings (content flags and the shortLife storage policy), nothing else.
  • A run's end differs by who ends it. At the normal end of an apply window the observation settings are put back, while the added ports, parse flags and attachments stay. A user restore also undoes the added ports and parse flags and detaches the attachments the run created; attachments made by hand are never touched. The reaper restores the observation settings only, and attachments then end by their time-to-live.

MCP server​

The nine Advisor tools of the MCP server follow the mcpServer.captureControl.enabled flag, with no Advisor flag of their own:

  • spider_capture_plan, spider_capture_status, spider_suggest_enrichment and spider_link_ids are read tools and are always registered when global.flips.mcp is on. They need the ADVISOR capability.
  • spider_capture_probe, spider_capture_apply, spider_capture_restore, spider_apply_enrichment and spider_apply_link_ids change the cluster or a whisperer configuration, and are registered only when mcpServer.captureControl.enabled: true. With the flag off they are absent from the tool list.

mcpServer.captureControl.defaultTtl and maxTtl time-box spider_attach; they do not bound the Advisor's probe and apply windows, which are the advisor.* values above.

global:
flips:
mcp: true
advisor: true
mcpServer:
captureControl:
enabled: true

The tools call the Advisor service, so turn both flips on together.

Checking the installation​

spider capture plan -n <namespace> -w <whispererId> --pretty

A LIC-GATE-001 answer means the licence lacks ADVISOR; check the ADVS-INIT-005 warning in the service log.