# Welcome Welcome to the Zirkul DevSecOps and AppSec management documentation site. Zirkul is a platform designed for DevSecOps (application security scanning automation) and Application Security program management. **AppSec Management** Zirkul can be used for: * Track all your managed assets in a single place, from Web Apps, Mobile Apps, Servers, IP ranges or anything you want to track security testing for. * Manage all security testing activities in a single place, from pentest, DAST, SAST, SCA, Network Scans, etc. It doesn't matter if you're scanning with third parties or internally. * Vulnerability Management designed for Agile teams, this can be used for assigning issues, request retest, raise exceptions, challenge false positives, ask questions, add comments, get remediation guidance, attach evidence and more. * Groups for access segmentation. * Fully granular user roles and permissions. * Generate metrics exporting data in excel format so you can answer questions such as: * How many pentest have been completed this year? * How many open vulnerabilities do we have, broken down by country or business unit? * Is App X in compliance with no Critical or High open vulnerabilities? * Which Apps have not completed a SAST or DAST scan this year? **DevSecOps / CICD** Zirkul is designed to be friendly with all CICD processes with functionalities available for integrating in many ways. You can launch scans from CICD pipelines by: * Making a webhook call. * Using our portable agent for scanning within the internal network. * Requesting scans to be executed in the Cloud. In the next sections you will find examples of running scans from some popular platforms. If you have any questions, please contact # Getting started AppSec scanning automation can be done in several ways explained in the sections of this page. ### First step Make sure you have access to the functionalities required for CICD automation: 1 - Check if the "Continuous Testing" is available to you. ![](https://3824814822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2TrvRPLIHQjOEfOcBEbb%2Fuploads%2FbvNRDvIV54Y1WVWWvcyY%2Fimage.png?alt=media\&token=4f5e01ff-24ea-4564-b6cf-a72345dc3158) 2 - Download the Agent

3 - To run scans, you'll need an API Key, ask your administrator to provide one or generate your own in the section User profile \ API Keys:

### I don't see these options If you don't see these options: * **I'm not an administrator**: Access can be requested to the company administrator. * **I'm an administrator**: validate your current subscription plan with the account manager assigned to your company. ### Second step Add a new job following the steps detailed [here](/devsecops/creating-jobs). ### Third step Get the Agent up and running in a system within your infrastructure with [this guide](/zirkul-agent/running-the-agent#service-mode). ### Fourth step Run the Job with [these steps](/devsecops/running-jobs). # Creating Jobs Automated tasks in Zirkul are handled by Jobs Let's say you want to run a security scan automatically every time an application is deployed by your CICD process. Jobs are used in Zirkul for setting up "recipes" or "playbooks" with the step-by-step instructions to be followed by the Agent. There's a straightforward syntax used for building your Jobs, here's an example: ```yaml # Let's load a target by ID target 150 # Create a new dynamic scan (DAST) new scan dynamic scan targetid: target.id subject: 'Dynamic Scan for {{target.name}}' status: 'not started' url: target.url tool name: 'Zirkul Agent' submit - # New scan data is stored in the object: scan # Let's move the scan to 'In progress' scan scan.id status: 'in progress' description: 'Scanning Target {{target.id}}' update - # Now we can run the scan with Zirkul scanner scanner url scan.url start spider - # Update the scan when the scan is completed scan scan.id status: 'completed' response message: 'Scan completed successfully' update - # Now let's publish all the issues found so you can track them in Zirkul publish issues ``` You will find more information on how to write Job scripts in the section: Agent CLI Let's add your first script: 1 - In te section "Continuous Testing \ Jobs", click on "Add Job"

2 - Fill out the form as follows for creating the classic "Hello world" Job:

