Contributing

All contributions are welcome!

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

You can visit the development board here.

Issues

We’d love you to open issues, if they’re relevant to this repository: feature requests, bug reports, etc. are all welcome.

In particular, if you have a large PR you want to send our way, it may make sense to open an issue to discuss it with the maintainers first.

Submitting a pull request

  1. Fork and clone the repository

  2. Make your changes

  3. Push to your fork and submit a pull request

  4. Pat your self on the back and wait for your pull request to be reviewed and merged.

Here are a few things you can do that will increase the likelihood of your pull request being accepted:

  • Install and use pre-commit to follow the same code style and conventions.

  • Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.

  • Write a good commit message, please use conventional commits

Work in Progress pull request are also welcome to get feedback early on, or if there is something blocked you. Please open such pull requests as Draft.

Development setup

For a development setup follow these steps:

  1. Create a virtual environment:

python3 -m venv path/to/myvenv

  1. Active the newly created virtual environment:

source path/to/myvenv/bin/activate

  1. Install ssltest package, the -e option allows for hot reload of your code

pip install -e .

  1. Nmap is required for some functions of the script (--ns/--nmap-scan and --nd/--nmap-discover), install on debian-like distros with:

apt-get install -y nmap

  1. To get out of your venv use:

deactivate

Contribute a new vulnerability test

In order to create a vulnerability test some conditions have to be met:

  1. The test class has to inherit from the VulnerablityTest class and implement required abstract methods and call the super constructor (super().__init__).

  2. The test method has to be implemented and has to return either a bool or a tuple(bool, str). The string in the tuple return variant is a note to the test result and will be displayed in the tool output.

  3. The variable valid_protocols has to be set to a list of SSL/TLS protocols you want the test to run on.

  4. Static variables name, short_name and description have to be defined.

  5. Test class has to be in ssltest/scan_vulnerabilities/tests.

  6. The doc of the file that hosts the test class has to start with this string Vulnerability test for.

Template vulnerability test class can be found in ssltest/scan_vulnerabilities/tests/TestTemplate.py

Other useful tools for implementing tests

  • The variable test_once can be set to False to run the test on multiple protocol versions in parallel. Protocols are chosen based on the intersection of valid_protocols and supported_protocols lists.

  • If the variable test_once is set to True the test will be run on the first available protocol version from the valid_protocols lists.

  • The method run_once() can be implemented in case the test_once variable is set to False to run some code before the parallel run of tests on multiple protocols (e.g. Drown).

  • The ClientHello class can be used to create the initial client hello message, where every client hello field can be customized such as cipher suites or TLS extensions.

  • The SafeSocket is the recommended way to send data, check other tests for example on how to use it.

  • The CipherSuiteTest class can be used to create a simplified vulnerability test where it is filtering cipher suites based on a regex string and checks if the server supports these filtered cipher suites. Set this regex string with the self.filter_regex variable. Check the Freak class for an example.

Updating CHANGELOG.md

If you are making adding a new feature, fixing a bug, changing something or removing something make an entry in the CHANGELOG.md file so that it can be used in future while creating a new release. Usefull tips on how to write additions to the changelog can be found here.

Release process

The release process is using semantic versioning 2.0.0 and is automated using GitHub actions. Whenever a new tag is pushed a new release will be created on GitHub and on pypi.