Use the API to create shared and global rulesets

For an overview of Application Control, see Lock down software with Application Control. For initial configuration instructions, see Set up Application Control.

Using the Workload Security API, you can create shared rulesets and global rules. You can use one type of ruleset or a combination. For more information, see Create a shared ruleset and Add global rules.

• Local ruleset: Rules that are added as part of a computer's software inventory or when in maintenance mode are stored only on the protected computer and are not visible in Workload Security. Allow or block rules that you configure in Workload Security are sent to the agent and stored in both places. Since agents do not transfer their inventory information to Workload Security, local rulesets offer better performance than shared rulesets.

  To determine whether software is new or has changed, Deep Security Agent version 10 compares the file with the initially installed software's SHA-256 hash, file size, path, and file name (they have a file-based local ruleset). Deep Security Agent version 11 and later compare only the file's SHA-256 hash and file size (they have a hash-based local ruleset). Since the rules created by version 11 or later agents compare only the unique hash and file size, a rule continues to be applied even if the software file is renamed or moved. As a result, using version 11 or later agents reduces the number of software changes that you need to deal with. Version 10 agents continue to use a file-based local ruleset until they are upgraded to version 11 or later. When you upgrade, its local ruleset is converted to use hash-based rules.

  If there are multiple file-based rules for the same hash value, they are consolidated into one hash-based rule. If the rules being consolidated conflict with each other (one rule blocks the file and another allows it), the new hash-based rule is an allow rule.

• Shared ruleset: Synchronizes all of its rule data onto both Deep Security Agent and Deep Security Manager. This increases network and disk space usage. However, it may be easier if you need to verify the rules from the initial inventory scan or maintenance mode, or if you manage a server farm with many computers that should be identical. For example, if you have a server pool of identical LAMP web servers, or if they are virtual machines (VMs) that are part of an auto-scaling group, shared rulesets can be useful. It can also reduce administrator workload.

  Do not use a shared ruleset if you enabled Block unrecognized software until it is explicitly allowed, and if computers are merely similar (but not identical). It blocks all software on other computers that is not in the first computer's ruleset. If those include critical files, it could break the OS. If that happens, you may be required to reinstall, revert to a backup, or use the OS recovery mode.

  When you create a new shared ruleset, it can only contain hash-based rules (rules that compare only a file's hash and size). If you created a shared ruleset using an earlier version of Workload Security, it contains file-based rules (rules that compare a file's name, path, size, and hash). Older shared rulesets continue to use file-based rules until all agents using the shared ruleset are upgraded to agent version 11 or later. Then the shared ruleset is converted to use hash-based rules.

  Do not create a new shared ruleset until all agents are upgraded to version 11.0 or later. New shared rulesets are hash-based and are not compatible with agent version 10.3 or earlier, which supports only file-based rulesets.

  If there are multiple file-based rules for the same hash value, they are consolidated into one hash-based rule. If the rules being consolidated conflict with each other (one rule blocks the file and another allows it), the new hash-based rule will be an allow rule.

  To create shared rules, see Create a shared ruleset.

• Global rules: Similarly to shared rulesets, global rules are distributed to agents by Workload Security. This increases network and disk space usage. However, because they are global, you do not need to spend time selecting them in each policy. Global rules are not part of the rulesets you can see in Workload Security. Global rules can only contain block rules, not allow rules.

  Global rules require an agent version 10.2 or later. Workload Security does not send the global rules to older agents. Global rules take precedence over all other Application Control rules and are enforced on all computers where Application Control is enabled. The rules in global rules are based on a file's MD5, SHA-1 or SHA-256 hash. Since a software file's hash is unique, you can block specific software everywhere, regardless of file path, policy, or computer group, and regardless of whether or not Application Control has detected the software before.

  In a multi-tenant deployment, each tenant has a separate global rules. To block software for all tenants, create the same global rules for each tenant.

  To create global rules, see Add global rules.

Create a shared ruleset

You can use the API to create shared allow or block rules and apply the ruleset to other computers. This can be useful if you have many identical computers (such as a load balanced web server farm). Shared rulesets should be applied only to computers with the exact same inventory.

1. Use the API to build a computer's shared allow and block rules. For more information, Create a Shared Ruleset. If you want to examine the shared ruleset before you deploy it, see View and change Application Control rulesets.
2. Go to Computer or Policy editor Application Control.

3. In the ruleset section, make sure Inherit settings is not selected, and then select Use a shared ruleset. Indicate which shared rules to use.

   These settings are hidden until you use the API to create at least one shared ruleset. If you have not created any shared rulesets, or if you have chosen to retain the default settings, each computer keeps its own allow and block rules locally. Changes to local rules do not affect other computers.

4. Click Save.

   The next time that the agent on the computer connects with Workload Security, the agent applies those rules.

   If you see an error saying that the ruleset upload was not successful, verify that network devices between the agent and Workload Security allow communications on the heartbeat port (see port numbers).

Change from shared to computer-specific allow and block rules

If the computer is currently using shared allow or block rules created via the API, you can change it to use local rules. Application Control scans the file system for all currently-installed software and creates an initial ruleset for it, similar to when you first enabled Application Control.

Before you start, verify that only good software is currently installed. Rebuilding the ruleset allows all currently installed software, even if it is insecure or malware. If you are not sure what is installed, the safest approach is to make a clean install, and then enable Application Control.

The following steps configure a computer's agent to use a local ruleset. If you want all computers to use local rules, edit the setting in the Policies tab instead.

1. Go to Computer editor > Application Control.
2. In the ruleset section, deselect Inherit settings (if necessary), and then select Use local ruleset initially based on installed software.
3. Click Save.

To verify the change, the next time the agent and Workload Security connect, look for event log messages about building the Application Control ruleset.