Which audit evidence EspoCRM produces by default and what it does not
EspoCRM produces change and access evidence through Audited fields, the Audit Log, the auth log and action history, but its default cleanup periods delete much of that evidence within months. Marking a field as Audited stores its changes in the stream and makes them available in the Audit Log, so the decision of which fields are audited is the first control to design. Out of the box, the config defaults remove action history after 15 days, the auth log after 2 months and audit log records after 3 months through cleanupActionHistoryPeriod, cleanupAuthLogPeriod and cleanupAuditPeriod. A regulated team that must answer a question about a change made a year ago will find that the record is already gone unless these periods were raised before the data was created.
DeployOpen plans and configures the audit settings, prepares the evidence procedures and documents what the instance records, but it does not issue audit reports, attestations or certificates. Those come from independent auditors and, for ISO/IEC 27001:2022, from accredited certification bodies that assess Annex A controls such as logging and monitoring against your own documented scope. Before you rely on any audited field, confirm with your compliance lead which events must be retained, for how long, and whether field changes made through the API or CSV import are captured the same way as changes made in the user interface. Test this on a non-production copy by making a known change through each path and checking the Audit Log and stream.
Plan the retention decision before go-live, because raising the cleanup periods later does not restore records already deleted. Decide which evidence belongs in your retention schedule, set the three cleanup parameters to match it, and check that database backups and any log shipping keep copies for at least as long as the CRM does. Also confirm how the audit trail behaves when an administrator changes a field definition, since a rename or a removed audited field can make historic entries harder to interpret. Record these decisions in writing so an assessor can see that the settings were chosen deliberately rather than left at defaults.
Mapping audit log requirements to EspoCRM settings
This table maps common Annex A evidence needs in ISO/IEC 27001:2022 to the EspoCRM capability that produces the evidence and the settings to review. Read each row as a question to answer for your environment, and confirm the control mapping with your certification body before relying on it. The main takeaway is that the default cleanup periods are short, so retention settings need to match your policy before production use.
| Requirement | EspoCRM capability | Configuration needed |
|---|---|---|
| 8.15 Logging: change evidence for audited fields | Fields marked as Audited store their changes in the stream and in the Audit Log. | Mark each field whose changes you must evidence as Audited. Keep a written list of covered fields. |
| 8.15 Logging: access evidence from logins | The auth log records login activity for user accounts. | Review cleanupAuthLogPeriod against your retention policy. The default is 2 months. |
| 8.16 Monitoring activities: user action history | Action history records user activity in the instance. | Set cleanupActionHistoryPeriod to match review needs. The default is 15 days, so confirm how longer retention is met. |
| 5.33 Protection of records: audit log retention | Audit log records are removed by a cleanup job after the configured period. | Set cleanupAuditPeriod to your policy. The default is 3 months. Back up the database before any cleanup. |
| 8.5 Secure authentication: identity provider sign-in | OIDC sign-in moves authentication events to the identity provider, and EspoCRM's own 2FA does not work with OIDC. | Confirm which system holds sign-in evidence. Retain identity provider logs under their own policy. |
| 8.10 Information deletion: cleanup against policy | Cleanup periods delete action history, auth log and audit log records automatically. | Document each period, its owner and its link to the deletion schedule. Test the setting in a non-production copy. |
| 8.17 Clock synchronization: consistent timestamps | Evidence is only useful if timestamps from EspoCRM, its database and the identity provider agree. | Confirm that the application, database and identity provider hosts use a synchronized time source. |
What evidence to keep from EspoCRM and how to keep it
EspoCRM produces several separate records of change and access, and each one has its own cleanup behavior. Treat them as distinct evidence sources, decide which ones an auditor will ask for, and move copies out of the instance before the default periods remove them.
Stream entries for audited fields
Audited fields write their changes into the record's stream, so a reviewer can see who changed a value and when. Check that every field carrying regulated or financial data is marked Audited before go-live, because a field that was not audited leaves no change trail. Stream entries follow the record, but they are still subject to the action history cleanup, so export the stream for records that matter before that window closes.
Audit Log records
The Audit Log holds the consolidated history of audited field changes across entities, which suits questions such as who changed a credit limit across all accounts in a quarter. Confirm in your own instance that the audit feature is enabled and test it with a controlled change. Audit Log records are removed by the audit cleanup period, so schedule regular exports to storage you control, with the record identifiers and timestamps intact.
Auth log entries
The auth log records login attempts and session events, which answers who accessed the system and from where. This is the evidence behind access reviews and investigations of compromised accounts. Pair it with your identity provider logs when you use OpenID Connect sign-in, since the EspoCRM entry shows only what EspoCRM received. Its default cleanup period is shorter than many access review cycles, so forward these entries to your log platform.
Action history
Action history records user actions such as views, edits and deletions, and it supports reconstruction of what a user did in the application. It is the shortest-lived record in the default configuration, so it is the first to disappear. Decide whether it counts as evidence in your policy, and if it does, set a longer cleanup period and document the change with a reason.
Exports taken as snapshots
A dated export of key entities gives an auditor a fixed view of the data at one point in time, independent of later edits or deletions. Use the export tooling your team controls, store the files with a hash and a retrieval log, and record who ran the export and why. Snapshots prove the state of data, not the history of changes, so keep them alongside the audit records rather than in place of them.
Configuration record of audited fields and cleanup periods
The configuration showing which fields are audited and which cleanup periods are set is evidence in its own right, because it proves the controls existed during the audit period. Version it in your change management system and export it after each change. Without this record, an auditor cannot tell whether a missing trail was a gap in logging or a setting chosen by policy.
How audited fields, the stream and the Audit Log connect
Marking a field as Audited is the one documented switch that produces change evidence for a specific field. Once it is set, changes to that field are stored in the record's stream, and the same changes are made available in the Audit Log. The two views are not separate recording systems. Treat the stream as the place a user reads the history of a record, and the Audit Log as the place an administrator searches across records. Before you rely on either, decide which fields carry regulatory or contractual weight (for example, contact details, consent flags, account owner, status and pricing) and mark those fields in the Entity Manager or field settings for each entity that holds them. A field that is not marked leaves no change trail in these views, so the list of audited fields is a control in its own right and belongs in your records of processing.
The documented feature covers changes to marked fields. It does not, on its own, prove who viewed a record, who exported it, or what a script changed in a field that was not marked. Access history sits in the auth log and action history, which have their own cleanup settings and are covered in the sections that follow. Because the behavior of stream and Audit Log entries can differ by version and by how a change was made (through the UI, the REST API, an import or a formula script), run a sample change on a non-production instance before you write the control down. Edit a marked field in the UI, change it through an API user, run a CSV import that updates it, and then check what the stream shows, what the Audit Log shows, which user name and timestamp each records, and whether old and new values both appear. Repeat the check after each upgrade, using the EspoCRM releases page to confirm the version you are testing against.
Configuring audit evidence before go-live
This sequence sets up EspoCRM so that changes to personal data, login activity and user actions are recorded, kept for a period you have chosen on purpose, and traceable to a named owner. It finishes with a tested evidence trail that your team can show an auditor or privacy reviewer.
Inventory personal data fields and log decisions
Before changing any setting, list every entity and field that holds customer personal data, such as contact names, email addresses, phone numbers, addresses and account notes. Record which entities feed the Audit Log and which actions your policy requires you to evidence, such as changes to contact details, status changes and record deletion. Your privacy lead and a CRM administrator should sign off on this list. The step is done when the list is approved and each field has a named business reason for being audited.
Mark required fields as audited
In the Entity Manager, open each entity on the approved list and mark the chosen fields as Audited. Audited field changes are stored in the stream and become available in the Audit Log, so only fields listed in the inventory should be changed. A CRM administrator makes the change and records the date and the name of the person who approved it. The step is done when a test edit to each audited field appears in the stream and the Audit Log.
Set cleanup periods against retention policy
Review cleanupActionHistoryPeriod, cleanupAuthLogPeriod and cleanupAuditPeriod in the configuration. EspoCRM's defaults clean up action history, the auth log and audit log records after set periods, so a default value may delete evidence sooner than your retention policy requires. Compare each value with the retention period your legal and compliance owners have approved, and set each one deliberately. The step is done when the three values match a written retention decision, and that decision is saved with the configuration change record.
Enforce two-factor authentication and restrict admin use
Apply the controls the EspoCRM security documentation recommends: a password policy, two-factor authentication for all users, a separate administrator account for setup work rather than daily use, limited auth token lifetime, disabled password recovery for admins and IP restrictions where your network allows. Note that EspoCRM's own two-factor authentication does not work with OIDC sign-in, so confirm your identity provider enforces an equivalent second factor. The step is done when a security review confirms each control is set and the admin accounts are inventoried.
Test a change end to end
Use a non-production test user to make a known set of changes: edit an audited field, log in, log out, attempt a failed login and run a delete. Then check that each event appears in the stream, the Audit Log or the auth log, with the correct user and timestamp. Confirm the record still shows after a background cleanup run would be expected to occur, using the cleanup periods you set. The step is done when every test event is found in the expected log and the results are saved as evidence.
Document the owner of each log
Write a short register that names the owner of the action history, the auth log and the audit log, along with who can read them, who can change the cleanup periods and where exports are stored. Include the retention decision from the earlier step and the date of the last successful test. Confirm the owners with your compliance and IT leads, since EspoCRM does not assign them. The step is done when the register is approved and linked from your access and retention procedures.
Which cleanup defaults delete evidence too early
How long does EspoCRM keep action history by default?
By default, EspoCRM cleans up action history after 15 days, controlled by the cleanupActionHistoryPeriod config parameter. Action history is the record of what users did in the instance, so a 15-day window is short for most evidence requests, particularly when an incident or access review surfaces activity weeks after it happened. Before relying on the default, decide how far back your team needs to see actions, then set the period to match that requirement. The setting is documented in the EspoCRM config parameters reference, which is the place to confirm the exact value format for your version.
How long does the EspoCRM auth log survive before cleanup?
The default cleanup period for the auth log is 2 months, set through cleanupAuthLogPeriod. The auth log records logins, so it is the most likely source for answering who accessed the instance and when. A two-month window may not cover a periodic access review or a delayed investigation into a compromised account. Decide the retention period your access review cycle requires, set cleanupAuthLogPeriod to match, and confirm that the value you choose is accepted by your installed version.
Does the EspoCRM audit log expire after three months?
Yes, by default audit log records are cleaned up after 3 months through the cleanupAuditPeriod parameter. Audit log entries come from fields marked as Audited, so the default covers only changes to those fields within that window. Changes to fields you did not mark as Audited never reach the Audit Log at all, which matters as much as the cleanup period. Review your audited field list against the evidence you expect to produce, and raise the cleanup period if the evidence must outlast three months.
How do I change the EspoCRM cleanup period settings?
Each period is a config parameter: cleanupActionHistoryPeriod for action history, cleanupAuthLogPeriod for the auth log and cleanupAuditPeriod for the audit log. You change them in the instance configuration, either through the administration interface if your version exposes the setting there or by editing the configuration file on the server. Confirm the accepted value format in the EspoCRM config parameters documentation, then test the change on a non-production copy. Record each change in your change management system so auditors can see when retention changed.
Do new cleanup periods apply to records that already exist?
Confirm this in your own environment before assuming either way. A new period governs when cleanup runs, so the practical question is whether records older than the new value that still exist will be removed at the next cleanup run or kept. Test this on a copy of your instance: create records with known timestamps, change the period, run the scheduled cleanup job and check what remains. Ask the EspoCRM project or your implementation partner to confirm the behavior for your installed version, and document the result as part of your retention evidence.
Can cleanup remove evidence before a retention rule requires it?
Yes. Each period is a single setting that applies to the whole instance, so a short default can delete evidence that your policy requires you to keep longer. The risk is highest when the policy sets a longer retention for access or change evidence than the 15-day, 2-month or 3-month defaults. Map each evidence type to a retention requirement from your policy, compare it against the shipped period, and extend the period where needed. Also check whether the cleanup job runs reliably, because a job that is disabled or failing can leave data that your policy never intended to keep.
What should I ask the vendor or test before relying on EspoCRM cleanup settings?
Ask or test these points before you rely on the defaults:
- Which cleanup parameters exist in your installed version, and their exact accepted values.
- Whether a period change applies to existing records at the next cleanup run.
- Whether the cleanup job runs on the schedule your server provides, since background jobs depend on cron or a scheduled task.
- Whether backups keep older copies of the evidence after live records are cleaned up, and for how long.
- Whether an exported copy of the audit log can be preserved outside the instance for the full retention period.
Record each answer with the version tested, so the evidence stays accurate after upgrades.
What EspoCRM does not cover for audit evidence
EspoCRM records changes and logins inside the application, but it does not make your evidence program complete on its own. The cards below cover the gaps that sit outside the CRM, in the identity provider, the database and server, and the governance processes that decide who reviews what and for how long.
No certification or audit report from the software
EspoCRM is open-source software, and the audit log is a feature of the application, not a attestation about its controls. An auditor will still ask how the instance was configured, patched and operated, and no product document answers that for you. Ask your auditor which evidence they accept from an application feature and which they expect from your own records, and keep the configuration as it was at each review date.
Retention beyond cleanup needs a process
The default cleanup periods delete action history after 15 days, the auth log after 2 months and audit log records after 3 months. If your policy requires longer retention, EspoCRM will not keep those records for you, so you need an export or archive process that runs before each cleanup job. Confirm the period in your own policy and test that the archive can be read back.
Database and server logs sit outside EspoCRM
Web server access logs, PHP errors, database query logs and operating system login records are written by the platform around EspoCRM. They can show requests that never reached the application log, such as failed requests or direct database changes. Decide where these logs are stored, who can read them, and how long they are kept, and make sure they are collected before the CRM cleanup removes its own records.
Identity provider logs hold SSO sign-ins
When EspoCRM uses OpenID Connect sign-in, the identity provider authenticates the user, so the record of a successful or failed sign-in, MFA challenge and account lock lives in that system. EspoCRM only sees the resulting session. Confirm that your identity provider retains these events long enough for your review cycle, and that its logs can be linked to EspoCRM user accounts by a stable identifier.
Review cadence and access reviews stay with you
Audit records prove what happened, but they do not show that anyone looked at them. Recurring tasks such as reviewing the audit log for sensitive fields, checking which users hold admin roles, and recertifying API users are governance decisions. Assign an owner, set the review frequency in writing, and keep dated sign-offs, since a missing review is a finding even when the logs are complete.
How much effort does audit log configuration take and what does it need from us?
How much effort does configuring EspoCRM audit logging take?
The configuration itself is small: marking fields as Audited and setting cleanup periods are settings changes in the EspoCRM admin area. The effort sits in deciding what to audit, testing that the evidence is complete, and documenting the result. Effort grows with the number of entities, the number of fields in scope and how many teams need to sign off. Ask any partner for a written quote that lists the entities and fields covered, the test cases used to prove the evidence appears, and the documentation delivered. A quote without those items cannot be compared.
What do we need to supply before audit logging work starts?
You need to provide three inputs. First, a field inventory: the entities and fields holding data you must be able to show changes for, such as contract values, account ownership or personal data. Second, a retention policy stating how long action history, auth log and audit log records must be kept. Third, a storage target for exporting or archiving evidence outside EspoCRM, since the default cleanup settings remove records on a schedule. Without these, the configuration cannot be checked against your own requirements.
Can our internal team configure EspoCRM audit logging on its own?
Yes, a team with EspoCRM administration skills can mark fields as Audited and change the cleanup parameters. The harder part is the judgment about which fields and periods are sufficient for your obligations, and proving the result. Internal teams usually need time to review the policy with compliance owners and to test that changes appear in the Audit Log and stream as expected. Decide early who owns the field inventory and who approves retention periods, since those decisions outlast the configuration work.
Does a major EspoCRM upgrade change audit log settings or evidence?
Settings may need review after an upgrade, so plan a re-check as part of each major version change. Audited field settings, cleanup parameters and any custom fields or extensions should be confirmed against the release notes for the target version. Recheck that the Audit Log still records changes on the fields in scope, and keep a copy of pre-upgrade evidence. The EspoCRM upgrade guidance is the starting point for the version you plan to move to, and your test environment should be used before production.
How will an auditor check the audit log evidence?
An auditor will usually ask you to show the rule that defines what is audited, the settings that enforce it, and sample records proving that changes were captured and kept for the stated period. They may also ask how you prevent evidence from being deleted early and who can view it. Prepare a short record of the field list, retention periods, export procedure and access roles. DeployOpen prepares systems, controls and evidence for compliance assessments, but auditors and certification bodies make the assessment decision.
What ongoing work does audit logging need after go-live?
Audit logging needs periodic review. Recurring work includes checking that new fields and entities added by your teams are included in the field inventory, confirming cleanup periods still match policy, testing that evidence exports work, and reviewing access to the logs. These tasks are typically recurring rather than one-time, so ask a partner whether they are included in a support retainer or handled by your team. A quote should separate the initial configuration from these recurring tasks.
What drives the cost of audit log work up or down?
The main drivers are the number of entities and fields in scope, the complexity of your retention requirements, whether evidence must be exported to your own storage, the number of teams and approvers involved, and whether an upgrade is planned in the same period. Fewer fields and a clear retention policy shorten the work. Ask for a quote that states what is included, what is excluded, and which items you must provide, so that cost differences can be traced to scope.
Official EspoCRM and ISO sources to read first
Start with the two primary references that define what this topic can promise: the EspoCRM fields documentation and the EspoCRM config parameters reference. The EspoCRM fields documentation explains how the Audited setting on a field stores its changes in the stream and makes them available in the Audit Log. Check which entity types and field types your instance will actually expose, and confirm whether the behavior matches your version, because you will be relying on that setting to capture every field that matters for your evidence. The EspoCRM config parameters reference lists the cleanup settings that govern how long action history, auth log and audit log records survive. Read the defaults for cleanupActionHistoryPeriod, cleanupAuthLogPeriod and cleanupAuditPeriod with your retention policy beside you, and record the values your instance will run with before any data enters production.
Next, read the ISO/IEC 27001:2022 standard page on the ISO website to understand what an auditor will ask about logging and monitoring. Do not expect the standard to name EspoCRM or any product. Instead, locate the Annex A controls on logging, monitoring and access, and confirm with your compliance lead which of them your CRM evidence will support. The ISO page also states that the standard is the third edition, published in 2022, which tells you the control set your certification body will assess against. Confirm with your certification body which edition and transition rules apply to your organization, since the transition period for the 2013 edition has already closed.
Finally, treat the vendor documentation as a statement of capability, not proof of compliance. Ask your own team to test a sample of changes and logins in a staging instance, export the results and check that the retained records answer the questions an auditor would ask. The ISO document explains what evidence is expected, but only your configured environment shows whether that evidence exists for the period you need.
How DeployOpen works on this
DeployOpen plans, configures and documents EspoCRM audit evidence as part of a self-hosted implementation inside your own infrastructure. We decide which fields, entities and access events must leave a trace, set retention so evidence is not deleted early, and hand over the settings and procedures your team needs to run it.
How we scope
- We list the entities and fields whose changes your auditors or privacy team will ask about.
- We confirm which login, API and action events need evidence and who reviews them.
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts.
How we build
- We mark the agreed fields as Audited and verify changes appear in the stream and Audit Log.
- We set cleanupAuditPeriod, cleanupAuthLogPeriod and cleanupActionHistoryPeriod to match your documented retention policy.
- We test change, login and action records against the scenarios your evidence requirements describe.
How we hand over
- We document which fields are audited, the retention values set, and where each log is read.
- We provide a runbook for exporting audit records before cleanup jobs remove them.
- We confirm with your team which evidence your independent auditor or certification body will accept.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover.
- We review audit settings again when new entities, fields or EspoCRM versions are introduced.
- Ongoing support can cover checking that cleanup periods still match policy after changes.
