Skip to content

Referencia

Referencia de configuración

Cada campo de nebula.config.json — tipos, valores por defecto y qué hace.

Nebula se controla mediante un archivo de config JSON (nebula.config.json) pasado con --config. Esta es la lista completa de campos. Todos son opcionales salvo inputs; las claves desconocidas producen una advertencia en lugar de ignorarse silenciosamente.

{
  "inputs": ["bin/Release/net8.0/MyApp.dll"],
  "outputDirectory": "bin/Release/net8.0/obf",
  "preservePublicApi": true,
  "controlFlowObfuscation": true,
  "encryptStrings": true
}

Ediciones. La edición Free hace renombrado de identificadores, hasta 2 cadenas cifradas y hasta 2 métodos con flujo de control. Todo lo demás (cadenas/flujo de control ilimitados, cifrado de métodos y recursos, ofuscación de referencias (llamadas por proxy), anti-manipulación, anti-depuración, detección de entorno/herramientas de manipulación, guardia de caducidad, auto-protección de licenciamiento, endurecimiento de metadatos, enmascarado de constantes, nombrado agresivo, renombrado entre ensamblados, firma, salida de PDB, plugins) es Pro; la intensidad aggressive del flujo de control y la marca de agua son Enterprise; la virtualización de código se incluye en Pro. Consulta Ediciones.

Entrada y salida

ClaveTipoPor defectoDescripción
inputsstring[]— (obligatorio)Ruta(s) de ensamblado a ofuscar. Enumera todos los ensamblados interdependientes juntos para un renombrado consistente entre ellos — consulta Varios ensamblados.
outputDirectorystring<inputDir>/nebulatedDónde se escriben los ensamblados ofuscados, los mapas de símbolos y los informes.
allowInPlaceboolfalseProtección de seguridad: sobrescribir el ensamblado de entrada se rechaza salvo que esto sea true, de modo que una ruta mal escrita no pueda destruir tu ensamblado de origen.
copyRuntimeConfigbooltrueCopia el *.runtimeconfig.json / *.deps.json de cada entrada junto a la salida para que una app dependiente del framework se ejecute desde la carpeta de salida.
verifyOutputbooltrueVuelve a comprobar el módulo transformado en busca de referencias colgantes antes de escribir y se niega a emitir una salida que no cargaría. Déjalo activado.
schemaVersionint1Versión del esquema de la config, para que los archivos antiguos reciban una advertencia clara de actualización.

Renombrado

ClaveTipoPor defectoDescripción
preservePublicApiboolfalseMantiene los nombres de tipos y miembros public/protected; renombra solo los internal/private. Actívalo on para una biblioteca referenciada por código fuera de la ejecución; off para renombrar todo lo elegible.
autoDetectbooltruePreserva automáticamente los nombres requeridos para la corrección — objetivos de reflexión/serialización/DI/XAML y miembros marcados con [Obfuscation]. Déjalo activado.
includestring[][]Lista de permitidos de nombres completos de tipo elegibles para renombrado. Cuando no está vacía, solo estos tipos (y sus miembros) se renombran; todo lo demás se preserva.
excludestring[][]Fuerza la preservación de nombres. Un nombre completo de tipo preserva el tipo y todos sus miembros; "Namespace.Type.Member" preserva un solo miembro.
excludeNamespacesstring[][]Fuerza la preservación de espacios de nombres completos: cualquier tipo cuyo espacio de nombres coincida o comience con una entrada (p. ej., MyApp.Api) mantiene su nombre y el de sus miembros.
renameResourcesboolfalseRenombra los nombres de recursos embebidos y actualiza las referencias (incl. los .resources asociados a un tipo, para que ResourceManager siga resolviéndolos).
aggressiveNamingboolfalseUsa identificadores Unicode confundibles y difíciles de leer en lugar de nombres ASCII cortos. Sigue siendo determinista y sin colisiones.
crossAssemblyRenameboolfalseEn una ejecución multiensamblado, renombra tipos/miembros compartidos entre los ensamblados de entrada y reescribe cada referencia entre ensamblados. Requiere que todos los ensamblados referenciantes sean entradas — consulta Varios ensamblados.

