Audited Workbench Jobs
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:
- Containerized sessions: Session images used to launch jobs do not need further configuration. Refer to the Job Launcher Configuration - Containerized Sessions section of this guide for more information.
- Session init container: The session init container adds the binary to your custom image at load time. Refer to the Job Launcher Configuraiton - Session Init Container section of this guide for more information.
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:
- the public key,
- a job’s output, and
- 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
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
:
= Sys.getenv("AUDIT_DETAILS_PATH")
path = paste(path, "hello-world.txt", sep="/")
file_path = file(file_path, "w")
fileConn writeLines(c("Hello World!"), fileConn)
close(fileConn)
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 |