🔁 IPSpinner

IPSpinner is a local proxy which can be used to redirect all incoming requests through different chosen providers. The purpose is to create a pass-through proxy that rotates the source IP address of each request. As an example, running a bruteforce operation through IPSpinner will help to avoid being caught because the server will receive the requests from hundreds of different IP addresses.

IPSpinner currently supports AWS (API Gateway), Azure (Cloud Shell) and GitHub (GitHub Actions).

Table of contents

1. How it works?
   1. General
   2. Per provider & launcher
      1. AWS API Gateway
      2. Azure Cloud Shell
      3. GitHub Actions
   3. Launcher comparison
2. How to install?
   1. Install Go
   2. Clone and build IPSpinner
   3. Clean builds
3. How to use?
   1. General
      1. Command line arguments
      2. Configuration file
   2. Per provider
      1. AWS
      2. Azure
      3. GitHub
4. How to ...?
   1. HTTP/2 support?

I/ How it works?

1) General

<div align="center"> <img src="images/ipspinner/overall_diagram.png" alt="Figure 1: IPSpinner - Overall diagram" style="width: 100%;" /> <span>Figure 1: IPSpinner - Overall diagram</span> </div>

IPSpinner works as a local proxy that redirects requests through external services. For this purpose, IPSpinner leverages providers and launchers.

A provider corresponds to a cloud provider or an online service provider (AWS, Azure, GitHub, etc.), which offers different services, so called launchers, that can be used to relay user's requests (AWS API Gateway, GitHub Actions, Azure Cloud Shells, etc.).

Thus, in order to launch IPSpinner, the user will have to provide credentials for the providers he wants to use and additional configurations for the launchers. Multiple launcher types can be used at the same time, IPSpinner will choose randomly one of the available ones for each request.

Moreover, IPSpinner implements a preload feature. Some launchers can be preloaded to avoid the reconfiguration delay in the case a new host is seen by the proxy. For these launcher, the preload procedure is recommended but not mandatory. For the others, no preloading is necessary.

2) Per provider & launcher

i. AWS API Gateway

Introduction

IPSpinner can leverage AWS API Gateway for sending requests. This implementation is based on FireProx, which creates a REST API Gateway to redirect incoming requests. FireProx has therefore been adapted to handle multiple hosts per API Gateway and to implement new features. To sum up, when IPSpinner receives a request, it selects or creates the right API Gateway instance and sends towards the request. Then, it gathers the response and returns it to the user. Thus, the targeted server has received the request from the API Gateway and not directly from the user. As API Gateway rotates its outgoing IP for each request, IPSpinner uses this feature to make IP address rotating.

<div align="center"> <img src="images/aws/api_gateway/overall_diagram.png" alt="Figure 2: AWS API Gateway - Overall diagram" style="width: 100%;" /> <span>Figure 2: AWS API Gateway - Overall diagram</span> </div>

The next graph, made in October 2024, shows the number of unique IP addresses available per AWS region according to the number of requests sent. Most of the regions offer more than 100 IP addresses and multiple regions can be used at the same time, allowing the user to proxifies his requests through thousands of worldwide addresses.

<div align="center"> <img src="images/aws/api_gateway/available_ips_per_region.png" alt="Figure 3: AWS API Gateway - Available IP addresses per region" style="width: 100%;" /> <span>Figure 3: AWS API Gateway - Available IP addresses per region</span> </div>

Finally, the Figure 4 shows, with a logarithmic green color level, how many addresses are available per country. It demonstrates that the user has the possibility to falsify his source IP address with addresses on any continent.

<div align="center"> <img src="images/aws/api_gateway/map.png" alt="Figure 4: AWS API Gateway - IP addresses per country" style="width: 100%;" /> <span>Figure 4: AWS API Gateway - IP addresses per country</span> </div>

Noteworthy details

IPSpinner implements a rotation feature that reguarly deletes and renews created FireProx instances. As the following graph shows, rotating a FireProx instance may deliver a new subset of IP. However, each AWS region has a limited set of IP and therefore at some point, rotations will not deliver new IPs.

<div align="center"> <img src="images/aws/api_gateway/rotating_process.png" alt="Figure 5: AWS API Gateway - Rotating process" style="width: 100%;" /> <span>Figure 5: AWS API Gateway - Rotating process</span> </div>

