Skip to content

Referencia

MSBuild y CI

Protege tus ensamblados automáticamente en cada compilación y en tu canalización de CI.

En producción, protege automáticamente en lugar de a mano. Nebula se integra tanto con MSBuild como con cualquier sistema de CI.

Nebula ofusca tus ensamblados compilados, no tu código fuente. Eso significa que no hay dependencia del código fuente: ni atributos, ni using, ni llamadas a API, y (con la CLI) ni siquiera una referencia de paquete en tus proyectos. Tu código permanece completamente libre de Nebula; la protección se aplica a la salida de la compilación.

Ofuscar solo en el servidor de compilación

Un requisito común: las compilaciones de los desarrolladores quedan sin ofuscar; solo se protege la compilación que produce tus paquetes oficiales y distribuibles. Como MSBuild expone automáticamente las variables de entorno como propiedades de compilación, condicionas la ofuscación a una variable que exista solo en el agente de compilación — mismo código, mismo dotnet build, sin flags ni cambios de código.

La integración con la compilación es una característica licenciada. La edición Free es solo la CLI y la app de escritorio; ofuscar como parte de una compilación requiere una licencia en la máquina de compilación.

Dos maneras de licenciar una máquina de compilación (no las confundas):

  • Clave en línea — ejecuta nebula register --key LIC-… una vez en el agente. Lo mejor para una máquina de compilación persistente (usa un puesto para esa máquina).
  • Archivo de licencia firmado sin conexión — establece NEBULA_LICENSE (o licenseFile en la configuración) a la ruta de un archivo .license firmado. Lo mejor para ejecutores CI efímeros, ya que no necesita activación de puesto en línea. NEBULA_LICENSE es una ruta de archivo, no una clave — una cadena LIC-… ahí no se resolverá.

Ejecuta la CLI nebula desde un archivo de infraestructura de compilación, condicionado por una variable exclusiva del agente de compilación. La CLI viene con la instalación de Nebula (la descarga) — no hay ningún paquete que añadir a tus proyectos, y nada en tu .csproj ni en tu C# referencia a Nebula. Registra en el repositorio un pequeño Directory.Build.targets que invoque la CLI sobre la salida de la compilación:

<!-- Directory.Build.targets at the repo root -->
<Project>
  <Target Name="NebulaObfuscate" AfterTargets="Build"
          Condition="'$(NEBULA_OBFUSCATE)' == '1' and '$(TargetFramework)' != ''">
    <Exec Command="nebula --config &quot;$(MSBuildThisFileDirectory)nebula.config.json&quot; --input &quot;$(TargetPath)&quot; --output &quot;$(TargetDir)obf&quot;" />
  </Target>
</Project>

En el agente de compilación establece NEBULA_OBFUSCATE=1 (más una licencia — ver abajo) y asegúrate de que nebula esté en el PATH. Las máquinas de los desarrolladores — donde la variable no está establecida — omiten el paso, compilan sin ofuscar y no necesitan tener Nebula instalado. El modificador --input permite que una sola configuración compartida de solo ajustes (transformaciones pero sin inputs) dirija la ejecución mientras la compilación suministra cada ensamblado; el guardia '$(TargetFramework)' != '' hace que se ejecute una vez por framework de destino en proyectos multi-destino (y que omita la compilación agregada). Funciona tanto con dotnet build como con Visual Studio / msbuild.exe.

Establecer las variables en el agente de compilación

Establécelas una vez en la máquina de compilación, con la cuenta bajo la que se ejecutan tus compilaciones, usando el shell que use tu agente.

Windows — Símbolo del sistema (cmd):

:: Persistent (applies to future build sessions):
setx NEBULA_OBFUSCATE 1
setx NEBULA_LICENSE "C:\keys\nebula-license.json"

:: Just the current session:
set NEBULA_OBFUSCATE=1
set NEBULA_LICENSE=C:\keys\nebula-license.json

Windows — PowerShell:

# Persistent, machine-wide (run PowerShell as Administrator):
[Environment]::SetEnvironmentVariable('NEBULA_OBFUSCATE', '1', 'Machine')
[Environment]::SetEnvironmentVariable('NEBULA_LICENSE', 'C:\keys\nebula-license.json', 'Machine')

# Just the current session:
$env:NEBULA_OBFUSCATE = '1'
$env:NEBULA_LICENSE   = 'C:\keys\nebula-license.json'

Agentes de compilación Linux / macOS (bash):

# Add to the agent's service environment or profile:
export NEBULA_OBFUSCATE=1
export NEBULA_LICENSE=/etc/nebula/nebula-license.json

