Group computers dynamically with smart folders

A smart folder is a dynamic group of computers that you define with a saved search query. It finds matching computers each time you click the group. For example, if you want to view your computers grouped by attributes such as operating system or AWS project tags, you can do this using smart folders.

If you prefer to search for resources programmatically, you can automate resource searches using the Deep Security API. For examples, see the Search for Resources guide in the Deep Security Automation Center.

You create smart folders by defining:

  1. What to search (1 - computer properties)
  2. How to determine a match (2 - operator)
  3. What to search for (3 - value)
Smart folder query

Create a smart folder

  1. Go to Computers > Smart Folders.

  2. Click Create a Smart Folder.

    A default, empty search criteria group ("rule group") appears. You must configure this first. If you need to define more or alternative possible matches, you can add more rule groups later.

  3. Type a name for your smart folder.

  4. In the first drop-down list, select a property that all matching computers have, such as Operating System. (See Searchable Properties.)

    If you selected AWS Tag , Azure Tag, or GCP Label, also type the tag's name or label key.

  5. Select the operator: whether to match identical, similar, or opposite computers, such as CONTAINS.
    6. Some operators are not available for all properties.

  6. Type all or part of the search term.

    Wild card characters are not supported.
    If you enter multiple words, it compares the entire phrase - not each word separately. No match occurs if the property's value has words in a different order, or only some of the words.
    To match any of the words, instead click Add Rule and OR, and then add another value: one word per rule.

  7. If computers must match multiple properties, click Add Rule and AND. Repeat steps 4-6.

    For more complex smart folders, you can chain multiple search criteria. Click Add Group, then click AND or OR. Repeat steps 4-7.

    For example, you might have Linux computers deployed both on-premises and in clouds such as AWS or vCloud. You could create a smart folder that contains all of them by using 3 rule groups based on:

    1. local physical computers' operating system
    2. AWS tag
    3. vCenter or vCloud name

    smart folder hybrid

    8. To test the results of your query before saving your smart folder, click Preview.
  8. Click Save.

  9. To verify, click your new smart folder. Verify that it contains all expected computers.

    For faster smart folders, remove unnecessary AND operations, and reduce sub-folder depths. They increase query complexity, which reduces performance.

    Also verify that it omits computers that shouldn't match the query. If you need to edit your smart folder's query, double-click the smart folder.

    If your account's role doesn't have the permissions, some computers won't appear, or you won't be able to edit their properties. For more information, see Define roles for users.

Edit a smart folder

If you need to edit your smart folder's query, double-click the smart folder.

To reorder search criteria rules or rule groups, move your cursor onto a rule or group until it changes to a 4 way arrow, then drag it to its destination.

Clone a smart folder

To duplicate and modify an existing smart folder as a template for a new smart folder, right-click the original smart folder, then select Copy Smart Folder.

Focus your search using sub-folders

You can use sub-folders to filter a smart folder's search results.

Smart folders can be nested up to 10 levels deep.

  • Smart folder 1
    • Sub-folder 2
      • Sub-folder 3 ...

For example, you might have a smart folder for all your Windows computers, but want to focus on computers that are specifically Windows 7, and maybe specifically either 32-bit or 64-bit. To do this, under the "Windows" parent folder, you could create a child smart folder for Windows 7. Then, under the "Windows 7" folder, you would create two child smart folders: 32-bit and 64-bit.

child smart folders

  1. Right-click a smart folder and select Create Child Smart Folder.
  2. Edit your child smart folder's query groups or rules. Click Save.
  3. Click your new smart folder. Verify that it contains all expected computers. Also verify that it omits computers that shouldn't match the query.

Automatically create sub-folders

Applies to AWS, Azure, and GCP computers only.

Instead of manually creating child folders, you can automatically create sub-folders for each value of an AWS tag, Azure tag, or GCP label that's assigned to an Amazon EC2 instance, Amazon Workspace, Azure VM, or GCP VM instance. For information on how to apply tags/labels to your computers, refer to the documentation from your cloud provider:

