secpolgenerate

Updated: April 19, 2023

Generate the security policy file

Syntax:

secpolgenerate -C clear used|errors
secpolgenerate -C load filename
secpolgenerate [-lNnuv] [-c config_file] [-f time] [-L max_logs] 
               [-r range_file][-S base_policy] [-s state_file] 
               [-T options ] [-t number_of_types]

Runs on:

QNX Neutrino

Options:

-C clear used|errors
Send a clear command to an existing secpolgenerate process. Specify either used or errors. Both options cause secpolgenerate to forget about events related to the use of abilities and path attachments. The difference is that used affects successful calls while errors affects unsuccessful calls.
-C load filename
Send a load command to an existing secpolgenerate process. Specify the name of a file that contains information about the abilities and path attachments to use as well as errors.
-c config_file
Read information from a configuration file. See Configuration file.
-f time
Improve logging by flushing the trace events every time seconds.
-L max_logs
The maximum number of error logs to include in /dev/secpolgenerate/errors. Default is 100.
-l
Log security check errors to a slog2 buffer.
-N
Create a security policy completely from scratch instead of basing it on an existing one.
-n
Use names instead of numbers in the state_file.
-r range_file
Get named range definitions from the specified file. See “Named range file” in the QNX Neutrino System Security Guide.
-S base_policy
Use the base_policy instead of /proc/boot/secpol.bin.
-s state_file
The secpolgenerate utility uses the state_file to save and restore the state. It does not have to be accessible when the utility starts.
-T options
In most cases, you test a service's behavior with respect to security policies by running it in a system that is using secpolgenerate using normal policy generation. However, if this type of system is not available, the following options may allow you to successfully run your service as a type in a system that mixes the features of a system that uses a security policy with features of one that doesn't:
  • all_connect — the type ID of any channel you attach to a path (using resmgr_attach()) is switched to 0. A type ID of 0 allows all processes to connect to a channel, irrespective of the process's abilities. This can prevent the system from failing because the channels of the process you're testing have non-zero type IDs.
  • zero_id — sets the policy ID of the policy that secpolgenerate provides at /proc/boot/secpol.bin to 0 instead of 1. Because a policy ID of 0 usually indicates no policy, specifying zero_id allows you to use secpolgenerate but other components behave as if it is not in use.

You can specify -T multiple times — once for each option you want to enable.

When you use these options, be aware that running a system that has features that use a policy as well as ones that ignore the policy can have unexpected results.

-t number_of_types
Allow this many more types in the new policy than currently exist in the base policy.
-u
Allow unrestricted behavior in the policy. For example, when you intend to use the policy in a development environment that is an insecure variant of another system.
-v
Write verbose output of errors to stderr.

Description:

The secpolgenerate utility is a tool for generating security policy rules by observing the system in action to determine the set of abilities each specific process needs. The rules it generates can either form a completely new security policy if one doesn't exist already, or they can indicate changes to the existing policy.

To allow changes from an existing policy in the generated policy, you must use either the –u or –t option.

However, if you choose to use the secpolgenerate utility on a secure system, you should not use either the –u or –t option.

This tool allows you to automate the process of developing a policy instead of creating one manually and reduces the amount of configuration required. Use it to identify updates that might be required to increase (or relax) security. Over time, information is generated and collected in the policy, unused and errors files in the /dev/secpolgenerate/ directory.

Note: Unless you are using secpolgenerate for monitoring only, you need to use libsecpol-gen.so.1 with the name libsecpol.so.1 instead of libsecpol.so.1 itself. You can rename libsecpol-gen.so.1 or use a process manager symlink. For example:
procmgr_symlink /proc/boot/libsecpol-gen.so.1 /proc/boot/libsecpol.so.1
See the Security Developers Guide for more information about:
  • how to design a security policy and automate its creation using secpolgenerate
  • the grammar that is used in the uncompiled, text version of the security policy file (generated or manual)
  • tutorials and information about booting the system for the first time
  • how to compile a security policy with the secpolcompile utility
  • best practices for security integration

Configuration file:

The secpolgenerate utility is designed to operate without any explicit configuration. However, using a configuration file provides a much more flexible and easy-to-use development environment and a way to handle some rare problems.

File location

On production systems, because secpolgenerate is either not running or running in a manner that cannot impact security, it makes no difference from a security point of view where its configuration file is located or what permissions it has.

