Custom rules support certain macros in the Path and Process fields. You can see a menu of macros by typing the left angle bracket (<) character in either of these fields.
The following types of macros are supported in Custom rules, and many are supported in other rules where appropriate, including Memory rules, Registry rules, Script rules, File (name) Bans, and Rapid Configs:
- Path macros – There are two types of path macro:
- Built-in Carbon Black App Control path macros (for example, <AppData>) are a subset of the well known folders for Windows – some may operate across platforms.
- You can insert a macro for any location that corresponds to a Windows known folder by using its GUID.
Both types always identify a location rather than a specific file. Path and Registry macros can be an effective for dynamically identifying a path on all computers for the specified platform, even when the files you want to affect are in different locations on different computers.
- Registry macros – These macros allow you to extract file paths and names from keys in the Windows Registry.
- OnlyIf macros – These macros specify conditions required for a given parameter in a rule to be expanded. If you want rules to affect only a subset of your agents, you can apply OnlyIf macros to all parameters to dictate which agents accept the rule, independent of which policy they are in.
- Command-line macros – These macros specify that a rule will only match if the process command line matches the specified criteria. They can always be used in the process field, and can be used in the target field if the target is a process (for example, process create).
- Certificate/hash-matching macros – These macros behave much like the OnlyIf macros, making rules affect an agent only if conditions match specified criteria. For example, you can specify that a rule is applied only if the issuer name for the certificate for a file in the specified path matches a specified string.
The console displays an error message if you enter an invalid macro.
- A path macro can be used only at the beginning of a Path or File in a rule (i.e., with no other text before it in the string). OnlyIf and Registry macros can be used anywhere in the Path or File specification for a Windows rule.
- Most macros are for the Windows platform.
- You can use macros with network paths by specifying the macro after the path, for example,
<OnlyIf:Hostname:Laptop-7>\\share\folder.
Common Path Macros
Carbon Black App Control provides built-in path macros that are based on a subset of the well-known folders for a platform (CSIDLs for pre-Vista Windows versions and KNOWNFOLDERIDs for Vista and later). Each path macro consists of a unique string surrounded by angle brackets.
<MyDocuments> in a Windows rule identifies the
My Documents folder for each user on each Windows computer, regardless of its actual location on an individual computer.
- For a full description of CSIDLs, see http://msdn.microsoft.com/en-us/library/windows/desktop/bb762494(v=vs.85).aspx
- For a full description of KNOWNFOLDERIDs, see http://msdn.microsoft.com/en-us/library/windows/desktop/dd378457(v=vs.85).aspx
Note: In addition to using the shorter, built-in macros for known folders, you can use the GUID string for any known folder documented in the link above. For more details, see Using Windows KNOWNFOLDER GUIDs in Macros.
Because a path macro always represents a directory, it is processed as if it is followed by the directory delimiter (slash or backslash), even if you have not added one. For example, <AppData> in a Windows rule is interpreted as <AppData>\ before it is expanded, and it applies to the Application Data directory and all of its files, subdirectories, sub-subdirectories, etc. Similarly, <AppData>myapp\ is interpreted as <AppData>\myapp\. If you add a backslash yourself, the rule processor does not add a second one.
To see the menu of macros, type a left angle bracket (<) as the first character in the Path or File box or the Process box on the add rule page. As you type, the auto-complete menu adjusts to show only those choices matching the string you have typed so far for the platform you have chosen. The following table shows the available path macros for Windows rules.
The table includes a Per User column to indicate which macros are expanded based upon the logged in user. There is a delay after a user is logged in before rules tied to that user take effect, and this delay varies by how many rules you have and how long it takes to expand macros or group membership in them. Because of this, rules with user-specific macros or that specify a user-group may not take effect immediately after a user logs on.
| Macro |
Per User |
Description |
|---|---|---|
<AppData> |
Yes |
Directory that serves as a common repository for application-specific data. Maps to:
|
<CommonAppData> |
No |
Directory that contains application data used by and accessible to all users. This folder is used for application data that is not user specific. For example, an application can store a spell-check dictionary, a database of clip art, or a log file here. Maps to:
|
<CommonDesktopDirectory> |
No
|
Directory that contains files and folders that appear on the desktop for all users. Maps to:
|
<CommonDocuments> |
No
|
Directory that contains documents that are common to all users. Maps to:
|
<CommonPrograms> |
No
|
Directory that contains the directories for the common program groups that appear on the Start menu for all users. Maps to:
|
<CommonStartMenu> |
No
|
Directory that contains the programs and folders that appear on the Start menu for all users. Maps to:
|
<CommonStartup> |
No
|
Directory that contains the programs that appear in the Startup folder for all users. Maps to:
|
<Cookies> |
Yes |
Directory that serves as a common repository for Internet cookies. Maps to:
|
<DesktopDirectory> |
Yes |
Directory used to physically store file objects on the desktop (not the desktop folder itself).
|
<InternetCache> |
Yes |
Directory that serves as a common repository for temporary Internet files. Maps to:
|
<LocalAppData> |
Yes |
Directory that serves as a data repository for local (non-roaming) applications. Maps to:
|
<MyDocuments> |
Yes |
Virtual folder that represents the My Documents folder. The file system directory used to physically store a user's common repository of documents. Maps to:
|
<Profile> |
Yes |
User's profile folder. Maps to:
|
<ProgramFiles> |
No |
Program Files folder. Maps to:
|
<ProgramFilesx86> |
No |
32-bit Program Files folder. Maps to:
|
<ProgramFilesCommon> |
No |
Folder for components shared across applications. Maps to:
|
<ProgramFilesCommonx86> |
No |
32-bit Program Files folder. Maps to:
|
<Programs> |
Yes |
Directory that contains the user's program groups (which are themselves file system directories). Maps to:
|
<RecycleBin> |
Yes |
Directory for the Recycle Bin. The location depends on the type of operating system and file system. Maps to:
|
<StartMenu> |
Yes |
Directory that contains Start menu items. Maps to:
|
<Startup> |
Yes |
Directory that corresponds to the user's Startup program group. Maps to:
|
<System> |
No |
The platform-specific Windows System folder. Maps to:
|
<Systemx86> |
No |
32-bit “System” folder on both 32-bit and 64-bit operating systems. Allows you to specify that a rule applies only to 32-bit versions of utilities. Maps to:
|
<Windows> |
No |
The Windows directory or SYSROOT. This corresponds to the %windir% or %SYSTEMROOT% environment variables. Maps to:
|
Using Windows KNOWNFOLDER GUIDs in Macros
The Windows path macros provide shortcuts to a significant number of the folders that you might want to include in a path for a rule. However, they do not cover all of the possible folders in the list of Windows known folder IDs. If necessary, you can use Microsoft’s unique identifier (GUID) for a known folder in a rule macro, whether or not that folder has a built-in Carbon Black App Control shortcut.
For information on the GUIDs for known folders, see http://msdn.microsoft.com/en-us/library/windows/desktop/dd378457(v=vs.85).aspx.
For example, if you wanted to include the Applications folder (FOLDERID_AppsFolder) in a rule path, you can look it up at the location above and use its GUID in a macro as shown here: <KnownFolder:{1e87508d-89c2-42f0-8a7e-645a0f50ca58}>, where {1e87508d-89c2-42f0-8a7e-645a0f50ca58} is the GUID.
On systems where the known folder does not exist, the rule simply does not “expand”; that is, the path is not converted from the macro to an actual path on the endpoint’s, and so the rule does not do anything. This could be the case in the following situations:
- Windows versions prior to Vista cannot process known folder GUIDs.
- Some known folders were introduced in later versions of Windows. For example, FOLDERID_AccountPictures was introduced in Windows 8, and so rules that use this macro are never applied to endpoints running earlier versions.
- Some known folders might have been deleted on specific systems.
Some known folders are user-specific, and macros using their GUIDs must specify the user to be effective. User-specific folders are listed as Folder Type PERUSER on the Microsoft page for Known Folders. If you use one of these folders in a macro, you must specify the intended users in the rule. Otherwise, the rule is only be expanded for the SYSTEM user’s version of the known folder. In addition to making the rule ineffective for other users, this often means it can never be triggered at all.
For example, to receive a report whenever a file is written to a user's Downloads directory (FOLDERID_Downloads), you can create a rule that included the following fields:
- Rule Type: Advanced
- Operation: Write
- Write Action: Report
- Path Or File: <KnownFolder:{374DE290-123F-4565-9164-39C4925E467B}>\*
- Process: *
- User Or Group: Authenticated Users
If you left out the "User: Authenticated Users" specification, the rule would not expand at all since the "SYSTEM" user does not have a Downloads directory.
OnlyIf Macros
The Custom rules page includes controls that specify conditions under which a rule is applied. For example, by restricting the rule to computers in certain policies. As a supplement to these user interface controls, you can also use OnlyIf macros to specify other conditions for a rule.
OnlyIf macros can be used in Custom rules, Registry rules, Memory rules, Script rules, and File rules (by name). You enter OnlyIf macros in rule fields that accept paths. In the case of Custom rules, this includes the Path or File and Process fields.
OnlyIf macros work with
Carbon Black App Control Agents beginning with v7.2.0. They do not function on earlier agents. In addition, some
OnlyIf macros may require the most recent agent.
The syntax of OnlyIf macros is:
<OnlyIf:condition:value >
For example, <OnlyIf:Hostname:Laptop-7> instructs the agent to apply the parameter that follows it only if the system on which the action is attempted is Laptop-7. This can be entered into the Path or File field of a Custom rule.
If a rule uses a single path and a single process, you can put the OnlyIf macro in either field and it has the same effect. For rules with multiple path or multiple processes, the location of the OnlyIf macro could be significant. For example, if you have a rule with three different paths but a single process, adding an OnlyIf clause to the process field makes it apply to all paths. If you wanted the OnlyIf test used only for one path, you would put the OnlyIf macro in that path field only. If you want it applied to multiple paths, it must precede each of them.
OnlyIf macros use the same wildcard comparison logic used for target/process name matching in Custom rules. Strings in the macros are case-insensitive and some arguments can use * and ? wildcards. You can chain multiple macros together in one path.
The table below lists and describes the conditions you can use in OnlyIf macros, and provides examples of each.
Some OnlyIf macros rely on metadata of the files that match the other specifications of a Custom Rule. These can be used to ensure that rules apply only apply if a particular version of a product is installed. Not all files have all of the metadata types for which macros are available. The format of metadata-based OnlyIf macros is:
< OnlyIf: MetadataType: Pattern: Filename>,
where Pattern is the (possibly wildcarded) pattern you want to compare the metadata field against, and Filename is the full path of the file whose metadata you want to test. The pathname argument cannot contain wildcards.
For example, if you include the following in a process or path field: < OnlyIf:Company:*Carbon Black*:<ProgramFilesX86>\bit9\parity agent\parity.exe> ,
the rule is expanded only if the binary for parity.exe on the path shown contains “Carbon Black” in the Company field of its metadata. Because of the wildcards, this would match files whose Company field showed only “Carbon Black” but also where the company name included “Inc” and commas or periods in the name string. The table below lists the OnlyIf macros that rely on file metadata in a separate section.
| OnlyIf Condition |
Description and Example |
|---|---|
| ConnectedToServer |
Expand only if the agent is connected to the server (Yes) or only if the agent is disconnected (No). Example: <OnlyIf:ConnectedToServer:Yes> |
| ProcessorArchitecture |
Expand only if the processor for the agent computer matches the value specified. The choices are x86 (32-bit) and x64 (64-bit). Example: <OnlyIf:ProcessorArchitecture:x86> |
| HostName |
Expand only if the NETBIOS machine name matches the specified string. Example: <OnlyIf:HostName:*BSMITH-1*> PLATFORM NOTE: This condition is effective for all OS platforms. |
| DomainName |
Expand only if the agent computer is in the specified domain. Example: <OnlyIf:DomainName:*mycompany.local> PLATFORM NOTE: This condition is effective for all OS platforms. |
| HardwareManufacturer |
Expand only if the computer manufacturer matches the specified string. Example: <OnlyIf:HardwareManufacturer:*Dell*> |
| HardwareModel |
Expand only if the computer model matches the specified string. Example: <OnlyIf:HardwareModel:*XPS> |
| ServiceName |
Expand only if a service exists with name that matches the specified string. Example: <OnlyIf:ServiceName:*Parity Server*> |
| ServiceDisplayName |
Expand only if a service exists with a display name that matches the specified string. Example: <OnlyIf:ServiceDisplayName:*Parity Server*> |
| Driver |
Expand only if the specified driver is loaded. Example: <OnlyIf:Driver:mfehidk> |
| Virtualized |
Expand only if the agent is running on a VM (if the value is 1), or is not running on a VM (if the value is 0). Example: <OnlyIf:Virtualized:1> |
| DEPSupported |
Expand only if DEP is supported on this system (if the value is 1), or if not supported (if the value is 0). Example: <OnlyIf:DEPSupported:0> |
| RegKeyExists |
Expand only if the specified registry key exists . Example: <OnlyIf:RegKeyExists:HKLM\Software\Foo> |
| RegValueExists |
Expand only if the specified registry value exists. Example: <OnlyIf:RegValueExists:HKLM\Software\Foo> |
| RegValueIs |
Expand only if the data contained in the specified key matches the specified pattern. In the example, Foo is the key and *Bar* is the pattern. Example: <OnlyIf:RegValueIs:HKLM\Software\Foo:*Bar*> |
| HostId |
Expand only for a computer whose HostID matches the specified number. Example: <OnlyIf:HostId:5> PLATFORM NOTE: This condition is effective for all OS platforms. |
| FileExistsOnDisk |
Expand only if a file with the specified name exists on the disk. This can be any file accessible to the local system user, and does not need to be tracked by Carbon Black App Control. In the example below, if c:\windows\system32\foo.txt exists, then the system would create a rule that targets d:\foo.exe. note that a full path must be provided in the OnlyIf clause Example: <OnlyIf:FileExistsOnDisk:<System>\foo.txt>d:\foo.exe |
| FileIsTracked |
Expand the rule only if a file with the specified name is present and is an interesting file that is tracked by the Carbon Black App Control Agent. A full path must be used. Example: <OnlyIf:FileIsTracked:<System>\calc.exe> |
| HashExists |
Expand the rule only if a file with the specified hash is present and is an interesting file that is tracked by the Carbon Black App Control Agent. Example: <OnlyIf:HashExists: 1c94cd9e3ee959ff6002eca3c5e7e7fdb9158657> |
| Bit9Version:Is |
Expand the rule only if the Carbon Black App Control Agent version matches that specified. Example: <OnlyIf:Bit9Version:Is:7.2.0.233> PLATFORM NOTE: This condition is effective for all OS platforms. |
| Bit9Version:Atleast |
Expand the rule only if the Carbon Black App Control Agent version is the version number specified or greater. Example: <OnlyIf:Bit9Version:Atleast:7.2.0.233> PLATFORM NOTE: This condition is effective for all OS platforms. |
| Bit9Version:AtMost |
Expand the rule only if the Carbon Black App Control Agent version number is not greater than the version specified. Example: <OnlyIf:Bit9Version:AtMost:7.2.0.233> PLATFORM NOTE: This condition is effective for all OS platforms. |
| OSVersionIs |
Expand the rule only if the operation system version (major.minor.point) on the agent system matches that specified. Example: <OnlyIf:OSVersionIs:10.6.8>
Note:
PLATFORM NOTE: This condition is effective for all OS platforms.
|
| OSVersionAtleast |
Expand the rule only if the operation system version (major.minor.point) on the agent system is the version specified or greater. Example: <OnlyIf:OSVersionAtleast:10.6.8> PLATFORM NOTE: This condition is effective for all OS platforms. |
| OSVersionAtMost |
Expand the rule only if the operation system version (major.minor.point) on the agent system is the version specified or less . Example: <OnlyIf:OSVersionAtMost:10.6.8> PLATFORM NOTE: This condition is effective for all OS platforms. |
| OSVersionString |
Expand the rule only if the detailed operating system description on the agent system matches the specified pattern. Example: <OnlyIf:OSVersionString:*Windows Server 2008*> PLATFORM NOTE: This condition is effective for all OS platforms. |
| ServerEdition |
Expand the rule only if this is a server edition of the operating system (if the value is 1) or if it is not (if the value is 0). Example: <OnlyIf:ServerEdition:1> |
| OnlyIf Macros based on File Metadata |
|
| BuildAttributes |
Expand only if the build attributes metadata for a file matches the specified string. |
| BuildTime |
Expand only if the build time metadata for a file matches the specified string. |
| PrivateBuild |
Expand only if metadata indicates that this is a private build. |
| SpecialBuild |
Expand only if metadata indicates that this is a special build. |
| Comments |
Expand only if the comments metadata for a file matches the specified string. |
| Company |
Expand only if the company metadata for a file matches the specified string. |
| Copyright |
Expand only if the copyright metadata for a file matches the specified string. Example: <OnlyIf:Copyright:Copyright 1984-2015 Adobe Systems Inc.:<ProgramFiles>\Adobe\Acrobat Reader DC\Reader\AcroRD32.exe> |
| Description |
Expand only if the file description metadata for a file matches the specified string. This is sometimes just the file name. Example: <OnlyIf:Description:”VMware Horizon Media Engine Library”:<ProgramFiles>\VMware\VMware Horizon Media Engine\VMWMediaProvider.dll> |
| FileType |
Expand only if the file type metadata of a file matches that specified. Example: <OnlyIf:FileType:”Application (.exe)”:<ProgramFiles>Dell Webcam\Dell Webcam Central\WebcamDell2.exe> |
| FileVersion |
Expand only if the file version metadata of the file matches the specified file version number. Example: <OnlyIf:FileVersion:1.0.38.0:<ProgramFiles>Dell Webcam\Dell Webcam Central\WebcamDell2.exe> |
| Language |
Expand only if the language metadata of the file matches the specified string. Example: <OnlyIf:Language:”English (United States)”:<ProgramFiles>\Mozilla Firefox\plugins\npMeetingJoinPluginOC.dll> |
| Manufacturer |
Expand only if the manufacturer metadata of the file matches the specified name. Example: <OnlyIf:Manufacturer:Microsoft Corporation:<CommonPrograms>\newfolder\newfile.exe> |
| OriginalName |
Expand only if the original name metadata for a file matches the specified string. Example: <OnlyIf:OriginalName:Extractor.exe:<DesktopDirectory>\e_codec.exe |
| PackageCode |
Expand only if a product matching the specified package code is installed. Example: <OnlyIf:PackageCode:{F1D61F7C-6E4C-4902-9278-0F93131BE2D2}:<ProgramFiles>\myapp\myapp.exe> See http://blogs.msdn.com/b/pusu/archive/2009/06/10/understanding-msi.aspx for more about Microsoft package codes. |
| ProductName |
Expand only if a product with the specified name is installed. In the example below, asterisk wildcards indicate that the Product Name contains “Microsoft Office”. Example: <OnlyIf:ProductName:*Microsoft Office*:<Program Filesx86>\Microsoft Office\Office16\ACCICONS.EXE> |
| ProductCode |
Expand only if a product with a matching GUID is installed. Example: <OnlyIf:ProductCode:{F1D61F7C-6E4C-4902-9278-0F93131BE2D2}:<ProgramFiles>\myapp\myapp.exe> See http://blogs.msdn.com/b/pusu/archive/2009/06/10/understanding-msi.aspx for more about Microsoft product codes. |
| ProductVersion |
Expand only if the product version metadata of a file matches the specified product version number. Example: <OnlyIf:ProductVersion:6.0.0170.4:<ProgramFiles>\java\jre6\java.exe> |
| TargetOS |
Expand only if the target operating system for the application build matches the specified value. |
| UpgradeCode |
Expand only if a product matching the specified upgrade code is installed. Example: <OnlyIf:UpgradeCode:{F1D61F7C-6E4C-4902-9278-0F93131BE2D2}:<ProgramFiles>\myapp\myapp.exe> See http://blogs.msdn.com/b/pusu/archive/2009/06/10/understanding-msi.aspx for more about Microsoft upgrade codes. |
| AboutURL |
Expand only if the About URL for the application in the path matches the specified URL. |
| HelpURL |
Expand only if the Help URL for the application in the path matches the specified URL. |
| UpdateURL |
Expand only if the Update URL for the application in the path matches the specified URL. This URL is used to check for application updates. |
Additional Macros
In addition to the OnlyIf macros, the macros in the Command-Line Macros table and the Additional Macros table can be used to specify conditions under which a rule must be expanded and applied.
- You can use wildcards in cmdline macros, for example, to trigger a rule on a particular string in a path regardless of where that string appears.
- Inserting other macros inside cmdline macros is not supported.
| Test Condition |
Description and Example |
|---|---|
| <CmdLine:X> |
Apply the rule only if the full command line matches specified pattern (X). Example: <CmdLine:*\svn -vq status myfile> matches |
| <CmdLineArgumentIdx:X:Y> |
Apply the the rule only if the command line contains at least X + 1 arguments, and argv[X] matches the pattern Y. Example: <CmdLineArgumentIdx:3:”get help”> matches |
| <CmdLineAnyArgument:X> |
Apply the rule if any argument in the command line matches pattern X. Example: <CmdLineAnyArgument:bar.exe> matches both |
| <CmdLineArgumentName:X:Y> |
Apply the rule if the command line contains argument X and the argv[X+1] (the next argument after X) matches Y. Example: <CmdLineArgumentName:/x:*\foo.msi"> matches and also |
| Test Condition |
Description and Example |
|---|---|
| <CertIssuer: name> |
Evaluate the rule if the specified name string matches the Issuer name string in the certificate details for the file. Only effective in the Publisher fields for target and process. |
| <CertSerial:number > |
Evaluate the rule if the specified serial number matches the Serial number in the certificate details for the file. Only effective in the Publisher fields for target and process. |
| <CertSHA1:hash> |
Evaluate the rule if the specified hash value matches the SHA1 hash in the certificate details for the file. Only effective in the Publisher fields for target and process. |
| <CertMD5:hash> |
Evaluate the rule if the specified hash value matches the MD5 hash in the certificate details for the file. Only effective in the Publisher fields for target and process. |
| <Sha256:hash> |
Evaluate the rule if a file or process matching the path specified in the rule has the specified Sha256 hash value. This macro normally should not be used in the target field of Write rules because Write rules are evaluated before the write occurs (and therefore before the hash is known). |
| <HostedService:servicename> |
This macro ensures that the agent only applies the rule to the specific svchost.exe instance hosting the specified service rather than all svchost.exe instances. For use only in the process pattern field. Example: <HostedService:EMET_Service> |
| <SourceNameOnly> |
For rename operations, compare the path only to the source name. This macro can be placed in the "target pattern" field of any custom rule. If this macro or the <DestinationNameOnly> macro are not included in a rule specification, the agent compares the pattern against both the source and destination names, and the rule matches if either the source or destination name matches. <DestinationNameOnly> and <SourceNameOnly> cannot be used in the same field. Example: This could be used to approve files that are moved out of the c:\temp folder: c:\temp\*<SourceNameOnly>. |
| <DestinationNameOnly> |
For rename operations, compare the path only to the destination name. This macro can be placed in the "target pattern" field of any custom rule. If this macro or the <SourceNameOnly> macro are not included in a rule specification, the agent compares the pattern against both the source and destination names and the rule matches if either the source or destination name matches. <DestinationNameOnly> and <SourceNameOnly> cannot be used in the same field. Example: The following could be used to approve files when they are moved into the c:\foo folder: c:\foo\*<DestinationNameOnly>. |
Enter a Windows Registry Macro
For Windows rules, Registry (Reg) macros represent Windows Registry values, which you can use in a Path or Process specification. Unlike path macros, reg macros have variable content between their brackets. A Reg macro must resolve to a value, not a key.
Reg macros are evaluated on each agent the first time the rule becomes available to that agent. If the rule is valid for that computer, it is enabled. For example, it is possible to create a rule that Promotes an updater for an application called “MyApp” by using the path value written to the registry. On systems with MyApp Update installed, <Reg:HKLM\Software\MyApp\Update\path> might expand to C:\Program Files (x86)\MyApp\Update\ MyAppUpdate.exe. On systems that did not include the update program, the rule would not be created.
Once evaluated, rules that use Reg macros are not re-evaluated on a computer unless certain conditions occur. This means that changes to the Registry during a session might not affect rule behavior, even if the change would enable or disable the rule. The conditions that cause "re-expansion" of rules on an agent are:
- the agent is stopped and restarted (e.g., the computer is shut down and restarted)
- a new user logs in
- the agent is reassigned to a policy with different rules
- rules are created, edited or deleted on the server
- the agent detects the end of an MSI install/upgrade
- manual re-evaluation is triggered using a special Carbon Black Support command.
Use the steps below to enter a Reg macro.
Procedure
Example: Using HKLM as the top-level Registry node
<Reg:HKLM\YourSpecifiedPath>
