New auditing features coming to Server/Data Center - What you need to know

We’re excited to announce our plans to release a new and improved set of Jira, Confluence and Bitbucket auditing functionality to our Server and Data Center customers.

In this document we want to walk the vendor community through these improvements ahead of release to allow appropriate planning and assist in better taking advantage of the newly introduced APIs.

Core points

  1. Core auditing functionality has been re-implemented as a cross-product, cross-platform plugin. While the same plugin is used for both Server and Data Center, some differing functionality is exposed to the customer depending on their license.
  2. We expose a new management experience to help customers choose the right level of event coverage and retention to suit their organisation. Customers are able to configure the audit coverage in multiple areas based on the following levels:
    1… Base: Logs core events. This provides a minimum level of insight into the instance activity.
    2… [Data Center only] Advanced - Logs more than just core events. This provides a more detailed picture of instance activity.
    3… [Data Center only] Full - Logs all events for a comprehensive record of the instance activity.
    4… Off - Turns off logging for this area.
  3. The changes introduce improved search and filtering capabilities.
  4. [Data Center only] The new auditing framework includes a significant expansion of Audit Event coverage across the products for a more complete record of the customer instance.
  5. [Data Center only] Customers will now be able to selectively export audit log results.
  6. [Data Center only] We’ve added write to file functionality for integration with best of breed log consumption tools like Splunk and ELK.

Milestone features

Milestone 1 Milestone 1.1
Updated UI Audit Contents Translation support
File externalization People & Project filters
Coverage/Retention Controls Increased coverage
Export and selective export
Object Linking (user and location)
Full text search and time filter
Audit Delegation (users can see audit logs of project/space/etc they have admin permissions for)

Planned versions for release

The following product releases are expected to contain the new auditing framework

  1. Bitbucket 7.0 - Milestone 1
  2. Jira 8.8 - Milestone 1.1
  3. Confluence 7.5 - Milestone 1.1
  4. Bitbucket 7.2 - Milestone 1.1

Experience

Milestone 1 audit log view

Milestone 1 audit log settings view

Vendor interactions

A few principles which may be of particular note to the vendor community:

  1. The database is ephemeral and should be used by customers for short/medium-term storage. Long term retention is achieved using the write to file integration, or manual export.
  2. Security events, data egress and data removal events are critical events for logging.
  3. High-frequency audit events should be put in the Full category.

New APIs

There are two new APIs for producing and consuming auditing events.

Producing events
  1. Import com.atlassian.audit.api.AuditService , can be done via
  2. in atlassian-plugin-xml
  3. spring scanner, i.e. @ComponentImport
  4. spring java configuration
  5. spring xml configuration
  6. invoke void audit(@Nonnull AuditEvent event) method, for example
auditService.audit(AuditEvent.builder("actionName", "categoryName", BASE)
    .affectedObject(AuditResource.builder("project1", "Project").id("100").build())
    .changedValue(new ChangedValue("desc", "old", "new"))
    .build());
Consuming events
  1. Implement com.atlassian.audit.api.AuditConsumer
public class MyConsumer implements AuditConsumer {
    @Override
    public void accept(@Nonnull List<AuditEntity> entities) {
        requireNonNull(entities, "entities").forEach(System.out::println);
    }
}
  1. Export the component (MyConsumer) to osgi via
  • in atlassian-plugin-xml
  • spring scanner, i.e. @ExportAsService
  • spring java configuration
  • spring xml configuration

Where can I see this in action

Vendors can check out the BB 7.0 EAP to see Milestone 1 in action today:

EAP Announcement Link

Ben Magro
Data Center - Product Manager

8 Likes

When I use the Jira Java API in my Jira addon, are these method calls automatically included in the audit e.g.

  • ProjectManager (com.atlassian.jira.project.ProjectManager)
  • VersionManager (com.atlassian.jira.project.version.VersionManager)
  • OptionsManager (com.atlassian.jira.issue.customfields.manager.OptionsManager)
  • ProjectComponentManager (com.atlassian.jira.bc.project.component.ProjectComponentManager)
  • PermissionManager (com.atlassian.jira.security.PermissionManager)
3 Likes

In Jira 8.8
Components audited : (AuditService.audit() will be invoked):

  • ProjectManager (com.atlassian.jira.project.ProjectManager)
  • VersionManager (com.atlassian.jira.project.version.VersionManager)
  • ProjectComponentManager (com.atlassian.jira.bc.project.component.ProjectComponentManager)

Components are NOT audited:

  • OptionsManager (com.atlassian.jira.issue.customfields.manager.OptionsManager)
  • PermissionManager (com.atlassian.jira.security.PermissionManager)
1 Like

Is there a documentation available where this is listed? Would be useful to have this documented e.g. in the JavaDoc API documentation.

1 Like

@bmagro on https://confluence.atlassian.com/doc/preparing-for-confluence-7-5-994316380.html there is a link to ‘Audit log API changes’ - https://confluence.atlassian.com/doc/audit-log-api-changes-for-developers-994316387.html however this is does not work for me or my colleagues.

has https://docs.atlassian.com/ConfluenceServer/rest/7.5.0/#api/audit-getAuditRecords been updated with the changes?

Thanks

James

Hi James,

I’ve just checked the REST API request to https://something.com/wiki/rest/auditing/1.0/events?limit=1 and it works for me. Can you please describe your problem in more details?