Tag/label-based sub-folders will replace any existing manually created child folders under the parent folder.
  1. In Deep Security Manager, right-click a smart folder and select Smart Folder Properties.
  2. In the main pane, near the bottom, select the Automatically create sub-folders for each value of a specific tag or label key check box.
  3. Select either the AWS, Azure, or GCP cloud vendor.
  4. Type the name of the AWS tag, Azure tag, or GCP label key. Sub-folders are automatically created for each of the tag or label values.
  5. Click Save.
Empty sub-folders can appear if tag or label value is not being used anymore. To remove them, right-click the smart folder and select Synchronize Smart Folder.

Searchable Properties

Properties are an attribute that some or all computers you want to find have. Smart folders show computers that have the selected property, and its value matches.

Type your search exactly as that property appears in Deep Security Manager- not, for example, vCenter/AWS/Azure/GCP. Otherwise your smart folder query won't match.
To find the exact matching text, (unless otherwise noted) go to Computers and look in the navigation pane on the left.

General

Property Description Data type Examples
Hostname The computer's host name, as seen on Computers > Details in Hostname. string ca-staging-web1
Computer Display Name The computer's display name in Deep Security (if any), as seen on Computers > Details in Display Name. string nginxTest
Folder Name The computer's assigned group. string US-East
Operating System The computer's operating system, as seen on Computers > Details in Platform. string

Microsoft Windows 7 (64 bit) Service Pack 1 Build 7601
IP Address

The computer's IP address.

You can find the IP address in Deep Security Manager. To find the IP of:

  • an AWS instance, GCP VM or Azure VM, that was added to Deep Security through Add > Add AWS|Azure|GCP Account, go the computer's details page, and under the General tab, scroll to the Virtual machine Summary section. The AWS IP addresses are listed in these fields:
    • Private IP Address
    • Public IP (PIP) Address
  • If you added the AWS, GCP, or Azure computer through Add > Add Computers, its IP address is located in the same place as a physical computer's.

  • a physical computer, go to the computer's details page and on the left, click Interfaces

    If "DHCP" is displayed instead of a static IP address, it won't match the smart folder query.
  • a vCenter or vCloud VM, go to the vCenter computer's details page, and under the General tab, scroll to the Virtual machine Summary section. The vCenter or vCloud IP address is listed in the IP Address field.
 IPv4 or IPv6 address, or an IPv4 range

172.20.1.5-172.20.1.55

2001:db8:face::5
Policy The computer's assigned Deep Security policy, as seen on Computers > Details.

string

(option in drop-down list)

Base Policy
Activated Whether or not the computer has been activated with Deep Security Manager, as seen on Computers > Details. Boolean Yes
Docker Host

Whether or not Docker is installed on the computer, as seen on Computers > Details.

 Boolean No
Computer Type The type of computer. Options are: Physical Computer, Amazon EC2 Instance, Amazon WorkSpace, vCenter VM, Azure Instance, Azure ARM Instance, GCP VM Instance. string (option in drop-down list) Examples: Physical Computer, Amazon EC2 Instance
Last Successful Recommendation Scan Whether or not the computer has had a successful recommendation scan within a specified time period. The last recommendation scan date and results can be seen on Computers > Details > General > Intrusion Prevention or Integrity Monitoring or Log Inspection > Recommendations. Date operator drop-down list, String, Date unit drop-down list OLDER THAN, 7, DAYS
Last Agent Communication

Whether or not the agent has communicated with Deep Security Manager within a specified time period. The Last Communication date can be seen on Computers > Details > General > Last Communication.

 Date operator drop-down list, String, Date unit drop-down list OLDER THAN, 3, DAYS
Agent Offline Whether or not the agent is offline. This is displayed as Managed (Offline) or Offline on Computers > Details > General > Last Communication. Boolean Yes
Task(s)

