Skip to main content

Architecture Introduction

This document describes the secureCodeBox Project (SCB) and is based on the arc42 architecture documentation template. secureCodeBox is a Kubernetes based, modularized toolchain for continuous security scans of your software project. Its goal is to orchestrate and easily automate a bunch of security-testing tools out of the box. With secureCodeBox we provide a toolchain for continuous security scanning of applications or infrastructures to find the low-hanging fruit issues early in the development process and free the resources of the penetration tester to concentrate on the major security issues.

Road Map​

note

We should move the roadmap from the OWASP project site here and reference to this document.

Conventions Used in this Documentation​

Some words about the structure, tools and style guide to follow, if you plan to contribute to this architecture documentation. This section about convention is as brief as possible 🙃

Structure​

As mentioned above we use arc42 as template for this documentation. This means that the whole architecture documentation is structured into 12 chapters as described in the arc42 overview. The basic concept of arc42 is to provide a standardized structure to "put your knowledge" into. This does not necessarily mean that you must write something into each chapter. The basic idea is to fill the chapters as needed: If you have something important to say about the architecture, then fill the free space given by the template. Thus we have some empty parts. They will disappear over time.

info

We do not have the aspiration to have a complete and comprehensive architecture documentation. This documentation is meant to be a living document evolving over time. There is no restriction who can contribute to the architecture documentation: Everybody who notices wrong, outdated or missing information is invited to open pull requests.

caution

We do not add linebreaks to split lines longer than 80 characters. We write whole paragraphs as a single line because all editors support soft-wrap for long lines and it is tedious to reformat a whole paragraph on insertion/deletion of a single word.

Images and Diagrams​

For diagrams we us UML notation, if appropriate. This is a widely adopted industry standard and the most important concepts and syntax is widely understood. We try to use UML "the right" way, but we do not have the aspiration to draw perfect UML diagrams. The important part is that everyone understands the diagrams as easily as possibly. Therefore a diagram should always have a legend, unless the meaning of the "boxes and arrows" is obvious. Keep in mind: What is obvious for you, may be a mystery for someone else 😉.

As tool we use Draw.io with its default color scheme and as format we use editable PNG. The images are stored in the directory static/img/docs/architecture/.

The only exception to not use Draw.io is for sequence diagrams. This type of diagram is very tedious and time consuming to edit with mouse in a classical drawing tool. The reason is you end up in moving lifelines back and forth all the time when insert or remove something in the diagram. We use a text-based tool PlantUML to generate sequence diagrams because insertion or removal of ne lifelines is simply add or remove a line of text. The PlantUML files (*.puml) are stored also in static/img/docs/architecture/. There is a make target to generate the images. Simply invoke make to see a help with the available targets.

Style Guide​

This section describes how to markup text in this documentation:

  • Emphasise named things: Emphasis (usually formatted as itallic) is used for terms with special meaning. E.g. everything in the glossary is a good candidate. The rationale behind this rule is that readers easily recognize a term as something with special meaning in the context of secureCodeBox. For example the term parser has a lot of different meaning depending on the context this term is used. In the context of secureCodeBox a parser has very special and narrow meaning. So, the reader sees that this word has a special meaning.
  • Strong important things: Important things which should be recognized, even if a reader only skims over the text, should be marked up strong.
  • Use code for code: The inline code markup should only be used for things which can be copy pasted as-is into the described context. For example you write about the image directory (static/img/docs/architecture) you can markup it as code because you can simply copy and paste this into your terminal. Same applies if it is a command or code snippet. Do not use this to emphasize things.
  • "Quote direct speech or quotes": Usually developers tend to use single or double quotes in texts to emphasise things because we are used to this from the most programing languages, but here a prime school reminder: Quotes are for quoting someone or direct speech.