La mayoría de los sistemas de CI también te permiten definir estas como variables de canalización/agente en su interfaz — establécelas solo en el agente de compilación, nunca en el repositorio. Después de setx o de un cambio a nivel de máquina, reinicia el agente/shell para que las nuevas compilaciones las recojan.

Para un producto multiensamblado, ofusca la salida publicada en un solo paso (todas las DLL juntas) en lugar de por proyecto, para que las referencias entre ensamblados se mantengan consistentes — usa AfterTargets="Publish" o un paso de publicación dedicado, condicionado de la misma manera. Consulta Múltiples ensamblados.

En CI

Como la CLI se dirige por configuración y devuelve códigos de salida con significado, integrarla en una canalización es un solo paso:

nebula --config nebula.config.json --json nebula-summary.json

Si la protección falla (configuración incorrecta, licencia ausente), el código de salida distinto de cero hace fallar la compilación. El resumen --json puede archivarse como artefacto de compilación.

Licenciamiento en CI

Los ejecutores CI también son máquinas, así que una activación en línea usa un puesto por máquina. Elige según el tipo de ejecutor:

  • Ejecutor persistente / autoalojado: activa una vez con nebula register --key LIC-…. Usa un puesto para esa máquina y cada compilación lo reutiliza.
  • Ejecutor efímero (p. ej. alojado por GitHub — una VM nueva en cada ejecución): usa un archivo de licencia firmado sin conexión para no consumir un puesto nuevo en cada ejecución. Guárdalo como secreto, escríbelo en un archivo durante el trabajo y apunta NEBULA_LICENSE a esa ruta (no a la clave). Pídenos un archivo de licencia sin conexión para tu canalización de compilación.

Consejo: mantén nebula.config.json en el control de versiones junto a tu proyecto para que los ajustes de protección se versionen con tu código.

Proyectos multi-destino — cada framework, automáticamente

El guardia '$(TargetFramework)' != '' en el target (arriba) hace que se ejecute una vez por framework de destino en un proyecto multi-destino (por ejemplo <TargetFrameworks>net462;net6.0</TargetFrameworks>), ofuscando el $(TargetPath) propio de cada framework y omitiendo la compilación externa agregada. --output "$(TargetDir)obf" ya es por framework, así que no hay colisiones de nombres de archivo. No listas los frameworks en ninguna parte — lo que sea que compile un proyecto queda protegido.

Esto se combina con una configuración de solo ajustes — un nebula.config.json con las transformaciones (renombrado, controlFlowInclude, encryptStringsInclude, firma) pero sin inputs. El modificador --input de la CLI suministra el ensamblado de cada framework en tiempo de compilación, de modo que una sola configuración compartida protege todos los proyectos y todos los frameworks:

nebula --config settings.json --input MyApp.dll --output out

Visual Studio y msbuild.exe

Como la integración invoca la CLI nebula en lugar de cargar una tarea de MSBuild, funciona igual tanto con dotnet build como con Visual Studio / msbuild.exe — sin configuración específica del motor. Pon nebula en el PATH del agente de compilación (o usa su ruta completa en el comando <Exec>). Las máquinas de los desarrolladores que no establecen la variable de condición compilan exactamente como antes y no necesitan tener Nebula instalado.

Licenciar solo el servidor de compilación

Como ofuscas en el servidor de compilación, solo necesitas licenciar la(s) máquina(s) de compilación — no a cada desarrollador. El licenciamiento de Nebula es por máquina: en un agente persistente activa una clave en línea con nebula register --key LIC-…, o apunta NEBULA_LICENSE / licenseFile a la ruta de un archivo de licencia firmado sin conexión (lo mejor para ejecutores efímeros). Los desarrolladores no necesitan tener nada instalado.

Hacer fallar la compilación si la licencia no puede proteger (recomendado)

Establece "requireLicensedEdition": true en la configuración para que una compilación falle en lugar de distribuir en silencio una salida débilmente ofuscada cuando la licencia está ausente, revocada, caducada o es de un nivel demasiado bajo para lo que pediste (por ejemplo, el flujo de control aggressive necesita Enterprise; en Pro, de lo contrario, se degradaría a normal). Sin este flag, un problema de licencia simplemente baja a la edición Free y aun así emite salida.

La compilación vuelve a verificar el arrendamiento de activación en línea a medida que se acerca a su caducidad, por lo que una licencia revocada se detecta en la siguiente compilación — dale al agente acceso de red saliente. Sin conexión, el arrendamiento en caché se respeta solo hasta que expira, tras lo cual la edición baja a Free (y, con requireLicensedEdition, la compilación falla). Mantén activa la licencia del agente.