Skip to content

Commit 49c4fd1

Browse files
adela-bytebaseadela-bytebase
committed
update
1 parent 45c4e54 commit 49c4fd1

File tree

1 file changed

+141
-95
lines changed

1 file changed

+141
-95
lines changed

‎docs/security/audit-log.mdx‎

Lines changed: 141 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -10,40 +10,23 @@ Audit logging is available only for **Pro** and **Enterprise** plans.
1010

1111
For a complete list of logged events, see the [Events Reference](#events-reference) section at the end of this document.
1212

13-
### Log Structure
14-
15-
Each audit log entry contains the following fields:
16-
17-
| Field | Description |
18-
|-------|-------------|
19-
| `time` | Timestamp when the event occurred (ISO 8601 format) |
20-
| `level` | Log severity level (INFO, WARNING, ERROR) |
21-
| `method` | API method or action performed |
22-
| `resource` | Target resource (e.g., projects/project-sample) |
23-
| `user` | User who performed the action |
24-
| `latency_ms` | Request processing time in milliseconds |
25-
| `client_ip` | IP address and port of the client |
26-
| `user_agent` | Browser or API client information |
27-
| `parent` | Parent resource context (for nested resources) |
28-
| `severity` | Event severity classification |
29-
30-
Example log entry:
13+
## Example Log Entry
3114

3215
```json
3316
{
34-
"time": "2025-12-10T15:55:21.729Z",
35-
"level": "INFO",
36-
"source": "v1/audit.go:274",
37-
"msg": "/bytebase.v1.ProjectService/SetIamPolicy",
38-
"log_type": "audit",
39-
"parent": "projects/project-sample",
40-
"method": "/bytebase.v1.ProjectService/SetIamPolicy",
41-
"resource": "projects/project-sample",
42-
"user": "users/101",
43-
"latency_ms": 7,
44-
"client_ip": "192.168.65.1:51907",
45-
"user_agent": "Mozilla/5.0...",
46-
"severity": "INFO"
17+
"parent": "projects/sample-project",
18+
"method": "/bytebase.v1.SQLService/Query",
19+
"resource": "instances/prod-postgres/databases/mydb",
20+
"user": "users/developer@example.com",
21+
"severity": "INFO",
22+
"request": "{\"name\":\"instances/prod-postgres/databases/mydb\",\"statement\":\"SELECT * FROM users LIMIT 10\",\"limit\":100}",
23+
"response": "{\"results\":[{\"columnNames\":[\"id\",\"name\"],\"columnTypeNames\":[\"int4\",\"text\"],\"rowsCount\":10}]}",
24+
"status": {"code": 0},
25+
"latency": {"seconds": 0, "nanos": 125000000},
26+
"requestMetadata": {
27+
"callerIp": "192.168.1.100",
28+
"callerSuppliedUserAgent": "Mozilla/5.0 Chrome/120.0"
29+
}
4730
}
4831
```
4932

@@ -110,75 +93,138 @@ Audit logs are stored in the `audit_log` table in the Bytebase metadata database
11093

11194
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.
11295

113-
## Events Reference
114-
115-
Bytebase logs the following event categories:
116-
117-
### Authentication & Authorization
118-
119-
- User login/logout (Login, Logout)
120-
- API token operations
121-
- IAM policy changes
122-
- Role assignments (CreateRole, UpdateRole, DeleteRole)
123-
124-
### Database Operations
125-
126-
- Schema migrations
127-
- Data changes (DML operations)
128-
- Database creation/deletion/updates
129-
- Database transfers between projects
130-
- SQL query executions
131-
- Database catalog modifications
132-
133-
### Project Management
134-
135-
- Project creation/updates/deletion
136-
- Project IAM policy updates
137-
- Database group management
138-
139-
### Issue & Change Management
140-
141-
- Issue creation/updates/approvals
142-
- Rollout plan executions
143-
- Task runs and approvals
144-
145-
### Instance Management
146-
147-
- Instance creation/updates/deletion
148-
- Instance connection operations
149-
- Data source management
150-
- Sync operations
151-
152-
### Configuration & Settings
153-
154-
- Workspace settings changes
155-
- Organization policy updates
156-
- SSO/IDP configurations
157-
- Setting updates
158-
159-
### Access Control
160-
161-
- Permission grants/revokes
162-
- Group membership changes (CreateGroup, UpdateGroup, DeleteGroup)
163-
- User management operations
96+
## Log Structure
97+
98+
### Payload Structure (JSON)
99+
100+
Each audit log entry contains a JSON payload with the following fields:
101+
102+
| Field | Type | Description |
103+
|-------|------|-------------|
104+
| `parent` | string | Scope of the audit log. Format: `projects/{project}` or `workspaces/{workspace}` |
105+
| `method` | string | Full API method name. Example: `/bytebase.v1.SQLService/Query` |
106+
| `resource` | string | The primary resource being acted upon. Context-dependent based on operation type |
107+
| `user` | string | User who performed the action. Format: `users/{email}` |
108+
| `severity` | string | Log severity level (see Severity Levels table) |
109+
| `request` | string | JSON-serialized request payload (sensitive fields redacted) |
110+
| `response` | string | JSON-serialized response payload (sensitive fields redacted) |
111+
| `status` | object | gRPC status with `code` and `message` fields |
112+
| `latency` | object | Operation duration with `seconds` and `nanos` fields |
113+
| `serviceData` | object | Service-specific metadata (e.g., IAM policy changes) |
114+
| `requestMetadata` | object | Client information (see below) |
115+
116+
### RequestMetadata Structure
117+
118+
| Field | Type | Description |
119+
|-------|------|-------------|
120+
| `callerIp` | string | Client IP address (extracted from X-Real-IP, X-Forwarded-For, or peer address) |
121+
| `callerSuppliedUserAgent` | string | User-Agent header value |
122+
123+
### Severity Levels
124+
125+
| Level | Value | Description |
126+
|-------|-------|-------------|
127+
| `SEVERITY_UNSPECIFIED` | 0 | Unspecified |
128+
| `DEBUG` | 1 | Debug-level information |
129+
| `INFO` | 2 | Informational messages (default for all audit logs) |
130+
| `NOTICE` | 3 | Notable events |
131+
| `WARNING` | 4 | Warning conditions |
132+
| `ERROR` | 5 | Error conditions |
133+
| `CRITICAL` | 6 | Critical conditions |
134+
| `ALERT` | 7 | Action must be taken immediately |
135+
| `EMERGENCY` | 8 | System is unusable |
136+
137+
### Status Codes
138+
139+
Status codes follow gRPC conventions:
140+
| Code | Name | Description |
141+
|------|------|-------------|
142+
| 0 | OK | Success |
143+
| 1 | CANCELED | Operation canceled |
144+
| 2 | UNKNOWN | Unknown error |
145+
| 3 | INVALID_ARGUMENT | Invalid input |
146+
| 5 | NOT_FOUND | Resource not found |
147+
| 7 | PERMISSION_DENIED | Insufficient permissions |
148+
| 13 | INTERNAL | Internal server error |
149+
| 16 | UNAUTHENTICATED | Authentication required |
150+
151+
## Audited Events
152+
153+
| Module | Event Name | Method | Description | Resource Field | Notes |
154+
|--------|------------|--------|-------------|----------------|-------|
155+
| **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. |
156+
| | User Logout | `/bytebase.v1.AuthService/Logout` | User session termination | - | |
157+
| | Token Exchange | `/bytebase.v1.AuthService/ExchangeToken` | Workload Identity token exchange (CI/CD) | - | Used for CI/CD pipelines with external OIDC tokens. |
158+
| **User Management** | Create User | `/bytebase.v1.UserService/CreateUser` | Create new user account | User name | User responses redacted to only include: `name`, `email`, `title`, `userType`. |
159+
| | Update User | `/bytebase.v1.UserService/UpdateUser` | Modify user settings, MFA, profile | User name | User responses redacted to only include: `name`, `email`, `title`, `userType`. |
160+
| | Delete User | `/bytebase.v1.UserService/DeleteUser` | Soft-delete user account | - | |
161+
| | Restore User | `/bytebase.v1.UserService/UndeleteUser` | Restore deleted user | - | |
162+
| | Update Email | `/bytebase.v1.UserService/UpdateEmail` | Change user email address | - | |
163+
| **Group Management** | Create Group | `/bytebase.v1.GroupService/CreateGroup` | Create user group | - | |
164+
| | Update Group | `/bytebase.v1.GroupService/UpdateGroup` | Modify group membership/settings | - | |
165+
| | Delete Group | `/bytebase.v1.GroupService/DeleteGroup` | Delete user group | - | |
166+
| **Role Management** | Create Role | `/bytebase.v1.RoleService/CreateRole` | Create custom role | - | |
167+
| | Update Role | `/bytebase.v1.RoleService/UpdateRole` | Modify role permissions | - | |
168+
| | Delete Role | `/bytebase.v1.RoleService/DeleteRole` | Delete custom role | - | |
169+
| **Identity Provider (SSO)** | Create Identity Provider | `/bytebase.v1.IdentityProviderService/CreateIdentityProvider` | Configure new SSO provider | - | |
170+
| | Update Identity Provider | `/bytebase.v1.IdentityProviderService/UpdateIdentityProvider` | Modify SSO configuration | - | |
171+
| | Delete Identity Provider | `/bytebase.v1.IdentityProviderService/DeleteIdentityProvider` | Remove SSO provider | - | |
172+
| **Project Management** | Delete Project | `/bytebase.v1.ProjectService/DeleteProject` | Soft-delete project | - | |
173+
| | Restore Project | `/bytebase.v1.ProjectService/UndeleteProject` | Restore deleted project | - | |
174+
| | Batch Delete Projects | `/bytebase.v1.ProjectService/BatchDeleteProjects` | Delete multiple projects | - | |
175+
| | Set Project IAM Policy | `/bytebase.v1.ProjectService/SetIamPolicy` | Modify project member permissions | Resource name | Includes `serviceData` with `PolicyDelta` showing added/removed bindings. |
176+
| **Workspace IAM** | Set Workspace IAM Policy | `/bytebase.v1.WorkspaceService/SetIamPolicy` | Modify workspace-level permissions | Resource name | Includes `serviceData` with `PolicyDelta` showing added/removed bindings. |
177+
| **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`. |
178+
| | Update Instance | `/bytebase.v1.InstanceService/UpdateInstance` | Modify instance configuration | Instance name | DataSource sensitive fields redacted (same as above). |
179+
| | Delete Instance | `/bytebase.v1.InstanceService/DeleteInstance` | Soft-delete instance | Instance name | |
180+
| | Restore Instance | `/bytebase.v1.InstanceService/UndeleteInstance` | Restore deleted instance | Instance name | |
181+
| | Batch Update Instances | `/bytebase.v1.InstanceService/BatchUpdateInstances` | Bulk update instances | - | |
182+
| | Add Data Source | `/bytebase.v1.InstanceService/AddDataSource` | Add connection to instance | Instance name | DataSource sensitive fields redacted. |
183+
| | Update Data Source | `/bytebase.v1.InstanceService/UpdateDataSource` | Modify connection settings | Instance name | DataSource sensitive fields redacted. |
184+
| | Remove Data Source | `/bytebase.v1.InstanceService/RemoveDataSource` | Remove connection | Instance name | |
185+
| **Database Management** | Update Database | `/bytebase.v1.DatabaseService/UpdateDatabase` | Modify database settings/labels | Database name | |
186+
| | Batch Update Databases | `/bytebase.v1.DatabaseService/BatchUpdateDatabases` | Bulk update databases | Parent | |
187+
| **Database Catalog** | Update Database Catalog | `/bytebase.v1.DatabaseCatalogService/UpdateDatabaseCatalog` | Modify schema catalog/classification | Catalog name | |
188+
| **Database Groups** | Create Database Group | `/bytebase.v1.DatabaseGroupService/CreateDatabaseGroup` | Create logical database group | - | |
189+
| | Update Database Group | `/bytebase.v1.DatabaseGroupService/UpdateDatabaseGroup` | Modify database group | - | |
190+
| | Delete Database Group | `/bytebase.v1.DatabaseGroupService/DeleteDatabaseGroup` | Delete database group | - | |
191+
| **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. |
192+
| | 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. |
193+
| | Export Data | `/bytebase.v1.SQLService/Export` | Export query results to file | Database/rollout name | Request `password` field redacted. Response `content` not logged (too large). |
194+
| **Issue Management** | Create Issue | `/bytebase.v1.IssueService/CreateIssue` | Create change request | - | |
195+
| | Update Issue | `/bytebase.v1.IssueService/UpdateIssue` | Modify issue details | - | |
196+
| | Create Issue Comment | `/bytebase.v1.IssueService/CreateIssueComment` | Add comment to issue | - | |
197+
| | Update Issue Comment | `/bytebase.v1.IssueService/UpdateIssueComment` | Modify issue comment | - | |
198+
| | Batch Update Issues Status | `/bytebase.v1.IssueService/BatchUpdateIssuesStatus` | Bulk status change | - | |
199+
| | Approve Issue | `/bytebase.v1.IssueService/ApproveIssue` | Approve change request | - | |
200+
| | Reject Issue | `/bytebase.v1.IssueService/RejectIssue` | Reject change request | - | |
201+
| | Request Issue | `/bytebase.v1.IssueService/RequestIssue` | Re-request approval | - | |
202+
| **Plan Management** | Create Plan | `/bytebase.v1.PlanService/CreatePlan` | Create deployment plan | - | |
203+
| | Update Plan | `/bytebase.v1.PlanService/UpdatePlan` | Modify deployment plan | - | |
204+
| **Rollout Management** | Create Rollout | `/bytebase.v1.RolloutService/CreateRollout` | Create deployment rollout | - | |
205+
| | Run Tasks | `/bytebase.v1.RolloutService/BatchRunTasks` | Execute deployment tasks | - | |
206+
| | Skip Tasks | `/bytebase.v1.RolloutService/BatchSkipTasks` | Skip deployment tasks | - | |
207+
| | Cancel Task Runs | `/bytebase.v1.RolloutService/BatchCancelTaskRuns` | Cancel running tasks | - | |
208+
| **Policy Management** | Create Policy | `/bytebase.v1.OrgPolicyService/CreatePolicy` | Create organizational policy | - | |
209+
| | Update Policy | `/bytebase.v1.OrgPolicyService/UpdatePolicy` | Modify policy settings | - | |
210+
| | Delete Policy | `/bytebase.v1.OrgPolicyService/DeletePolicy` | Remove policy | - | |
211+
| **Settings Management** | Update Setting | `/bytebase.v1.SettingService/UpdateSetting` | Modify system settings | Setting name | |
212+
---
164213

165-
### Data Security
214+
## Events Not Logged
166215

167-
- Data masking rule changes
168-
- Access control policy updates
169-
- Sensitive data access (via SQL queries)
216+
| Category | Methods/Operations | Reason |
217+
|----------|-------------------|--------|
218+
| **Read-Only Operations** | All `Get*`, `List*`, `Search*` methods, `GetIamPolicy` | Low security impact - viewing data doesn't modify state |
219+
| **High-Frequency Operations** | `AuthService/Refresh`, `BatchSyncInstances`, Actuator health checks | Too frequent, would create excessive log volume |
220+
| **Validate-Only Requests** | Any request with `validate_only = true` | Dry-run operations that don't modify state |
221+
| **Utility Services** | `CELService/*`, `SQLService/AICompletion`, `SQLService/DiffMetadata` | Utility functions with no security implications |
222+
| **Review & Sheet Operations** | `ReviewConfigService/*`, `SheetService/*`, `WorksheetService/*` | Lower security impact configuration |
223+
| **Release & Revision Operations** | `ReleaseService/*`, `RevisionService/*` | Schema tracking operations |
224+
| **Instance Role Operations** | `InstanceRoleService/*` | Database role management |
170225

171226
## Limitations
172227

173-
### Events Not Logged
174-
175-
The following activities are not logged:
176-
177-
- Most read-only operations (Get, List, Search methods - viewing data, browsing schemas)
178-
- System health checks and monitoring probes (/actuator endpoints)
179-
- Internal background jobs and maintenance tasks
180-
- WebSocket connections and real-time events
181-
182228
### Privacy and Security Considerations
183229

184230
- **Query results excluded:** Actual row data from queries is redacted in audit logs

0 commit comments

Comments
 (0)