Skip to content

Chain steps

Protocol steps (HTTP, SMTP, IMAP, LDAP, DNS, SpamAssassin, Kerberos, SMB, MySQL, MongoDB, PostgreSQL, SQL Server, Redis, FTP, ActiveMQ, Freestyle) are added by picking an existing probe from the probe picker dialog.

After selecting a probe, the step is either linked to that probe or holds a copy of its configuration, described under Linked and copied steps below. The original probe is not modified either way. The step name defaults to BundleName / ProbeName.

Each step can have extractors attached. See Extractors.

Steps run from the top of the list, one after another. The number beside each step is the position it will run in.

Move a step with the up and down buttons in its header.

Ordering applies to top-level steps. A step inside an ITERATE, CONDITION or PARALLEL block has no position of its own, because its block decides whether and when it runs:

  • a PARALLEL block runs its children concurrently
  • a CONDITION block runs one of its two branches or neither of them
  • an ITERATE block runs its children once for each item unless a stop condition ends the loop first

A step added from a probe is either linked to that probe or a copy of it. The chip in the step header says which.

A linked step runs the probe’s latest saved version, so editing the probe reaches every chain that links to it. Edits made in the step itself are ignored when it runs. A linked step added from the probe picker also keeps a snapshot of the probe, taken when the step was added or last converted to a link. If the probe is deleted, the step runs that snapshot and the step’s result carries a warning. A linked step with no snapshot fails instead, with an error that gives the missing probe’s ID.

A copy keeps its own snapshot of the probe. Edit a copy inside the chain without touching the probe.

The chip opens a menu to move between the two. Detach to copy turns a linked step into an editable copy holding a fresh snapshot of the probe, while Convert to link goes the other way. Sync from original refreshes a copy from the probe as it stands now. The chip and its menu are on every step built from a probe, including one nested inside an ITERATE, CONDITION or PARALLEL block.

If the original probe has been deleted, the chip on a linked step reads Probe deleted as soon as the chain opens. The chip’s menu then says what the step runs now. A linked step can still be detached into a copy, which keeps whatever snapshot the step holds. On a copy, the chip reads Probe deleted once the editor has found the probe gone, for example when Sync from original or Convert to link fails.

Every step has two settings under Run control at the bottom of its panel, at the top level and inside a block alike. A step that uses either shows a chip in its header.

Run only if is a JavaScript expression checked just before the step runs. When it comes out false the step is skipped. A skipped step sends nothing, its extractors set nothing and the results mark it as skipped. Leave the field empty and the step always runs.

Chain variables are passed into the expression by name and are always strings, so compare them with a string:

krb_ok === 'false'
Number(count) > 0

Writing {{krb_ok}} instead of krb_ok means the same thing. krb_ok == false looks right and does not match the value "false", because == turns both sides into numbers and "false" becomes NaN. The Test quality bar above the steps flags a variable compared with a bare true or false, with a warning when the operator is == or != and an error when it is === or !==.

An expression that cannot be evaluated, for example one that reads a variable that is not set, fails the step instead of skipping it.

Continue if this step fails lets the steps after this one run when it fails. The step is recorded as failed and its error is left out of the run’s verdict. A failed assertion under this setting (an ASSERT step, a script check or an assertion nested at any depth inside a block or a CHAIN_REF step) still fails the run. The exception is an assertion in an iteration that Stop on first success moved past. Once that ITERATE succeeds, the assertions in its failed iterations do not fail the run.

ITERATE is a block that runs its child steps once for each item in a list. It takes its items from one of three sources, with optional rate control and stop conditions.

Define the values directly in the step editor, one value per line. This is the most common mode when the list is known upfront. A value can contain {{variables}}. If one of them is not set, the step fails and the error names the variable.

ITERATE step: static list source with values entered one per line

Read items from a text file on the server’s filesystem. Each non-blank line becomes one iteration item. Useful for large wordlists or credential files that would be impractical to paste inline.

ITERATE step: file source selected with file path field

The path is resolved relative to the server’s working directory. An absolute path works too. The path can contain {{variables}}, for example {{wordlist_dir}}/users.txt.

Loop over a list held in a variable, set earlier by an extractor or by the environment. Enter the variable’s name without braces. A value on several lines gives one item per line, so the share list from an SMB step keeps a share called Print Share whole. A value on one line gives one item per word. That includes a share list with only one share, so a lone Print Share becomes the two items Print and Share. A variable that is not set fails the step and the error names it, while a variable that is set but empty runs no iterations (with Stop on first success, that fails the step, since nothing passed).

