winfoom

Basic Proxy Facade for NTLM, Kerberos, SOCKS and Proxy Auto Config file proxies

To help this project please give it a star ⭐

Overview

Winfoom is an HTTP(s) proxy server facade that allows applications to authenticate through the following proxies:

• NTLM or Kerberos HTTP authenticated proxy (Kerberos is supported only on Windows systems)
• SOCKS version 4 or 5, with or without authentication
• Proxy Auto Config files - including Mozilla Firefox extension that is not part of original Netscape specification

typically used in corporate environments, without having to deal with the actual handshake.

A lot of software applications have problems when dealing with an authenticated proxy server's protocol. Winfoom sits between the corporate proxy and applications and offloads the authentication and the proxy's protocol, acting as a facade. This way, the software application will only have to deal with a basic proxy with no authentication.

An example of such a facade for NTLM proxies is CNTLM

Getting Started

Download Winfoom

Download prepackaged

To try out Winfoom without needing to download the source and package it, check out the releases for a prepackaged winfoom-*.zip. Winfoom is a Java application and requires a Java Runtime Environment (at least v11).

If it is not already installed on your system, you can download it from AdoptOpenJDK or, on Linux systems, use your package manager.

If, for certain reasons, you do not want to install Java globally on your system then download the JRE archive according to your system architecture, unzip it in the Winfoom directory and rename it to jdk.

Build from source code

If you decide to build the executable jar file from the source code, you would need these prerequisites:

• Java JDK 11(+)
• Maven 3.x version (optional)

First download the source code from releases and unzip it.

Then open a terminal and execute this command inside the winfoom-x.x.x directory:

 mvn clean package

or, if you did not install Maven, use the Maven Wrapper:

 .\mvnw clean package

Now you should have the generated executable jar file under the target directory and the two release archives: one for Windows, the other for Linux/MacOS.

Run Winfoom

The prepackaged winfoom-windows.zip for Windows systems, contains the following executable files:

• launch.bat launches the application
• launchGui.bat launches the application in graphical mode
• foomcli.bat manages the application in GUI-less mode

The prepackaged winfoom-unix.zip for Linux/MacOS systems, contains the following executable files:

• launch.sh launches the application (needs to be made executable)
• foomcli.sh manages the application in GUI-less mode (needs to be made executable)

On Windows systems, Winfoom can be launched by double-click on launchGui.bat or from the command prompt:

launch

or, to run it in debug mode:

launch --debug

or, to run it in the graphical mode:

launch --gui

On Linux/MacOS systems, there is no graphical mode available. Make sure the *.sh files are executable. To run Winfoom, execute in a terminal:

./launch.sh

or, to run it in debug mode:

./launch.sh --debug

Winfoom can be launched with modified Java and system parameters by defining the environment variable FOOM_ARGS. For example:

FOOM_ARGS=-Dsocket.soTimeout=10 -Dconnection.request.timeout=60

👉 Note: It's a good idea to add the Winfoom's home directory to the PATH environment variable.

Winfoom's logs

The application log file is placed under out/logs directory.

Configuration

User settings

The graphical mode (Windows only)

Winfoom has a graphical user interface that allows configuration.

The first thing to select is the proxy type:

1. HTTP - if the upstream proxy is NTLM or any other HTTP proxy
2. SOCKS4 - if the upstream proxy is SOCKS version 4
3. SOCKS5 - if the upstream proxy is SOCKS version 5
4. PAC - if the proxy is using a Proxy Auto Config file
5. DIRECT - no proxy, used for various testing environments

Then fill in the required fields. You can use the field's tooltip to get more information.

To put the application in autostart mode or autodetect mode see the Settings menu.

The command line mode (all systems)

If you run the application in non-graphical mode, Winfoom exposes an API accessible over HTTP on a local port (default 9999, configurable), that allows configuration and management.

The script foomcli provides easy access to this API.

👉 Note: The foomcli script requires curl. The current version of WIndows 10 provides it by default. You can check if it is available by executing curl --version in your terminal. If you see something like command not found then you need to manually install it.

To get help about the usage execute:

foomcli --help (on Linux/MacOS is ./foomcli.sh --help)

👉 Note: You can move the script foomcli whatever location you want. It is not required to be in the Winfoom's directory.

Examples

After launching Winfoom, check the status of the local proxy facade:

foomcli status

If the local proxy is stopped, you cat start it with:

foomcli start

but before that, you need to configure it. Execute:

foomcli config

to get the current configuration. You'll get something like:

{
"proxyType" : "DIRECT",
"localPort" : 3129,
"proxyTestUrl" : "https://example.com"
}

The output is in JSON format. The name of the fields is self-descriptive. Suppose you want to configure Winfoom for an HTTP proxy. First, change the proxy type to HTTP with:

foomcli config -t http

Then, executing foomcli config again, the output is something like:

{
  "proxyType" : "HTTP",
  "proxyHost" : "",
  "proxyPort" : 0,
  "localPort" : 3129,
  "proxyTestUrl" : "http://example.com",
  "useCurrentCredentials" : true
}

The field useCurrentCredentials only appears on Windows. When the value is true, it means Winfoom will use the current user's credentials also will automatically handle the upstream proxy protocol; otherwise, you will have to provide the user and password (or DOMAIN\user and password).

To change the above values, copy the content of the output into a text file named, let's say, http_config.json in the same directory, and edit the field's values accordingly:

{
"proxyType" : "HTTP",
"proxyHost" : "192.168.0.105",
"proxyPort" : 80,
"localPort" : 3129,
"proxyTestUrl" : "http://example.com"
}

To load the new values, execute:

foomcli config -f http_config.json

and check the new configuration with foomcli config to be sure everything is as expected.

