sap\_audit\_logging
===================
Provides audit logging functionalities for Python applications.
**Note**: From v1.3.0 of the library, it requires Python >=3.7.
Overview
--------
Audit logging is about writing entries in a specific format to a log
storage. Subject to audit logging are events of significant importance.
For example, security events which may impact the confidentiality, the
integrity or the availability of a system. Another example of such an
event would be access to personal data (both reading and altering) like
bank accounts, political opinion, health status, etc.
While the consumer of ordinary logs is a system administrator who would
like to keep track of the state of a system, audit logs are read by an
auditor. There are legal requirements regarding audit logging.
In general, the events that are supposed to be audit logged can be
grouped in 3 main categories:
- changes to system configurations (which may have significant effect on the system itself)
- access to personal data (related to data privacy)
- general security events (like starting/stopping a system, failed authorization checks, etc.)
General audit logging principles
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- All attempts to perform an action in a system should be audit logged,
no matter if they have been successful or not.
- Audit log entries should be consistent with the state of the system.
If, for example, the writing of the audit log entry fails, but the
changes to system critical parameters have been applied, then those
changes should be reverted. Best practice is to wait for the callback
of the logger before continuing with the execution of other code.
- Especially important is which user (or other agent) has triggered the
corresponding event that is being audit logged. For most of the cases
the library will validate that such a field is provided in the
message.
- All audit log entries should be in English. Numbers should be
converted to strings with English locale. All time fields should be
in UTC time in order to avoid timezone and day light saving time
issues.
- Passwords should never be audit logged.
Prerequisites
~~~~~~~~~~~~~
An application using the audit log library needs to be bound to an
instance of the audit log service.
API
---
The library provides an API for writing audit messages of type
configuration changes, data modifications, data accesses and security
events.
The library is using `Audit Log service API V2 <https://github.wdf.sap.corp/xs-audit-log/audit-java-client/wiki/Audit-Log-V2>`_.
Importing the library
~~~~~~~~~~~~~~~~~~~~~
.. code:: python
from sap.audit_logging import AuditLogger
Create message factory
~~~~~~~~~~~~~~~~~~~~~~
.. code:: python
audit_logger = AuditLogger()
This will create an audit log message factory which will use the audit
log service binding from the *VCAP\_SERVICES* environment variable. If more
than one audit log service binding is available, you can specify the
service instance name in the *AuditLogger* constructor. For example:
.. code:: python
audit_logger = AuditLogger('<service_instance_name>')
It is also possible to directly pass audit log service credentials
(a dictionary) when creating the message factory:
.. code:: python
audit_logger = AuditLogger(credentials={...})
**Note**: If no service instance is available in the environment then
messages will be logged to the standard output.
**Note**: The library takes *application\_name*, *organization\_name* and *space\_name* from
the environment variable *VCAP\_APPLICATION* and sends them to the audit
log service.
The library supports the *oauth2* plan of the audit log service. Also, it supports and x509 certificate.
It is possible to provide the user information via configuring a message factory
with a security context object. Refer to the documentation of `xssec <https://github.com/SAP/cloud-pysec>`_
for more information. Example:
.. code:: python
audit_logger = AuditLogger('<service_instance_name>').with_security_context(security_context)
**Note**: When a message is logged, the library checks for missing mandatory properties, and will throw an error if some of them are
not provided.
**Note**: In case a request to audit log service fails, the library will retry sending it.
By default the number of attempts is 5, can be configured via the *AUDITLOG_CONNECTION_RETRY_COUNT* environment variable.
The default backoff factor (time between retry attempts after the second try) is `1` second. It can be configured via
the *AUDITLOG_CONNECTION_BACKOFF_FACTOR* environment variable.
**Note**: The request timeout can be configured to avoid long lasting requests.
By default there is no timeout, it can be configured via the *AUDITLOG_CONNECTION_TIMEOUT* environment variable (timeout in seconds).
Data access messages
~~~~~~~~~~~~~~~~~~~~
If you need to create an entry for a data access operation
over personal data, you can achieve that with the following code:
.. code:: python
data_access_message = audit_logger.create_data_access_msg()
data_access_message\
.set_user('user123')\
.set_tenant('tenant')\
.set_channel('RFC')\
.set_object({
'type': '<string>',
'id': {
'<string>': '<string>'
}
})\
.set_data_subject({
'type': '<string>',
'role': '<string>',
'id': {
'<string>': '<string>'
}
})\
.add_attribute('news', True)\
.add_attachment('attachment_id', 'attachment_name')\
.log()
- ``set_user(user)`` - takes a string which identifies the *user*
performing the action. This is **mandatory**.
- ``set_tenant(tenant)`` - takes a string which specifies the tenant
id. The provided value is ignored by older versions of the audit log
service that do not support setting a tenant.
- ``set_channel(channel)`` - takes a string which specifies *channel*
of access.
- ``set_object(object_attributes)`` - takes a *dict* which specifies the object which is being *accessed*. The *dict* must have two properties: 'type' - *string* and 'id' - *dict*. This is **mandatory**.
- ``set_data_subject(data_subject)`` - takes a *dict* which specifies the data subject. The *dict* must have two properties: 'type' - *string* and 'id' - *dict*. It can also have an optional property 'role' - *string*. This is **mandatory**.
- ``add_attribute(name, is_successful)`` - sets object attributes. It
is **mandatory** to provide at least one attribute.
- ``name`` - is the name of the attribute being accessed.
- ``is_successful`` - specifies whether the access was successful or not.
- ``add_attachment(attachment_id, name)`` - if attachments or files are
downloaded or displayed, information identifying the attachment shall
be logged.
- ``attachment_id`` - attachment id
- ``name`` - attachment name
- ``log()`` - sends the message to the audit log service.
Data modification messages
~~~~~~~~~~~~~~~~~~~~~~~~~~
Here is how to create an entry for a data modification operation:
.. code:: python
data_modification_message = audit_logger.create_data_modification_msg()
data_modification_message\
.set_user('user123')\
.set_tenant('tenant')\
.set_object({
'type': '<string>',
'id': {
'<string>': '<string>'
}
})\
.set_data_subject({
'type': '<string>',
'role': '<string>',
'id': {
'<string>': '<string>'
}
})\
.add_attribute('news', 'old news', 'new news')\
.log_prepare()
# make modification ...
# set modification as successful
data_modification_message.log_success()
- ``set_user(user)`` - takes a string which identifies the *user*
performing the action. This is **mandatory**.
- ``set_tenant(tenant)`` - takes a string which specifies the tenant
id. The provided value is ignored by older versions of the audit log
service that do not support setting a tenant.
- ``set_object(object_attributes)`` - takes a *dict* which specifies the object which is being *accessed*. The *dict* must have two properties: 'type' - *string* and 'id' - *dict*. This is **mandatory**.
- ``set_data_subject(data_subject)`` - takes a *dict* which specifies the data subject. The *dict* must have two properties: 'type' - *string* and 'id' - *dict*. It can also have an optional property 'role' - *string*. This is **mandatory**.
- ``add_attribute(name, old_value, new_value)`` - sets object
attributes. It is **mandatory** to provide at least one attribute.
- ``name`` - is the name of the attribute being modified.
- ``old_value`` - is the current value of the attribute.
- ``new_value`` - is the value of the attribute after the change.
- ``log_prepare()`` - sends the message to the audit log service with
status *pending*.
- ``log_success()`` - updates the message status to *successful*.
- ``log_failure()`` - updates the message status to *failed*.
**Note**: If *log\_success* or *log\_failure* are called without
*log\_prepare*, the message will be sent to the audit log service with
the corresponding status.
Configuration change messages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Here is how to create an entry for a configuration change operation:
.. code:: python
configuration_change_message = audit_logger.create_configuration_change_msg()
configuration_change_message\
.set_user('user123')\
.set_tenant('tenant')\
.set_object({
'type': '<string>',
'id': {
'<string>': '<string>'
}
})\
.add_attribute('news', 'old news', 'new news')\
.log_prepare()
# make configuration change ...
# set configuration change as successful
configuration_change_message.log_success()
- ``set_user(user)`` - takes a string which identifies the *user*
performing the action. This is **mandatory**.
- ``set_tenant(tenant)`` - takes a string which specifies the tenant
id. The provided value is ignored by older versions of the audit log
service that do not support setting a tenant.
- ``set_object(object_attributes)`` - takes a *dict* which specifies the object which is being *accessed*. The *dict* must have two properties: 'type' - *string* and 'id' - *dict*. This is **mandatory**.
- ``add_attribute(name, old_value, new_value)`` - sets object
attributes. It is **mandatory** to provide at least one attribute.
- ``name`` - is the name of the attribute being modified.
- ``old_value`` - is the current value of the attribute.
- ``new_value`` - is the value of the attribute after the change.
- ``log_prepare()`` - sends the message to the audit log service with
status *pending*.
- ``log_success()`` - updates the message status to *successful*.
- ``log_failure()`` - updates the message status to *failed*.
General security messages
~~~~~~~~~~~~~~~~~~~~~~~~~
Here is how to create a general security audit log message:
.. code:: python
security_event_message = audit_logger.create_security_event_msg()
security_event_message\
.set_user('user123')\
.set_tenant('tenant')\
.set_data('unsuccessful login attempt')\
.set_ip('1.1.1.1')\
.log()
- ``set_user(user)`` - takes a string which identifies the *user*
performing the action. This is **mandatory**.
- ``set_tenant(tenant)`` - takes a string which specifies the tenant
id. The provided value is ignored by older versions of the audit log
service that do not support setting a tenant.
- ``set_data(data)`` - takes a string representing the security event
description. This is **mandatory**.
- ``set_ip(source_ip)`` - states the IP of the machine that contacts
the system. It is not mandatory, but it should be either IPv4 or
IPv6.
- ``log()`` - sends the message to the audit log service.
Raw data
{
"_id": null,
"home_page": "https://www.sap.com/",
"name": "sap-audit-logging",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "SAP audit auditlog",
"author": "SAP SE",
"author_email": "",
"download_url": "",
"platform": null,
"description": "sap\\_audit\\_logging\n===================\n\nProvides audit logging functionalities for Python applications.\n\n**Note**: From v1.3.0 of the library, it requires Python >=3.7.\n\nOverview\n--------\n\nAudit logging is about writing entries in a specific format to a log\nstorage. Subject to audit logging are events of significant importance.\nFor example, security events which may impact the confidentiality, the\nintegrity or the availability of a system. Another example of such an\nevent would be access to personal data (both reading and altering) like\nbank accounts, political opinion, health status, etc.\n\nWhile the consumer of ordinary logs is a system administrator who would\nlike to keep track of the state of a system, audit logs are read by an\nauditor. There are legal requirements regarding audit logging.\n\nIn general, the events that are supposed to be audit logged can be\ngrouped in 3 main categories:\n\n- changes to system configurations (which may have significant effect on the system itself)\n- access to personal data (related to data privacy)\n- general security events (like starting/stopping a system, failed authorization checks, etc.)\n\nGeneral audit logging principles\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n- All attempts to perform an action in a system should be audit logged,\n no matter if they have been successful or not.\n- Audit log entries should be consistent with the state of the system.\n If, for example, the writing of the audit log entry fails, but the\n changes to system critical parameters have been applied, then those\n changes should be reverted. Best practice is to wait for the callback\n of the logger before continuing with the execution of other code.\n- Especially important is which user (or other agent) has triggered the\n corresponding event that is being audit logged. For most of the cases\n the library will validate that such a field is provided in the\n message.\n- All audit log entries should be in English. Numbers should be\n converted to strings with English locale. All time fields should be\n in UTC time in order to avoid timezone and day light saving time\n issues.\n- Passwords should never be audit logged.\n\nPrerequisites\n~~~~~~~~~~~~~\n\nAn application using the audit log library needs to be bound to an\ninstance of the audit log service.\n\nAPI\n---\n\nThe library provides an API for writing audit messages of type\nconfiguration changes, data modifications, data accesses and security\nevents.\nThe library is using `Audit Log service API V2 <https://github.wdf.sap.corp/xs-audit-log/audit-java-client/wiki/Audit-Log-V2>`_.\n\nImporting the library\n~~~~~~~~~~~~~~~~~~~~~\n\n.. code:: python\n\n from sap.audit_logging import AuditLogger\n\nCreate message factory\n~~~~~~~~~~~~~~~~~~~~~~\n\n.. code:: python\n\n audit_logger = AuditLogger()\n\nThis will create an audit log message factory which will use the audit\nlog service binding from the *VCAP\\_SERVICES* environment variable. If more\nthan one audit log service binding is available, you can specify the\nservice instance name in the *AuditLogger* constructor. For example:\n\n.. code:: python\n\n audit_logger = AuditLogger('<service_instance_name>')\n\nIt is also possible to directly pass audit log service credentials\n(a dictionary) when creating the message factory:\n\n.. code:: python\n\n audit_logger = AuditLogger(credentials={...})\n\n**Note**: If no service instance is available in the environment then\nmessages will be logged to the standard output.\n\n**Note**: The library takes *application\\_name*, *organization\\_name* and *space\\_name* from\nthe environment variable *VCAP\\_APPLICATION* and sends them to the audit\nlog service.\n\nThe library supports the *oauth2* plan of the audit log service. Also, it supports and x509 certificate.\nIt is possible to provide the user information via configuring a message factory\nwith a security context object. Refer to the documentation of `xssec <https://github.com/SAP/cloud-pysec>`_\nfor more information. Example:\n\n.. code:: python\n\n audit_logger = AuditLogger('<service_instance_name>').with_security_context(security_context)\n\n**Note**: When a message is logged, the library checks for missing mandatory properties, and will throw an error if some of them are\nnot provided.\n\n**Note**: In case a request to audit log service fails, the library will retry sending it.\nBy default the number of attempts is 5, can be configured via the *AUDITLOG_CONNECTION_RETRY_COUNT* environment variable.\nThe default backoff factor (time between retry attempts after the second try) is `1` second. It can be configured via \nthe *AUDITLOG_CONNECTION_BACKOFF_FACTOR* environment variable.\n\n**Note**: The request timeout can be configured to avoid long lasting requests.\nBy default there is no timeout, it can be configured via the *AUDITLOG_CONNECTION_TIMEOUT* environment variable (timeout in seconds).\n\nData access messages\n~~~~~~~~~~~~~~~~~~~~\n\nIf you need to create an entry for a data access operation\nover personal data, you can achieve that with the following code:\n\n.. code:: python\n\n data_access_message = audit_logger.create_data_access_msg()\n data_access_message\\\n .set_user('user123')\\\n .set_tenant('tenant')\\\n .set_channel('RFC')\\\n .set_object({\n 'type': '<string>',\n 'id': {\n '<string>': '<string>'\n }\n })\\\n .set_data_subject({\n 'type': '<string>',\n 'role': '<string>',\n 'id': {\n '<string>': '<string>'\n }\n })\\\n .add_attribute('news', True)\\\n .add_attachment('attachment_id', 'attachment_name')\\\n .log()\n\n- ``set_user(user)`` - takes a string which identifies the *user*\n performing the action. This is **mandatory**.\n- ``set_tenant(tenant)`` - takes a string which specifies the tenant\n id. The provided value is ignored by older versions of the audit log\n service that do not support setting a tenant.\n- ``set_channel(channel)`` - takes a string which specifies *channel*\n of access.\n- ``set_object(object_attributes)`` - takes a *dict* which specifies the object which is being *accessed*. The *dict* must have two properties: 'type' - *string* and 'id' - *dict*. This is **mandatory**.\n- ``set_data_subject(data_subject)`` - takes a *dict* which specifies the data subject. The *dict* must have two properties: 'type' - *string* and 'id' - *dict*. It can also have an optional property 'role' - *string*. This is **mandatory**.\n- ``add_attribute(name, is_successful)`` - sets object attributes. It\n is **mandatory** to provide at least one attribute.\n - ``name`` - is the name of the attribute being accessed.\n - ``is_successful`` - specifies whether the access was successful or not.\n- ``add_attachment(attachment_id, name)`` - if attachments or files are\n downloaded or displayed, information identifying the attachment shall\n be logged.\n - ``attachment_id`` - attachment id\n - ``name`` - attachment name\n- ``log()`` - sends the message to the audit log service.\n\nData modification messages\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nHere is how to create an entry for a data modification operation:\n\n.. code:: python\n\n data_modification_message = audit_logger.create_data_modification_msg()\n data_modification_message\\\n .set_user('user123')\\\n .set_tenant('tenant')\\\n .set_object({\n 'type': '<string>',\n 'id': {\n '<string>': '<string>'\n }\n })\\\n .set_data_subject({\n 'type': '<string>',\n 'role': '<string>',\n 'id': {\n '<string>': '<string>'\n }\n })\\\n .add_attribute('news', 'old news', 'new news')\\\n .log_prepare()\n # make modification ...\n # set modification as successful\n data_modification_message.log_success()\n\n- ``set_user(user)`` - takes a string which identifies the *user*\n performing the action. This is **mandatory**.\n- ``set_tenant(tenant)`` - takes a string which specifies the tenant\n id. The provided value is ignored by older versions of the audit log\n service that do not support setting a tenant.\n- ``set_object(object_attributes)`` - takes a *dict* which specifies the object which is being *accessed*. The *dict* must have two properties: 'type' - *string* and 'id' - *dict*. This is **mandatory**.\n- ``set_data_subject(data_subject)`` - takes a *dict* which specifies the data subject. The *dict* must have two properties: 'type' - *string* and 'id' - *dict*. It can also have an optional property 'role' - *string*. This is **mandatory**.\n- ``add_attribute(name, old_value, new_value)`` - sets object\n attributes. It is **mandatory** to provide at least one attribute.\n - ``name`` - is the name of the attribute being modified.\n - ``old_value`` - is the current value of the attribute.\n - ``new_value`` - is the value of the attribute after the change.\n- ``log_prepare()`` - sends the message to the audit log service with\n status *pending*.\n- ``log_success()`` - updates the message status to *successful*.\n- ``log_failure()`` - updates the message status to *failed*.\n\n**Note**: If *log\\_success* or *log\\_failure* are called without\n*log\\_prepare*, the message will be sent to the audit log service with\nthe corresponding status.\n\nConfiguration change messages\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nHere is how to create an entry for a configuration change operation:\n\n.. code:: python\n\n configuration_change_message = audit_logger.create_configuration_change_msg()\n configuration_change_message\\\n .set_user('user123')\\\n .set_tenant('tenant')\\\n .set_object({\n 'type': '<string>',\n 'id': {\n '<string>': '<string>'\n }\n })\\\n .add_attribute('news', 'old news', 'new news')\\\n .log_prepare()\n # make configuration change ...\n # set configuration change as successful\n configuration_change_message.log_success()\n\n- ``set_user(user)`` - takes a string which identifies the *user*\n performing the action. This is **mandatory**.\n- ``set_tenant(tenant)`` - takes a string which specifies the tenant\n id. The provided value is ignored by older versions of the audit log\n service that do not support setting a tenant.\n- ``set_object(object_attributes)`` - takes a *dict* which specifies the object which is being *accessed*. The *dict* must have two properties: 'type' - *string* and 'id' - *dict*. This is **mandatory**.\n- ``add_attribute(name, old_value, new_value)`` - sets object\n attributes. It is **mandatory** to provide at least one attribute.\n - ``name`` - is the name of the attribute being modified.\n - ``old_value`` - is the current value of the attribute.\n - ``new_value`` - is the value of the attribute after the change.\n- ``log_prepare()`` - sends the message to the audit log service with\n status *pending*.\n- ``log_success()`` - updates the message status to *successful*.\n- ``log_failure()`` - updates the message status to *failed*.\n\nGeneral security messages\n~~~~~~~~~~~~~~~~~~~~~~~~~\n\nHere is how to create a general security audit log message:\n\n.. code:: python\n\n security_event_message = audit_logger.create_security_event_msg()\n security_event_message\\\n .set_user('user123')\\\n .set_tenant('tenant')\\\n .set_data('unsuccessful login attempt')\\\n .set_ip('1.1.1.1')\\\n .log()\n\n- ``set_user(user)`` - takes a string which identifies the *user*\n performing the action. This is **mandatory**.\n- ``set_tenant(tenant)`` - takes a string which specifies the tenant\n id. The provided value is ignored by older versions of the audit log\n service that do not support setting a tenant.\n- ``set_data(data)`` - takes a string representing the security event\n description. This is **mandatory**.\n- ``set_ip(source_ip)`` - states the IP of the machine that contacts\n the system. It is not mandatory, but it should be either IPv4 or\n IPv6.\n- ``log()`` - sends the message to the audit log service.\n",
"bugtrack_url": null,
"license": "SAP DEVELOPER LICENSE AGREEMENT",
"summary": "SAP Python audit log service client",
"version": "1.3.0",
"project_urls": {
"Homepage": "https://www.sap.com/"
},
"split_keywords": [
"sap",
"audit",
"auditlog"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a53e412f695005319d6c30844918ce1f041ef7049a2143e825da987b3da36f3c",
"md5": "0b4fa9f69b79e0d1ea91c70012bc4dd3",
"sha256": "24193e86f8ae1082944d7359ff7829b5228b0b8628496f3b8ea17ccf9ea04009"
},
"downloads": -1,
"filename": "sap_audit_logging-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0b4fa9f69b79e0d1ea91c70012bc4dd3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 19326,
"upload_time": "2023-06-05T14:10:01",
"upload_time_iso_8601": "2023-06-05T14:10:01.420966Z",
"url": "https://files.pythonhosted.org/packages/a5/3e/412f695005319d6c30844918ce1f041ef7049a2143e825da987b3da36f3c/sap_audit_logging-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-05 14:10:01",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "sap-audit-logging"
}
JSON