Please follow the quickstart to get Web Security Map on your system.
Additionally the Docker page could be very helpful.
A normal change to the software¶
This is an illustration to show a normal development practices.
We use git, which comes with many pitfalls. Just search your answer on stack exchange first and ask in the group later.
Make sure Web Security Map is up and running, by following the getting started instructions. Then make a branch that describes what you are doing. For example:
git branch documentation_upgrade
Then make any changes to the source code. You’ll see that the devserver automatically restarts after every save.
Once you’re happy with your changes, and you’ve tested it on your environment using a meaningful dataset (eg productiondata), then you can verify (and autofix) the code to our code standards:
tox -e autofix
Fix any of the remarks it gives, otherwise your changes will not be added to the master branch.
You can only commit files to the master branch if you’re up to date with it’s code:
git pull --rebase origin master
Follow the instructions on screen to fix merge conflicts if any.
When you are happy, review your changes and remove any temporary files using the instructions given:
If you like the files that are changed, add all changes to be merged:
git add -A
Then commit them:
git commit -m "a short description why you changed something"
Then push them to the server:
The push command will give you a link to file a merge request. Meanwhile the build servers are checking your code before merging.
Follow the merge request link to create the actual merge request. Share it on the chat.websecuritymap.org channel for review and feedback.
Once the feedback is processed (if needed at all) you can merge the code. If you can’t, other members of the project can. So ask.
The web security map command won’t start and i get some weird errors…?¶
Make sure you’ve got an up to date development environment. You can do so by running the following commands:
Rebuild the environment:
Get all requirements and development requirements:
pip install -r requirements.txt pip install -r requirements.dev.txt
Code quality / Testing¶
This project sticks to default pycodestyle/pyflakes configuration to maintain code quality.
To run code quality checks and unit tests run:
For a comprehensive test run:
tox -e check,test,datasets
To make life easier you can use
isort before running
tox to automatically fix most style issues:
tox -e autofix
To run only a specific test use:
tox -e test -- -k test_name
To only run a specific test suite use for example:
.tox/default/bin/websecmap test tests/scanners/test_dummy.py
A coverage report is generated after running tests, on OSX it can be viewed using:
Pytest allows to drop into Python debugger when a tests fails. To enable run:
tox -- --pdb
Besides quality checks and unit tests there are also integration and system testing frameworks available.
These frameworks will run in the CI system but not by default when running
tox due to their dependencies.
To run these testsuites make sure Docker is installed and running and run either:
tox -e integration
tox -e system
Direnv / Virtualenv¶
This project has direnv configuration to automatically manage the Python
virtual environment. Install direnv and run
direnv allow to enable it initially. After this the environment will by automatically loaded/unloaded every time you enter/leave the project directory.
If you don’t want to use Direnv be sure to source the
.envrc file manually every time you want to work on the project: