Audit log

The audit log is an append-only record of every action that mutates organizational state or affects access. It is the primary evidence source for SOC 2, ISO 27001, and HIPAA control reviews.

What is recorded

Each row captures who did what, to which target, and from where:

Field	Description
`id`	Unique event ID
`orgId`	Organization scope
`actor`	User ID, API key ID, or `anonymous` for pre-auth events like SSO failures
`action`	Dotted action name (see action catalog below)
`target`	Resource the action affected, e.g. `connection:sso-1`, `user:u-42`, `registry:r-7`
`ip`	Client IP from `X-Forwarded-For`
`createdAt`	UTC timestamp

Example entry

{
  "id": "ae-1745601234-x9k2",
  "orgId": "org-acme",
  "actor": "u-42",
  "action": "vulnerability.triaged",
  "target": "vuln:CVE-2025-12345",
  "ip": "203.0.113.18",
  "createdAt": "2026-04-26T14:21:08.512Z"
}

Action catalog

Action names follow domain.event and are stable across versions. Common categories:

Category	Examples
Authentication	`login.success`, `login.failed`, `login.mfa_required`
Membership	`member.invited`, `member.role_changed`, `member.suspended`, `member.removed`, `member.provisioned`
Teams	`team.created`, `team.updated`, `team.deleted`
API keys	`apikey.created`, `apikey.rotated`, `apikey.revoked`
Settings	`settings.updated`, `settings.sla_policy.updated`, `settings.scim.token_regenerated`
Registries	`registry.added`, `registry.updated`, `registry.removed`
Scans	`scan.triggered`, `scan.uploaded`, `scan.failed`
Vulnerabilities	`vulnerability.triaged`, `vulnerability.status_changed`
Exceptions	`exception.created`, `exception.renewed`, `exception.revoked`, `exception.expired`
Reporting	`report.generated`, `evidencepack.generated`, `evidencepack.downloaded`
SSO	`sso.login.initiated`, `sso.login.success`, `sso.login.failed`, `sso.connection.created`, `sso.connection.updated`, `sso.connection.deleted`, `sso.connection.tested`, `sso.user.provisioned`, `sso.user.linked`, `sso.impersonate.used`
SCIM	`scim.sync_completed`
Audit	`organization.audit_log_exported`

Reading the log

The UI lives at Settings -> Audit log. The same data is available via the API:

curl -H "X-API-Key: $HG_API_KEY" \
  "https://harborguard.co/api/audit-log?page=1&limit=50&action=login.failed&dateFrom=2026-04-01"

Supported filters:

action — exact match (e.g. login.failed)
actor — user ID or anonymous
target — exact resource string
dateFrom, dateTo — ISO 8601 timestamps
search — case-insensitive substring across action, actor, target
sort — one of createdAt, action, actor, with optional :asc or :desc

CSV export

Auditors and Admins can export the filtered set as CSV:

curl -H "X-API-Key: $HG_API_KEY" \
  "https://harborguard.co/api/audit-log/export?dateFrom=2026-01-01&dateTo=2026-03-31" \
  -o q1-audit.csv

Columns: timestamp,actor,action,resource,details,ip. Up to 10,000 rows per export — paginate by date if you need more.

Every export is itself recorded as organization.audit_log_exported with the filters used. This satisfies SOC 2 INF.2 (auditors must be able to see who pulled evidence and when).

Audit events are retained for the lifetime of the organization. They are never edited; once written, the row is immutable. Organization deletion purges audit data 14 days after the soft-delete window closes. Export your evidence before that window expires.

Tamper evidence

The audit table is append-only at the application layer. The Owner can request hash-chained export receipts (each row's SHA-256 includes the prior row's hash) for use as cryptographic evidence; ask support to enable for your tenant.