completers

func CachedList ¶ added in v0.3.0

func CachedList[T any](con *client.Client, name, label, emptyMsg string, read func() ([]T, error), render func([]T) carapace.Action) carapace.Action

CachedList is the exported, generic shell for a plain DB-backed list completer — the one the per-domain ID completers (hosts, services, credentials, scans, agents, channels) share. It folds the cache + Guard + connect boilerplate each of them used to hand-roll (and, crucially, gives them the panic Guard they previously lacked). read runs only on a cache miss with a live connection and returns the domain objects; an error becomes a visible message, an empty result short-circuits to emptyMsg, otherwise render turns the objects into the candidate action (its own Tag/style/order).

func CachedListByPrefix ¶ added in v0.3.0

func CachedListByPrefix[T any](con *client.Client, name, label, emptyMsg string, read func(prefix string) ([]T, error), render func([]T) carapace.Action) carapace.Action

CachedListByPrefix is CachedList for completers that push the typed word down to the server as a prefix filter (HostFilters.Prefix and friends) instead of fetching the whole object set. It reads c.Value inside the callback, hands it to read so the DB returns only that prefix's candidates, and keys the cache by the prefix (via CacheCompletionByPrefix) so each prefix is cached independently. The server filter is a superset of what the candidate render will show, so carapace's own local filtering still narrows the result to exactly the matching candidates — the pushdown only shrinks the wire payload, it never drops a valid completion. An empty read on a non-empty prefix yields no candidates (the shell shows nothing), not emptyMsg — emptyMsg means a genuinely empty database.

func Domain ¶

func Domain(con *client.Client) carapace.Action

Domain completes a domain value — an NSE `dns-*` arg (dns-brute.domain, …), and any DNS/recon tool's domain flag later — from the DNS names already in the database. Each known hostname contributes its parent zones (every suffix of ≥2 labels, minus the host name itself), aggregated by how many known hosts fall under each; zones under the current agent's host are promoted via the relevance layer. Cached; the cache key carries the agent id.

The value is intentionally *not* a full host FQDN (that is the target completer's job) — it is the zone an operator hands to a brute/transfer tool to enumerate.

func FilterSelected ¶ added in v0.3.0

func FilterSelected(a carapace.Action) carapace.Action

FilterSelected wraps a completer so already-typed positional args are dropped from its candidates. The filter runs per-invocation OUTSIDE the static cache key (which CachedList owns), so a cached read is still reused across keystrokes while the selected-args elision stays live. It is the shared tail the scan completers (CompleteByID, CompleteSeriesHead) used to inline.

func Guard ¶

func Guard(label string, fn carapace.CompletionCallback) carapace.CompletionCallback

Guard wraps a completion callback so a panic degrades to a visible carapace message instead of crashing the exec-once `_carapace` subprocess — which the shell experiences as completion hanging with no output. The message also surfaces the failure (with its location in the panic text) so it can be diagnosed rather than silently swallowed. label names the completer for the message.

func Interface ¶

func Interface() carapace.Action

Interface completes a network-interface value — nmap's `-e`, an NSE `*.interface` arg, and any other scanner's interface flag — from the LOCAL machine's interfaces (the box the completion process runs on). It is deliberately not agent-context aware: interfaces belong to the operator's host, not the possibly-remote loaded agent. Purely local and cheap, so it is not cached. Interfaces are grouped up vs down (you scan from an up interface), each described by its addresses.

func MAC ¶

func MAC(con *client.Client) carapace.Action

MAC completes a MAC-address value — nmap's `--spoof-mac`, masscan's `--router-mac`/ `--adapter-mac`/`--spoof-mac`, and an NSE `*.mac` arg — from the MACs already in the database (the `Host.MAC` field and any address of type "mac", which carries an OUI vendor). MACs on the agent's host, then its subnet, are promoted via the relevance layer. Cached; the key carries the agent id.

func PortSpec ¶

func PortSpec(con *client.Client) carapace.Action

PortSpec is PortValue plus named-service tokens (ssh, http, …), for nmap's `-p`, which — unlike masscan — accepts a service name and expands it via nmap-services. The service group renders last, after the numeric ports.

func PortValue ¶

func PortValue(con *client.Client) carapace.Action

PortValue completes a numeric port value — masscan's `-p`/`--ports` and NSE `*.port` — from the DB's known open ports plus a curated set of well-known ports. Ports open on the current agent's host, then on its subnet neighbours, are promoted via the shared relevance layer, so the operator sees "what's open around here" first. Cached; the cache key carries the agent id.

func Secret ¶

func Secret(con *client.Client) carapace.Action

Secret completes a secret value — an NSE `*.password`/`*.passphrase` arg, and any brute/auth tool's secret flag later — from the credential store, so known passwords/hashes can be reused (AIMS's whole point). Secrets are grouped by credential type (the PrivateType axis), and the credentials used on the current agent's host are promoted to the top via the relevance layer (RelevanceOfHostID over the Logins that attach a credential to a host). Cached; key carries the agent id.

