Audited Workbench Jobs

Workbench | Advanced

Overview

You can configure Posit Workbench to track auditing information alongside Workbench job output. This includes digital signatures, environment information, and user-defined ad hoc information. Audited Workbench jobs are available in the RStudio IDE.

You can enable audited Workbench jobs in the rserver.conf file:

audited-jobs=1

File storage

Workbench stores audited job details at audited-jobs-storage-path, which defaults to your server’s shared storage. The rstudio-server user is the only user that can modify this location, and is not accessible to end users.

Before enabling audited jobs and using them at scale, Posit recommends that you determine whether there is sufficient space in shared storage to support your usage. If not, then set the audited-jobs-storage-path to a better location.

Audited Workbench jobs provide two limits that prevent a single job from consuming too much storage:

  • The number of log lines captured for a particular audited Workbench job
  • The amount of user-defined data that can be supplied to audit details

Additionally, audited Workbench jobs eventually expire, as configured by audited-jobs-deletion-expiry. Shortly after the job becomes eligible for deletion, the job is deleted from the database, and its data is removed from disk.

Containerized environments

To enable Workbench to collect audited job information in a containerized environment, the job’s image must contain a binary titled pwb-supervisor located at /usr/lib/rstudio-server/bin/pwb-supervisor. The user running the job must be able to execute this binary.

Depending on your installation, Posit supports including this binary in your image via these methods:

Audited information

Digital signature

Audited Workbench jobs compute a digital signature of the job’s output. This digital signature verifies the integrity and authenticity of the data that runs in the Workbench job. It can also verify that the job output remained unchanged after execution.

In an audited Workbench job, the digital signature is computed as follows:

  • Workbench computes a sha256 digest for the job’s output after the job has finished running.
  • Then, it uses a private key located at audited-jobs-private-key-path, to encrypt the digest with the RSA and stores the result as part of the audit details.

By default, a private and public signing key is created in /etc/rstudio if one is not present.

Manual key management

Creating a private key

Workbench needs a private key located at audited-jobs-private-key-path to successfully compute a digital signature. To create a new private key, use openssl:

openssl genpkey -algorithm RSA -out /etc/rstudio/audited-jobs-private-key.pem

You must set permissions for the audited-jobs-private-key.pem file to be visible to rstudio-server. For example:

ubuntu@ip-172-98-2-32:~$ ls -la /etc/rstudio
total 116
drwxr-xr-x   4 root           root  4096 Mar 27 22:35 .
drwxr-xr-x 128 root           root 12288 Mar 27 22:35 ..
-rw-------   1 rstudio-server root  1874 Mar 27 22:33 audited-jobs-private-key.pem
-rw-r--r--   1 root           root   451 Mar 27 22:33 audited-jobs-public-key.pem
-rw-------   1 rstudio-server root  2792 Mar 27 17:39 database.configured
Verifying the digital signature

The following three components verify the digital signature:

  1. the public key,
  2. a job’s output, and
  3. the computed digital signature

To create the public key, run:

openssl rsa -pubout -in /etc/rstudio/audited-jobs-private-key.pem -out /etc/rstudio/audited-jobs-private-key.pem

Run the following command to verify the digital signature:

PUBLIC_KEY_PATH=/etc/rstudio/audited-jobs-public-key.pem
AUDITED_JOB_ID=<your audited job id here>
AUDITED_JOB_STORAGE_PATH=/var/lib/rstudio-server/shared-storage/audited-jobs
SIGNATURE_FULL_PATH=$AUDITED_JOB_STORAGE_PATH/$AUDITED_JOB_ID/audit_data/script_output/signature.bin 
JOB_OUTPUT_FULL_PATH=$AUDITED_JOB_STORAGE_PATH/$AUDITED_JOB_ID/audit_data/script_output/job.out

openssl dgst -sha256 -verify $PUBLIC_KEY_PATH -signature $SIGNATURE_FULL_PATH $JOB_OUTPUT_FULL_PATH```

If successful, the output reports Verified OK.

Key rotation

The private key can be safely replaced with a new signing key, which is used for future digital signatures. Previously created digital signatures require the old public key to verify the digital signature.

To add a new key, create a public and private key. Then, adjust the rserver.conf file to use the new keys, as well as the old public key. The old private key is safe to delete.

audited-jobs-private-key-path=audited-jobs-private-key-new.pem
audited-jobs-public-key-paths=audited-jobs-public-key-old.pem,audited-jobs-public-key-new.pem

Environment

Audited Workbench jobs can capture information about the environment used to run the job, including:

  • Operating systems information
  • R or Python versions, as well as installed packages
  • Select environment variables that typically impact R or Python execution:
    • R_HOME
    • R_SHARE_DIR
    • R_INCLUDE_DIR
    • R_DOC_DIR
    • LD_LIBRARY_PATH
    • PYTHONPATH
    • PYTHONHOME
Note

R and Python detection requires the audited job’s executable (exe) to be set to either R or Python. Use a relative path such as R or a full path such as /usr/lib/R.

User-defined information

The code running in an audited Workbench job can also write custom files to be included in the audit record, allowing users to customize auditing for their particular environment. During execution, a temporary directory is created for user-defined files. This directory is exposed to the script through the environment variable AUDIT_DETAILS_PATH. Files written to that directory are captured as part of the audit details of the job.

Here is an example script that captures a file called hello-world.txt:

path = Sys.getenv("AUDIT_DETAILS_PATH")
file_path = paste(path, "hello-world.txt", sep="/")
fileConn = file(file_path, "w")
writeLines(c("Hello World!"), fileConn)
close(fileConn)
Note

At most, 1MB of files can be included as user-defined data. If that limit is exceeded, the job logs display an error message, and the audit record is not include the files.

Configuring audited Workbench jobs

There are a number of rserver.conf options that influence audited Workbench job behavior, and they assume sensible values by default.

Config Option Description Default Value
audited-jobs Indicates whether or not to enable support for audited jobs. 0
audited-jobs-storage-path Specifies the path to the directory where audited job data is stored. /var/lib/rstudio-server/shared-storage/audited-jobs
audited-jobs-private-key-path Path to a private key used to generate digital signatures of a jobs output /etc/rstudio/audited-jobs-private-key.pem
audited-jobs-public-key-paths Paths to public keys used to generate digital signatures of a jobs output /etc/rstudio/audited-jobs-public-key.pem
audited-jobs-log-limit Specifies the maximum number of audit log entries to keep. 10000
audited-jobs-deletion-expiry The number of days before completed audited jobs are deleted. 90
audited-jobs-vanilla-required Whether –vanilla is required for audited jobs that run R. 1
audited-jobs-details-environment Captures environment information as part of the audited jobs details. 1
audited-jobs-details-user-defined Captures user-defined information as part of the audited jobs details. 1
Back to top