Security
This page explains how ERD Studio for Confluence (the "app") is built to keep your GitHub repositories and your Confluence site safe. The app is made by Liam Wynne, a sole trader in Australia (ABN 94 885 368 933). For what data the app reads and stores, see the privacy policy.
In short: the app runs entirely on Atlassian Forge. It reads GitHub through a GitHub App your organisation installs on the repositories it chooses, with read-only access. Each GitHub token is narrowed to one repository, lasts under an hour and never reaches the browser. Every backend function that reads repository data or changes settings checks the caller's permissions itself.
Architecture
- The app is an Atlassian Forge app. Its backend code runs on Atlassian's infrastructure, and its pages run in Forge's sandboxed Custom UI frames inside Confluence.
- We run no servers or databases of our own. Everything the app stores is in Forge storage for your site.
- The app is read-only. It never writes to GitHub, and it doesn't change Confluence content.
Access to GitHub
Access goes through the "ERD Studio for Confluence" GitHub App. A GitHub organisation owner installs it and picks which repositories it can see. Nobody shares a personal access token.
| GitHub App permission | Why |
|---|---|
| Contents: read | To read the diagram files in .erd-studio/ folders. |
| Metadata: read | To list repository and branch names in the macro settings. |
- Short-lived, narrow tokens. To read a diagram, the backend asks GitHub for an installation
token limited to that one repository and to
contents: read. Listing repositories uses a separate token limited tometadata: read, which can't read file contents. GitHub expires these tokens after one hour. - Encrypted storage. Tokens are cached in Forge's encrypted secret storage until shortly before they expire, then replaced. They're deleted when an admin disconnects or reconnects GitHub.
- Never in the browser. Tokens stay in the backend. Page viewers don't need a GitHub account and never see a token.
- Private key. The GitHub App's private key is stored as an encrypted Forge environment variable. It isn't in source control and never reaches the browser.
Connecting GitHub to your site
- Only Confluence site admins can connect or disconnect GitHub. The backend checks this on every admin request.
- The admin signs in to GitHub, and the app asks GitHub (
GET /user/installations) which installations that GitHub user can access. Only one of those can be linked. An installation ID sent from the browser is never trusted on its own, so one company can't connect another company's installation. - Once connected, diagrams can only come from repositories owned by the connected GitHub account, and only those the installation was granted.
Permission checks
Forge doesn't limit who can call an app's backend functions, so each function checks for itself instead of trusting which screen the request came from.
| Function | Checks |
|---|---|
| Showing a diagram on a page | Active licence. The repository, branch and file are read only from the macro settings saved in the page, which only page editors can change. Anything else the browser sends is ignored. |
| Previewing a diagram, and listing repositories, branches and files in the macro settings | Active licence, and the caller must be able to edit the page the macro is on. |
| Connecting, disconnecting and checking the GitHub connection | The caller must be a Confluence site admin. |
The macro settings panel can also ask which GitHub account the site is connected to. That returns only the account name and whether the site is licensed.
Handling repository content
Macro settings are written by page editors and repository files by anyone with push access, so the app treats both as untrusted.
- Only diagram files. A macro can only load a
.jsonfile inside a layer folder of an.erd-studio/folder (.erd-studio/<layer>/<domain>.json). Every other file it reads (layers.jsonandlogical-models/*.yml) is in that same folder. Repository, branch and path names are checked, and..is rejected. - Plain model names. Model names must be plain file names, so a domain file can't point the app at other files.
- Size limits. A domain can list at most 500 models, and each YAML file can expand to at most 50,000 nodes, which stops "billion laughs" alias attacks.
- Read-only rendering. Readers can move tables around in their browser, but nothing they do is saved or sent back.
Network access and Forge scopes
Forge only lets the app contact the addresses declared in its manifest:
| Address | Used for |
|---|---|
api.github.com | Backend: reading repository files and metadata, and checking installations |
github.com | Backend: completing the admin's GitHub sign-in |
avatars.githubusercontent.com | Browser: the connected GitHub account's avatar image on the admin page |
The app asks Atlassian for three scopes:
| Scope | Why |
|---|---|
storage:app | To store the GitHub connection, cached tokens and cached diagrams in Forge storage. |
read:confluence-user | To check whether the caller is a site admin. |
read:confluence-content.permission | To check whether the caller can edit the page the macro is on. |
The app can't read Confluence page content, attachments or comments.
Data retention and deletion
- Disconnect GitHub on the app's admin page to delete the stored installation link and every cached token.
- Uninstall the app from Confluence. Atlassian deletes the app's Forge storage for your site according to Forge's data retention rules.
- Uninstall the GitHub App from your GitHub organisation, or remove repositories from it. GitHub then refuses the app access to those repositories.
Logging
The app logs only unexpected errors, to Atlassian's Forge logs. An error message can include a repository or file name. We use these logs only to run and support the app, and we don't share them.
Reporting a vulnerability
If you think you've found a security issue, email digest@w2solutions.ai with "Security" in the subject. Include what you found and how to reproduce it.
- We'll acknowledge your report within 2 business days.
- Please don't disclose the issue publicly until we've released a fix.
- We don't run a bug bounty programme at the moment.
Incidents
If a security incident affects your data, we'll notify affected customers without undue delay, tell you what happened and what we're doing about it.
Changes
If we change how the app handles security, we'll update this page and the date at the top.