Audit Log
The Audit Log is a comprehensive, tamper-proof record of all actions taken in your Plexicus account. Each entry is cryptographically signed using SHA-256 hash chaining, providing chain-of-custody evidence for compliance audits and security investigations. You can export the trail as CSV or JSON and verify the integrity of the chain from the same page.
Audit Log access requires Admin or SuperAdmin role. Regular users cannot view audit logs.
Accessing the Audit Log
- Navigate to Settings → Audit Log (or
app.plexicus.ai/settings#audit-log) - You will see a paginated list of events, newest first
Understanding Audit Events
The audit log records the following categories of actions:
| Category | Examples |
|---|---|
| User Events | User login, password change, 2FA setup, passkey registration, role assignment |
| Client Events | Organization name change, subscription tier update, feature flag toggles (Fix Verification, Autonomous Scan, etc.) |
| Repository Events | Repository added/removed, branch scanned, scan configuration changed, webhook triggered |
| Finding Events | Finding created, severity updated, marked as false positive, assigned to team member, remediation requested |
| Refused attempts | A change that was rejected because the caller was not authenticated, not allowed, or rate-limited — see Refused attempts |
Each event record includes:
- Timestamp — ISO-8601 UTC timestamp when the action occurred
- Actor — User ID and email of who performed the action
- Action — The specific operation (e.g.,
role.created,repository.deleted) - Resource Type — The entity affected (e.g., "finding", "repository", "user")
- Resource ID — The specific ID of the affected entity
- Previous Hash — Cryptographic link to the prior entry (enables tamper detection)
- Entry Hash — SHA-256 signature of this record (used to verify integrity)
Refused attempts
A change that Plexicus refuses is recorded too, so the trail shows who tried to do something, not only who succeeded. When a request that changes data (POST, PUT, PATCH or DELETE) is rejected with one of these statuses, an entry is written:
| Status | Meaning |
|---|---|
401 | Authentication failed |
403 | The caller's role does not allow the action |
429 | The caller was rate-limited (a possible brute-force signal) |
The entry's Action tells you what was attempted:
<action>.failed— the operation has its own audit action, and the attempt is recorded under that name with a.failedsuffix. For example, a user without permission to add repositories who tries anyway leaves arepository.created.failedentry.request.denied— the refused operation has no audit action of its own. The entry's Resource Type is taken from the request path (for examplefindings), and its metadata records the HTTP status, the refusal reason, the method and the path.
Each refused attempt is recorded once, attributed to the user and organization of the token that made it. A request with no token, or with a token that cannot be read (for example an expired one), cannot be attributed to your organization, so it does not appear in your audit log.
Refused attempts appear in the table alongside successful actions. To list only them, call the list or export endpoint with action_type=failed or action_type=request.denied; the API's action_type filter matches partially.
Filtering and Searching
Use the filter controls to narrow results:
By Time Range
- Select a Date range to view events in a specific period
- Useful for incident response ("What changed between 3pm and 5pm?")
By Actor
- Actor ID: Exact match on user ID (API only)
- Actor email: Case-insensitive partial match on email address
- Example: Filter by "alice@company.com" to see all changes made by that user
By Action
- Action Type: In the app, pick a common action from the list. Through the API,
action_typeis a case-insensitive partial match on the action string - API examples: "role", "remediation", "failed" to find related events
- Useful for compliance ("Show all role changes in Q2")
By Resource
- Resource Type: Exact match (e.g., "finding", "repository", "user")
- Resource ID: Exact match on the entity's ID (API only)
- Example: Filter by resource_type="finding" and resource_id="CVE-2024-1234" to track a specific vulnerability
Pagination
- Results are cursor-based (not offset-based) to ensure consistency
- Default limit: 50 records per page (max 200)
- Navigate using Next and Previous buttons
Exporting the Audit Log
Download the audit trail as a file for offline review, evidence packs or ingestion into a SIEM.
- In Settings → Audit Log, set the filters you want (date range, actor email, action type, resource type). The export contains exactly what the filters match — the same records the table shows, not only the current page.
- Click Export CSV or Export JSON. The file downloads as
audit-log-<UTC timestamp>.csvor.json. - A notification confirms the download: Export ready — N records.
CSV or JSON
| Format | Best for | Shape |
|---|---|---|
| CSV | Spreadsheets and reviewers | One row per entry with the columns id, timestamp, actor_email, user_id, actor_type, action, resource_type, resource_id, resource_name, ip_address, metadata (as JSON), previous_hash, entry_hash. UTF-8 with a byte-order mark, so Excel shows non-ASCII emails correctly. |
| JSON | SIEM ingestion and scripts | An object with exported_at, filters (the filters that were applied), count, truncated and records (the same fields as the CSV columns, with metadata as an object). |
To keep a CSV export safe to open in a spreadsheet, any cell that starts with =, +, -, @, a tab or a carriage return is prefixed with a single quote ('), so it is shown as text instead of being evaluated as a formula. Remove that quote if you compare such a value with the original record.
The 10,000-record limit
One export holds at most 10,000 records. When your filters match more, the file contains the newest 10,000 and the notification adds: The filter matched more records than one file holds. This download has the newest 10,000. To get the older records, narrow the Date range and export again, period by period.
Programmatic exports report the same thing in response headers:
| Header | Value |
|---|---|
X-Export-Truncated | true when the filters matched more than 10,000 records, otherwise false |
X-Export-Rows | Number of records in the file |
A JSON export also carries "truncated": true in the file itself.
Exports are audited
Every export is itself recorded in the audit log, as audit.export_csv or audit.export_json. The entry's metadata holds the format, the number of records exported, the number the filters matched, whether the file was truncated, and the filters used, so you can always tell who took a copy of the trail, and what it contained.
Re-verifying an exported file
Each exported record keeps its previous_hash and entry_hash, so the file stays tied to the hash chain after it leaves Plexicus. Records are ordered newest first. In an export without filters, each record's previous_hash equals the entry_hash of the record on the next line (the one just before it in time). A record removed from, or inserted into, the file breaks that link. A filtered export skips the records that did not match, so compare its hashes with the live trail instead.
Exporting through the API
curl -G "https://api.app.plexicus.ai/audit-logs/export" \
-H "Authorization: Bearer $TOKEN" \
--data-urlencode "format=csv" \
--data-urlencode "from_date=2026-07-01T00:00:00Z" \
--data-urlencode "to_date=2026-07-31T23:59:59Z" \
-D headers.txt -o audit-log.csv
formatiscsv(default) orjson.- It accepts the same filters as the list endpoint:
from_date,to_date,actor_id,actor_email,action_type,resource_type,resource_id. - It needs the same permission as reading the audit log (
audit-logs:read). - Check
X-Export-Truncatedinheaders.txtto know whether the file is complete.
Integrity Verification
Plexicus uses SHA-256 hash chaining to prevent audit log tampering. Each entry contains:
previous_hash: The entry hash of the immediately preceding record (64 zeros for the first record in the chain)entry_hash: SHA-256 of the record's content combined withprevious_hash
If anyone later modifies or deletes an entry, the hashes and links from that point on no longer match.
Verifying the Hash Chain
To verify your audit log has not been tampered with:
- In Settings → Audit Log, click Verify integrity. Plexicus recomputes every hash from oldest to newest and checks that each entry links to the one before it.
- Read the result in the Hash-chain integrity panel:
| Field | Meaning |
|---|---|
| Chain intact / Chain broken | The verdict. Chain intact means every chained record passed both checks. Chain broken means at least one did not. |
| Verified records | Records that passed both checks, out of all chained records (for example 5432 / 5432). |
| Tampered records | Records whose stored hash or link failed. Any value above 0 makes the chain broken. |
| Written before chaining | Records written before hash chaining was introduced. They have no hashes, so they are not verified and do not affect the verdict. |
| Chain covers | The time span from the first to the most recent chained record. |
| First break | Shown only when the chain is broken: the time of the earliest failing record. |
| Record | The ID and action of that earliest failing record. |
| Failed checks | Which check failed for it: Stored hash does not match the record (its content was changed after it was written), Link to the previous entry is broken (a record before it was removed, inserted or altered), or both. |
Verification continues past the first break, so Tampered records counts every failing record, while First break points to where to start the investigation.
The Verify integrity button needs the audit-logs:verify permission. Admins have it by default; see Roles and RBAC for custom roles.
Verifying through the API
For automated compliance workflows:
curl -X GET "https://api.app.plexicus.ai/audit-logs/integrity-verification" \
-H "Authorization: Bearer $TOKEN"
Response example:
{
"valid": true,
"total_records": 5432,
"verified_records": 5432,
"tampered_records": 0,
"first_break": null,
"chain_started_at": "2026-03-04T09:12:44Z",
"chain_ends_at": "2026-07-02T20:15:00Z",
"pre_chain_records": 0
}
When valid is false, first_break describes the earliest failing record:
"first_break": {
"record_id": "665f1c2e9b1d4a0012ab34cd",
"timestamp": "2026-06-18T14:03:27Z",
"action": "role.assigned",
"linkage_broken": false,
"hash_mismatch": true
}
hash_mismatch corresponds to Stored hash does not match the record, and linkage_broken to Link to the previous entry is broken.
The hash chain only protects records written after hash chaining was introduced in your Plexicus deployment. Older records appear in pre_chain_records (Written before chaining) and are excluded from the integrity verdict.
Compliance Use Cases
SOC 2 Type II
Demonstrate user access controls and change tracking by exporting audit logs filtered by date range and action type. The hash chain proves the records have not been modified, and refused attempts show that access controls were enforced.
GDPR Data Subject Access Requests (DSAR)
Filter by actor email to show all actions taken by a specific user, then export the result. Useful for privacy audits.
Incident Response
Filter by time range and action type to reconstruct the timeline of a security incident, including refused attempts.
- Example: "Show all
remediationand.failedevents between 2026-07-01 12:00:00Z and 2026-07-01 14:00:00Z"
Compliance Audits (ISO 27001, FedRAMP, etc.)
The SHA-256 hash chain provides chain-of-custody evidence that audit logs are authentic and unmodified. Run Verify integrity before you export, and keep the result with the exported file.
Retention and Limits
- Data retention: Audit logs are retained per your plan's retention policy (typically 1–7 years)
- Query limits: Maximum 200 records per request; use pagination for larger datasets
- Export limits: Maximum 10,000 records per export; narrow the date range to export older records
Related Pages
- Two-Factor Authentication — MFA events appear in audit log
- Roles and RBAC — Role changes appear in audit log
- Domain Verification — Domain verification events appear in audit log