Home

Awesome

<div align="center">

alt text

<hr/>

Fluxzy.Core Fluxzy.Core Docker Image Version build codecov gitter

Features | Quick usage (.NET) | Quick usage (CLI) | Quick usage (Docker) | Documentation | Build | License | Releases

</div>

fluxzy is a fully managed and fully streamed MITM engine and a CLI app to intercept, record and alter HTTP/1.1, H2, websocket traffic over plain or secure channels.

This repository contains the source code of Fluxzy CLI which is a standalone command line application for Windows, macOS, and Linux and the .NET packages that are used by Fluxzy Desktop.

1. Features

1.1 Core features

1.2 Alteration and traffic management features

Alteration and traffic management features are available as fluxzy actions. You can browse this dedicated search page to see built-in actions on the latest stable version. Here are a few examples:

2. Quick Usage

2.1 .NET library

2.1.1 Simple usage

The main documentation is available at docs.fluxzy.io. The following shows a very basic usage of the .NET packages.

The main line to begin a capture session is to create a FluxzySetting instance and use it to create a Proxy instance.

Install NuGet package Fluxzy.Core

dotnet add package Fluxzy.Core

Create a top-level statement console app, with .NET 6.0 or above:

using System.Net;
using Fluxzy;
using Fluxzy.Core;
using Fluxzy.Rules.Actions;
using Fluxzy.Rules.Actions.HighLevelActions;
using Fluxzy.Rules.Filters;
using Fluxzy.Rules.Filters.RequestFilters;
using Fluxzy.Rules.Filters.ResponseFilters;

// Create a new setting 
var fluxzySetting = FluxzySetting.CreateDefault(IPAddress.Loopback, 8080);

fluxzySetting
    .ConfigureRule()
    // Forward request
    .WhenHostMatch("twitter.com")
    .Forward("https://www.google.com/")

    // Mock any POST request to /api/auth/token
    .WhenAll(
        new GetFilter(),
        new PathFilter("/api/auth/token", StringSelectorOperation.Contains))
    .ReplyJson("{ token: \"your fake key\" }")

    // Select wikipedia domains that produces text/html content-type
    .WhenAll(
        new HostFilter("wikipedia.[a-z]+$", StringSelectorOperation.Regex),
        new HtmlResponseFilter()
    )
    // Inject a CSS after opening head tag
    .Do(
        // Remove CSP to allow injecting CSS and scripts
        new DeleteResponseHeaderAction("Content-Security-Policy"),
        new InjectHtmlTagAction
        {
            Tag = "head",
            // Make all pages purple
            HtmlContent = "<style>* { background-color: #7155ab !important; }</style>"
        }
    );

await using var proxy = new Proxy(fluxzySetting);
var endPoints = proxy.Run();

// Register as system proxy, the proxy is restore when the IAsyncDisposable is disposed
await using var _ = await SystemProxyRegistrationHelper.Create(endPoints.First());

// Create a new HttpClient that uses the proxy 
var httpClient = HttpClientUtility.CreateHttpClient(endPoints, fluxzySetting);

var responseText = await httpClient.GetStringAsync("https://baddomain.com/api/auth/token");

Console.WriteLine($"Final answer: {responseText}");
Console.WriteLine("Press enter to halt this program and restore system proxy setting...");

Console.ReadLine();

More examples are available at docs.fluxzy.io.

2.2 Fluxzy CLI

Fluxzy CLIVersion
Windowswin32 win64 winArm64
macOSosx64 osxArm64
Linuxlinux64 linuxArm64

Sample usage

The following highlights the basic way to use fluxzy with a simple rule file.

The "rule file" is a straightforward YAML file containing a list of directives that fluxzy will evaluate during proxying.

For more detailed documentation, visit fluxzy.io or use the --help option available for each command.

Create a rule.yaml file as follows:

rules:
  - filter:
      typeKind: requestHeaderFilter
      headerName: authorization # Select only requests with authorization header
      operation: regex
      pattern: "Bearer (?<BEARER_TOKEN>.*)" # A named regex instructs fluxzy
                                             # to extract the token from the authorization
                                             # header into the variable BEARER_TOKEN
    action:
      # Write the token to a file
      typeKind: FileAppendAction # Append the token to the file
      filename: token-file.txt # Save the token to token-file.txt
      text: "${authority.host} --> ${user.BEARER_TOKEN}\r\n"  # user.BEARER_TOKEN retrieves 
                                                              # the previously captured variable 
      runScope: RequestHeaderReceivedFromClient  # Run the action when the request header 
                                                 # is received from the client
  - filter:
      typeKind: anyFilter # Apply to any exchanges
    action:
      typeKind: AddResponseHeaderAction # Append a response header
      headerName: fluxzy
      headerValue: Passed through fluxzy

The rule file above performs two actions:

For more information about the rule syntax, visit the documentation page. Visit directive search page to see all built-in filters and actions.

Then start fluxzy with the rule file

fluxzy start -r rule.yaml --install-cert -sp -o output.fxzy -c

You can use the command dissect to read the fluxzy file or, alternatively, you can use Fluxzy Desktop to view it with a GUI.

More command and options are available, including exporting to HAR or managing certificates, you can run --help to see all available options and commands.

By default, fluxzy will bind to 127.0.0.1:44344.

Run with docker

The CLI can be run from a docker image.

docker run -it -p 43444:43444 fluxzy/fluxzy:latest start

To test:

curl -x 127.0.0.1:44344 https://www.fluxzy.io

3. Build

3.1 Requirements

3.2 Build

3.3 Test

4 Contact