Access Control Lists¶

Access Control Lists or ACLs are list of policies that explicitly define which subnet, hosts, user-agent or other specific criterias are granted or denied access to web resources, mostly through the HTTP(S) protocol.

Access Control Lists (ACLs) are ordered sets of rules that explicitly determine which entities—such as subnets, individual hosts, user-agents, or other defined criteria—are permitted or denied access to web resources. These rules deliver precise, granular control over resource accessibility, thereby safeguarding endpoints and infrastructure assets against a wide range of threats, including command-and-control (C2) communications, malware downloads, data exfiltration, and other malicious activities.

The ACL configuration file employs a proprietary format that closely resembles JavaScript Object Notation (JSON) but is significantly more permissive and user-friendly. Unlike strict JSON, it supports inline and block comments, multi-line values and unquoted keys and string values.

Rules Files¶

Access Control List (ACL) policies are defined within rule files (with .acls file extension). A dedicated directory is used for this purpose, allowing rules to be distributed across multiple text files. The filename determines the loading and processing order of rules files which are processed in lexicographical order. This approach is intentionally modeled after the very popular udevd rules, which significantly simplifies policy management and administration.

Policies¶

A rule file consists of one or more policy blocks. Each policy block must contain at least a name and one match attribute/value.

The following example shows the contents of a rule file containing policies that allow specific package mirrors:

# Allow Package Mirrors

accept-ubuntu-initseven: {
    match-uri: https://mirror.init7.net/ubuntu/ #(1)!
    application: https
    action: permit
    description: Local Ubuntu Mirror
}

accept-mirror-switch: {
    match-uri-regex: ^(https?:\/\/)?.*mirror.switch.ch.* # (2)!
    application: https
    action: permit
    description: SWITCH mirror
}

1. Match all URIs that start with https://mirror.init7.net/ubuntu/.
2. Match all URIs that use either the HTTP or HTTPS scheme (or have no scheme specified, e.g., when only a hostname or SNI is present) and whose domain is mirror.switch.ch.

In the above example, two policies are defined, named accept-ubuntu-initseven and accept-mirror-switch respectively. Both policies apply to HTTPS traffic and match requests whose URI satisfies the specified criteria. The first policy employs the match-uri attribute, while the second policy uses regular expression matching using the match-uri-regex attribute, the latter is more versatile but also more complex.

As the name indicates, the action attribute or parameter defines the action to be taken when a match occurs. In both cases, the value permit allows the matching requests to proceed.

Management Utility¶

The Access Control Lists (ACLs) or rules must be imported into the database prior to being retrieved and compiled by the ControlGuard Engine into highly efficient in-memory structures optimized for both performance and memory utilization. This operation is performed using the rule management program, a lightweight, portable command-line tool provided for this purpose.

The Rule Management program reads the ACL policy files from the local filesystem, aggregates and orders the rules according to the defined precedence, and generates a consolidated running configuration. This running configuration is then imported into the database instance for use by the ControlGuard Engine.

For the policies to take effect, the rule management utility must be able to:

1. Read the ACL rules files from their designated directory.
2. Process and validate the policies. Any errors detected during this phase will be reported, and must be corrected before proceeding.
3. Establish a connection to the database instance (local or remote) and load the generated running configuration.
4. Contact the ControlGuard Engine’s client API to trigger a refresh, thereby applying the new rules.

The final step is optional and must be explicitly initiated by an administrator. This action instructs the ControlGuard Engine to re-initialize its internal data structures, thereby applying the new policies.

Committing Changes¶

To define or modify policies, edit the ACL rule files using a text editor of your choice (e.g., vi, vim, nano, or any other preferred editor).

Load rules into database¶

To import the rules or policies into the database, execute the following command:

cgacls policy-load

Carefully review any reported errors or warnings and address them as needed before proceeding again. Successful execution with no errors is required for the policies to be loaded successfully.

Trigger database refresh¶

For the current downloaded policies to take effect immediately, you must manually instruct the ControlGuard Engine to reload and reinitialize its scanning engine. This is accomplished by issuing th below command:

cgacls policy-reload

Upon successful communication with the Client API, the ControlGuard Engine will immediately process and apply the new rules and policies.

Configuration File¶

The cgacls utility reads its configuration from the file located at /etc/controlguard/conf/cgacls.conf by default.

[global]¶

The optional [global] section contains settings that apply globally to the cgacls program.

Parameters: