diff --git a/docs/build-for-developers/security-for-devs.md b/docs/build-for-developers/security-for-devs.md index 82ba4f8c0b4..720e89fc1dc 100644 --- a/docs/build-for-developers/security-for-devs.md +++ b/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 diff --git a/docs/build/workflows.md b/docs/build/workflows.md index 13857c3ec6b..8f9fdc3250b 100644 --- a/docs/build/workflows.md +++ b/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 diff --git a/docs/get-started/implementation-checklist.md b/docs/get-started/implementation-checklist.md index 2776efe8363..d489db340ae 100644 --- a/docs/get-started/implementation-checklist.md +++ b/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 diff --git a/docs/get-started/security-compliance.md b/docs/get-started/security-compliance.md index 31b0de94f8f..bb5f184f2c1 100644 --- a/docs/get-started/security-compliance.md +++ b/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.  @@ -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? diff --git a/docs/get-started/security.md b/docs/get-started/security.md index 640b8520b5c..40fc8b44358 100644 --- a/docs/get-started/security.md +++ b/docs/get-started/security.md @@ -3,115 +3,246 @@ sidebar_label: Implementation Security title: Security Considerations for Data Integration Projects --- -# Security Guidelines for Data Integration Implementations - -Even if the technologies leveraged in your integration solution can be -considered secure, there are still many security risks in data integration, -especially during implementation. With support from Digital Square, we have -therefore developed a **Security Guidebook for Data Integration -Implementations**. - -Since 2014, we at Open Function Group (the primary custodians of OpenFn) have -helped implement nearly 100 data integration solutions for over 45 NGO and -government partners around the world. Through our engagements with security -teams at different partners, our own research and development, consultations -with security experts internal and external, and partnerships with other -communities of practice, we have developed a strong understanding of security -best practices and considerations for data integration projects that we would -like to share with the wider digital development community. - -**This Guidebook aims to help digital implementers in the Digital Public Good -and Global Goods communities better understand security risks and presents 23 -best practices for the various implementation phases of data integration -projects.** It also links to some open-sourced OFG resources our team uses in -our own implementation process for OpenFn projects. - -You can find a complete list of the 23 best practices on this page below. - -**To access the Guidebook, check out the below slides or click the link to share -& download:** -[https://bit.ly/security_guidebook](https://bit.ly/security_guidebook) +Even when every system you connect is secure, an integration project can still +expose data: a password pasted into job code, a test run that sends messages to +real patients, or a former contractor who can still open the project. This page +sets out the security work for each phase of an OpenFn implementation: the main +risks, the practices and OpenFn settings that reduce them, and the checks to +pass before you move to the next phase. + +The guidance builds on the +[Security Guidebook for Data Integration Implementations](#the-security-guidebook), +which Open Function Group developed with support from Digital Square from its +work on nearly 100 integration projects with NGO and government partners. + +## Discovery + +The main risks at this stage are collecting more data than the workflow needs, +and learning late that a policy or data sharing agreement rules out the design. + +- Identify access requirements: who will build, run, and monitor the workflows, + and which system accounts OpenFn will use to connect to each system. +- Classify the data each workflow touches. Mark the fields that are personally + identifiable information (PII) or health data in your + [mapping specification](/design/mapping-specs.md). +- Move only the data points the workflow needs. +- Find the policies that apply to sharing, storing, and protecting the data, + such as national data protection law, GDPR, or a data sharing agreement. +- Model threats early. For each system and data flow, ask what could go wrong + (e.g., a leaked credential, a compromised source system, or data sent to the + wrong place) and how you would notice. +- Don't take API security for granted. Check how each system authenticates API + users, and whether it supports dedicated accounts with limited permissions. +- Budget time for security testing in the project plan. + +See [Discovery & Scoping](/design/discovery.md) for the rest of the discovery +process. + +### Phase-gate check: discovery + +Before you set up the project, you can answer these questions: + +- What data does each workflow move, and which fields are sensitive? +- Which policies and agreements apply, and who signs off on compliance? +- Who needs access to the OpenFn project, and with which role? +- What are the main threats, and how does the design reduce them? + +## Project setup + +The main risks are giving too many people too much access, and credentials with +no clear owner. + +- Add only the people who need access, and give each one the lowest role that + lets them do their work. See + [Collaboration](/manage-projects/collaboration.md) and + [User Roles](/manage-projects/user-roles-permissions.md). +- Require multi-factor authentication (MFA). Project owners and admins can turn + on **Require MFA?** in the project's `Settings > Security` tab, so that + collaborators must + [turn on MFA for their account](/manage-users/user-profile.md#enable-multi-factor-authentication) + before they can open the project. This option depends on your plan. +- Store every secret as an OpenFn + [credential](/manage-projects/manage-credentials.md), never in job code, + workflow files, or shared documents. Credentials are encrypted at rest. +- Give each credential a clear owner. Only the owner can view or edit its secret + values, but anyone with the Editor role or above can attach it to a step, and + that step's code can read the values when it runs. Base each credential on a + dedicated integration account in the connected system, with only the + permissions the workflow needs. +- Choose a data storage policy. If OpenFn should not keep the inputs and outputs + of your runs, choose zero persistence in + [Data Storage](/manage-projects/io-data-storage.md). Otherwise, set a + [history retention period](/manage-projects/retention-periods.md) that matches + your data policy. +- If a workflow starts from a webhook, add + [webhook authentication](/manage-projects/webhook-auth.md) so that only known + systems can trigger it. + +### Phase-gate check: project setup + +- Each collaborator has the lowest role that fits their work. +- Every credential has a named owner and uses a dedicated integration account + with limited permissions. +- You have decided whether to require MFA. +- The data storage policy and retention period are set, and the data owner has + agreed to them. + +## Build + +The main risks are secrets in code or repositories, real data in development, +and sensitive data in logs. + +- Attach credentials to steps instead of writing secrets into job code. When you + build with the CLI, follow + [Security considerations for OpenFn development](/build-for-developers/security-for-devs.md). +- Build in a [sandbox](/build/sandboxes.md). Sandboxes share the parent + project's credentials, so give each credential a value for the sandbox's + [environment](/build/sandboxes.md#environments) that points to a test system. + Otherwise, a sandbox run connects to the same systems as production. +- Use sanitized or made-up test data in every build environment. Don't copy + production payloads into a repository or a sample data file. +- Keep sensitive data out of logs. Log what a job did, such as the number of + records it fetched, not the records themselves. You can turn off + [console.log() output](/build/workflows.md#log-outputs) for a workflow. +- Keep a traceable history of changes with + [GitHub sync](/manage-projects/link-to-gh.md), and give repository access only + to active contributors. +- Design for failure and reprocessing. Use unique identifiers and upsert + operations so that a retried run doesn't create duplicate records, and + validate data before you send it. + +### Phase-gate check: build + +- There are no secrets in job code, repositories, or sample data. +- All test data is anonymized or made up. +- Logs show what each run did without showing personal data. +- Someone other than the author has reviewed the job code. + +## Integrated testing + +The main risks are test runs reaching real people or production systems, and +personal data left in run history. + +- Use only anonymized or made-up data in test datasets. +- Limit who can open test projects and sandboxes. A sandbox starts with the + parent project's collaborators, and you can then remove the ones who don't + need access. +- Guard notifications. If a workflow sends emails, SMS, or other messages, make + sure test runs send them only to test recipients, for example with a + credential environment that points to a test messaging account. +- Test the failure paths too: an expired credential, a system that is down, or a + record that fails validation. +- Before sign-off, check run history, logs, and outputs for any personal data + that should not be there. + +### Phase-gate check: integrated testing + +- Every test used non-production data. +- No test sent a message to a real person or wrote to a production system. +- A final review of logs and run history found no unexpected personal data. + +## Deployment + +The main risks are leftover access and credentials from build and testing, and +no way back if go-live goes wrong. + +- Lock down production access. Remove collaborators who only needed access + during build and testing. +- Rotate credentials at go-live. Replace any secret that was shared during build + or testing, for example by email or chat, with a new value that only the + credential owner knows. +- Review the security architecture and your security requirements again before + you let live traffic in: data flows, storage policy, webhook authentication, + and roles. +- Get rollback ready. Know how to + [disable a workflow](/build/workflows.md#enabling-or-disabling-a-workflow) and + how to restore its previous version from GitHub, and test both. +- Train users and system administrators on the security practices that apply to + them, and agree who to contact to report a security issue. + +The +[Project Security Configuration & Go-Live Checklist](https://docs.google.com/document/d/1CbQkN7SqNmXeqt3nMTYP4ioQlTuwF2LbDkkFqhp0zsU/edit?usp=sharing) +is a template for this review. + +### Phase-gate check: deployment + +- Only the people who run the live integration can open the production project. +- Every credential used in production has been rotated. +- You have tested disabling the workflow and restoring a previous version. +- Users know how to report a security issue, and to whom. + +## Operations + +The main risks build up over time: people who have left but still have access, +outdated adaptors, and data kept longer than it should be. + +- Review access regularly. Remove inactive collaborators and check that each + credential owner still works on the project. Every collaborator, including + Viewers, can + [export the project's history](/manage-projects/io-data-storage.md#export-history) + with its inputs and outputs. In the `Collaboration` tab, the **Grant support + access** setting lets the instance's support users open the project with + Editor permissions; turn it off when you don't need support. +- Keep adaptors up to date, and read the changelog before you upgrade a step to + a new version. +- Monitor your workflows. Turn on + [failure alerts and digests](/manage-projects/notifications.md), and look into + unusual failures such as repeated authentication errors. +- Enforce your retention and deletion policy. Check that the + [history retention period](/manage-projects/retention-periods.md) still + matches your data policy, and delete projects you no longer use. +- Agree how changes are requested, reviewed, and approved, and train partners on + that process. + +### Phase-gate check: operations + +Repeat these checks on a regular schedule, such as every quarter: + +- Every collaborator still needs access, with their current role. +- Every credential has a current owner and a recent rotation date. +- Adaptor versions are supported and up to date. +- Retention settings still match the data policy. + +## The Security Guidebook + +The practices above build on the 23 best practices in the Security Guidebook for +Data Integration Implementations. View the slides below, or share and download +them from [bit.ly/security_guidebook](https://bit.ly/security_guidebook).
-