You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+6-4Lines changed: 6 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,8 @@
1
+
<!-- Working Branch for May Release -->
2
+
1
3
# Sourcegraph Docs
2
4
3
-
<!-- Working branch for SG 6.3 Release -->
5
+
<!-- Working branch for Sourcegraph 6.4 Release -->
4
6
5
7
Welcome to the Sourcegraph documentation! We're excited to have you contribute to our docs. We've recently rearchitectured our docs tech stack — powered by Next.js, TailwindCSS and deployed on Vercel. This guide will walk you through the process of contributing to our documentation using the new tech stack.
6
8
@@ -9,16 +11,16 @@ Welcome to the Sourcegraph documentation! We're excited to have you contribute t
9
11
To get started with this template, clone this repository to your local machine using the following command:
Service accounts are specialized user accounts designed for automation, API integrations, and programmatic access to Sourcegraph, as opposed to using access tokens from regular users. Unlike regular user accounts, service accounts don't require an email address or password, cannot access the Sourcegraph UI, don't count towards a license's user limit and won't be part of any billing cycles.
4
+
5
+
## Creating Service Accounts
6
+
7
+
Service accounts are created like regular user accounts, but with a few key differences.
8
+
9
+
- Go to **Site admin** → **Users & auth** → **Users**
10
+
- Click **Create User**
11
+
- Enter a descriptive **Username** (e.g., `ci-bot-scip-uploads`, `api-search-jobs`)
12
+
- Check the **Service account** checkbox
13
+
- Click **Create service account**
14
+
15
+
You'll be presented with some next steps you might want to take, like creating an access token, managing and assigning roles, and managing repository permissions.
16
+
17
+
- Service accounts are automatically assigned the "Service Account" system role
18
+
- They appear in the user list with "Service account" type designation
19
+
- By default, service accounts can only access public and unrestricted repositories
20
+
21
+
## Managing Access Tokens
22
+
23
+
Service accounts authenticate using access tokens rather than passwords. For detailed information about creating, managing, and using access tokens, see:
24
+
25
+
-[Creating an access token](/cli/how-tos/creating_an_access_token)
-[Revoking an access token](/cli/how-tos/revoking_an_access_token)
28
+
29
+
Use service account access tokens to access Sourcegraph's [GraphQL API](/api/graphql).
30
+
31
+
## Role-Based Access Control (RBAC)
32
+
33
+
Service accounts integrate with Sourcegraph's [role-based access control](/admin/access_control) to provide fine-grained permission control.
34
+
35
+
### System Roles
36
+
37
+
Service accounts are automatically assigned the **Service Account** system role, which provides basic API access permissions and standard search capabilities. The **Service Account** system role is applied to all service accounts and can be used to provide service accounts with a default set of permissions. For more specialized service accounts, it is recommended to create custom roles and assign them to service accounts as needed.
38
+
39
+
### Managing Roles
40
+
41
+
Administrators can assign additional roles to service accounts through the user management interface. For detailed information on managing roles and permissions, see:
42
+
43
+
-[Managing roles and permissions](/admin/access_control#managing-roles-and-permissions)
44
+
-[Managing user roles](/admin/access_control#managing-user-roles)
Service accounts respect repository permissions and access controls. For comprehensive information about repository permissions, see the [Repository permissions](/admin/permissions) documentation.
50
+
51
+
Service accounts by default can only access public and unrestricted repositories in Sourcegraph. You may explicitly grant fine-grained access to private repositories from the service account's user settings page, under the **Repo permissions** tab, or via [the GraphQL API](/admin/permissions/api#explicit-permissions-api). In the **Repo permissions** tab, you can also grant service accounts access to all current and future repositories on Sourcegraph, regardless of their visibility, which is useful for service accounts that need to do things like perform search jobs, but admins should take care to ensure that the access tokens for these accounts are not shared with unauthorized users.
The audit log will capture all critical events that affect entities of interest within Sourcegraph services. The audit log is built on top of our [logging standard](https://docs-legacy.sourcegraph.com/dev/how-to/add_logging), using structured logs as the base building block. Every captured entry is aligned with the following design mantra:
5
+
The audit log captures all critical events that affect entities of interest within Sourcegraph services. The audit log is built on top of our [logging standard](https://docs-legacy.sourcegraph.com/dev/how-to/add_logging), using structured logs as the base building block. Every captured entry is aligned with the following design mantra:
6
6
7
7
> Actor takes action on an entity within a context
Here's a word-by-word breakout to demonstrate how the captured entry aligns with the design mantra:
46
50
47
51
-**Actor** - `Attributes.audit.actor` field carries essential information about the actor who performed the action.
48
52
-**Action** - `Body` field carries the action description. This action is suffixed with a "sampling immunity token," which carries the unique audit log entry ID. The audit entry ID must be present in the `Body` so that the message is always unique and never gets dropped by the sampling mechanism (hence the sampling immunity token string).
49
-
-**Entity** - `Attributes.audit.entity` describes the audited entity.`Resource` field contains additional information about the audited resource as well.
50
-
-**Context** - Any non-`audit` child node of `Attributes`. This is represented by the `event` node in the example above.
53
+
-**Entity** - `Attributes.audit.entity` describes the audited entity.
54
+
-**Context** - Additional fields within the `audit` object provide context for the action.
51
55
52
56
### What is audited?
53
57
54
-
-**Security Events** - [A list of events](./security_event_logs) such as logins, site configuration updates, code host configuration updates (_These logs can be sent to the database for easier collection as well as to the standard output_).
55
-
-**Gitserver Access** - Requests to the [`gitserver`](./deploy/scale.mdx#gitserver) component that is responsible for brokering transactions between the git repos on disk and all other Sourcegraph components.
56
-
-**GraphQL Requests** - Requests To The Sourcegraph [`frontend`](./deploy/scale.mdx#frontend) component that is usually named `sourcegraph-frontend-{DYNAMICALLY CREATED ALPHANUMERIC}`
57
-
58
-
This list is expected to grow in the future.
58
+
The audit log captures a wide range of security-relevant events including:
@@ -73,54 +115,91 @@ The audit log is currently configured using the site config. Here's the correspo
73
115
"gitserverAccess": false,
74
116
"severityLevel": "INFO" // DEPRECATED, defaults to SRC_LOG_LEVEL
75
117
}
76
-
"securityEventLog": {
77
-
"location": "auditlog" // option to set "database" or "all" as well, default to outputing as an audit log
78
118
}
79
119
```
80
120
81
-
We believe the individual settings are self-explanatory, but here are a couple of notes:
82
-
83
-
-`securityEventLog` configures the destination of security events, logging to the database may result in performance issues
84
-
-`internalTraffic` is disabled by default and will result in security events from internal traffic not being logged
121
+
Configuration options:
122
+
-`internalTraffic`: When false (default), suppresses audit logs from internal system actors to reduce noise
123
+
-`graphQL`: Controls auditing of GraphQL API requests
124
+
-`gitserverAccess`: Controls auditing of gitserver access events
125
+
-`severityLevel`: DEPRECATED - audit log level now follows the global `SRC_LOG_LEVEL` environment variable
85
126
86
127
## Using
87
128
88
-
Audit logs are structured logs. As long as one can ingest logs, we assume one can also ingest audit logs.
129
+
Audit logs are structured logs delivered as JSON to STDERR. As long as one can ingest logs, we assume one can also ingest audit logs.
130
+
131
+
### Log Output
132
+
133
+
All audit logs are delivered to **STDERR** for each individual [component](./deploy/scale.mdx#core-components).
134
+
135
+
136
+
### Filtering Audit Logs
137
+
138
+
There are two approaches to filtering the audit logs:
89
139
90
-
### On Premises
140
+
-**JSON-based**: Look for the presence of the `Attributes.audit` node. Do not depend on the log level, as it can change based on `SRC_LOG_LEVEL`.
141
+
-**Message-based**: Filter based on the following string: `auditID` (note: this is the current field name, not `auditId`).
91
142
92
-
All logs mentioned are delivered to the standard output (stdout) for each individual [component](./deploy/scale.mdx#core-components).
143
+
### Important Fields for Filtering
93
144
145
+
Customers can filter audit logs using these key fields:
94
146
95
-
There are two easy approaches to filtering the audit logs:
147
+
#### Core Audit Fields
148
+
-`Attributes.audit.auditID`: Unique identifier for each audit event
149
+
-`Attributes.audit.entity`: The entity being acted upon (e.g., "user", "site.config")
150
+
-`Attributes.audit.action`: The action performed (e.g., "created", "modified", "deleted")
151
+
-`Attributes.audit.tenant`: Tenant ID for multi-tenant environments
96
152
97
-
- JSON-based: look for the presence of the `Attributes.audit` node. Do not depend on the log level, as it can change based on `SRC_LOG_LEVEL`.
98
-
- Message-based: we recommend going the JSON route, but if there's no easy way of parsing JSON using your SIEM or data processing stack, you can filter based on the following string: `auditId`.
153
+
#### Actor Information
154
+
-`Attributes.audit.actor.actorUID`: User ID of the actor performing the action
155
+
-`Attributes.audit.actor.ip`: IP address of the request
156
+
-`Attributes.audit.actor.fromAccessTokenID`: Access token ID if action performed via API
157
+
-`Attributes.audit.actor.sourcegraphOperator`: Boolean indicating if actor is a Sourcegraph operator
158
+
-`Attributes.audit.actor.userAgent`: User agent string from the request
159
+
-`Attributes.audit.actor.X-Forwarded-For`: Forwarded IP addresses
160
+
-`Attributes.audit.actor.X-Sourcegraph-API-Client-Name`: API client name
161
+
-`Attributes.audit.actor.X-Sourcegraph-API-Client-Version`: API client version
162
+
163
+
#### Timestamp and Service Information
164
+
-`Timestamp`: Event timestamp (nanoseconds since Unix epoch)
165
+
-`Resource.service.name`: Service that generated the audit log
166
+
-`Resource.service.version`: Version of the service
167
+
-`Body`: Human-readable action description with sampling immunity token
99
168
100
169
### Cloud
101
170
102
171
For Sourcegraph Cloud customers, please refer to Cloud [documentations](/cloud/#audit-logs).
103
172
104
173
## Developing
105
174
106
-
The single entry point to the audit logging API is made via the [`audit.Log`](https://sourcegraph.com/github.com/sourcegraph/sourcegraph/-/blob/internal/audit/audit.go?L19) function. This internal function can be used from any place in the app, and nothing else needs to be done for the logged entry to appear in the audit log.
175
+
The single entry point to the audit logging API is made via the `audit.Log` function. This internal function can be used from any place in the app, and nothing else needs to be done for the logged entry to appear in the audit log.
107
176
108
177
Example call:
109
-
```
178
+
```go
110
179
audit.Log(ctx, logger, audit.Record{
111
-
Entity: "security events",
112
-
Action: string(event.Name),
180
+
Entity: "user",
181
+
Action: "modified",
113
182
Fields: []log.Field{
114
-
log.Object("event",
115
-
log.String("URL", event.URL),
116
-
),
183
+
log.Int32("userID", userID),
184
+
log.String("operation", "updateProfile"),
117
185
},
118
186
})
119
187
```
120
-
- audit log checks the current settings via the cached `schema.SiteConfiguration`
121
-
-`ctx` parameter is required for acquiring `actor.Actor` and `requestclient.Client`
122
-
-`logger` parameter is used for performing the actual log call
123
-
-`audit.Record` carries all the information required for constructing a valid audit log entry
188
+
189
+
**Parameters:**
190
+
-`ctx`: Context parameter required for acquiring `actor.Actor` and `requestclient.Client`
191
+
-`logger`: Logger instance used for performing the actual log call
192
+
-`audit.Record`: Structure carrying all the information required for constructing a valid audit log entry
193
+
-`Entity`: Name of the audited entity
194
+
-`Action`: Description of the state change
195
+
-`Fields`: Additional context fields specific to the action
196
+
-`MustRecord`: Optional flag to bypass internal traffic filtering
197
+
198
+
The audit log system automatically:
199
+
- Checks current settings via cached `schema.SiteConfiguration`
200
+
- Extracts actor information from context
201
+
- Generates unique audit ID with sampling immunity
202
+
- Formats the log entry according to the structured format
124
203
125
204
## FAQ
126
205
@@ -134,7 +213,7 @@ The `audit.actor` node carries ID of the user who performed the action (`actorUI
134
213
1. Find the corresponding user by searching the query results for the encoded ID from above
135
214
136
215
GraphQL query:
137
-
```
216
+
```graphql
138
217
{
139
218
users {
140
219
nodes {
@@ -145,16 +224,9 @@ GraphQL query:
145
224
}
146
225
```
147
226
148
-
### Excessive audit logging
149
-
150
-
If you are seeing a large number of logs in the format `frontend.SecurityEvents` or similar, these are securityEventLogs.
227
+
**How do I reduce audit log volume?**
151
228
152
-
To disable them, in the site config set `log.securityEventLog.location` to `none`.
153
-
154
-
```json
155
-
"log": {
156
-
"securityEventLog": {
157
-
"location": "none"
158
-
}
159
-
}
160
-
```
229
+
To reduce audit log volume:
230
+
1. Set `log.auditLog.internalTraffic` to `false` (default) to suppress logs from internal system actors
231
+
2. Configure specific audit types (`graphQL`, `gitserverAccess`) based on your monitoring needs
232
+
3. Use log filtering at the ingestion level to focus on specific entities or actions
Copy file name to clipboardExpand all lines: docs/admin/auth/index.mdx
+4Lines changed: 4 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -29,6 +29,10 @@ The following methods are supported for sign up and sign in:
29
29
30
30
The authentication providers are configured in the [`auth.providers`](/admin/config/site_config#authentication-providers) site configuration option.
31
31
32
+
## Programmatic authentication
33
+
34
+
For automated systems, CI/CD pipelines, and API integrations that need to authenticate without human interaction, use [service accounts](/admin/access_control/service_accounts). Service accounts are specialized user accounts designed for automation that authenticate using access tokens rather than passwords.
35
+
32
36
## Login form configuration
33
37
34
38
To configure the presentation of the login form, see the [login form configuration page](/admin/auth/login_form).
0 commit comments