@cap-js/audit-logging 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+This project adheres to [Semantic Versioning](http://semver.org/).
+The format is based on [Keep a Changelog](http://keepachangelog.com/).
+
+## Version 0.3.2 - 2023-10-11
+
+### Fixed
+
+- If the request has no tenant (e.g., Unauthorized), the audit log shall be sent to the provider account
+
+## Version 0.3.1 - 2023-09-25
+
+### Fixed
+
+- Defaulting of `@PersonalData.DataSubjectRole` to entity name
+- Overriding service configuration
+
+## Version 0.3.0 - 2023-09-05
+
+### Changed
+
+- Default value for `cds.requires['audit-log'].handle` changed to `['READ', 'WRITE']`, i.e., accessing sensitive data is now logged by default.
+
+## Version 0.2.0 - 2023-09-01
+
+### Added
+
+- Export class `AuditLogService` for extending in custom implementations as follows:
+  ```js
+  const { AuditLogService } = require('@cap-js/audit-logging')
+  class MyAuditLogService extends AuditLogService {
+    async init() {
+      [...]
+      // call AuditLogService's init
+      await super.init()
+    }
+  }
+  module.exports = MyAuditLogService
+  ```
+
+## Version 0.1.0 - 2023-08-18
+
+### Added
+
+- New API:
+  - `await audit.log('<event>', <data>)` for asynchronous logs (cf. `emit`)
+  - `await audit.logSync('<event>', <data>)` for synchronous logs (cf. `send`)
+- New REST API-based schema with auto-filled `LogEntry` aspect
+- New events `SensitiveDataRead`, `PersonalDataModified`, `ConfigurationModified`, and `SecurityEvent`
+- Full support for OAuth2 plan of SAP Audit Log Service
+
+### Changed
+
+- Whether reading sensitive data and modifying personal data is logged is determined by `cds.requires['audit-log'].handle: [...]`.
+  Possible values in the array are `READ` and/ or `WRITE`, with `WRITE` as the sole default entry.
+  Hence, accessing sensitive data is not logged by default.
+- Integration with SAP Audit Log Service via REST API instead of client library (`@sap/audit-logging`)
+
+### Fixed
+
+- Various glitches in log calculation
+
+### Removed
+
+- Old events `dataAccessLog`, `dataModificationLog`, `configChangeLog`, and `securityLog`
+- `@AuditLog.Operation` annotations are ignored. Having the plugin as dependency signals the intent to audit log.
+- `cds.features.audit_personal_data: true` is no longer necessary. Instead, simply add the plugin as a dependency.

package/README.md

@@ -1,8 +1,9 @@
 # Welcome to @cap-js/audit-logging
+[![REUSE status](https://api.reuse.software/badge/github.com/cap-js/audit-logging)](https://api.reuse.software/info/github.com/cap-js/audit-logging)
 
 ## About this project
 
-`@cap-js/audit-logging` is a CDS plugin providing integration to the SAP BTP Audit Logging Service as well as out-of-the-box personal data-related audit logging based on annotations.
+`@cap-js/audit-logging` is a CDS plugin providing integration to the SAP Audit Log service as well as out-of-the-box personal data-related audit logging based on annotations.
 
 Documentation can be found at [cap.cloud.sap](https://cap.cloud.sap/docs/guides/data-privacy).
 
@@ -10,7 +11,7 @@ Documentation can be found at [cap.cloud.sap](https://cap.cloud.sap/docs/guides/
 
 See [Getting Started](https://cap.cloud.sap/docs/get-started) on how to jumpstart your development and grow as you go with SAP Cloud Application Programming Model.
 
-The end-to-end out-of-the-box functionality provided by this plugin requires a paid-for instance of the [SAP Audit Logging Service for SAP BTP]([url](https://help.sap.com/docs/application-logging-service?locale=en-US)). However, it is possible to provide an own implementation that writes the audit logs to a custom store.
+The end-to-end out-of-the-box functionality provided by this plugin requires a paid-for instance of the [SAP Audit Log service for customers](https://help.sap.com/docs/btp/sap-business-technology-platform/audit-log-write-api-for-customers?locale=en-US). However, it is possible to provide an own implementation that writes the audit logs to a custom store.
 
 ## Support, Feedback, Contributing
 

package/lib/utils.js

@@ -1,8 +1,10 @@
 const WRITE = { CREATE: 1, UPDATE: 1, DELETE: 1 }
 
 const hasPersonalData = entity => {
-  if (!entity['@PersonalData.DataSubjectRole']) return
   if (!entity['@PersonalData.EntitySemantics']) return
+  // default role to entity name
+  if (entity['@PersonalData.EntitySemantics'] === 'DataSubject' && !entity['@PersonalData.DataSubjectRole'])
+    entity['@PersonalData.DataSubjectRole'] = entity.name.match(/\w+/g).pop()
   return !!Object.values(entity.elements).some(
     element =>
       element['@PersonalData.IsPotentiallyPersonal'] ||
@@ -148,31 +150,27 @@ const _getUps = (entity, model) => {
   return entity.set('__parents', ups)
 }
 
-const _ifDataSubject = (entity, role) => {
-  return entity['@PersonalData.EntitySemantics'] === 'DataSubject' && entity['@PersonalData.DataSubjectRole'] === role
-}
-
-const _getDataSubjectUp = (role, model, entity, prev, next, result) => {
+const _getDataSubjectUp = (model, entity, prev, next, result) => {
   for (const element of _getUps(entity, model)) {
     const me = { entity, relative: element.parent, element }
     if (prev) prev.next = me
-    if (_ifDataSubject(element.parent, role)) {
+    if (element.parent['@PersonalData.EntitySemantics'] === 'DataSubject') {
       if (!result) result = { dataSubjectEntity: element.parent, subs: [] }
       result.subs.push(next || me)
       return result
     } else {
       // dfs is a must here
-      result = _getDataSubjectUp(role, model, element.parent, me, next || me, result)
+      result = _getDataSubjectUp(model, element.parent, me, next || me, result)
     }
   }
   return result
 }
 
-const _getDataSubjectDown = (role, entity, prev, next) => {
+const _getDataSubjectDown = (entity, prev, next) => {
   const associations = Object.values(entity.associations || {}).filter(e => !e._isBacklink)
   for (const element of associations) {
     const me = { entity, relative: entity, element }
-    if (_ifDataSubject(element._target, role)) {
+    if (element._target['@PersonalData.EntitySemantics'] === 'DataSubject') {
       if (prev) prev.next = me
       return { dataSubjectEntity: element._target, subs: [next || me] }
     }
@@ -181,24 +179,25 @@ const _getDataSubjectDown = (role, entity, prev, next) => {
   for (const element of associations) {
     const me = { entity, relative: entity, element }
     if (prev) prev.next = me
-    const dataSubject = _getDataSubjectDown(role, element._target, me, next || me)
+    const dataSubject = _getDataSubjectDown(element._target, me, next || me)
     if (dataSubject) return dataSubject
   }
 }
 
-const getDataSubject = (entity, model, role) => {
-  const hash = '__dataSubject4' + role
+const getDataSubject = (entity, model) => {
+  const hash = '__dataSubject'
   if (entity.own(hash)) return entity[hash]
   // entities with EntitySemantics 'DataSubjectDetails' or 'Other' must not necessarily
   // be always below or always above 'DataSubject' entity in CSN tree
-  let dataSubject = _getDataSubjectUp(role, model, entity)
-  if (!dataSubject) dataSubject = _getDataSubjectDown(role, entity)
-  return entity.set(hash, dataSubject)
+  let dataSubjectInfo = _getDataSubjectUp(model, entity)
+  if (!dataSubjectInfo) dataSubjectInfo = _getDataSubjectDown(entity)
+  return entity.set(hash, dataSubjectInfo)
 }
 
 const addDataSubjectForDetailsEntity = (row, log, req, entity, model) => {
-  const role = entity['@PersonalData.DataSubjectRole']
-  const dataSubjectInfo = getDataSubject(entity, model, role)
+  const dataSubjectInfo = getDataSubject(entity, model)
+  const role = dataSubjectInfo.dataSubjectEntity['@PersonalData.DataSubjectRole']
+  log.data_subject.role ??= role
   log.data_subject.type = dataSubjectInfo.dataSubjectEntity.name
   /*
    * for each req (cf. $batch with atomicity) and data subject role (e.g., customer vs supplier),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cap-js/audit-logging",
-  "version": "0.3.0",
-  "description": "CDS plugin providing integration to the SAP BTP Audit Logging Service as well as out-of-the-box personal data-related audit logging based on annotations.",
+  "version": "0.3.2",
+  "description": "CDS plugin providing integration to the SAP Audit Log service as well as out-of-the-box personal data-related audit logging based on annotations.",
   "repository": "cap-js/audit-logging",
   "author": "SAP SE (https://www.sap.com)",
   "homepage": "https://cap.cloud.sap/",
@@ -9,7 +9,8 @@
   "main": "cds-plugin.js",
   "files": [
     "lib",
-    "srv"
+    "srv",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "lint": "npx eslint .",
@@ -21,27 +22,25 @@
   "devDependencies": {
     "@cap-js/sqlite": "^1",
     "axios": "^1",
-    "better-sqlite3": "8.5.2",
     "eslint": "^8",
     "express": "^4",
     "jest": "^29"
   },
   "cds": {
     "requires": {
-      "audit-log": true,
-      "kinds": {
-        "audit-log": {
-          "handle": [
-            "READ",
-            "WRITE"
-          ],
-          "[development]": {
-            "kind": "audit-log-to-console"
-          },
-          "[production]": {
-            "kind": "audit-log-to-restv2"
-          }
+      "audit-log": {
+        "handle": [
+          "READ",
+          "WRITE"
+        ],
+        "[development]": {
+          "kind": "audit-log-to-console"
         },
+        "[production]": {
+          "kind": "audit-log-to-restv2"
+        }
+      },
+      "kinds": {
         "audit-log-to-console": {
           "impl": "@cap-js/audit-logging/srv/log2console",
           "outbox": false

package/srv/log2restv2.js

@@ -69,6 +69,7 @@ module.exports = class AuditLog2RESTv2 extends AuditLogService {
       setTimeout(() => tokens.delete(tenant), (expires_in - 60) * 1000)
       return access_token
     } catch (err) {
+      LOG._trace && LOG.trace('error during token fetch:', err)
       // 401 could also mean x-zid is not valid
       if (String(err.response?.statusCode).match(/^4\d\d$/)) err.unrecoverable = true
       throw err
@@ -76,25 +77,30 @@ module.exports = class AuditLog2RESTv2 extends AuditLogService {
   }
 
   async _send(data, path) {
-    let url
     const headers = { 'content-type': 'application/json' }
-    // TODO: what are these for?
     if (this._vcap) {
       headers.XS_AUDIT_ORG = this._vcap.organization_name
       headers.XS_AUDIT_SPACE = this._vcap.space_name
       headers.XS_AUDIT_APP = this._vcap.application_name
     }
+    let url
     if (this._oauth2) {
       url = this.options.credentials.url + PATHS.OAUTH2[path]
+      data.tenant ??= this._providerTenant //> if request has no tenant, stay in provider account
       headers.authorization = 'Bearer ' + (await this._getToken(data.tenant))
       data.tenant = data.tenant === this._providerTenant ? '$PROVIDER' : '$SUBSCRIBER'
     } else {
       url = this.options.credentials.url + PATHS.STANDARD[path]
       headers.authorization = this._auth
     }
+    if (LOG._debug) {
+      const _headers = Object.assign({}, headers, { authorization: headers.authorization.split(' ')[0] + ' ***' })
+      LOG.debug(`sending audit log to ${url} with tenant "${data.tenant}", user "${data.user}", and headers`, _headers)
+    }
     try {
       await _post(url, data, headers)
     } catch (err) {
+      LOG._trace && LOG.trace('error during log send:', err)
       // 429 (rate limit) is not unrecoverable
       if (String(err.response?.statusCode).match(/^4\d\d$/) && err.response?.statusCode !== 429)
         err.unrecoverable = true