Cifrado de cadenas

ClaveTipoPor defectoDescripción
encryptStringsboolfalseCifra los literales de cadena en el IL y los descifra en tiempo de ejecución con una clave por compilación.
encryptStringsIncludestring[][]Lista de permitidos de literales exactos a cifrar. Cuando no está vacía, solo estos se cifran. Descúbrelos con nebula inspect --strings.
excludeStringsstring[][]Literales exactos a dejar sin cifrar (p. ej., el texto de la licencia).

Flujo de control y protección de código

ClaveTipoPor defectoDescripción
controlFlowObfuscationboolfalseAplana el flujo de control del método en una máquina de estados con despachador. Funciona para todas las formas de método, incluidos try/catch/finally (el nivel superior y cada cuerpo try se aplanan; los manejadores anidados se mantienen atómicos). Todo lo que no sea demostrablemente seguro de mover se deja intacto.
controlFlowIntensitystring"normal"none / light / normal / aggressive — aproximadamente el 0 / 25 / 60 / 100 % de los métodos elegibles cuando no se da una lista de inclusión explícita. aggressive es solo de Enterprise; en un nivel inferior se degrada a normal (y con requireLicensedEdition esa degradación hace fallar la compilación).
controlFlowIncludestring[][]Lista de permitidos de métodos a aplanar, por Namespace.Type.Method. Cuando no está vacía, solo estos se transforman. Descubre los nombres con nebula inspect --methods.
controlFlowExcludestring[][]Métodos a omitir, por Namespace.Type.Method.
obfuscateConstantsboolfalseEnmascara las cargas de literales enteros con una clave XOR por compilación resuelta al cargar (decodificada en línea en tiempo de ejecución). Esto es enmascarado ligero, no criptografía — rompe el literal plano y vence el escaneo ingenuo de constantes.
proxyReferencesboolfalseDe pago. Enruta call/callvirt a través de métodos proxy inyectados y sin marca para que un decompilador / de4dot no pueda leer a qué método externo o del BCL llama un sitio. Conservador y que preserva el comportamiento (omite constructores, genéricos, llamadas de instancia de tipos por valor, etc.).
virtualizeMethodsboolfalsePro. Compila los métodos elegibles a un bytecode personalizado ejecutado por una VM embebida — la lógica ya no existe como IL. Consulta virtualización de código.
virtualizeIncludestring[][]Lista de permitidos de métodos a virtualizar por Namespace.Type.Method (vacío = todos los elegibles).
encryptMethodsboolfalseLa protección de código estático más fuerte: cifra todo el IL de un método y lo vuelve a emitir en el momento de la llamada mediante el ayudante Nebula.Runtime (copiado junto a la salida), manteniendo el IL cifrado en reposo en memoria (anti-volcado). La elegibilidad es deliberadamente estrecha — cubre métodos estáticos, no genéricos, sin manejadores de excepciones ni parámetros por referencia/puntero; cualquier otra cosa se deja intacta. Ten en cuenta las contrapartidas: una vez que el JIT del CLR compila un método descifrado, su código nativo sigue residiendo en memoria, y descifrar en cada llamada añade sobrecarga por invocación, así que apúntalo a unos pocos métodos de alto valor en lugar de a rutas calientes.
encryptResourcesboolfalseCifra los recursos embebidos leídos mediante Assembly.GetManifestResourceStream(string) y los descifra a demanda. (Los .resources para ResourceManager/WinForms/satélite se omiten.)

Anti-manipulación y anti-depuración

