Skip to main content

YesWeHack x BugTracker

Simplify bug tracking with seamless integration between your systems

Updated yesterday

YesWeHack to Bug trackers (YWH2BT) synchronizes your vulnerability reports with issues of your bug tracker(s). It automatically retrieves reports you want to copy in your bug tracker, creates the related issue, and syncs further updates between issues and reports.
It comes with a handy GUI to set up and test the integration, while completely controlling the information you allow to be synchronized from both side.
It supports github, gitlab, jira/jiracloud and servicenow.

YesWeHack to Bug trackers (YWH2BT) embeds both the GUI to set up the integration, and the application to be scheduled on your server to periodically poll and synchronize new reports.
You can either run both on a single machine, or prepare the configuration file on a computer (with the GUI) and transfer it on the server and use it through a scheduled command.
Since data is pulled from the YesWeHack platform to your server, only regular outbound web connections need to be authorized on your server.

ℹ️ First, you will need to create a PAT.

You have two options:

  • Create a BugTracker PAT at the BU level. In this case, a single PAT can be used for all your programs.

  • Create a BugTracker PAT at the program level. In this case, each program will need its own PAT.

Learn how to create PAT here.

ℹ️ YesWeHack to BugTracker (YWH2BT) currently work with 4 Bug Trackers (BT):

  • Jira/JiraCloud

  • Gitlab

  • Github

  • ServiceNow

If your bug tracker isn’t supported by our YWH2BT tool, please contact [email protected] to explore integration options.

Download YWH2BT and install

Installation

Prerequisites

Install with pip

YWH2BT can be installed with pip, through the command:

pip install ywh2bt

Since the version 2.8.0, the default installation does not include the GUI anymore ; to include the GUI in the installation (The guide is based on the YWH2BT-GUI version), execute the command:

 pip install 'ywh2bt[gui]'

Or upgraded from a previously installed version:

pip install ywh2bt --upgrade

or

pip install 'ywh2bt[gui]' --upgrade

Install in Venv with poetry

Install poetry:

pip install poetry

Install ywh2bt with GUI (This guide is based on the YWH2BT-GUI version):

cd ywh2bugtracker 
poetry install --extras=gui

Or install ywh2bt headless:

cd ywh2bug tracker 
poetry install

Instead of running ywh2bt [command] or ywh2bt-gui, you can run poetry run ywh2bt [command] or poetry run ywh2bt-gui.

Associate your program with YWH2BT to your BT

  1. Issue creation is achieved upon first synchronization after ”Ask for integration” (AFI) Tracking
    Status is set:
    • When integrated, Tracking Status is automatically set to ”Tracked”;
    • Creation is possible whatever report status. It is however advised to set AFI status only after acceptance, since the report is from this point considered valid;
    • Subsequent returns to ”Ask for integration” status won’t create another issue.

  2. The types of comments synchronized depend on the configuration
    • You can decide what message you can synchronize or not with YesWeHack.

    (Go to the 'Configure your tracked program' section to learn more.)

Configure your BT

On the YWH2BT GUI:

  • Click on “new”

Jira

Create a Jira API token:

  • Go to your “Atlassian account”

  • Go to “Security” > “API token” > Create and manage API tokens

  • Click on “Create an API token”

  • Name the token

  • Click on “Create”

⚠️ Important: Make sure to copy the token. You won’t be able to see it again!

  • On YWH2BT, click on the “Jira icon”

