Filters

Filters allow you to narrow request results when programmatically interacting with StrongDM via the CLI or the API. This article describes how to use filters with the sdm admin CLI commands, including proper syntax, usage examples, and available filter parameters and values.

For information on how to use filters in API requests with any of StrongDM’s SDKs, please consult the documentation for the specific tool you wish to use.

Syntax and Filtering Considerations #

Filters are specified in sdm admin CLI commands with the --filter flag followed by the field and the value on which you want to filter.

Example:

sdm admin users list --filter '<FIELD>:<VALUE>'

Let’s say, for example, that your organization has 50 users whose first name is Sam, and you want to list only those people. To do that, run the command with the filter set as follows:

sdm admin users list --filter 'firstname:sam'

Possible filter fields and values are described in section Filter Parameters by Entity and section Potential Resource Type Values.

Wildcards #

The --filter flag accepts wildcard (*) values for certain fields, such as name and email. For example, you can use a filter and wildcard to list only users whose email address ends with @strongdm.com:

sdm admin users list --filter 'email:*@strongdm.com'

Special characters #

Special characters must be properly escaped using quotation marks. Additionally, multi-word names in filters must be encapsulated in quotation marks. For example, name:"Foo Bar" is correct, and name:Foo Bar is not.

Case #

Filters are case-insensitive. Uppercase and lowercase values return the same results.

Terminal syntax differences #

The terminal programs on different operating systems use syntax that can vary slightly. For example, using the --filter flag requires the following syntax for most macOS or Linux terminals:

--filter 'verb:"user added"'

Command Prompt on Windows, however, requires the following formatting for the same command:

--filter="verb:\"user added\""

The examples presented throughout the documentation primarily use the first syntax example given (for macOS or Linux) for CLI command examples. If your command is not working, verify that you are following the appropriate syntax rules for your terminal program when it comes to quoting, escaping, flagging, and similar operations.

Date/Time format #

Our system can parse the date (year, month, day) and time (hours, minutes, seconds) in a variety of formats. Examples of some accepted formats include the following:

• 2024-01-01 00:00:00 UTC
• 01 January 2024 00:00
• 2024-01-01T12:00:00Z

When filtering based on date and time, an acceptable format must be used. It’s optional to provide the time.

Example:

sdm audit activities --filter 'after:2024-01-01'

An error message is returned if you are not using a valid format: Could not find format and will need to structure your date in a different way.

Usage Examples #

This section provides examples of various ways to use single filters and multiple filters with the sdm admin management commands.

List servers by name #

The following example command shows how you can apply a filter to list all servers with a name that includes the word “admin.” Note the use of wildcards around “admin.”

$ sdm admin servers list --filter 'name:*admin*'
Server ID               Name                           Type
rs-03ad1e1b240c85c1     azure-gateway - CA (admin)     sshCert
rs-7bb96dd41d9ac70b     azure-gateway-admin            ssh

Show only sshCert servers #

In the following example, the type filter is used to list SSH Certificate-type servers:

$ sdm admin servers list --filter 'type:sshCert'
Server ID               Name                           Type
rs-1b08901ed124e296     azure-gateway                  sshCert
rs-2b73c2267a7e1379     azure-gateway - CA (root)      sshCert
rs-03ad1e1b240c85c1     azure-gateway - CA (admin)     sshCert

Use multiple filters #

The following example uses two filters, one for type and one for name, to list SSH Certificate-type servers that have admin in their name:

$ sdm admin servers list --filter 'type:sshCert,name:*admin*'
Server ID               Name                           Type
rs-03ad1e1b240c85c1     azure-gateway - CA (admin)     sshCert

Use multiple flags for multiple filters #

You can also provide filters as separate flags to achieve the same results, as in the following example:

$ sdm admin servers list --filter 'type:sshCert' --filter 'name:*admin*'
Server ID               Name                           Type
rs-03ad1e1b240c85c1     azure-gateway - CA (admin)     sshCert

Filter based on ID #

When id is used as a filter, results return any matching results. Because every ID is unique, it would be impossible to match more than one simultaneously if multiple id filters are provided.

In the example shown, you can see that listing servers and filtering by id results in a list of all servers that have the specified IDs.

$ sdm admin servers list --filter 'id:rs-1b08901ed124e296' --filter 'id:rs-2b73c2267a7e1379' --filter 'id:rs-03ad1e1b240c85c1'
Server ID               Name                           Type
rs-1b08901ed124e296     azure-gateway - CA             sshCert
rs-2b73c2267a7e1379     azure-gateway - CA (Copy)      sshCert
rs-03ad1e1b240c85c1     azure-gateway - CA (admin)     sshCert

