Babel Obfuscator Tool ★Ultimate

Che cosa contiene il pacchetto

Babel.Obfuscator.Tool è un pacchetto di tipo strumento .NET  che installa il comando babel. È lo stesso strumento da riga di comando distribuito nei pacchetti zip babel_net*, con le stesse opzioni, ed è compreso nell’edizione Ultimate e nelle edizioni per sede di Babel Licensing (Server e Data Center). Il pacchetto include una build dello strumento per ogni runtime supportato, da .NET 6.0 a .NET 10.0, e la CLI dotnet sceglie la build che corrisponde all’SDK presente sul computer. Ogni build contiene:

• babel.dll, lo strumento da riga di comando, con la sua configurazione di runtime.
• Il plugin BabelEncrypt, pronto per essere caricato con --plugin.
• Babel.Build.dll, l’assembly del task Babel di MSBuild, per gli script di build che referenziano il task Babel tramite il percorso del file.

Come Babel.Obfuscator, il pacchetto dello strumento non è su nuget.org: ospitalo sul tuo feed come descritto in Ospitare il pacchetto.

Quando usare lo strumento

Usa lo strumento quando vuoi eseguire Babel direttamente, anziché come passo di una build MSBuild:

• Offuscare assembly già compilati, per esempio binari .NET Framework prodotti da un altro sistema di build.
• Offuscare molti assembly tramite script o in batch, e automatizzare il lavoro tramite agenti con la modalità compatibile con l’AI.
• Eseguire lo strumento da riga di comando su computer e agenti di build Linux e macOS.
• Usare comandi di utilità come la decodifica di uno stack trace (--stacktrace), il controllo della licenza (--license) o la generazione di un progetto MSBuild a partire da una riga di comando (--makeproject).

Installare lo strumento

Strumento globale

Uno strumento globale viene installato una volta per utente ed è disponibile da ogni terminale:

dotnet tool install Babel.Obfuscator.Tool -g

Quando il feed non è elencato in un file NuGet.config, passalo esplicitamente. L’origine può essere l’URL di un feed o una cartella locale:

dotnet tool install Babel.Obfuscator.Tool -g --add-source ~/NuGet

Su Linux e macOS assicurati che la cartella degli strumenti sia nel PATH, altrimenti il comando babel non viene trovato:

export PATH="$PATH:$HOME/.dotnet/tools"

Strumento locale

Uno strumento locale è fissato a un repository tramite un manifesto degli strumenti, così ogni sviluppatore e ogni agente CI esegue la stessa versione di Babel:

dotnet new tool-manifest
dotnet tool install Babel.Obfuscator.Tool

Lo strumento viene così registrato in .config/dotnet-tools.json, che devi includere nel commit. Su qualsiasi altro computer, dotnet tool restore installa la versione fissata. Uno strumento locale si richiama tramite la CLI dotnet:

dotnet babel --version

Aggiornare e rimuovere

dotnet tool update Babel.Obfuscator.Tool -g
dotnet tool list -g
dotnet tool uninstall Babel.Obfuscator.Tool -g

Per uno strumento locale ometti -g. Gli stessi comandi sono descritti in Installazione.

Fornire la licenza allo strumento

Lo strumento richiede la stessa licenza del prodotto. Uno strumento dotnet non ha una cartella di installazione in cui copiare babel.licenses, quindi fornisci la licenza a Babel in uno di questi modi:

• Imposta la variabile d’ambiente BABEL_LICENSE_PATH sul percorso completo del file di licenza. È la configurazione consigliata sui computer degli sviluppatori e sugli agenti di build:

export BABEL_LICENSE_PATH=~/Babel/babel.licenses

• Passa --license a ogni chiamata, con il percorso del file di licenza o di una cartella in cui cercarlo.
• Passa --license env:BABEL_LICENSE, dove la variabile contiene una chiave di licenza: è la scelta giusta sui server di build, dove la chiave è conservata in un segreto. Per una licenza flottante, salva la chiave utente come floating:<user key>.

