feat: add upstream proxy configuration for outbound requests

Author: Andreybest

config.schema.json

@@ -367,6 +367,29 @@
           }
         }
       }
+    },
+    "upstreamProxy": {
+      "description": "Configuration for routing outbound requests to upstream Git hosts via an HTTP(S) proxy.",
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Whether to use an outbound HTTP(S) proxy for upstream Git hosts."
+        },
+        "url": {
+          "type": "string",
+          "description": "Proxy URL used for outbound connections to upstream Git hosts when set.",
+          "format": "uri"
+        },
+        "noProxy": {
+          "type": "array",
+          "description": "Additional hostnames or domain suffixes that should bypass the upstream proxy.",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": false
     }
   },
   "definitions": {

docs/Architecture.md

@@ -222,6 +222,26 @@ Currently supports the following out-of-the-box:
 - ActiveDirectory auth configuration for querying via a REST API rather than LDAP
 - Gitleaks configuration
 
+#### `upstreamProxy`
+
+Configures routing of outbound requests from the GitProxy server to upstream Git hosts (e.g. GitHub, GitLab) via an HTTP(S) proxy. Use this when the server runs in an environment where direct Internet access is not allowed and all traffic must go through a corporate web proxy ("proxying the proxy").
+
+- **`enabled`** (boolean): When `true`, outbound connections to upstream Git hosts use the configured proxy. When `false`, the proxy is not used even if `url` or environment variables are set.
+- **`url`** (string): The HTTP(S) proxy URL (e.g. `http://proxy.corp.local:8080` or `http://user:pass@proxy.corp.local:8080`). If omitted, GitProxy falls back to the `HTTPS_PROXY`, `https_proxy`, `HTTP_PROXY` or `http_proxy` environment variables (first defined wins).
+- **`noProxy`** (array of strings, optional): Hostnames or domain suffixes for which the proxy should be bypassed (e.g. internal Git hosts). Combined with the `NO_PROXY` / `no_proxy` environment variable.
+
+Example:
+
+```json
+"upstreamProxy": {
+  "enabled": true,
+  "url": "http://proxy.corp.local:8080",
+  "noProxy": ["github.corp.local", "gitlab.corp.local"]
+}
+```
+
+If `upstreamProxy` is not configured, setting only `HTTPS_PROXY` (or `HTTP_PROXY`) in the environment will also enable use of that proxy for outbound connections, unless `enabled` is explicitly set to `false` in config.
+
 #### `commitConfig`
 
 Used in [`checkCommitMessages`](./Processors.md#checkcommitmessages), [`checkAuthorEmails`](./Processors.md#checkauthoremails) and [`scanDiff`](./Processors.md#scandiff) processors to block pushes depending on the given rules.

package-lock.json

@@ -107,6 +107,7 @@
     "express-session": "^1.19.0",
     "font-awesome": "^4.7.0",
     "history": "5.3.0",
+    "https-proxy-agent": "^7.0.6",
     "isomorphic-git": "^1.36.3",
     "jsonwebtoken": "^9.0.3",
     "load-plugin": "^6.0.3",

package.json

@@ -101,6 +101,10 @@ export interface GitProxyConfig {
    * UI routes that require authentication (logged in or admin)
    */
   uiRouteAuth?: UIRouteAuth;
+  /**
+   * Configuration for routing outbound requests to upstream Git hosts via an HTTP(S) proxy.
+   */
+  upstreamProxy?: UpstreamProxy;
   /**
    * Customisable URL shortener to share in proxy responses and warnings
    */
@@ -563,6 +567,24 @@ export interface RouteAuthRule {
   [property: string]: any;
 }
 
+/**
+ * Configuration for routing outbound requests to upstream Git hosts via an HTTP(S) proxy.
+ */
+export interface UpstreamProxy {
+  /**
+   * Whether to use an outbound HTTP(S) proxy for upstream Git hosts.
+   */
+  enabled?: boolean;
+  /**
+   * Additional hostnames or domain suffixes that should bypass the upstream proxy.
+   */
+  noProxy?: string[];
+  /**
+   * Proxy URL used for outbound connections to upstream Git hosts when set.
+   */
+  url?: string;
+}
+
 // Converts JSON strings to/from your types
 // and asserts the results of JSON.parse at runtime
 export class Convert {
@@ -780,6 +802,7 @@ const typeMap: any = {
       { json: 'tempPassword', js: 'tempPassword', typ: u(undefined, r('TempPassword')) },
       { json: 'tls', js: 'tls', typ: u(undefined, r('TLS')) },
       { json: 'uiRouteAuth', js: 'uiRouteAuth', typ: u(undefined, r('UIRouteAuth')) },
+      { json: 'upstreamProxy', js: 'upstreamProxy', typ: u(undefined, r('UpstreamProxy')) },
       { json: 'urlShortener', js: 'urlShortener', typ: u(undefined, '') },
     ],
     false,
@@ -981,6 +1004,14 @@ const typeMap: any = {
     ],
     'any',
   ),
+  UpstreamProxy: o(
+    [
+      { json: 'enabled', js: 'enabled', typ: u(undefined, true) },
+      { json: 'noProxy', js: 'noProxy', typ: u(undefined, a('')) },
+      { json: 'url', js: 'url', typ: u(undefined, '') },
+    ],
+    false,
+  ),
   AuthenticationElementType: ['ActiveDirectory', 'jwt', 'local', 'openidconnect'],
   DatabaseType: ['fs', 'mongo'],
 };

src/config/generated/config.ts

@@ -149,6 +149,12 @@ export const getProxyUrl = (): string | undefined => {
   return config.proxyUrl;
 };
 
+// Get upstream proxy configuration
+export const getUpstreamProxyConfig = () => {
+  const config = loadFullConfiguration();
+  return config.upstreamProxy || {};
+};
+
 // Gets a list of authorised repositories
 export const getAuthorisedList = () => {
   const config = loadFullConfiguration();

src/config/index.ts

@@ -23,6 +23,9 @@ import { processUrlPath, validGitRequest } from './helper';
 import { getAllProxiedHosts } from '../../db';
 import { ProxyOptions } from 'express-http-proxy';
 import { getErrorMessage, handleAndLogError } from '../../utils/errors';
+import { getUpstreamProxyConfig } from '../../config';
+import { HttpsProxyAgent } from 'https-proxy-agent';
+import { OutgoingHttpHeaders, RequestOptions } from 'http';
 
 enum ActionType {
   ALLOWED = 'Allowed',
@@ -144,7 +147,100 @@ const getRequestPathResolver: (prefix: string) => ProxyOptions['proxyReqPathReso
   };
 };
 
-const proxyReqOptDecorator: ProxyOptions['proxyReqOptDecorator'] = (proxyReqOpts) => proxyReqOpts;
+const getEnvProxyUrl = () =>
+  process.env.HTTPS_PROXY ||
+  process.env.https_proxy ||
+  process.env.HTTP_PROXY ||
+  process.env.http_proxy;
+
+const getEnvNoProxyList = (): string[] => {
+  const noProxy = process.env.NO_PROXY || process.env.no_proxy;
+  if (!noProxy) {
+    return [];
+  }
+  return noProxy
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+};
+
+const hostMatchesNoProxy = (host: string | null | undefined, noProxyList: string[]): boolean => {
+  if (!host) {
+    return false;
+  }
+
+  const hostname = host.split(':')[0];
+
+  return noProxyList.some((pattern) => {
+    if (!pattern) {
+      return false;
+    }
+    const trimmed = pattern.trim();
+    if (trimmed === '') {
+      return false;
+    }
+
+    // Exact match
+    if (hostname === trimmed) {
+      return true;
+    }
+
+    // Domain suffix match, e.g. example.com matches foo.example.com
+    if (hostname.endsWith(`.${trimmed}`)) {
+      return true;
+    }
+
+    return false;
+  });
+};
+
+const buildUpstreamProxyAgent = (
+  proxyReqOpts: Omit<RequestOptions, 'headers'> & {
+    headers: OutgoingHttpHeaders;
+  },
+) => {
+  const upstreamProxyConfig = getUpstreamProxyConfig();
+
+  const configuredUrl = upstreamProxyConfig.url;
+  const envUrl = getEnvProxyUrl();
+
+  const proxyUrl = configuredUrl || envUrl;
+
+  // If nothing is configured, do not use a proxy
+  if (!proxyUrl) {
+    return undefined;
+  }
+
+  // If config explicitly disabled the proxy, do not use it
+  if (upstreamProxyConfig.enabled === false) {
+    return undefined;
+  }
+
+  const host: string | null | undefined = proxyReqOpts.host || proxyReqOpts.hostname;
+
+  const configNoProxy = upstreamProxyConfig.noProxy ? upstreamProxyConfig.noProxy : [];
+  const envNoProxy = getEnvNoProxyList();
+  const combinedNoProxy = [...configNoProxy, ...envNoProxy];
+
+  if (hostMatchesNoProxy(host, combinedNoProxy)) {
+    return undefined;
+  }
+
+  return new HttpsProxyAgent(proxyUrl);
+};
+
+const proxyReqOptDecorator: ProxyOptions['proxyReqOptDecorator'] = (proxyReqOpts, _srcReq) => {
+  const agent = buildUpstreamProxyAgent(proxyReqOpts);
+
+  if (!agent) {
+    return proxyReqOpts;
+  }
+
+  return {
+    ...proxyReqOpts,
+    agent,
+  };
+};
 
 const proxyReqBodyDecorator: ProxyOptions['proxyReqBodyDecorator'] = (bodyContent, srcReq) => {
   if (srcReq.method === 'GET') {
@@ -273,4 +369,5 @@ export {
   isPackPost,
   extractRawBody,
   validGitRequest,
+  buildUpstreamProxyAgent,
 };