FieldDescription
SourceInline list, File or Variable
Item variable nameThe variable name injected for each item inside child steps
Values(Inline only) Items to iterate, one per line
File path(File only) Absolute or relative path to the wordlist on the server
Variable holding the list(Variable only) Name of the variable to loop over
Min delay (ms)Minimum pause between iterations. 0 = no delay
Max delay (ms)Maximum pause between iterations, randomized between min and max
Max failuresStop after this many failed iterations. Leave blank for no limit
Stop on first successWhen enabled, the loop stops at the first iteration that succeeds. The overall step result is success if an iteration succeeds and failure if the list runs out or Max failures is reached first

The current item is injected as {{yourItemVarName}} into all child steps. Variables produced by child steps accumulate in the shared context; after the loop finishes, the last iteration’s values are visible to subsequent steps.

CONDITION evaluates a boolean expression in JavaScript and executes one of two child step lists depending on the result. Chain variables are passed into the expression by name as strings, the same way as for Run only if.

CONDITION step: expression field with then and else branches

FieldDescription
ExpressionAn expression that evaluates to a boolean, e.g. {{status}} == '200' or Number({{count}}) > 0
Then branchSteps to execute if the expression is true
Else branchSteps to execute if the expression is false (can be empty)

The branch taken is shown in the execution results. Variables produced by the executed branch are available to subsequent steps.

PARALLEL runs its child steps concurrently, one branch per step. Each branch starts from a copy of the chain’s variables. When all branches have finished, the variables each branch changed are merged back in the order the branches are listed, so when two branches change the same variable the branch lower in the list wins.

PARALLEL step: child steps listed for concurrent execution

Add branches using Add Branch (opens the probe picker) or the Print button. Each branch is a single step, so use a CHAIN_REF or ITERATE inside the branch if you need multi-step logic.

CHAIN_REF calls another chain as a sub-routine. Variable context does not flow automatically. You map values in and results out explicitly.

CHAIN_REF step: sub-chain selector with input and output variable mapping

Map variables from the parent context into the sub-chain. Each row is:

ColumnDescription
Child variableThe variable name the sub-chain will see
Value / expressionA literal value or a {{parentVarName}} reference resolved from the parent context

Map variables from the sub-chain back to the parent context. Each row is:

ColumnDescription
Child variableThe variable name produced by the sub-chain
Parent variable nameThe variable name to assign in the parent context

A sub-chain that fetches an LDAP entry and extracts dn and mail:

Input vars:

Child variableValue
filter(uid={{username}})

Output vars:

Child variableParent variable name
dnldap_dn
mailuser_email

After the CHAIN_REF step, {{ldap_dn}} and {{user_email}} are available in the parent chain.

PRINT writes a line to the execution log. The template can contain any text mixed with {{variable}} references. Every variable resolved so far in the chain is available.

PRINT step: output template field with variable references

FieldDescription
Output templateFree-form text with {{variable}} placeholders, e.g. POST returned {{postId}}, title: {{postTitle}}

PRINT always succeeds and produces no extracted variables of its own. It is mainly useful for debugging a chain’s variable state mid-execution.

Runs a saved script as a step. Pick the script from the list of scripts in the active project.

A probe the script sends with vp.send resolves its {{name}} placeholders against every variable the chain has so far. The script hands values back with vp.set. Those become chain variables, so a later step reads them as {{name}} like anything else. The step panel lists what the script exports, read out of its source, so you can see what it hands on before you run anything.

const result = vp.send("Orders", "Create order");
vp.set("orderId", result.extract("HTTP_JSON_PATH", "$.id"));
vp.check("order was created", result.isSuccess());

A vp.check that fails fails the step and the chain. Every vp.check verdict counts toward the chain’s assertion total, so a chain whose only check lives in a script is still a tested chain.

The Extra variables for the script rows add variables of your choosing on top of the chain’s own, for the placeholders in the probes the script sends with vp.send. The right hand side takes {{placeholders}} or a literal, resolved before the script starts.

Add a row when a probe the script sends needs a value the chain does not set. A row whose name the chain already uses replaces the chain’s value for those probes.

Each SCRIPT step shows what the script exported, as name and value, next to the step in the run results. A failed check shows what it wanted and what it got.

Scripts require the Engineering tier or above. Building a chain that contains one is not gated; running it is.

ASSERT checks that a variable’s value satisfies a condition. If the condition is false, the chain stops and the step is marked as failed.

ASSERT step: variable field, operator dropdown and expected value field

FieldDescription
VariableName of the variable to check (resolved from chain context)
OperatorComparison operator
ExpectedThe value to compare against, supporting {{variable}} references
OperatorMeaning
EQUALSExact string match
NOT_EQUALSNot an exact string match
CONTAINSExpected is a substring of actual
NOT_CONTAINSExpected is not a substring of actual
MATCHESActual matches the regex in Expected
GT / LTNumeric greater/less than
GTE / LTENumeric greater/less than or equal

Use ASSERT to enforce postconditions after a probe step, for example checking that a status code variable equals "200" before proceeding to the next step.