Control Utility¶
Control API specification
The Control API specification is currently proprietary. We plan to make it publicly available once it reaches a stable, production-ready state. As of this writing, the API specification is still evolving and is not yet considered stable for public release.
The control utility cgutils is a command-line tool that provides remote management capabilities for the ControlGuard Engine. These capabilities are exposed through a RESTful API accessible over HTTPS and it offers a flexible and modular interface for interacting with the engine.
Non-Interactive Commands¶
The cgutils utility provides a variety of commands that enable users to remotely retrieve information or perform actions on the ControlGuard engine.
The commands are organized in a hierarchical structure, closely resembling the naming conventions and operational style of CLI commands found on network equipment from vendors such as Cisco, Juniper Networks, and Fortinet. This design choice was made intentionally to ensure that network and system administrators feel immediately familiar and comfortable within the ControlGuard ecosystem.
To display a list of available commands, use the help command.
As shown above, a single command is available at the root level: controlguard. This is the primary command for all ControlGuard-related operations.
To display the list of available subcommands for controlguard operations, append the help subcommand as follows:
$ cgutils controlguard help
ControlGuard sub-commands:
show-status Display ControlGuard status
show-version Display ControlGuard version information
show-neighbor-summary Display neighbor(s) summary information
show-neighbor-detail Display neighbor(s) sessions details
show-database-status Display database connection status
request-neighbor-teardown Request neighbor(s) session(s) teardown
request-uriengine-restart Request restart of the URI engine
request-user-add Request addition of a new user
Commands Naming Convention
Commands that display information are typically prefixed with the show keyword, whereas commands that perform actions are usually prefixed with request.
Display ControlGuard Status¶
To retrieve the current status and version information of the ControlGuard services and its subsystems, use the show-status and show-version controlguard sub-commands, respectively:
$ cgutils controlguard show-status
ControlGuard Engine Status: UP
ControlGuard Database Status: UP
ControlGuard API Status: UP
$ cgutils controlguard show-version
ControlGuard Engine Version: 2025.2.20.1641 (EA)
Local Control API Version: 0.0.2.0
Remote Control API Version: 0.0.1.19
Display Neighbors Information¶
To display information about current neighbor sessions, use the show-neighbor-summary subcommand:
$ cgutils controlguard show-neighbor-summary
Types: C - Connector, CT - Connector over TLS, ? - Unknown
# T Neighbor ID State Address Connected since
83 C 127.0.0.1 UP/ACTIVE 127.0.0.1:36392 0d 9h 55m 20s
84 C 127.0.0.1 UP/ACTIVE 127.0.0.1:36394 0d 9h 55m 20s
The above output displays two connector sessions that are UP and in the ACTIVE state.
To display detailed information about neighbor sessions, use the show-neighbor-detail subcommand:
$ cgutils controlguard show-neighbor-detail
Neighbor 127.0.0.1, AS Number 64515
Type is Connector (Squid)
Using transport protocol tcp
with plaintext connnection
Session authentication method is SHA256
Connected from address 127.0.0.1 port tcp/36392
to address 127.0.0.1 port tcp/11224
Session state is UP/ACTIVE
Has sent defendr protocol messages:
Open 1 msg OpenConfirm 0 msg
Request 112 msg Acknowlegment 1 msg
Response 0 msg Keepalive 513 msg
Teardown 0 msg Notification 0 msg
Unknown 0 msg
Connected on Mon Dec 1 01:00:05.694 2025 CET
Last heared on Mon Dec 1 10:58:35.690 2025 CET
Current uptime is 0w 0d 9h 59m 23s
Registered with ID #83 (uuid:117d43c6-4b88-4423-8b9f-a8d4805a9507)
Advertised version: 2025.2.20.1641 (EA) (capflag:0x0)
Neighbor 127.0.0.1, AS Number 64515
Type is Connector (Squid)
Using transport protocol tcp
with plaintext connnection
Session authentication method is SHA256
Connected from address 127.0.0.1 port tcp/36394
to address 127.0.0.1 port tcp/11224
Session state is UP/ACTIVE
Has sent defendr protocol messages:
Open 1 msg OpenConfirm 0 msg
Request 120 msg Acknowlegment 1 msg
Response 0 msg Keepalive 513 msg
Teardown 0 msg Notification 0 msg
Unknown 0 msg
Connected on Mon Dec 1 01:00:05.694 2025 CET
Last heared on Mon Dec 1 10:58:35.689 2025 CET
Current uptime is 0w 0d 9h 59m 23s
Registered with ID #84 (uuid:0115ecb4-9430-4340-951e-e0e53677f5b9)
Advertised version: 2025.2.20.1641 (EA) (capflag:0x0)
The output above displays detailed verbose information for each neighbors session. It includes extensive technical details that are particularly valuable for debugging and troubleshooting purposes. This information encompasses:
- Connector Type
- Transport Protocol Information
- Authentication Methods and Algorithms
- Session and Finite State Machine (FSM) state
- Defendr Protocol Information
- Timestamps and Timers
- Software Details
Request Session Teardown¶
You can manually terminate one or more neighbor sessions using the request-neighbor-teardown subcommand:
$ cgutils controlguard request-neighbor-teardown
Neighbor session ID or identifier: 127.0.0.1
Requested neighbor session teardown: success
You will be prompted to enter a neighbor identifier. All sessions matching the provided identifier will be terminated by the engine.
Request URI Engine Restart¶
Sometimes, you may want to manually restart the URI scanning engine subsystem, use the following command: request-uriengine-restart:
Add a User¶
Password File
When a new user is added to the engine, the password file is automatically updated with a newly generated entry for that user.
User Naming Convention
The username must follow the below rules: - Usernames must begin with a lowercase letter (a–z). - Permitted characters: lowercase letters, digits (0–9), underscore (_), and hyphen (-). - Length: minimum 3 characters, maximum 128 characters.
To add a new user to the engine, use the request-user-add subcommand. This command will interactively prompt you for the required user details.
$ cgutils controlguard request-user-add
You are about to add a new user to ControlGuard. Enter '.' if you want to leave a field blank.
-----
Available User types: 1) Monitoring User, 2) Standard User, A) Administrator
User Types: 1
[i] Valid usernames must start with a lowercase character, can include special characters such as '_' or '-', and must be between 3 and 128 characters long.
Username: monitor
User Description: Dedicated Monitoring User
Password: **********
Repeat Password: **********
Configuration File¶
The default location for the control utility configuration file is /etc/controlguard/cgutils.conf.
[global]¶
The optional global section contains settings that apply globally to the cgutils program.
Authentication Directives
Authentication credentials may be stored within the configuration file, allowing the utility to persist them across subsequent invocations. However, we recommend prioritizing security by passing authentication credentials as command-line parameters instead.
Parameters:
| Name | Type | Description | Default | Required |
|---|---|---|---|---|
host |
string | Specifies the connector's destination hostname or IP address. | 127.0.0.1 |
Optional |
port |
integer | Defines the destination port for the API connection. | 11225 |
Optional |
cert |
string | The file path to the API root SSL/TLS certificate. | conf/ssl/cert.pem |
Optional |
username |
string | The username utilized for API authentication. | admin |
Optional |
password |
string | The password utilized for API authentication. | Optional |