In the new tab:

  • Key: The key for your YesWeHack-specific configuration.

  • API URL: Your Jira URL (example : https://my-company.atlassian.net ).

  • Login: Your Jira user email.

  • Password: Your token API generated from Jira not your Jira password.

  • Project slug: Your project name, where issue will be created.

  • Verify SSL: This option verifies that the server uses a valid certificate. We recommend keeping it enabled. For self-hosted Jira, you may need to disable verification.

  • Issue type: Type of the issue created. Commonly task are used.

  • Issue closed status: Status of the Jira issue when closed. Commonly set-up to Closed.

Gitlab

Create a GitLab API access token:

  • Go to your “GitLab account”

  • Go to “Preferences” > “User Settings” > “Access Tokens”

  • Name the “Token” and select the “API scope”

  • Click “Create personal access token”

⚠️ Important: Make sure to copy the token. You won’t be able to see it again!

  • On YWH2BT, click on the “Gitlab icon”

  • Key: The key for your YesWeHack-specific configuration.

  • API URL: GitLab API URL (if different from the default one).

  • API token: GitLab API access token previously created.

  • Project path: Path of the project on.

  • Verify TLS: Whether to verify if the API server’s TLS certificate is valid.

  • Confidential issues: Whether to mark created issues as confidential.

Github

Create a GitHub API access token:

  • Go to your “GitHub account”

  • In “Settings” > “Developer settings” > “Personal access tokens”, click on“Generate new token”

  • Name the token and select the scopes. If the repository in which you want to integrate the issues is:

    • Public: choose ”Access public repositories” (public_repo) scope

    • Private: choose ”Full control of private repositories” (repo) scope

  • Click ”Generate token”

⚠️ Important: Make sure to copy the token. You won’t be able to see it again!

On YWH2BT, click on the “Github icon”

  • Key: a unique name identifying this integration.
    This will be used when configuring YesWeHack integration.

  • API URL: GitHub API URL (if different from the default one).

  • API token: GitHub API access token previously created.

  • Project path: Path of the github’s project (e.g., for the project located at GitHub - yeswehack/ywh2bugtracker: YesWeHack BugTracker, the path is yeswehack/ywh2bugtracker).

  • Verify TLS: Whether to verify if the API server’s TLS certificate is valid.

  • Use CDN: When activated, this option allows upload of file attachments using a workaround because GitHub API does not natively provide a functionality to upload attachments on issues.

  • Login: GitHub account login. Only used when “Use CDN” is activated.

  • Password: GitHub account password. Only used when “Use CDN” is activated.

Known limitations

When ”Use CDN” is activated, the GitHub account associated with the ”Login” cannot have the two-factor authentication enabled.

ServiceNow

Create a new user in your ServiceNow instance:

  • In “User Administration” > “Users”, click the “New button”

Fill in the details about the new user, providing at least: “User ID” & “Password”
It is strongly recommended to check Web service access only in order to prevent the
user from accessing the ServiceNow UI.

  • Click the “Submit” button to create the user

  • In order to read and modify the Additional Comments on the ServiceNow incidents, users must be granted a specific role that allows access controls on the sys_journal_field table:

    • In “System Definition” > “Tables”, open “Journal Entry” / sys_journal_field

    • Select the “Controls” tab

    • Check “Create access controls”

    • In the “User role” field, enter u_journal_entry_user or leave the default value

    • Click the “Update” button

    • Apply the user roles to the user:

      • In “User Administration” > “Users”, open the user you created earlier

      • Select the “Roles” tab

      • Click the “Edit” button

      • Move the following items from the list on the left to the list on the right:

        • snc_platform_rest_api_access : allows access to Platform Rest APIs

        • sn_incident_read : read access to the Incident Management Application and related functions

        • sn_incident_write : write access to the Incident Management Application and related functions

        • u_journal_entry_user (or the role you defined earlier): allows access to the sys_journal_field table

  • Click the “Save” button to save the roles

  • Click the “Update” button to update the user

On YWH2BT click on the "ServiceNow" icon

  • Key: A unique name identifying this integration.

  • Instance host: ServiceNow instance host (e.g., ywh2bt.service-now.com ).

  • Login: ServiceNow user login.

  • Password: ServiceNow user password.

  • Use SSL: Whether to use SSL connection with the server.

  • Verify TLS: Whether to verify if the API server’s TLS certificate is valid.

Specific behavior

When the feedback option “Issue closed to report AFV of YesWeHack integration” is activated, the report status will be set to AFV only if the ServiceNow incident is set to Closed, not Resolved.

Track 1 program

Run ywh2bt[gui]

Prerequisites - Prepare your report to be track

In order to track a report, it must be in the "Ask For Integration" status.
To do this, when a hunter submits a bug bounty report, go to the right-hand panel and click "Edit" next to "Tracking status".

In the opened modal select “Ask for integration”, write a message (optional) then click on “Update”.

Set up YesWeHack tracker

Configure your PAT

On YWH2BT, click on the “YesWeHack” icon.

In the new tab :

  • Key: The key for your YesWeHack-specific configuration.
    If you choose to use a PAT at the program level, you will need to create multiple configurations — therefore, naming this key properly will be important.

  • API Url: Keep https://api.yeswehack.com.

  • Personal Access Token: The PAT for this configuration.

  • Verify TLS: Verifies that the server uses a valid certificate. We recommend keeping it enabled.

Then click on the “+” next to “Programs”.

Configure your tracked program

In the extended tab:

  • Program slug: Slug of the program that you want to track.

ℹ️ You can get your slug from the details page of a program from the YesWeHack platform.
For example: https://yeswehack.com/business-units/yeswehack/programs/my-program-slug/details

  • Synchronization options: Updates pushed from reports to issues.

  • Feedback options: Updates pushed from issues to reports.

  • Bug trackers: Link the bugtracker(s)'s configuration previously made with its“Key” (From our Jira step you should use “jira_configuration_1”). You can link as many configuration as you want to your YesWeHack configuration, but you can’t select different option without recreating a new YesWeHack’s configuration.

  • Click on the “Test” button

If your configuration is valid you should see this message:

You can now synchronize with the sync button:

ℹ️ Do not forget to save your configuration from File > Save as [...]

Track 2 or more programs with a PAT Business Unit Bug Tracker (BU Level)

After creating your first configuration in step "Track 1 program", click the '+' button at the end of the 'Programs' line.

Then configure your new program as described in section 'Configure Your Tracked Program'.

ℹ️ You can use the same Bug trackers configuration as your first program, or use a new one.

Track 2 or more programs with a PAT Program Bug Tracker (Program level)

After creating your first configuration in step "Track 1 program", click on the “YesWeHack” icon at the end on the YesWeHack line.

Repeat the step "Track 1 program".

Command line

Synchronize

Since synchronization is not automatic, if you want to regularly sync your reports, we recommend setting up a cron job and using the YWH2BT CLI.

From the saved conf file to run a synchronization you can simply run:

ywh2bt sync --config-file my_conf.yml

Convert file between json and yaml

You can use both json or yaml file to run ywh2bt. You can simply convert from one format to another with:

ywh2bt convert --config-file=conf.yml --config-format=yaml --destination-file=config.json --destination-format=json

Validate your conf

You can test the validity of your file with:

ywh2bt validate \
 --config -file=my -config.yml \
 --config -format=yaml && echo OK 

OK

Test your conf

You can test that all element in your conf work well with:

ywh2bt test --config-file conf.yml
Related Articles
Sign up on YesWeHack
API Personal Access Tokens
Did this answer your question?