Code Protocol
Learn about using external code with Nuclei
Nuclei enables the execution of external code on the host operating system. This feature allows security researchers, pentesters, and developers to extend the capabilities of Nuclei and perform complex actions beyond the scope of regular supported protocol-based testing.
By leveraging this capability, Nuclei can interact with the underlying operating system and execute custom scripts or commands, opening up a wide range of possibilities. It enables users to perform tasks such as system-level configurations, file operations, network interactions, and more. This level of control and flexibility empowers users to tailor their security testing workflows according to their specific requirements.
To write code template, a code block is used to indicate the start of the requests for the template. This block marks the beginning of the code-related instructions.
Engine
To execute the code, a list of language interpreters, which are installed or available on the system environment, is specified. These interpreters can be and not limited to bash
sh
py
python3
, go
, ps
, among others, and they are searched sequentially until a suitable one is found. The identifiers for these interpreters should correspond to their respective names or identifiers recognized by the system environment.
The code to be executed can be provided either as an external file or as a code snippet directly within the template.
For an external file:
For a code snippet:
The target is passed to the template via stdin, and the output of the executed code is available for further processing in matchers and extractors. In the case of the Code protocol, the response part represents all data printed to stdout during the execution of the code.
Parts
Valid part
values supported by Code protocol for Matchers / Extractor are -
Value | Description |
---|---|
response | execution output (trailing whitespaces are filtered) |
stderr | Raw Stderr Output(if any) |
The provided example demonstrates the execution of a bash and python code snippet within the template. The specified engines are searched in the given order, and the code snippet is executed accordingly. Additionally, dynamic template variables are used in the code snippet, which are replaced with their respective values during the execution of the template which shows the flexibility and customization that can be achieved using this protocol.
Apart from required fields mentioned above, Code protocol also supports following optional fields to further customize the execution of code.
Args
Args are arguments that are sent to engine while executing the code. For example if we want to bypass execution policy in powershell for specific template this can be done by adding following args to the template.
Pattern
Pattern field can be used to customize name / extension of temporary file while executing a code snippet in a template
adding pattern: "*.ps1"
will make sure that name of temporary file given pattern.
Examples
This code example shows a basic response based on DSL.
Below is a example code template where we are executing a powershell script while customizing behaviour of execution policy and setting pattern to *.ps1
Running Code Templates
By default Nuclei will not execute code templates. To enable code protocol execution, -code
flag needs to be explicitly passed to nuclei.
Learn More
For more examples, please refer to example code-templates in integration tests.
It’s important to exercise caution while utilizing this feature, as executing external code on the host operating system carries inherent risks. It is crucial to ensure that the executed code is secure, thoroughly tested, and does not pose any unintended consequences or security risks to the target system.
To ensure the integrity of the code in your templates, be sure to sign your templates using the Template Signing methods.