The information in this document applies to version 7.0 of Syhunt Hybrid.

Introduction

Launching Syhunt scans from within a BitBucket CI YML script is simple and straightforward, allowing you to integrate the Syhunt Dynamic, Syhunt Code and Syhunt Mobile security testing tools into your continuous delivery pipeline.

The following example BitBucket YML script will scan the current repository source code, failing the job if medium or high vulnerabilities are identified. In addition to this, and it attachs a vulnerability report to the pipeline job artifacts.

Windows

pipelines:
  default:
      - step:
          runs-on:
            - self.hosted
            - windows
          script:
            - Start-CodeScan -pfcond 'fail-if:risk=mediumup' -output 'report.pdf'
          artifacts:
            - report.pdf

Linux

pipelines:
   default:
       - step:
           runs-on:
             - self.hosted
             - linux.shell
           script: 
             - ${HOME}/syhunt-hybrid/carbon/scancode ${PWD} -pfcond:fail-if:risk=mediumup -rout:${PWD}/report.html
           artifacts:
             - report.html

Activating a Syhunt Runner

Syhunt Runner is a CI service that will receive scan requests, execute scans and communicate the scan results with BitBucket.

IMPORTANT: For security and performance reasons, it is advised that the Runner is installed on a separated virtual machine or dedicated physical machine.

1. First, install with its default settings the Git command:
   1. On Windows: install Git for Windows, which can be downloaded at https://gitforwindows.org/
   2. On Linux: install the git package using your distribution's package manager.
2. Secondly, install with its default settings Syhunt Hybrid (syhunt-hybrid-7.0.14.0.exe on Windows or syhunt-hybrid-7.0.14.0.jar on Linux)
3. Thirdly, type java -version in the Windows command prompt or Linux terminal and make sure you have Java 22.0.2 or superior installed. If not, install JDK22 or superior at https://www.oracle.com/java/technologies/downloads/
4. Finally, on Bitbucket.com, navigate to the main page of the repository:
   1. Under your repository name, click Repository settings in the left sidebar.
   2. Scroll down to Pipelines and click Runners
   3. Click the Add runner button, and select in System and architecture: Windows (64bit) or Linux Shell if you have Syhunt installed on Linux.
   4. Give the runner a name (eg: Syhunt) and a label (eg: syhunt) and click Next
   5. You will see instructions showing you how to download the runner application and install it on your self-hosted runner machine.
5. Follow the given instructions to activate the runner and, after that, click Next

Syhunt is now ready to be called from BitBucket CI scripts! See examples below

Adding Syhunt to your CI YML script

If you don't have a workflow YML file in your repository, create a file like “bitbucket-pipelines.yml” at your project’s root path.

SAST Example - The following example BitBucket CI YML script will scan the current repository source code, failing the job if medium or high vulnerabilities are identified. In addition to this, it attachs a vulnerability report to the pipeline job artifacts.

Windows

pipelines:
  default:
      - step:
          runs-on:
            - self.hosted
            - windows
          script:
            - Start-CodeScan -pfcond 'fail-if:risk=mediumup' -output 'report.pdf'
          artifacts:
            - report.pdf

Linux

pipelines:
   default:
       - step:
           runs-on:
             - self.hosted
             - linux.shell
           script: 
             - ${HOME}/syhunt-hybrid/carbon/scancode ${PWD} -pfcond:fail-if:risk=mediumup -rout:${PWD}/report.html
           artifacts:
             - report.html

DAST Example - The following example BitBucket YML script will scan the live web application after going into production, failing the job if medium or high vulnerabilities are identified. In addition to this, it attachs a vulnerability report to the pipeline job artifacts.

Linux

pipelines:
   default:
       - step:
           runs-on:
             - self.hosted
             - linux.shell
           script: 
             - ${HOME}/syhunt-hybrid/carbon/scanurl www.productionurl.com -pfcond:fail-if:risk=mediumup -rout:${PWD}/report.html
           artifacts:
             - report.html

Windows

pipelines:
  default:
      - step:
          runs-on:
            - self.hosted
            - windows
          script:
            - Start-DynamicScan -target 'www.productionurl.com' -pfcond 'medium' -output 'report.pdf'
          artifacts:
            - report.pdf

Additional Windows examples:

# SAST Example - Scan local directory/repository
Start-CodeScan -pfcond "medium"

# SAST Example - Scan a remote project repository
$MyProject = @{
  target = 'https://github.com/syhunt/vulnphp.git';
  branch = 'main';
  pfcond = 'medium';
  output = 'report.pdf'
}
Start-CodeScan @MyProject

