Filters
Last modified on September 20, 2023
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.
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
type:sshCert
or type:sshcert
returns the same results.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.
--apply
(or --all
or -a
) to specify that you want to delete all matching resources. Omitting that flag results in an error.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_YOUR_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.
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:
- Accounts (users and services)
- Gateways and relays
- Resources (clouds, clusters, datasources, servers, websites)
- Roles
Supported data types for filter values
Data type | Description |
---|---|
Boolean | True or false values, including true , false , t , f , 1 , and 0 |
Text values that are properly formatted email addresses | |
IP | Supports IPv4 address with or without port |
KVP | Key-value pair in the format title=value |
String | Any non-null value |
URL | Data that follows the pattern of a URL |
Users and services
Field | Description | Value type | Usage example |
---|---|---|---|
active | Users who have (true ) or have not (false ) actively used StrongDM in the last 90 days | Boolean | sdm admin users list --filter 'active:false' |
email | User’s email address | sdm admin users list --filter 'email:alice.glick@strongdm.com' | |
firstname | User’s first name | String | `sdm admin users |
fullname | User’s full name (first and last) or the service account’s name | String | sdm admin services list --filter 'fullname:*Service |
id | User ID | String | sdm admin users list --filter 'id:a-005c9fd06213dba8' |
lastname | User’s last name | String | sdm admin users list --filter 'lastname:glick' |
locked | Users who are locked out or not from StrongDM | Boolean | sdm admin users list --filter 'locked:true' |
managed | Users who are managed and provisioned by StrongDM (false ) or managed and provisioned by a third-party identity provider (true ) such as Azure AD or Okta | Boolean | sdm admin users list --filter 'managed:false' |
permissionlevel | User’s permission level (admin , admin-token , auditor , database-admin , multi-team-leader , relay , service , suspended , scim-token , or user ) | String | sdm admin users list --filter 'permissionlevel:database-admin' |
suspended | User’s status | Boolean | sdm admin users list --filter 'suspended:true' |
tags | Tag(s) assigned to the user; supports wildcards (* ); tag values containing commas must be inside quotes | KVP | sdm admin users list --filter 'tags:region="useast,uswest"' |
type | Type of account (user or service ) | String | sdm admin users list --filter 'type:user' |
Gateways and relays
Field | Description | Value type | Usage example |
---|---|---|---|
bindaddr | Bind address; note that this parameter is only for gateways | IP | sdm admin relays list gateways --filter 'bindaddr:0.0.0.0:5000' |
id | ID of the gateway or relay | String | sdm admin relays list --filter 'id:n-123abc4d567e89fg' |
listenaddr | IP or host address that the gateway listens on; this parameter is only for gateways, as relays do not listen for client connections | IP, URL | sdm admin gateways --filter 'listenaddr:ec2-1-23-456-78.compute-1.amazonaws.com:5000' |
name | Name of the gateway or relay | String | sdm admin relays list --filter 'name:docs' |
online | Status of the gateway or relay | Boolean | sdm admin relays list --filter 'online:false' |
tags | Resource tag(s) assigned to the gateway or relay | KVP | sdm admin relays list --filter 'tag:env=dev' |
type | Node type (gateway or relay ) | String | sdm admin relays list --filter 'type:relay' |
Resources: clouds, clusters, datasources, servers, websites
Field | Description | Value type | Usage example |
---|---|---|---|
bindinterface | IP address to which the resource is bound, in the 127.0.0.1 to 127.255.255.254 IP address range; default is 127.0.0.1 | IP | sdm admin datasources list --filter 'bindinterface:127.0.0.1' |
healthy | Health status of the resource | Boolean | sdm admin datasources list --filter 'healthy:false' |
hostname | Hostname of the resource; for websites, the URL of the website | URL | sdm admin datasources list --filter 'hostname:example-host.com' |
httpsubdomain | Organization’s web domain value | String | sdm admin datasources list --filter 'httpsubdomain:education-team' |
id | ID of the resource | String | sdm admin datasources list --filter 'id:rs-058a6582617b2c95' |
name | Name of the resource | String | sdm admin datasources list --filter 'name:ExampleResourceName' |
port | Port number | Number | sdm admin datasources list --filter 'port:27017' |
portoverride | Port override to which the resource is bound | Number | sdm admin datasources list --filter 'portoverride:1234' |
remoteIdentityEnabled | Method of authentication for the resource, either Remote Identities (true ) or leased credentials (false ) | Boolean | sdm admin servers list --filter 'remoteidentityenabled:true' |
secretStoreId | Secret store identifier for the resource; use sdm admin secretstores list to get it | String | sdm admin clouds list --filter 'secretStoreId:se-1a2b3cd45678e9f1' |
tags | Resource tag(s) assigned to the resource | KVP | sdm admin datasources list --filter 'tag:env=dev' |
type | Specific type of resource (for example, sshCert , redis , and so forth) | String | sdm admin datasources list --filter 'type:redis' |
username | Username to be used for authentication to the resource | String | sdm admin datasources list --filter 'username:admin' |
Roles
Field | Description | Value type | Usage example |
---|---|---|---|
id | Role ID | String | sdm admin roles list --filter 'id:r-449dd90f60f610d7' |
managed | Roles (groups) that are managed and provisioned by StrongDM (false ) or managed and provisioned by a third-party identity provider (true ) such as Azure AD or Okta | Boolean | sdm admin roles list --filter 'managed:false' |
name | Name of the role | String | sdm admin roles list --filter 'name:Docs' |
tags | Tag(s) assigned to the role | KVP | sdm admin roles update 'Test Role' --tags 'env=dev' |
Potential Resource Type Values
This section provides the accepted values for each resource type.
Datasources
This table provides the values for each datasource type.
Datasource type | Value |
---|---|
Amazon ES | amazones |
Amazon MQ (AMQP 0.9.1) | amazonmq-amqp-091 |
Athena | athena |
Aurora MySQL | aurora-mysql |
Aurora PostgreSQL | aurora-postgres |
Azure Database for MySQL | azuremysql |
BigQuery | bigquery |
Cassandra | cassandra |
Citus | citus |
Clustrix | clustrix |
CockroachDB | cockroach |
DocumentDB (replica set) | documentdbreplicaset |
DocumentDB (single host) | documentdbhost |
Druid | druid |
DynamoDB | dynamo |
ElastiCache Redis | ecredis |
Elasticsearch | elastic |
Greenplum | greenplum |
Maria | maria |
Memcached | memcached |
MemSQL | memsql |
Microsoft SQL Server | mssql |
Microsoft SQL Server (Azure AD) | mssqlAzureAD |
Microsoft SQL Server (Kerberos) | mssqlKerberos |
MongoDB (replica set) | mongo-replicaset |
MongoDB (single host) | mongo |
MySQL | mysql |
Neptune | neptune |
Neptune (IAM) | neptuneiam |
Oracle | oracle |
PostgreSQL | postgres |
PostgreSQL (mTLS) | mTLSPostgres |
Presto | presto |
RabbitMQ (AMQP 0.9.1) | rabbitmq-amqp-091 |
Redis | redis |
Redshift | redshift |
SingleStore | singlestore |
Snowflake | snowflake |
Sybase ASE | sybase |
Sybase IQ | sybase-iq , sybaseiq |
Teradata | teradata |
Servers
This table provides the values for each server type.
Server type | Value |
---|---|
RDP | rdp |
SSH (Public Key) | ssh |
SSH (Certificate Based) | ssh-cert , sshCert |
SSH (Customer Managed Key) | ssh-customer-key |
TCP | rawtcp |
Clusters
This table provides the values for each cluster type.
Cluster type | Value |
---|---|
AKS | aks |
AKS (HTTP Basic Auth) | aks-basic , aksbasic |
AKS (Service Account) | aks-service , aksservice |
AKS (Service Account - User Impersonation) | aks-service-ui , aksserviceui |
AKS (User Impersonation) | aks-ui |
Elastic Kubernetes Service | amazon-eks , amazoneks , eks |
Elastic Kubernetes Service (User Impersonation) | amazon-eks-ui , amazoneksui , eksui |
Google Kubernetes Engine | gke |
Google Kubernetes Engine (User Impersonation) | gke-ui |
Kubernetes | k8s , kubernetes |
Kubernetes (HTTP Basic Auth) | k8s-basic , k8sbasic |
Kubernetes (Service Account) | k8s-service , k8sservice |
Kubernetes (Service Account - User Impersonation) | k8s-service-ui , k8sserviceui |
Kubernetes (User Impersonation) | k8s-ui , kubernetesui |
Clouds
This table provides the values for each cloud type.
Cloud type | Value |
---|---|
AWS | aws |
Azure (Certificate) | azurecert |
Azure (Password) | azure |
GCP | gcp |
Websites
This table provides the values for each website type.
Website type | Value |
---|---|
HTTP | http , httpNoAuth , http-no-auth |
HTTP Basic Auth | http-basic , httpBasic , basicauth |
HTTP Custom Auth | http-header-auth , headerauth |