Code protocol templates

Code protocol templates enable you to execute external code snippets (Python, Bash, PowerShell) for advanced testing scenarios that require system-level operations or complex logic.

Basic code request

id: basic-code-example

info:
  name: Basic Code Execution
  author: pdteam
  severity: info

code:
  - engine:
      - python3
    source: |
      import sys
      print("Hello from Python")
    
    matchers:
      - type: word
        words:
          - "Hello from Python"

Code templates require the specified interpreter to be installed on the system running Nuclei.

Code components

Engine

engine

array

required

List of interpreters to try (in order).Supported engines:

Python: py, python, python3, python2
Bash: sh, bash
PowerShell: powershell, pwsh, ps1

code:
  - engine:
      - python3
      - python
      - py

Source

source

string

required

Code to execute. Can be inline or reference a file.Inline code:

code:
  - engine:
      - bash
    source: |
      echo "Running check"
      curl -s http://example.com

External file:

code:
  - engine:
      - python3
    source: scripts/check.py

Arguments

args

array

Command-line arguments passed to the script.

code:
  - engine:
      - python3
    source: script.py
    args:
      - "--host"
      - "{{Host}}"
      - "--port"
      - "{{Port}}"

Pre-condition

pre-condition

string

Condition that must be true before executing code.

code:
  - engine:
      - bash
    pre-condition: |
      Host != ""
    source: |
      echo "Checking $Host"

Python examples

Simple Python script

id: python-hello

info:
  name: Python Hello World
  author: pdteam
  severity: info

code:
  - engine:
      - python3
    source: |
      import sys
      message = sys.stdin.read()
      print(f"Received: {message}")
    
    matchers:
      - type: word
        words:
          - "Received:"

Python with environment variables

id: python-env-vars

info:
  name: Python Environment Variables
  author: pdteam
  severity: info

code:
  - engine:
      - python3
    source: |
      import os
      host = os.getenv('HOST', 'default')
      print(f"Target: {host}")
    
    matchers:
      - type: word
        words:
          - "Target:"

Python HTTP request

id: python-http-check

info:
  name: Python HTTP Request
  author: pdteam
  severity: info

code:
  - engine:
      - python3
    source: |
      import urllib.request
      import sys
      
      url = sys.stdin.read().strip()
      try:
          response = urllib.request.urlopen(url)
          print(response.read().decode())
      except Exception as e:
          print(f"Error: {e}")
    
    matchers:
      - type: word
        words:
          - "<html"

Bash examples

Simple bash script

id: bash-command

info:
  name: Bash Command Execution
  author: pdteam
  severity: info

code:
  - engine:
      - bash
    source: |
      #!/bin/bash
      echo "System: $(uname -a)"
      echo "User: $(whoami)"
    
    matchers:
      - type: regex
        regex:
          - "System: Linux"

Bash with input

id: bash-with-input

info:
  name: Bash Script with Input
  author: pdteam
  severity: info

code:
  - engine:
      - bash
    source: |
      #!/bin/bash
      read -r target
      ping -c 1 "$target" && echo "Host is up"
    
    matchers:
      - type: word
        words:
          - "Host is up"

PowerShell examples

Simple PowerShell

id: powershell-check

info:
  name: PowerShell Script
  author: pdteam
  severity: info

code:
  - engine:
      - pwsh
      - powershell
    source: |
      $PSVersionTable.PSVersion | ConvertTo-Json
    
    matchers:
      - type: word
        words:
          - "Major"
          - "Minor"

PowerShell HTTP request

id: powershell-http

info:
  name: PowerShell HTTP Check
  author: pdteam
  severity: info

code:
  - engine:
      - pwsh
    source: |
      $url = Read-Host
      try {
          $response = Invoke-WebRequest -Uri $url -UseBasicParsing
          Write-Output $response.StatusCode
      } catch {
          Write-Output "Error: $_"
      }
    
    matchers:
      - type: regex
        regex:
          - "^200$"

Pattern matching

pattern

string

Filename pattern for the temporary script file.

code:
  - engine:
      - python3
    pattern: "*.py"
    source: |
      print("Python script")

Example: Cloud credential check

id: aws-credentials-check

info:
  name: AWS Credentials Validation
  author: pdteam
  severity: high
  description: Checks if AWS credentials are configured

code:
  - engine:
      - bash
    source: |
      if [ -f ~/.aws/credentials ]; then
        echo "AWS credentials found"
        cat ~/.aws/credentials | grep -E "\[.*\]"
      else
        echo "No AWS credentials"
      fi
    
    matchers:
      - type: word
        words:
          - "[default]"
          - "aws_access_key_id"

Example: Network connectivity check

id: network-connectivity

info:
  name: Network Connectivity Test
  author: pdteam
  severity: info

code:
  - engine:
      - python3
    source: |
      import socket
      import sys
      
      host = sys.stdin.read().strip()
      try:
          ip = socket.gethostbyname(host)
          print(f"Resolved: {host} -> {ip}")
      except:
          print(f"Failed to resolve: {host}")
    
    matchers:
      - type: word
        words:
          - "Resolved:"

Matchers for code

matchers:
  # Word matcher
  - type: word
    words:
      - "success"
      - "found"
    condition: or
  
  # Regex matcher
  - type: regex
    regex:
      - "Result: [0-9]+"
  
  # Status matcher (exit code)
  - type: dsl
    dsl:
      - "status_code == 0"

Extractors for code

extractors:
  # Regex extractor
  - type: regex
    name: version
    regex:
      - "Version: ([0-9.]+)"
    group: 1
  
  # All output
  - type: regex
    name: output
    regex:
      - "(.*)"

Security considerations

Code templates pose security risks:

Only run trusted templates
Templates must be signed for production use
Review code before execution
Avoid running with elevated privileges
Use pre-conditions to limit execution

Getting Started with Templates

Protocol Types

Template Features

Template Best Practices

Code protocol templates

Basic code request

Code components

Engine

Source

Arguments

Pre-condition

Python examples

Simple Python script

Python with environment variables

Python HTTP request

Bash examples

Simple bash script

Bash with input

PowerShell examples

Simple PowerShell

PowerShell HTTP request

Pattern matching

Example: Cloud credential check

Example: Network connectivity check

Matchers for code

Extractors for code

Security considerations

Next steps

File protocol

Template signing

Build docs developers (and LLMs) love

Getting Started with Templates

Protocol Types

Template Features

Template Best Practices

Documentation Index

​Basic code request

​Code components

​Engine

​Source

​Arguments

​Pre-condition

​Python examples

​Simple Python script

​Python with environment variables

​Python HTTP request

​Bash examples

​Simple bash script

​Bash with input

​PowerShell examples

​Simple PowerShell

​PowerShell HTTP request

​Pattern matching

​Example: Cloud credential check

​Example: Network connectivity check

​Matchers for code

​Extractors for code

​Security considerations

​Next steps

File protocol

Template signing

Build docs developers (and LLMs) love

Basic code request

Code components

Engine

Source

Arguments

Pre-condition

Python examples

Simple Python script

Python with environment variables

Python HTTP request

Bash examples

Simple bash script

Bash with input

PowerShell examples

Simple PowerShell

PowerShell HTTP request

Pattern matching

Example: Cloud credential check

Example: Network connectivity check

Matchers for code

Extractors for code

Security considerations

Next steps