ClaveTipoPor defectoDescripción
antiTamperboolfalseInyecta una comprobación de integridad en tiempo de carga (SHA-256 de la imagen escrita) que reacciona si el archivo se modificó después de la ofuscación. Detiene el parcheo casual.
antiTamperReactionstring"terminate"Al no coincidir: terminate (FailFast), throw, exit o callback.
antiTamperCallbackstringnullNamespace.Type.Method de un método estático y sin parámetros a llamar cuando la reacción es callback (debe preservarse para que se resuelva).
antiDebugboolfalseInyecta una comprobación de detección de depurador gestionado que se ejecuta al cargar el módulo. Desactivado por defecto para que nunca estorbe tus propias compilaciones de QA.
antiDebugReactionstring"throw"Ante un depurador detectado: throw, terminate, exit o callback.
antiDebugCallbackstringnullMétodo de callback para la reacción callback de anti-depuración.
environmentChecksboolfalseInyecta una comprobación en tiempo de carga que reacciona al ejecutarse bajo un profiler del CLR (CORECLR_ENABLE_PROFILING / COR_ENABLE_PROFILING) o un framework de parcheo en tiempo de ejecución conocido — Harmony o MonoMod.RuntimeDetour (Detour/Hook/NativeDetour). La detección es por tipo gestionado cargado; un hook nativo en línea puro o una inyección de DLL cruda quedan fuera de alcance. Desactivado por defecto para que nunca estorbe tu propio profiling/QA.
environmentChecksReactionstring"throw"Ante una detección: throw, terminate, exit o callback.
environmentChecksCallbackstringnullMétodo de callback para la reacción callback de la comprobación de entorno.
environmentChecksContinuousboolfalseSigue vigilando más allá del tiempo de carga (requiere environmentChecks): se suscribe a AppDomain.AssemblyLoad para que un parcheador que se adjunta después del inicio se detecte al cargarse, y vuelve a ejecutar la comprobación en la entrada de los métodos que llaman a tu SDK de licenciamiento (los mismos que encuentra autoProtectLicensing, vía licensingNamespaces) para que un depurador/parcheador adjuntado tarde se detecte en la puerta. Reutiliza la misma reacción.
environmentChecksIntervalSecondsint0Con el modo continuo, vuelve a comprobar también en un temporizador en segundo plano cada N segundos (0 = sin temporizador; el hook de AssemblyLoad y las recomprobaciones en los sitios de llamada siguen aplicándose). El primer disparo se desfasa (jitter) por compilación para que la cadencia no sea trivialmente identificable.
autoProtectLicensingboolfalseDirige automáticamente los métodos que llaman a tu SDK de licencias a la protección más fuerte que aplica la edición: los incluye a la fuerza en la virtualización (si está activada) y el aplanado del flujo de control, y nunca los excluye — sin necesidad de nombrar los métodos de control. Función de pago.
licensingNamespacesstring[]["Keyright"]Espacios de nombres raíz que autoProtectLicensing trata como el SDK de licencias. Por defecto Keyright; añade el espacio de nombres raíz de cualquier otro SDK de licencias.
expiryUtcdatenullCaducidad / «time-bomb»: un instante UTC tras el cual la compilación protegida deja de funcionar (para betas, evaluaciones, versiones embargadas). Un guardián en tiempo de carga reacciona una vez pasada la fecha. Se comprueba contra el reloj de la máquina, así que combínalo con antiTamper.
expiryReactionstring"throw"Al caducar: throw, terminate, exit o callback.
expiryCallbackstringnullMétodo de callback para la reacción callback de caducidad.
tamperReportUrlstringnullTelemetría de manipulación integrada («report-home»): cuando se establece, un guardián que se dispara (anti-manipulación, anti-depuración, comprobaciones de entorno, caducidad) también envía por POST un mínimo {"event":"…"} a esta URL — tu propio endpoint (nunca a Delta1 Labs) antes de su reacción, así obtienes telemetría sin escribir un callback. El envío es acotado y se traga sus propios errores — no puede bloquear ni colgar la app. Solo se envía el nombre del evento (ni código fuente, ni contenido de ensamblados, ni datos personales). Totalmente opcional: si no se establece, nunca se envía nada. Es tu telemetría a tu endpoint, por lo que es independiente de NEBULA_NO_TELEMETRY — esa variable solo silencia la analítica anónima propia de la herramienta Nebula (un canal aparte en tiempo de compilación) y no afecta a report-home. Función de pago; añade tráfico saliente desde las apps protegidas (no apto para air-gapped).
expiryMessagestringnullMensaje personalizado opcional mostrado por el guardián de caducidad.

