From 28f520768d476d67679ebcddecb8b5ab3ccdbe6c Mon Sep 17 00:00:00 2001 From: adela Date: Tue, 30 Dec 2025 11:47:26 +0800 Subject: [PATCH 1/5] update audit log --- docs/security/audit-log.mdx | 215 ++++++++++++++++++++++++------------ 1 file changed, 144 insertions(+), 71 deletions(-) diff --git a/docs/security/audit-log.mdx b/docs/security/audit-log.mdx index 1edd95ab..e11dd4bc 100644 --- a/docs/security/audit-log.mdx +++ b/docs/security/audit-log.mdx @@ -2,119 +2,192 @@ title: Audit Log --- -**Workspace Admin** or **DBA** can view the audit logs of the workspace. +Audit logging tracks all configuration changes and data operations within your Bytebase workspace. These logs help you identify who performed what action, when it occurred, and what resources were affected. This enables compliance monitoring, security analysis, and troubleshooting. -![overview](/content/docs/security/audit-log/overview.webp) + +Audit logging is available only for **Pro** and **Enterprise** plans. + -## Filter audit logs +For a complete list of logged events, see the [Events Reference](#events-reference) section at the end of this document. -You can filter the audit logs by different conditions. +### Log Structure -![filter](/content/docs/security/audit-log/filter.webp) +Each audit log entry contains the following fields: -You can also specify a time range. +| Field | Description | +|-------|-------------| +| `time` | Timestamp when the event occurred (ISO 8601 format) | +| `level` | Log severity level (INFO, WARNING, ERROR) | +| `method` | API method or action performed | +| `resource` | Target resource (e.g., projects/project-sample) | +| `user` | User who performed the action | +| `latency_ms` | Request processing time in milliseconds | +| `client_ip` | IP address and port of the client | +| `user_agent` | Browser or API client information | +| `parent` | Parent resource context (for nested resources) | +| `severity` | Event severity classification | -![filter-date](/content/docs/security/audit-log/filter-date.webp) +Example log entry: -## Export audit logs +```json +{ + "time": "2025-12-10T15:55:21.729Z", + "level": "INFO", + "source": "v1/audit.go:274", + "msg": "/bytebase.v1.ProjectService/SetIamPolicy", + "log_type": "audit", + "parent": "projects/project-sample", + "method": "/bytebase.v1.ProjectService/SetIamPolicy", + "resource": "projects/project-sample", + "user": "users/101", + "latency_ms": 7, + "client_ip": "192.168.65.1:51907", + "user_agent": "Mozilla/5.0...", + "severity": "INFO" +} +``` - +## Accessing Audit Logs -If you want to export the audit logs to an external system such as S3, refer [Audit Log API](/integrations/api/audit-log/). +### GUI - +**Workspace Admin** or **DBA** can access audit logs through the Bytebase console: + +1. Navigate to the **Settings** page +2. Select **Audit Log** from the sidebar +3. View the chronological list of all audit events + +![overview](/content/docs/security/audit-log/overview.webp) -You can also export the audit logs. +You can filter audit logs by: +- User +- Action type +- Resource +- Time range + +![filter](/content/docs/security/audit-log/filter.webp) ![filter-date](/content/docs/security/audit-log/filter-date.webp) -## Stream audit logs to external systems +### API -Bytebase can stream audit logs to **stdout** for collection by external logging and monitoring systems. +Use the Bytebase API to programmatically access audit logs for integration with external systems and automated monitoring. -### Configuration + +For detailed API documentation and examples, see [Audit Log API](/integrations/api/audit-log/). + -1. Navigate to **Settings** → **General** → **Audit Log Export**. -2. Enable **Enable audit logging to stdout**. +### Streaming -Once enabled, audit events stream to the standard output of your Bytebase service. +Stream audit logs to external logging and monitoring systems for centralized management. It supports JSON format output in addition to the default text format. -### Output format +1. Navigate to **Settings** → **General** → **Audit Log Export** +1. Enable **Enable audit logging to stdout** +1. Save the configuration -By default, audit logs are output as key-value pairs. To enable JSON format for easier parsing by log aggregators, start Bytebase with one of these flags: +Once enabled, all audit events stream to stdout of your Bytebase service. -- `--enable-json-logging` - Outputs all logs in JSON format (you still need to enable the audit log export in the settings) +To enable **JSON format output**, start Bytebase with the `--enable-json-logging` flag: -**Docker example with JSON format:** ```bash docker run --rm --init \ --name bytebase \ --publish 8080:8080 --pull always \ --volume ~/.bytebase/data:/var/opt/bytebase \ bytebase/bytebase:latest \ - --port 8080 --data /var/opt/bytebase --enable-json-logging + --enable-json-logging ``` - -While using the `--enable-json-logging` flag, you need to specify the port and data directory. - +It supports **SIEM Platforms** (e.g., Splunk, Datadog, Elastic Security), **Log Aggregators** (e.g., Fluentd, Logstash, Grafana Loki) and **Cloud Services** (e.g., AWS CloudWatch, Google Cloud Logging, Azure Monitor, New Relic Logs). -### Example output +## Retention -**Default format (key-value pairs):** -``` -time=2025-12-10T15:55:21.729Z level=INFO source=v1/audit.go:274 -msg=/bytebase.v1.ProjectService/SetIamPolicy log_type=audit -parent=projects/project-sample method=/bytebase.v1.ProjectService/SetIamPolicy -resource=projects/project-sample user=users/101 latency_ms=7 -client_ip=192.168.65.1:51907 user_agent="Mozilla/5.0..." severity=INFO -``` + +Bytebase does not automatically purge audit logs. You must implement periodic cleanup to prevent disk space exhaustion, which can cause Bytebase to crash. + -**With JSON format enabled:** -```json -{ - "time": "2025-12-10T15:55:21.729Z", - "level": "INFO", - "source": "v1/audit.go:274", - "msg": "/bytebase.v1.ProjectService/SetIamPolicy", - "log_type": "audit", - "parent": "projects/project-sample", - "method": "/bytebase.v1.ProjectService/SetIamPolicy", - "resource": "projects/project-sample", - "user": "users/101", - "latency_ms": 7, - "client_ip": "192.168.65.1:51907", - "user_agent": "Mozilla/5.0...", - "severity": "INFO" -} -``` +Audit logs are stored in the `audit_log` table in the Bytebase metadata database. -### Integration +You can manually delete old logs from the `audit_log` table or set up a scheduled job (e.g., using pg_cron or system cron) to automatically purge logs periodically. -When running Bytebase in Docker or Kubernetes, audit logs automatically appear in container logs and can be collected by your existing logging infrastructure: +## Events Reference -- **Docker**: Access via `docker logs` or configure Docker logging drivers -- **Kubernetes**: Collected by cluster logging systems (Fluentd, Fluent Bit) -- **Cloud platforms**: Stream to CloudWatch (AWS), Cloud Logging (GCP), or Azure Monitor +Bytebase logs the following event categories: -### Supported systems +### Authentication & Authorization -The stdout logs can be ingested by any log collection system, including: +- User login/logout (Login, Logout) +- API token operations +- IAM policy changes +- Role assignments (CreateRole, UpdateRole, DeleteRole) -- **SIEM platforms**: Splunk, Datadog, Elastic, Sumo Logic, Panther -- **Log aggregators**: Fluentd, Logstash, Vector, Loki -- **Cloud logging**: AWS CloudWatch, GCP Logging, Azure Monitor +### Database Operations -## Retention +- Schema migrations +- Data changes (DML operations) +- Database creation/deletion/updates +- Database transfers between projects +- SQL query executions +- Database catalog modifications -Bytebase does not purge the audit logs. If you want to purge the audit logs, please locate the -`audit_log` table in the metadata database and delete manually. +### Project Management -![audit-log-table](/content/docs/security/audit-log/audit-log-table.webp) +- Project creation/updates/deletion +- Project IAM policy updates +- Database group management -```sql +### Issue & Change Management -DELETE FROM public.audit_log -WHERE created_ts < EXTRACT(EPOCH FROM NOW() - INTERVAL '3 months'); +- Issue creation/updates/approvals +- Rollout plan executions +- Task runs and approvals -``` +### Instance Management + +- Instance creation/updates/deletion +- Instance connection operations +- Data source management +- Sync operations + +### Configuration & Settings + +- Workspace settings changes +- Organization policy updates +- SSO/IDP configurations +- Setting updates + +### Access Control + +- Permission grants/revokes +- Group membership changes (CreateGroup, UpdateGroup, DeleteGroup) +- User management operations + +### Data Security + +- Data masking rule changes +- Access control policy updates +- Sensitive data access (via SQL queries) + +## Limitations + +### Events Not Logged + +The following activities are not logged: + +- Most read-only operations (Get, List, Search methods - viewing data, browsing schemas) +- System health checks and monitoring probes (/actuator endpoints) +- Internal background jobs and maintenance tasks +- WebSocket connections and real-time events + +### Privacy and Security Considerations + +- **Query results excluded:** Actual row data from queries is redacted in audit logs +- **Sensitive data masking:** Passwords, API keys, SSL certificates, SSH keys, and other secrets are automatically replaced with masked values +- **Response truncation:** Large response payloads may be omitted + +### Technical Limitations + +- **Log generation:** Audit logs are generated synchronously during request processing +- **Pagination limit:** Maximum 5000 audit log entries can be retrieved per API call +- **Filter complexity:** Audit log searches must use valid CEL expressions +- **Storage:** Audit logs are stored in the meta database and follow its retention policies \ No newline at end of file From 45c4e547a300b4855687e5683bae67961843f39d Mon Sep 17 00:00:00 2001 From: Adela Date: Tue, 30 Dec 2025 12:00:50 +0800 Subject: [PATCH 2/5] Update docs/security/audit-log.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/security/audit-log.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/security/audit-log.mdx b/docs/security/audit-log.mdx index e11dd4bc..a2bde629 100644 --- a/docs/security/audit-log.mdx +++ b/docs/security/audit-log.mdx @@ -108,7 +108,7 @@ Bytebase does not automatically purge audit logs. You must implement periodic cl Audit logs are stored in the `audit_log` table in the Bytebase metadata database. -You can manually delete old logs from the `audit_log` table or set up a scheduled job (e.g., using pg_cron or system cron) to automatically purge logs periodically. +You can manually delete old logs from the `audit_log` table or set up a scheduled job (e.g., using pg_cron or system cron) to automatically purge logs periodically. As a general best practice, many organizations retain audit logs for **at least 90 days**, and often **6–12 months** in environments with stricter compliance or investigation requirements. When choosing a retention period, balance your regulatory and security needs against available storage capacity and consider exporting logs to external log management or SIEM systems for longer-term retention. ## Events Reference From 49c4fd1c86fb1db542ff22d2b82709f37b61ef26 Mon Sep 17 00:00:00 2001 From: adela Date: Wed, 31 Dec 2025 16:03:25 +0800 Subject: [PATCH 3/5] update --- docs/security/audit-log.mdx | 236 +++++++++++++++++++++--------------- 1 file changed, 141 insertions(+), 95 deletions(-) diff --git a/docs/security/audit-log.mdx b/docs/security/audit-log.mdx index a2bde629..c603c2cb 100644 --- a/docs/security/audit-log.mdx +++ b/docs/security/audit-log.mdx @@ -10,40 +10,23 @@ Audit logging is available only for **Pro** and **Enterprise** plans. For a complete list of logged events, see the [Events Reference](#events-reference) section at the end of this document. -### Log Structure - -Each audit log entry contains the following fields: - -| Field | Description | -|-------|-------------| -| `time` | Timestamp when the event occurred (ISO 8601 format) | -| `level` | Log severity level (INFO, WARNING, ERROR) | -| `method` | API method or action performed | -| `resource` | Target resource (e.g., projects/project-sample) | -| `user` | User who performed the action | -| `latency_ms` | Request processing time in milliseconds | -| `client_ip` | IP address and port of the client | -| `user_agent` | Browser or API client information | -| `parent` | Parent resource context (for nested resources) | -| `severity` | Event severity classification | - -Example log entry: +## Example Log Entry ```json { - "time": "2025-12-10T15:55:21.729Z", - "level": "INFO", - "source": "v1/audit.go:274", - "msg": "/bytebase.v1.ProjectService/SetIamPolicy", - "log_type": "audit", - "parent": "projects/project-sample", - "method": "/bytebase.v1.ProjectService/SetIamPolicy", - "resource": "projects/project-sample", - "user": "users/101", - "latency_ms": 7, - "client_ip": "192.168.65.1:51907", - "user_agent": "Mozilla/5.0...", - "severity": "INFO" + "parent": "projects/sample-project", + "method": "/bytebase.v1.SQLService/Query", + "resource": "instances/prod-postgres/databases/mydb", + "user": "users/developer@example.com", + "severity": "INFO", + "request": "{\"name\":\"instances/prod-postgres/databases/mydb\",\"statement\":\"SELECT * FROM users LIMIT 10\",\"limit\":100}", + "response": "{\"results\":[{\"columnNames\":[\"id\",\"name\"],\"columnTypeNames\":[\"int4\",\"text\"],\"rowsCount\":10}]}", + "status": {"code": 0}, + "latency": {"seconds": 0, "nanos": 125000000}, + "requestMetadata": { + "callerIp": "192.168.1.100", + "callerSuppliedUserAgent": "Mozilla/5.0 Chrome/120.0" + } } ``` @@ -110,75 +93,138 @@ Audit logs are stored in the `audit_log` table in the Bytebase metadata database You can manually delete old logs from the `audit_log` table or set up a scheduled job (e.g., using pg_cron or system cron) to automatically purge logs periodically. As a general best practice, many organizations retain audit logs for **at least 90 days**, and often **6–12 months** in environments with stricter compliance or investigation requirements. When choosing a retention period, balance your regulatory and security needs against available storage capacity and consider exporting logs to external log management or SIEM systems for longer-term retention. -## Events Reference - -Bytebase logs the following event categories: - -### Authentication & Authorization - -- User login/logout (Login, Logout) -- API token operations -- IAM policy changes -- Role assignments (CreateRole, UpdateRole, DeleteRole) - -### Database Operations - -- Schema migrations -- Data changes (DML operations) -- Database creation/deletion/updates -- Database transfers between projects -- SQL query executions -- Database catalog modifications - -### Project Management - -- Project creation/updates/deletion -- Project IAM policy updates -- Database group management - -### Issue & Change Management - -- Issue creation/updates/approvals -- Rollout plan executions -- Task runs and approvals - -### Instance Management - -- Instance creation/updates/deletion -- Instance connection operations -- Data source management -- Sync operations - -### Configuration & Settings - -- Workspace settings changes -- Organization policy updates -- SSO/IDP configurations -- Setting updates - -### Access Control - -- Permission grants/revokes -- Group membership changes (CreateGroup, UpdateGroup, DeleteGroup) -- User management operations +## Log Structure + +### Payload Structure (JSON) + +Each audit log entry contains a JSON payload with the following fields: + +| Field | Type | Description | +|-------|------|-------------| +| `parent` | string | Scope of the audit log. Format: `projects/{project}` or `workspaces/{workspace}` | +| `method` | string | Full API method name. Example: `/bytebase.v1.SQLService/Query` | +| `resource` | string | The primary resource being acted upon. Context-dependent based on operation type | +| `user` | string | User who performed the action. Format: `users/{email}` | +| `severity` | string | Log severity level (see Severity Levels table) | +| `request` | string | JSON-serialized request payload (sensitive fields redacted) | +| `response` | string | JSON-serialized response payload (sensitive fields redacted) | +| `status` | object | gRPC status with `code` and `message` fields | +| `latency` | object | Operation duration with `seconds` and `nanos` fields | +| `serviceData` | object | Service-specific metadata (e.g., IAM policy changes) | +| `requestMetadata` | object | Client information (see below) | + +### RequestMetadata Structure + +| Field | Type | Description | +|-------|------|-------------| +| `callerIp` | string | Client IP address (extracted from X-Real-IP, X-Forwarded-For, or peer address) | +| `callerSuppliedUserAgent` | string | User-Agent header value | + +### Severity Levels + +| Level | Value | Description | +|-------|-------|-------------| +| `SEVERITY_UNSPECIFIED` | 0 | Unspecified | +| `DEBUG` | 1 | Debug-level information | +| `INFO` | 2 | Informational messages (default for all audit logs) | +| `NOTICE` | 3 | Notable events | +| `WARNING` | 4 | Warning conditions | +| `ERROR` | 5 | Error conditions | +| `CRITICAL` | 6 | Critical conditions | +| `ALERT` | 7 | Action must be taken immediately | +| `EMERGENCY` | 8 | System is unusable | + +### Status Codes + +Status codes follow gRPC conventions: +| Code | Name | Description | +|------|------|-------------| +| 0 | OK | Success | +| 1 | CANCELED | Operation canceled | +| 2 | UNKNOWN | Unknown error | +| 3 | INVALID_ARGUMENT | Invalid input | +| 5 | NOT_FOUND | Resource not found | +| 7 | PERMISSION_DENIED | Insufficient permissions | +| 13 | INTERNAL | Internal server error | +| 16 | UNAUTHENTICATED | Authentication required | + +## Audited Events + +| Module | Event Name | Method | Description | Resource Field | Notes | +|--------|------------|--------|-------------|----------------|-------| +| **Authentication** | User Login | `/bytebase.v1.AuthService/Login` | User authentication (password, SSO, MFA) | User email | Sensitive fields redacted: `password`, `otpCode`, `recoveryCode`, `mfaTempToken`, `idpContext`. MFA phase logs extract user email from MFA temp token when email is not in request. | +| | User Logout | `/bytebase.v1.AuthService/Logout` | User session termination | - | | +| | Token Exchange | `/bytebase.v1.AuthService/ExchangeToken` | Workload Identity token exchange (CI/CD) | - | Used for CI/CD pipelines with external OIDC tokens. | +| **User Management** | Create User | `/bytebase.v1.UserService/CreateUser` | Create new user account | User name | User responses redacted to only include: `name`, `email`, `title`, `userType`. | +| | Update User | `/bytebase.v1.UserService/UpdateUser` | Modify user settings, MFA, profile | User name | User responses redacted to only include: `name`, `email`, `title`, `userType`. | +| | Delete User | `/bytebase.v1.UserService/DeleteUser` | Soft-delete user account | - | | +| | Restore User | `/bytebase.v1.UserService/UndeleteUser` | Restore deleted user | - | | +| | Update Email | `/bytebase.v1.UserService/UpdateEmail` | Change user email address | - | | +| **Group Management** | Create Group | `/bytebase.v1.GroupService/CreateGroup` | Create user group | - | | +| | Update Group | `/bytebase.v1.GroupService/UpdateGroup` | Modify group membership/settings | - | | +| | Delete Group | `/bytebase.v1.GroupService/DeleteGroup` | Delete user group | - | | +| **Role Management** | Create Role | `/bytebase.v1.RoleService/CreateRole` | Create custom role | - | | +| | Update Role | `/bytebase.v1.RoleService/UpdateRole` | Modify role permissions | - | | +| | Delete Role | `/bytebase.v1.RoleService/DeleteRole` | Delete custom role | - | | +| **Identity Provider (SSO)** | Create Identity Provider | `/bytebase.v1.IdentityProviderService/CreateIdentityProvider` | Configure new SSO provider | - | | +| | Update Identity Provider | `/bytebase.v1.IdentityProviderService/UpdateIdentityProvider` | Modify SSO configuration | - | | +| | Delete Identity Provider | `/bytebase.v1.IdentityProviderService/DeleteIdentityProvider` | Remove SSO provider | - | | +| **Project Management** | Delete Project | `/bytebase.v1.ProjectService/DeleteProject` | Soft-delete project | - | | +| | Restore Project | `/bytebase.v1.ProjectService/UndeleteProject` | Restore deleted project | - | | +| | Batch Delete Projects | `/bytebase.v1.ProjectService/BatchDeleteProjects` | Delete multiple projects | - | | +| | Set Project IAM Policy | `/bytebase.v1.ProjectService/SetIamPolicy` | Modify project member permissions | Resource name | Includes `serviceData` with `PolicyDelta` showing added/removed bindings. | +| **Workspace IAM** | Set Workspace IAM Policy | `/bytebase.v1.WorkspaceService/SetIamPolicy` | Modify workspace-level permissions | Resource name | Includes `serviceData` with `PolicyDelta` showing added/removed bindings. | +| **Instance Management** | Create Instance | `/bytebase.v1.InstanceService/CreateInstance` | Register new database instance | Instance name | DataSource sensitive fields redacted: `password`, `sslCa`, `sslCert`, `sslKey`, `sshPassword`, `sshPrivateKey`, `authenticationPrivateKey`, `externalSecret`, `saslConfig.krbConfig.keytab`, `masterPassword`. | +| | Update Instance | `/bytebase.v1.InstanceService/UpdateInstance` | Modify instance configuration | Instance name | DataSource sensitive fields redacted (same as above). | +| | Delete Instance | `/bytebase.v1.InstanceService/DeleteInstance` | Soft-delete instance | Instance name | | +| | Restore Instance | `/bytebase.v1.InstanceService/UndeleteInstance` | Restore deleted instance | Instance name | | +| | Batch Update Instances | `/bytebase.v1.InstanceService/BatchUpdateInstances` | Bulk update instances | - | | +| | Add Data Source | `/bytebase.v1.InstanceService/AddDataSource` | Add connection to instance | Instance name | DataSource sensitive fields redacted. | +| | Update Data Source | `/bytebase.v1.InstanceService/UpdateDataSource` | Modify connection settings | Instance name | DataSource sensitive fields redacted. | +| | Remove Data Source | `/bytebase.v1.InstanceService/RemoveDataSource` | Remove connection | Instance name | | +| **Database Management** | Update Database | `/bytebase.v1.DatabaseService/UpdateDatabase` | Modify database settings/labels | Database name | | +| | Batch Update Databases | `/bytebase.v1.DatabaseService/BatchUpdateDatabases` | Bulk update databases | Parent | | +| **Database Catalog** | Update Database Catalog | `/bytebase.v1.DatabaseCatalogService/UpdateDatabaseCatalog` | Modify schema catalog/classification | Catalog name | | +| **Database Groups** | Create Database Group | `/bytebase.v1.DatabaseGroupService/CreateDatabaseGroup` | Create logical database group | - | | +| | Update Database Group | `/bytebase.v1.DatabaseGroupService/UpdateDatabaseGroup` | Modify database group | - | | +| | Delete Database Group | `/bytebase.v1.DatabaseGroupService/DeleteDatabaseGroup` | Delete database group | - | | +| **SQL Operations** | Execute Query | `/bytebase.v1.SQLService/Query` | Execute read-only SQL query | Database name | Response rows completely redacted - only metadata captured: `columnNames`, `columnTypeNames`, `rowsCount`, `error`, `latency`, `statement`. Masking reason icons stripped. | +| | Admin Execute | `/bytebase.v1.SQLService/AdminExecute` | Execute SQL with admin privileges (streaming) | Database name | Response rows completely redacted. Each request/response pair in the stream generates a separate audit log. | +| | Export Data | `/bytebase.v1.SQLService/Export` | Export query results to file | Database/rollout name | Request `password` field redacted. Response `content` not logged (too large). | +| **Issue Management** | Create Issue | `/bytebase.v1.IssueService/CreateIssue` | Create change request | - | | +| | Update Issue | `/bytebase.v1.IssueService/UpdateIssue` | Modify issue details | - | | +| | Create Issue Comment | `/bytebase.v1.IssueService/CreateIssueComment` | Add comment to issue | - | | +| | Update Issue Comment | `/bytebase.v1.IssueService/UpdateIssueComment` | Modify issue comment | - | | +| | Batch Update Issues Status | `/bytebase.v1.IssueService/BatchUpdateIssuesStatus` | Bulk status change | - | | +| | Approve Issue | `/bytebase.v1.IssueService/ApproveIssue` | Approve change request | - | | +| | Reject Issue | `/bytebase.v1.IssueService/RejectIssue` | Reject change request | - | | +| | Request Issue | `/bytebase.v1.IssueService/RequestIssue` | Re-request approval | - | | +| **Plan Management** | Create Plan | `/bytebase.v1.PlanService/CreatePlan` | Create deployment plan | - | | +| | Update Plan | `/bytebase.v1.PlanService/UpdatePlan` | Modify deployment plan | - | | +| **Rollout Management** | Create Rollout | `/bytebase.v1.RolloutService/CreateRollout` | Create deployment rollout | - | | +| | Run Tasks | `/bytebase.v1.RolloutService/BatchRunTasks` | Execute deployment tasks | - | | +| | Skip Tasks | `/bytebase.v1.RolloutService/BatchSkipTasks` | Skip deployment tasks | - | | +| | Cancel Task Runs | `/bytebase.v1.RolloutService/BatchCancelTaskRuns` | Cancel running tasks | - | | +| **Policy Management** | Create Policy | `/bytebase.v1.OrgPolicyService/CreatePolicy` | Create organizational policy | - | | +| | Update Policy | `/bytebase.v1.OrgPolicyService/UpdatePolicy` | Modify policy settings | - | | +| | Delete Policy | `/bytebase.v1.OrgPolicyService/DeletePolicy` | Remove policy | - | | +| **Settings Management** | Update Setting | `/bytebase.v1.SettingService/UpdateSetting` | Modify system settings | Setting name | | +--- -### Data Security +## Events Not Logged -- Data masking rule changes -- Access control policy updates -- Sensitive data access (via SQL queries) +| Category | Methods/Operations | Reason | +|----------|-------------------|--------| +| **Read-Only Operations** | All `Get*`, `List*`, `Search*` methods, `GetIamPolicy` | Low security impact - viewing data doesn't modify state | +| **High-Frequency Operations** | `AuthService/Refresh`, `BatchSyncInstances`, Actuator health checks | Too frequent, would create excessive log volume | +| **Validate-Only Requests** | Any request with `validate_only = true` | Dry-run operations that don't modify state | +| **Utility Services** | `CELService/*`, `SQLService/AICompletion`, `SQLService/DiffMetadata` | Utility functions with no security implications | +| **Review & Sheet Operations** | `ReviewConfigService/*`, `SheetService/*`, `WorksheetService/*` | Lower security impact configuration | +| **Release & Revision Operations** | `ReleaseService/*`, `RevisionService/*` | Schema tracking operations | +| **Instance Role Operations** | `InstanceRoleService/*` | Database role management | ## Limitations -### Events Not Logged - -The following activities are not logged: - -- Most read-only operations (Get, List, Search methods - viewing data, browsing schemas) -- System health checks and monitoring probes (/actuator endpoints) -- Internal background jobs and maintenance tasks -- WebSocket connections and real-time events - ### Privacy and Security Considerations - **Query results excluded:** Actual row data from queries is redacted in audit logs From 8d128e2ccf2427af2809315a4531d86f3b331f51 Mon Sep 17 00:00:00 2001 From: adela Date: Wed, 31 Dec 2025 16:57:20 +0800 Subject: [PATCH 4/5] update --- docs/security/audit-log.mdx | 420 +++++++++++++++++++++++------------- 1 file changed, 267 insertions(+), 153 deletions(-) diff --git a/docs/security/audit-log.mdx b/docs/security/audit-log.mdx index c603c2cb..d1ff5895 100644 --- a/docs/security/audit-log.mdx +++ b/docs/security/audit-log.mdx @@ -8,28 +8,6 @@ Audit logging tracks all configuration changes and data operations within your B Audit logging is available only for **Pro** and **Enterprise** plans. -For a complete list of logged events, see the [Events Reference](#events-reference) section at the end of this document. - -## Example Log Entry - -```json -{ - "parent": "projects/sample-project", - "method": "/bytebase.v1.SQLService/Query", - "resource": "instances/prod-postgres/databases/mydb", - "user": "users/developer@example.com", - "severity": "INFO", - "request": "{\"name\":\"instances/prod-postgres/databases/mydb\",\"statement\":\"SELECT * FROM users LIMIT 10\",\"limit\":100}", - "response": "{\"results\":[{\"columnNames\":[\"id\",\"name\"],\"columnTypeNames\":[\"int4\",\"text\"],\"rowsCount\":10}]}", - "status": {"code": 0}, - "latency": {"seconds": 0, "nanos": 125000000}, - "requestMetadata": { - "callerIp": "192.168.1.100", - "callerSuppliedUserAgent": "Mozilla/5.0 Chrome/120.0" - } -} -``` - ## Accessing Audit Logs ### GUI @@ -43,6 +21,7 @@ For a complete list of logged events, see the [Events Reference](#events-referen ![overview](/content/docs/security/audit-log/overview.webp) You can filter audit logs by: + - User - Action type - Resource @@ -81,159 +60,294 @@ docker run --rm --init \ --enable-json-logging ``` -It supports **SIEM Platforms** (e.g., Splunk, Datadog, Elastic Security), **Log Aggregators** (e.g., Fluentd, Logstash, Grafana Loki) and **Cloud Services** (e.g., AWS CloudWatch, Google Cloud Logging, Azure Monitor, New Relic Logs). - -## Retention - - -Bytebase does not automatically purge audit logs. You must implement periodic cleanup to prevent disk space exhaustion, which can cause Bytebase to crash. - - -Audit logs are stored in the `audit_log` table in the Bytebase metadata database. +Supported integrations: -You can manually delete old logs from the `audit_log` table or set up a scheduled job (e.g., using pg_cron or system cron) to automatically purge logs periodically. As a general best practice, many organizations retain audit logs for **at least 90 days**, and often **6–12 months** in environments with stricter compliance or investigation requirements. When choosing a retention period, balance your regulatory and security needs against available storage capacity and consider exporting logs to external log management or SIEM systems for longer-term retention. +- **SIEM Platforms**: e.g., Splunk, Datadog, Elastic Security +- **Log Aggregators**: e.g., Fluentd, Logstash, Grafana Loki +- **Cloud Services**: e.g., AWS CloudWatch, Google Cloud Logging, Azure Monitor ## Log Structure -### Payload Structure (JSON) +### Example Entry -Each audit log entry contains a JSON payload with the following fields: - -| Field | Type | Description | -|-------|------|-------------| -| `parent` | string | Scope of the audit log. Format: `projects/{project}` or `workspaces/{workspace}` | -| `method` | string | Full API method name. Example: `/bytebase.v1.SQLService/Query` | -| `resource` | string | The primary resource being acted upon. Context-dependent based on operation type | -| `user` | string | User who performed the action. Format: `users/{email}` | -| `severity` | string | Log severity level (see Severity Levels table) | -| `request` | string | JSON-serialized request payload (sensitive fields redacted) | -| `response` | string | JSON-serialized response payload (sensitive fields redacted) | -| `status` | object | gRPC status with `code` and `message` fields | -| `latency` | object | Operation duration with `seconds` and `nanos` fields | -| `serviceData` | object | Service-specific metadata (e.g., IAM policy changes) | -| `requestMetadata` | object | Client information (see below) | - -### RequestMetadata Structure +```json +{ + "parent": "projects/sample-project", + "method": "/bytebase.v1.SQLService/Query", + "resource": "instances/prod-postgres/databases/mydb", + "user": "users/developer@example.com", + "severity": "INFO", + "request": "{\"name\":\"instances/prod-postgres/databases/mydb\",\"statement\":\"SELECT * FROM users LIMIT 10\",\"limit\":100}", + "response": "{\"results\":[{\"columnNames\":[\"id\",\"name\"],\"columnTypeNames\":[\"int4\",\"text\"],\"rowsCount\":10}]}", + "status": { "code": 0 }, + "latency": { "seconds": 0, "nanos": 125000000 }, + "requestMetadata": { + "callerIp": "192.168.1.100", + "callerSuppliedUserAgent": "Mozilla/5.0 Chrome/120.0" + } +} +``` -| Field | Type | Description | -|-------|------|-------------| -| `callerIp` | string | Client IP address (extracted from X-Real-IP, X-Forwarded-For, or peer address) | -| `callerSuppliedUserAgent` | string | User-Agent header value | +### Payload Fields + +| Field | Type | Description | +| ----------------- | ------ | ------------------------------------------------------------------------------ | +| `parent` | string | Scope of the audit log. Format: `projects/{project}` or `workspaces/{workspace}` | +| `method` | string | Full API method name. Example: `/bytebase.v1.SQLService/Query` | +| `resource` | string | The primary resource being acted upon | +| `user` | string | User who performed the action. Format: `users/{email}` | +| `severity` | string | Log severity level | +| `request` | string | JSON-serialized request payload (sensitive fields redacted) | +| `response` | string | JSON-serialized response payload (sensitive fields redacted) | +| `status` | object | gRPC status with `code` and `message` fields | +| `latency` | object | Operation duration with `seconds` and `nanos` fields | +| `serviceData` | object | Service-specific metadata (e.g., IAM policy changes) | +| `requestMetadata` | object | Client information including `callerIp` and `callerSuppliedUserAgent` | ### Severity Levels -| Level | Value | Description | -|-------|-------|-------------| -| `SEVERITY_UNSPECIFIED` | 0 | Unspecified | -| `DEBUG` | 1 | Debug-level information | -| `INFO` | 2 | Informational messages (default for all audit logs) | -| `NOTICE` | 3 | Notable events | -| `WARNING` | 4 | Warning conditions | -| `ERROR` | 5 | Error conditions | -| `CRITICAL` | 6 | Critical conditions | -| `ALERT` | 7 | Action must be taken immediately | -| `EMERGENCY` | 8 | System is unusable | +| Level | Value | Description | +| ---------------------- | ----- | ------------------------------------ | +| `SEVERITY_UNSPECIFIED` | 0 | Unspecified | +| `DEBUG` | 1 | Debug-level information | +| `INFO` | 2 | Informational messages (default) | +| `NOTICE` | 3 | Notable events | +| `WARNING` | 4 | Warning conditions | +| `ERROR` | 5 | Error conditions | +| `CRITICAL` | 6 | Critical conditions | +| `ALERT` | 7 | Action must be taken immediately | +| `EMERGENCY` | 8 | System is unusable | ### Status Codes Status codes follow gRPC conventions: -| Code | Name | Description | -|------|------|-------------| -| 0 | OK | Success | -| 1 | CANCELED | Operation canceled | -| 2 | UNKNOWN | Unknown error | -| 3 | INVALID_ARGUMENT | Invalid input | -| 5 | NOT_FOUND | Resource not found | -| 7 | PERMISSION_DENIED | Insufficient permissions | -| 13 | INTERNAL | Internal server error | -| 16 | UNAUTHENTICATED | Authentication required | + +| Code | Name | Description | +| ---- | ----------------- | ------------------------ | +| 0 | OK | Success | +| 1 | CANCELED | Operation canceled | +| 2 | UNKNOWN | Unknown error | +| 3 | INVALID_ARGUMENT | Invalid input | +| 5 | NOT_FOUND | Resource not found | +| 7 | PERMISSION_DENIED | Insufficient permissions | +| 13 | INTERNAL | Internal server error | +| 16 | UNAUTHENTICATED | Authentication required | ## Audited Events -| Module | Event Name | Method | Description | Resource Field | Notes | -|--------|------------|--------|-------------|----------------|-------| -| **Authentication** | User Login | `/bytebase.v1.AuthService/Login` | User authentication (password, SSO, MFA) | User email | Sensitive fields redacted: `password`, `otpCode`, `recoveryCode`, `mfaTempToken`, `idpContext`. MFA phase logs extract user email from MFA temp token when email is not in request. | -| | User Logout | `/bytebase.v1.AuthService/Logout` | User session termination | - | | -| | Token Exchange | `/bytebase.v1.AuthService/ExchangeToken` | Workload Identity token exchange (CI/CD) | - | Used for CI/CD pipelines with external OIDC tokens. | -| **User Management** | Create User | `/bytebase.v1.UserService/CreateUser` | Create new user account | User name | User responses redacted to only include: `name`, `email`, `title`, `userType`. | -| | Update User | `/bytebase.v1.UserService/UpdateUser` | Modify user settings, MFA, profile | User name | User responses redacted to only include: `name`, `email`, `title`, `userType`. | -| | Delete User | `/bytebase.v1.UserService/DeleteUser` | Soft-delete user account | - | | -| | Restore User | `/bytebase.v1.UserService/UndeleteUser` | Restore deleted user | - | | -| | Update Email | `/bytebase.v1.UserService/UpdateEmail` | Change user email address | - | | -| **Group Management** | Create Group | `/bytebase.v1.GroupService/CreateGroup` | Create user group | - | | -| | Update Group | `/bytebase.v1.GroupService/UpdateGroup` | Modify group membership/settings | - | | -| | Delete Group | `/bytebase.v1.GroupService/DeleteGroup` | Delete user group | - | | -| **Role Management** | Create Role | `/bytebase.v1.RoleService/CreateRole` | Create custom role | - | | -| | Update Role | `/bytebase.v1.RoleService/UpdateRole` | Modify role permissions | - | | -| | Delete Role | `/bytebase.v1.RoleService/DeleteRole` | Delete custom role | - | | -| **Identity Provider (SSO)** | Create Identity Provider | `/bytebase.v1.IdentityProviderService/CreateIdentityProvider` | Configure new SSO provider | - | | -| | Update Identity Provider | `/bytebase.v1.IdentityProviderService/UpdateIdentityProvider` | Modify SSO configuration | - | | -| | Delete Identity Provider | `/bytebase.v1.IdentityProviderService/DeleteIdentityProvider` | Remove SSO provider | - | | -| **Project Management** | Delete Project | `/bytebase.v1.ProjectService/DeleteProject` | Soft-delete project | - | | -| | Restore Project | `/bytebase.v1.ProjectService/UndeleteProject` | Restore deleted project | - | | -| | Batch Delete Projects | `/bytebase.v1.ProjectService/BatchDeleteProjects` | Delete multiple projects | - | | -| | Set Project IAM Policy | `/bytebase.v1.ProjectService/SetIamPolicy` | Modify project member permissions | Resource name | Includes `serviceData` with `PolicyDelta` showing added/removed bindings. | -| **Workspace IAM** | Set Workspace IAM Policy | `/bytebase.v1.WorkspaceService/SetIamPolicy` | Modify workspace-level permissions | Resource name | Includes `serviceData` with `PolicyDelta` showing added/removed bindings. | -| **Instance Management** | Create Instance | `/bytebase.v1.InstanceService/CreateInstance` | Register new database instance | Instance name | DataSource sensitive fields redacted: `password`, `sslCa`, `sslCert`, `sslKey`, `sshPassword`, `sshPrivateKey`, `authenticationPrivateKey`, `externalSecret`, `saslConfig.krbConfig.keytab`, `masterPassword`. | -| | Update Instance | `/bytebase.v1.InstanceService/UpdateInstance` | Modify instance configuration | Instance name | DataSource sensitive fields redacted (same as above). | -| | Delete Instance | `/bytebase.v1.InstanceService/DeleteInstance` | Soft-delete instance | Instance name | | -| | Restore Instance | `/bytebase.v1.InstanceService/UndeleteInstance` | Restore deleted instance | Instance name | | -| | Batch Update Instances | `/bytebase.v1.InstanceService/BatchUpdateInstances` | Bulk update instances | - | | -| | Add Data Source | `/bytebase.v1.InstanceService/AddDataSource` | Add connection to instance | Instance name | DataSource sensitive fields redacted. | -| | Update Data Source | `/bytebase.v1.InstanceService/UpdateDataSource` | Modify connection settings | Instance name | DataSource sensitive fields redacted. | -| | Remove Data Source | `/bytebase.v1.InstanceService/RemoveDataSource` | Remove connection | Instance name | | -| **Database Management** | Update Database | `/bytebase.v1.DatabaseService/UpdateDatabase` | Modify database settings/labels | Database name | | -| | Batch Update Databases | `/bytebase.v1.DatabaseService/BatchUpdateDatabases` | Bulk update databases | Parent | | -| **Database Catalog** | Update Database Catalog | `/bytebase.v1.DatabaseCatalogService/UpdateDatabaseCatalog` | Modify schema catalog/classification | Catalog name | | -| **Database Groups** | Create Database Group | `/bytebase.v1.DatabaseGroupService/CreateDatabaseGroup` | Create logical database group | - | | -| | Update Database Group | `/bytebase.v1.DatabaseGroupService/UpdateDatabaseGroup` | Modify database group | - | | -| | Delete Database Group | `/bytebase.v1.DatabaseGroupService/DeleteDatabaseGroup` | Delete database group | - | | -| **SQL Operations** | Execute Query | `/bytebase.v1.SQLService/Query` | Execute read-only SQL query | Database name | Response rows completely redacted - only metadata captured: `columnNames`, `columnTypeNames`, `rowsCount`, `error`, `latency`, `statement`. Masking reason icons stripped. | -| | Admin Execute | `/bytebase.v1.SQLService/AdminExecute` | Execute SQL with admin privileges (streaming) | Database name | Response rows completely redacted. Each request/response pair in the stream generates a separate audit log. | -| | Export Data | `/bytebase.v1.SQLService/Export` | Export query results to file | Database/rollout name | Request `password` field redacted. Response `content` not logged (too large). | -| **Issue Management** | Create Issue | `/bytebase.v1.IssueService/CreateIssue` | Create change request | - | | -| | Update Issue | `/bytebase.v1.IssueService/UpdateIssue` | Modify issue details | - | | -| | Create Issue Comment | `/bytebase.v1.IssueService/CreateIssueComment` | Add comment to issue | - | | -| | Update Issue Comment | `/bytebase.v1.IssueService/UpdateIssueComment` | Modify issue comment | - | | -| | Batch Update Issues Status | `/bytebase.v1.IssueService/BatchUpdateIssuesStatus` | Bulk status change | - | | -| | Approve Issue | `/bytebase.v1.IssueService/ApproveIssue` | Approve change request | - | | -| | Reject Issue | `/bytebase.v1.IssueService/RejectIssue` | Reject change request | - | | -| | Request Issue | `/bytebase.v1.IssueService/RequestIssue` | Re-request approval | - | | -| **Plan Management** | Create Plan | `/bytebase.v1.PlanService/CreatePlan` | Create deployment plan | - | | -| | Update Plan | `/bytebase.v1.PlanService/UpdatePlan` | Modify deployment plan | - | | -| **Rollout Management** | Create Rollout | `/bytebase.v1.RolloutService/CreateRollout` | Create deployment rollout | - | | -| | Run Tasks | `/bytebase.v1.RolloutService/BatchRunTasks` | Execute deployment tasks | - | | -| | Skip Tasks | `/bytebase.v1.RolloutService/BatchSkipTasks` | Skip deployment tasks | - | | -| | Cancel Task Runs | `/bytebase.v1.RolloutService/BatchCancelTaskRuns` | Cancel running tasks | - | | -| **Policy Management** | Create Policy | `/bytebase.v1.OrgPolicyService/CreatePolicy` | Create organizational policy | - | | -| | Update Policy | `/bytebase.v1.OrgPolicyService/UpdatePolicy` | Modify policy settings | - | | -| | Delete Policy | `/bytebase.v1.OrgPolicyService/DeletePolicy` | Remove policy | - | | -| **Settings Management** | Update Setting | `/bytebase.v1.SettingService/UpdateSetting` | Modify system settings | Setting name | | ---- + + + +| Event | Method | Description | +| -------------- | ----------------------------------------- | ---------------------------------------------------- | +| User Login | `/bytebase.v1.AuthService/Login` | User authentication (password, SSO, MFA) | +| User Logout | `/bytebase.v1.AuthService/Logout` | User session termination | +| Token Exchange | `/bytebase.v1.AuthService/ExchangeToken` | Workload Identity token exchange for CI/CD pipelines | + +**Notes:** + +- Sensitive fields redacted: `password`, `otpCode`, `recoveryCode`, `mfaTempToken`, `idpContext` +- MFA phase logs extract user email from MFA temp token when email is not in request + + + + +| Event | Method | Description | +| ------------ | --------------------------------------- | ------------------------------------ | +| Create User | `/bytebase.v1.UserService/CreateUser` | Create new user account | +| Update User | `/bytebase.v1.UserService/UpdateUser` | Modify user settings, MFA, profile | +| Delete User | `/bytebase.v1.UserService/DeleteUser` | Soft-delete user account | +| Restore User | `/bytebase.v1.UserService/UndeleteUser` | Restore deleted user | +| Update Email | `/bytebase.v1.UserService/UpdateEmail` | Change user email address | + +**Notes:** + +- User responses redacted to only include: `name`, `email`, `title`, `userType` + + + + +| Event | Method | Description | +| ------------ | --------------------------------------- | -------------------------------- | +| Create Group | `/bytebase.v1.GroupService/CreateGroup` | Create user group | +| Update Group | `/bytebase.v1.GroupService/UpdateGroup` | Modify group membership/settings | +| Delete Group | `/bytebase.v1.GroupService/DeleteGroup` | Delete user group | + + + + +| Event | Method | Description | +| ----------- | ------------------------------------- | ----------------------- | +| Create Role | `/bytebase.v1.RoleService/CreateRole` | Create custom role | +| Update Role | `/bytebase.v1.RoleService/UpdateRole` | Modify role permissions | +| Delete Role | `/bytebase.v1.RoleService/DeleteRole` | Delete custom role | + + + + +| Event | Method | Description | +| ------------------------ | ------------------------------------------------------------- | -------------------------- | +| Create Identity Provider | `/bytebase.v1.IdentityProviderService/CreateIdentityProvider` | Configure new SSO provider | +| Update Identity Provider | `/bytebase.v1.IdentityProviderService/UpdateIdentityProvider` | Modify SSO configuration | +| Delete Identity Provider | `/bytebase.v1.IdentityProviderService/DeleteIdentityProvider` | Remove SSO provider | + + + + +| Event | Method | Description | +| ---------------------- | ------------------------------------------------- | --------------------------------- | +| Delete Project | `/bytebase.v1.ProjectService/DeleteProject` | Soft-delete project | +| Restore Project | `/bytebase.v1.ProjectService/UndeleteProject` | Restore deleted project | +| Batch Delete Projects | `/bytebase.v1.ProjectService/BatchDeleteProjects` | Delete multiple projects | +| Set Project IAM Policy | `/bytebase.v1.ProjectService/SetIamPolicy` | Modify project member permissions | + +**Notes:** + +- IAM policy changes include `serviceData` with `PolicyDelta` showing added/removed bindings + + + + +| Event | Method | Description | +| ------------------------ | -------------------------------------------- | ---------------------------------- | +| Set Workspace IAM Policy | `/bytebase.v1.WorkspaceService/SetIamPolicy` | Modify workspace-level permissions | + +**Notes:** + +- Includes `serviceData` with `PolicyDelta` showing added/removed bindings + + + + +| Event | Method | Description | +| ---------------------- | --------------------------------------------------- | ------------------------------ | +| Create Instance | `/bytebase.v1.InstanceService/CreateInstance` | Register new database instance | +| Update Instance | `/bytebase.v1.InstanceService/UpdateInstance` | Modify instance configuration | +| Delete Instance | `/bytebase.v1.InstanceService/DeleteInstance` | Soft-delete instance | +| Restore Instance | `/bytebase.v1.InstanceService/UndeleteInstance` | Restore deleted instance | +| Batch Update Instances | `/bytebase.v1.InstanceService/BatchUpdateInstances` | Bulk update instances | +| Add Data Source | `/bytebase.v1.InstanceService/AddDataSource` | Add connection to instance | +| Update Data Source | `/bytebase.v1.InstanceService/UpdateDataSource` | Modify connection settings | +| Remove Data Source | `/bytebase.v1.InstanceService/RemoveDataSource` | Remove connection | + +**Notes:** + +- DataSource sensitive fields redacted: `password`, `sslCa`, `sslCert`, `sslKey`, `sshPassword`, `sshPrivateKey`, `authenticationPrivateKey`, `externalSecret`, `saslConfig.krbConfig.keytab`, `masterPassword` + + + + +| Event | Method | Description | +| ----------------------- | ----------------------------------------------------------- | ------------------------------------ | +| Update Database | `/bytebase.v1.DatabaseService/UpdateDatabase` | Modify database settings/labels | +| Batch Update Databases | `/bytebase.v1.DatabaseService/BatchUpdateDatabases` | Bulk update databases | +| Update Database Catalog | `/bytebase.v1.DatabaseCatalogService/UpdateDatabaseCatalog` | Modify schema catalog/classification | + + + + +| Event | Method | Description | +| --------------------- | ------------------------------------------------------- | ----------------------------- | +| Create Database Group | `/bytebase.v1.DatabaseGroupService/CreateDatabaseGroup` | Create logical database group | +| Update Database Group | `/bytebase.v1.DatabaseGroupService/UpdateDatabaseGroup` | Modify database group | +| Delete Database Group | `/bytebase.v1.DatabaseGroupService/DeleteDatabaseGroup` | Delete database group | + + + + +| Event | Method | Description | +| ------------- | -------------------------------------- | --------------------------------------------- | +| Execute Query | `/bytebase.v1.SQLService/Query` | Execute read-only SQL query | +| Admin Execute | `/bytebase.v1.SQLService/AdminExecute` | Execute SQL with admin privileges (streaming) | +| Export Data | `/bytebase.v1.SQLService/Export` | Export query results to file | + +**Notes:** + +- Response rows completely redacted - only metadata captured: `columnNames`, `columnTypeNames`, `rowsCount`, `error`, `latency`, `statement` +- Each request/response pair in streaming operations generates a separate audit log +- Export request `password` field redacted; response `content` not logged + + + + +| Event | Method | Description | +| -------------------------- | --------------------------------------------------- | ---------------------- | +| Create Issue | `/bytebase.v1.IssueService/CreateIssue` | Create change request | +| Update Issue | `/bytebase.v1.IssueService/UpdateIssue` | Modify issue details | +| Create Issue Comment | `/bytebase.v1.IssueService/CreateIssueComment` | Add comment to issue | +| Update Issue Comment | `/bytebase.v1.IssueService/UpdateIssueComment` | Modify issue comment | +| Batch Update Issues Status | `/bytebase.v1.IssueService/BatchUpdateIssuesStatus` | Bulk status change | +| Approve Issue | `/bytebase.v1.IssueService/ApproveIssue` | Approve change request | +| Reject Issue | `/bytebase.v1.IssueService/RejectIssue` | Reject change request | +| Request Issue | `/bytebase.v1.IssueService/RequestIssue` | Re-request approval | + + + + +| Event | Method | Description | +| ---------------- | ------------------------------------------------- | ------------------------- | +| Create Plan | `/bytebase.v1.PlanService/CreatePlan` | Create deployment plan | +| Update Plan | `/bytebase.v1.PlanService/UpdatePlan` | Modify deployment plan | +| Create Rollout | `/bytebase.v1.RolloutService/CreateRollout` | Create deployment rollout | +| Run Tasks | `/bytebase.v1.RolloutService/BatchRunTasks` | Execute deployment tasks | +| Skip Tasks | `/bytebase.v1.RolloutService/BatchSkipTasks` | Skip deployment tasks | +| Cancel Task Runs | `/bytebase.v1.RolloutService/BatchCancelTaskRuns` | Cancel running tasks | + + + + +| Event | Method | Description | +| -------------- | -------------------------------------------- | ---------------------------- | +| Create Policy | `/bytebase.v1.OrgPolicyService/CreatePolicy` | Create organizational policy | +| Update Policy | `/bytebase.v1.OrgPolicyService/UpdatePolicy` | Modify policy settings | +| Delete Policy | `/bytebase.v1.OrgPolicyService/DeletePolicy` | Remove policy | +| Update Setting | `/bytebase.v1.SettingService/UpdateSetting` | Modify system settings | + + + ## Events Not Logged -| Category | Methods/Operations | Reason | -|----------|-------------------|--------| -| **Read-Only Operations** | All `Get*`, `List*`, `Search*` methods, `GetIamPolicy` | Low security impact - viewing data doesn't modify state | -| **High-Frequency Operations** | `AuthService/Refresh`, `BatchSyncInstances`, Actuator health checks | Too frequent, would create excessive log volume | -| **Validate-Only Requests** | Any request with `validate_only = true` | Dry-run operations that don't modify state | -| **Utility Services** | `CELService/*`, `SQLService/AICompletion`, `SQLService/DiffMetadata` | Utility functions with no security implications | -| **Review & Sheet Operations** | `ReviewConfigService/*`, `SheetService/*`, `WorksheetService/*` | Lower security impact configuration | -| **Release & Revision Operations** | `ReleaseService/*`, `RevisionService/*` | Schema tracking operations | -| **Instance Role Operations** | `InstanceRoleService/*` | Database role management | +| Category | Operations | Reason | +| --------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------- | +| **Read-Only Operations** | All `Get*`, `List*`, `Search*` methods, `GetIamPolicy` | Low security impact - viewing data doesn't modify state | +| **High-Frequency Operations** | `AuthService/Refresh`, `BatchSyncInstances`, Actuator health checks | Too frequent, would create excessive log volume | +| **Validate-Only Requests** | Any request with `validate_only = true` | Dry-run operations that don't modify state | +| **Utility Services** | `CELService/*`, `SQLService/AICompletion`, `SQLService/DiffMetadata` | Utility functions with no security implications | +| **Review & Sheet Operations** | `ReviewConfigService/*`, `SheetService/*`, `WorksheetService/*` | Lower security impact configuration | +| **Release & Revision** | `ReleaseService/*`, `RevisionService/*` | Schema tracking operations | +| **Instance Role Operations** | `InstanceRoleService/*` | Database role management | + +## Retention + + +Bytebase does not automatically purge audit logs. You must implement periodic cleanup to prevent disk space exhaustion, which can cause Bytebase to crash. + + +Audit logs are stored in the `audit_log` table in the Bytebase metadata database. + +**Recommended retention periods:** + +- **Minimum**: 90 days +- **Compliance environments**: 6–12 months + +**Cleanup options:** + +- Manually delete old logs from the `audit_log` table +- Set up a scheduled job using `pg_cron` or system cron +- Export logs to external log management or SIEM systems for longer-term retention ## Limitations -### Privacy and Security Considerations +### Privacy and Security -- **Query results excluded:** Actual row data from queries is redacted in audit logs -- **Sensitive data masking:** Passwords, API keys, SSL certificates, SSH keys, and other secrets are automatically replaced with masked values -- **Response truncation:** Large response payloads may be omitted +- **Query results excluded**: Actual row data from queries is redacted +- **Sensitive data masking**: Passwords, API keys, SSL certificates, SSH keys automatically replaced with masked values +- **Response truncation**: Large response payloads may be omitted -### Technical Limitations +### Technical Constraints -- **Log generation:** Audit logs are generated synchronously during request processing -- **Pagination limit:** Maximum 5000 audit log entries can be retrieved per API call -- **Filter complexity:** Audit log searches must use valid CEL expressions -- **Storage:** Audit logs are stored in the meta database and follow its retention policies \ No newline at end of file +- **Synchronous generation**: Audit logs are generated during request processing +- **Pagination limit**: Maximum 5,000 entries per API call +- **Filter complexity**: Searches must use valid CEL expressions +- **Storage**: Logs stored in metadata database, following its retention policies From 3cc30cf623611b32a7f6556399de2a9886cbd191 Mon Sep 17 00:00:00 2001 From: adela Date: Wed, 31 Dec 2025 17:23:45 +0800 Subject: [PATCH 5/5] update --- docs/security/audit-log.mdx | 33 +++++++++++++++++++++------------ 1 file changed, 21 insertions(+), 12 deletions(-) diff --git a/docs/security/audit-log.mdx b/docs/security/audit-log.mdx index d1ff5895..a7963f8e 100644 --- a/docs/security/audit-log.mdx +++ b/docs/security/audit-log.mdx @@ -120,18 +120,27 @@ Supported integrations: ### Status Codes -Status codes follow gRPC conventions: - -| Code | Name | Description | -| ---- | ----------------- | ------------------------ | -| 0 | OK | Success | -| 1 | CANCELED | Operation canceled | -| 2 | UNKNOWN | Unknown error | -| 3 | INVALID_ARGUMENT | Invalid input | -| 5 | NOT_FOUND | Resource not found | -| 7 | PERMISSION_DENIED | Insufficient permissions | -| 13 | INTERNAL | Internal server error | -| 16 | UNAUTHENTICATED | Authentication required | +Status codes follow [gRPC conventions](https://grpc.io/docs/guides/status-codes/): + +| Code | Name | Description | +|------|------|-------------| +| 0 | OK | Operation succeeded (no error) | +| 1 | CANCELED | Operation was canceled, typically by the caller | +| 2 | UNKNOWN | Operation failed for an unknown reason | +| 3 | INVALID_ARGUMENT | Client supplied an invalid argument | +| 4 | DEADLINE_EXCEEDED | Deadline expired before the operation could complete | +| 5 | NOT_FOUND | Requested entity (e.g., file, resource) was not found | +| 6 | ALREADY_EXISTS | Entity that client attempted to create already exists | +| 7 | PERMISSION_DENIED | Caller doesn't have permission to execute the operation | +| 8 | RESOURCE_EXHAUSTED | Some resource has been exhausted (e.g., quota, disk space) | +| 9 | FAILED_PRECONDITION | System is not in a state required for operation's execution | +| 10 | ABORTED | Operation aborted due to concurrency issue (e.g., transaction abort) | +| 11 | OUT_OF_RANGE | Operation attempted past the valid range (e.g., seek past EOF) | +| 12 | UNIMPLEMENTED | Operation isn't implemented, supported, or enabled | +| 13 | INTERNAL | Internal error - some invariants expected by the system have been broken | +| 14 | UNAVAILABLE | Service is currently unavailable (usually temporary) | +| 15 | DATA_LOSS | Unrecoverable data loss or corruption | +| 16 | UNAUTHENTICATED | Request does not have valid authentication credentials | ## Audited Events