Skip to content
Open
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
7 changes: 7 additions & 0 deletions config.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -367,6 +367,13 @@
}
}
}
},
"basicAuthHosts": {
"description": "Hostnames of self-hosted git servers that verify the Basic auth username and password themselves (e.g. via htpasswd or LDAP). For these hosts, GitProxy identifies the pusher by the Basic auth username once the server accepts the credentials. Do not list servers that accept any username alongside a token.",
"type": "array",
"items": {
"type": "string"
}
}
},
"definitions": {
Expand Down
11 changes: 10 additions & 1 deletion docs/Architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ Don't forget to save and update the attached .drawio (XML)! -->
Three types of policies can be applied to incoming pushes:

- Default policies: These are already present in the GitProxy pull/push chain and require modifying source code to change their behaviour.
- For example, [`checkUserPushPermission`](./Processors.md#checkuserpushpermission) which simply checks if the pusher's email exists in the GitProxy database, and if their user is marked in the "Contributors" list (`canPush`) for the repository they're trying to push to.
- For example, [`checkUserPushPermission`](./Processors.md#checkuserpushpermission) which authenticates the pusher from their git credentials, checks that they map to a GitProxy user (via `gitAccount`), and if their user is marked in the "Contributors" list (`canPush`) for the repository they're trying to push to.
- Configurable policies: These are policies that can be easily configured through the GitProxy config (`proxy.config.json` or a custom file).
- For example, [`checkCommitMessages`](./Processors.md#checkcommitmessages) which reads the configuration and matches the string patterns provided with the commit messages in the push in order to block it.
- Custom policies:
Expand All @@ -75,6 +75,7 @@ Action chains are a list of processors that a Git operation goes through before
Executed when a user makes a `git push` to GitProxy. These are the actions in `pushActionChain`, by order of execution:

- [`parsePush`](./Processors.md#parsepush)
- [`resolvePusher`](./Processors.md#resolvepusher)
- [`checkEmptyBranch`](./Processors.md#checkemptybranch)
- [`checkRepoInAuthorisedList`](./Processors.md#checkrepoinauthorisedlist)
- [`checkCommitMessages`](./Processors.md#checkcommitmessages)
Expand Down Expand Up @@ -344,6 +345,14 @@ This will limit the number of **requests made to the API** to 150 per minute.

Optionally, a `statusCode` and a `message` can be specified to override the default responses.

#### `basicAuthHosts`

Hostnames (optionally with port) of self-hosted git servers that verify the Basic auth username and password themselves, such as servers backed by htpasswd or LDAP. For pushes to these hosts, GitProxy checks that the server rejects anonymous `git-receive-pack` discovery and accepts it with the push credentials, and then identifies the pusher by the Basic auth username, which must match a GitProxy user's `gitAccount`. This setting takes precedence over the GitHub/GitLab API lookup for the listed hosts. Pushes to hosts that are neither GitHub, GitLab nor listed here are blocked. Never list a server that accepts any username alongside a token.

```json
"basicAuthHosts": ["git.internal.example.com"]
```

#### `privateOrganizations` (deprecated)

Formerly used to block organizations, replaced by `commitConfig.diff.block.providers`.
Expand Down
24 changes: 20 additions & 4 deletions docs/Processors.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,15 +78,31 @@ Note that invalid regex patterns will throw an error during proxy startup. These

Source: [/src/proxy/processors/push-action/checkAuthorEmails.ts](/src/proxy/processors/push-action/checkAuthorEmails.ts)

#### `resolvePusher`

Runs right after `parsePush` (and before any push plugins). Resolves the authenticated pusher in the same way as [`checkUserPushPermission`](#checkuserpushpermission) and, if exactly one GitProxy user matches, sets `action.user` and `action.userEmail` so that plugins see a trusted identity. It never blocks the push; enforcement happens in `checkUserPushPermission`.

Source: [/src/proxy/processors/push-action/resolvePusher.ts](/src/proxy/processors/push-action/resolvePusher.ts)

#### `checkUserPushPermission`

Checks if the push has a valid user email associated to it (the email of the user making the push, **not the individual commit authors**), and if that user is allowed to push to that specific repo.
Authenticates the pusher from the credentials presented to the proxy (the HTTP Basic `Authorization` header sent by the git client) and checks that the matching GitProxy user is allowed to push to that specific repo. Commit metadata in the pack (e.g. the committer email) is **never** used to identify the pusher, since it is fully controlled by the client.

The pusher's SCM account is resolved as follows:

- `github.com`: the token owner's `login` from `GET https://api.github.com/user`
- GitLab hosts (hostname contains `gitlab`): the token owner's `username` from `GET <host>/api/v4/user`
- Hosts listed in the `basicAuthHosts` configuration (self-hosted servers that verify the Basic auth username and password themselves): the Basic auth username, once the server rejects anonymous `git-receive-pack` discovery on the repository and accepts it with the push credentials (checked before the GitHub/GitLab rules)
- Any other git server: the push is blocked, since the Basic auth username alone does not prove who owns the credentials

The SCM account is then matched (case-insensitively) against the `gitAccount` of GitProxy users. On success, `action.user` and `action.userEmail` are set to that GitProxy user's username and email; these are what the dashboard uses to prevent a reviewer from approving or rejecting their own push.

This step will fail on various scenarios such as:

- Push has no email associated to it (potentially a push parsing error)
- The email associated to the push matches multiple GitProxy users
- The user with the given email isn't in the repo's contributor list (`canPush`)
- The push has no valid Basic credentials, the SCM provider cannot resolve the token owner, or the host is not GitHub/GitLab or listed in `basicAuthHosts`
- The SCM account matches multiple GitProxy users
- No GitProxy user has that SCM account as their `gitAccount`
- The user isn't in the repo's contributor (`canPush`) or approver (`canAuthorise`) list

Note: The _pusher_ can potentially be a different user from the _commit author(s)_. In order to filter the commit authors, you must use the `commitConfig.author` config entry. See [`checkAuthorEmails`](#checkauthoremails) for more details.

Expand Down
8 changes: 8 additions & 0 deletions src/config/generated/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,13 @@ export interface GitProxyConfig {
* List of repositories that are authorised to be pushed to through the proxy.
*/
authorisedList?: AuthorisedRepo[];
/**
* Hostnames of self-hosted git servers that verify the Basic auth username and password
* themselves (e.g. via htpasswd or LDAP). For these hosts, GitProxy identifies the pusher
* by the Basic auth username once the server accepts the credentials. Do not list servers
* that accept any username alongside a token.
*/
basicAuthHosts?: string[];
/**
* Block commits based on rules defined over author/committer e-mail addresses, commit
* message content and diff content
Expand Down Expand Up @@ -763,6 +770,7 @@ const typeMap: any = {
typ: u(undefined, a(r('AuthenticationElement'))),
},
{ json: 'authorisedList', js: 'authorisedList', typ: u(undefined, a(r('AuthorisedRepo'))) },
{ json: 'basicAuthHosts', js: 'basicAuthHosts', typ: u(undefined, a('')) },
{ json: 'commitConfig', js: 'commitConfig', typ: u(undefined, r('CommitConfig')) },
{ json: 'configurationSources', js: 'configurationSources', typ: u(undefined, 'any') },
{ json: 'contactEmail', js: 'contactEmail', typ: u(undefined, '') },
Expand Down
5 changes: 5 additions & 0 deletions src/config/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -307,6 +307,11 @@ export const getDomains = () => {
return config.domains || {};
};

export const getBasicAuthHosts = (): string[] => {
const config = loadFullConfiguration();
return config.basicAuthHosts || [];
};

export const getUIRouteAuth = () => {
const config = loadFullConfiguration();
return config.uiRouteAuth || {};
Expand Down
5 changes: 3 additions & 2 deletions src/proxy/chain.ts
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ import { handleErrorAndLog } from '../utils/errors';

const pushActionChain: ((req: Request, action: Action) => Promise<Action>)[] = [
proc.push.parsePush,
proc.push.resolvePusher,
proc.push.checkEmptyBranch,
proc.push.checkRepoInAuthorisedList,
proc.push.checkCommitMessages,
Expand Down Expand Up @@ -111,8 +112,8 @@ export const getChain = async (
);
for (const pluginObj of chainPluginLoader.pushPlugins) {
console.log(`Inserting push plugin ${pluginObj.constructor.name} into chain`);
// insert custom functions after parsePush but before other actions
pushActionChain.splice(1, 0, pluginObj.exec);
// insert custom functions after parsePush and resolvePusher but before other actions
pushActionChain.splice(2, 0, pluginObj.exec);
}
for (const pluginObj of chainPluginLoader.pullPlugins) {
console.log(`Inserting pull plugin ${pluginObj.constructor.name} into chain`);
Expand Down
52 changes: 35 additions & 17 deletions src/proxy/processors/push-action/checkUserPushPermission.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,72 +18,90 @@ import { Request } from 'express';

import { Action, Step } from '../../actions';
import { getUsers, isUserPushAllowed } from '../../../db';
import { User } from '../../../db/types';
import { getVerifiedGitAccount } from '../pusherIdentity';

// Execute if the repo is approved
const exec = async (_req: Request, action: Action): Promise<Action> => {
const exec = async (req: Request, action: Action): Promise<Action> => {
const step = new Step('checkUserPushPermission');
const userEmail = action.userEmail;

if (!userEmail) {
step.setError('Push blocked: User not found. Please contact an administrator for support.');
// The pusher is identified from the credentials presented to the proxy, never from
// commit metadata in the pack, which the client fully controls.
const gitAccount = await getVerifiedGitAccount(action, req.headers?.authorization, step);

if (!gitAccount) {
step.setError(
'Push blocked: Unable to authenticate the pusher. Please make sure your git credentials are valid.',
);
action.addStep(step);
step.error = true;
return action;
}

return await validateUser(userEmail, action, step);
return await validateUser(gitAccount, action, step);
};

/**
* Finds the GitProxy users linked to an SCM account.
* @param {string} gitAccount The authenticated SCM account
* @return {Promise<User[]>} The matching users
*/
const findUsersByGitAccount = async (gitAccount: string): Promise<User[]> =>
(await getUsers()).filter((user) => user.gitAccount?.toLowerCase() === gitAccount.toLowerCase());

/**
* Helper that validates the user's push permission.
* This can be used by other actions that need it.
* @param {string} userEmail The user to validate
* @param {string} gitAccount The authenticated SCM account of the pusher
* @param {Action} action The action object
* @param {Step} step The step object
* @return {Promise<Action>} The action object
*/
const validateUser = async (userEmail: string, action: Action, step: Step): Promise<Action> => {
const validateUser = async (gitAccount: string, action: Action, step: Step): Promise<Action> => {
let isUserAllowed = false;

// Find the user associated with this email address
const list = await getUsers({ email: userEmail });
// Find the GitProxy user linked to this SCM account
const list = await findUsersByGitAccount(gitAccount);

if (list.length > 1) {
step.error = true;
step.log(
`Multiple Users have email <${userEmail}> so we cannot uniquely identify the user, ending`,
`Multiple Users have git account ${gitAccount} so we cannot uniquely identify the user, ending`,
);

step.setError(
`Your push has been blocked (there are multiple users with email ${action.userEmail})`,
`Your push has been blocked (there are multiple users with git account ${gitAccount})`,
);
action.addStep(step);
return action;
} else if (list.length == 0) {
step.log(`No user with email address ${userEmail} found`);
step.log(`No user with git account ${gitAccount} found`);
} else {
action.user = list[0].username;
action.userEmail = list[0].email;
step.log(`Push authenticated as user ${list[0].username} (git account ${gitAccount})`);
isUserAllowed = await isUserPushAllowed(action.url, list[0].username);
}

step.log(`User ${userEmail} permission on Repo ${action.url}: ${isUserAllowed}`);
step.log(`User ${gitAccount} permission on Repo ${action.url}: ${isUserAllowed}`);

if (!isUserAllowed) {
step.error = true;
step.log(`User ${userEmail} is not allowed to push on repo ${action.url}, ending`);
step.log(`User ${gitAccount} is not allowed to push on repo ${action.url}, ending`);
step.setError(
`Your push has been blocked (${action.userEmail} ` +
`Your push has been blocked (${gitAccount} ` +
`is not allowed to push on repo ` +
`${action.url})`,
);
action.addStep(step);
return action;
}

step.log(`User ${userEmail} is allowed to push on repo ${action.url}`);
step.log(`User ${gitAccount} is allowed to push on repo ${action.url}`);
action.addStep(step);
return action;
};

exec.displayName = 'checkUserPushPermission.exec';

export { exec, validateUser };
export { exec, validateUser, findUsersByGitAccount };
2 changes: 2 additions & 0 deletions src/proxy/processors/push-action/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ import { exec as checkIfWaitingAuth } from './checkIfWaitingAuth';
import { exec as checkCommitMessages } from './checkCommitMessages';
import { exec as checkAuthorEmails } from './checkAuthorEmails';
import { exec as checkUserPushPermission } from './checkUserPushPermission';
import { exec as resolvePusher } from './resolvePusher';

import { exec as checkEmptyBranch } from './checkEmptyBranch';

Expand All @@ -47,5 +48,6 @@ export {
checkCommitMessages,
checkAuthorEmails,
checkUserPushPermission,
resolvePusher,
checkEmptyBranch,
};
9 changes: 4 additions & 5 deletions src/proxy/processors/push-action/parsePush.ts
Original file line number Diff line number Diff line change
Expand Up @@ -109,12 +109,11 @@ async function exec(req: Request, action: Action): Promise<Action> {
action.commitFrom = action.commitData[action.commitData.length - 1].parent;
}

const { committer, committerEmail } = action.commitData[action.commitData.length - 1];
// Note: This is not always the pusher's email, it's the last committer's email.
// The committer is self-asserted by the client and must not be used as the pusher's
// identity; checkUserPushPermission sets action.user from the push credentials.
// See https://github.com/finos/git-proxy/issues/1400
step.log(`Push request received from user ${committer} with email ${committerEmail}`);
action.user = committer;
action.userEmail = committerEmail;
const { committer, committerEmail } = action.commitData[action.commitData.length - 1];
step.log(`Push contains commits last committed by ${committer} <${committerEmail}>`);
Comment thread
devin-ai-integration[bot] marked this conversation as resolved.
Resolved
}

step.content = {
Expand Down
46 changes: 46 additions & 0 deletions src/proxy/processors/push-action/resolvePusher.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
/**
* Copyright 2026 GitProxy Contributors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

import { Request } from 'express';

import { Action, Step } from '../../actions';
import { getVerifiedGitAccount } from '../pusherIdentity';
import { findUsersByGitAccount } from './checkUserPushPermission';

// Records the authenticated pusher on the action so that push plugins, which run right
// after this step, see a trusted identity. Never blocks: checkUserPushPermission enforces.
const exec = async (req: Request, action: Action): Promise<Action> => {
const step = new Step('resolvePusher');

const gitAccount = await getVerifiedGitAccount(action, req.headers?.authorization, step);
if (gitAccount) {
const list = await findUsersByGitAccount(gitAccount);
if (list.length === 1) {
action.user = list[0].username;
action.userEmail = list[0].email;
step.log(`Push authenticated as user ${list[0].username} (git account ${gitAccount})`);
} else {
step.log(`Found ${list.length} users with git account ${gitAccount}`);
}
}

action.addStep(step);
return action;
};

exec.displayName = 'resolvePusher.exec';

export { exec };
Loading
Loading