# DAST Example - Scan URL
$MyWebsite= @{
  target = 'https://www.somewebsite.com';
  pfcond = 'medium';
  output = 'report.pdf'
}
Start-DynamicScan @MyWebsite

Start-DynamicScan Function

Linux

On Linux, Syhunt Dynamic must be launched through the scanurl command.

Windows

Syhunt Dynamic must be launched through the Start-DynamicScan() function. The following parameters must be provided when calling the Start-DynamicScan() function:

• target (required) - the target URL to be scanned (eg. http://www.somesite.com)
• huntmethod (optional) - the Hunt Method to be used during the scan, If omitted, the default method will be used.
• pfcond (optional) - allows the script to fail with proper exit code if a certain condition is met. See below a list of available pass/fail conditions.
• tracker (optional) - the name of previously created tracker or a dynamically generated tracker that will receive a summary of identified vulnerabilities at the end of the scan. Examples
• output (optional) - allows to set an output filename (eg. report.pdf or report.html).
• outputex (optional) - allows to set a second output filename (eg. export.json).
• verbmode (optional) - $false by default. If changed to true, turns on verbose mode allowing information other than error and basic info to be printed.
• genrep (optional) - $true by default. If changed to false, Syhunt will not generate an output file.
• redirIO (optional) - $true by default. If changed to false, input and output from the Syhunt scanner will not be redirected to the console.
• timelimit (optional) - sets the maximum scan time limit (default: no limit). If the time is reached, the scan is aborted. Examples: 1d, 3h, 2h30m, 50m

When using the output or outputex parameters, all output formats supported by Syhunt are available. The report or export will be saved to the current working directory, unless a full path name is provided.

Examples:

# Example 1 - Scan URL with single line
Start-DynamicScan -target 'https://www.somewebsite.com' -pfcond 'fail-if:risk=mediumup'

# Example 2 - Scan URL
$MyWebsite= @{
  target = 'https://www.somewebsite.com';
  pfcond = 'medium';
  output = 'report.pdf'
}
Start-DynamicScan @MyWebsite

Start-CodeScan Function

Linux

On Linux, Syhunt Code must be launched through the scancode command.

Windows

Syhunt Code must be launched through the Start-CodeScan() function. The following parameters can be provided when calling the Start-CodeScan() function, all of which are optional:

• target - the target URL of a project repository to be scanned, or a local source code directory or file. If the target parameter is omitted, the current working directory is scanned.
• branch - the repository branch to be scanned. If the branch parameter is omitted, the git client will fetch the default branch.
• huntmethod - the Hunt Method to be used during the scan, If omitted, the default method will be used.
• pfcond - allows the script to fail with proper exit code if a certain condition is met. See below a list of available pass/fail conditions.
• tracker (optional) - the name of previously created tracker or a dynamically generated tracker that will receive a summary of identified vulnerabilities at the end of the scan. Examples
• output - allows to set an output filename (eg. report.pdf or report.html).
• outputex - allows to set a second output filename (eg. export.json).
• verbmode - $false by default. If changed to true, turns on verbose mode allowing information other than error and basic info to be printed.
• genrep - $true by default. If changed to false, Syhunt will not generate an output file.
• redirIO - $true by default. If changed to false input and output from the Syhunt scanner will not be redirected to the console.
• timelimit (optional) - sets the maximum scan time limit (default: no limit). If the time is reached, the scan is aborted. Examples: 1d, 3h, 2h30m, 50m

When using the output or outputex parameters, all output formats supported by Syhunt are available. The report or export will be saved to the current working directory, unless a full path name is provided.

Examples:

# Example 1 - Scan the current directory/repository
Start-CodeScan -pfcond "medium"

# Example 2 - Scan a remote GIT project
Start-CodeScan -target "https://github.com/someuser/somerepo.git" -huntmethod "normal" -pfcond "medium"

# Example 2 - Scan a remote Azure DevOps Services project
Start-CodeScan -target "https://dev.azure.com/user/projectname" -huntmethod "normal" -pfcond "medium"

# Example 4 - Scan a specific local directory
Start-CodeScan -target "C:\www\" -huntmethod "normal" -pfcond "medium"

Pass/Fail Conditions

The following are the pass/fail conditions currently supported by Syhunt:

• high or fail-if:risk=high - Fail if a High risk vulnerability or threat is found
• medium or fail-if:risk=mediumup - Fail if a Medium or High risk vulnerability or threat is found
• low or fail-if:risk=lowup - Fail if a Low, Medium or High risk vulnerability or threat is found

Integrating with BitBucket Issues

While CI integration with BitBucket pipeline is available, integration with BitBucket issues is expected to be added in a future release of Syhunt.

For additional product documentation, visit syhunt.com/docs