babel --license senza argomenti stampa la licenza in uso. Ricorda che un file di licenza è valido per una sola versione del prodotto: usa il file ricevuto con la stessa versione dello strumento e aggiorna entrambi insieme.

Usare lo strumento

Il comando babel accetta la sintassi e le opzioni documentate in Riga di comando e nel Riferimento della riga di comando. Una chiamata tipica indica l’assembly da offuscare, il file di output e le funzionalità da abilitare:

babel MyApp.dll --output obfuscated/MyApp.dll --stringencryption stream --controlflow if=on --controlflow switch=on --iterations 3 --resourceencryption --rules babelRules.xml --mapout

Tutte le funzionalità descritte in questo manuale sono disponibili dallo strumento: le regole con --rules, l’unione e l’incorporamento con gli assembly passati come argomenti aggiuntivi e con --embed, i file map con --mapin e --mapout, i plugin con --plugin e il decifratore AES gestito con --use encryption=aesmanaged. Con uno strumento locale, anteponi dotnet al comando.

Script e automazione

Dalla versione 11.7 la riga di comando ha una modalità compatibile con l’AI pensata per script e agenti:

babel MyApp.dll --stringencryption stream --format ndjson --quiet --strict-exit

--format json o ndjson trasforma l’output in un flusso leggibile dalle macchine e indirizza sullo standard error la diagnostica destinata alle persone, --quiet rimuove il banner e fa fallire subito qualsiasi richiesta interattiva, e --strict-exit restituisce un codice di uscita distinto per argomenti non validi, input mancante ed errori di offuscamento, di licenza e di firma.

Eseguire lo strumento su un server di build

Lo strumento si adatta alle pipeline che offuscano gli artefatti della build in un passo separato. Con un manifesto degli strumenti incluso nel repository e il feed configurato in NuGet.config (vedi l’esempio GitHub Actions per una configurazione che si autentica su GitHub Packages), un job di GitHub Actions ha questo aspetto:

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-dotnet@v4
    with:
      dotnet-version: '10.0.x'
  - name: Restore tools
    run: dotnet tool restore
    env:
      PACKAGES_TOKEN: ${{ secrets.PACKAGES_TOKEN }}
  - name: Obfuscate
    run: dotnet babel artifacts/MyLib.dll --license env:BABEL_LICENSE --stringencryption stream --strict-exit
    env:
      BABEL_LICENSE: ${{ secrets.BABEL_LICENSE_SECRET }}

Host con FIPS abilitato

Dalla versione 11.8 i binari dello strumento sono offuscati a loro volta con l’algoritmo AES gestito, così babel si avvia anche sugli host in cui il provider FIPS di OpenSSL non funziona. Gli assembly che proteggi su questi host hanno comunque bisogno di un proprio decifratore gestito: usa l’algoritmo di cifratura delle stringhe STREAM e --use encryption=aesmanaged per le altre funzionalità di cifratura, come spiegato in Conformità FIPS.

Risoluzione dei problemi

• babel: command not found: la cartella degli strumenti globali non è nel PATH; aggiungi ~/.dotnet/tools a PATH, oppure usa uno strumento locale ed esegui dotnet babel.
• Un messaggio che chiede di installare .NET: la build dello strumento selezionata richiede il runtime .NET corrispondente, dalla versione 6.0 alla 10.0. Installa quel runtime, oppure imposta DOTNET_ROLL_FORWARD=Major per eseguire lo strumento su un runtime più recente.
• A valid license could not be found: controlla BABEL_LICENSE_PATH o l’argomento --license, poi esegui babel --license per vedere che cosa ha caricato Babel. Un file di licenza di un’altra versione viene segnalato come non valido.
• L’output è diverso da quello di un’esecuzione di Babel Desktop: Babel Desktop applica le impostazioni salvate nel suo progetto .babel, mentre lo strumento applica solo le opzioni presenti sulla riga di comando. Confronta le due configurazioni, in particolare l’Obfuscation Agent e le regole.