Docs for Sourcegraph version 5.4

docs.config.js

@@ -1,5 +1,5 @@
 const config = {
-	DOCS_LATEST_VERSION: '5.3'
+	DOCS_LATEST_VERSION: '5.4'
 };
 
 module.exports = config;

docs/versioned/5.3/admin/access_control/batch_changes.mdx

@@ -0,0 +1,8 @@
+# Access control for Batch Changes
+
+Granular controls for who can access [Batch Changes](/batch_changes/) can be configured by site admins by tuning the roles assigned to users and the permissions granted to those roles. This page describes the permission types available for Batch Changes, and whether they are granted by default to the **User** [system role](/admin/access_control#system-roles). All permissions are granted to the **Site Administrator** system role by default.
+
+        Name          |                                                                                                                    Description                                                                                                                     | Granted to **User** by default?
+--------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----------------------------:
+`batch_changes:read`  | **_Coming soon!_**                                                                                                                                                                                                                                 |                ✓
+`batch_changes:write` | <ul><li>User can create, update, close, or delete batch changes.</li><li>User can create, execute, and apply batch specs.</li><li>User can perform bulk operations on changesets such as publishing, commenting on, closing, or merging them.</li></ul> |                ✓

docs/versioned/5.3/admin/access_control/index.mdx

@@ -0,0 +1,57 @@
+# Access control
+
+<Callout type="info">This feature is in Beta stage.</Callout>
+
+> NOTE: This page refers to in-product permissions, which determine who can, for example, create a batch change, or who is a site admin. This is *not* the same as [repository permissions](/admin/permissions/), which enforces the same repository access on Sourcegraph as your code host.
+
+> NOTE: Feature supported on Sourcegraph versions 5.0+
+
+Sourcegraph uses [Role-Based Access Control (RBAC)](https://en.wikipedia.org/wiki/Role-based_access_control) to enable fine-grained control over different features and abilities of Sourcegraph, without having to modify permissions for each user individually. Currently, the scope of permissions control is limited to [Batch Changes](/admin/access_control/batch_changes) functionality, but it will be expanded to other areas in the future.
+
+## Managing roles and permissions
+
+<img alt="Role management page" src="https://sourcegraphstatic.com/docs/images/administration/access_control/managing_roles_permissions_dark.png" />
+
+Site admins can control which features each type of user has access to by creating custom roles and assigning permissions to them. You can see all available roles and create new ones under **Site admin > Users & auth > Roles**.
+
+### System roles
+
+Every Sourcegraph instance ships with two built-in system roles:
+
+- **Site Administrator**: This role is granted to any user who is promoted to site admin. It always has all features and permissions of Sourcegraph granted to it and the set of permissions cannot be modified.
+- **User:** This role is granted to every user of the Sourcegraph instance and cannot be unassigned. By default, it has all features and permissions of Sourcegraph granted to it, but _the set of permissions can be modified_.
+
+### Creating a new role and assigning it permissions
+
+To create a new role, click the **+ Create role** button. Give the role a unique, descriptive name, then select which permissions to associate with it using the checkboxes. Then click **Create**.
+
+### Editing permissions for an existing role
+
+> NOTE: The **Site Administrator** role cannot be modified.
+
+To edit the permissions granted to a role, click the role to expand it, then select the new set of permissions you want to grant to it. Then click **Update** to save your changes.
+
+You can read about the specific permission types available for each RBAC-enabled product area below:
+
+- [Batch Changes](/admin/access_control/batch_changes)
+- [Ownership](/admin/access_control/ownership)
+
+### Deleting a role
+
+> NOTE: Built-in system roles cannot be deleted.
+
+To delete a role, click the **Delete** button on it. You will be prompted to confirm your choice. Once deleted, all users previously assigned that role will lose all permissions associated with it. Be aware, though, that the same permissions could still be granted by their other roles.
+
+## Managing user roles
+
+> NOTE: Built-in system roles cannot be assigned this way.
+
+Site admins can manage which roles are assigned to which users from **Site admin > Users & auth > Users**. To view or edit a user's roles, click the triple dots to open the context menu for that user, then click **Manage roles**. This will open a modal dialog where you can see the user's current roles, assign new ones, or unassign current ones. You can type in the input field to search roles by name. Click **Update** to save any changes, or **Cancel** to discard. Note that system roles cannot be revoked or assigned via this modal.
+
+To assign the **Site Administrator** system role to a user, open the same context menu from the triple dots, then click **Promote to site admin**. To unassign the **Site Administrator** role, open the same context menu from the triple dots, then click **Revoke site admin**.
+
+The **User** system role is automatically assigned to all users and cannot be revoked.
+
+<video width="1920" height="1080" loop playsInline controls style={{ width: '100%', height: 'auto' }}>
+  <source src="https://storage.googleapis.com/sourcegraph-assets/docs/images/administration/access_control/assign_roles_to_user_dark.mp4" type="video/mp4"/>
+</video>

docs/versioned/5.3/admin/access_control/ownership.mdx

@@ -0,0 +1,7 @@
+# Access control for Ownership
+
+Granular controls for who can assign [Ownership](/own/) can be configured by site admins by tuning the roles assigned to users and the permissions granted to those roles. This page describes the permission types available for Ownership, and whether they are granted by default to the **User** [system role](/admin/access_control/#system-roles). All permissions are granted to the **Site Administrator** system role by default.
+
+Name      | Description | Granted to **User** by default?
+--------- | ----------- | :-:
+`ownerships:assign` | Assign ownership to users and teams on repository, directory and file levels | ✗

docs/versioned/5.3/admin/analytics.mdx

@@ -0,0 +1,43 @@
+# Analytics
+
+The analytics section helps Sourcegraph administrators understand user engagement across the various Sourcegraph features, identify power users, and convey value to internal leaders. Introduced in version 3.42, the section includes analytics breakdowns for our most common features such as Batch Changes, Search Notebooks and search, while also providing basic user-level analytics.
+
+## Data Visualizations
+
+The goal of these pages is to help administrators answer any question they might have about how features are being used within their Sourcegraph instance. So far, we have introduced pages for Search, Batch Changes, Code Intel, Search, and Search Notebooks, as well as a general users page.
+
+Each page can visualize the past one week, the past one month, or the path three months of data. For graphs that show user data, the graph can toggle between total users or unique users.
+
+These graphs pull directly from the event log table within the Sourcegraph instance they are running. There should not be an increase to the storage on disk of these tables due to these new features. Further, no data beyond published ping data is sent back to Sourcegraph.
+
+## Value Calculators
+
+Each page also includes a total time saved value which can be used to measure the value Sourcegraph is bringing to your organization. This metric is derived from the configurable calculators below the total time saved value. Each calculator multiplies event log data (ex: number of precise code intel events such as a go-to-definition) by a configurable number of minutes saved per event to arrive at a time saved by the feature.
+
+We designed this to be configurable by you because we want to...
+- help admins understand the value that is being seen by their organization today.
+- be customizable so admins can explore what changes will best increase developer time saved.
+
+These calculators exist on the Search, Code Intel, Batch Changes, and Notebooks analytics pages. Each calculator looks different as they include metrics specifically designed for that part of the application. Please note that the calculator configuration does not save and will return to the default if you navigate away from the page.
+
+If you have questions about how this works or about how to convey this value to leaders within your organization, please do not hesitate to reach out to your customer engineer.
+
+## FAQ
+
+**Who has access to see these improved analytics? Where can I find it?**
+
+To see these new visualizations, you must be a site admin. You can find these under Site Admin section, under the Analytics section of the left-nav bar.
+
+**Do these improved analytics require sending data to Sourcegraph?**
+
+No! The processing happens entirely within a your instance so no data is sent in or out of your instance. Further, these improved analytics leverage data already being captured within the event log table of your instance so there is no additional storage or processing required for this change. Basically, customers should notice no perceivable difference to their infrastructure.
+
+**How often is the data updated?**
+
+The data is updated approximately every 24 hours.
+
+**How does this work with the existing usage stats page?**
+
+This new analytics experience has been redesigned from the ground up to provide the most value to administrators. In the future, we plan to deprecate the legacy usage stats page and statistics section once this functionality moved from experimental to generally available.
+
+Note: The new analytics experience is experimental. For billing information, use [usage stats](/admin/usage_statistics).

docs/versioned/5.3/admin/audit_log.mdx

@@ -0,0 +1,164 @@
+# Audit Log
+
+## Philosophy
+
+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://sourcegraph.com/docs/dev/how-to/add_logging), using structured logs as the base building block. Every captured entry is aligned with the following design mantra:
+
+> Actor takes action on an entity within a context
+
+Here's a sample audit log entry:
+
+```
+{
+  "SeverityText": "INFO",
+  "Timestamp": 1667210919544146000,
+  "InstrumentationScope": "server.SecurityEvents",
+  "Caller": "audit/audit.go:43",
+  "Function": "github.com/sourcegraph/sourcegraph/internal/audit.Log",
+  "Body": "AccessGranted (sampling immunity token: 7aacf0e8-d001-4aec-8b7d-20e46d34c8db)",
+  "Resource": {
+    "service.name": "frontend",
+    "service.version": "0.0.0+dev",
+    "service.instance.id": "Michals-MacBook-Pro-2.local"
+  },
+  "Attributes": {
+    "audit": {
+      "auditId": "7aacf0e8-d001-4aec-8b7d-20e46d34c8db",
+      "entity": "security events",
+      "actor": {
+        "actorUID": "1",
+        "ip": "127.0.0.1",
+        "X-Forwarded-For": "127.0.0.1, 127.0.0.1"
+      }
+    },
+    "event": {
+      "URL": "",
+      "source": "BACKEND",
+      "argument": "{\"resource\":\"db.repo\",\"service\":\"frontend\",\"repo_ids\":[9]}",
+      "version": "0.0.0+dev",
+      "timestamp": "2022-10-31 10:08:39.542876 +0000 UTC"
+    }
+  }
+}
+```
+
+Here's a word-by-word breakout to demonstrate how the captured entry aligns with the design mantra:
+
+- **Actor** - `Attributes.audit.actor` field carries essential information about the actor who performed the action.
+- **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).
+- **Entity** - `Attributes.audit.entity` describes the audited entity. `Resource` field contains additional information about the audited resource as well.
+- **Context** - Any non-`audit` child node of `Attributes`. This is represented by the `event` node in the example above.
+
+### What is audited?
+
+- [Security events](./security_event_logs)
+- [Gitserver access](https://sourcegraph.com/github.com/sourcegraph/sourcegraph/-/blob/cmd/gitserver/internal/accesslog/accesslog.go?L100-104)
+- [GraphQL requests](https://sourcegraph.com/github.com/sourcegraph/sourcegraph/-/blob/cmd/frontend/internal/httpapi/graphql.go?L226-244)
+
+This list is expected to grow in the future.
+
+### Target audience
+
+Security specialists. We expect these to ingest the logs into their SIEM tools and define alert policies as they see fit. Site admins are currently not the target audience, but we'll likely offer an easy-to-use in-app audit log.
+
+## Configuring
+
+The audit log is currently configured using the site config. Here's the corresponding entry:
+
+```
+  "log": {
+    "auditLog": {
+      "internalTraffic": false,
+      "graphQL": false,
+      "gitserverAccess": false,
+      "severityLevel": "INFO" // DEPRECATED, defaults to SRC_LOG_LEVEL
+    }
+    "securityEventLog": {
+     "location": "auditlog" // option to set "database" or "all" as well, default to outputing as an audit log
+  }
+```
+
+We believe the individual settings are self-explanatory, but here are a couple of notes:
+
+- `securityEventLog` configures the destination of security events, logging to the database may result in performance issues
+- `internalTraffic` is disabled by default and will result in security events from internal traffic not being logged
+
+## Using
+
+Audit logs are structured logs. As long as one can ingest logs, we assume one can also ingest audit logs.
+
+### On Premises
+
+There are two easy approaches to filtering the audit logs:
+
+- 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`.
+- 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`.
+
+### Cloud
+[Cloud](/cloud/#audit-logs)
+
+
+Audit Logs are a default feature for Cloud instances, with a standard retention policy of 30 days. Should you wish to
+extend this period, please be aware that additional charges will apply. To request an extension, please contact
+your assigned Customer Engineer (CE) or send an email to Sourcegraph Support at support@sourcegraph.com.
+
+For requesting audit logs, please follow the above steps and contact your assigned Sourcegraph representative or our support team.
+
+
+## Developing
+
+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.
+
+Example call:
+```
+audit.Log(ctx, logger, audit.Record{
+  Entity: "security events",
+  Action: string(event.Name),
+  Fields: []log.Field{
+    log.Object("event",
+      log.String("URL", event.URL),
+    ),
+  },
+})
+```
+- audit log checks the current settings via the cached `schema.SiteConfiguration`
+- `ctx` parameter is required for acquiring `actor.Actor` and `requestclient.Client`
+- `logger` parameter is used for performing the actual log call
+- `audit.Record` carries all the information required for constructing a valid audit log entry
+
+## FAQ
+
+**How do I map actor ID to the Sourcegraph user?**
+
+The `audit.actor` node carries ID of the user who performed the action (`actorUID`), but it’s not mapped into a full Sourcegraph user right now. You can, however, obtain the user details by following these steps:
+
+1. Grab the user ID from the audit log
+1. Base64 [encode](https://www.base64encode.org) the ID with a "User:" prefix. For example, for Actor with ID 71 use `User:71`, which encodes to `VXNlcjo3MQ==`
+1. Navigate to Site Admin -> API Console and run the query below
+1. Find the corresponding user by searching the query results for the encoded ID from above
+
+GraphQL query:
+```
+{
+  users {
+    nodes {
+      id
+      username
+    }
+  }
+}
+```
+
+### Excessive audit logging
+
+If you are seeing a large number of logs in the format `frontend.SecurityEvents` or similar, these are securityEventLogs.
+
+To disable them, in the site config set `log.securityEventLog.location` to `none`.
+
+```json
+ "log": {
+    "securityEventLog": {
+      "location": "none"
+    }
+}
+```