# 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
```