Skip to content

Commit caf8987

Browse files
author
RandomCrocodile
committed
docs: restructure README as landing page with dedicated doc pages
Slim down README to a clean overview with badges, quick start, and doc links. Move detailed content into separate docs: getting-started, protections reference, CLI reference, building from source, and declarative obfuscation (converted from .txt).
1 parent 840f557 commit caf8987

6 files changed

Lines changed: 725 additions & 95 deletions

File tree

‎README.md‎

Lines changed: 37 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -1,132 +1,74 @@
11
# ConfuserExx
22

33
[![CI][img_ci]][ci]
4+
[![Tests][img_test]][test]
45
[![CodeQL][img_codeql]][codeql]
56
[![MIT License][img_license]][license]
67

7-
An actively maintained fork of [ConfuserEx][upstream] — an open-source protector for .NET applications.
8-
9-
> The original [mkaring/ConfuserEx][upstream] has been dormant since 2022. This fork includes bug fixes, new features, and modern .NET support.
10-
11-
## Features
12-
13-
* Supports .NET Framework 2.0/3.5/4.x, .NET Standard 2.0, .NET Core, .NET 5+/6/7/8+
14-
* Symbol renaming (Support WPF/BAML)
15-
* Protection against debuggers/profilers
16-
* Protection against memory dumping
17-
* Protection against tampering (method encryption)
18-
* Control flow obfuscation
19-
* Constant/resources encryption
20-
* Reference hiding proxies
21-
* Disable decompilers
22-
* Embedding dependency
23-
* Compressing output
24-
* Extensible plugin API
25-
* Roslyn code analysis integration
26-
* Auto-detection of .NET runtime paths for modern framework support
27-
28-
## What's improved over upstream
29-
30-
* Fixed WPF resource renaming, .NET Standard obfuscation, control flow protection
31-
* Serialization-aware renaming (DataContract, DataMember, JsonProperty)
32-
* Graceful handling of external/unresolvable assemblies (no more crashes)
33-
* Auto-detection of .NET Core/5+/6/7/8+ runtime assembly paths
34-
* CLI `--snkey` and `--snkeypass` options for CI/CD signing
35-
* Wildcard module loading in `.crproj` files
36-
* Roslyn analyzers (NetAnalyzers + Roslynator) for code quality
37-
* GitHub Actions CI/CD with automatic releases
38-
* Better error messages for .NET 6+ native host executables
39-
40-
## Usage
8+
An actively maintained .NET obfuscator. Protects assemblies from .NET Framework 2.0 through .NET 10+.
419

42-
```bash
43-
Confuser.CLI.exe <path to project file>
44-
```
45-
46-
The project file is a ConfuserEx Project (`*.crproj`).
47-
The format of project file can be found in [docs/ProjectFormat.md][project_format].
48-
49-
### CLI Options
50-
51-
```
52-
-n|noPause : no pause after finishing protection
53-
-o|out : specifies output directory
54-
-probe : specifies probe directory
55-
-plugin : specifies plugin path
56-
-debug : specifies debug symbol generation
57-
-snkey : specifies strong name key file path
58-
-snkeypass : specifies strong name key password
59-
```
60-
61-
## Building from Source
62-
63-
### Prerequisites
10+
The original [mkaring/ConfuserEx][mkaring] has been dormant since 2022. This fork ships bug fixes, modern framework support, and an automated release pipeline.
6411

