Saltar al contenido principal

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.

nota

Audit Log access requires Admin or SuperAdmin role. Regular users cannot view audit logs.

Accessing the Audit Log​

  1. Navigate to Settings → Audit Log (or app.plexicus.ai/settings#audit-log)
  2. You will see a paginated list of events, newest first

Understanding Audit Events​

The audit log records the following categories of actions:

CategoryExamples
User EventsUser login, password change, 2FA setup, passkey registration, role assignment
Client EventsOrganization name change, subscription tier update, feature flag toggles (Fix Verification, Autonomous Scan, etc.)
Repository EventsRepository added/removed, branch scanned, scan configuration changed, webhook triggered
Finding EventsFinding created, severity updated, marked as false positive, assigned to team member, remediation requested
Refused attemptsA 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:

StatusMeaning
401Authentication failed
403The caller's role does not allow the action
429The 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 .failed suffix. For example, a user without permission to add repositories who tries anyway leaves a repository.created.failed entry.
  • request.denied — the refused operation has no audit action of its own. The entry's Resource Type is taken from the request path (for example findings), 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_type is 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.

  1. 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.
  2. Click Export CSV or Export JSON. The file downloads as audit-log-<UTC timestamp>.csv or .json.
  3. A notification confirms the download: Export ready — N records.

CSV or JSON​

FormatBest forShape
CSVSpreadsheets and reviewersOne 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.
JSONSIEM ingestion and scriptsAn 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).
nota

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:

HeaderValue
X-Export-Truncatedtrue when the filters matched more than 10,000 records, otherwise false
X-Export-RowsNumber 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
  • format is csv (default) or json.
  • 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-Truncated in headers.txt to 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 with previous_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:

  1. 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.
  2. Read the result in the Hash-chain integrity panel:
FieldMeaning
Chain intact / Chain brokenThe verdict. Chain intact means every chained record passed both checks. Chain broken means at least one did not.
Verified recordsRecords that passed both checks, out of all chained records (for example 5432 / 5432).
Tampered recordsRecords whose stored hash or link failed. Any value above 0 makes the chain broken.
Written before chainingRecords written before hash chaining was introduced. They have no hashes, so they are not verified and do not affect the verdict.
Chain coversThe time span from the first to the most recent chained record.
First breakShown only when the chain is broken: the time of the earliest failing record.
RecordThe ID and action of that earliest failing record.
Failed checksWhich 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.

aviso

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 remediation and .failed events 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