Note: this deliberately surfaces plaintext secrets as completion values — that is the point of credential reuse, and the operator owns the store (cf. Sliver's GetPlaintextCredsByHashType).

func SourceAddr ¶

func SourceAddr() carapace.Action

SourceAddr completes a source-address value — nmap's `-S`, masscan's `--source-ip`/ `--adapter-ip` — from the LOCAL machine's interface addresses: the legitimate source IPs a scan can send from. Like Interface it is deliberately local, not agent-context (the source belongs to the box running the scan tooling, not the possibly-remote loaded agent). Free-form is still accepted — spoofing an arbitrary address — this only offers the real local addresses as a shortcut.

func Targets ¶

func Targets(con *client.Client) carapace.Action

Targets completes a target slot with known hosts, sub-grouped by address locality, and drops any target already present on the command line. It is the shared target completer — the nmap positional target slot and NSE host-valued script args both use it — so excluding already-chosen targets happens here, once, for every reuse site.

The exclusion (Filter against c.Args) is applied *outside* the cache: cachedTargets stores the whole host set once, and each keystroke filters that set against the live arguments. Filtering by exact token is safe against the DisableFlagParsing arg stream — flags and flag-values (-sS, a --script value) never equal a host candidate.

func TemplateAuthors ¶ added in v0.3.0

func TemplateAuthors() carapace.Action

TemplateAuthors completes a `-a`/`-author` value with every contributor credited across the indexed corpus, frequency-bucketed the same way as TemplateTags — described by template count, since a name alone (unlike a tag) doesn't convey how prolific/relevant an author is.

func TemplateIDs ¶ added in v0.3.0

func TemplateIDs() carapace.Action

TemplateIDs completes a `-id`/`-template-id`/`-eid`/`-exclude-id` value with every template id in the indexed corpus, grouped by severity (critical first — see severityOrder) and described by the template's human name, so `-id <TAB>` lets an operator browse "what critical-severity checks does nuclei even have" rather than needing to already know an id.

func TemplateProtocolTypes ¶ added in v0.3.0

func TemplateProtocolTypes() carapace.Action

TemplateProtocolTypes completes a `-pt`/`-type`/`-ept`/`-exclude-type` value.

func TemplateSeverities ¶ added in v0.3.0

func TemplateSeverities() carapace.Action

TemplateSeverities completes a `-s`/`-severity`/`-es`/`-exclude-severity` value with nuclei's own closed severity vocabulary (info/low/medium/high/critical/unknown — see severityOrder), each described by how many indexed templates currently carry it. This is exactly the "vocab is stable/small" case COMPLETERS.md calls out for a static described list — except the counts are live against the operator's actual installed corpus rather than hand-maintained, so they stay correct across `nuclei -update-templates` for free.

func TemplateTags ¶ added in v0.3.0

func TemplateTags() carapace.Action

TemplateTags completes a `-tags`/`-etags`/`-exclude-tags`/`-itags` value with every tag seen across the indexed corpus, frequency-bucketed (see templateFrequencyCutoff). No descriptions: a tag's name already says what it is, and with ~8k of them a description column buys nothing worth the noise.

func Templates ¶ added in v0.3.0

func Templates() carapace.Action

Templates completes a template/workflow path slot by walking the local nuclei-templates tree one path segment at a time (carapace.ActionMultiParts, the same primitive ActionFiles/ActionDirectories are built on — see internalActions.go). Each level renders two sub-groups:

• "directories": the next path segment for every subdirectory still below the typed prefix, described by how many templates it contains, so `-t http/<TAB>` conveys "cves/ (2841 templates)" without opening a shell;
• "<severity> severity": the template files directly in this directory, grouped and ordered by severity (critical first) and described by name — so a directory mixing a critical RCE detector with a dozen "info" tech-fingerprint templates surfaces the one that matters first.

Directory candidates end in "/", which ActionMultiParts's shared NoSpace('/') handling (see its doc comment) lets the shell continue typing into rather than treating as a finished argument; template files have no trailing "/" and take a normal trailing space, since they are a complete, terminal value for the flag.

func Username ¶

func Username(con *client.Client) carapace.Action

Username completes a username value — an NSE `*.username`/`*.user` arg, and any auth tool's user flag later — from the credential store, and is the username half of the credential pair: each candidate is described by the secret it is paired with (its type and realm), so the operator picks a username *knowing* whether its password is on hand. It mirrors Secret's agent-context promotion on the username axis — usernames whose login is on the agent's host lead. This replaces the flat credentials.CompleteByUsername for scan slots. Cached; the key carries the agent id.

func WebURL ¶

func WebURL(con *client.Client) carapace.Action

WebURL completes a URL value — an NSE `*.url`/`*.uri` arg, and any web scanner's `-u`/`--url` later — by synthesizing `scheme://host[:port]/` from the DB's web services rather than completing free text. Endpoints on the current agent's host, then its subnet, are promoted via the relevance layer; the rest are grouped by scheme (with un-fingerprinted web ports flagged as guesses). Cached; the cache key carries the agent id.

func WorkflowTemplates ¶ added in v0.3.0

func WorkflowTemplates() carapace.Action

WorkflowTemplates completes `-w`/`-workflows` scoped to the workflows/ subdirectory: the operator never has to type "workflows/" themselves — completion behaves as if it were already typed — but the value nuclei receives still carries it, since nuclei resolves -w paths relative to the templates root/CWD the same way it does -t.

The trick is a context rewrite rather than a second index or a parallel rendering path: prepending "workflows/" to c.Value before delegating to Templates() makes carapace's own ActionMultiParts split it into c.Parts=["workflows", ...] exactly as if the operator had typed it, so every other mechanic (directory counts, severity grouping, the NoSpace('/') continuation) is inherited for free. c.Args is untouched — Templates never reads it.