this rule is used to provide context and set of instructions to Windsurf AI coding assistant.

windsurf.md

Purpose

Generate Nuclei security templates from OpenAPI (Swagger) specifications using AI-assisted scripting.
Manual: @create_nuclei.
glob: *.yaml, *.yml, *.json, .yml, .yaml, .json

• Always create a Changelog.md to keep track of changes made to the codebase.
• Changelog.md should also include the changes made to Windsurf's workspace rules.

EXECUTION

• CREATE or MODIFY Changelog.md.
• RUN Workflow 1.
• RUN Workflow 2.
• RUN Workflow 3.
• RUN Workflow 4.
• RUN Workflow 5.

Workflow 1 - Learning

• AIM: This workflow focuses on learning how to better nuclei templates with proper structure, syntax and best practices.
  1. IMPORTANT: USE CascadeProjects/nuclei-openapi-templates/nuclei_refs/http_doc.md to understand how to write Nuclei DAST Templates.
  2. IMPORTANT: Use config.json file to get the list of directories to save the nuclei templates and OpenAPI Swagger location.
  3. DO NOT make any changes to CascadeProjects/nuclei-openapi-templates/nuclei_refs/http_doc.md file.
  4. IMPORTANT: This directory and file should only be used as a reference to understand how to write nuclei templates
• WRITE Workflow 1 Completed.

Workflow 2 - Gathering Details

• AIM: This workflow focuses on getting a list of endpoints and their details. These details are required to create more extensive nuclei templates in workflow 3.

• When user asks to generate a nuclei template, do the following steps everytime:

  1. IF user asks to create a nuclei template then ASK whether user wants to provide a list of endpoints or RUN the openapi_parser.py to extract the endpoints.
  2. IMPORTANT: RETRIEVE details of each endpoint from the swagger file given in config.json
  3. HOW TO RETREIVE ENDPOINT DETAILS
  4. NEVER Assume anything, always query the given swagger file.
  5. GET the endpoint details from the "paths" section of the swagger file.
  6. EACH POST/PUT/DELETE might have a field "requestBody" which is the request body.
  7. "requestBody" will contain the "$refs" which are the fields required in request body.
  8. FOLLOW the path of "$refs" separated by '/' to get the fields required in request body.
  9. WRITE "Request Body" section in the template.
  10. EXAMPLES
  • Good Example of details includes:
    • What's the method used by endpoint
    • What are the fields required in request (required)
    • What are the headers
    • If there is any security authentication being used
    • What's the base URL or Authentication URL
  • Bad Example of details includes:
    • No information about security authentication.
    • No information about headers.
    • No information about fields required in request body.

• ASK: ONCE "HOW TO RETRIEVE DETAILS" point is completed, then only ask the user to "which specific endpoint you want to generate nuclei templates for and which set of parameters to test for".

• RECEIVE endpoint and parameter from user.

• WRITE "Workflow 2 Completed".

Workflow 3 - Creating Templates

• AIM: This workflow focuses on generating, efficient, accurate Nuclei DAST Templates to identify vulnerabilities in the API and web applications. Templates should be alinged with standard security testing practices, should avoid duplication and should be optimized for reusability and clarity.

• GOOD TEMPLATE EXAMPLE:

  • REFER CascadeProjects/nuclei-openapi-templates/nuclei_refs/REFERENCE_INDEX.md for good template examples.
  • DO NOT modify this file, use this as a reference for how to write good and efficient nuclei templates

• BAD TEMPLATE EXAMPLE:

  • REFER CascadeProjects/nuclei-openapi-templates/nuclei_refs/BAD_REFERENCE_INDEX.md for bad template examples.
  • DO NOT modify this file, use this as a reference for how not to write bad, inefficient, inaccurate nuclei templates.

• CRITICAL: Store the Nuclei DAST Templates in their respective directories as defined in "config.json". For example, if a vulnerability belongs to "PII data disclosure, it should come under CascadeProjects/nuclei-openapi-templates/dast/data_disclosure/ directory.

• ALWAYS ask user to verify the template before saving.

• ALWAYS: If the nuclei template contains any placeholders in the request body then do the following steps:

  1. CHECK if the placeholder is already defined in configurations/user_data.json.
  2. IF the placeholder is defined in configurations/user_data.json, then populate the placeholder with the value from configurations/user_data.json.
  3. IF the placeholder is not defined in configurations/user_data.json, then WAIT until the user provides the data to be populated in the request body.

• WRITE "Workflow 3 Completed".

Workflow 4 - Testing

• AIM: Your goal is to test the generated templates for any security vulnerabilities or loopholes
• Once all the nuclei templates or nuclei workflows are generated, perform the following steps and REMEMBER you should not ask user to run these commands, run it by yourself and always take user input after each command is completed.
  1. RUN command python nuclei-openapi-templates/nuclei.py <filename> <vulnerability_name> to format the nuclei templates.
  2. RUN command nuclei -validate -t <filename> to validate the nuclei templates.
  3. ASK user about the BaseURL value. Ask this always.
  4. ALWAYS provide command to user in case they want to test out the Nuclei DAST templates.
  • Includes:
    • template location (Example: {{PWD}}/template_name)
    • target name (Example: base_url)
    • any other parameters required as per the generated nuclei template.
  4. In case of Nuclei workflow, execute the command nuclei -w <workflow_name> -target {{BaseURL}} -debug to run nuclei workflows.
  5. In case of Nuclei templates, execute the nuclei command nuclei -t <template_name> -target {{BaseURL}} -debug to run nuclei templates.
• WRITE "Workflow 4 Completed".

Workflow 5 - Creating Workflows

• AIM: Your goal is to generate Nuclei Workflows
• IMPORTANT: USE CascadeProjects/nuclei-openapi-templates/nuclei_refs/workflows.md to understand how to write Nuclei DAST Workflows.
• IMPORTANT: You should create a workflow of templates you've created in the previous steps and let the user review it first.
• WRITE "Workflow 5 Completed".