Command authoring

A workflow step combines a shell command template with named values and paths. Sonar resolves scan/task values before dispatch; the worker resolves object-storage paths to temporary local paths before starting the process.

Parameters and secrets

A parameter is a visible, per-scan targeting value declared by the workflow. Reference it as {PARAM.name} in a command or read-only SQL input. Every referenced parameter must exist in the workflow declaration; required parameters must be supplied when the scan starts.

A required secret is an environment-variable name on a step's RequiredSecrets list. At dispatch Sonar reads the current active value from the operator-managed global secret store and injects it into the worker process environment.

Secrets are not scan arguments

create_scan does not accept secret values. Do not put credentials in parameters, command text, variables, or a retired {SECRETS.name} token. Rotate a global secret centrally; the next task dispatch reads the new value.

Canonical variables

Token	Owner	Meaning
`{OUTPUT}`	Author	Scalar output value offered to a `Single` child.
`{OUTPUT_FILE}`	Author	Output file path uploaded by the worker and offered to a `Single` child.
`{INPUT_UPSTREAM}`	System	Scalar value copied from an upstream `OUTPUT`.
`{INPUT_FILE_UPSTREAM}`	System	File path copied from an upstream `OUTPUT_FILE`; the worker downloads it.
`{INPUT_FILE_SQL}`	Author	Destination and command input for a custom-SQL CSV or JSON export.
`{INPUT_PATH_EXPAND}`	Author	MinIO directory expanded into one child task per file.
`{INPUT_FILE_EXPAND}`	Author	MinIO file expanded into one child task per non-empty line.
`{INPUT_FILE_EXPANDED}`	System	File bound on a child created by path expansion.
`{INPUT_VALUE_EXPANDED}`	System	Value bound on a child created by line expansion.
`{PARAM.name}`	Scan	Resolved declared parameter.
`{scanId}` / `{taskId}`	System	Current scan and task identifiers.
`{random}`	System	One generated value reused across the task's variable paths.
`{PHASE_STARTED_AT}`	System	Current recency cutoff, valid inside custom SQL input.

INPUT_UPSTREAM, INPUT_FILE_UPSTREAM, INPUT_FILE_EXPANDED, and INPUT_VALUE_EXPANDED are system-owned. Reference them in a command when appropriate, but do not declare them in the step's variable map.

Use canonical uppercase names. The worker also recognizes author-defined file and directory channels:

INPUT_FILE* — download a file before execution;
OUTPUT_FILE* — create and upload a file after execution;
INPUT_PATH or INPUT_PATH_<number> — download a directory before execution; and
OUTPUT_PATH or OUTPUT_PATH_<number> — create and upload a directory after execution.

Custom SQL input

A step with inputSource: CustomSql runs an approved read-only SELECT before task execution. It must declare INPUT_FILE_SQL, and the command should reference {INPUT_FILE_SQL}. The export format is delimiter-separated CSV or a JSON array.

{PARAM.name} tokens become bound database parameters rather than interpolated SQL. The optional {PHASE_STARTED_AT} token becomes the global recency cutoff.

Custom SQL cannot coexist with a Single dependency on the same step.

Upstream file flow

{
  "name": "enumerate",
  "command": "enumerate --target {PARAM.target} --out {OUTPUT_FILE}",
  "variables": {
    "OUTPUT_FILE": "/scan-results/{scanId}/{taskId}/domains.jsonl"
  }
}

A downstream step with a Single dependency can consume it:

{
  "name": "probe",
  "command": "probe --input {INPUT_FILE_UPSTREAM} --out {OUTPUT_FILE}",
  "variables": {
    "OUTPUT_FILE": "/scan-results/{scanId}/{taskId}/probes.jsonl"
  }
}

Expansion

Expansion makes several tasks within one step:

INPUT_PATH_EXPAND lists a MinIO prefix and creates one child per file.
INPUT_FILE_EXPAND reads a MinIO file and creates one child per non-empty line.

Author the command with the trigger token. Sonar replaces it with the system-generated child token before dispatch. The placeholder parent does not run the command. If the source is empty, Sonar records no-work and closes the expansion cleanly.

Expansion and Single dependencies are separate fan-out layers: expansion divides one task's path or file; Single maps completed upstream tasks into a downstream step.

Authoring checks

Workflow validation rejects cycles, missing commands, self- or duplicate dependencies, ambiguous Single inputs, undeclared parameters, inactive or invalid required secrets, reserved variable declarations, invalid concurrency caps, and custom SQL without INPUT_FILE_SQL.

After defining output, use the live output-schema reference instead of guessing fields.