Phase-based implementation security guidance

docs/build-for-developers/security-for-devs.md

@@ -19,25 +19,17 @@ developers might make. Here are some of them and tips on how to avoid them:
 
 ### Hardcoding sensitive information
 
-- **Avoid Hardcoding Credentials:** Instead of hardcoding usernames, passwords,
-  or API keys directly into your scripts, use the `state` object to store and
-  retrieve sensitive information.
-
-```json
-// Store credentials in state.json
-{
-  "configuration": {
-    "username": "your_username",
-    "password": "your_password"
-  }
-}
-```
-
-```javascript
-// Retrieve credentials from state
-const username = state.configuration.username;
-const password = state.configuration.password;
-```
+Never write usernames, passwords, or API keys into job code. In OpenFn, attach a
+[credential](/manage-projects/manage-credentials.md) to the step instead. When
+the step runs, the credential's values are passed to the job as
+`state.configuration`, and the adaptor reads them from there, so your code
+rarely needs to touch them.
+
+When you run jobs locally with the CLI, keep credential values in a file outside
+your project's repository, or add the file to `.gitignore`, and pass it to the
+CLI as a credential map. See
+[Running workflows in projects](/build-for-developers/cli-sync.md#running-workflows-in-projects).
+The CLI does not add credential files to `.gitignore` for you.
 
 ### Checking sensitive data into GitHub
 
@@ -63,11 +55,6 @@ const password = state.configuration.password;
 
 ### Use of `console.log()`
 
-- **Mindful Logging Practices:** While `console.log()` is crucial during job
-  development, it's essential to be cautious about logging sensitive
-  information. Once jobs are built, administrators can disable the output of
-  console logs, but certain aspects of the sandbox may still be displayed.
-
 - **Avoid Logging Sensitive Data:** Be cautious when using `console.log(state)`
   or `console.log(state.configuration)`, especially if they contain sensitive
   information like usernames and passwords. In certain cases, this can lead to
@@ -86,10 +73,12 @@ console.log('Received sensitive data:', state.data);
   logging practices align with the client's requirements, and avoid exposing
   confidential information inadvertently.
 
-- **Administrator Control:** Understand that administrators can control the
-  visibility of console logs on an OpenFn project. However, it's crucial to
-  adopt logging practices that align with both development needs and client
-  security considerations.
+- **Turn Off Job Logs:** Once a workflow is built, anyone with the Editor role
+  or above can turn off its
+  [Allow console.log() usage](/build/workflows.md#log-outputs) setting. This
+  hides everything your job code logs. Messages from the adaptor and from OpenFn
+  itself, such as which step ran and how long it took, still appear in the run
+  logs.
 
 > These best practices around `console.log()` usage contribute to secure job
 > development on OpenFn, minimizing the risk of inadvertently exposing sensitive
@@ -146,18 +135,24 @@ least privilege. Specifically:
 
 ### Retaining your OpenFn project
 
-If you have strict data residency requirements, it’s possible to configure
-OpenFn as a “zero-retention” data pipeline to ensure compliance. This ensures
-that no data processed in OpenFn workflows (Inputs, Outputs) are retained, even
-on OpenFn’s cloud-hosted platform offering.
+If OpenFn must not keep the data your workflows process, set the project's data
+storage to **Never retain input/output data (zero-persistence)**. This works on
+the OpenFn Cloud too. OpenFn then deletes each run's Input as soon as the run
+starts, and doesn't store its Outputs. Run logs and details such as status and
+timestamps are still kept, so keep sensitive data out of your logs. With zero
+persistence on, you can't retry runs. Zero persistence controls what OpenFn
+stores, not where data is processed. If data must stay in a country or network,
+[deploy OpenFn there](/deploy/options.md).
 
 Many users find that temporarily retaining data in OpenFn can be helpful for
 troubleshooting. For example, if you have a 3-step workflow and the workflow
 fails at step 3, it might be helpful to retain the Input for this failed step so
 that you can inspect the data, quickly troubleshoot, and retry from that point
 of failure. To enable this more user-friendly troubleshooting experience, most
-users opt to leave temporary data retention on, and the retention period can be
-adjusted by the OpenFn super admin.
+users opt to leave temporary data retention on. Project owners and admins can
+change the [Data Storage](/manage-projects/io-data-storage.md) setting and the
+[History Retention](/manage-projects/retention-periods.md) period in the
+project's settings.
 
 ### Adaptors security practices
 

docs/build/workflows.md

@@ -187,8 +187,9 @@ canvas.
 ### Log Outputs
 
 For data security and compliance purposes, the log output of a workflow run can
-be configured to disable logging `console.log()` statements. This can be done
-via the workflow configuration modal by a project owner or administrator.
+be configured to disable logging `console.log()` statements. Anyone with the
+Editor role or above can change this in the workflow settings. Messages from the
+adaptor and from OpenFn itself still appear in the run logs.
 
 1. Click on the settings icon.
 2. In the modal, toggle the **Allow `console.log()` usage** switch to disable

docs/get-started/implementation-checklist.md

@@ -17,6 +17,9 @@ outlined provide a template workplan that can help any organization prepare for
 their upcoming implementation. **The implementation process is broken up into
 the seven phases summarized below. Check out the checklist for detailed steps.**
 
+For the security work at each phase, including the checks to pass before you
+move on, see [Implementation Security](/get-started/security.md).
+
 :::tip
 
 Check out a real-world example: see the UNICEF Cambodia repository for

docs/get-started/security-compliance.md

@@ -14,7 +14,7 @@ NGOs worldwide.
 
 ✓ Robust, configurable security settings to ensure compliance with your policies
 
-✓ Build “zero-persistence” data pipelines to fully control where data is stored
+✓ Build “zero-persistence” data pipelines that don't store the data they process
 
 ✓ Security implementation training & guidance for your project teams
 ([read more](/get-started/security.md))
@@ -49,10 +49,12 @@ more on project and
 [data storage settings](/manage-projects/io-data-storage.md).
 
 See the below diagram for an example architecture where even the OpenFn Cloud
-can be configured as a **“zero-persistence” data pipeline** to ensure compliance
-with data security and residency requirements. This enables partners to rapidly
-configure and pilot projects using the turnkey OpenFn cloud-hosted platform,
-before migrating to a local deployment when they’re ready to scale.
+can be configured as a **“zero-persistence” data pipeline**, so that the inputs
+and outputs of workflow runs are not stored. Data still passes through the
+OpenFn Cloud while it is processed, and run logs are kept. If data must not
+leave a country or network, [deploy OpenFn locally](/deploy/options.md). Many
+partners pilot a project on the OpenFn Cloud with zero persistence, then move to
+a local deployment when they're ready to scale.
 
 ![Sample Architecture](/img/zero-persistence.webp)
 
@@ -89,30 +91,32 @@ you are connecting. Technical documentation for individual adaptors can be found
 in the [Adaptor docs](/adaptors) or in their respective repositories on Github
 at [github.com/OpenFn/adaptors](https://github.com/OpenFn/adaptors).
 
-Credentials can only be viewed by you (the creator), and are loaded into your
-private runtime for job execution. You can delete these credentials at any time
-and they will be purged from the system.
-[See docs](/manage-users/user-credentials.md) for more on OpenFn credentials
-management and sharing.
+Each credential has one owner, who chooses which projects can use it. Only the
+owner can view or change its secret values in the app. Collaborators with the
+Editor role or above can attach a shared credential to a step, and the step's
+code receives the credential's values when it runs. Give Editor access only to
+people you would trust with those systems. See
+[User Credentials](/manage-users/user-credentials.md) for how to share,
+transfer, and delete credentials.
 
 ## User Access Management and RBAC
 
-OpenFn supports user access management through **role-based access control
-(RBAC)**, allowing admins to assign granular permissions at both the environment
-and project levels. Roles (e.g., Admin, Editor, Viewer) control who can view,
-edit, run, or manage workflows and credentials. Access can be restricted to
-specific projects or environment configurations, with support for audit logs and
-scoped API tokens to ensure security and compliance.
-
-When new users are invited to work on your Project as Collaborators, they are
-assigned a role that determines their permissions. See docs on
-[Collaboration](/manage-projects/collaboration.md) and
+OpenFn controls access to each project through **role-based access control
+(RBAC)**. Only the people added to a project as collaborators can open it, and
+each one has a role: Owner, Admin, Editor, or Viewer. The role decides who can
+view, edit, and run workflows, and who can manage the project's settings and
+collaborators. See [Collaboration](/manage-projects/collaboration.md) and
 [User Roles](/manage-projects/user-roles-permissions.md) for more information.
 
-When users register for the platform, they will be prompted to create a secure
-password. OpenFn super administrators can also enable
-[Multi-Factor Authentication](/manage-users/user-profile.md), password expiry,
-and stale account lockout.
+The instance administrator can view an audit trail of user actions across the
+instance. If you use the OpenFn Cloud, contact
+[support@openfn.org](mailto:support@openfn.org) to request audit information.
+
+When users register for the platform, they are prompted to create a secure
+password. Each user can turn on
+[Multi-Factor Authentication](/manage-users/user-profile.md#enable-multi-factor-authentication)
+(MFA) for their account. Project owners and admins can also require MFA for
+everyone who opens their project, depending on their plan.
 
 :::info More OpenFn Security Questions?