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
| Requirement | Detail |
|---|---|
| Helm flag | global.flips.advisor: true. Off by default; it deploys the advisor service and its gateway route /advisor/v1. |
| Licence | The 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. |
| Controller | 3.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. |
| Whisperer | An 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.
| Key | Default | Meaning |
|---|---|---|
advisor.probe.defaultTtl / maxTtl | PT5M / PT15M | Lifetime of the attachments made by a probe. The service never accepts more than PT15M. |
advisor.probe.minSessions | 3 | A probe ends early once every probed port has this many sessions. |
advisor.probe.maxSessionsPerPort | 5 | Sessions read per port. |
advisor.probe.payloadBytes | 512 | First bytes of each direction used to classify the protocol. |
advisor.probe.maxPortsPerTarget | 20 | Ports probed on one workload. |
advisor.probe.reaperInterval | PT30S | How often abandoned runs are looked for. |
advisor.probe.finalizeGrace | PT10M | After a probe's deadline, how long a client has to read the run before the Advisor restores it by itself. |
advisor.probe.resultTtl | P1D | How long a probe or apply run stays readable. |
advisor.apply.defaultWindow / maxWindow | PT30M / PT2H | Observation window of an apply when the caller gives none, and the longest accepted. |
advisor.apply.effectiveDelay | PT5M | The 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.minWindow | PT5M | Shortest window. |
advisor.apply.enoughComs | 200 | The window ends early (never before minWindow) once every planned protocol has this many communications with content. |
advisor.apply.finalizeGrace | PT10M | Same 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:
| Key | Default | Meaning |
|---|---|---|
advisor.capturePlan.maxAttachments | 50 | Workloads one plan may attach (1 to 50). An apply asking for more than 400 attachments is refused. |
advisor.capturePlan.maxWindow | PT24H | Longest span of network usage a plan reads. |
advisor.capturePlan.minEdgeBytes | 1024 | Traffic between two actors below this over the window is ignored as noise. |
advisor.capturePlan.probeThreshold | 0.7 | A port whose protocol prior is below this confidence is flagged as needing a probe. |
advisor.suggest.defaultMaxComs / maxComs | 2000 / 5000 | Communications 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
shortLifestorage 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_enrichmentandspider_link_idsare read tools and are always registered whenglobal.flips.mcpis on. They need theADVISORcapability.spider_capture_probe,spider_capture_apply,spider_capture_restore,spider_apply_enrichmentandspider_apply_link_idschange the cluster or a whisperer configuration, and are registered only whenmcpServer.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.