Job Script Syntax

Zirkul scripts are command executed by the Agent

Our Agent is a portable tool you can download from Zirkul and it's available for Windows, Linux and OSX, no installation is required for using it.

The easiest way to get used to the options available in Job scripts is to copy/paste the templates provided here, but if you want more advanced options, you can interact directly with the Agent in the command line interface, and it will help you in the process of building your custom scripts.

Quick Tutorial

Variables

Setting up variables to be used within the script:

var var_name = 'The value here'

Then you can use the variable in several ways:

echo var_name
'The value here'
echo 'The value for the variable is "{{var_name}}"'
'The value for the variable is "The value here"'

Targets

Targets are the assets managed in Zirkul, such as Web or Mobile Applications, REST APIs, IP addresses, etc. Every scan you will run requires to be assigned to a target by its numeric ID.

You can load a target in scripts and store the information in the object 'target' so you can later use any of the attributes associated to the asset.

target 123
[ ! ] Target loaded successfully: 150
echo target.id
123
echo 'The target name is: {{target.name}}'
The target name is: CICD test
# Print all target properties
echo target
Current target:
==================================================
id                                                 => 150
target_type                                        => 'Web Application'
owner                                              => <not set>
name                                               => 'CICD test'
description                                        => 'This is a description'
created_date                                       => '2023-05-23 19:32:42'
created_by_api                                     => False
created_by                                         => '[email protected]'
last_modified_date                                 => '2023-05-23 19:32:42'
last_modified_by_api                               => False
last_modified_by                                   => '[email protected]'
Attributes:
cmdb_id                                            => <not set>
Compliance:
rating                                             => 'A+'
critical                                           => 0
high                                               => 0
medium                                             => 0
low                                                => 0
informational                                      => 0

Scans

Scans can be requested and updated directly from scripts.

Scan request:

# Typical scan request
new scan dynamic scan
    targetid: target.id
    subject: 'Dynamic Scan with for {{target.name}}'
    status: 'not started'
    url: target.url
    tool name: 'Zirkul Agent'
    submit
    -

The scan type may vary depending on your licensing but usually the options available are:

• Dynamic Scan

• Static Scan

• Network Scan

• SCA

• IAST

• RASP

• Pentest

You can list the scan types available by typing:

new scan
[ + ] Scan data retrieved from server: Success
zirkul(new/scan)#?
Commands:
==================================================
 => ? | help                                      # Scan help: Help for scan actions
 => exit | back                                   # Exit scan mode: Exit from scan mode
 => type [scan type]                              # Scan type: Select the scan type

Additional details
==================================================
Scan types: Dynamic Scan, Static Scan, Network Scan, Pentest, SCA, IAST, RASP, Red Team, Proactive Threat Detection

Every scan type has its own attributes so make sure to provide the required values, the question mark can be used everywhere for getting help at any time if you're using the CLI tool.

zirkul#new scan dynamic scan
zirkul(new/scan/dynamic scan)#?
Options available:
==================================================
 => targetid : <not set>                          # Required: Target ID (Integer)
 => subject : <not set>                           # Required: This is the subject or short name for your scan (String)
 => description : <not set>                       # Optional: This can be a short description (String)
 => status : <not set>                            # Optional: The status can be one of the following (Not started, In ...
 => Assignee : <not set>                          # (User)
 => URL : <not set>                               # The URL to scan (url)
 => Directory Restriction : <not set>             # (Boolean)
 => Enable http and https : <not set>             # (Boolean)
 => Enable form submissions : <not set>           # (Boolean)
 => Credentials : <not set>                       # (ShortString)
 => Authentication Notes : <not set>              # (ShortString)
 => TimeZone : <not set>                          # (Integer)
 => StartDate : <not set>                         # (DateTime)
 => DueDate : <not set>                           # (DateTime)
 => TimeFrom : <not set>                          # (Integer)
 => TimeTo : <not set>                            # (Integer)
 => Scan Notes : <not set>                        # (ShortString)
 => Tool name : <not set>                         # (ShortString)
 => Result : <not set>                            # Assigned grade used for Security Gates (Passed, Failed, Error)
 => Response message : <not set>                  # (ShortString)
 => Date Started : <not set>                      # (DateTime)
 => Date Completed : <not set>                    # (DateTime)

Actions:
==================================================
 => ? | help                                      # New Scan help: Help for new scan actions
 => exit | back                                   # Exit scan request: Exit from scan request mode
 => submit                                        # Submit request: Request a new scan

zirkul(new/scan/dynamic scan)#

The action "submit" send the request to Zirkul for creating a new scan, if the request is approved, the current scan is stored in the object "scan":

echo scan.id
123

Update scans

If you want to update an existing scan, you can load it for modifying any of its attributes:

# Load a scan by id
scan 123
    status: 'in progress'
    description: 'Scanning Target {{target.id}}'
    update
    -

# Load the current scan if it was previously loaded
scan scan.id
    status: 'completed'
    description: 'Scanning Target {{target.id}}'
    update
    -

Web scan with Zirkul Scanner

The Agent has a built-in vulnerability scanner you can use for detecting issues in your web applications:

scanner
    url scan.url
    start spider
    -

Plugins

The most powerful feature the Agent has is the ability to run scans with external tools, you can use plugins for well-known tools and orchestrate everything from Zirkul with this functionality.

For example, let's say you want to run a scan using Burp Suite Pro/Enterprise, nmap, OWASP ZAP, Wapiti, etc and get everything published in Zirkul, this is possible with the plugins available in the marketplace.

plugins
[ ! ] Plugins Available:
 => burp                                          # BurpSuite: BurpSuite integration for Dynamic automated scanning
 => sonarqube                                     # SonarQube: SonarQube integration for Static Analysis
 => zap                                           # OWASP ZAP: Run OWASP ZAP

[ ! ] For loading plugins use: load <plugin_name>

Example: OWASP ZAP

load zap
[ + ] Downloading plugin: zap
[ + ] Plugin file downloaded
[ + ] Installing plugin: zap
[ + ] Loading plugin: zap

Run OWASP ZAP
How to use: OWASP ZAP Version: 1.1
==================================================
 usage: zap

OWASP ZAP plugin require the following parameters:
==================================================
 => url : <not set>                               # url (Required): URL ZAP will be scanning
 => args : <not set>                              # args: Send custom arguments for running ZAP (override other parame...
 => port : 9995                                   # port: The port used by ZAP for running the local proxy
 => apikey : <not set>                            # apikey: Setup a custom API key for ZAP, if not provided JaguarScan...
 => path : <not set>                              # path: Custom path for locating the zap.bat or zap.sh script, if no...
 => memory : 512                                  # memory: You can specify how much memory Zap will use (512 default)
 => scantype : 'full'                             # scantype (Required): What scan type do you want ZAP to run: spider...

 Return = "vuln"

Commands:
==================================================
 => ?                                             # Help: Show this message
 => run                                           # Run: Execute this plugin
 => back                                          # Exit: Close this plugin

Publishing results

The results from all the security scans and plugins you run in the script are stored locally in the Agent's memory, you must explicitly publish the results for uploading the issues to Zirkul.

publish issues