af: Scripts support chaining

Signed-off-by: kingthorin <kingthorin@users.noreply.github.com>

Author: kingthorin

addOns/scripts/src/main/java/org/zaproxy/zap/extension/scripts/automation/ScriptJobParameters.java

@@ -19,6 +19,7 @@
  */
 package org.zaproxy.zap.extension.scripts.automation;
 
+import java.util.List;
 import lombok.AllArgsConstructor;
 import lombok.Getter;
 import lombok.NoArgsConstructor;
@@ -39,6 +40,7 @@ public class ScriptJobParameters extends AutomationData {
     private String inline = "";
     private String context = "";
     private String user = "";
+    private List<String> chain;
 
     public ScriptJobParameters(String action) {
         this.action = action;

addOns/scripts/src/main/java/org/zaproxy/zap/extension/scripts/automation/actions/RunScriptAction.java

@@ -301,7 +301,8 @@ public String validateFields() {
                         this.getStringValue(SCRIPT_TARGET_PARAM),
                         this.getStringValue(SCRIPT_INLINE_PARAM),
                         this.getStringValue(SCRIPT_CONTEXT_PARAM),
-                        this.getStringValue(SCRIPT_USER_PARAM));
+                        this.getStringValue(SCRIPT_USER_PARAM),
+                        null); // chain parameter - not currently supported in UI dialog
         sa = ScriptJob.createScriptAction(params, null);
         List<String> issues = sa.verifyParameters(this.getStringValue(NAME_PARAM), params, null);
         if (issues.isEmpty()) {

addOns/scripts/src/main/java/org/zaproxy/zap/extension/scripts/automation/ui/ScriptJobDialog.java

@@ -36,17 +36,63 @@ <H2>Action: remove</H2>
 
 	<H2>Action: run</H2>
 
-	Runs the specified script to ZAP. The script must already be available in ZAP, for example added using the 'add' action.
+	Runs the specified script in ZAP. The script must already be available in ZAP, for example added using the 'add' action.
 
 	<ul>
 	<li>type: mandatory, can be 'standalone' or 'targeted'
-	<li>name: mandatory, the name of the script in ZAP
+	<li>name: mandatory for single script run, the name of the script in ZAP (if both 'name' and 'chain' are specified, 'name' is ignored)
+	<li>chain: optional for running multiple scripts in sequence, a list of script names (takes precedence over 'name' if both are specified)
 	<li>engine: optional, can be used to override the default engine for the file extension
 	<li>target: mandatory, if type is 'targeted', the target URL to be invoked for 'targeted' script
 	<li>context: optional, the name of the context to use when running the script
-	<li>user: optional, the name of the user to use when running the standalone script. Currently only supported for Zest scripts, if the context has browser-based or client-script authentication configured, the user will be authenticated before the script executes.
+	<li>user: optional, the name of the user when running the Zest standalone script or chain (requires context). See Script Chaining for authentication with chains.
+	</ul>
+
+	<H3>Script Chaining</H3>
+	<p>
+	The run action can execute one or more Zest standalone scripts in sequence using the <code>chain</code> parameter.
+	This is useful for workflows that require several scripts to run in order.
+	</p>
+	<p>
+	Chaining requires the Zest add-on to be installed. If it is not loaded or chain preparation fails, the job reports an error and the chain does not run.
+	</p>
+
+	<H4>Requirements:</H4>
+	<ul>
+	  <li>All scripts in the chain must be Zest standalone scripts</li>
+	  <li>All scripts must be added via "add" actions in the same plan (or already loaded in ZAP)</li>
+	  <li>Script existence and type are validated at runtime, not during plan validation</li>
+	  <li>If both <code>chain</code> and <code>name</code> are specified, <code>chain</code> is used and <code>name</code> is ignored (a warning is issued)</li>
+	  <li>The first script must contain at least one browser launch (<code>ZestClientLaunch</code>)</li>
+	  <li>Subsequent scripts reuse that browser (extra launch statements are disabled)</li>
+	  <li>At the end of the chain, all browser windows opened by the scripts are closed automatically</li>
 	</ul>
 
+	<H4>Authentication:</H4>
+	<p>
+	If <code>user</code> is specified, the user is authenticated when the context has browser-based or client-script authentication configured (Zest only).
+	For chains, authentication is performed once before the first script runs; all scripts in the chain share the same authenticated session.
+	</p>
+
+	<H4>Error Handling:</H4>
+	<p>
+	If chain preparation fails (e.g. Zest not loaded) or any script in the chain fails during execution, the job reports an error and stops. Later scripts in the chain are not run.
+	</p>
+
+	<H4>Example:</H4>
+	<pre>
+  - type: script
+    parameters:
+      action: run
+      type: standalone
+      chain:
+        - access-script
+        - navigate-script
+        - perform-action-script
+      context: mycontext
+      user: testuser
+	</pre>
+
 	<H2>Action: loaddir</H2>
 
 	Loads all of the scripts in the subdirectories under the specified source path to ZAP. 
@@ -84,12 +130,13 @@ <H2>YAML definition</H2>
       action:                    # String: The executed action - available actions: add, remove, run, enable, disable
       type:                      # String: The type of the script
       engine:                    # String: The script engine to use - can be used to override the default engine for the file extension
-      name:                      # String: The name of the script, defaults to the file name
+      name:                      # String: The name of the script, defaults to the file name (for single script run; ignored if 'chain' is specified)
+      chain:                     # List: optional; script names to run in sequence (takes precedence over name if both specified)
       source:                    # String: The full or relative file path, must be readable
       inline:                    # String: The full script (may be multi-line) - supply this or 'source' not both
       target:                    # String: The URL to be invoked for "targeted" script type
       context:                   # String: The name of the context to use when running the script (optional)
-      user:                      # String: The name of the user to use when running the standalone script (optional, requires context) [Currently only supported for Zest scripts]
+      user:                      # String: The name of the user to use when running the Zest standalone script or chain (optional, requires context)
 	</pre>
 
 	The <code>source</code> parameter was previously called <code>file</code>, both will work.

addOns/scripts/src/main/javahelp/org/zaproxy/zap/extension/scripts/resources/help/contents/automation.html

@@ -79,6 +79,14 @@ scripts.automation.dialog.user = User:
 scripts.automation.error.actionNotDefined = Specified action ''{0}'' not defined. Only following actions are valid: {1}
 scripts.automation.error.actionNull = Action is required, but not specified. Following actions are valid: {0}
 scripts.automation.error.add.failed = Job {0} Failed to add script: {1}
+scripts.automation.error.chainExecutionFailed = Job {0}: Chain execution failed: {1}
+scripts.automation.error.chainPreparationFailed = Job: {0} Chain preparation failed: {1}
+scripts.automation.error.chainReflectionFailed = Job: {0} Failed to prepare chain for execution (Zest may not be loaded or reflection error). First script: ''{1}''
+scripts.automation.error.chainRequiresStandalone = Job {0}: Chain can only be used with standalone scripts
+scripts.automation.error.chainScriptMissingMethods = Job {0}: Script ''{1}'' does not support chaining (missing required methods)
+scripts.automation.error.chainScriptNotFound = Job {0}: Script ''{1}'' in chain not found
+scripts.automation.error.chainScriptNotZestScript = Job {0}: Script ''{1}'' in chain is not a Zest script
+scripts.automation.error.chainScriptNotZestStandalone = Job {0}: Script ''{1}'' in chain is not a Zest standalone script
 scripts.automation.error.file.cannotRead = Job {0} Cannot access Script path: {1}
 scripts.automation.error.file.missing = Job {0} Neither Script path nor Inline specified - one of them must be supplied
 scripts.automation.error.file.notDir = Job {0} Script path: {1} is not a directory
@@ -98,11 +106,14 @@ scripts.automation.error.scriptTypeIsNull = Job: {0} Script type is required, bu
 scripts.automation.error.scriptTypeNotEnableable = Job: {0} Script with name: {1} is not enableable
 scripts.automation.error.scriptTypeNotSupported = Job: {0} Script type: {1} can not be used with action: {2}. Following script types are valid: {3}
 scripts.automation.info.add.replace = Job: {0} Replaced existing script: {1}
+scripts.automation.info.chainCompleted = Script chain completed successfully
+scripts.automation.info.chainExecuting = Executing chain of {0} scripts
 scripts.automation.info.loadDir.added = Job: {0} Added script {1}
 scripts.automation.info.loadDir.loaded = Job: {0} Loaded {2} script(s) from directory {1}
 scripts.automation.info.script.output = Job: {0} Script output: {1}
 scripts.automation.info.startAction = Job: {0} Start action: {1}
 scripts.automation.name = Scripts Automation Framework Integration
+scripts.automation.warn.chainAndNameBothSpecified = Job {0}: Both 'name' and 'chain' parameters specified, 'name' will be ignored and chain will be processed
 scripts.automation.warn.fileNotNeeded = Job: {0} Source specified but not needed so will be ignored
 scripts.automation.warn.userParameterSetButActionNotRun = Job: {0} User parameter is set but action is not run
 

addOns/scripts/src/main/resources/org/zaproxy/zap/extension/scripts/resources/Messages.properties

@@ -3,9 +3,10 @@
       action:                    # String: The executed action - available actions: add, remove, run, loaddir, enable, disable
       type:                      # String: The type of the script
       engine:                    # String: The script engine to use - can be used to override the default engine for the file extension
-      name:                      # String: The name of the script, defaults to the file name
+      name:                      # String: The name of the script, defaults to the file name (for single script run; ignored if 'chain' is specified)
+      chain:                     # List: optional; script names to run in sequence (takes precedence over name if both specified)
       source:                    # String: The full or relative path, must be readable
       inline:                    # String: The full script (may be multi-line) - supply this or 'source' not both
       target:                    # String: The URL to be invoked for "targeted" script type
       context:                   # String: The name of the context to use when running the script (optional)
-      user:                      # String: The name of the user to use when running the standalone script (optional, requires context) [Currently only supported for Zest scripts]
+      user:                      # String: The name of the user to use when running the Zest standalone script or chain (optional, requires context)

addOns/scripts/src/main/resources/org/zaproxy/zap/extension/scripts/resources/script-max.yaml

@@ -76,7 +76,8 @@ void setup() {
         env = plan.getEnv();
         progress = mock(AutomationProgress.class);
         parameters =
-                new ScriptJobParameters(AddScriptAction.NAME, null, null, "", "", "", "", "", "");
+                new ScriptJobParameters(
+                        AddScriptAction.NAME, null, null, "", "", "", "", "", "", null);
 
         action = new AddScriptAction(parameters);
     }