feat(audit-logging): Adds audit logging support

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Added audit logging. [#355](https://github.com/sourcebot-dev/sourcebot/pull/355)
+
 ### Fixed
 - Delete account join request when redeeming an invite. [#352](https://github.com/sourcebot-dev/sourcebot/pull/352)
 - Fix issue where a repository would not be included in a search context if the context was created before the repository. [#354](https://github.com/sourcebot-dev/sourcebot/pull/354)

docs/docs.json

@@ -75,7 +75,8 @@
                                 ]
                             },
                             "docs/configuration/transactional-emails",
-                            "docs/configuration/structured-logging"
+                            "docs/configuration/structured-logging",
+                            "docs/configuration/audit-logs"
                         ]
                     },
                     {

docs/docs/configuration/audit-logs.mdx

@@ -0,0 +1,182 @@
+---
+title: Audit Logs
+sidebarTitle: Audit logs
+---
+
+import LicenseKeyRequired from '/snippets/license-key-required.mdx'
+
+<LicenseKeyRequired />
+
+Audit logs are a collection of notable events performed by users within a Sourcebot deployment. Each audit log records information on the action taken, the user who performed the 
+action, and when the action took place. 
+
+This feature gives security and compliance teams the necessary information to ensure proper governance and administration of your Sourcebot deployment.
+
+## Enabling Audit Logs
+Audit logs must be explicitly enabled by setting the `SOURCEBOT_EE_AUDIT_LOGGING_ENABLED` [environment variable](/docs/configuration/environment-variables) to `true`
+
+## Fetching Audit Logs
+Audit logs are stored in the [postgres database](/docs/overview#architecture) connected to Sourcebot. To fetch all of the audit logs, you can use the following API:
+
+```bash icon="terminal" Fetch audit logs
+curl --request GET '$SOURCEBOT_URL/api/ee/audit' \
+  --header 'X-Org-Domain: ~' \
+  --header 'X-Sourcebot-Api-Key: $SOURCEBOT_OWNER_API_KEY'
+```
+
+```json icon="brackets-curly" wrap expandable Fetch audit logs example response
+[
+  {
+    "id": "cmc146k7m0003xgo2tri5t4br",
+    "timestamp": "2025-06-17T22:48:08.914Z",
+    "action": "api_key.created",
+    "actorId": "cmc12tnje0000xgn58jj8655h",
+    "actorType": "user",
+    "targetId": "205d1da1c6c3772b81d4ad697f5851fa11195176c211055ff0c1509772645d6d",
+    "targetType": "api_key",
+    "sourcebotVersion": "unknown",
+    "orgId": 1
+  },
+  {
+    "id": "cmc146c8r0001xgo2xyu0p463",
+    "timestamp": "2025-06-17T22:47:58.587Z",
+    "action": "query.code_search",
+    "actorId": "cmc12tnje0000xgn58jj8655h",
+    "actorType": "user",
+    "targetId": "1",
+    "targetType": "org",
+    "sourcebotVersion": "unknown",
+    "metadata": {
+      "message": "render branch:HEAD"
+    },
+    "orgId": 1
+  },
+  {
+    "id": "cmc12vqgb0008xgn5nv5hl9y5",
+    "timestamp": "2025-06-17T22:11:44.171Z",
+    "action": "query.code_search",
+    "actorId": "cmc12tnje0000xgn58jj8655h",
+    "actorType": "user",
+    "targetId": "1",
+    "targetType": "org",
+    "sourcebotVersion": "unknown",
+    "metadata": {
+      "message": "render branch:HEAD"
+    },
+    "orgId": 1
+  },
+  {
+    "id": "cmc12txwn0006xgn51ow1odid",
+    "timestamp": "2025-06-17T22:10:20.519Z",
+    "action": "query.code_search",
+    "actorId": "cmc12tnje0000xgn58jj8655h",
+    "actorType": "user",
+    "targetId": "1",
+    "targetType": "org",
+    "sourcebotVersion": "unknown",
+    "metadata": {
+      "message": "render branch:HEAD"
+    },
+    "orgId": 1
+  },
+  {
+    "id": "cmc12tnjx0004xgn5qqeiv1ao",
+    "timestamp": "2025-06-17T22:10:07.101Z",
+    "action": "user.owner_created",
+    "actorId": "cmc12tnje0000xgn58jj8655h",
+    "actorType": "user",
+    "targetId": "1",
+    "targetType": "org",
+    "sourcebotVersion": "unknown",
+    "metadata": null,
+    "orgId": 1
+  },
+  {
+    "id": "cmc12tnjh0002xgn5h6vzu3rl",
+    "timestamp": "2025-06-17T22:10:07.086Z",
+    "action": "user.signed_in",
+    "actorId": "cmc12tnje0000xgn58jj8655h",
+    "actorType": "user",
+    "targetId": "cmc12tnje0000xgn58jj8655h",
+    "targetType": "user",
+    "sourcebotVersion": "unknown",
+    "metadata": null,
+    "orgId": 1
+  }
+]
+```
+
+## Response schema
+
+```json icon="brackets-curly" expandable wrap Audit log fetch response schema
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "FetchAuditLogsResponse",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "required": [
+      "id",
+      "timestamp",
+      "action",
+      "actorId",
+      "actorType",
+      "targetId",
+      "targetType",
+      "sourcebotVersion",
+      "metadata",
+      "orgId"
+    ],
+    "properties": {
+      "id": {
+        "type": "string"
+      },
+      "timestamp": {
+        "type": "string",
+        "format": "date-time"
+      },
+      "action": {
+        "type": "string"
+      },
+      "actorId": {
+        "type": "string"
+      },
+      "actorType": {
+        "type": "string",
+        "enum": ["user", "api_key"]
+      },
+      "targetId": {
+        "type": "string"
+      },
+      "targetType": {
+        "type": "string",
+        "enum": ["user", "org", "file", "api_key", "account_join_request", "invite"]
+      },
+      "sourcebotVersion": {
+        "type": "string"
+      },
+      "metadata": {
+        "anyOf": [
+          {
+            "type": "object",
+            "properties": {
+              "message": { "type": "string" },
+              "api_key": { "type": "string" },
+              "emails": { "type": "string" }
+            },
+            "additionalProperties": false
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "orgId": {
+        "type": "integer"
+      }
+    },
+    "additionalProperties": false
+  }
+}
+
+```

docs/docs/configuration/environment-variables.mdx

@@ -39,6 +39,7 @@ The following environment variables allow you to configure your Sourcebot deploy
 ### Enterprise Environment Variables
 | Variable | Default | Description |
 | :------- | :------ | :---------- |
+| `SOURCEBOT_EE_AUDIT_LOGGING_ENABLED` | `false` | <p>Enables/disables audit logging</p> |
 | `AUTH_EE_ENABLE_JIT_PROVISIONING` | `false` | <p>Enables/disables just-in-time user provisioning for SSO providers.</p> |
 | `AUTH_EE_GITHUB_BASE_URL` | `https://github.com` | <p>The base URL for GitHub Enterprise SSO authentication.</p> |
 | `AUTH_EE_GITHUB_CLIENT_ID` | `-` | <p>The client ID for GitHub Enterprise SSO authentication.</p> |

docs/docs/configuration/structured-logging.mdx

@@ -1,5 +1,6 @@
 ---
-title: Structured logging
+title: Structured Logging
+sidebarTitle: Structured logging
 ---
 
 By default, Sourcebot will output logs to the console in a human readable format. If you'd like Sourcebot to output structured JSON logs, set the following env vars:

docs/docs/deployment-guide.mdx

@@ -33,7 +33,7 @@ Watch this 1:51 minute video to get a quick overview of how to deploy Sourcebot
     <Step title="Create a config.json">
         Create a `config.json` file that tells Sourcebot which repositories to sync and index:
 
-        ```bash
+        ```bash wrap icon="terminal" Create example config
         touch config.json
         echo '{
             "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
@@ -58,7 +58,7 @@ Watch this 1:51 minute video to get a quick overview of how to deploy Sourcebot
 
         In the same directory as `config.json`, run the following command to start your instance:
 
-        ``` bash
+        ``` bash icon="terminal" Start the Sourcebot container
         docker run \
             -p 3000:3000 \
             --pull=always \

packages/db/prisma/migrations/20250617031335_add_audit_table/migration.sql

@@ -0,0 +1,21 @@
+-- CreateTable
+CREATE TABLE "Audit" (
+    "id" TEXT NOT NULL,
+    "timestamp" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "action" TEXT NOT NULL,
+    "actorId" TEXT NOT NULL,
+    "actorType" TEXT NOT NULL,
+    "targetId" TEXT NOT NULL,
+    "targetType" TEXT NOT NULL,
+    "sourcebotVersion" TEXT NOT NULL,
+    "metadata" JSONB,
+    "orgId" INTEGER NOT NULL,
+
+    CONSTRAINT "Audit_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "Audit_actorId_actorType_targetId_targetType_orgId_idx" ON "Audit"("actorId", "actorType", "targetId", "targetType", "orgId");
+
+-- AddForeignKey
+ALTER TABLE "Audit" ADD CONSTRAINT "Audit_orgId_fkey" FOREIGN KEY ("orgId") REFERENCES "Org"("id") ON DELETE CASCADE ON UPDATE CASCADE;

packages/db/prisma/schema.prisma

@@ -172,6 +172,8 @@ model Org {
   /// List of pending invites to this organization
   invites Invite[]
 
+  audits Audit[]
+
   accountRequests AccountRequest[]
 
   searchContexts SearchContext[]
@@ -227,6 +229,24 @@ model ApiKey {
 
 }
 
+model Audit {
+  id String @id @default(cuid())
+  timestamp DateTime @default(now())
+
+  action String
+  actorId String
+  actorType String
+  targetId String
+  targetType String
+  sourcebotVersion String
+  metadata Json?
+
+  org   Org @relation(fields: [orgId], references: [id], onDelete: Cascade)
+  orgId Int
+
+  @@index([actorId, actorType, targetId, targetType, orgId])
+}
+
 // @see : https://authjs.dev/concepts/database-models#user
 model User {
   id              String      @id @default(cuid())

packages/shared/src/entitlements.ts

@@ -36,15 +36,16 @@ const entitlements = [
     "public-access",
     "multi-tenancy",
     "sso",
-    "code-nav"
+    "code-nav",
+    "audit"
 ] as const;
 export type Entitlement = (typeof entitlements)[number];
 
 const entitlementsByPlan: Record<Plan, Entitlement[]> = {
     oss: [],
     "cloud:team": ["billing", "multi-tenancy", "sso", "code-nav"],
-    "self-hosted:enterprise": ["search-contexts", "sso", "code-nav"],
-    "self-hosted:enterprise-unlimited": ["search-contexts", "public-access", "sso", "code-nav"],
+    "self-hosted:enterprise": ["search-contexts", "sso", "code-nav", "audit"],
+    "self-hosted:enterprise-unlimited": ["search-contexts", "public-access", "sso", "code-nav", "audit"],
     // Special entitlement for https://demo.sourcebot.dev
     "cloud:demo": ["public-access", "code-nav", "search-contexts"],
 } as const;