> ## Documentation Index
> Fetch the complete documentation index at: https://docs.endorlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Filters

> Learn how to use filters with the Endor Labs REST API.

export const YamlTable = ({children, data: propData, content}) => {
  const KV_RE = /^([A-Za-z][A-Za-z0-9_()/#\s-]+?):\s*(.+)$/;
  const INLINE_MD_RE = /(\[([^\]]+)\]\(([^)]+)\))|(`([^`]+)`)|(\*\*([^*]+)\*\*)|(\*([^*]+)\*)/g;
  const YES_RE = /^-yes-$/i;
  const NO_RE = /^-no-$/i;
  const LIMITED_RE = /^-(limited|partial)-$/i;
  const NA_RE = /^-(na|none)-$/i;
  const NA2_RE = /^-na2-$/i;
  const SIMPLE_TAG_RE = /(<br\s*\/?>)|(<p\s*\/?>)|(-note-)|(-warning-)/gi;
  const tryParseKV = trimmed => {
    const m = KV_RE.exec(trimmed);
    return m ? {
      key: m[1],
      value: m[2].trim()
    } : null;
  };
  const registerKey = (key, seenKeys, orderedKeys) => {
    if (!seenKeys.has(key)) {
      orderedKeys.push(key);
      seenKeys.add(key);
    }
  };
  const flushEntry = (currentEntry, entries) => {
    if (Object.keys(currentEntry).length > 0) entries.push(currentEntry);
  };
  const parseDashPrefixed = (lines, entries, orderedKeys, seenKeys) => {
    let currentEntry = {};
    let inEntry = false;
    for (const line of lines) {
      const trimmed = line.trim();
      if (trimmed.startsWith('- ')) {
        if (inEntry) entries.push(currentEntry);
        currentEntry = {};
        inEntry = true;
        const kv = tryParseKV(trimmed.substring(2).trim());
        if (kv) {
          registerKey(kv.key, seenKeys, orderedKeys);
          currentEntry[kv.key] = kv.value;
        }
      } else if (inEntry && trimmed !== '') {
        const kv = tryParseKV(trimmed);
        if (kv) {
          registerKey(kv.key, seenKeys, orderedKeys);
          currentEntry[kv.key] = kv.value;
        }
      }
    }
    flushEntry(currentEntry, entries);
  };
  const parseBlankSeparated = (lines, entries, orderedKeys, seenKeys) => {
    let currentEntry = {};
    let inEntry = false;
    for (const line of lines) {
      const trimmed = line.trim();
      if (trimmed === '') {
        if (inEntry) {
          flushEntry(currentEntry, entries);
          currentEntry = {};
          inEntry = false;
        }
        continue;
      }
      const kv = tryParseKV(trimmed);
      if (!kv) continue;
      const isNewEntry = !line.startsWith(' ') && !line.startsWith('\t');
      if (isNewEntry && inEntry && Object.keys(currentEntry).length > 0) {
        entries.push(currentEntry);
        currentEntry = {};
      }
      registerKey(kv.key, seenKeys, orderedKeys);
      currentEntry[kv.key] = kv.value;
      inEntry = true;
    }
    flushEntry(currentEntry, entries);
  };
  const normalizeEntries = (entries, orderedKeys) => entries.map(entry => {
    const filled = {};
    for (const key of orderedKeys) filled[key] = entry[key] || '';
    return filled;
  });
  const parseYamlTableContent = contentStr => {
    if (!contentStr) return [];
    const entries = [];
    const orderedKeys = [];
    const seenKeys = new Set();
    const lines = contentStr.split('\n');
    if (lines.some(line => line.trim().startsWith('- '))) {
      parseDashPrefixed(lines, entries, orderedKeys, seenKeys);
    } else {
      parseBlankSeparated(lines, entries, orderedKeys, seenKeys);
    }
    return normalizeEntries(entries, orderedKeys);
  };
  const processText = text => {
    if (!text) return text;
    const parts = [];
    let keyIndex = 0;
    let lastIndex = 0;
    let match;
    while ((match = INLINE_MD_RE.exec(text)) !== null) {
      if (match.index > lastIndex) parts.push(text.slice(lastIndex, match.index));
      if (match[1]) {
        parts.push(<a key={keyIndex++} href={match[3]}>{match[2]}</a>);
      } else if (match[4]) {
        parts.push(<code key={keyIndex++}>{match[5]}</code>);
      } else if (match[6]) {
        parts.push(<strong key={keyIndex++}>{match[7]}</strong>);
      } else if (match[8]) {
        parts.push(<em key={keyIndex++}>{match[9]}</em>);
      }
      lastIndex = match.index + match[0].length;
    }
    if (lastIndex < text.length) parts.push(text.slice(lastIndex));
    if (parts.length === 0) return text;
    const keyRef = {
      current: keyIndex
    };
    return expandHtmlTags(parts, keyRef);
  };
  const processBadges = text => {
    if (!text || typeof text !== 'string') return text;
    if (YES_RE.test(text)) return <span className="yt-badge-yes" role="img" aria-label="Supported" title="Supported">✓</span>;
    if (NO_RE.test(text)) return <span className="yt-badge-no" role="img" aria-label="Not supported" title="Not supported">✗</span>;
    if (LIMITED_RE.test(text)) return <span className="yt-badge-limited" role="img" aria-label="Partially supported" title="Partially supported">◐</span>;
    if (NA_RE.test(text) || NA2_RE.test(text)) return <span className="yt-sr-only" title="Not applicable">Not applicable</span>;
    return processText(text);
  };
  const cellClassName = text => {
    if (!text || typeof text !== 'string') return undefined;
    if (NA_RE.test(text)) return 'yt-cell-na';
    if (NA2_RE.test(text)) return 'yt-cell-na2';
    return undefined;
  };
  const expandSimpleTags = (str, keyRef) => {
    const result = [];
    let last = 0;
    SIMPLE_TAG_RE.lastIndex = 0;
    let m;
    while ((m = SIMPLE_TAG_RE.exec(str)) !== null) {
      if (m.index > last) result.push(str.slice(last, m.index));
      if (m[1]) {
        result.push(<br key={keyRef.current++} />);
      } else if (m[2]) {
        result.push(<br key={keyRef.current++} />, <br key={keyRef.current++} />);
      } else if (m[3]) {
        result.push(<span key={keyRef.current++} className="yt-badge-note" style={{
          fontWeight: 600
        }}>Note: </span>);
      } else if (m[4]) {
        result.push(<span key={keyRef.current++} className="yt-badge-warning" style={{
          fontWeight: 600
        }}>Warning: </span>);
      }
      last = m.index + m[0].length;
    }
    if (last < str.length) result.push(str.slice(last));
    return result;
  };
  const expandHtmlTags = (chunks, keyRef) => {
    const out = [];
    for (const chunk of chunks) {
      if (typeof chunk === 'string') {
        out.push(...expandSimpleTags(chunk, keyRef));
      } else {
        out.push(chunk);
      }
    }
    return out;
  };
  const extractText = node => {
    if (node === null || node === undefined) return '';
    if (typeof node === 'string') return node;
    if (typeof node === 'number') return String(node);
    if (typeof node === 'boolean') return '';
    if (Array.isArray(node)) return node.map(extractText).join('');
    if (node && typeof node === 'object' && node.type) {
      const props = node.props || ({});
      if (typeof props.children === 'string') return props.children;
      if (props.children) return extractText(props.children);
      return '';
    }
    return String(node || '');
  };
  const [mounted, setMounted] = useState(false);
  useEffect(() => {
    setMounted(true);
  }, []);
  const data = useMemo(() => {
    if (propData) return propData;
    if (content && typeof content === 'string') return parseYamlTableContent(content);
    if (!children) return [];
    if (typeof children === 'string') return parseYamlTableContent(children);
    const childrenArray = Array.isArray(children) ? children : [children];
    return parseYamlTableContent(childrenArray.map(extractText).join('').trim());
  }, [children, propData, content]);
  const columns = useMemo(() => {
    if (!data || data.length === 0) return [];
    const firstRow = data[0];
    if (!firstRow || typeof firstRow !== 'object') return [];
    return Object.keys(firstRow);
  }, [data]);
  if (!mounted) return null;
  if (!data || data.length === 0) return null;
  const rowKey = row => columns.map(c => row[c] || '').join('|');
  return <table>
      <thead>
        <tr>
          {columns.map(col => <th key={col}>{col.replaceAll('_', ' ')}</th>)}
        </tr>
      </thead>
      <tbody>
        {data.map(row => <tr key={rowKey(row)}>
            {columns.map(col => <td key={col} className={cellClassName(row[col])}>{processBadges(row[col])}</td>)}
          </tr>)}
      </tbody>
    </table>;
};

Filters allow you to specify a subset of objects that a request returns, for example:

<Tabs>
  <Tab title="endorctl">
    ```bash theme={null}
    endorctl api list --resource Finding \
      --filter "meta.name==dependency_with_critical_vulnerabilities" \
      --count
    ```
  </Tab>

  <Tab title="curl">
    ```bash theme={null}
    curl --get \
      --header "Authorization: Bearer $ENDOR_TOKEN" \
      --data-urlencode "list_parameters.filter=meta.name==dependency_with_critical_vulnerabilities" \
      --data-urlencode "list_parameters.count=true" \
      https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings
    ```
  </Tab>

  <Tab title="HTTP">
    ```bash theme={null}
    @baseUrl = https://api.endorlabs.com
    @token = `<insert-access-token>`
    @namespace = `<insert-namespace>`

    ###
    GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?list_parameters.filter=meta.name==dependency_with_critical_vulnerabilities&list_parameters.count=true HTTP/1.1
    Authorization: Bearer {{token}}
    ```
  </Tab>
</Tabs>

## Keys

A filter key specifies the field of the object to match against using a dot-delimited path. For example, given an object:

```json expandable theme={null}
{
  "uuid": "63ef202d090b62ecf3f6655b",
  "meta": {
    "name": "Example Object",
    "tags": ["dev"]
  },
  "spec": {
    "dependencies": [
      {
        "name": "mvn://org.slf4j:slf4j-api@2.0.0",
      },
      {
        "name": "mvn://ch.qos.logback:logback-access@1.3.0",
      }
    ],
    "version": {
      "ref": "v1.6.333",
      "timestamp": "2024-05-31TT21:04:55.799Z"
    }
  }
}
```

* `uuid` specifies the root field with the value `"63ef202d090b62ecf3f6655b"`
* `meta.name` specifies the nested field with the value `"Example Object"`
* `meta.tags` specifies the nested list field containing the values `["dev"]`
* `spec.dependencies.name` specifies the nested fields within the list with the values: `"mvn://org.slf4j:slf4j-api@2.0.0"` and `"mvn://ch.qos.logback:logback-access@1.3.0"`
* `spec.version.ref` specifies the nested field with the value `"v1.6.333"`

For more information, see [Data model](/developers-api/rest-api/using-the-rest-api/data-model).

## Operators

The API supports the following filter operators.

<YamlTable>
  {`
    - Operator: \`==\`
    Description: Matches objects where a specified field is equal to a specified value.
    - Operator: \`!=\`
    Description: Matches objects where a specified field is NOT equal to a specified value.
    - Operator: \`<\`
    Description: Matches objects where a specified field is less than a specified value.
    - Operator: \`<=\`
    Description: Matches objects where a specified field is less than or equal to a specified value.
    - Operator: \`>\`
    Description: Matches objects where a specified field is greater than a specified value.
    - Operator: \`>=\`
    Description: Matches objects where a specified field is greater than or equal to a specified value.
    - Operator: \`contains\`
    Description: Matches objects where a specified list contains one or more specified values.
    - Operator: \`in\`
    Description: Matches objects where a specified field is equal to one or more specified values.
    - Operator: \`matches\`
    Description: Matches objects where a specified field matches a specified regex pattern.
    - Operator: \`exists\`
    Description: Matches objects where a specified field in a json payload exists.

    `}