This launcher implements a preloading procedure. As said before, it is not mandatory, but can prevent some reconfiguration delays or synchronisation errors during the first seconds after being reconfigured.

Moreover, API Gateways set by default a X-Forwarded-For header, which cannot be deleted but can be overrided. Thus, the user can specify in the IPSpinner configuration an IP address range from which an random IP will be chosen for each request (IPv4 or IPv6 range).

ii. Azure Cloud Shell

Introduction

IPSpinner leverages Azure Cloud Shell to send requests. An Azure Cloud Shell is an interactive, authenticated, browser-accessible terminal for managing Azure resources. Cloud Shell runs on a temporary host provided on a per-session, per-user basis.

Thus, IPSpinner uses several Azure users for whom a Cloud Shell session is prepared. Then, each request will be redirected to an initialised Cloud Shell, before being renewed to reset its IP address.

<div align="center"> <img src="images/azure/cloud_shell/overall_diagram.png" alt="Figure 6: Azure Cloud Shell - Overall diagram" style="width: 100%;" /> <span>Figure 6: Azure Cloud Shell - Overall diagram</span> </div>

As the following graph shows, the different regions available to deploy Cloud Shells sessions each offer dozens of IP addresses. The user can configure multiple regions at the same time to increase his IP pool.

<div align="center"> <img src="images/azure/cloud_shell/available_ips_per_region.png" alt="Figure 7: Azure Cloud Shell - Available IP addresses per region" style="width: 100%;" /> <span>Figure 7: Azure Cloud Shell - Available IP addresses per region</span> </div>

However, IP addresses are more concentrated than for AWS API Gateway. As the following map illustrates, most of them are located in the US, in Europe and in India.

<div align="center"> <img src="images/azure/cloud_shell/map.png" alt="Figure 8: Azure Cloud Shell - IP addresses per country" style="width: 100%;" /> <span>Figure 8: Azure Cloud Shell - IP addresses per country</span> </div>

Noteworthy details

Due to the Cloud Shell renewing process delay, we advise to limit the request flow rate. More information in the launcher comparison subsection.

iii. GitHub Actions

Introduction

IPSpinner can also take advantage of the GitHub Actions to send requests. This implementation is inspired of git-rotate but has been completely modified and adapted to get rid of the catcher server.

It creates a repository with a predefined workflow template. Then, for each request, it runs the workflow by giving request information through the environment variables. All data is encrypted to avoid being readable by an external user. IPSpinner finally collects response data from the workflow logs.

<div align="center"> <img src="images/github/github_actions/overall_diagram.png" alt="Figure 9: GitHub Actions - Overall diagram" style="width: 100%;" /> <span>Figure 9: GitHub Actions - Overall diagram</span> </div>

The following figure shows that GitHub Actions offer thousands of different IP addresses.

<div align="center"> <img src="images/github/github_actions/available_ips_per_region.png" alt="Figure 10: GitHub Actions - Available IP addresses per region" style="width: 100%;" /> <span>Figure 10: GitHub Actions - Available IP addresses per region</span> </div>

However, the following map illustrates that GitHub Actions only offer American IP addresses. After analysis, their worker seem to be deployed on an Azure infrastructure.

<div align="center"> <img src="images/github/github_actions/map.png" alt="Figure 11: GitHub Actions - IP addresses per country" style="width: 100%;" /> <span>Figure 11: GitHub Actions - IP addresses per country</span> </div>

Noteworthy details

⚠️ Moreover, "GitHub takes abuse and spam of Actions seriously, and they have a dedicated team to track “spammy users.”". Thus, the user MUST NOT use this provider with its own account or with the company account to avoid any account closure issue.

Due to the per-hour GitHub REST API limit, the maximum request flow rate must be limited to avoid any disruption. More information in the launcher comparison subsection.

3) Launcher comparison

| | AWS API Gateway | Azure Cloud Shell | GitHub Actions | |---------------------------|-----------------|-------------------|----------------| | Available IP addresses | ≈ 12,418 | ≈ 276 | > 6,000 | | Mean response time | 0.46s | 13.04s | 21.42s | | Mean reconfiguration time | None | 20s | None | | Ma