haga-rak / fluxzy.core

Fast and fully streamed Man-On-The-Middle engine and a CLI app to intercept, record and alter HTTP/1.1, H2, websocket traffic over plain or secure channels.

---

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

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

• Intercept HTTP/1.1, H2, WebSocket traffic over plain or secure channels
• Fully streamed intermediate as proxy or transparent proxy
• Deflect operating system traffic (act as system proxy)
• Automatic root certificate installation (with elevation on Windows, macOS, and several Linux distributions)
• Certificate management: built-in feature to create CA compatible certificates
• Export as HTTP Archive
• Use a custom root certificate authority
• Choice between default .NET SSL provider and BouncyCastle
• Raw packet capture (with the extension Fluxzy.Core.Pcap)
• NSS Key log extraction (when using Bouncy Castle)
• Optional configuration-based data extraction and alteration

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:

• Add, remove, modify request and response headers
• Mock or substitute request and response body
• Forward, redirect, spoof DNS, abort connections
• Inject html snippet on intercepted request and response bodies
• Remove cache directives, add request and response cookies
• Serve static directory
• Add metadata to HTTP exchanges (tags and comments)
• Provide a specific certificate for a host

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 CLI	Version
Windows
macOS
Linux

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:

• It extract any BEARER token from the authorization header and write it to a file (`token-file.txt``)
• It appends a response header (fluxzy: Passed through fluxzy) to all exchanges

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 

• --install-cert, -sp, -o, -c, -r are optional.

• -o will save all collected data in a fluxzy file. The file will be created only at the end of the capture session.

• -sp will make fluxzy act as system proxy. The proxy settings will be reverted when fluxzy is stopped with SIGINT (Ctrl+C). The proxy settings won't be reverted if the fluxzy process is killed.

• -c will enable raw packet capture.

• --install-cert will install the default certificate on the current user. This option needs elevation and may trigger interactive dialogs on certain OS.

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

• .NET 8.0 SDK
• Git bash if Windows
• libpcap or any equivalent library
• tests collecting pcap files and installing certificates requires elevation.
• An IDE is not necessary to build the app. For information, this project was developed using both Visual Studio 2022 and JetBrains Rider on Windows, macOS and Linux.

3.2 Build

• Clone the repository
• Run dotnet build src/Fluxzy.Core for Fluxzy.Core
• Run dotnet build src/Fluxzy.Core.Pcap for Fluxzy.Core.Pcap

3.3 Test

• Several tests are run against various private web servers (iis, nginx, kestrel, apache, ...) which is not currently available to the public.

4 Contact

• Use github issues for bug reports and feature requests
• Mail to [email protected] for inquiries

fluxzy.core's Issues

Enable setting up user level default root certificate

Currently, the default root certificate used is embedded into the binary.

If the final user uses fluxzy in multiple instances and wishes to change the default root certificate, he has to configure the certificate retrieval mode for each instances.

This feature should simplify this inconvienience by enabling a default root certificate location at user level. The default certificate will be read through env var or via a fixed path on the user directory.

Add a default rule name to avoid repetitive usage of `-r` option

Just like docker-compose.yaml for docker compose, it will be nice to have a default rule file name on which the fluxzy instance will automatically load. It will avoid repetitive usage of -r or -R options. However, the file will be ignored when one these options are set.

The suggest filename is fluxzy-rule.yaml or/and fluxzy-rule.yml.

Issue with "Proxy-Authenticate" header

Describe the bug:
I'm not sure if this is a bug.

Is there a way to force the client to send a "Proxy-Authenticate" header after an HTTP CONNECT?
I'm trying to respond with HTTP 407, but before any rule fires, the library responds with HTTP 200 (x-fluxzy-message: enjoy your privacy)

Describe the tool and the environment
Fluxzy.Core 1.21.3

Add action to limit connection throughput

Unable to alteration WebSocket

Describe the bug
The rule added by AddAlterationRules seems doesn't capture WebSocket Exchanges.

Describe the tool and the environment
macOS 14.4.1
.NET 8.0.204
Fluxzy.Core 1.23.2

To Reproduce
Steps to reproduce the behavior:
Program to reproduce:

using Fluxzy;
using Fluxzy.Core;
using Fluxzy.Core.Breakpoints;
using Fluxzy.Rules;
using Fluxzy.Rules.Filters;
using Action = Fluxzy.Rules.Action;

var filter = new IsWebSocketFilter();
var action = new MyAction();
var fluxzyStartupSetting = FluxzySetting.CreateLocal(23410).AddAlterationRules(action, filter);
var total = 0;
await using var proxy = new Proxy(fluxzyStartupSetting);
proxy.Writer.ExchangeUpdated += (sender, args) =>
{
    if (args.ExchangeInfo.IsWebSocket)
    {
        total++;
    }
};
var endPoints = proxy.Run();

// press any key to exit
Console.ReadKey();
Console.WriteLine($"Actually total WS Exchange: {total}, but action.Total: {action.Total}");

class MyAction : Action
{
    public override FilterScope ActionScope => FilterScope.OnAuthorityReceived;

    public override string DefaultDescription => nameof(MyAction);

    public int Total { get; set; }

    public override ValueTask InternalAlter(
        ExchangeContext context,
        Exchange? exchange,
        Connection? connection,
        FilterScope scope,
        BreakPointManager breakPointManager
    )
    {
        Total++;
        return default;
    }
}

1. Write this program.cs
2. dotnet run it in a console
3. Launch Chrome/Chromium with args --proxy-server=127.0.0.1:23410 --ignore-certificate-errors https://game.maj-soul.com/1/
4. Wait for loading and stay on the sign-in page for serval seconds
5. Press any key to stop the program
6. Counts of WS Exchanges from Rule and Proxy.Writer.ExchangeUpdated should showup.

Expected behavior
The counts from Rule and Proxy.Writer.ExchangeUpdated should be identical.

Additional context
Additionally, sometimes I get the wrong WsMessage compared to what Chrome Dev Tool shows.

Add a feature to export in one file all pcap connections in an archive file/directory

Fluxzy.Desktop startup error

Describe the bug
I'm trying to use fluxzy desktop version, but it suddenly won't start, even uninstalling and reinstalling the latest version doesn't help. This just happened today. I have never encountered this problem before. At least I could open it yesterday.

Describe the tool and the environment

• Fluxzy.Desktop v1.18.2
• Windows 10

To Reproduce
Steps to reproduce the behavior:

1. 打开桌面图标(Fluxzy Desktop)
2. See error

Screenshot

When `operation` field is not set for filters based `StringFilter`, connection are closed prematurely

This is a example of yaml rule that leads to this bug:

filter:
  typeKind: HostFilter
  pattern: example.com
actions:
  - typekind: NoOpAction

Add support for native AOT for Fluxzy CLI

Native AOT is a very interesting feature for CLI app: faster startup and reduced binary size

Add example description

Hi, can you give me a simple example of how to get the http/https traffic from a browser or any other device within the LAN? Just like the fluxzy desktop version, you can get the URL and other details of the request and response. I have read the documentation and API you provided, but since I don’t know much English, I can only use translation. I don’t understand many places, so I am particularly Came here to ask for help, I saw this example in the documentation but not how to get the requested URLs and the response information associated with them:

Deflect OS traffic

Fluxy.Core provides APIs to automatically deflects OS traffic to itself. This feature is only available on Desktop environment (Windows, macOS and Gnome based Linux).

The static method SystemProxyRegistrationHelper.Create is the entry point to enable this feature. It takes endpoints returned by Proxy.Start() as argument and register the first available endpoint as the system proxy. The call returns an IAsyncDisposable that can be used to revert the system proxy to its previous state.

using Fluxzy;
using Fluxzy.Core;

// Create a new proxy instance 
await using var proxy = new Proxy(FluxzySetting.CreateDefault());

// Proxy run will returns the endpoints that the proxy is listening on
var endPoints = proxy.Run();

// Pick an endpoint and register it as the system proxy
var proxyRegistration = await SystemProxyRegistrationHelper.Create(endPoints.First());

// System proxy is now set 

// Call DisposeAsync() to unregister the proxy
await proxyRegistration.DisposeAsync();

My purpose is to implement a very simple tool similar to the desktop version in my WPF, which can display the URL list of http/https requests and responses of all programs that use proxies, as well as the body of the response. Thank you for your hard work. Got it

Support mtls (client certificate) when using Bouncy Castle SSL Provider

Right now, client certificate is only possible with native SSL provider. Make client certificate feature enable when using Bouncy Castle.

Export curl command from `Fluxzy.Core`

Is your feature request related to a problem? Please describe.
In Fluxzy Desktop, you can export an HTTP request to curl command. I would like to automate this feature with Core.
Is it possible do implement this feature?

Describe the solution you'd like

Thank you for this awesome nuget btw.

Enable chaining to an upstream proxy

Allow fluxzy to chain outbound connections to another HTTP proxy. This new feature shall be defined as rule to allow only particular request to be chained to the outbound proxy.

IStreamSubstitution Unable to Mock Request Body

Describe the bug
https://fluxzy.io/documentation/528-transport-errors">fluxzy.io/documentation/528-transport-errors

Describe the tool and the environment
Fluxzy.Core

To Reproduce
Steps to reproduce the behavior:

1. fluxzySetting.WhenAll( the uri filter).Do(new ReqMockAction)
2. create a class ReqMockAction:Action
3. inside InternalAlter function -> context.RegisterRequestBodySubstitution(new RequestBodySubsitition());
4. ActionScope => RequestHeaderReceivedFromClient
5. create a class with RequestBodySubsitition: IStreamSubstitution
6. for Substitute(Stream originalStream) -> await originalStream.FlushAsync();
7. add some request body changing code and convert to new MemoryStream
   Expected behavior
   the request should be mocked

Add proxy authentication

Add option to enable a basic authentication when connecting to the proxy

Remove `Microsoft.Win32.Registry` dependency

Microsoft.Win32.Registry depends on .NETCoreApp* which has known security issues with .NET standard 2.1.
This package is used only to setup system proxy on win32. Replace with straightforward pinvoke calls or any equivalent.