Back to files

Program Guard

1 Description
Program Guard allows the user of a Linux workstation to specify which application programs that are allowed TCP/IP connections to the Internet (Internet addresses are defined as any IP address not in the range of 10.0.0.0/24 or 192.168.0.0/16). The application program names can be specified by listing them in a file (Static Mode) by querying the user (Query Mode). In Query Mode, when a program that is unknown to Program Guard attempts to access an Internet IP address, Program Guard displays the Program Guard Dialog Box. In addition to providing connection information, this dialog box gives the workstation user the option of allowing the program to access the Internet or to be blocked from accessing the Internet. This can be done either for the current instance of the program or for this and all future instances of the program (Make Persistent checkbox). This screenshot shows the Program Guard Dialog Box when Firefox is attempting an Internet access.

Currently, the program names that are allowed or denied Internet access apply to all users of the workstation rather than on a per user basis. For example, if Program Guard is running in Query Mode and user A invokes a program previously blocked from Internet access by user B, the program will be blocked from Internet access for User A as well.

Connections blocked by Program Guard are logged to the Program Guard log file pgrd.log. It is located in the /var/log/pgrd directory. If desired, Program Guard can be configured to log all Internet connection attempts rather than just those that have been blocked.

Program Guard has been tested with Fedora Core 1 and Fedora Core 3 on single processor 32 bit X86 Intel processors. It has not been tested on other distributions or on multi-processor machines. While it works on Fedora Core 1, it will not build on a standard Linux 2.4.x kernel due to task_struct definitions that were not made until Linux 2.6. If there is enough interest, a version that runs under a standard Linux 2.4 kernel may be made available.

To run in Query Mode, Gnome 2.x and Glade 2.x are required. There are no prerequisites for Static Mode.

2 Installation

Program Guard consists of three components: a kernel module; a daemon; and a Gnome GUI user interface component. All files needed to build the components are in the pgrd.tgz file.

An installation shell script install-pgrd is provided for Fedora distributions. It will build/install (or remove) the kernel module and daemon as well as configure them to be started automatically when the system is booted. To invoke it, type install-pgrd <install | remove>. This script may or may not be useable as is for other Linux distributions. If you modify the install script, please note that the module, daemon and various support files must be installed in the /opt/pgrd directory for Program Guard to work properly (this is already handled when using the install script as provided).

To run in Query Mode, each user must be configured by invoking the install-pgrd-user <username> script. And by going to the Preferences->More Preferences->Sessions selection in the Fedora Main Menu and adding pgrdgui to the Startup Programs tab.

Program Guard will be started the next time the machine is rebooted. If you do not wish to reboot, you may start Program Guard manually as described below in Manual Starting And Stopping. Note: If starting manually and using Query Mode, once the daemon and kernel module are started, make sure that you either manually start the GUI component or log out and log back in.

3 Operation
3.1 Configuration
Program Guard's operation is controlled by the values contained in its configuration file - /opt/pgrd/pgrd.conf. The following paragraphs describe the modes of operations and the configuration settings available in the pgrd.conf file.

In Static Mode, each application name that the user has specified in the pgrd.apps file will be blocked from connecting to the Internet; all others will be allowed. Each program name must be listed on a separate line in the file. Program Guard only reads this file at start-up, so changes to the pgrd.apps file will not take effect until it is restarted. To enable Static Mode, set the "QUERY_MODE" value in pgrd.conf to "NO".

If your workstation has a GUI interface, you may run Program Guard in Query Mode. To enable Query Mode, set the "QUERY_MODE" value in pgrd.conf to "YES". NOTE: Insure that the executable pgrdgui has been configured to start when a user logs on. If this is not done, no pop-up dialogs will be seen by the user.

Regardless of mode, the following options are controlled by the pgrd.conf file:

CHECK_ALL=YES NO
If NO, IP addresses in the range of 10.0.0.0/24 or 192.168.0.0/16) are not checked by Program Guard. If YES, all addresses are checked. NO is the default value

LOG_ALL=YES NO
If NO, only connections blocked by Program Guard are logged to the pgrd.log file. If YES, all connections are logged. NO is the default.

There are a number of pgrd.conf file options that are provided for debugging purposes and are not normally used. They are documented here for completeness.

BEADAEMON=YES NO
If YES, Program Guard is launched as a daemon. If NO, it is launched as a normal process. The default is YES

DEBUG_ON=YES NO
If set to YES, debugging messages are logged to Syslog. NO is the default.

LOG_STDOUT
If YES, messages that are normally sent to Syslog are sent to stdout instead. When this value is YES, BEADAEMON must be set to NO or an error will occur. NO is the default.

3.2 Manual Starting and Stopping
Program Guard daemon and kernel module may be manually started and stopped using the shell script pgrd. The syntax is pgrd <start | stop | restart>. You must have root privileges to perform these operations. Under Fedora you may also use chkconfig pgrd . If the daemon terminates with some error condition and you wish to restart Program Guard, it is important to issue a stop because this will stop both the daemon and the kernel module.

To Program Guard GUI component can be started manually by typing pgrd/pgrdgui in the user's home directory - after the daemon and kernal module have been started. It can only be manually stopped via the shell kill command.

3.3 Runtime Command Line Options
Once Program Guard is running, command line operations are available to provide status or to change the Internet access rights of a program. They are only valid in Query Mode and are:

Show Program Names
In Query Mode, lists the program name and Internet access right of each program for which Program Guard has been configured. Invoke by typing pgrdd -s

Modify Program Access Right
In Query Mode, toggles the allowed/blocked access right of a program. Invoke by typing pgrdd -m

Display Version Number
Displays the Program Guard version number. Invoke by typing pgrdd -v.

3.3 Error Conditions
Any error conditions encountered by Program Guard will be logged to syslog. If things are not working properly, that is the first place to look.

It is possible for either the daemon or the GUI component to terminate, if this occurs in Query Mode, Program Guard will be unable to prompt the user when a new application requests Internet access. In this case, any new applications will be blocked from accessing the Internet until the Program Guard is stopped and restarted.