Policies¶

With the ControlGuard components now configured, you can proceed to define policies using Access Control Lists (ACLs).

Access Control Lists¶

An Access Control List or ACL is a collection of policies. Each policy consists of at least one match criteria and an associated action.

The match criteria determine the conditions that an incoming request must satisfy in order for the policy to apply. Once a matching policy is identified, the action specifies how the request should be handled (e.g., allow, deny, redirect, etc.).

Requests can be matched based on the Universal Resource Identifier (URI) using advanced regular expressions, a predefined list of domains, or a combination of both. For the purposes of this guide, we will demonstrate the use of both regular expression matching and domain lists. For detailed information about ACL configuration options, refer to the Access Control Lists (ACLs) section in the reference documentation.

Policy Examples¶

Example 1: Blocking URL Shortening Services¶

In this example, we will block access to known URL-shortening domains.

Create a new rules file named 90-denyurlshort.acls with your favorite editor such as vim:

vim /opt/controlguard/etc/rules.d/90-denyurlshort.acls

Add a policy block that defines how to deny requests matching a list of domains:

# deny url shortening domains
deny-urlshortening-domains: {
    match-domain-list: /usr/var/controlguard/lists/urlshorts.txt
    action: deny
    description: Access to URL shortening services is not permitted
}

Explanation¶

The above policy do the following:

• The policy is named deny-urlshortening-domains.
• The match-domain-list attribute references a text file containing one domain per line (the list of URL shorteners).
• When a request matches any domain in the list, the action: deny is triggered.
• The description field is displayed to users on the captive portal (if redirection is enabled).
• Lines beginning with # are comments and appear only in the configuration file for administrative purpose.

Example 2: Allowing Swiss Domains (.ch)¶

For this guide purpose, we now create a higher-precedence rules file to explicitly permit access to Swiss domains:

vi /opt/controlguard/etc/rules.d/10-allowswissdomains.acls

Add the following policy:

# Allow websites with .ch gtld
allow-swissdomains: {
    match-uri-regex: ^(https?:\/\/)?[^\/]+[.]ch
    action: permit
    description: swiss domain names ending with .ch
}

Explanation¶

• The file precedence 10- ensures this policy is evaluated before the previous 90- rules file.
• The regular expression matches any HTTP(S) URIs whose hostname or domain ends with .ch.
• Matching requests receive action: permit, allowing them to proceed without modification.

Resulting Behavior¶

With only these two policies configured:

• Requests to domains listed in urlshorts.txt are blocked; users are redirected to the captive portal with the message “Access to URL shortening services is not permitted”.
• Requests to any .ch domain are explicitly permitted (due to higher precedence).
• All other requests are blocked by default, because ControlGuard operates in a deny-all-unless-explicitly-allowed mode.

This default-deny posture can be modified by adjusting the engine’s global policy if a more permissive baseline is required.

Load policies¶

As a final step, you must load (or commit) the newly created rules files into the running configuration and persist them in the database.

To do so, use the Access Control List Management Utility:

cgacls policy-load

This command performs the following actions:

• Scans and processes all rules files in the /opt/controlguard/etc/rules.d/ directory according to their numeric precedence.
• Validates the syntax of each policy.
• Compiles the policies and write them in the local running configuration file.
• Load the running configuration file's policies into the database.
• Send a database reload API call to the engine.

Once executed successfully, the ControlGuard engine will immediately begin enforcing the updated policies. For additional options and details about the management utility, refer to the ACL Management Utility section in the reference documentation.