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 17(+)
• 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.