Home > Articles > Security > Network Security

systrace in OpenBSD

systrace is an OpenBSD tool that allows administrators to monitor, intercept, and restrict system calls. Find out how to get started using systrace in this chapter from Secure Architectures with OpenBSD.
This chapter is from the book

This chapter is from the book

29.1 Introduction

The OpenBSD default system comes with a policy enforcement tool named systrace, which provides a way to monitor, intercept, and restrict system calls. The systrace facility acts as a wrapper to the executables, shepherding their traversal of the system call table. The systrace facility then intercepts the system calls and, using the systrace device, processes them through the kernel and handles the system calls.

Getting started with systrace is quite easy. You can run your programs under systrace, generate policies based on the observed behavior, and then enforce this policy on the program in subsequent runs. There are, however, two problems with this approach:

  • This approach assumes that the executable behaves entirely correctly and within the expected bounds. Violations of this assumption can include the use of a modified executable that has been reconfigured by an attacker. Subsequent uses of systrace will allow the malicious behavior to continue. To remedy this problem, policies should be reviewed after their generation to ensure that the anticipated behavior is observed, and trusted executables should be used in policy generation. Generally, automated policy generation should be undertaken only with trusted applications. Unknown applications can be used with interactive policy generation, so that decisions can be made before any damage is done by a rogue application.

  • This approach assumes that the initial runs of the systrace policy generator fully exercise the range of actions for which the policy is intended. In reality, the ls executable, for example, may not know that it is allowed to list the files in a publicly allowed directory that was skipped in the original run.

To remedy this situation, it is possible to bootstrap the policy that systrace knows about by using arbitrary external policies and the -f flag. In this scenario, a base policy can be built and extended. Furthermore, one can generatefilters that use wildcards, which eliminate the need for fully itemized lists:

native-open: filename match "$HOME/*" and oflags sub "ro" then permit 

In this example, one can read (but not write to) any files and directories under the current user’s home directory. This filter is forward adaptable and condensed.

Executables run under the systrace facility can pass policies on to their children and inherit policies from their parents. This is useful for login shells, for example, where you may wish to restrict a user’s behavior using systrace. Any children from this shell will have a policy that has been inherited from their parent. A simple systrace login shell would look like the following:1


