Audit Logs & System Monitoring

Relevant source files

The following files were used as context for generating this wiki page:

• api/v2.0/swagger.yaml
• src/controller/event/handler/auditlog/auditlog_test.go
• tests/apitests/python/test_audit_log_forward.py
• src/lib/config/metadata/metadatalist.go
• tests/testcases/Group4-logging/4-03-DB-admin-view-logs.md
• src/portal/src/app/base/project/project-log/audit-log.component.spec.ts

Audit Logs & System Monitoring in Harbor provide a comprehensive mechanism for tracking user activities and system operations. The system captures significant events—such as artifact creation, deletion, pulls, and pushes—and stores them for administrative review and security compliance.

The scope of this system includes local database logging, external syslog forwarding, and specialized monitoring for long-running background tasks like Garbage Collection (GC) and Vulnerability Scanning. It ensures that administrators have full visibility into the lifecycle of OCI artifacts and the security posture of the registry.

Architecture & Data Flow

Harbor utilizes an event-driven architecture to manage audit logs. When a significant action occurs (e.g., creating a project or pushing an image), a metadata event is published to a internal notification framework. Specialized handlers subscribe to these topics to process and persist the logs.

Event Processing Flow

The diagram below illustrates how a project creation event is captured and logged.

Logic & Components

• AuditLog Handler: Listens for system topics like TopicCreateProject and builds audit metadata. Sources: src/controller/event/handler/auditlog/auditlog_test.go:76-80
• Manager Interface: Provides methods for CRUD operations on audit logs, including List, Get, Count, and Create. Sources: src/controller/event/handler/auditlog/auditlog_test.go:34-55
• Forwarding Logic: If configured, logs are sent to a remote syslog endpoint, potentially bypassing the local database to save storage. Sources: tests/apitests/python/test_audit_log_forward.py:58-85

API Implementation & Endpoints

The system provides several RESTful endpoints to query and manage logs at both the system and project levels.

Audit Log Endpoints

Endpoint	Method	Description
/audit-logs	GET	(Deprecated) Get recent logs of projects for admins.
/auditlog-exts	GET	Get detailed audit logs for system admins or project admins.
/auditlog-exts/events	GET	List all supported audit log event types.
/projects/{project_name}/auditlog-exts	GET	Get recent logs specifically for a named project.
/system/purgeaudit	GET/POST	Manage and schedule the purging of old audit logs.
Sources: api/v2.0/swagger.yaml:1385-1490, api/v2.0/swagger.yaml:2620-2750

Data Structures

The core data model for an audit log entry (AuditLogExt) includes the following fields:

• ID: Unique identifier for the log entry.
• Username: The operator who performed the action.
• Resource: The specific resource affected (e.g., repository/image).
• ResourceType: The type of resource (e.g., artifact, project, tag).
• Operation: The action performed (e.g., create, delete, push, pull).
• OperationResult: Boolean indicating success or failure.
• OpTime: Timestamp of the operation.
  Sources: api/v2.0/swagger.yaml:6335-16360

System Configuration & Monitoring

Monitoring and logging behavior can be tuned through system configurations, allowing for high-performance setups and compliance-driven retention.

Monitoring Configurations

Configuration Key	Type	Default	Description
audit_log_forward_endpoint	string	""	Syslog endpoint (e.g., harbor-log:10514).
skip_audit_log_database	bool	false	If true, logs are forwarded but not saved locally.
disabled_audit_log_event_types	string	""	Comma-separated list of events to ignore (e.g., pull_artifact).
metric_enable	bool	false	Enables the Prometheus metrics exporter.
metric_port	string	"9090"	Port for the metrics exporter.
Sources: src/lib/config/metadata/metadatalist.go:175-185, src/lib/config/metadata/metadatalist.go:145-155

Health & Metrics Flow

Harbor components provide health status and performance metrics to ensure the system is operational.

Log Retention & Maintenance

To prevent database bloat, Harbor implements an automated purge mechanism for audit logs.

• Log Purge: Admins can schedule a "Purge Audit" job. This job removes records older than a specified interval (in hours or days).
• Manual Trigger: The /system/purgeaudit endpoint allows for immediate execution of a cleanup task.
• Dry Run: Cleanups can be simulated (dry run) to estimate how many records would be removed without actually deleting data.
  Sources: api/v2.0/swagger.yaml:2620-2760, tests/testcases/Group4-logging/4-03-DB-admin-view-logs.md

Scheduled Purge Parameters

{
  "parameters": {
    "audit_retention_hour": 168,
    "dry_run": true,
    "include_event_types": "create_artifact,delete_artifact"
  },
  "schedule": {
    "type": "Hourly",
    "cron": "0 0 * * * *"
  }
}

Sources: api/v2.0/swagger.yaml:2715-2725

Conclusion

Audit Logs & System Monitoring are vital for maintaining the security and efficiency of the registry. By leveraging internal events, flexible persistence options (Local vs. Syslog), and robust maintenance tools like automated purging, Harbor provides administrators with a reliable audit trail and real-time visibility into system health.