Skip to content

feat(audit-logging): Adds audit logging support #355

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 17 commits into from
Jun 18, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ 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)
<!-- @NOTE: this release includes a API change that affects the MCP package (@sourcebot/mcp). On release, bump the MCP package's version and delete this message. -->

### Fixed
Expand Down
3 changes: 2 additions & 1 deletion docs/docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,8 @@
]
},
"docs/configuration/transactional-emails",
"docs/configuration/structured-logging"
"docs/configuration/structured-logging",
"docs/configuration/audit-logs"
]
},
{
Expand Down
212 changes: 212 additions & 0 deletions docs/docs/configuration/audit-logs.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,212 @@
---
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
}
]
```

## Audit action types

| Action | Actor Type | Target Type |
| :------- | :------ | :------|
| `api_key.creation_failed` | `user` | `org` |
| `api_key.created` | `user` | `api_key` |
| `api_key.deletion_failed` | `user` | `org` |
| `api_key.deleted` | `user` | `api_key` |
| `user.creation_failed` | `user` | `user` |
| `user.owner_created` | `user` | `org` |
| `user.jit_provisioning_failed` | `user` | `org` |
| `user.jit_provisioned` | `user` | `org` |
| `user.join_request_creation_failed` | `user` | `org` |
| `user.join_requested` | `user` | `org` |
| `user.join_request_approve_failed` | `user` | `account_join_request` |
| `user.join_request_approved` | `user` | `account_join_request` |
| `user.join_request_removed` | `user` | `account_join_request` |
| `user.invite_failed` | `user` | `org` |
| `user.invites_created` | `user` | `org` |
| `user.invite_accept_failed` | `user` | `invite` |
| `user.invite_accepted` | `user` | `invite` |
| `user.signed_in` | `user` | `user` |
| `user.signed_out` | `user` | `user` |
| `org.ownership_transfer_failed` | `user` | `org` |
| `org.ownership_transferred` | `user` | `org` |
| `query.file_source` | `user \| api_key` | `file` |
| `query.code_search` | `user \| api_key` | `org` |
| `query.list_repositories` | `user \| api_key` | `org` |


## 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
}
}

```
1 change: 1 addition & 0 deletions docs/docs/configuration/environment-variables.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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> |
Expand Down
3 changes: 2 additions & 1 deletion docs/docs/configuration/structured-logging.mdx
Original file line number Diff line number Diff line change
@@ -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:
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/deployment-guide.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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 \
Expand Down
Original file line number Diff line number Diff line change
@@ -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;
20 changes: 20 additions & 0 deletions packages/db/prisma/schema.prisma
Original file line number Diff line number Diff line change
Expand Up @@ -172,6 +172,8 @@ model Org {
/// List of pending invites to this organization
invites Invite[]

audits Audit[]

accountRequests AccountRequest[]

searchContexts SearchContext[]
Expand Down Expand Up @@ -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())
Expand Down
7 changes: 4 additions & 3 deletions packages/shared/src/entitlements.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
Loading