State of the computer's tasks, as displayed in the Task(s) column on the Computers page. For a list of all possible tasks, see Computer and agent statuses.

 string Activating
Host Created Date Date when the computer was added to Deep Security Manager. string (date) 2019-03-15
Version Deep Security Agent version. string 12.0.0.1

AWS

Property Description Data type Examples
Tag

The computer's AWS tag key:value pair, as seen on Computers > Details > Overview > General under Virtual machine Summary, in Cloud Instance Metadata.

Type the tag name, then its value. Case-sensitive.

 string

Tag Key: env

Tag Value: staging
Security Group Name The computer's associated AWS security group name, as seen on Computers > Details > Overview > General under Virtual machine Summary, in Security Group(s). string SecGrp1
Security Group ID The computer's AWS security group ID, as seen on Computers > Details > Overview > General under Virtual machine Summary, in Security Group(s). string sg-12345678
AMI ID The computer's Amazon Machine AMI ID, as seen on Computers > Details > Overview > General under Virtual machine Summary, in AMI ID. string ami-23c44a56
Account ID

The computer's associated 12-digit AWS Account ID, as seen on Computers when you right-click Amazon Account and select Properties.

Results include computers in sub-folders.

 string 123456789012
Account Name

The computer's associated AWS Account Alias, as seen on Computers when you right-click the AWS Cloud Connector and select Properties.

Results include computers in sub-folders.

 string MyAccount-123
Region ID

The computer's AWS region suffix.

Results include computers in sub-folders.

 string us-east-1
Region Name

The computer's associated AWS region name.

Results include computers in sub-folders.

 string US East (Ohio)
VPC ID

The computer's Virtual Private Cloud (VPC) ID.

If an alias exists, the folder name is the alias, followed by the VPC ID in parentheses. Otherwise the folder's name is the VPC ID.

Results include computers in sub-folders.

 string vpc-3005e48a
Subnet ID

The computer's associated Virtual Private Cloud (VPC) subnet ID.

If an alias exists, the folder name is the alias, followed by the VPC subnet ID in parentheses. Otherwise the folder's name is the VPC subnet ID.

Results include computers in sub-folders.

 string subnet-b1c2e468
Directory ID The ID of the AWS directory where the user entry associated with an Amazon WorkSpace resides. The directory ID is seen on the Computers > Details > Virtual machine Summary, in the WorkSpace Directory field. That field takes the format <directory_alias>(<directory_ID>), for example, myworkspacedir(d-9367232d89). string d-9367232d89

Azure

Property Description Data type Examples
Subscription Name

As of Deep Security Manager 12.0, the Subscription Name is no longer collected. It remains visible in the drop-down list of properties in case the information was obtained through a previous version of the manager.

The computer's associated Azure subscription account ID, as seen on Computers when you right-click Azure and select Properties.

Results include computers in sub-folders.

 string MyAzureAccount
Resource Group The computer's associated resource group. string MyResourceGroup
Location The computer’s location name string East US
Tag

The computer's Azure tag key:value pair, as seen on Computers > Details > Overview > General under under Virtual machine Summary, in Cloud Instance Metadata.

Type the tag name, then its value. Case-sensitive.

 string

Tag Key: env

Tag Value: staging

GCP

Property Description Data type Examples
Label

The computer's GCP label key:value pair, as seen on Computers > Details > Overview > General under Virtual machine Summary, in Cloud Instance Metadata.

Type the label key, and then its value. Case-sensitive.

 string

Label Key: env

Label Value: staging

Network Tag The computer's network tag, as seen on Computers > Details > Overview > General under Virtual machine Summary, in Cloud Instance Metadata. string production

vCenter

Property Description Data type Examples
Name

The computer's associated vCenter.

Results include computers in sub-folders.

 string vCenter - lab13-vc.example.com
