ywh2bt - YesWeHack to Bug Tracker
Project description
ywh2bt
ywh2bt is a tool to integrate your bug tracking system(s) with YesWeHack platform. It automatically creates issues in your bug tracking system for all your program's report, and add to the concerned reports the link to the issue.
Table of contents
- Features
- Requirements
- Installation
- GUI
- Command line
- Supported configuration file formats
- Known limitations and specific behaviours
- Changelog
- Local development
Features
- synchronization from YesWeHack platform to trackers:
- platform reports to tracker issues
- reports logs/comments to issues comments
- creation, modification, synchronization, validation, conversion of configuration files through a GUI
- validation of configuration files
- format conversion of configuration files
Supported trackers
- github
- gitlab
- jira / jiracloud
Requirements
python
>= 3.7,<=3.9pip
To use it on your program, while maintaining the maximum security, the tool requires:
- a specific right on the YesWeHack platform allowing you to use the API, and a custom HTTP header to put in your configuration. Both of them can be obtained by e-mailing us at support@yeswehack.com.
- creation of a user with role "program consumer" on the desired program. It is the credentials of this user that you must use in the configuration.
Installation
pip install ywh2bt
GUI
The GUI provides assistance to create, modify and validate/test configurations. It also allows synchronization with bug trackers.
To run it, simply type ywh2bt-gui
in a shell.
Usage
- Changes to the configuration can be made either in the configuration tab or in the "Raw" tab ; changes made in one tab are automatically reflected in the other tab.
- Hovering labels and buttons with the mouse pointer often reveals more information in a floating tooltip or in the status bar.
- A description of the schema of the configuration files is accessible via the "Help > Schema documentation" menu or by clicking on the button in the main toolbar.
Screenshots
- example.yml configuration:
Command line
ywh2bt
Main script used to execute synchronization, validate and test configurations.
Usage: ywh2bt [command]
. See ywh2bt -h
or ywh2bt [command] -h
for detailed help.
Commands
validate
: validate a configuration file (mandatory fields, data types, ...)test
: test the connection to the trackersconvert
: convert a configuration file into another formatsynchronize
(aliassync
): synchronize trackers with YesWeHack reportsschema
: dump a schema of the structure of the configuration files in Json-Schema, markdown or plaintext
Example usages
Validation:
$ ywh2bt validate \
--config-file=my-config.yml \
--config-format=yaml && echo OK
OK
Conversion (yaml
to json
):
$ ywh2bt convert \
--config-file=my-config.yml \
--config-format=yaml \
--destination-file=/tmp/cfg.json \
--destination-format=json
Synchronization:
$ ywh2bt synchronize --config-file=my-config.json --config-format=json
[2020-12-21 10:20:58.881315] Starting synchronization:
[2020-12-21 10:20:58.881608] Processing YesWeHack "yeswehack1":
[2020-12-21 10:20:58.881627] Fetching reports for program "my-program": 2 report(s)
[2020-12-21 10:21:08.341460] Processing report #123 (CVE-2017-11882 on program) with "my-github": https://github.com/user/project/issues/420 (untouched ; 0 comment(s) added) | tracking status unchanged
[2020-12-21 10:21:09.656178] Processing report #96 (I found a bug) with "my-github": https://github.com/user/project/issues/987 (created ; 3 comment(s) added) | tracking status updated
[2020-12-21 10:21:10.773688] Synchronization done.
Supported configuration file formats
yaml
(legacy)json
Use ywh2bt schema -f json
to obtain a Json-Schema describing the format.
Both yaml
and json
configuration files should conform to the schema.
Known limitations and specific behaviours
- Apps API doesn't require TOTP authentication, even if corresponding user has TOTP enabled.
However, on a secured program, information is limited for user with TOTP disabled, even in apps.
As a consequence, to allow proper bug tracking integration on a secured program, program consumer must have TOTP enabled and, in BTI configuration TOTP must be set tofalse
. - References to a same uploaded attachment in different comments is not supported yet, i.e., if an attachment is referenced (either displayed inline or as a link) in several comments, only first one will be correctly handled.
- Manually tracked reports (i.e., where a manager directly set the Tracking status to "tracked") are also integrated in the tracker the way they are when a manager set "Ask for integration".
- Since v2.0.0, unlike in previous versions, setting a tracked report back to "Ask for integration" won't create a new issue in the tracker but update the existing one.
Changelog
- v0.* to v2.0.0:
- behavior changes:
- reports logs can selectively be synchronized with the trackers:
- public comments
- private comments
- report details changes
- report status changes
- rewards
- a program can now only be synchronized with 1 tracker
- reports logs can selectively be synchronized with the trackers:
- added support for JSON configuration files
- removed
ywh-bugtracker
command (useywh2bt synchronize
) - added
ywh2bt
command:- added
ywh2bt synchronize
:- note:
ywh2bt synchronize --config-file FILE --config-format FORMAT
is the equivalent ofywh-bugtracker -n -f FILE
in v0.*
- note:
- added
ywh2bt validate
- added
ywh2bt test
- added
ywh2bt convert
- added
ywh2bt schema
- added
- removed command line interactive mode
- added GUI via
ywh2bt-gui
command
- behavior changes:
Local development
Requirements
poetry
(pip install poetry
)
Installation
make install
(orpoetry install
): creates a virtualenv and install dependencies
Usage
Instead of ywh2bt [command]
, run commands using poetry run ywh2bt [command]
.
Same goes for ywh2bt-gui
, run poetry run ywh2bt-gui
instead.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.