65-
* [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) (or later)
66-
* [.NET Framework 4.8 Developer Pack](https://dotnet.microsoft.com/download/dotnet-framework/net48) (for library targets and test subjects)
67-
* [Visual Studio 2025+](https://visualstudio.microsoft.com/) with **Desktop development with C++** workload (for the C++/CLI test project)
68-
* Windows 10/11 (WPF GUI is Windows-only)
12+
## Get Started
6913

70-
### Build
14+
Download the latest build from [Releases][releases], extract, and run:
7115

7216
```bash
73-
# Full solution (requires VS 2025+ MSBuild 18)
74-
msbuild Confuser2.sln -p:Configuration=Release
17+
# GUI
18+
ConfuserEx.exe
7519

76-
# .NET projects only (without C++/CLI test project)
77-
dotnet build Confuser2.sln -c Release
78-
79-
# Run tests
80-
dotnet test Confuser2.sln -c Release
20+
# CLI
21+
Confuser.CLI.exe my-project.crproj
8122
```
8223

83-
### Target Frameworks
84-
85-
| Project | TFM |
86-
|---------|-----|
87-
| Core, Protections, Renamer, DynCipher | net48 + netstandard2.0 |
88-
| GUI (ConfuserEx) | net10.0-windows |
89-
| CLI (Confuser.CLI) | net10.0 |
90-
| Runtime | net20 (injected into targets) |
24+
See the [Getting Started Guide](docs/getting-started.md) for walkthroughs and configuration.
9125

92-
## Bug Report
26+
## Documentation
9327

94-
See the [Issues][issues] section. Please check existing issues before filing a new one.
28+
| | |
29+
|---|---|
30+
| [Getting Started](docs/getting-started.md) | Installation, first run, basic configuration |
31+
| [Protections](docs/protections.md) | All protections with options, presets, and examples |
32+
| [CLI Reference](docs/cli-reference.md) | Command-line options and usage |
33+
| [Project File Format](docs/ProjectFormat.md) | `.crproj` XML schema, rules, and pattern expressions |
34+
| [Declarative Obfuscation](docs/declarative-obfuscation.md) | Attribute-based configuration via `[Obfuscation]` |
35+
| [Building from Source](docs/building.md) | Prerequisites, build commands, and project layout |
36+
| [Contributing](CONTRIBUTING.md) | How to contribute, test policy, and PR workflow |
9537

96-
## Contributing
38+
## Issues
9739

98-
1. Fork the repository
99-
2. Create a branch from `develop` (see [CONTRIBUTING.md](CONTRIBUTING.md) for naming conventions)
100-
3. Make your changes and ensure CI passes
101-
4. Open a PR targeting `develop`
40+
Check [existing issues][issues] first, then [open a new one][new_issue].
10241

10342
## License
10443

105-
Licensed under the MIT license. See [LICENSE.md][license] for details.
44+
MIT. See [LICENSE.md][license].
45+
46+
## Credits
47+
48+
- **[0xd4d][0xd4d]** — [dnlib][dnlib]
49+
- **[Ki (yck1509)][ki]** — original ConfuserEx
50+
- **[Martin Karing][mkaring]** — maintained through v1.6
10651

10752
## Contributors
10853

10954
<a href="https://github.com/mcpolo99/ConfuserExx/graphs/contributors">
11055
<img src="https://contrib.rocks/image?repo=mcpolo99/ConfuserExx" />
11156
</a>
11257

113-
## Credits
114-
115-
**[0xd4d]** for [dnlib][dnlib] and extensive .NET metadata knowledge.
116-
**[Ki (yck1509)][ki]** for the original ConfuserEx.
117-
**[Martin Karing][mkaring]** for maintaining the project through v1.6.
118-
58+
<!-- links -->
11959
[0xd4d]: https://github.com/0xd4d
12060
[dnlib]: https://github.com/0xd4d/dnlib
12161
[ki]: https://github.com/yck1509
122-
[mkaring]: https://github.com/mkaring
123-
[upstream]: https://github.com/mkaring/ConfuserEx
62+
[mkaring]: https://github.com/mkaring/ConfuserEx
12463
[ci]: https://github.com/mcpolo99/ConfuserExx/actions/workflows/ci.yml
64+
[test]: https://github.com/mcpolo99/ConfuserExx/actions/workflows/test.yml
12565
[codeql]: https://github.com/mcpolo99/ConfuserExx/actions/workflows/codeql-analysis.yml
12666
[issues]: https://github.com/mcpolo99/ConfuserExx/issues
67+
[new_issue]: https://github.com/mcpolo99/ConfuserExx/issues/new/choose
68+
[releases]: https://github.com/mcpolo99/ConfuserExx/releases
12769
[license]: LICENSE.md
128-
[project_format]: docs/ProjectFormat.md
12970

130-
[img_ci]: https://github.com/mcpolo99/ConfuserExx/actions/workflows/ci.yml/badge.svg?branch=main
71+
[img_ci]: https://github.com/mcpolo99/ConfuserExx/actions/workflows/ci.yml/badge.svg
72+
[img_test]: https://github.com/mcpolo99/ConfuserExx/actions/workflows/test.yml/badge.svg
13173
[img_codeql]: https://github.com/mcpolo99/ConfuserExx/actions/workflows/codeql-analysis.yml/badge.svg
132-
[img_license]: https://img.shields.io/github/license/mcpolo99/ConfuserExx.svg?style=flat
74+
[img_license]: https://img.shields.io/github/license/mcpolo99/ConfuserExx.svg

‎docs/building.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Building from Source
2+
3+
## Prerequisites
4+
5+
- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) (or later)
6+
- [.NET Framework 4.8 Developer Pack](https://dotnet.microsoft.com/download/dotnet-framework/net48)
7+
- [Visual Studio 2025+](https://visualstudio.microsoft.com/) with **Desktop development with C++** workload (only needed for the C++/CLI test project)
8+
- Windows 10/11 (WPF GUI is Windows-only)
9+
10+
## Build
11+
12+
```bash
13+
# Full solution (requires VS 2025+ / MSBuild 18 for C++/CLI test project)
14+
msbuild Confuser2.sln -p:Configuration=Release
15+
16+
# .NET projects only (skips C++/CLI test — works without VS C++ workload)
17+
dotnet build Confuser2.sln -c Release
18+
```
19+
20+
## Test
21+
22+
```bash
23+
# All tests
24+
dotnet test Confuser2.sln -c Release
25+
26+
# Specific test project
27+
dotnet test Tests/Confuser.CLI.Test/Confuser.CLI.Test.csproj -c Release
28+
29+
# With coverage
30+
dotnet test Confuser2.sln -c Release --collect:"XPlat Code Coverage"
31+
```
32+
33+
## Clean
34+
35+
```bash
36+
./scripts/clean-build-artifacts.sh
37+
```
38+
39+
## Project Layout
40+
41+
```
42+
Confuser.Core/ Core obfuscation engine
43+
Confuser.Protections/ Built-in protection implementations
44+
Confuser.Renamer/ Renaming protection (separate due to complexity)
45+
Confuser.DynCipher/ Dynamic cipher generation for protections
46+
Confuser.Runtime/ Runtime stubs injected into protected assemblies (net20)
47+
Confuser.CLI/ Command-line interface
48+
ConfuserEx/ WPF GUI application
49+
Confuser.MSBuild.Tasks/ MSBuild integration NuGet package
50+
Tests/ Unit, integration, and end-to-end tests
51+
docs/ Documentation
52+
scripts/ Build and maintenance scripts
53+
additional/ Example .crproj files
54+
```
55+
56+
## Target Frameworks
57+
58+
| Project | TFM | Notes |
59+
|---------|-----|-------|
60+
| Core, Protections, Renamer, DynCipher | `net48` + `netstandard2.0` | Multi-targeted for broad compatibility |
61+
| GUI (ConfuserEx) | `net10.0-windows` | WPF, Windows-only |
62+
| CLI (Confuser.CLI) | `net10.0` | Cross-platform |
63+
| Runtime | `net20` | Injected into target assemblies at any framework level |
64+
| MSBuild Tasks | `netstandard2.0` | Runs inside MSBuild process |
65+
66+
## CI/CD
67+
68+
| Workflow | Trigger | Purpose |
69+
|----------|---------|---------|
70+
| `ci.yml` | Push to `master`, `pre-release`, `feature/**`, `fix/**` + PRs to `master`/`pre-release` | Build, package, create releases |
71+
| `test.yml` | Push to `master`, `pre-release`, `feature/**`, `fix/**` + PRs to `master`/`pre-release` | Build, test, coverage report |
72+
| `format.yml` | Every push | Code style and Roslyn analyzer checks |
73+
| `codeql-analysis.yml` | Weekly + manual | Security analysis |
74+
75+
Releases are created automatically by `ci.yml`:
76+
- Push to `pre-release` branch creates (or updates) a pre-release on GitHub
77+
- Push to `master` branch creates a stable versioned release with a git tag
78+
79+
Versioning is handled by [Nerdbank.GitVersioning](https://github.com/dotnet/Nerdbank.GitVersioning) from `version.json`.

‎docs/cli-reference.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# CLI Reference
2+
3+
## Usage
4+
5+
```bash
6+
Confuser.CLI.exe [options] <project-file>
7+
```
8+
9+
The project file is a `.crproj` XML file describing which modules to protect and which protections to apply. See [Project File Format](ProjectFormat.md).
10+
11+
## Options
12+
13+
| Option | Description |
14+
|--------|-------------|
15+
| `-n`, `--noPause` | Do not pause after finishing (useful in CI/CD) |
16+
| `-o`, `--out <dir>` | Override the output directory from the project file |
17+
| `-probe <dir>` | Add a probe directory for dependency resolution |
18+
| `-plugin <path>` | Load a protection plugin from the given path |
19+
| `-debug` | Generate debug symbols (`.pdb`) for the protected output |
20+
| `-snkey <path>` | Strong name key file (`.snk` or `.pfx`) for signing |
21+
| `-snkeypass <password>` | Password for the strong name key (when using `.pfx`) |
22+
23+
## Examples
24+
25+
### Basic protection
26+
27+
```bash
28+
Confuser.CLI.exe MyApp.crproj
29+
```
30+
31+
### Override output directory
32+
33+
```bash
34+
Confuser.CLI.exe MyApp.crproj -o ./protected
35+
```
36+
37+
### CI/CD with strong-name signing
38+
39+
```bash
40+
Confuser.CLI.exe MyApp.crproj -n -snkey signing.snk
41+
```
42+
43+
### With a plugin
44+
45+
```bash
46+
Confuser.CLI.exe MyApp.crproj -plugin ./MyCustomProtection.dll
47+
```
48+
49+
### Multiple probe paths
50+
51+
```bash
52+
Confuser.CLI.exe MyApp.crproj -probe ./libs -probe ./shared
53+
```
54+
55+
## Exit Codes
56+
57+
| Code | Meaning |
58+
|------|---------|
59+
| `0` | Protection completed successfully |
60+
| non-zero | Protection failed (check console output for details) |
61+
62+
## MSBuild Integration
63+
64+
The `Confuser.MSBuild.Tasks` NuGet package runs the CLI as a post-build step:
65+
66+
```xml
67+
<PackageReference Include="Confuser.MSBuild.Tasks" Version="1.7.0-*" />
68+
```

0 commit comments

Comments
 (0)