For a development environment, however, the location of the configuration file has a significant impact on how easily you can implement changes to it as you work. For more information, see Developing systems with a security policy in the “Tutorial: Build a system that uses a security policy” chapter in the System Security Guide.

File contents

secpolgenerate reads the configuration file line by line. Each line contains an option class followed by its configuration. Empty lines or lines whose first non-space character is a pound sign (#) are ignored.

ability options

These options use the following format:

ability ability-name [option...]
Options Description
range Configures the ability to support sub-ranges. This option is primarily for dynamic abilities that are all assumed by default not to take sub-ranges. In principle, it can be applied to a small number of static abilities (such as prot_exec) that secpolgenerate treats as non-ranged but which do support ranges (although these ranges are considered to be of little use).
protect Prevents the ability from being dropped.

This option allows you to ensure that an ability that is given to the type because it is unrestricted is not accidentally dropped. Processes sometimes drop all abilities except for a set of them that they know they need. This behavior can cause failures when abilities are added and a process drops them, even though it requires them later.

However, you can't use this option to stop a process from dropping an ability that it explicitly drops because locking an ability that a process mentions in a procmgr_ability() call causes the call to fail.
type Indicates that the specified dynamic ability is subranged by type rather than numerically. This option causes secpolgenerate to create policy statements that use type names. Currently, secpolcompile does not support these kinds of ranges except for the two abilities that it knows can be subranged by type: settypeid and channel_connect.
type options

These options use the following format:

type type-name [option...]
Options Description
unrestricted Indicates that the type should be unrestricted even if secpolgenerate is running with types restricted to the existing policy. This option allows you to selectively relax the policy while the rest of the system runs as intended.
restricted Indicates the type should be restricted to rules in the existing policy even if secpolgenerate is run in an unrestricted manner.
deny:ability-spec[:user]... When a type is run in an unrestricted manner, denies all abilities in the comma-separated ability list either for just non-root or for both root and non-root. For example:
 type type1 deny:setuid,setgid:nonroot deny:fork
This entry denies the setuid and setgid abilities for non-root only and the fork ability for all user IDs.

When secpolgenerate generates a policy, it usually allows all abilities and monitors which ones are used. In some rare cases, allowing an ability can cause problems. For example, some versions of sshd try to verify that they are unable to revert to a user ID of 0 and exit if they can. This option allows you to deny sshd the setuid ability even when its behavior is otherwise unrestricted.

keep:ability-list When a type is run in an unrestricted manner, maintain any restrictions in the existing policy for the abilities specified in the comma-separated list. For example:
type type1 keep:setuid,setgid
Maintains the rules for the setuid and setgid abilities for type type1 regardless of whether the type is run in an restricted manner.
unlock:ability-list Preserve the default permissions for each ability in the comma-separated list of abilities and prevent them from being locked. This option has the same effect as when secpolgenerate detects that a process is attempting to configure an ability using procmgr_ability().

To detect an ability configuration, secpolgenerate requires that the process preload the library secpol-preload.so. In the rare case where this preloading cannot be done, this option can be used to achieve the same result. If the option is needed but not provided, the process will likely experience an error when it tries to configure its abilities.

no_procmgr_ability Configures secpolgenerate to ignore any calls that the specified process makes to procmgr_ability() and generate rules as if the call did not occur. Without this option, when a process calls procmgr_ability(), secpolgenerate leaves the abilities contained in the call with their default configuration to avoid problems such as causing the procmgr_ability() call to fail.

If you generate a policy with this option and run the system with it and without secpolgenerate, any call to procmgr_ability() typically fails. This causes no problems if the process ignores the error but could cause the system to fail otherwise.

global options

These options use the following format:

option option...
Options Description
restricted Configures secpolgenerate to restrict types to the rules contained in the policy by default. Individual types may be made unrestricted by specifying the type option with unrestricted. This option overrides the -u command line argument.
unrestricted Configures secpolgenerate to allow types unrestricted privileges by default. Individual types may be restricted to the existing policy by specifying the type option with restricted.

This option is almost equivalent to using the -u command line option. Unlike unrestricted, the -u or -t command line options enable secpolgenerate to override the policy in any way as well as making types unrestricted. For systems where the configuration file is on a writable file system, unrestricted provides an easy way to make changes to restrictions.