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 => 'user@company.com'
last_modified_date => '2023-05-23 19:32:42'
last_modified_by_api => False
last_modified_by => 'user@company.com'
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.
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.