</YamlTable>

### Contains

Use `contains` or `not contains` to filter on the content of a list field. The filter treats multiple values as an OR operation, for example:

* To get all findings for vulnerabilities that have a fix available OR are in a reachable function use:

  `spec.finding_tags contains [FINDING_TAGS_FIX_AVAILABLE, FINDING_TAGS_REACHABLE_FUNCTION]`

* To get all findings for vulnerabilities that have a fix available AND are in a reachable function use:

  `spec.finding_tags contains [FINDING_TAGS_FIX_AVAILABLE] and spec.finding_tags contains [FINDING_TAGS_REACHABLE_FUNCTION]`

* To get all projects that do not have the meta tags "sanity" or "test" use:

  `meta.tags not contains [sanity, test]`

### In

Use `in` or `not in` to filter on the value of a field against one or more given values. The filter treats multiple values as an OR operation, for example:

* To get all findings with a "Critical" or "High" severity level use:

  `spec.finding_level in [FINDING_LEVEL_CRITICAL, FINDING_LEVEL_HIGH]`

* To get all findings that are not from the "Maven" or "npm" ecosystems use:

  `spec.ecosystem not in [ECOSYSTEM_MAVEN, ECOSYSTEM_NPM]`

### Matches

Use `matches` to filter on a regex pattern. Due to the nature of regex evaluation, this is much slower than using for example `==` or `!=`. Also due to the nature of regex evaluation, `not matches` is not supported.