main(int argc, char *argv)
       char            *args[4];

       args[0] = "-Ua";          /* system policies, auto enforce */
       args[1] = "/bin/ksh";     /* run ksh */
       args[2] = "-l";           /* login shell */
       args[3] = NULL;
       if (execv("/bin/systrace", args) <0) {
               fprintf(stderr, "loging in failed.");
       /* NOTREACHED */
       return (0);

The series of steps to enable this system for users would look like the following:

$ mkdir -p /usr/local/src/bin/stsh/ 
$ vi /usr/local/src/bin/stsh/stsh.c 
  enter above code
$ gcc -o /usr/local/src/bin/stsh/stsh /usr/local/src/bin/stsh/stsh.c 
$ sudo cp /usr/local/src/bin/stsh/stsh /bin/stsh 
$ sudo vi /etc/login.conf 
  edit the variable ‘‘shells’’ to be /bin/stsh 

This can be applied in the default class for all users or just to users in a particular login class.

Before you begin, make sure you have a policy for /bin/sh in the directory /etc/systrace (saved as bin sh). Now test this setup (leaving at least one user with a normal shell for login purposes). Also, this method disables the utility chsh, which users can use to change their shells. They cannot disable their use of stsh and use a non–systrace-wrapped /bin/ksh, for example. Instead, their parent shell will always be a systrace-wrapped /bin/ksh. Newer versions of stsh can spawn any shell the user chooses, wrapped in systrace.

The target uses of systrace are threefold. First, it is designed for untrusted data paths, such as executables from potentially untrusted sources or applications that handle untrustworthy data. These can include daemon processes, for example, which are open to the world. By using systrace, an administrator can restrict the arbitrary execution of commands. Second, this program is very useful for machines with untrusted users operating in their shells. By spawning the login shell under the control of systrace and then forcing children to inherit this policy, transparent sandboxing of the system can occur. Third, systrace can protect users from their own processes. Some applications are untrusted or otherwise potentially damaging to the system or accept untrusted data from the network. Cradeling their execution by using systrace can help mitigate any damage they may cause.

Global system policies live in the system directory /etc/systrace. Examples policies exist for two daemons, lpd and named, which provide robust sandboxing for the executables. These examples show what can be done to secure a system using systrace.

User-specific policies are found in /home/username/.systrace. If a user modifies a global policy, the modified version is saved in his or her home directory. This prevents one user from modifying the execution environment of other users’ applications.

Note that systrace does require a modest level of understanding regarding system calls and their consequences. It is easy to write a policy that is impossible to use by ignoring fundamental actions, which is why it is advisable to start with automatically generated policies. Also, some large, complex applications may be difficult to run under systrace due to the large number of system calls they make. In these situations, it may be wise to attempt to allow nearly everything except a subset of commands. For example, your Web browser may be allowed to open arbitrary sockets above 1024 but not allowed to spawn a child shell.

29.1.1 Example Use

As described previously, it is possible to use systrace to automatically generate a policy for an executable. With the -A flag set, systrace will accept all actions as permitted and use them to build a policy. The following example shows the geneation of a simple policy allowing /bin/ ls to read the user’s home directory:

$ cd

$ systrace -A ls 

By default, systrace will store the generated policies in the directory /home/username/ .systrace. For our example run of ls, a policy named bin ls will appear with the contents of the policy for that executable:

Policy: /bin/ls, Emulation: native 
    native-_sysctl: permit
    native-mmap: permit
    native-mprotect: permit 
    native-ioctl: permit 
    native-getuid: permit 
    native-fsread: filename eq "/etc/malloc.conf" then permit
    native-issetugid: permit 
    native-break: permit 
    native-fsread: filename eq "/home/jose" then permit 
    native-fchdir: permit 
    native-fstat: permit 
    native-fcntl: permit 
    native-fstatfs: permit 
    native-getdirentries: permit 
    native-lseek: permit 
    native-close: permit 
    native-write: permit 
    native-munmap: permit 
    native-exit: permit 

This simple, minimalistic policy is nevertheless very restrictive. When we try to use this policy to enforce actions, we can see the effect. Using the command systrace -a,we can automatically enforce the policy we have installed:

$ systrace -a ls /etc/ 
ls: /etc/: Operation not permitted 

Additionally, a message is logged to the central system logs via the syslog mechanism. By default, these messages will appear in the file /var/ log/messages. Reading these messages can be useful for security monitoring or policy review and adjustment purposes:

May 30 07:12:11 superfly systrace: deny user: jose, prog:
/bin/ls, pid: 1664(0)[17057], policy: /bin/ls, filters: 129, syscall:
native-dup2(90), args: 8 

The denial of system calls can be controlled by using the specific signal sent to the executable making the request. For example, it may be advisable to send ls a “permission denied” signal when it attempts to show the files in the /etc directory. The ls command gracefully reports the error to the user and exits.

More complicated policies can be generated interactively. When the X11 environment is available, the application xsystrace is used to provide responses to policy queries. In a text-only environment, the responses are handled on the command line. Responses are “permit” and “deny” with options that match those found in the policy file. For example, generating a policy for tcpdump would look like the following:

# systrace tcpdump 
/usr/sbin/tcpdump, pid: 8159(0)[0], policy: /usr/sbin/tcpdump,
filters: 0, syscall: native-issetugid(253), args: 0 
Answer: permit

Note that systrace uses the shell from which it was started to make these policy queries. If the shell has been closed, the application will hang while waiting for a policy decision.

The systrace system understands the following environmental variables and expands them as macros: These variables can be substituted in the systrace policy and allowed to expand. An example setup using such macros would appear as follows:

  • HOME    The user’s home directory (e.g., /home/jose).
  • USER      The user’s name (e.g., jose).
  • CWD       The current working directory (also known as .).

These variables can be substituted in the systrace policy and allowed to expand. An
example setup using such macros would appear as follows:

native-fsread: filename eq "$HOME/.gaim" then permit   
native-fswrite: filename eq "$HOME/.gaimrc" then permit 

These examples were taken from a policy for the IM chat client gaim, generated automatically by systrace -A, and then smoothed over by manual editing.

InformIT Promotional Mailings & Special Offers

I would like to receive exclusive offers and hear about products from InformIT and its family of brands. I can unsubscribe at any time.


Pearson Education, Inc., 221 River Street, Hoboken, New Jersey 07030, (Pearson) presents this site to provide information about products and services that can be purchased through this site.

This privacy notice provides an overview of our commitment to privacy and describes how we collect, protect, use and share personal information collected through this site. Please note that other Pearson websites and online products and services have their own separate privacy policies.

Collection and Use of Information

To conduct business and deliver products and services, Pearson collects and uses personal information in several ways in connection with this site, including:

Questions and Inquiries

For inquiries and questions, we collect the inquiry or question, together with name, contact details (email address, phone number and mailing address) and any other additional information voluntarily submitted to us through a Contact Us form or an email. We use this information to address the inquiry and respond to the question.

Online Store

For orders and purchases placed through our online store on this site, we collect order details, name, institution name and address (if applicable), email address, phone number, shipping and billing addresses, credit/debit card information, shipping options and any instructions. We use this information to complete transactions, fulfill orders, communicate with individuals placing orders or visiting the online store, and for related purposes.


Pearson may offer opportunities to provide feedback or participate in surveys, including surveys evaluating Pearson products, services or sites. Participation is voluntary. Pearson collects information requested in the survey questions and uses the information to evaluate, support, maintain and improve products, services or sites, develop new products and services, conduct educational research and for other purposes specified in the survey.

Contests and Drawings

Occasionally, we may sponsor a contest or drawing. Participation is optional. Pearson collects name, contact information and other information specified on the entry form for the contest or drawing to conduct the contest or drawing. Pearson may collect additional personal information from the winners of a contest or drawing in order to award the prize and for tax reporting purposes, as required by law.


If you have elected to receive email newsletters or promotional mailings and special offers but want to unsubscribe, simply email information@informit.com.

Service Announcements

On rare occasions it is necessary to send out a strictly service related announcement. For instance, if our service is temporarily suspended for maintenance we might send users an email. Generally, users may not opt-out of these communications, though they can deactivate their account information. However, these communications are not promotional in nature.

Customer Service

We communicate with users on a regular basis to provide requested services and in regard to issues relating to their account we reply via email or phone in accordance with the users' wishes when a user submits their information through our Contact Us form.

Other Collection and Use of Information

Application and System Logs

Pearson automatically collects log data to help ensure the delivery, availability and security of this site. Log data may include technical information about how a user or visitor connected to this site, such as browser type, type of computer/device, operating system, internet service provider and IP address. We use this information for support purposes and to monitor the health of the site, identify problems, improve service, detect unauthorized access and fraudulent activity, prevent and respond to security incidents and appropriately scale computing resources.

Web Analytics

Pearson may use third party web trend analytical services, including Google Analytics, to collect visitor information, such as IP addresses, browser types, referring pages, pages visited and time spent on a particular site. While these analytical services collect and report information on an anonymous basis, they may use cookies to gather web trend information. The information gathered may enable Pearson (but not the third party web trend services) to link information with application and system log data. Pearson uses this information for system administration and to identify problems, improve service, detect unauthorized access and fraudulent activity, prevent and respond to security incidents, appropriately scale computing resources and otherwise support and deliver this site and its services.

Cookies and Related Technologies

This site uses cookies and similar technologies to personalize content, measure traffic patterns, control security, track use and access of information on this site, and provide interest-based messages and advertising. Users can manage and block the use of cookies through their browser. Disabling or blocking certain cookies may limit the functionality of this site.

Do Not Track

This site currently does not respond to Do Not Track signals.


Pearson uses appropriate physical, administrative and technical security measures to protect personal information from unauthorized access, use and disclosure.


This site is not directed to children under the age of 13.


Pearson may send or direct marketing communications to users, provided that

  • Pearson will not use personal information collected or processed as a K-12 school service provider for the purpose of directed or targeted advertising.
  • Such marketing is consistent with applicable law and Pearson's legal obligations.
  • Pearson will not knowingly direct or send marketing communications to an individual who has expressed a preference not to receive marketing.
  • Where required by applicable law, express or implied consent to marketing exists and has not been withdrawn.

Pearson may provide personal information to a third party service provider on a restricted basis to provide marketing solely on behalf of Pearson or an affiliate or customer for whom Pearson is a service provider. Marketing preferences may be changed at any time.

Correcting/Updating Personal Information

If a user's personally identifiable information changes (such as your postal address or email address), we provide a way to correct or update that user's personal data provided to us. This can be done on the Account page. If a user no longer desires our service and desires to delete his or her account, please contact us at customer-service@informit.com and we will process the deletion of a user's account.


Users can always make an informed choice as to whether they should proceed with certain services offered by InformIT. If you choose to remove yourself from our mailing list(s) simply visit the following page and uncheck any communication you no longer want to receive: www.informit.com/u.aspx.

Sale of Personal Information

Pearson does not rent or sell personal information in exchange for any payment of money.

While Pearson does not sell personal information, as defined in Nevada law, Nevada residents may email a request for no sale of their personal information to NevadaDesignatedRequest@pearson.com.

Supplemental Privacy Statement for California Residents

California residents should read our Supplemental privacy statement for California residents in conjunction with this Privacy Notice. The Supplemental privacy statement for California residents explains Pearson's commitment to comply with California law and applies to personal information of California residents collected in connection with this site and the Services.

Sharing and Disclosure

Pearson may disclose personal information, as follows:

  • As required by law.
  • With the consent of the individual (or their parent, if the individual is a minor)
  • In response to a subpoena, court order or legal process, to the extent permitted or required by law
  • To protect the security and safety of individuals, data, assets and systems, consistent with applicable law
  • In connection the sale, joint venture or other transfer of some or all of its company or assets, subject to the provisions of this Privacy Notice
  • To investigate or address actual or suspected fraud or other illegal activities
  • To exercise its legal rights, including enforcement of the Terms of Use for this site or another contract
  • To affiliated Pearson companies and other companies and organizations who perform work for Pearson and are obligated to protect the privacy of personal information consistent with this Privacy Notice
  • To a school, organization, company or government agency, where Pearson collects or processes the personal information in a school setting or on behalf of such organization, company or government agency.


This web site contains links to other sites. Please be aware that we are not responsible for the privacy practices of such other sites. We encourage our users to be aware when they leave our site and to read the privacy statements of each and every web site that collects Personal Information. This privacy statement applies solely to information collected by this web site.

Requests and Contact

Please contact us about this Privacy Notice or if you have any requests or questions relating to the privacy of your personal information.

Changes to this Privacy Notice

We may revise this Privacy Notice through an updated posting. We will identify the effective date of the revision in the posting. Often, updates are made to provide greater clarity or to comply with changes in regulatory requirements. If the updates involve material changes to the collection, protection, use or disclosure of Personal Information, Pearson will provide notice of the change through a conspicuous notice on this site or other appropriate way. Continued use of the site after the effective date of a posted revision evidences acceptance. Please contact us if you have questions or concerns about the Privacy Notice or any objection to any revisions.

Last Update: November 17, 2020