3 - For executing Jobs, you need the Agent running in service mode connected to Zirkul, [download the Agent](/devsecops/getting-started#first-step) and run it with the following command: ``` zirkul --service true --agent cicd --server http://app.zirkul.com --apikey 'YOUR-API-KEY-HERE' ``` If everything is working as expected, you should see something like this:

4 - Let's run the Job from Zirkul clicking the "play" icon:

You can see the progress clicking the option "View executed jobs" ![](https://3824814822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2TrvRPLIHQjOEfOcBEbb%2Fuploads%2F7NYjMPPhyCZv1ywWtWf1%2Fimage.png?alt=media\&token=a8a278a7-5e59-47d2-9ff3-8813df8614c0)

You should also see the Agent running the Job in the command line:

Once completed, the executed Job should look like this:

Of course, this was just a testing exercise, and you don't want to manually execute a Job every time it's needed, in the next section we're going to see the options available for automating the process for running Jobs. # Running Jobs Jobs are intended to be triggered from CICD automation tools We'll asume you have created a Job already, if you want to know how to create a new Job please read [this](/devsecops/creating-jobs). There are diverse ways you can use for running Jobs and we're going to cover each in this section. ### Webhook calls Every Job has a webhook id that can be used for easily triggering the Job from anywhere, this webhook call information can be obtained directly from the Job by clicking the button "CICD Integration":

This will open a window where you can copy the command used for triggering the Job

Let's see several ways for calling the webhook: #### CURL command OSX and Linux: ```sh curl -H "X-API-KEY: " https://app.zirkul.com/api/webhook/ ``` Windows: ```sh curl -H @{'X-API-KEY'=''} https://app.zirkul.com/api/webhook/ ``` If you want to send variables in your request, use the custom http request header `ZIRKUL-VARIABLES` as follows. ```sh curl -H "X-API-KEY: " -H "ZIRKUL-VARIABLES: my_var='the value' " https://app.zirkul.com/api/webhook/ ``` #### Zirkul Agent CLI The Agent can be executed as a CLI interactive tool and there are some parameters that allows you to call a webhook with some extended functionalities. This is a simple command for calling a webhook and wait until the job is completed: ```sh zirkul --agent cicd --server https://app.zirkul.com --webhook --apikey '' --wait ``` You can also send custom variables to the Job with the [variables option.](/zirkul-agent/running-the-agent/command-line-interface#external-variables) The output would be something like this:

Use the option `--wait` if you want the Agent to wait until the Job is completed, otherwise the command will exit as soon as the webhook call is completed. See more about [webhook calls here](#webhook-calls). #### PowerShell ```powershell $headers = @{ 'X-API-KEY' = '' } Invoke-RestMethod -Uri https://app.zirkul.com/api/webhook/ -Method Get -Headers $headers ``` ### Securing your secrets It's strongly recommended to store your API Keys in variables instead of hardcoding the values in your pipelines to prevent unauthorized access to secrets. # Azure DevOps Pipelines Zirkul Jobs can be easily executed from Azure DevOps in several ways we'll be covering here. ### Service Hooks Azure DevOps has a functionality called Service Hooks that can be used for calling webhooks under specific conditions. This can be configured in the section "Project settings \ Service hooks"

Click in the "+" icon for adding a new service, select "Web hook" from the list and click "Next":

Select the options of your preference for the trigger settings and click "Next":

In the section "Action", add the full URL for [calling the webhook in Zirkul ](/devsecops/running-jobs#webhook-calls)and provide the API Key information in the HTTP headers section:

Click "Test" for making sure everything's configured correctly

With this approach, the webhook is going to be called automatically every time the conditions are met. ### Webhook call from Pipelines You can also call the webhook directly from your pipeline, the API Key can be stored in an encrypted variable for avoiding hardcoding any secrets in your YAML files and prevent leakage in log entries. In the pipeline configuration you can add a variable for your API Key as follows:

Make sure the "lock" icon is closed for storing the secret with encryption. Then in your pipeline tasks you can add a command line script for [running the webhook call](/devsecops/running-jobs#webhook-calls) replacing the API Key with the variable:

For calling the variable use the format: `$(variable_name)` Test your pipeline and you should see something like this:

*Note the secret is being protected.* # Jenkins Pipelines Zirkul Jobs can be executed from Jenkins Pipelines simply by making webhook calls, however you have to make sure the API Key is protected and avoid hardcoding any secret in your pipeline scripts. Let's start by storing the Zirkul API Key in Jenkins Credentials manager:

Add a new credential scoped to the project folder:

The kind of secret is "Secret text", in the secret section you can paste the API Key value and use the ID zirkul\_apikey (for convenience in this guide):

You can then use the secret within the pipeline script in the following way:

Here's the pipeline script: ```yaml pipeline { agent any stages { stage('Hello') { steps { withCredentials([string(credentialsId: 'zirkul_apikey', variable: 'zirkul_apikey')]) { sh 'curl -H "X-API-KEY: $zirkul_apikey" https://app.zirkul.com/api/webhook/f3f75cca-da48-4720-be53-8c0396ca041e' } } } } } ``` Note you may need to update the webhook id with the [URL provided by Zirkul for your Job](/devsecops/running-jobs#webhook-calls). Once you run the pipeline, the console output should look like this:

Note: * The API Key is protected and is not included in the logs * The webhook call returned the message "Success" # Job Script Syntax Zirkul scripts are command executed by the Agent Our Agent is a portable tool you can [download from Zirkul ](/devsecops/getting-started#first-step)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: ```sh var var_name = 'The value here' ``` Then you can use the variable in several ways: ```sh 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. ```sh 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 => 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 => 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:** ```bash # 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: ```sh 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. ```sh zirkul#new scan dynamic scan zirkul(new/scan/dynamic scan)#? Options available: ================================================== => targetid : # Required: Target ID (Integer) => subject : # Required: This is the subject or short name for your scan (String) => description : # Optional: This can be a short description (String) => status : # Optional: The status can be one of the following (Not started, In ... => Assignee : # (User) => URL : # The URL to scan (url) => Directory Restriction : # (Boolean) => Enable http and https : # (Boolean) => Enable form submissions : # (Boolean) => Credentials : # (ShortString) => Authentication Notes : # (ShortString) => TimeZone : # (Integer) => StartDate : # (DateTime) => DueDate : # (DateTime) => TimeFrom : # (Integer) => TimeTo : # (Integer) => Scan Notes : # (ShortString) => Tool name : # (ShortString) => Result : # Assigned grade used for Security Gates (Passed, Failed, Error) => Response message : # (ShortString) => Date Started : # (DateTime) => Date Completed : # (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": ```sh echo scan.id 123 ``` **Update scans** If you want to update an existing scan, you can load it for modifying any of its attributes: ```sh # 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: ```sh 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. ```sh 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 ``` Example: OWASP ZAP ```sh 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 : # url (Required): URL ZAP will be scanning => args : # args: Send custom arguments for running ZAP (override other parame... => port : 9995 # port: The port used by ZAP for running the local proxy => apikey : # apikey: Setup a custom API key for ZAP, if not provided JaguarScan... => path : # 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. ```sh publish issues ``` # Script templates Quick templates you can use for common tasks Feel free to use the templates in this section as the starting point for your scripts ## CICD DAST scan with Zirkul scanner ```yaml var tool = 'Zirkul Scanner' target 150 new scan dynamic scan targetid: target.id subject: 'Dynamic Scan with {{tool}} for {{target.name}}' status: 'not started' url: target.url tool name: tool submit - scan scan.id status: 'in progress' description: 'Scanning Target {{target.id}} with {{tool}}' update - scanner url scan.url start spider - scan scan.id status: 'completed' response message: 'Scan completed successfully' update - publish issues ``` # Running the Agent Zirkul Agent can be used for several tasks including: * **Stand alone tool:** for security tasks such as manually running scans or commands taking advantage fo the plugins available. * **Webhook Trigger**: for starting CICD jobs. * **Service mode**: for running as a system service within your infrastructure for executing Jobs created for CICD pipelines. ### Stand alone Zirkul Agent was initially designed as a command line tool for security automation, you can simply run zirkul from terminal for starting the interactive command line interface: ```bash zirkul ```

See more in [Command Line Interface](/zirkul-agent/running-the-agent/command-line-interface) ### Webhook Trigger You can use the Agent for calling webhooks used for starting Jobs in Zirkul Server: ```sh zirkul --apikey "" --webhook "" --agent "" --wait ``` Where: * \ is the API Key created in Zirkul Server. * \ is the webhook token id assigned to the Job you want to run. see [Creating Jobs](/devsecops/creating-jobs) * \ is the Agent name or key you want to assign. Note: * \--server is optional, the default value is '' * \--webhook is required for calling a web hook. * \--apikey is required for calling a web hook. * \--agent is required for calling a web hook. * \--wait is optional, use this if you want the agent to wait until the Job is completed. ### Service Mode Service mode is used for running the agent as system service that will continue running continuously waiting for Jobs to be executed. ```sh zirkul --server "https://app.zirkul.com" --service --agent "" --apikey "" ``` Where: * \ is the API Key created in Zirkul Server. * \ is the Agent name or key you want to assign. Note: * \--server is optional, the default value is '' * \--service is required for running in service mode. * \--apikey is required for running in service mode. * \--agent is required for running in service mode. # Command Line Interface Zirkul Agent was initially designed as a command line tool for security automation, you can simply run zirkul from terminal for starting the interactive command line interface: ```bash zirkul ```

You can also get more information related to parameters with: ```sh zirkul --help ```

The command line interface support commands, options and plugins created for making a cross-platform terminal loaded with helpful cyber security functionalities available in OSX, Linux and Windows. ### Commands Commands are used for running built-in functionalities and configuring system options: ```sh echo "Hello world!" ``` See all the commands available sending the question" ? " character:

### Plugins Plugins are the main functionality of the Agent allowing the tool to integrate with almost any tool either from command line or trough REST APIs. Plugins are made as Python scripts making it very easy to create and extend. Example, loading ZAP plugin: ```sh load zap ``` There are different types of plugins for "functions", "exploits" or "integrations": * **Functions**: Processing and/or returning values without interacting with external tools.\ Example: \` echo date \` will return the current date in text format. * **Exploits**: Testing known vulnerabilities (CVEs) receiving parameters and returning if the execution was successful or not.\ Example: \` load ms15-034 \` * **Integrations**: These plugins are used for interacting with external tools such as command line tools or remote services through Web APIs.\ Example: Running scans and returning results from tools such as ZAP, Burp Suite, nmap, sqlmap, Metasploit, etc. ### Options Options are used for configuring parameters sent to plugins, usually separated by colon ' : ' Example: ```sh load zap url: "https://evil.com" # The option is 'url', note ':' is required. ``` ### External Variables Zirkul Agent can get external variables either from command line arguments or environment variables as follows. #### Command line argument "--variables" With the argument ' --variables ' you can send as many as the terminal allows, example: ```sh zirkul --variables "var_name=123 another_var='Text with spaces'" ``` Every variable must be separated by spaces, any value including spaces must be enclosed with single quotes. #### Environment variables Environment variables are defined at system level in your computer, usually can be set with the command: ```sh export MY_VAR="This is the value" ``` From Zirkul Agent, you can get the environment's variable value with the [env function](/zirkul-agent/command-reference/env): ```sh echo env("MY_VAR") => This is the value ``` See more information in the [command reference](/zirkul-agent/command-reference). # Command reference Here you will find the list of commands available in Zirkul Agent, any command can be used in your CICD Jobs. Zirkul agent can be used as an interactive standalone command line application if you run it with no arguments: ```bash c:\zirkul.exe =========================================================== Zirkul Agent v2.1.11 Zirkul S.A, 2024 =========================================================== If you have any questions: Visit: https://docs.zirkul.com Email: support@zirkul.com [ ! ] Loading service configuration [ ! ] Loading Vulnerability translation database Welcome to Zirkul Agent, send "?" for help on how to use this tool zirkul# ``` Once the agent is loaded, you will see the terminal mode is changed to `zirkul#` which means, Zirkul is ready for receiving commands. ### Command line arguments Command line arguments are also available, you can use -h or --help for getting the list of arguments available: ```bash zirkul -h usage: zirkul [-h] [-k APIKEY] [-u SERVER] [-f SCRIPT] [-H WEBHOOK] [-w {True,False}] [-a AGENT] [-p PLUGINS] [-S {True,False}] Zirkul Agent 2.1.11 for CLI and CICD automation optional arguments: -h, --help show this help message and exit -k APIKEY, --apikey APIKEY API Key for connecting to Zirkul server -u SERVER, --server SERVER Zirkul Server URL (SaaS will be used if not provided) -f SCRIPT, --script SCRIPT File path for the script you want to run -H WEBHOOK, --webhook WEBHOOK Execute a remote job via webhook call -w , --wait Wait for webhook task to be completed -a AGENT, --agent AGENT Use an unique agent name that should match with the agent in a job for CICD -p PLUGINS, --plugins PLUGINS Overwrite the path where the plugins are located -S , --service Run this tool in service mode if you want to use the agent for running scans locally For more information visit: https://docs.zirkul.com ``` ### Commands basics Some important basic considerations: * Commands and arguments need to be separated by spaces.\ `zirkul# command argument` * Text literals need to be enclosed between single or double quotes:\ `zirkul# print "Hello world"` * Multiline text is also supported as follows:\ ``zirkul# print `multiline text``\ `` another line` `` * There are locations or configuration modes for configuring settings or plugins, when you're inside a configuration mode the terminal symbol will chance indicating the location you're currently in:\ `zirkul# server` \ `zirkul(server)#` * For getting out of a configuration mode, use the command `exit` or ' `-` '\ `zirkul(server)# exit`\ `zirkul#` * If you need help on the commands available in any mode, use the command `help` or simply ' `?` ' * Exit the application with `exit` or `quit`. Scripts can be created with the list of commands you want the agent to execute, this is useful for automation purposes, let's create a simple script 'script.txt': ```bash # This is a comment in my first script var my_name = 'John' print 'My name is: {{my_name}}' ``` Now we can run the script with the following command: ```bash zirkul.exe --script script.txt =========================================================== Zirkul Agent v2.1.11 Zirkul S.A, 2024 =========================================================== If you have any questions: Visit: https://docs.zirkul.com Email: support@zirkul.com [ ! ] Loading service configuration [ ! ] Loading Vulnerability translation database Welcome to Zirkul Agent, send "?" for help on how to use this tool [ ! ] Running Script: script.txt var my_name = 'John' print 'My name is: {{my_name}}' My name is: John [ ! ] Script Completed ``` # Help Get help on how to use any command or option based on the location you're currently on. Command: `? | help` Location based help syntax: ```bash zirkul#? Zirkul Command line Interface ============================= Commands reference: =================== Global commands: ================ => ? | help # Help: Display this message => cls | clear # Clear screen: Clear the screen => var = # Variable: Store or update a variable => vars # List Variables: List current variables => print | echo | > # Print message: Display a message in the screen => - # Exit mode: Exit from configuration mode => scan # Load scan: Load scan in Zirkul server => date # date: Return the current date => now # now: Return the current date including time and milliseconds => utcnow # utcnow: Same as "now" returning the date in UTC time => day # day: Return the current day (number) => month # month: Return the current month (number) => year # year: Return the current year (number) => hour # hour: Return the current hour (number) => minute # minute: Return the current minute (number) => second # second: Return the current second (number) .... ``` Command help syntax: ```bash zirkul#cls ? Clear screen: Clear the screen ============================== Usage: cls | clear ``` # Clear Clear the terminal screen. Command: `cls | clear` Syntax: ```bash zirkul#cls ``` # Var Defines temporary local variables. Command: `var` Syntax: ```bash var = ``` Example: ```bash var myVar = 'Text here' print myVar Text here ``` You can use variables in several diverse ways, here are some examples: In commands: ```bash var url = "http://example.com" server url ``` In options: ```bash zirkul(plugin)# url: varname ``` Within formatted string values: ```bash zirkul(scanner)# url "http://{{var_name}}" zirkul(scan)# summary: "My Scan for {{var_name}}" ``` ### There are also reserved variables for dates, time, paths or objects. Current date: ```bash print date Mar-27-2095 ``` Current time: ```bash print now 2095-03-27 13:52:56 ``` Current time in UTC time zone: ```bash print utcnow 2024-03-27 19:55:29 ``` Current day of the month in numeric format: ```bash print day 27 ``` Current month in numeric format: ``` print month 3 ``` Current year in numeric format: ```bash print year 2095 ``` Current hour, minute and second:

print 'Time = {{hour}} : {{minute}} : {{second}}'
Time = 12 : 35 : 47

Current working directory: ```bash print working_path /Applications/zirkul.app/Contents/MacOS ``` Path based on agent current location: ```bash print binary_path /user/Documents ``` The scan object is created when a scan is loaded or created, you can use the object directly or it's attributes as follows: ```bash zirkul#scan 2 [ + ] Vulnerability data retrieved from server: Success [ + ] Scan data retrieved from server: Success zirkul(scan)#print scan Current scan: ================================================== id => 2 targetid => 339 subject => 'Network Scan - Internal' description => '192.168.90.0/24' scan_type => 'Network Scan' status => 'Completed' created_date => '2021-01-18 13:12:13' created_by => 'user@example.com' created_api => False last_modified_date => '2024-03-26 21:00:10' last_modified_by => 'admin@zirkul.com' last_modified_api => False Attributes: ip => '192.168.90.0/24' testing_environment_type => 'Internal' assignee => 'user@client.com' Compliance: rating => 'F' critical => 1 high => 4 medium => 78 low => 16 informational => 0 zirkul(scan)#print scan.scan_type Network Scan zirkul(scan)# ``` The target object is created when a target is loaded, you can use the object directly or it's attributes as follows: ```bash zirkul#target 1 [ ! ] Target loaded successfully: 1 zirkul#print target Current target: ================================================== id => 1 target_type => 'Network range' owner => name => 'Dolphin' description => 'Internal network in Dolphin offices' created_date => '2021-01-18 13:11:47' created_by_api => False created_by => 'user@example.com' last_modified_date => '2021-10-21 21:31:00' last_modified_by_api => False last_modified_by => 'user@example.com' Compliance: rating => 'A+' critical => 0 high => 0 medium => 0 low => 0 informational => 0 zirkul# zirkul#print target.name Dolphin zirkul# ``` There's also an object called 'issues' created by the internal scanner or plugins containing the list of issues detected in the current session, you can get the summary of all issues as well as details for every specific issue as follows: ``` zirkul#print issues Local issues data: ================================================== issues.count => 15 issues.critical => 0 issues.high => 0 issues.medium => 3 issues.low => 12 issues.info => 0 ================================================== You can also get more details from any issue: print issues[1] print issues[1].details zirkul#print issues.count 15 zirkul#print issues[1].type Missing X-Frame-Options Header ``` # Vars Print the list of defined variables. Command: `vars` Syntax: ```bash vars ``` Example: ```bash zirkul#vars Variables: ================================================== myVar => 'Text here' Reserved variables: date => (reserved) now => (reserved) utcnow => (reserved) day => (reserved) month => (reserved) year => (reserved) hour => (reserved) minute => (reserved) second => (reserved) binary_path => (reserved) working_path => (reserved) Syntax: ================================================== var var_name = "value" You an use variables in several different ways, here are some examples: In commands # zirkul# server var_name In options # zirkul(plugin)# url: var_name Within string values # zirkul(scanner)# url "http://{{var_name}}" zirkul(scan)# summary: "My Scan for {{var_name}}" Private variables # zirkul# print scan.id # zirkul# print target.id # zirkul# print issues # zirkul# print issues[1] # zirkul# print issues[1].severity zirkul# ``` # Print Print values in the terminal. Command: `print` Syntax: ```bash print | echo | > 'string or numeric values' ``` Example: ```bash print 'Hello world!' Hello world! echo 'Hello world!' Hello world! > 'Hello world!' Hello world! print 123 123 var my_var = 'MyVar' echo my_var MyVar echo 'The value is {{my_var}}' The value is MyVar ``` # Date Return the current date Command: `date` Syntax: ```bash echo date ``` Example:

echo date
Jul-10-2024

var my_date = date
echo my_date
Jul-10-2024

var my_date = date
echo 'The current date is {{my_date}}'
The current date is Jul-10-2024

# Now Return the current date and time Command: `now` Syntax: ```bash echo now ``` Example:

echo now
2024-07-10 16:34:23

var my_date = now
echo my_date
2024-07-10 16:34:23

var my_date = now
echo 'The current date is {{my_date}}'
The current date is 2024-07-10 16:34:23

# UTCNow Return the current date and time Command: `utcnow` Syntax: ```bash echo utcnow ``` Example:

echo utcnow
2024-07-10 16:34:23

var my_date = utcnow
echo my_date
2024-07-10 16:34:23

var my_date = utcnow
echo 'The current date is {{my_date}}'
The current date is 2024-07-10 16:34:23

# Day Return the current day in numeric value Command: `day` Syntax: ```bash echo day ``` Example:

echo day
10

var my_day = day
echo my_day
10

var my_day = day
echo 'The current day is {{my_day}}'
The current day is 10

# Month Return the current month in numeric value Command: `month` Syntax: ```bash echo month ``` Example:

echo month
10

var my_month = month
echo my_month
10

var my_month = month
echo 'The current month is {{my_month}}'
The current month is 10

# Year Return the current year in numeric value Command: `year` Syntax: ```bash echo year ``` Example:

echo year
2024

var my_year = year
echo my_myear
2024

var my_year = year
echo 'The current year is {{my_year}}'
The current year is 2024

# Hour Return the current hour in numeric value (24 hours format) Command: `hour` Syntax: ```bash echo hour ``` Example:

echo hour
17

var my_hour = hour
echo my_hour
22

var my_hour = hour
echo 'The current hour is {{my_hour}}'
The current hour is 22

# Minute Return the current minute in numeric value Command: `minute` Syntax: ```bash echo minute ``` Example:

echo minute
17

var my_minute = minute
echo my_minute
22

var my_minute = minute
echo 'The current minute is {{my_minute}}'
The current minute is 22

# Second Return the current second in numeric value Command: `second` Syntax: ```bash echo second ``` Example:

echo second
17

var my_second = second
echo my_second
22

var my_second = second
echo 'The current second is {{my_second}}'
The current second is 22

# Env Return the value for the environment variable name given Command: `env` Syntax: ```bash echo env option = env() ``` Example:

echo env "HOME"
/Users/username

var my_var = env("HOME")
echo my_var
/Users/username

var my_var = env("HOME")
echo 'The environment variable value is: {{my_var}}'
The current second is: /Users/username

# Is base64 Return True or False if the value provided is encoded in Base64 Command: `is_base64` Syntax: ```bash is_base64 ``` Example: ```bash > to_base64 "Hello World!" SGVsbG8gV29ybGQh > is_base64 "SGVsbG8gV29ybGQh" True > is_base64 "Random Value" False ``` # To base64 Return the value provided encoded with Base64 Command: `to_base64` Syntax: ```bash to_base64 ``` Example: ```bash > to_base64 "Hello World!" SGVsbG8gV29ybGQh ``` # From base64 Return the clear text value decoded from the Base64 value provided Command: `from_base64` Syntax: ```bash from_base64 ``` Example: ```bash > from_base64 "SGVsbG8gV29ybGQh" Hello World! ``` # Scanner signatures Zirkul Agent automatically downloads vulnerability detection rules from the official server, however, the community can also help by creating their own rules and sharing them with other users. In this section you will find the format used for creating passive or active scan rules as well as the steps needed for testing them. ### Passive scan signatures Passive scan refers to exploring a web site without sending any exploit, this is done by the spider included in the scanner which crawls all the locations found in the URL provided, for each URL discovered, the scanner will try to match the conditions defined in the passive scan rules then reporting the vulnerability if the conditions are met. Here's an example: ```json { "name": "Missing Content Sniffing protection", "key": "content-sniff-protection", "type": "vulnerability", "severity": "medium", "cwe": 693, "owasp": "A05:2021", "cvss": 4.3, "cvss_string": "AV:N/AC:L/PR:N/UI:R/S:U/C:L/I:N/A:N", "cve": null, "details": "The server is not returning the following security header: X-Content-Type-Options", "technology": {"application": "Jenkins", "lang": "Java"}, "rules": [ { "in": "response header name", "header name": "x-content-type-options", "compare": "missing" },{ "in": "response header value", "header name": "status", "compare": "contains", "value": "200" } ] } ``` #### Keywords definition: **name**: This is the name of the vulnerability or object to be reported **key**: This should be a unique identifier, using a duplicate key will produce an error. **details**: Details explaining why this is a risk and the potential impact. **type**: This is the object type from: **vulnerability**: The reported object is a vulnerability. **waf**: This will be used for Web Application Firewall detection **platform**: The rule will be used for platform detection **severity**: The severity assigned for vulnerabilities: **Critical**, **High**, **Medium**, **Low**, **Info** (For types **waf** and **platform**, the severity should be **info**) **cwe**: (Optional) Common weakness enumeration from MITRE if applicable. **owasp**: (Optional) OWASP Top 10 reference id if applicable. **cvss**: (Optional) Common vulnerability scoring system (CVSS) numeric score if applicable, from 0 to 10. **cvss\_string**: (Optional) CVSS vector string with the factors for calculating the score from MITRE's calculator. **cve**: (Optional) Common vulnerabilities and exposures id if applicable. **remediation**: (Optional) Remediation guidance for fixing the vulnerability. **technology**: (Optional) The signature would identify platform details if the conditions defined in **rules** are met, this can be used later for conditions defined in the **rules** or other signatures based on the technologies detected: **application server:** (Optional) Application server identified with the value provided, examples: GlassFish, Tomcat, Flask, etc. **web server**: (Optional) Web server identified with the value provided examples: IIS, NGinX, Apache, Websphere, etc. **lang**: (Optional) Programming language identified with the value provided, examples: Java, Python, Ruby, .NET, etc. **application**: (Optional) Application name identified with the value provided, examples: Jenkins, Wordpress, Drupal, Joomla, Jira, etc. **rules**: The rules are the conditions for deciding if the detection is True or False, see [rules section](#rule-syntax) further in the page. ### Active scan signatures Active scan signatures are interactions with the target host or application, the interaction could be an exploit for known vulnerabilities or discovery of exposed assets or services. Here's an example: ```json { "name": "Wordpress vulnerable to Distributed Denial of Service Attacks (DDoS)", "key": "active-wordpress-xml-rpc", "type": "vulnerability", "severity": "high", "details": "Wordpress functionality XML-RPC is enabled and exposed, this functionality can be used by threat actors for performing Distributed Denial of Service (DDoS) attacks against the vulnerable site.", "remediation": "Restrict the access to XML-RPC so it can only be used internally instead of exposing it to external users, this can be done with .htaccess rules if you're using Apache, access control configuration in NGinX or via rules in WAF configuration.", "technology": {"application server": "PHP", "application": "Wordpress", "lang": "PHP"}, "active scan": { "type": "one issue", "trigger": [ { "in": "technology", "compare": "contains", "value": "wordpress" } ], "do": { "post": "{{current_dir}}/xmlrpc.php", "data": "system.listMethods", "rules": [ { "in": "response header value", "header name": "status", "compare": "contains", "value": "200" }, { "in": "response body", "compare": "contains", "value": "pingback.ping" } ] } } } ``` #### Keywords definition: Most of the keywords defined for passive scan signatures are also applicable here, the following are the ones only applicable for active scan signatures. **active scan**: This object contains the pre-requirements for running the signature (trigger) and the conditions for validating the results (rules). **type**: This is the way the signature should be applied: \ **one issue**: The scanner shall report just one issue of this type per scan, this is useful for avoiding duplicates if the same conditions are met in multiple locations during the scan.\ **every request**: The scanner will evaluate this signature for every URL detected by the spider. **trigger**: The trigger contains the rules used for deciding if the signature should be executed or not, all conditions must be True. (see[ rules section](#rule-syntax) for syntax reference) **do**: This object contains the actions to be executed by the scanned if the trigger conditions are met.\ \ : \ # The request http method followed by the URL , examples:\ `"get": "http://zirkul.com"`\ `"post": "http://zirkul.com"`\ `"put": "http://zirkul.com"`\ `"patch": "http://zirkul.com"`\ `"delete": "http://zirkul.com"`\ \ **data**: (Optional) This is the payload used for the http methods: POST, PUT or PATCH\ headers: (Optional) HTTP headers to be included in the request in json format, example\ `{"User-Agent": "My user agent"}`\ **rules**: The rules are the conditions for deciding if the detection is True or False, see [rules section](#rule-syntax) further in the page. ### Rule syntax The "rules" are conditions evaluated for making decisions, the result is True only if all the conditions are met, otherwise the result is going to be False. The object "rules" can contain one or a list of json objects, the following examples are both valid: ```json "rules": [ { "in": "response header value", "header name": "status", "compare": "contains", "value": "200" }, { "in": "response body", "compare": "contains", "value": "pingback.ping" } ] ``` ```json "rules": { "in": "response header value", "header name": "status", "compare": "contains", "value": "200" } ``` #### Keywords definition: Every rule has the following sections for defining: * **in**: where is the value to be compared. * **header name**: (Optional) If the "in" clause is based on a header value, you can define the specific header name here. * **compare**: What kind of validation or comparison should be done. * **value**: (Optional) The value to compare based on the "compare" clause. ### in (Required) Defines where is the value to be used, here are the allowed values: ***response header name*** Compare something in the response header name, the additional ***header name*** clause is required for defining the name of the header. Example: ```json { "in": "response header name", "header name": "x-powered-by", "compare": "exists" } ``` ***response header value*** Compare something in the response header value, the additional ***header name*** clause is required for defining the name of the header. Example: ```json { "in": "response header value", "header name": "server", "compare": "contain numbers" } ``` ***response body*** Compare something in the response body value. Example: ```json { "in": "response body", "compare": "contains", "value": "

Apache" } ``` ***request header name*** Compare something in the request header name. Example: ***request header value*** Compare something in the request header value. Example: ***request data*** Compare something in the request data for POST, PUT or PATCH methods. Example: ***request method*** Compare something in the request http method value. Methods or verbs such as get, post, head, put, patch, delete, etc. Example: ***url*** Compare something in the url. Keep in mind the rules can be tested against all URLs crawled by the spider or manually provided in the scope before running the scan. Example: ```json { "in": "url", "compare": "contains", "value": "jsessionid" } ``` ***technology*** Compare something in the technology labels identified for the current scan based on other signatures for platform detection or the built-in fingerprinting functionality. This is useful for restricting signatures that should be only tested against confirmed platforms and avoid false positives. Example: ```json { "in": "technology", "compare": "contains", "value": "wordpress" } ``` ### header name (Optional) This is only required if "**in**" is "***response header name***" or "***response header value***". The expected value is the header name to be analyzed, for comparing against the response status code you can use the reserved keyword "**status**". Example: ```json { "in": "response header value", "header name": "status", "compare": "contains", "value": "200" } ``` ### compare (Required) This is how the values are going to be compared, the allowed keywords are: * **contains** : If the value analyzed contains a **value** provided (case insensitive) * **not contains** : If the value analyzed do not contains a **value** provided (case insensitive) * **exists** : If the value analyzed exists. * **not exists** : If the value analyzed does not exist. * **is** : If the value analyzed is equal to the **value** provided (case insensitive) * **is not** : If the value analyzed is not equal to the **value** provided (case insensitive) * **is numeric** : If the value analyzed is a number. * **contain numbers** : If the value analyzed contains any number. * missing : If the value provided is missing in the **value** analyzed (case insensitive) ### https\_only (Optional) Specify if the signature is only applicable to https requests. Example: ```json { "name": "Strict Transport Security header not configured", "key": "hsts", "type": "vulnerability", "severity": "medium", "cwe": 693, "owasp": "A05:2021", "cvss": 4.3, "cvss_string": "AV:N/AC:L/PR:N/UI:R/S:U/C:L/I:N/A:N", "cve": null, "details": "The server is not returning the following security header: Strict-Transport-Security", "in": "response header name", "header name": "strict-transport-security", "compare": "missing", "https_only": true } ```