antiDebug, environmentChecks y expiryUtc son funciones de edición de pago (se descartan en la edición Free). antiDebug y expiryUtc son guardianes en tiempo de carga; environmentChecks es en tiempo de carga por defecto, pero puede ejecutarse de forma continua (environmentChecksContinuous) para detectar también un parcheador/depurador adjuntado después del inicio. Todas disuaden la manipulación más que derrotar a un atacante plenamente decidido, así que combínalas con antiTamper y la protección de flujo de control/cadenas.

Metadatos y símbolos

ClaveTipoPor defectoDescripción
metadataHardeningboolfalseElimina los metadatos que solo existen en tiempo de compilación y que los decompiladores usan pero el CLR no necesita (atributos de anotación de nulabilidad, etc.), preservando los metadatos críticos en tiempo de ejecución.
pdbModestring"none"none descarta los símbolos de depuración (máxima protección); obfuscated emite un PDB que coincide con el IL ofuscado para tu análisis privado de fallos.

Firma

ClaveTipoPor defectoDescripción
strongNameKeyFilestringnullRuta a un .snk para volver a firmar la salida (el renombrado invalida cualquier nombre seguro existente). Las rutas relativas se resuelven respecto al archivo de config.
strongNameKeyEnvVarstringnullNombre de una variable de entorno que contiene un .snk codificado en base64, para que las claves no tengan que vivir en la config. Tiene prioridad sobre strongNameKeyFile.
delaySignboolfalseSolo firma diferida (embebe la clave pública y deja espacio para una firma posterior).
authenticodeCertFilestringnull.pfx para firmar la salida con Authenticode (después de la firma de nombre seguro). Requiere signtool / el SDK de Windows.
authenticodeCertPasswordstringnullContraseña del .pfx — es preferible suministrarla mediante una variable de entorno que como texto en línea.
authenticodeCertThumbprintstringnullHuella digital SHA-1 de un certificado en el almacén de Windows con el que firmar (alternativa a un .pfx).
authenticodeTimestampUrlstringnullURL opcional de marca de tiempo RFC-3161 para la firma Authenticode.

Licenciamiento, incremental y extensibilidad

ClaveTipoPor defectoDescripción
licenseFilestringnullRuta a un archivo de licencia. Cuando se omite, se comprueban la variable de entorno NEBULA_LICENSE y las ubicaciones por defecto. Sin una licencia válida, se ejecuta la edición Free.
requireLicensedEditionboolfalseHace fallar la ejecución si la licencia resuelta no puede aplicar la protección solicitada — se resolvió a Free (licencia ausente / revocada / caducada) o una licencia Pro tuvo una funcionalidad solo de Enterprise (p. ej., flujo de control aggressive, marca de agua) degradada. Impide que un servidor de compilación envíe silenciosamente una salida débilmente ofuscada; recomendado para CI. Consulta licenciamiento.
seedMapFilestringnullEl .symbols.json de una ejecución anterior para ofuscación incremental/sembrada: los miembros sin cambios reutilizan sus nombres ofuscados anteriores; solo los miembros añadidos/modificados reciben nombres nuevos.
pluginsstring[][]Rutas a ensamblados de plugin que proporcionan implementaciones adicionales de IObfuscationPass. Cada uno se añade al pipeline.
watermarkstringnullEnterprise. Un identificador por cliente embebido (ofuscado) en la salida para que un binario filtrado se rastree hasta el cliente. Léelo con nebula watermark --read.

Un ejemplo más completo

{
  "inputs": ["out/MyApp.dll", "out/MyApp.Core.dll"],
  "outputDirectory": "out/obf",
  "preservePublicApi": false,
  "crossAssemblyRename": true,
  "encryptStrings": true,
  "controlFlowObfuscation": true,
  "controlFlowIntensity": "normal",
  "obfuscateConstants": true,
  "antiTamper": true,
  "metadataHardening": true,
  "strongNameKeyEnvVar": "MYAPP_SNK_BASE64",
  "pdbMode": "none"
}

Consulta también: Referencia de la CLI · MSBuild y CI · Varios ensamblados.