From 688d8ff6630fc815cc885447390a268a3b71e129 Mon Sep 17 00:00:00 2001 From: Petri-Johan Last Date: Fri, 4 Oct 2024 15:14:54 +0200 Subject: [PATCH 1/4] Add docs for Perforce IP enforcement --- docs/admin/repo/perforce.mdx | 41 +++++++++++++++++++++++++++++------- 1 file changed, 33 insertions(+), 8 deletions(-) diff --git a/docs/admin/repo/perforce.mdx b/docs/admin/repo/perforce.mdx index eee953679..8119537e3 100644 --- a/docs/admin/repo/perforce.mdx +++ b/docs/admin/repo/perforce.mdx @@ -60,7 +60,7 @@ Sourcegraph will now talk to the Perforce host and sync the configured `depots` It's worthwhile to note some limitations of this process: -- When syncing depots either [git p4](https://git-scm.com/docs/git-p4) or [p4-fusion](https://github.com/salesforce/p4-fusion) (recommended) are used to convert Perforce depots into git repositories so that Sourcegraph can index them. +- When syncing depots [p4-fusion](https://github.com/salesforce/p4-fusion) is used to convert Perforce depots into git repositories so that Sourcegraph can index them. - Rename of a Perforce depot, including changing the depot on the Perforce server or the `repositoryPathPattern` config option, will cause a re-import of the depot. - Unless [permissions syncing](#repository-permissions) is enabled, Sourcegraph is not aware of the depot permissions, so it can't enforce access restrictions. @@ -126,11 +126,11 @@ If file-level permissions is not enabled, Sourcegraph provides limited support f ### File-level permissions -File-level permissions make the [syncing of subdirectories to match permission boundaries](#syncing-subdirectories-to-match-permission-boundaries) unnecessary. +File-level permissions eliminate the need for [syncing subdirectories to match permission boundaries](#syncing-subdirectories-to-match-permission-boundaries). To enable file-level permissions: -1. Enable [the feature in the site config](https://sourcegraph.com/github.com/sourcegraph/sourcegraph@2a716bd/-/blob/schema/site.schema.json?L227-249): +1. Add the following entry to your [site configuration file](https://sourcegraph.com/github.com/sourcegraph/sourcegraph@2a716bd/-/blob/schema/site.schema.json?L227-249): ```json { @@ -150,11 +150,36 @@ To enable file-level permissions: } ``` -1. Save the configuration. Permissions will be synced in the background based on your [Perforce protects file](https://www.perforce.com/manuals/cmdref/Content/CmdRef/p4_protect.html). +1. Save the configuration. -#### Handling Host rules in the protects file +Permissions will be synced in the background based on your [Perforce protects file](https://www.perforce.com/manuals/cmdref/Content/CmdRef/p4_protect.html). -When file-level permissions are enabled, Sourcegraph will read the Perforce protects file to determine what users can access. Because Sourcegraph originates all depot access from one host, protects rules with a Host field cannot be followed exactly. By default, they are parsed as if they apply to all hosts, which can result in users losing access when they should have access. If you have protects rules with hosts that are causing lost access for users, you can set `ignoreRulesWithHost` to `true` in the code host configuration. +#### Handling host rules in the protects file + +By default, Sourcegraph applies all rules in the protects table regardless of the host rule (treating all host rules as the wildcard `*`). If your setup relies heavily on host rules, this could lead to unintended permissions for users. + +You have two options if the default behavior is not suitable: + +1. Enforce host rules +1. Ignore rules that have a host value other than `*` + +##### Enforcing host rules + +To enforce host-specific rules, modify your [site configuration](https://sourcegraph.com/github.com/sourcegraph/sourcegraph@2a716bd/-/blob/schema/site.schema.json?L227-249) as follows: + + ```json + { + "experimentalFeatures": { + "subRepoPermissions": { "enabled": true, "enforceIPRestrictions": true } + } + } + ``` + +When `enforceIPRestrictions` is set to `true`, Sourcegraph will use the user's IP address to apply Perforce permissions at the user level. It uses the final `X-Forwarded-For` header in the request to identify the user's IP. Note that this header can be easily spoofed, so ensure your load balancer or proxy handles `X-Forwarded-For` headers securely. + +##### Ignore rules with host + +To ignore rules that have a host value other than `*`, set `ignoreRulesWithHost` to `true` in your **code host configuration**: ```json { @@ -165,12 +190,13 @@ When file-level permissions are enabled, Sourcegraph will read the Perforce prot } ``` +With this setting, Sourcegraph will ignore any rules with a host other than `*`, treating them as if they do not exist. + ### Notes about permissions - Sourcegraph users are mapped to Perforce users based on their verified email addresses. - As long as a user has been granted at least `Read` permissions in Perforce they will be able to view content in Sourcegraph. - As a special case, commits in which a user does not have permissions to read any files are hidden. If a user can read a subset of files in a commit, only those files are shown. -- [The host field from protections are not supported](#known-issues-and-limitations). - [file-level permissions must be disabled for Batch Changes to work](#known-issues-and-limitations). - Setting `authz.enforceForSiteAdmins` to `true` in the site configuration will enforce permissions for admin users. They may not be able to see repositories and their contents if their Sourcegraph user account email does not match with their email on the Perforce server. @@ -228,7 +254,6 @@ When file-level permissions are enabled, Sourcegraph will read the Perforce prot We are actively working to significantly improve Sourcegraph's Perforce support. Please [file an issue](https://github.com/sourcegraph/sourcegraph/issues) to help us prioritize any specific improvements you'd like to see. - Sourcegraph was initially built for Git repositories only, so it stores Perforce depots as Git repositories when syncing. Perforce concepts and languages are expressed in the UI, but under the hood, Git tools are used. -- The [host field](https://www.perforce.com/manuals/cmdref/Content/CmdRef/p4_protect.html#Form_Fields_..361) in protections is not supported. - Batch Changes does not support [file-level permissions](#file-level-permissions) (also known as sub-repo permissions) - Batch Changes does not handle the shelved changelist other than to query the Perforce server for its status. - Permalinks with Changelist Id do not work yet From 88631eb020511c407d0330ab5108f4d9a5bce003 Mon Sep 17 00:00:00 2001 From: Petri-Johan Last Date: Tue, 8 Oct 2024 13:36:47 +0200 Subject: [PATCH 2/4] Slight rewording --- docs/admin/repo/perforce.mdx | 52 +++++++++++++++++++++++------------- 1 file changed, 34 insertions(+), 18 deletions(-) diff --git a/docs/admin/repo/perforce.mdx b/docs/admin/repo/perforce.mdx index 8119537e3..8c4a00565 100644 --- a/docs/admin/repo/perforce.mdx +++ b/docs/admin/repo/perforce.mdx @@ -154,26 +154,42 @@ To enable file-level permissions: Permissions will be synced in the background based on your [Perforce protects file](https://www.perforce.com/manuals/cmdref/Content/CmdRef/p4_protect.html). -#### Handling host rules in the protects file +#### Handling IP-based rules -By default, Sourcegraph applies all rules in the protects table regardless of the host rule (treating all host rules as the wildcard `*`). If your setup relies heavily on host rules, this could lead to unintended permissions for users. +Perforce's `protects` table allows administrators to define fine-grained access controls based on user identities and host IP addresses. By default, Sourcegraph applies all rules from the `protects` table without considering host-specific restrictions, effectively treating all host rules as the wildcard `*`. This behavior can lead to users having unintended access to repositories or files that should be restricted based on their IP addresses. -You have two options if the default behavior is not suitable: +If your Perforce environment relies heavily on host-based permissions, it's crucial to configure Sourcegraph appropriately to respect these restrictions. This documentation provides detailed instructions on how to enforce or ignore host rules in Sourcegraph when integrating with Perforce. -1. Enforce host rules -1. Ignore rules that have a host value other than `*` +##### Default Behavior + +By default, Sourcegraph: + +- **Applies all rules** in the Perforce `protects` table. +- **Ignores host-specific restrictions**, treating all host fields as `*`. + +**Implication**: Users may gain access to resources that should be restricted based on their IP addresses. + +##### Configuration Options + +To ensure Sourcegraph handles host rules according to your requirements, you have two additional options: + +1. **Enforce Host Rules**: Configure Sourcegraph to respect and enforce IP-based restrictions defined in the `protects` table. +2. **Ignore Host-Specific Rules**: Configure Sourcegraph to disregard any rules with a host value other than `*`. ##### Enforcing host rules -To enforce host-specific rules, modify your [site configuration](https://sourcegraph.com/github.com/sourcegraph/sourcegraph@2a716bd/-/blob/schema/site.schema.json?L227-249) as follows: +If you want Sourcegraph to enforce host-specific permissions, you need to enable IP restriction enforcement in your [site configuration](https://sourcegraph.com/docs/admin/config/site_config): - ```json - { - "experimentalFeatures": { - "subRepoPermissions": { "enabled": true, "enforceIPRestrictions": true } - } +```json +{ + "experimentalFeatures": { + "subRepoPermissions": { + "enabled": true, + "enforceIPRestrictions": true } - ``` + } +} +``` When `enforceIPRestrictions` is set to `true`, Sourcegraph will use the user's IP address to apply Perforce permissions at the user level. It uses the final `X-Forwarded-For` header in the request to identify the user's IP. Note that this header can be easily spoofed, so ensure your load balancer or proxy handles `X-Forwarded-For` headers securely. @@ -182,12 +198,12 @@ When `enforceIPRestrictions` is set to `true`, Sourcegraph will use the user's I To ignore rules that have a host value other than `*`, set `ignoreRulesWithHost` to `true` in your **code host configuration**: ```json - { - "authorization": { - "subRepoPermissions": true, - "ignoreRulesWithHost": true - } - } +{ + "authorization": { + "subRepoPermissions": true, + "ignoreRulesWithHost": true + } +} ``` With this setting, Sourcegraph will ignore any rules with a host other than `*`, treating them as if they do not exist. From 9e93c33dbb9ff6fdbfed3f121d83dafb26fce74a Mon Sep 17 00:00:00 2001 From: ggilmore Date: Thu, 17 Oct 2024 04:00:18 -0700 Subject: [PATCH 3/4] update note --- docs/admin/repo/perforce.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/admin/repo/perforce.mdx b/docs/admin/repo/perforce.mdx index 8c4a00565..5e2f590d9 100644 --- a/docs/admin/repo/perforce.mdx +++ b/docs/admin/repo/perforce.mdx @@ -190,8 +190,9 @@ If you want Sourcegraph to enforce host-specific permissions, you need to enable } } ``` - + When `enforceIPRestrictions` is set to `true`, Sourcegraph will use the user's IP address to apply Perforce permissions at the user level. It uses the final `X-Forwarded-For` header in the request to identify the user's IP. Note that this header can be easily spoofed, so ensure your load balancer or proxy handles `X-Forwarded-For` headers securely. + ##### Ignore rules with host From b1b53638d157b731fde6e5374f144d004a3ae219 Mon Sep 17 00:00:00 2001 From: Petri-Johan Last Date: Fri, 18 Oct 2024 10:30:17 +0200 Subject: [PATCH 4/4] Change from note to warning --- docs/admin/repo/perforce.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/repo/perforce.mdx b/docs/admin/repo/perforce.mdx index 5e2f590d9..f20e8811c 100644 --- a/docs/admin/repo/perforce.mdx +++ b/docs/admin/repo/perforce.mdx @@ -190,7 +190,7 @@ If you want Sourcegraph to enforce host-specific permissions, you need to enable } } ``` - + When `enforceIPRestrictions` is set to `true`, Sourcegraph will use the user's IP address to apply Perforce permissions at the user level. It uses the final `X-Forwarded-For` header in the request to identify the user's IP. Note that this header can be easily spoofed, so ensure your load balancer or proxy handles `X-Forwarded-For` headers securely.