Datacenter

The computer's associated vCenter data center.

Results include computers in sub-folders.

 string lab13-datacenter
Folder

The computer's vCenter folder.

Results include computers in sub-folders.

 string db_dev
Parent ESX Hostname

The hostname of the ESXi hypervisor where the computer's guest VM is running, as seen on Computers.

 string lab13-esx2.example.com
Custom Attribute

The computer's assigned vCenter custom attribute, as seen on Computers > Details in Virtual machine Summary.

string

(comma-separated attribute name and value)

 env, production
Power State

The computer's vCenter state, as seen on Computers > Details in VMware Virtual machine Summary.

string

(option in list)

 Powered On

vCloud

Property Description Data type Examples
Name

The computer's associated vCloud.

Results include computers in sub-folders.

 string vCloud-lab23
Datacenter

The computer's associated vCloud data center.

Results include computers in sub-folders.

 string lab13-datacenter
vApp

The computer's associated vCloud data center folder.

Results include computers in sub-folders.

 string db_dev

Active Directory

Property Description Data type Examples
Name The hostname of the Microsoft Active Directory or LDAP directory.

Results include computers in sub-folders.

 string ad01.example.com
Folder

The computer's Microsoft Active Directory or LDAP folder name.

Results include computers in sub-folders.

 string Computers

Operators

Smart folder operators indicate whether matching computers should have a property value that is identical, similar, or dissimilar to your search term. Not all operators are available for every property.

Operator Description Example usage
EQUALS The search query only finds computers that are an exact match. A search query for 'Windows' in the Operating System property does not find computers with 'Windows 7' or 'Microsoft Windows'.
DOES NOT EQUAL The search query finds any computers that are not an exact match. A search query for 'Amazon Linux (64 bit)' in the Operating System property finds all computers other than Amazon Linux 64-bit machines.
CONTAINS The search query finds any computers that contain the search term. A search query for '203.0.113.' in the IP Address property finds any computers on the 203.0.113.xxx subnet.
DOES NOT CONTAIN The search query finds any computers that do not contain the search term. A search query for 'Windows' in the Operating System property finds any computers that do not have 'Windows' in their operating system name.
ANY VALUE The search query finds all computers with the selected property. A search query in the Group Name property finds all computers in that group.
IN RANGE The search query finds all computers between the specified start and end range. A search query in the IP Address property with Start Range 10.0.0.0 and End Range 10.255.255.255 would find all computers with IP addresses between 10.0.0.0 and 10.255.255.255.
NOT IN RANGE The search query finds all computers that are not between the specified start and end range. A search query in the IP Address property with Start Range 10.0.0.0 and End Range 10.255.255.255 finds all computers that have IP addresses outside the range of 10.0.0.0 and 10.255.255.255.
Yes The search query finds all computers with the selected property. A search query with 'Yes' selected for the Docker property finds any computers with the Docker service running.
No The search query finds all computers that do not have the selected property. A search query with 'No' selected for the Docker property would find any computers that do not have the Docker service running.
OLDER THAN

The search query finds all computers prior to the specified date for the property.

Used with an accompanying DAYS, WEEKS, HOURS, or MINUTES operator.

A search query with 'OLDER THAN', '7', 'DAYS' for the 'Last Successful Recommendation Scan' property finds computers that have had a successful recommendation scan 8 days or longer ago.

 
MORE RECENTLY THAN

The search query finds all computers more recent than the specified date for the property.

Used with an accompanying DAYS, WEEKS, HOURS, or MINUTES operator.

 A search query with 'MORE RECENTLY THAN', '1', 'MONTH' for the 'Last Successful Recommendation Scan' property finds computers that have had a successful recommendation scan earlier than 1 month ago.
NEVER

The search query finds all computers that do not match the property.

A search query with 'NEVER' for the 'Last Successful Recommendation Scan' property finds computers that have never had a successful recommendation scan.