RFC-65 App Audit Logs for Admins

General Request for Comments (RFC)
,
1

Disclaimer: This is a proposal and is subject to changes. Its purpose is to gather feedback.

RFCs are a way for Atlassian to share what we’re working on with our valued developer community.

It’s a document for building shared understanding of a topic. It expresses a technical solution, but can also communicate how it should be built or even document standards. The most important aspect of an RFC is that a written specification facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.

Please respect our community guidelines: keep it welcoming and safe by commenting on the idea not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!
*The scope of this RFC does not cover implementation details and these will be shared in future RFCs.

Summary

Integrate app activity logs into Atlassian audit logs within admin.atlassian.com to enhance monitoring and compliance for Jira and Confluence apps.

  • Publish: Sep 23, 2024
  • Discuss: Oct 04, 2024
  • Resolve: Oct 11, 2024

Problem

Current and prospective cloud customers - especially those in highly regulated industries such as government, finance, or healthcare - require visibility into their app activities to ensure data security and compliance. There are currently no solutions available to customers that would provide any insights into third-party app behaviour.

Providing transparency of app activity is considered a ‘must have’ for enterprise customers’ security teams and often a pre requisite for their cloud move. This is the outcome of a research exercise run with enterprise customers over the past months.

Solution

We propose to show app API calls for Connect, Forge and 3LO apps through the Atlassian audit logs in admin.atlassian.com which is accessible to cloud enterprise customers or Atlassian Guard Premium subscribers. Such integration will provide org admins with a new view to monitor Jira and Confluence app activities, enabling them to take necessary actions proactively if deemed appropriate.

Admins will be able to search and filter for the app API logs through the UI. To do so, they can use the ‘search’ bar or ‘activities’ filter. The result will show the API calls and related response codes.

Alternatively, admins can choose to register for a webhook to stream the API logs to their preferred destination for further analysis or integrate with a threat detection tool they may use. Finally, there is also the option to use the audit log API.

Adding app API calls to the audit log experience will build trust through improved security and compliance and allow for more apps to be part of a customer’s cloud move.

Benefits we aim to deliver:

  • Enhanced Security - proactive monitoring of app activities to identify and mitigate potential threats.
  • Compliance and Reporting - allowing for compliance reporting for regulated industries.
  • Operational Transparency - granular insights into third-party app API logs to help with troubleshooting and improving overall operational transparency

Below screenshot shows how app API calls would show in a first MVP phase

image
image1781×703 132 KB

Customer Quote

“a lot of customers will still want to integrate this into a SIEM of some point. So from an integration point of view it will be an easier thing to do if it’s all in a central place”

Ask

We would like to ask our partner community for feedback on the planned app audit log feature incl potential areas of concern.

1 Like
2

Hi Julia,

appreciate the RFC and a focus on security and transparency. That said, coming from a customer support perspective, I know there are always customers easily scared by an UI like this and my fear is we will need to do a lot of “damage” control in our support channels for customers who don’t understand why we need to access data - most often to prefill our UI in the Jira issue, e.g. with issue title, attachment names, etc.

E.g. when a single user interacts with our app in the Jira issue UI, we easily do 3-5 REST API calls, which will make this audit log blow up with entries for our app - not sure how helpful this is for customers without any context. Also, I’m not sure if this conveys that most of this data is only requested (at least for us) for in-transit purposes and not stored.

My concrete questions:

  • Can you allow Marketplace apps to somehow add a link to some kind of support page to give more context on why which call is being made
  • Can you introduce a REST API header “x-audit-log-description” to allow us to provide a reasoning / context for each call?
  • Do you differentiate calls by JWT app authentication (usually service calls, without user interaction) vs. impersonated calls (what we usually use, when working from the Jira UI)

Thanks!
Tobias

12 Likes
3

Hi Julia,
I think this transparency is a good idea.

For customers and us it would be important to distinguish between calls from our backend (i.e. our servers call into the Atlassian app), and calls from the frontend (e.g. in response to a button click by a user or viewing some data or similar).

5 Likes
4

I agree with the previous suggestions to:

  1. Separate front-end calls from back-end calls, at least assuming that front-end calls are even captured. (Are they?)
  2. Allow vendors to optionally provide a text rationale via HTTP header that will be stored with each request and displayed to the user.
  3. Vendors should be able to register at least one hyperlink that would be shown to the user for all API calls made by the app. This allows us to direct customers to a support page that might provide more context and explanations. (I do not think this necessarily needs to be a different link per API call, so a single page for an entire app would probably suffice.)

I have a few other suggestions/questions:

  1. It says the audit log will be accessible only to “cloud enterprise customers or Atlassian Guard Premium subscribers”, which effectively means that no Marketplace vendors will be able to test it. Can this audit feature be enabled on all Developer Canary instances? I suppose this could be done in a restricted fashion to avoid giving away the feature for free, such as by only showing audit data for locally-installed (non-Marketplace) versions of apps. Otherwise, we are all flying blind.
  2. Will query parameters be recorded in the audit logs? If so, all of them, or a subset? Some APIs would need to have query parameters logged to identify which space or project the API is accessing, and without this, the audit trail would be somewhat useless to admins.
  3. Will the audit service perform any sort of aggregation? Especially with the newer V.2 version of Confluence APIs, previously-simple requests can now turn into a hundred different API calls and I expect that logs will get flooded with requests. If you are performing aggregation, at what level?
