# Selectors

Selectors are used in various places to scope policies, rules, and actions. Spyderbat's selectors based on [Kubernetes Labels and Selectors](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/).

## Selector Primitives

Spyderbat's selectors offer set-based selector primitives.

|                            |                                                 |
| -------------------------- | ----------------------------------------------- |
| \*matchLabels              | user-defined key value pairs                    |
| \*matchExpressions         | contain a key, operator, and values             |
| \*\*matchFields            | pre-defined key value pairs                     |
| \*\*matchFieldsExpressions | key from pre-defined list, operator, and values |

* \* Matches the syntax from Kubernetes
* \*\* Unique to Spyderbat's Selectors

### Expressions

Expressions have 3 fields: `key`, `operator`, and `values`. They allow you to define set-based groupings.

Example:

```yaml
matchExpressions:
- key: app
  operator: In
  values: [apache, mysql]
```

In the example above whatever is being matched on, must have a label with a key `app` and the value of that label must be either `apache` or `mysql`.

#### Operators

Operators define how the set-based expression is to be evaluated.

|              |                                                           |
| ------------ | --------------------------------------------------------- |
| In           | The key must exist and the value must be in `values`      |
| NotIn        | The key must exists and the value must not be in `values` |
| Exists       | The key must exist                                        |
| DoesNotExist | The key must not exist                                    |

### Pattern Matching

Field values in `matchFields` and `matchFieldsExpressions` support Unix-style glob patterns for flexible matching.

| Pattern | Description                                      | Example                                                    |
| ------- | ------------------------------------------------ | ---------------------------------------------------------- |
| `*`     | Matches any number of characters (including `/`) | `systemd/*/curl` matches `systemd/crio/conmon/runc/6/curl` |
| `?`     | Matches exactly one character                    | `runc/?` matches `runc/6` but not `runc/runc`              |
| `[abc]` | Matches any one character in the set             | `runc/[69]` matches `runc/6` or `runc/9`                   |
| `[a-z]` | Matches any one character in the range           | `runc/[0-9]` matches `runc/6` but not `runc/runc`          |

{% hint style="warning" %}
The `*` wildcard matches across path separators (`/`). A pattern like `systemd/*/curl` will match process ancestor chains of any depth. Use specific path segments to constrain matches — for example, `systemd/crio/conmon/runc/*/curl` is safer than `systemd/*/curl`.
{% endhint %}

Values containing wildcards must be quoted in YAML:

```yaml
values:
  - "systemd/crio/conmon/runc/*/health-check/curl"
  - "*strimzi/kafka*"
```

## Pod and Namespace Selectors

Pod and Namespace selectors are defined the exact same way that Kubernetes Pod and Namespace selectors are. Both resources types can have user-defined labels that allow them to be grouped by selectors.

The labels are found within the Pod and Namespace object yaml.

| Supported Primitives |
| -------------------- |
| matchLabels          |
| matchExpressions     |

Examples:

```yaml
podSelector:
  matchLabels:
    app: apache
  matchExpressions:
  - {key: tier, operator: In, values: [frontend, backend]}
  - {key: test, operator: DoesNotExist}
```

```yaml
namespaceSelector:
  matchLabels:
    kubernetes.io/metadata.name: production
  matchExpressions:
  - {key: dedicated-node, operator: Exists}
```

## Other Selectors

The following selectors are Custom to Spyderbat's environment. They add an additional level on granularity to scoping operations.

| Supported Primitives   |
| ---------------------- |
| matchFields            |
| matchFieldsExpressions |

### Cluster Selector

The Cluster Selector allows for scoping by Kubernetes Cluster. Field values may be wildcarded with an `*` character.

| Supported Fields | Description                                                             |
| ---------------- | ----------------------------------------------------------------------- |
| name             | The name of the cluster as defined in Spyderbat                         |
| uid              | The Spyderbat-provided uid of the cluster generally begins with `clus:` |

Example:

```yaml
clusterSelector:
  matchFields:
    name: demo-cluster
```

### Machine Selector