For troubleshooting you can also check and verify that the bundled plugin “Atlassian Audit Plugin” is enabled on your system (it is the plugin who provides the REST API).

As for the previous audit REST API from the link https://docs.atlassian.com/ConfluenceServer/rest/7.5.0/#api/audit-getAuditRecords - it should still work in the same way (because Confluence has to support all existing REST APIs). But it’s implementation has been changed to use the new auditing framework under the hood. I recommend to migrate from the old REST API to the new one, because it’s more powerful and better reflects the current model.

I’m trying to add auditing to our plugin, but cannot wrap my head around how this is supposed to work. More specifically, I would like to produce audit events when our plugin creates and deletes its own plugin-specific objects.

I’ve looked at the Jira source code (e.g., IssueLinkingHandlerImpl.java) but that code uses the API in a different way: it uses constants like com.atlassian.jira.auditing.AuditingCategory.ISSUE to create AuditType:s, which are then passed to auditService.audit().

Since neither source code or documentation for com.atlassian.audit.api.AuditService seem to be available, I’m not sure how to use these constants.

Also, I’m adding the package via a pom.xml dependency:

        <dependency>
            <groupId>com.atlassian</groupId>
            <artifactId>atlassian-audit-api</artifactId>
            <version>0.0.7</version>
            <scope>provided</scope>
        </dependency>

Will this get me the correct API and version?

Thank you!

1 Like

Hey Gustav, Audit API is designed to allow consumer specifying category/action/level, in your example you either call i18n api if you have Audit API version 1.7.0+ (assuming those properties key are defined in your plugin i18n files)

AuditEvent auditEvent = AuditEvent.fromI18nKeys("MyPlugin.property.name", "ObjCreated.property.key", CoverageLevel.BASE)
                .build()

or

AuditEvent auditEvent = AuditEvent.builder("MyPlugin", "Obj Created", CoverageLevel.BASE)
                .build()

FYI
Jira 8.8/8.9 provides auditing API 1.5.7 (no i18n)
Jira 8.10 provides auditing API 1.8.5 (i18n supported)

Thank you!

What should the look like in pom.xml? The one I’ve tried seems to be incorrect (it only goes up to version 0.0.7).

Which Jira version are you testing against? Can you please bump the audit-api version to 1.5.0?

I’m building against Jira 8.10.0.

[ERROR] Failed to execute goal on project (plugin): 
Could not resolve dependencies for project (plugin): 
Could not find artifact com.atlassian:atlassian-audit-api:jar:1.5.0 in atlassian-public (https://maven.atlassian.com/repository/public) -> [Help 1]

Hey, the url (https://maven.atlassian.com/repository/public) seems to be deprecated, you should use ( packages.atlassian.com/maven/repository/public/).

We are in the process of deprecating all maven.atlassian.com urls. If you are using any of those, please change them to a url mentioned above as soon as practical. We will update the developer community more widely when we expect to decommision the old maven.atlassian.com urls permanently.

you can refer to this document : https://developer.atlassian.com/server/framework/atlassian-sdk/atlassian-maven-repositories-2818705/

1 Like

OK! I don’t know how do I change it, though.

atlas-version gives me

ATLAS Version:    8.0.16
ATLAS Home:       /usr/local/Cellar/atlassian-plugin-sdk62/6.2.14/libexec
ATLAS Scripts:    /usr/local/Cellar/atlassian-plugin-sdk62/6.2.14/libexec/bin
ATLAS Maven Home: /usr/local/Cellar/atlassian-plugin-sdk62/6.2.14/libexec/apache-maven-3.5.4
AMPS Version:     8.0.2
--------

which I believe is the latest version of the SDK.

Hey Gustav, actually the issue is caused by incorrect group id, we changed the group id to be com.atlassian.audit from version 0.0.8:

update your pom should fix the issue:

        <dependency>
            <groupId>com.atlassian.audit</groupId>
            <artifactId>atlassian-audit-api</artifactId>
            <version>1.5.0</version>
            <scope>provided</scope>
        </dependency>
1 Like

Thank you!

I’ve included that dependency in pom.xml. In my code I now have

import com.atlassian.audit.api.AuditService;
import com.atlassian.audit.entity.AuditEvent;
import static com.atlassian.audit.entity.CoverageLevel.BASE;

...
@Path("/somepath")
public class RESTEndpoint {
  ...
  private final AuditService fAuditService;

  @Inject
  public RESTEndpoint(
    ...
    @ComponentImport final AuditService iAuditService) {
      fAuditService = iAuditService;
      ...
  }
  ...
}

and in one of the class methods:

AuditEvent auditEvent = 
  AuditEvent.builder("My plugin", "My action", CoverageLevel.BASE)
  .build();
fAuditService.audit(auditEvent);

This results in a compilation error

[ERROR] myfile.java:[206,69] cannot find symbol
[ERROR]   symbol:   variable CoverageLevel

So I’m missing some other dependencies in pom.xml. Which one(s) should I add?

I think there is an issue in your code, you should either:

import com.atlassian.audit.entity.CoverageLevel;

AuditEvent.builder("My plugin", "My action", CoverageLevel.BASE)

or

import static com.atlassian.audit.entity.CoverageLevel.BASE;

AuditEvent.builder("My plugin", "My action", BASE)

That was indeed the error. Thank you!