Skip to main content

Confluence

Bring the policies and procedures you keep in Confluence Cloud into the JupiterOne graph as evidence for GRC and continuous controls monitoring — spaces, the pages in them with their status, version number and last-updated date, the labels that classify them, and the users who created and last updated each page. Scope ingestion to your policy spaces and policy labels, then query for policies that have not been updated in the last year, see who last changed each one, and alert on policies last edited by an account that is no longer active. The integration reads page metadata only: page bodies, comments, attachments and content property values are never retrieved.

Installation​

This integration connects to Confluence Cloud using the Confluence Cloud REST API v2 (https://<your-site>.atlassian.net/wiki/api/v2/...) and ingests spaces, pages, page labels, and the users who authored them. It is built for GRC and continuous controls monitoring use cases where your policies and procedures live in Confluence. The integration is managed by JupiterOne and runs in the JupiterOne cloud, so no collector is needed. Confluence Data Center and Server are not supported.

Prerequisites​

  • A Confluence Cloud site, for example your-company.atlassian.net.
  • An Atlassian account that can read the spaces and pages you want to ingest, and an API token for that account.
  • Access to JupiterOne with permission to configure integrations.

Configuration in Confluence​

The integration authenticates with Basic authentication: the Atlassian account email and an API token, sent as Authorization: Basic <base64(email:api_token)>. Every request is read-only.

Choose the account​

The API token can see exactly what its Atlassian account can see. Pages and spaces the account cannot view are not returned by the API and are not ingested. We recommend a dedicated account that has:

  • Access to the Confluence site (the Can use global permission).
  • View permission on every space you want to ingest.
  • Permission to view user profiles, which the Confluence Users data source needs.

The integration never writes to Confluence, so the account does not need edit or admin permissions.

Create the API token​

  1. Sign in to id.atlassian.com/manage-profile/security/api-tokens as the account above.
  2. Select Create API token, give it a name, and choose an expiration date.
  3. Select Create, then copy the token. Store it somewhere safe; you will paste it into JupiterOne.

Create a regular API token, not an API token with scopes. Atlassian requires scoped tokens to call the API through api.atlassian.com, while this integration calls your site host directly.

Atlassian API tokens expire. New tokens default to one year, and one year is the longest you can choose. Note the expiration date: when the token expires, the integration stops ingesting until you add a new token to the instance.

Configuration in JupiterOne​

To install the Confluence integration in JupiterOne, navigate to the Integrations tab in JupiterOne and select Confluence. Click New Instance to begin configuring your integration.

Creating an instance requires the following:

  • The Account Name used to identify the Confluence account in JupiterOne. Ingested entities will have this value stored in tag.AccountName when the AccountName toggle is enabled.

  • Description to assist in identifying the integration instance, if desired.

  • Polling Interval that you feel is sufficient for your monitoring needs. You may leave this as DISABLED and manually execute the integration.

  • The Authentication fields below.

Authentication fields​

FieldRequiredDescription
Site HostYesYour Confluence Cloud site host, for example your-company.atlassian.net. A full URL such as https://your-company.atlassian.net/wiki is also accepted and is reduced to the host.
Account EmailYesThe email address of the Atlassian account that owns the API token.
API TokenYesThe API token created above.

When you save the instance, JupiterOne checks the credentials by requesting one space from the site.

Filters​

All filters are optional. Leave them empty to ingest everything the account can read.

FieldDefaultDescription
Space KeysEmpty (all spaces the account can read)Ingest only these spaces, by space key. Applies to both spaces and pages. If none of the keys match a space, no pages are ingested.
Policy LabelsEmpty (all pages)Ingest only pages that carry at least one of these labels. Labels are matched case-insensitively.
Page StatusesCurrent and ArchivedWhich page statuses to ingest. Options are Current and Archived.
Fetch Content PropertiesOffAlso record the keys of each page's custom content properties in the page's contentProperties property.

Click Create once all values are provided to finalize the integration.

Narrowing ingestion to your policies​

A Confluence site usually holds much more than policies. Use Space Keys and Policy Labels together to ingest only your policy documents. For example, set Space Keys to the space where your policies live and Policy Labels to the label your team puts on approved policies, such as policy.

Each filter has a different cost:

  • Space Keys is applied by the Confluence API, so it costs no extra requests and reduces the number of pages read.
  • Policy Labels cannot be applied by the API. The integration lists every page in scope and makes one extra request per page to read its labels before deciding whether to keep it. Combine it with Space Keys on a large site so fewer pages have to be checked.

Policy Labels works on its own and does not need the Confluence Page Labels data source. That data source is what creates confluence_label entities in the graph.

caution

Narrowing a filter later removes pages from JupiterOne. Pages that no longer match Space Keys, Policy Labels or Page Statuses on the next run are deleted from the graph.

Page statuses and drafts​

By default the integration ingests current (published) and archived pages. Unpublished drafts cannot be ingested, because the Confluence pages API does not list them. A published page with unpublished edits is still ingested, with the status current.

Content properties​

Fetch Content Properties makes one extra request per ingested page. Only the property keys are stored. Property values can hold arbitrary data, so they are never ingested.

Data Sources​

Each data source can be enabled or disabled on its own. All data sources are disabled by default, so enable the ones you want to ingest. The confluence_account entity for the site is always created.

Data SourceDescriptionEntities Created
Confluence SpacesSpaces in the Confluence site, limited by Space Keys when set.confluence_space
Confluence PagesPages in the Confluence site, limited by the filters above, with their status, version number, version message, created and last-updated dates, and (optionally) the keys of their content properties.confluence_page
Confluence Page LabelsLabels on the ingested pages, used to tell policies from general wiki content. Makes one API request per ingested page. Requires Confluence Pages.confluence_label
Confluence UsersUsers referenced as creators, owners or last editors of the ingested pages, and creators of the ingested spaces. Requires Confluence Spaces and Confluence Pages.confluence_user

To ingest everything the integration supports, enable Confluence Spaces, Confluence Pages and Confluence Users, and add Confluence Page Labels if you want labels in the graph.

caution

Confluence Users must be enabled together with Confluence Spaces and Confluence Pages. Users are not read from a directory: they are looked up from the creator, owner and last-editor account IDs on the ingested pages and spaces. If either Confluence Spaces or Confluence Pages is disabled, the Confluence Users data source does not run at all and no users are ingested.

Relationships are built only when every data source they need is enabled:

RelationshipRequires
confluence_account HAS confluence_spaceConfluence Spaces
confluence_space HAS confluence_pageConfluence Spaces and Confluence Pages
confluence_page HAS confluence_page (parent page to child page)Confluence Pages
confluence_page HAS confluence_labelConfluence Pages and Confluence Page Labels
confluence_account HAS confluence_userConfluence Users (with Spaces and Pages)
confluence_user CREATED confluence_pageConfluence Users (with Spaces and Pages)
confluence_user UPDATED confluence_page (author of the current version)Confluence Users (with Spaces and Pages)

A parent-to-child page relationship is created only when the parent page was also ingested. With Policy Labels set, a policy whose parent page has no matching label has no parent relationship.

Each user is looked up in Confluence. The user's email is included only when the user's Atlassian profile privacy settings allow it.

Example queries​

Policy pages that have not been updated in the last 12 months. On an instance where Space Keys and Policy Labels already limit ingestion to your policies:

FIND confluence_page WITH status = 'current' AND updatedOn < date.now - 12 months

With the Confluence Page Labels data source enabled, the same check for pages labeled policy, with a link to each page:

FIND confluence_page AS p
  THAT HAS confluence_label AS l
  WHERE l.name = 'policy' AND p.updatedOn < date.now - 12 months
RETURN p.displayName, p.updatedOn, p.webLink

What the integration does not collect​

  • Page body content, comments, attachments, and content property values.
  • Unpublished drafts, blog posts, whiteboards, databases and folders. Only pages are ingested.
  • Page and space permissions or restrictions.
  • Policy acceptance or acknowledgment records. Confluence does not provide them, so evidence that employees have read and accepted a policy has to come from another system.

Rate limits​

Confluence Cloud enforces rate limits. The integration paces its own requests and, when Confluence answers with 429 Too Many Requests, waits for the time given in the Retry-After header before retrying. Policy Labels, Fetch Content Properties and the Confluence Page Labels data source each add one request per page, so on large sites they make each run take longer.

Next steps​

Now that your integration instance has been configured, it will begin running on the polling interval you provided, populating data within JupiterOne. Continue on to our Instance management guide to learn more about working with and editing integration instances.

Additional resources​