Now you can start the local proxy facade with foomcli start. At this moment you should be able to use Winfoom as a proxy facade in your browser.

On Windows, if you want to provide your own credentials, change the useCurrentCredentials value to false by editing http_config.json file like this:

{
"proxyType" : "HTTP",
"useCurrentCredentials" : false
}

Execute foomcli config -f http_config.json again, then foomcli config to see the result:

{
  "proxyType" : "HTTP",
  "proxyHost" : "192.168.0.105",
  "proxyPort" : 80,
  "proxyUsername" : null,
  "proxyPassword" : null,
  "localPort" : 3129,
  "proxyTestUrl" : "http://example.com",
  "useCurrentCredentials" : false,
  "httpAuthProtocol" : null
}

Edit the http_config.json file again to fill in the required fields:

{
  "proxyType" : "HTTP",
  "proxyUsername" : "user",
  "proxyPassword" : "password",
  "httpAuthProtocol" : "NTLM"
}

Execute foomcli config -f http_config.json again and start the local proxy server.

If you want to shut down Winfoom execute foomcli shutdown

---

On Linux/MacOS or Windows with useCurrentCredentials=false, if the proxy type is HTTP you need to set the httpAuthProtocol field, which is the proxy protocol: one of NTLM, BASIC values.

If the proxy type is PAC, then the output of the foomcli config command would be like:

{
  "proxyType" : "PAC",
  "proxyUsername" : "DOMAIN\\winfoom",
  "proxyPassword" : "***",
  "proxyPacFileLocation" : "C:\\path_to\\proxy-ntlm-auth.pac",
  "blacklistTimeout" : 30,
  "localPort" : 3129,
  "proxyTestUrl" : "https://example.com",
  "pacHttpAuthProtocol" : "NTLM"
}

The possible values of pacHttpAuthProtocol field are: NTLM, BASIC. You need to set this field only when the PAC file points to at least one upstream HTTP proxy.

---

To put Winfoom in autostart mode first execute:

foomcli settings

The output would be something like:

{
"autostart" : false,
"autodetect" : false,
"appVersion" : "3.0.1",
"apiPort" : 9999
}

Copy the output into a file named, let's say, settings.json and modify accordingly:

{
"autostart" : true
}

Since we only modify the autostart option, the other fields are dropped off.

To load the new values, execute:

foomcli settings -f settings.json

then check the new settings with foomcli settings

👉 Note: If you modify the apiPort then you need to set the variable FOOM_LOCATION. (For example FOOM_LOCATION=localhost:[your new port])

👉 WARNING: All the provided passwords are stored encoded BASE64 without any encryption. Make sure you protect the access to the config directory!

System settings

The system settings configuration file is config/system.properties.

Please do not modify this file unless absolutely necessary. It is advisable to post your issue in Issues Section first.

The available settings:

Key	Description	Type	Default value
maxConnections.perRoute	Connection pool property: max polled connections per route	Integer	20
maxConnections	Connection pool property: max polled connections	Integer	600
internalBuffer.length	The max size of the entity buffer (bytes)	Integer	102400
connectionManager.clean.interval	The frequency of running purge idle on the connection manager pool (seconds)	Integer	30
connectionManager.idleTimeout	The connections idle timeout, to be purged by a scheduled task (seconds)	Integer	30
serverSocket.backlog	The maximum number of pending connections	Integer	1000
socket.soTimeout	The timeout for read/write through socket channel (seconds)	Integer	60
socket.connectTimeout	The timeout for socket connect (seconds)	Integer	20
pacScriptEngine.pool.maxTotal	The pacScriptEngine pool maximum total instances	Integer	100
pacScriptEngine.pool.minIdle	The pacScriptEngine pool min idle instances	Integer	20
connection.request.timeout	The timeout for request connection (seconds)	Integer	30
apiServer.request.timeout	The timeout for API commands (seconds)	Integer	10

Authentication

• For HTTP proxy type, Winfoom uses the current Windows user credentials to authenticate to the upstream proxy, unless you uncheck the Use system credentials checkbox. On Linux/MacOS or on Windows with Use system credentials unchecked you need to provide the user and password (or DOMAIN\user and password if the DOMAIN is required)
• For SOCKS5 proxy type, the user/password need to be provided when required.
• For PAC proxy type, starting with v3.4.0, there is some support for authentication (still, keep in mind that the PAC protocol does not support authentication) when:
  1. All upstream proxy servers accept the same credentials.
  2. On Windows, if the proxyUsername field is empty, the current user's credentials are used for authentication.
  3. On Unix based systems, if the proxyUsername field is empty the authentication is disabled.
  4. On all systems, when the proxyUsername field is not empty, the provided proxyUsername/proxyPassword are used for authentication. If at least one of the upstream proxy servers is of HTTP type, the field pacHttpAuthProtocol needs to be provided.

Error codes

Starting with v2.6.0 Winfoom gives back the following HTTP error codes when there is no response from the upstream proxy for various reasons:

Proxy type	HTTP error code	When
ALL	502	The upstream proxy is not available
SOCKS/DIRECT	504	The giving address is not reachable
PAC	502	All upstream proxies are blacklisted
ALL	500	Any other error

Test

To test it, open a browser, let's say Firefox and configure proxy like this:

Now you should be able to access any URL without Firefox asking for credentials.

If you don't have an available proxy, you still can test Winfoom by installing WinGate and configure it to act as a NTML proxy.

TODOs

• Proper unit testing

Coding Guidance

Please review these docs below about coding practices.

• Google Java Style Guide
• Java Code Conventions

Feedback

Any feedback or suggestions are welcome. It is hosted with an Apache 2.0 license so issues, forks and PRs are most appreciated.