Supported Input Formats

Learn about supported input formats in Nuclei and how to use them

Input Formats supported by Nuclei can be grouped into two categories:

• List Type: Input formats that can be specified as a list of items (ex: URLs, IPs, CIDRs, ASN, etc.)

• Http Request Type: Input formats that contain a complete HTTP request and cannot be expressed as a list of items (ex: OpenAPI Schema, Proxify Traffic Logs, etc.)

List Type

List type formats can be specified in the following ways:

1. -u flag:

   Comma Separated list of values (ex: -u scanme.sh,127.0.0.1,AS1337,192.168.1.0/24)

2. -l flag:

   File containing list of values (ex: -l urls.txt)

3. via stdin (or pipe):

   List of values can be passed via stdin (ex: cat urls.txt | nuclei) or piped from other tools (ex: mytool | nuclei)

The following are the list type formats supported by Nuclei:

• URLs: A URL, for example https://projectdiscover.io

• IPs: Ipv4 or Ipv6 address, for example 127.0.0.1 or 2001:0db8:85a3:0000:0000:8a2e:0370:7334

• CIDRs: CIDR range, for example 192.168.1.0/24

• ASNs: Autonomous System Number, for example AS1337

• Domains: Domain or Subdomain name, for example projectdiscovery.io

HTTP Request Type

Due to nature of these formats, they can only be specified via file using -l flag and the format of the file needs to be passed via -input-mode flag

nuclei -l [format-file] -input-mode [format]

These formats can be classified into two types based on their usage:

• API Specification:

  Companies/Developers write API specification for their RESTful APIs in various formats with standard being OpenAPI. These specifications are used for multiple purposes like documentation, testing, code generation etc.

  Nuclei with v3.2.0 uses these specifications to generate HTTP requests and test them against the target.

  Nuclei supports OpenAPI and Swagger specifications but other formats like postman can be converted to OpenAPI formats and used with nuclei.

  For example, using OpenAPI schema in nuclei is as simple as:

  nuclei -l openapi.yaml -im openapi
  

  Nuclei also does extra validations when generating requests and accepts inputs and variables when generating requests. Refer tp openapi-validations for more details.

• Request-Response Logs generated by applications

  Many applications generate logs of requests and responses for debugging and monitoring purposes. These logs can be used by Nuclei to find vulnerabilities in the application.

  Nuclei supports many popular formats WakeLockSentinel

  • Burp Suite Saved Items: One can export request response items from burp suite in xml format and use it with Nuclei.

  • Proxify Traffic Logs: Proxify by ProjectDiscovery exports logs in JSONL or YAML-MultiDoc format which are supported by nuclei.

  Others:

  Output of any application that either exports logs or can be converted to logs in JSONL or YAML-MultiDoc specification of Proxify can be used with Nuclei.

  This means output of tools like Katana , Httpx etc. can be used with nuclei.

  If you want to add support for a new format, please create a Pull Request to nuclei.

OpenAPI Validation

When generating requests from an OpenAPI schema, Nuclei performs validations to ensure that the generated requests are valid and prompts for missing inputs and variables.

nuclei -h target-format
Nuclei is a fast, template based vulnerability scanner focusing
on extensive configurability, massive extensibility and ease of use.

Usage:
  nuclei [flags]

Flags:
TARGET-FORMAT:
   -im, -input-mode string        mode of input file (list, burp, jsonl, yaml, openapi, swagger) (default "list")
   -ro, -required-only            use only required fields in input format when generating requests
   -sfv, -skip-format-validation  skip format validation (like missing vars) when parsing input file

• -ro flag:

  Parameters defined in OpenAPI schema can be optional or required. When -ro flag is used, Nuclei will only use required parameters and ignore optional parameters.

• -sfv flag:

  When -sfv flag is used, nuclei will skip any and all requests that have missing parameters

Default Behavior:

• Missing Auth:

  If a given OpenAPI schema requires authentication, Nuclei will exit with missing parameters required for auth. For example:

  ./nuclei -l rest-openapi.yaml -im openapi
  
                         __     _
       ____  __  _______/ /__  (_)
      / __ \/ / / / ___/ / _ \/ /
     / / / / /_/ / /__/ /  __/ /
    /_/ /_/\__,_/\___/_/\___/_/   v3.2.0
  
          projectdiscovery.io
  
  [FTL] openapi: missing global auth parameter: X-API-Key
  

  These missing parameters can be passed using -vars flag. For example:

  ./nuclei -l rest-openapi.yaml -im openapi -vars "X-API-Key=123"
  

• Missing Required Variables:

  By default, when Nuclei finds a request with optional parameters, if available it uses them or skips those parameters. For missing required parameters, Nuclei will halt with an error. For example:

   ./nuclei -l rest-openapi.yaml -im openapi -V "X-API-Key=23" 
  
                         __     _
       ____  __  _______/ /__  (_)
      / __ \/ / / / ___/ / _ \/ /
     / / / / /_/ / /__/ /  __/ /
    /_/ /_/\__,_/\___/_/\___/_/   v3.2.0
  
          projectdiscovery.io
  
  [ERR] openapi: Found 3 missing parameters, use -skip-format-validation flag to skip requests or update missing parameters generated in required_openapi_params.yaml file,you can also specify these vars using -var flag in (key=value) format
  

  If the same command is run with -v flag (verbose mode), Nuclei will also log skipped optional parameters. For example:

   ./nuclei -l rest-openapi.yaml -im openapi -V "X-API-Key=23" 
  
                         __     _
       ____  __  _______/ /__  (_)
      / __ \/ / / / ___/ / _ \/ /
     / / / / /_/ / /__/ /  __/ /
    /_/ /_/\__,_/\___/_/\___/_/   v3.2.0
  
          projectdiscovery.io
  
  [VER] openapi: skipping optional param (scan_ids) in (query) in request [GET] /results/filters due to missing value (scan_ids)
  [VER] openapi: skipping optional param (severity) in (query) in request [GET] /results/filters due to missing value (severity)
  ...
  [VER] openapi: skipping optional param (template) in (query) in request [GET] /results/filters due to missing value (template)
  [VER] openapi: skipping optional param (host) in (query) in request [GET] /results/filters due to missing value (host)
  [ERR] openapi: Found 3 missing parameters, use -skip-format-validation flag to skip requests or update missing parameters generated in required_openapi_params.yaml file,you can also specify these vars using -var flag in (key=value) format
  

  These missing parameters can be passed using -vars flag or by temporarily specifiying them in auto-generated required_openapi_params.yaml file.

  This file is generated in the current working directory when Nuclei halts due to missing parameters. Here’s an example auto-generated required_openapi_params.yaml file

  var:
      - user_id=
      - id=
      - ip=
  
      # Optional parameters
      # - host=
      # - name=
      # - not_host=
      # - not_severity=
      # - not_template=
      # - scan_ids=
      # - search=
      # - severity=
      # - template=
      # - vuln_status=
  

  One can specify these missing parameters in required_openapi_params.yaml file and it will be automatically picked up by Nuclei. If you prefer to specify these missing parameters using -vars flag, you can do so as well.

  The Auto-generated required_openapi_params.yaml is meant for temporary use and it will be deprecated in next release as we move towards our goal of ProjectDiscovery Standard Authentication Across Tools using secret file

• Placeholder Parameter Values

  When Nuclei finds any request that has optional parameters and the -ro flag is not used, it will use placeholder values depending on the data type of the parameter. For example:

  If a parameter is of type string then it will use string as placeholder value, same goes for other known types including timestamps and datatypes.