Configuring Credentials for Non-Domain-Joined and Linux/Unix Scanners

Overview

This topic explains how to configure the credentials a discovery scanner uses to authenticate to non-domain-joined and Linux/Unix targets. It covers credential configuration only; it does not cover end-to-end Linux/Unix discovery setup. To create and configure a Linux/Unix discovery source from start to finish, see Creating a Linux/Unix Discovery Source.

When running Discovery on non-domain joined or Linux/Unix targets, there are two methods of finding local administrator credentials to authenticate to the target:

• Specify a secret with an expected default password - recommended for performing an initial scan if you have a known password or key for a privileged account.
• Specify a Secret Search Filter - recommended when you cannot use a default password because each machine’s account password is unique.
  A Secret Search Filter dynamically searches for a secret with a name or folder location that corresponds to the target scanned. If a matching secret is found, Secret Server will authenticate to the target using the administrator credentials in the secret.

Setting Credentials on a Discovery Scanner

1. From the left menu-bar, hover over Discovery and select Sources, the page will open by default on the Sources tab.

2. Select one of the enabled discovery sources, and inside that page, click on the Scanners tab.

3. Select a scanner from the ones available, a details page will popup on the right side of the screen where you will see the Edit Scanner option.

4. Select the Edit Scanner option and here you will see different settings for that scanner. Under Credentials, choose among the following options:

   • Click Add Secret to specify a default credential.
   • Click Add Secret Search Filter to specify an existing secret search filter.

Secret Server will try the secrets and secret search filters in sequence until it finds a match.

Creating a Secret Search Filter

If you decided to create a secret search filter, perform the following:

1. In the search bar type Discovery secret search filters, this will cause the Scanner definition page to appear.

2. Select Create Secret Search Filter and the following options will appear:

3. Specify all the mandatory* settings along with any others you need, as described below:

   • Secret Name Pattern: Specifies the pattern that Secret Server will search for. The pattern can contain tokens that Secret Server replaces with values from the target machine before it runs the search. For example, if the pattern is $MACHINE\Administrator and the scanner is scanning a machine named appserver01, Secret Server searches for a secret named appserver01\Administrator. For the full list of tokens, see Secret Search Filter Tokens.

   • State: Enabled or not.
   • Folder: Specifies the folder to search within.
   • Secret Template: Specifies the template that returned secrets should be based on.
   • Include Subfolders: Specifies that the search should include the specified folder as well as subfolders.
   • Expect Single: Specifies that only one result should be returned. If more than one is returned, Secret Server will log an error to the discovery log.
   • Allow Partial Match: Specifies that secret names will be returned if they partially match the pattern. By default the secret name must be an exact match to the secret name pattern.

4. Click Save when all your settings have been specified and go back to your discovery source, i.e. back to the Edit Scanner page.

5. Click Add Secret Search Filter and select the filter you just created.

Now, when scanning a machine, Secret Server will try a default credential, and then it will try the secret returned by the search filter.

Secret Search Filter Tokens

The Secret Name Pattern field supports token substitution. When a discovery scanner runs, Secret Server replaces each token with the matching value from the computer being scanned, then searches for a secret whose name matches the result. Two kinds of tokens are available: built-in tokens and dynamic tokens.

Built-In Tokens

The following tokens are always available, regardless of scanner type:

Token	Replaced with
$Machine	The computer's NetBIOS name (ComputerName)
$Domain	The discovery source's domain name
$DistinguishedName	The computer's Active Directory distinguished name
$DnsHost	The computer's DNS host name

For example, the pattern $Machine\Administrator matches a secret named appserver01\Administrator when scanning appserver01, and the pattern $Domain - Network Admin matches a secret named corp.example.com - Network Admin when the discovery source's domain is corp.example.com.

Dynamic Tokens

In addition to the built-in tokens, any property that a scanner stores in the computer's additional data is available as a $<PropertyName> token in the Secret Name Pattern for later scans against that computer. These properties are name/value pairs and vary by scanner type.

This is mainly useful with Extensible Discovery. If a custom machine scanner retrieves or derives a value, such as an expected administrator account name, and returns it as a named output property, that value can be referenced as a token in the search filter. For example, if administrator account names follow a predictable pattern, or can be looked up from an external system at scan time, a custom machine scanner can surface that value and make it available as a token.

Keep the following limitations in mind:

• Dynamic tokens require Extensible Discovery with custom PowerShell scripting.
• The value must be knowable at the machine scanner stage, before account discovery runs.
• The value must be deterministic or retrievable from an external system. It cannot come from the output of the discovery scan itself.

Why $Username Is Not Supported

The secret search filter runs before the scanner authenticates to the target. Its job is to find the credential Secret Server uses to log in so that the scanner can run, so it is evaluated at machine-scan time, before any accounts have been discovered on that machine. Discovered account names are the output of the local account scanner, which runs after authentication. A $Username token in the filter would therefore require knowing which accounts exist on a machine before you could authenticate to discover them, so it is not available in the built-in scanner flow.