### Exists

If a field does not exist then it can't be equal to anything, so we use `exists` and `not exists` instead of `!= null` or `== null`. This also covers `{}`, `[]`, etc.

## Values

A filter value works with the operator to match against the values at the specified field.

Use double quotes to escape string or regex values in a filter, for example:

* `uuid in ["64a3b8326dda5fb62bfcceea", "658323c91aa208f231cc7eff", "658323c963ca516ef02d1b02"]`
* `meta.name matches "validation bypass"`

<Note>
  Filters are case-sensitive by default.
</Note>

To filter with case-insentive values, you can use a regex modifier, for example:

* `meta.description matches "(?i)django"`

### Date/Time Values

Use `date` to encode date values in a filter, for example:

* To filter for objects created after a given date, use a date value with the format `YYYY-MM-DD`:

  `meta.update_time >= date(2024-05-01)`

* To filter for objects created between specific times, use a timestamp values with the [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) format:

  `meta.create_time >= date(2024-05-01T13:30:00.000Z) and meta.create_time < date(2024-05-01T23:30:00.000Z)`

Use `now` to encode relative date values in a filter by a given duration offset, for example:

* To filter for objects created in the last 15 minutes, use:

  `meta.create_time >= now(-12h)`

* To filter for objects created in the last 72 hours, use:

  `meta.create_time >= now(-72h)`

## Combinations

Use `and` or `or` to combine multiple filters, for example:

* `spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY] and meta.create_time >= date(2024-05-31)`
* `meta.name==archived_source_code_repo or meta.name==outdated_release`

### Nesting filters

You can also nest multiple filters together into a single filter with parentheses `()`, for example:

* `(spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY] and spec.level==FINDING_LEVEL_CRITICAL) or (spec.finding_categories contains [FINDING_CATEGORY_SECRETS] and spec.level in [FINDING_LEVEL_CRITICAL, FINDING_LEVEL_HIGH])`