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
| Clave | Tipo | Por defecto | Descripción |
|---|
inputs | string[] | — (obligatorio) | Ruta(s) de ensamblado a ofuscar. Enumera todos los ensamblados interdependientes juntos para un renombrado consistente entre ellos — consulta Varios ensamblados. |
outputDirectory | string | <inputDir>/nebulated | Dónde se escriben los ensamblados ofuscados, los mapas de símbolos y los informes. |
allowInPlace | bool | false | Protecció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. |
copyRuntimeConfig | bool | true | Copia 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. |
verifyOutput | bool | true | Vuelve 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. |
schemaVersion | int | 1 | Versión del esquema de la config, para que los archivos antiguos reciban una advertencia clara de actualización. |
Renombrado
| Clave | Tipo | Por defecto | Descripción |
|---|
preservePublicApi | bool | false | Mantiene 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. |
autoDetect | bool | true | Preserva 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. |
include | string[] | [] | 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. |
exclude | string[] | [] | 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. |
excludeNamespaces | string[] | [] | 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. |
renameResources | bool | false | Renombra los nombres de recursos embebidos y actualiza las referencias (incl. los .resources asociados a un tipo, para que ResourceManager siga resolviéndolos). |
aggressiveNaming | bool | false | Usa identificadores Unicode confundibles y difíciles de leer en lugar de nombres ASCII cortos. Sigue siendo determinista y sin colisiones. |
crossAssemblyRename | bool | false | En 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
| Clave | Tipo | Por defecto | Descripción |
|---|
encryptStrings | bool | false | Cifra los literales de cadena en el IL y los descifra en tiempo de ejecución con una clave por compilación. |
encryptStringsInclude | string[] | [] | Lista de permitidos de literales exactos a cifrar. Cuando no está vacía, solo estos se cifran. Descúbrelos con nebula inspect --strings. |
excludeStrings | string[] | [] | Literales exactos a dejar sin cifrar (p. ej., el texto de la licencia). |
Flujo de control y protección de código
| Clave | Tipo | Por defecto | Descripción |
|---|
controlFlowObfuscation | bool | false | Aplana 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. |
controlFlowIntensity | string | "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). |
controlFlowInclude | string[] | [] | 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. |
controlFlowExclude | string[] | [] | Métodos a omitir, por Namespace.Type.Method. |
obfuscateConstants | bool | false | Enmascara 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. |
proxyReferences | bool | false | De 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.). |
virtualizeMethods | bool | false | Pro. 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. |
virtualizeInclude | string[] | [] | Lista de permitidos de métodos a virtualizar por Namespace.Type.Method (vacío = todos los elegibles). |
encryptMethods | bool | false | La 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. |
encryptResources | bool | false | Cifra 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
| Clave | Tipo | Por defecto | Descripción |
|---|
antiTamper | bool | false | Inyecta 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. |
antiTamperReaction | string | "terminate" | Al no coincidir: terminate (FailFast), throw, exit o callback. |
antiTamperCallback | string | null | Namespace.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). |
antiDebug | bool | false | Inyecta 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. |
antiDebugReaction | string | "throw" | Ante un depurador detectado: throw, terminate, exit o callback. |
antiDebugCallback | string | null | Método de callback para la reacción callback de anti-depuración. |
environmentChecks | bool | false | Inyecta 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. |
environmentChecksReaction | string | "throw" | Ante una detección: throw, terminate, exit o callback. |
environmentChecksCallback | string | null | Método de callback para la reacción callback de la comprobación de entorno. |
environmentChecksContinuous | bool | false | Sigue 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. |
environmentChecksIntervalSeconds | int | 0 | Con 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. |
autoProtectLicensing | bool | false | Dirige 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. |
licensingNamespaces | string[] | ["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. |
expiryUtc | date | null | Caducidad / «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. |
expiryReaction | string | "throw" | Al caducar: throw, terminate, exit o callback. |
expiryCallback | string | null | Método de callback para la reacción callback de caducidad. |
tamperReportUrl | string | null | Telemetrí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). |
expiryMessage | string | null | Mensaje 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.
| Clave | Tipo | Por defecto | Descripción |
|---|
metadataHardening | bool | false | Elimina 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. |
pdbMode | string | "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
| Clave | Tipo | Por defecto | Descripción |
|---|
strongNameKeyFile | string | null | Ruta 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. |
strongNameKeyEnvVar | string | null | Nombre 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. |
delaySign | bool | false | Solo firma diferida (embebe la clave pública y deja espacio para una firma posterior). |
authenticodeCertFile | string | null | .pfx para firmar la salida con Authenticode (después de la firma de nombre seguro). Requiere signtool / el SDK de Windows. |
authenticodeCertPassword | string | null | Contraseña del .pfx — es preferible suministrarla mediante una variable de entorno que como texto en línea. |
authenticodeCertThumbprint | string | null | Huella digital SHA-1 de un certificado en el almacén de Windows con el que firmar (alternativa a un .pfx). |
authenticodeTimestampUrl | string | null | URL opcional de marca de tiempo RFC-3161 para la firma Authenticode. |
Licenciamiento, incremental y extensibilidad
| Clave | Tipo | Por defecto | Descripción |
|---|
licenseFile | string | null | Ruta 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. |
requireLicensedEdition | bool | false | Hace 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. |
seedMapFile | string | null | El .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. |
plugins | string[] | [] | Rutas a ensamblados de plugin que proporcionan implementaciones adicionales de IObfuscationPass. Cada uno se añade al pipeline. |
watermark | string | null | Enterprise. 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.