Bulk operations examples #

You can use filters to assist with various bulk actions, such as showing all websites for a given hostname, deleting a group of resources, and so forth. This section includes some examples of such bulk operations.

Update multiple resources #

You may use filters to do batch updates on multiple resources.

In the following example, an Update command is used with the --filter and --tags flags to add the env=public tag to all HTTP (No Auth) type-websites:

$ sdm admin websites update --filter 'type:httpnoauth' --tags 'env=public'
changed 4 out of 4 matching datasources

To check that the env=public tag has been applied to the correct websites, you can filter for all websites with the type httpnoauth, as in the following example:

$ sdm admin websites list --filter 'type:httpnoauth'
Website ID              Name                    Type           Tags
rs-3b34c199bef73d19     google                  httpNoAuth     env=public
rs-000000000004682d     ksql control center     httpNoAuth     env=public
rs-4d1c88780405f0ad     potato                  httpNoAuth     env=public
rs-000000000004d17f     support kibana          httpNoAuth     env=public

Delete multiple resources #

You can use the --filter flag to delete a group of the same resources that have something in common. The filter specifies what they have in common, such as an assigned tag or the resource type.

In the example shown, the --filter flag is used to delete all the websites that are tagged with env=public.

$ sdm admin websites delete --filter 'tags:env=public' --apply
deleted 4 datasources

JSON Filters #

For larger or more complex search queries, you can use a JSON file to define your list of filters. Commands that point to JSON files use the --filter-json flag instead of --filter.

Example:

sdm admin datasources list --filter-json <PATH_TO_JSON_FILE>

Let’s say that you want to list a specific datasource and all PostgreSQL datasources that have been assigned the region=EU tag. Your command includes the --filter-json flag and the path to the JSON filter file:

sdm admin datasources list --filter-json /Users/alice.glick/Documents/example.json

The JSON filter file includes several filter parameters and their values, as in the following example:

[
    {
        "ids": [
            "rs-0835300a78ea36a0"
        ]
    },
    {
        "type": "postgres",
        "tags": {
            "region": "EU"
        }
    }
]

Note that the JSON-based filter is the union of filters, whose attributes are additive. In this example, results of the filter file are the union of one datasource (id = rs-0835300a78ea36a0) and all datasources whose type is postgres and contain the region=EU tag.

Filters Help #

You can use the --filters-help option with any CLI command that has filters to show all possible filters and usage examples. This option enables you to see filters with proper syntax, in context, without leaving the CLI. The --filters-help option is supported for all CLI commands that have the --filter option.

The output varies based on entity type. In the example shown, sdm admin datasources list --filters-help returns all possible filters that can be used to filter a list of datasources.

Example:

$ sdm admin datasources list --filters-help
Filters:
assigned                    true
bindAddress                 127.0.0.1:2022
bindInterface               127.0.0.1
discoveryEnabled            true
hasRequest                  true
healthy                     true
hostname                    www.example.com
http_subdomain              internalsite
id                          rs-e1b2
identity_enabled            true
identity_set_id             ig-e1b2
inPeeringGroup              true
lockStatus                  locked
name                        dev-db2
port                        5432
port_override               15432
secretStoreId               se-e1b2
tags                        k=v
type                        postgres
userAccess                  available
username                    admin
vnmMode                     true
workflow                    aw-e1b2

Filter Parameters by Entity #

Fields available to filter on vary by entity type. This section describes all possible filter parameters for the following entity types:

• Access requests
• Accounts (users and services)
• Activities
• Healthchecks
• Nodes (gateways and relays)
• Queries
• Permissions (account resources)
• Resources (clouds, clusters, datasources, servers, websites)
• Roles
• Workflows (including workflow approvers, workflow assignments, and workflow roles)

Supported data types for filter values #

Access requests #

Accounts - users and service accounts #

Activities #

Healthchecks #

Nodes - gateways and relays #

Permissions #

Queries #

Resources - clouds, clusters, datasources, servers, websites #

Roles #

Workflows, workflow-approvers, workflow-assignments, workflow-roles #

Potential Resource Type Values #

This section provides the accepted values for each resource type.

Datasources #

This table provides the values for each datasource type.

Servers #

This table provides the values for each server type.

Clusters #

This table provides the values for each cluster type.

Clouds #

This table provides the values for each cloud type.

Websites #

This table provides the values for each website type.