The Machine Selector allows for scoping my Machine. A machine in this context is a device with the Spyderbat Nano Agent installed.

| Supported Fields | Description                                                             |
| ---------------- | ----------------------------------------------------------------------- |
| hostname         | The hostname of a host on the network                                   |
| uid              | The Spyderbat-provided uid of the machine generally begins with `mach:` |

Example:

```yaml
machineSelector:
  matchFieldsExpressions:
  - {key: hostname, operator: In, values: [test_node, staging_node]}
```

### Container Selector

The Container Selector allows for scoping by fields associated with containers.

| Supported Fields | Description                                                        |
| ---------------- | ------------------------------------------------------------------ |
| image            | The container's image name                                         |
| imageID          | The container's image hash                                         |
| containerName    | The name of a specific container instance (usually auto-generated) |
| containerID      | The ID of a specific container instance (usually auto-generated)   |

Example:

```yaml
containerSelector:
  matchFields:
    image: docker.io/apache
```

### Service Selector

The Service Selector allows for scoping by fields associated with Linux Services

| Supported Fields | Description                                                                                                  |
| ---------------- | ------------------------------------------------------------------------------------------------------------ |
| cgroup           | The cgroup that every process within the service falls under. Ex. `systemd:/system.slice/nano-agent.service` |
| name             | The simple name of the Linux service. Ex. `nano-agent.service`                                               |

Example:

```yaml
serviceSelector:
  matchFields:
    cgroup: systemd:/system.slice/nano-agent.service
```

### Trace Selector

The Trace Selector is used by Trace Suppression Policies to suppress Spydertraces within a specific scope.

| Supported Fields | Description                                                                    |
| ---------------- | ------------------------------------------------------------------------------ |
| triggerClass     | The class of flag that triggered the Spydertrace                               |
| triggerAncestors | The names of the ancestor processes of the flag that triggered the Spydertrace |

Field values support glob pattern matching including `*`, `?`, and character classes like `[0-9]`. See [Pattern Matching](#pattern-matching) for the full syntax.

#### Using matchFields

```yaml
traceSelector:
  matchFields:
    triggerClass: redflag/proc/command/high_severity/suspicious/netcat
    triggerAncestors: systemd/containerd-shim/runc/*/sh/python/sh/netcat
```

Use `matchFields` when you need to match a single value per field (with optional wildcards). When you need to match multiple possible values for the same field, use `matchFieldsExpressions` instead.

#### Using matchFieldsExpressions

Use `matchFieldsExpressions` when you need to match multiple patterns for the same field. This is useful when a workload runs across different container runtimes (e.g., CRI-O and containerd) that produce different process ancestry paths.

```yaml
traceSelector:
  matchFieldsExpressions:
    - key: triggerAncestors
      operator: In
      values:
        - "systemd/crio/conmon/runc/*/health-check/curl"
        - "systemd/containerd-shim/runc/*/health-check/curl"
    - key: triggerClass
      operator: In
      values:
        - "redflag/proc/command/high_severity/suspicious/curl"
```

Each value in the `values` array supports wildcards and is evaluated independently. A trace matches if its field value matches **any** of the listed values (`In` operator provides OR semantics).

The same [Operators](#operators) available for `matchExpressions` apply to `matchFieldsExpressions`: `In`, `NotIn`, `Exists`, and `DoesNotExist`.

### User Selector

The User Selector is used by Trace Suppression Policies to suppress Spydertraces triggered by a specific user or users.

| Supported Fields | Description                        |
| ---------------- | ---------------------------------- |
| user             | The username of the offending user |

Example:

```yaml
userSelector:
  matchFieldsExpressions:
  - {key: user, operator: NotIn, values: [admin, root]}
```

### Process Selector

The Process Selector is used to scope by fields associated with a Linux Process.

| Supported Fields | Description                                 |
| ---------------- | ------------------------------------------- |
| name             | The name of the process                     |
| exe              | The executable of the process               |
| euser            | The username of the process' effective user |

```yaml
processSelector:
  matchFields:
    exe: /bin/bash
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.spyderbat.com/reference/selectors.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.