secureCodeBox · Weltraumschaf · Mar 21, 2022 · Mar 17, 2022 · Mar 17, 2022 · Mar 17, 2022
diff --git a/.gitignore b/.gitignore
@@ -59,7 +59,7 @@ yarn-error.log*
 src/integrations.js
 docs/scanners/*.md
 docs/hooks/*.md
-docs/architecture/adr/*.md
+docs/architecture/10_adr/*.md
 docs/guides/
 static/findings
 

diff --git a/README.md b/README.md
@@ -109,7 +109,7 @@ Recommended websites for free icons or images:
 
 Since we work with various different tools, it is even more important to keep a clean and well structured Documentation. Our website's purpose is to provide a comfortable navigation and clear overview. But since no one is going to update the documentation if it's untraceable, it is also very important to keep the documentation's location clear and as less spread as possible throughout our project. So no single-page documentation hidden in the deep structure of a remote repository! In general we keep specific documentation in the respective directory (e.g. the Amass documentation is a README.md in the Amass directory). Documentation can also be housed in this repository, if it is not specifically categorized to something, but follows the guidelines of the documentation build scripts. One key feature our documentations share in order to be put on the website is a frontmatter in each documentation. It is mandatory since at least a title (and for integrations also a description) are required. But it also can provide helpful other information very easily, for a documentation see [frontmatter]. Don't be afraid to use it for including important information, which you can't get/provide otherwise very well, but don't overuse it! For more detailed examples see the following sections.
 
-### Adding a scanner or hook
+### Adding a Scanner or Hook
 
 Scanners and hooks are referred to as integrations. Scanners, which are integrated into our [secureCodeBox] repository have their own directories (located at [/scanners/](https://github.com/secureCodeBox/secureCodeBox/tree/master/scanners)) in which the main documentation must be written in a `README.md` file. Hooks have their own respective directory of similar structure. But in general the documentation is build programmatically, so for further information have a look at the respective build script (`scripts/`).
 
@@ -173,7 +173,7 @@ Currently under development, this will be the guide for our "Docs" developer doc
 
 Since we want to have our documentation in the main repository available on this site as well, we use some custom scripts to build the documentation structure in the `docs/` folder, afterwards creating programmatically the sidebar and also provide the frontmatter information of integrations to the frontend. These scripts are located at the `scripts/` folder. Each script can be called and work independently from one another. The respective commands are defined in the `package.json` and chained together by a pre-hook to the general build command. If you want to add a new script it should be kept as an individually executable script and follow our naming convention: `<whatItCreatesOrMutates>.<generalOperation>.js`. The configuration for all scripts can be found at `scripts/utils/config.js`. Though our frontend is built in TypeScript, those scripts remain in JavaScript currently.
 
-### Docs builder
+### Docs Builder
 
 The docs builder script is responsible to retrieve and generate specified folder and files, containing documentation and works as follows:
 
@@ -212,7 +212,7 @@ sizeLimit: number, // Limit of file size, most importantly used for large findin
 findingsDir: string, // Directory for large findings which exceeded sizeLimit
 ```
 
-### Sidebar builder
+### Sidebar Builder
 
 The sidebar script iterates through the entire `docs/` folder and work as follows:
 
@@ -269,10 +269,22 @@ defaultIcon: string, // Default Icon when no imageUrl provided or could not reso
 
 All changes pushed to the `master` branch get automatically build by [Netlify]. This also means that the `npm run build` command is executed, thus executing our custom build scripts through a pre-hook.
 
+# Architecture Documentation
+
+The architecture documentation is located under `docs/architecture/`.
+
+## Architecture Diagrams
+
+The PNG files are made with [Draw.io][draw.io]. They contain the metadata for Draw.io, so you can simply open the file in Draw.io. **It's important that you save the files as _editable bitmap image_**.
+
+Files ending with `.puml` are made with [PlantUML][plantuml]. Here we commit the text file **and** the generated PNG file. 
+
 [securecodebox.io]: https://securecodebox.github.io
-[securecodebox]: https://github.com/secureCodeBox/secureCodeBox
-[docusaurus]: https://v2.docusaurus.io/
-[netlify]: https://www.netlify.com/
-[node.js and npm]: https://nodejs.org/en/download/
-[nvm]: https://github.com/nvm-sh/nvm
-[frontmatter]: https://v2.docusaurus.io/docs/markdown-features/#markdown-headers
+[securecodebox]:    https://github.com/secureCodeBox/secureCodeBox
+[docusaurus]:       https://v2.docusaurus.io/
+[netlify]:          https://www.netlify.com/
+[node.js and npm]:  https://nodejs.org/en/download/
+[nvm]:              https://github.com/nvm-sh/nvm
+[frontmatter]:      https://v2.docusaurus.io/docs/markdown-features/#markdown-headers
+[draw.io]:          https://app.diagrams.net/
+[plantuml]:         https://plantuml.com/
diff --git a/docs/architecture/introduction.md → ...architecture/01_introduction_and_goals.md b/docs/architecture/introduction.md → ...architecture/01_introduction_and_goals.md
@@ -3,14 +3,13 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-title: "Architecture Introduction"
-sidebar_label: "Introduction"
+title: "Introduction and Goals"
+sidebar_label: "Introduction and Goals"
 sidebar_position: 1
 ---
+# Introduction and Goals {#section-introduction-and-goals}
 
-This document describes the secureCodeBox Project (SCB) and is based on the [arc42](https://arc42.org/overview/) 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 scanning of applications 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.
-
-Initially, the goal of secureCodeBox was to provide a tool for easy integrating security test tools into your CI/CD pipeline to run against your web project. Some years ago we asked ourselves: Why only scan a single project? So a great idea was born: Consider the whole company as a project. Additionally, secureCodeBox can aid penetration testers in the recon and discovery phase of a security assessment. The purpose of secureCodeBox is not to replace the penetration testers or make them obsolete. We strongly recommend to run extensive tests by experienced penetration testers on all your applications.
+Initially, the goal of _secureCodeBox_ was to provide a tool for easy integrating security test tools into your CI/CD pipeline to run against your web project. Some years ago we asked ourselves: Why only scan a single project? So a great idea was born: Consider the whole company as a project. Additionally, _secureCodeBox_ can aid penetration testers in the recon and discovery phase of a security assessment. The purpose of _secureCodeBox_ is not to replace the penetration testers or make them obsolete. We strongly recommend running extensive tests by experienced penetration testers on all your applications.
 
 The following goals have been established for this project:
 
@@ -22,18 +21,19 @@ The following goals have been established for this project:
 | 4            | The findings are displayed in a navigable way with least amount of duplication.                                   |
 | 5            | SecureCodeBox starts new relevant scans in an agile way, based on previous findings.                              |
 
-## Requirements
+## Requirements Overview {#_requirements_overview}
 
-![Use-case diagram](/img/architecture/UseCaseDiagramSCB.png)
+![Use-case diagram](/img/docs/architecture/use-case-diagram.png)
 
 | **Id** | **Requirement**             | **Explanation**                                                    |
 |--------|-----------------------------|--------------------------------------------------------------------|
 | UC1    | Initiate scans              | Initiating scans in parallel and orchestrating them.               |
-| UC1.1  | Initiating subsequent scans | Initiate scans based on pervious results, through cascading rules. |
+| UC1.1  | Initiating subsequent scans | Initiate scans based on previous results, through cascading rules. |
 | UC2    | Parse findings              | Parse findings in a human readable and friendly way.               |
 
-## Quality Goals
-Below, the most important qualities are described that this project strives for. The qualities are categorized using the [ISO 25010](https://iso25000.com/index.php/en/iso-25000-standards/iso-25010) standard. Most of these qualities are derived from [this](https://docs.securecodebox.io/blog/2021/07/20/the-architecture-of-securecodebox-v2) blog post. For the entire list of quality-goals see [Quality Requirements](./functional/quality-requirements)
+## Quality Goals {#_quality_goals}
+
+Below, the most important qualities are described that this project strives for. The qualities are categorized using the [ISO 25010][iso-25010] standard. Most of these qualities are derived from blog post [The Architecture of secureCodeBox v2][blog-architecture]. For the entire list of quality-goals see [Quality Requirements](/docs/architecture/quality_requirements).
 
 | **Category**           | **Quality**          | **Description**                                                      | **Scenario** |
 |------------------------|----------------------|----------------------------------------------------------------------|--------------|
@@ -55,10 +55,10 @@ Below, the most important qualities are described that this project strives for.
 | SC3    | SCB is out of resources and a new scan is initiated. The scan is queued until resources are available |
 | SC4    | A scan is easily created and started by writing and loading a config file                             |
 
-## Stakeholders
+## Stakeholders {#_stakeholders}
 
 | **Company** | **Name**          | **Role**                 | **GitHub Account**                                 | **Expectations** |
-| ----------- | ----------------- | ------------------------ | -------------------------------------------------- | ---------------- |
+|-------------|-------------------|--------------------------|----------------------------------------------------|------------------|
 | iteratec    | Robert Seedorff   | Product Owner            | [@rseerdorff](https://github.com/rseedorff)        |                  |
 |             | Sven Strittmatter | Scrum Master & Developer | [@Weltraumschaf](https://github.com/Weltraumschaf) |                  |
 |             | Jannik Hollenbach | Core Developer           | [@J12934](https://github.com/J12934)               |                  |
@@ -70,37 +70,5 @@ Below, the most important qualities are described that this project strives for.
 |             | Jop Zitman        |                          | [@EndPositive](https://github.com/EndPositive)     |                  |
 |             | Stijn van Es      | Developer                | [@Stijn-FE](https://github.com/Stijn-FE)           | Contributes      |
 
-
-## Architecture constraints
-
-| **Constraint** | **Description** |
-|----------------|-----------------|
-|                |                 |
-
-> Following...
-
-# Context & Scope
-
-SCB is an orchestration platform managing scan jobs and parsing results. The aim of this project is to make automated vulnerability scanning easy and efficient. The diagrams below, illustrate the external factors and the context in which SCB is used.
-
-SCB only manages the scan tasks. The scanning functionality itself is considered out of scope and for this, third-party software is used.
-
-## Business
-
-![Business context diagram](/img/architecture/BusinessContextDiagram.png)
-
-## Technical
-
-![Technical context diagram](/img/architecture/TechnicalContextDiagram.png)
-
-# Solution Strategy
-
-| **Goal/Requirement** | **Architectural Approach** | **Details** |
-|----------------------|----------------------------|-------------|
-|
-
-> Following...
-
-## Road Map
-
-> Following...
+[iso-25010]:          https://iso25000.com/index.php/en/iso-25000-standards/iso-25010
+[blog-architecture]:  https://www.securecodebox.io/blog/2021/07/20/the-architecture-of-securecodebox-v2
diff --git a/docs/architecture/02_architecture_constraints.md b/docs/architecture/02_architecture_constraints.md
@@ -0,0 +1,16 @@
+---
+# SPDX-FileCopyrightText: the secureCodeBox authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+title: "Architecture Constraints"
+sidebar_label: "Architecture Constraints"
+sidebar_position: 2
+---
+# Architecture Constraints {#section-architecture-constraints}
+
+:::note
+Not documented yet.
+:::
+
+<!-- TODO #41: Here we could write about the constraint that we run only on K8s. -->
diff --git a/docs/architecture/03_system_scope_and_context.md b/docs/architecture/03_system_scope_and_context.md
@@ -0,0 +1,28 @@
+---
+# SPDX-FileCopyrightText: the secureCodeBox authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+title: "System Scope and Context"
+sidebar_label: "System Scope and Context"
+sidebar_position: 3
+---
+# System Scope and Context {#section-system-scope-and-context}
+
+SCB is an orchestration platform managing scan jobs and parsing results. The aim of this project is to make automated vulnerability scanning easy and efficient. The diagrams below, illustrate the external factors and the context in which SCB is used.
+
+SCB only manages the scan tasks. The scanning functionality itself is considered out of scope and for this, third-party software is used.
+
+## Business Context {#_business_context}
+
+![Business context diagram](/img/docs/architecture/business-context-diagram.png)
+
+<!-- **optionally: Explanation of external domain interfaces** -->
+
+## Technical Context {#_technical_context}
+
+![Technical context diagram](/img/docs/architecture/technical-context-diagram.png)
+
+<!-- **optionally: Explanation of technical interfaces** -->
+
+<!-- **Mapping Input/Output to Channels** -->
diff --git a/docs/architecture/04_solution_strategy.md b/docs/architecture/04_solution_strategy.md
@@ -0,0 +1,14 @@
+---
+# SPDX-FileCopyrightText: the secureCodeBox authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+title: "Solution Strategy"
+sidebar_label: "Solution Strategy"
+sidebar_position: 4
+---
+# Solution Strategy {#section-solution-strategy}
+
+:::note
+Not defined yet.
+:::
diff --git a/docs/architecture/05_building_block_view.md b/docs/architecture/05_building_block_view.md
@@ -0,0 +1,90 @@
+---
+# SPDX-FileCopyrightText: the secureCodeBox authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+title: "Building Block View "
+sidebar_label: "Building Block View "
+sidebar_position: 5
+---
+# Building Block View {#section-building-block-view}
+
+Below, an overview is given of the global design/architecture of secureCodeBox. This document is inspired by the [C4][C4] model for visualizing software architecture. Conform this model, this document is split in 4 parts (i.e. levels). First, a _context_ level overview, displaying the context in which the application is used. The second level, _containers_, broadly describes the different data streams. The third level consists of a _components_ overview, describing the different components and the interactions between them. The fourth and final level contains a _code_ overview. Which will consist of class- and database-diagrams.
+
+## Whitebox Overall System {#_whitebox_overall_system}
+
+***Overview Diagram***
+
+![Technical context diagram](/img/docs/architecture/technical-context-diagram.png)
+
+Motivation
+
+:   *text explanation*
+
+Contained Building Blocks
+
+:   *Description of contained building block (black boxes)*
+
+Important Interfaces
+
+:   *Description of important interfaces*
+
+### Name black box 1 {#__name_black_box_1}
+
+*Purpose/Responsibility*
+
+*Interface(s)*
+
+*(Optional) Quality/Performance Characteristics*
+
+*(Optional) Directory/File Location*
+
+*(Optional) Fulfilled Requirements*
+
+*(optional) Open Issues/Problems/Risks*
+
+### Name black box 2 {#__name_black_box_2}
+
+*black box template*
+
+### Name black box n {#__name_black_box_n}
+
+*black box template*
+
+### Name interface 1 {#__name_interface_1}
+
+...
+
+### Name interface m {#__name_interface_m}
+
+## Level 2 {#_level_2}
+
+### White Box *building block 1* {#_white_box_emphasis_building_block_1_emphasis}
+
+*white box template*
+
+### White Box *building block 2* {#_white_box_emphasis_building_block_2_emphasis}
+
+*white box template*
+
+...
+
+### White Box *building block m* {#_white_box_emphasis_building_block_m_emphasis}
+
+*white box template*
+
+## Level 3 {#_level_3}
+
+### White Box _building block x.1_ {#_white_box_building_block_x_1}
+
+*white box template*
+
+### White Box _building block x.2_ {#_white_box_building_block_x_2}
+
+*white box template*
+
+### White Box _building block y.1_ {#_white_box_building_block_y_1}
+
+*white box template*
+
+C4: https://c4model.com/
diff --git a/docs/architecture/06_runtime_view.md b/docs/architecture/06_runtime_view.md
@@ -0,0 +1,16 @@
+---
+# SPDX-FileCopyrightText: the secureCodeBox authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+title: "Runtime View"
+sidebar_label: "Runtime View"
+sidebar_position: 6
+---
+# Runtime View {#section-runtime-view}
+
+This section describes the runtime view of _secureCodeBox_.
+
+## Runtime Scenario 1 {#__runtime_scenario_1}
+
+![Runtime view diagram](/img/docs/architecture/kubernetes-diagram.png)
diff --git a/docs/architecture/07_deployment_view.md b/docs/architecture/07_deployment_view.md
@@ -0,0 +1,36 @@
+---
+# SPDX-FileCopyrightText: the secureCodeBox authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+title: "Deployment View"
+sidebar_label: "Deployment View"
+sidebar_position: 7
+---
+# Deployment View {#section-deployment-view}
+
+This section describes the deployment of _secureCodeBox_.
+
+## Cluster Internal Central Scans {#_cluster_internal_central_scans}
+
+Cluster internal security scans with one dedicated namespace.
+
+***Overview Diagram***
+
+![Cluster internal central scans diagram](/img/docs/architecture/deployment-cluster-internal-central-scans.png)
+
+### Motivation
+
+The motivation behind this scenario is to have one central point to accumulate all findings of all scanned namespaces. Typically, this scenario is for a team which want to monitor a whole landscape of applications and services (e.g. a SOC team). 
+
+## Cluster/Namespace Internal {#_cluster_namespace_internal}
+
+Cluster internal security scans directly in the business service's namespace.
+
+### Motivation
+
+The motivation behind this scenario is to provide each development team its own "instance" of _secureCodeBox_. The common parts like _operator_ is shared, but each team deploys its own _scans_ inside their namespace. Typically, you will use this scenario if you do not want to allow that a team can see the findings of other teams. 
+
+***Overview Diagram***
+
+![Cluster internal central scans diagram](/img/docs/architecture/deployment-cluster-namespace-internal.png)
diff --git a/docs/architecture/08_concepts.md b/docs/architecture/08_concepts.md
@@ -0,0 +1,20 @@
+---
+# SPDX-FileCopyrightText: the secureCodeBox authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+title: "Cross-cutting Concepts"
+sidebar_label: "Cross-cutting Concepts"
+sidebar_position: 8
+---
+# Cross-cutting Concepts {#section-concepts}
+
+This section describes the cross-cutting concepts of _secureCodeBox_. These are concepts which affect all components. Instead of concepts only affecting a single or some components. They are described here particularly because they are not easy exchangeable with something differently. In fact, they are strong coupled dependencies, and therefore must be chosen carefully. 
-This section describes the cross-cutting concepts of _secureCodeBox_. These are concepts which affect all components. Instead of concepts only affecting a single or some components. They are described here particularly because they are not easy exchangeable with something differently. In fact, they are strong coupled dependencies, and therefore must be chosen carefully. 
+This section describes the cross-cutting concepts of _secureCodeBox_. These are concepts which affect all components, instead of only affecting a single or some components. They are described here particularly because they are not easy exchangeable with something different. In fact, they are strong coupled dependencies, and therefore must be chosen carefully. 
-This section describes the cross-cutting concepts of _secureCodeBox_. These are concepts which affect all components. Instead of concepts only affecting a single or some components. They are described here particularly because they are not easy exchangeable with something differently. In fact, they are strong coupled dependencies, and therefore must be chosen carefully. 
+This section describes the cross-cutting concepts of _secureCodeBox_. These are concepts which affect all components, instead of only affecting a single or some components. They are described here particularly because they are not easy exchangeable with something different. In fact, they are strong coupled dependencies, and therefore must be chosen carefully. 
+
+## Custom Resources {#_custom_resources}
+
+:::note
+Not documented yet.
+:::
+<!-- TODO: https://github.com/secureCodeBox/documentation/issues/236 -->
+