10 Likes
5

Love this feature and love the x-audit-log-description idea. I’d happily add that header to our code.

1 Like
6

Interesting proposal. I second the suggestions to:

  • Differentiate front-end calls from back-end calls.
  • Let vendors provide a link leading to further explanations about those API calls.
    • For our app, we would explain the potential thousands of API-calls needed to sync external data into Jira issues.
    • Not sure if/how this link would be provided after the app is un-installed…
  • Alternatively/additionally, I can see the benefit in grouping related API-calls. Coming from our app, I can see a heading like XXX API calls for issues sync on 2024-09-24, and clicking that would expand all XXX API calls. A custom request-header could facilitate this.

Scott already asked about query parameters. What about further data, like response times?

Will there be storage limits? Globally, or per app? How many API calls will be stored, for how long?

7

Thanks a lot for the feedback! Trying to summarise what I am hearing:

  • You are suggesting to differentiate between FE and BE calls
    We currently don’t capture these but I can see how this could make a big difference for customers as well in case they are trying to investigating who has done what and why (app or user initiated)

  • Register to a support document that can be linked to an app in audit logs
    That’s an interesting idea and a couple of customers have told us they would like to see a link out to an API description to better understand what the API is doing. We were thinking to introduce ‘entity based logging’ at a later stage. So instead of an API call we could show something like ‘edited jira issue xxx’. Your comment seems to be more around explaining the API calls themselves (or the volume of the calls). Our entity based logging would not explain the ‘Why’ if that’s what you were after

  • You would like to test the feature
    The app logs are shown on Org level for Enterprise customers only. The Canary program is a premium and site level setup I believe. For those of you interested: you could create an Org in Prod and install Marketplace apps. If you share the OrgID with us we could stream app logs to the org for a period of time. Could that be of interest?

  • User impersonation
    Clearly a ‘must have’ for customers which we aim to deliver before we GA

  • Aggregating API calls
    We don’t have any plans to do this at this stage. I can see how the volume of API calls may look scary in a UI for some apps. Most Enterprise customers will run app log analysis outside the audit log UI, either through export or by using the audit log API. We wouldn’t therefore expect such aggregation to be required. However, as we are currently asking customers about their feedback on the logs we will see if this an ask on their end as well

  • Query Parameters
    The app API log primary use case is security. Therefore we currently focus our MVP on the API response code as this was identified as a key indicator for possibly suspicious behaviour.

1 Like
8

Hi Julia,

I want to thank you for opening this up to discussion from our community. It is, as usual, much appreciated.

I would like to agree with my predecessor’s comments (especially about user impersonation and explanations) and add one more point to consider:

Could you let our apps add their own events to the audit log?

API calls from our apps to Atlassian only tell half the story. A lot of apps have to store data outside of Jira issues in their own storage such as a database for Connect apps or Forge storage for Forge apps to protect the confidentiality and integrity of this data.

Modifications to such data, for example app settings that influence the way the app operates, could be relevant information to have in case of a scenario when Audit Logs have to be consulted. Of course we as app vendors store logs anyway, but I could see benefits in this data being integrated with Atlassian’s data and platform with all of its compliance efforts.

I don’t know if this integration would also be API request-level or just more high-level events (“App settings changed …”); I could see value in both.

I realize this request is very likely out of scope for this version of this feature, but I wanted to bring it up again since it could help give our mutual customers a better picture of what is happening in their systems.

Edit: I just saw this API already exists in Confluence but not in Jira

Thanks again,
Tobi from resolution

4 Likes
9

Hi @tobitheo, whilst changes to app settings is as you suspected not part of this iteration it seems a logical extension to what we are proposing.
We already capture some user interactions with apps such as installation, uninstallation or updates of apps (for example, when an app’s permissions change and the admin consents to such update) and this be visible in the ‘in product manage apps’ experience (UPM). We are adding these logs to the admin.atlassian.com audit logs with the goal to have all app logs in one place. Next step is to validate how we can further improve these logs.

Note that the Confluence API you are referencing is part of the v1 APIs which are currently being deprecated.

10

Hi,

Happy to hear your considering including apps into the audit log! I can see a lot of value in this, and I think this transparency will increase customers’ trust.

The API calls that the app can make are important to surface, especially for the apps like ours, that require admin scope.

We’ve had a look at our logs to see how many requests we’re generating towards Atlassian. For one of our biggest customer, we generate have generated 1.2 million API requests to Atlassian in a day. Only 10k of these were as an app, all the rest is user impersonation.

Will 1.2 million daily entries in the audit log make any sense for the customer? I think it’s important to consider what is logged to ensure that the audit log doesn’t become too noisy. I’m concerned that important events may get lost in the noise.

Edited to include that the numbers are daily usage.

11

Hi Janette, that’s a very valid point and thanks for sharing these numbers!
The audit log platform team is actively looking at options to handle such use cases. This could look like: allowing admins to define and save audit log filters. Or introduce filter options that allow users to also exclude events from view