diff --git a/INSTALL.md b/INSTALL.md
index 6ac79ccc..4d36394f 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -1,39 +1,131 @@
-# Install DSOMM
-The DSOMM application is frontend only. Data is only stored in server side YAML files, and in the localStorage im the user's browser.
+
+DSOMM - DevSecOps Maturity Model
-The application can be deployed in many ways. using a number of Docker, Amazon AWS and a standalone Angular service.
+# DSOMM – DevSecOps Maturity Model
-## Get the Activities
+The **DevSecOps Maturity Model (DSOMM)** is a framework designed to help organizations assess, prioritize, and continuously improve security practices within their software development and delivery lifecycle.
-The _DSOMM activities_ are maintained in a separate GitHub repository. For the latest version, get it from:
-- https://github.com/devsecopsmaturitymodel/DevSecOps-MaturityModel-data
+DSOMM is an open project of the **OWASP Foundation**, developed to provide practical, implementation-focused guidance for modern DevOps environments.
+
-## Docker
-1. Install [Docker](https://www.docker.com)
-1. Download and run DSOMM: \
- `docker pull wurstbrot/dsomm:latest` \
- `docker run --rm -p 8080:8080 wurstbrot/dsomm:latest`
-1. Open DSOMM on http://localhost:8080
- - If you are using docker-machine instead of the native docker installation on Windows or macOs: open instead
-If you want to override the default `generated.yaml` you can mount this file when starting the docker command.
+---
-`docker run --rm --volume $PWD/generated.yaml:/srv/assets/YAML/generated/generated.yaml -p 8080:8080 wurstbrot/dsomm`
+
+What is DSOMM
-**NB!** Note that the docker command requires an absolute path to the local file. (Hence, the use of the `$PWD` variable. On Windows, substitute `$PWD` with `%CD%`.)
+# What Is DSOMM?
+DSOMM helps organizations answer three fundamental questions:
-## Amazon EC2 Instance
+- Where are we today in our DevSecOps maturity?
+- What security activities should we prioritize next?
+- How do we systematically improve security without slowing delivery?
-1. In the _EC2_ sidenav select _Instances_ and click _Launch Instance_
-2. In _Step 1: Choose an Amazon Machine Image (AMI)_ choose an _Amazon
- Linux AMI_ or _Amazon Linux 2 AMI_
-3. In _Step 3: Configure Instance Details_ unfold _Advanced Details_ and
- copy the script below into _User Data_
-4. In _Step 6: Configure Security Group_ add a _Rule_ that opens port 80
- for HTTP
-5. Launch your instance
-6. Browse to your instance's public DNS
+The model focuses on **concrete, technical activities** that integrate security directly into DevOps workflows such as CI/CD pipelines, containerization, infrastructure provisioning, and testing.
+
+Rather than prescribing abstract processes, DSOMM provides a **clear roadmap of actionable improvements** that teams can implement incrementally and measure over time.
+
+
+
+---
+
+
+DSOMM vs OWASP SAMM
+
+# DSOMM vs OWASP SAMM
+
+DSOMM and **OWASP SAMM** share a common goal: improving software security maturity. However, they serve different audiences and use cases.
+
+**OWASP SAMM**:
+- Focuses on overall software assurance maturity
+- Covers governance, compliance, risk management, and organizational processes
+- Written primarily by security specialists for security programs
+- Takes a broad, organization-wide perspective
+
+**DSOMM**:
+- Focuses on embedding security directly into DevOps workflows
+- Operates lower in the technical stack (pipelines, containers, tooling)
+- Provides concrete implementation guidance for engineering teams
+- Is written for practitioners building and operating secure software systems
+
+SAMM currently holds **OWASP Flagship** status, while DSOMM is an **OWASP Lab** project. The two models are complementary and are often used together.
+
+
+
+---
+
+
+How the DSOMM Application Works
+
+# How the DSOMM Application Works
+
+The DSOMM application is a **frontend-only web application**.
+
+## Community Instance (Quick Start)
+
+You can immediately explore DSOMM using the public community instance:
+
+https://dsomm.owasp.org
+
+Important notes:
+- All progress is stored in your browser’s localStorage
+- Clearing browser data will erase your progress
+- Progress cannot be shared directly with other users
+
+This mode is ideal for:
+- Learning DSOMM
+- Individual exploration
+- Lightweight, ad-hoc assessments
+
+
+
+---
+
+
+Running Your Own DSOMM Instance
+
+# Running Your Own DSOMM Instance
+
+To enable collaboration, persistence, or GitOps-style workflows, you should run your own DSOMM instance.
+
+DSOMM can be deployed in three primary ways:
+
+- Docker container
+- Amazon EC2
+- Local Angular application
+
+---
+
+
+## Running DSOMM as a Docker Container (Recommended)
+
+### Prerequisites
+- Docker installed
+
+### Steps
+```bash
+docker pull wurstbrot/dsomm:latest
+docker run --rm -p 8080:8080 wurstbrot/dsomm:latest &
+```
+
+### Access
+```text
+http://localhost:8080
+```
+
+On macOS or Windows using docker-machine:
+```text
+http://192.168.99.100:8080
+```
+
+---
+
+## Running DSOMM on Amazon EC2
+
+1. Open the EC2 console and click **Launch Instance**
+2. Choose an **Amazon Linux AMI** or **Amazon Linux 2 AMI**
+3. In **Configure Instance Details**, expand **Advanced Details** and add the following to **User Data**:
```bash
#!/bin/bash
@@ -41,63 +133,259 @@ service docker start
docker run -d -p 80:8080 wurstbrot/dsomm:latest
```
+4. In **Security Groups**, allow inbound HTTP traffic on port 80
+5. Launch the instance
+6. Access DSOMM via the instance’s public DNS
+
+---
-## Any web server - Angular build
-Since DSOMM is a frontend only application, any web server can host DSOMM.
-- Clone the DSOMM repo
+## Running DSOMM from GitHub (Local Development)
-- **NB!** The DSOMM activities are maintained separately. Download the `generated.yaml` and put it in the required folder
-```
-git clone https://github.com/devsecopsmaturitymodel/DevSecOps-MaturityModel.git
+### Prerequisites
+- Node.js
+- Angular CLI
+
+### Steps
+```bash
+git clone https://github.com/wurstbrot/DevSecOps-MaturityModel
cd DevSecOps-MaturityModel
npm install
-curl https://raw.githubusercontent.com/devsecopsmaturitymodel/DevSecOps-MaturityModel-data/main/src/assets/YAML/generated/generated.yaml -o src/assets/YAML/generated/generated.yaml
-ng build
+ng serve
+```
+
+### Access
+```text
+http://localhost:4200
```
-The files that were created in the subfolder `dist`
-If your DSOMM application is having a subfolder in the URL (e.g. https://server.local/our-dsomm), you need to build the Angular application to prepare for this. In that case build the application by using `ng build --base-href /our-dsomm/`.
+---
+
+## DSOMM Customization
+
+DSOMM is designed to be flexible and adaptable to different organizational structures, assessment contexts, and maturity models. Customization is achieved through YAML configuration files that are mounted into the DSOMM container at runtime.
+
+---
+
+### Teams and Groups
+To customize teams and groups, you can create your own `default/teams.yaml` file with unique team definitions. You can also download the teams file from the Teams page and selecting "Download Team Setup".
-## Teams and Groups
-To customize these teams, you can create your own [meta.yaml](src/assets/meta.yaml) file with your unique team definitions.
+Assessments within DSOMM can be based on either:
+- A **team**, or
+- A **specific application**
-Assessments within the framework can be based on either a team or a specific application, which can be referred to as the context. Depending on how you define the context or teams, you may want to group them together.
+These are collectively referred to as the **assessment context**. Depending on how you define contexts, you may want to group them hierarchically.
-Here are a couple of examples to illustrate this, in breakers the DSOMM word:
-- Multiple applications (teams) can belong to a single overarching team (application).
-- Multiple teams (teams) can belong to a larger department (group).
+#### Common use cases for custom teams and groups
-Feel free to create your own [meta.yaml](src/assets/meta.yaml) file to tailor the framework to your specific needs and mount it in your environment (e.g. kubernetes or docker).
-Here is an example to start docker with customized meta.yaml:
+- Multiple applications (teams) belonging to a single overarching application
+- Multiple teams grouped under a larger department or business unit
+
+#### Load a custom teams and groups file
+
+```bash
+docker run --rm \
+ -v /local/path/teams.yaml:/srv/assets/YAML/default/teams.yaml \
+ -p 8080:8080 \
+ wurstbrot/dsomm &
```
-# Customized meta.yaml
-cp src/assets/YAML/meta.yaml .
-docker run -v $(pwd)/meta.yaml:/srv/assets/YAML/meta.yaml -p 8080:8080 wurstbrot/dsomm
-
-# Customized meta.yaml and generated.yaml
-cp src/assets/YAML/meta.yaml .
-cp $(pwd)/src/assets/YAML/generated/generated.yaml .
-docker run -v $(pwd)/meta.yaml:/srv/assets/YAML/meta.yaml -v $(pwd)/generated.yaml:/srv/assets/YAML/generated/generated.yaml -p 8080:8080 wurstbrot/dsomm
+
+---
+
+### DSOMM Application Settings
+
+Application-level configuration is stored in the `meta.yaml` file. This file allows you to customize:
+
+- Browser behavior
+- Data file names
+- Progress definitions
+- Language and localization options
+- Other application settings
+
+#### Load custom application settings
+
+```bash
+docker run --rm \
+ -v /local/path/meta.yaml:/srv/assets/YAML/meta.yaml \
+ -p 8080:8080 \
+ wurstbrot/dsomm &
```
-In the corresponding [dimension YAMLs](https://github.com/devsecopsmaturitymodel/DevSecOps-MaturityModel-data/tree/main/src/assets/YAML/default), use:
+---
+
+### Custom DSOMM Model
+
+By default, DSOMM loads the standard maturity model. You can override this by supplying a custom `model.yaml` file.
+
+This allows you to:
+- Add, remove, or modify dimensions
+- Customize sub-dimensions
+- Define or remove activities
+
+#### Load a custom DSOMM model
+
+```bash
+docker run --rm \
+ -v /local/path/custom-model.yaml:/srv/assets/YAML/default/model.yaml \
+ -p 8080:8080 \
+ wurstbrot/dsomm &
```
-[...]
- teamsImplemented:
- Default: false
- B: true
- C: true
- teamsEvidence:
- B: All team members completed OWASP Secure Coding Dojo training on 2025-01-11.
- C: |
- The pentest report from 2025 has been split into Jira tasks under
- [TODO-123](https://jira.example.com/issues/TODO-123).
-
- _2025-04-01:_ All fixes of **critical** findings are deployed to production.
+
+---
+
+### Team Progress Import and Restore
+
+The DSOMM application allows exporting the current assessment state via:
+
+**Overview → Download Team Progress**
+
+This produces a `team-progress.yaml` file, which can be used to restore progress when:
+- Switching between organizational assessments
+- Recovering from accidental browser resets
+- Rehydrating assessments in new environments
+
+> Progress can only be restored if it was previously exported.
+
+#### Load a saved team progress export
+
+```bash
+docker run --rm \
+ -v /local/path/team-progress.yaml:/srv/assets/YAML/team-progress.yaml \
+ -p 8080:8080 \
+ wurstbrot/dsomm &
+```
+
+---
+
+### Evidence and Team-Specific Implementation
+
+Within the dimension YAML files, activities can track implementation status and evidence per team.
+
+Example:
+
+```yaml
+teamsImplemented:
+ Default: false
+ B: true
+ C: true
+
+teamsEvidence:
+ B: All team members completed OWASP Secure Coding Dojo training on 2025-01-11.
+ C: |
+ The pentest report from 2025 has been split into Jira tasks under
+ [TODO-123](https://jira.example.com/issues/TODO-123).
+
+ _2025-04-01:_ All fixes of **critical** findings are deployed to production.
+```
+
+Notes:
+- The `|` character indicates a multi-line YAML block
+- Markdown syntax is supported within evidence fields
+- Evidence is displayed directly on the activity within the **Matrix** view
+
+---
+
+### Loading Multiple Custom Files at Once
+
+```bash
+docker run --rm \
+ -v /local/path/meta.yaml:/srv/assets/YAML/meta.yaml \
+ -v /local/path/teams.yaml:/srv/assets/YAML/default/teams.yaml \
+ -v /local/path/team-progress.yaml:/srv/assets/YAML/team-progress.yaml \
+ -v /local/path/custom-model.yaml:/srv/assets/YAML/default/model.yaml \
+ -p 8080:8080 \
+ wurstbrot/dsomm:latest &
```
-The `|` is yaml syntax to indicate that the evidence spans multiple lines. Markdown
-syntax can be used. The evidence is currently visible on the activity from the Matrix page.
+
+This approach enables:
+- Fully reproducible assessments
+- GitOps-style configuration management
+- Multi-team and multi-context maturity tracking
+
+
+
+---
+
+
+Understanding the DSOMM Framework
+
+# Understanding the DSOMM Framework
+
+DSOMM organizes security activities by **dimensions** and **maturity levels**.
+
+Each activity:
+- Represents a concrete security capability
+- Is assigned a maturity level
+- Can be marked as implemented per team
+- Can include documented evidence
+
+Example:
+- Centralized system logging → Maturity Level 1
+- Correlation of security events → Maturity Level 5
+
+Before starting, it is strongly recommended to review **Maturity Level 0**, which focuses on stakeholder alignment and foundational prerequisites.
+
+
+
+---
+
+
+DSOMM Dimensions
+
+# DSOMM Dimensions
+
+DSOMM groups activities into the following dimensions:
+
+- **Build and Deployment**
+ Security practices in CI/CD pipelines and deployment workflows
+
+- **Culture and Organization**
+ Organizational culture, training, and processes that support security
+
+- **Implementation**
+ Secure coding, infrastructure hardening, and configuration management
+
+- **Information Gathering**
+ Metrics, telemetry, threat intelligence, and risk data collection
+
+- **Test and Verification**
+ Security testing and validation to ensure continuous improvement
+
+
+
+---
+
+
+Evidence and Auditing
+
+# Evidence and Auditing
+
+For organizations that require evidence (e.g., for CISOs or auditors), DSOMM supports attaching evidence directly in YAML files.
+
+Evidence is defined in `generated.yaml` or `team-progress.yaml` files using the `teamsEvidence` attribute. Markdown is supported, and multi-line evidence can be provided using YAML block syntax.
+
+Evidence is displayed directly on the activity within the Matrix view.
+
+> Note: Evidence cannot currently be entered directly in the browser UI.
+
+
+
+---
+
+
+Local Storage Behavior
+
+# Local Storage Behavior
+
+By default:
+- DSOMM stores progress in browser localStorage
+- Clearing browser data will reset progress
+- Self-hosted deployments are recommended for persistence
+
+
+
+---
+
# Back link
@@ -139,13 +427,3 @@ An example attribution by changing the content:
The OWASP DevSecOps Maturity Model and any contributions are Copyright © by Timo Pagel 2017-2025.
-
-For customized DSOMM, take a look at https://github.com/wurstbrot/DevSecOps-MaturityModel-custom.
-
-You can download your current state from the circular heatmap and mount it again via
-
-```bash
-wget https://raw.githubusercontent.com/devsecopsmaturitymodel/DevSecOps-MaturityModel-data/main/src/assets/YAML/generated/generated.yaml # or go to /circular-heatmap and download edited yaml (bottom right)
-docker run -p 8080:8080 -v /tmp/generated.yaml:/srv/assets/YAML/generated/generated.yaml wurstbrot/dsomm:latest
-```
-
diff --git a/README.md b/README.md
index 04ea8754..8e508237 100644
--- a/README.md
+++ b/README.md
@@ -1,91 +1,198 @@
-# Introduction
+# About DSOMM
-From a startup to a multinational corporation the software development industry is currently dominated by agile frameworks and product teams and as part of it DevOps strategies. It has been observed that during the implementation, security aspects are usually neglected or are at least not sufficient taken account of. It is often the case that standard safety requirements of the production environment are not utilized or applied to the build pipeline in the continuous integration environment with containerization or concrete docker. Therefore, the docker registry is often not secured which might result in the theft of the entire company’s source code.
+Modern software delivery is powered by agile teams, CI/CD pipelines, containerization, and cloud-native platforms. While these practices have dramatically increased delivery speed and scalability, security often fails to mature at the same pace.
-The OWASP DevSecOps Maturity Model provides opportunities to harden DevOps strategies and shows how these can be prioritized.
+In many organizations, security controls that are mandatory in production environments are inconsistently applied, or entirely missing, in build pipelines, container registries, and integration workflows. This gap introduces unnecessary risk, including exposed registries, vulnerable container images, weak pipeline controls, and, in severe cases, the loss of proprietary source code.
-With the help of DevOps strategies security can also be enhanced. For example, each component such as application libraries and operating system libraries in docker images can be tested for known vulnerabilities.
+The **OWASP DevSecOps Maturity Model (DSOMM)** exists to close this gap.
-Attackers are intelligent and creative, equipped with new technologies and purpose. Under the guidance of the forward-looking DevSecOps Maturity Model, appropriate principles and measures are at hand implemented which counteract the attacks.
+---
+
+## Why DSOMM Exists
+
+DSOMM provides a structured, opinionated maturity model that helps organizations systematically integrate security into DevOps practices - without sacrificing delivery velocity. It enables teams to:
+
+- Assess their current DevSecOps maturity
+- Prioritize meaningful security improvements
+- Incrementally strengthen security capabilities across the software lifecycle
+- Align engineering, security, and leadership around a shared roadmap
+
+Rather than treating security as a separate function or a final gate, DSOMM embeds security directly into how software is built, tested, and delivered.
+
+---
+
+## The DSOMM Application
+
+The DSOMM Application operationalizes the maturity model by transforming abstract concepts into concrete, trackable activities. Teams can:
+
+- Visualize maturity across dimensions and sub-dimensions
+- Track implementation levels per activity
+- Document progress using a GitOps-style workflow
+- Attach evidence to activities for audit and executive reporting
+- Map DSOMM activities to other standards and frameworks
+
+This makes DSOMM equally valuable for engineers, security practitioners, auditors, and CISOs.
+
+---
+
+## Security as an Enabler
+
+When implemented correctly, security strengthens DevOps rather than competing with it. Automated dependency scanning, container hardening, pipeline enforcement, and policy-driven controls are accelerators; not blockers.
+
+DSOMM helps teams adopt these practices deliberately, measurably, and sustainably.
+
+---
+
+## Built for Continuous Change
+
+Attackers evolve. Tooling advances. Threats adapt.
+
+DSOMM provides a forward-looking framework that allows organizations to respond with clarity instead of reaction-grounded in shared language, shared priorities, and continuous improvement.
+
+---
+
+## Open and Community-Driven
+
+DSOMM is an open, community-driven project under the umbrella of the OWASP Foundation. It is designed to be transparent, adaptable, and practical at any scale-from startups to multinational enterprises.
+
+Contributions, feedback, and collaboration from the community are encouraged to ensure the model remains relevant and effective as DevSecOps practices evolve.
+
+
+---
+
+
+Usage
# Usage
-Go to https://dsomm.owasp.org.
+
+DSOMM - DevSecOps Maturity Model
+
+# DSOMM – DevSecOps Maturity Model
+
+The **DevSecOps Maturity Model (DSOMM)** is a framework designed to help organizations assess, prioritize, and continuously improve security practices within their software development and delivery lifecycle.
+
+DSOMM is an open project of the **OWASP Foundation**, developed to provide practical, implementation-focused guidance for modern DevOps environments.
+
+
+
+---
+
+
+What is DSOMM
+
+# What Is DSOMM?
+
+DSOMM helps organizations answer three fundamental questions:
+
+- Where are we today in our DevSecOps maturity?
+- What security activities should we prioritize next?
+- How do we systematically improve security without slowing delivery?
+
+The model focuses on **concrete, technical activities** that integrate security directly into DevOps workflows such as CI/CD pipelines, containerization, infrastructure provisioning, and testing.
-* _matrix_ shows the dimensions, subdimensions and activities are described.
-* _Implementation Levels_ can be used to show the current implementation level by clicking on the specific activities which have been performed (it is recommended to use a gitops-like flow)
-* _Mappings_ Shows mappings to other standards and provides the ability to download an excel sheet
-* _Usage_ describes how to use DSOMM
+Rather than prescribing abstract processes, DSOMM provides a **clear roadmap of actionable improvements** that teams can implement incrementally and measure over time.
-In this [video](https://www.youtube.com/watch?v=tX9RHZ_O5NU) Timo Pagel describes different strategic approaches for your secure DevOps strategy. The use OWASP DSOMM in combination with [OWASP SAMM](https//owaspsamm.org) is explained.
+
-In case you have evidence or review questions to gather evidence, you can add the attribute "evidence" to an activity which will be attached to an activity to provide it to your CISO or your customer's CISO.
-You can switch on to show open TODO's for evidence by changing IS_SHOW_EVIDENCE_TODO to true 'bib.php' `define(IS_SHOW_EVIDENCE_TODO, true);`
+---
-This page uses the Browser's localStorage to store the state of the circular headmap.
+
+DSOMM vs OWASP SAMM
-# Changes
-Changes to the application are displayed at the release page of [DevSecOps-MaturityModel](https://github.com/devsecopsmaturitymodel/DevSecOps-MaturityModel-data/releases).
+# DSOMM vs OWASP SAMM
-Changes to the maturity model content are displayed at the release page of [DevSecOps-MaturityModel-data](https://github.com/devsecopsmaturitymodel/DevSecOps-MaturityModel-data/releases).
+DSOMM and **OWASP SAMM** share a common goal: improving software security maturity. However, they serve different audiences and use cases.
-# Community
-Join #dsomm in [OWASP Slack](https://owasp.slack.com/join/shared_invite/zt-g398htpy-AZ40HOM1WUOZguJKbblqkw#/).
-Create issues or even better Pull Requests in [github](https://github.com/wurstbrot/DevSecOps-MaturityModel/).
+**OWASP SAMM**:
+- Focuses on overall software assurance maturity
+- Covers governance, compliance, risk management, and organizational processes
+- Written primarily by security specialists for security programs
+- Takes a broad, organization-wide perspective
-# Slides and talks
-* [Video: OWASP (DevSecOps) Projects, 2021-04-28, OWASP Stammtisch Frankfurt](https://www.youtube.com/watch?v=8webiYnF56A)
-* [Video: DSOMM Enhancement Workshop at Open Security Summit, 2021-04-16](https://youtu.be/H2BA6gaeKBE)
-* [Video: Strategic Usage of the OWASP Software Assurance Maturity Model and the OWASP DevSecOps Maturity Model, OWASP Jakarta](https://m.youtube.com/watch?v=lLMLGIzl56M)
-* [Video: GitHub practical DSOMM snippet on twitch](https://www.twitch.tv/githubenterprise/clip/EsteemedTriumphantMinkFailFish)
-* [Blog: GitHub on DSOMM](https://github.blog/2020-08-06-achieving-devsecops-maturity-with-a-developer-first-community-driven-approach/) 2020
-* [Video: Benutzung vom OWASP DevSecOps Maturity Model (German)](https://vimeo.com/456523229)
-* [Online: OWASP DevSecOps Maturity Model - Culture (German)](https://www.meetup.com/de-DE/Breaking-Agile/) 2020-08-25
-* [Video: Usage of the OWASP DevSecOps Maturity Model](https://www.youtube.com/watch?v=tX9RHZ_O5NU), [OWASP Ottawa Chapter](https://www.meetup.com/de-DE/OWASP-Ottawa/events/272355636/), 2020-08-17
-* [Continuous Application Security Testing for Enterprise](https://docs.google.com/presentation/d/1dAewXIHgBEKHKwBPpM5N_G2eM6PRpduoGJrp6R6pNUI/edit?usp=sharing), DevOps Meetup Hamburg, 2019-09-26
-* [DevSecOps Maturity Model](https://docs.google.com/presentation/d/1zF7c_0cPYBO7LHcLNtEApQBB_qJugXgRQUyiwBKKtKk/edit?usp=sharing), Open Security Summit, near London, 2018
-* [Security in DevOps-Strategies](https://www.youtube.com/watch?v=gWjGWebWahE&t=448s), 28.09.2017, Hamburg, Germany
-* [DevSecOps Maturity Model](https://docs.google.com/presentation/d/1rrbyXqxy3LXAJNPFrVH99mj_BNaJKymMsXZItYArWEM/edit?usp=sharing), 2017
+**DSOMM**:
+- Focuses on embedding security directly into DevOps workflows
+- Operates lower in the technical stack (pipelines, containers, tooling)
+- Provides concrete implementation guidance for engineering teams
+- Is written for practitioners building and operating secure software systems
-# Assessment
+SAMM currently holds **OWASP Flagship** status, while DSOMM is an **OWASP Lab** project. The two models are complementary and are often used together.
-In case you would like to perform a DevSecOps assessment, the following tools are available:
+
-* Usage of the applicaton in a `container`.
-* Development of an export to [OWASP Maturity Models](https://github.com/OWASP/Maturity-Models) (recommended for assessments with a lot of teams)
-* Creation of your excel sheet (not recommended, you want to use DevOps, don't even try!)
+---
-## Container
+
+How the DSOMM Application Works
-1. Install [Docker](https://www.docker.com)
-2. Run `docker pull wurstbrot/dsomm:latest && docker run --rm -p 8080:8080 wurstbrot/dsomm:latest`
-3. Browse to (on macOS and Windows browse to if you are using docker-machine instead
- of the native docker installation)
+# How the DSOMM Application Works
-For customized DSOMM, take a look at https://github.com/wurstbrot/DevSecOps-MaturityModel-custom.
+The DSOMM application is a **frontend-only web application**.
-You can download your current state from the circular heatmap and mount it again via
+## Community Instance (Quick Start)
+You can immediately explore DSOMM using the public community instance:
+
+https://dsomm.owasp.org
+
+Important notes:
+- All progress is stored in your browser’s localStorage
+- Clearing browser data will erase your progress
+- Progress cannot be shared directly with other users
+
+This mode is ideal for:
+- Learning DSOMM
+- Individual exploration
+- Lightweight, ad-hoc assessments
+
+
+
+---
+
+
+Running Your Own DSOMM Instance
+
+# Running Your Own DSOMM Instance
+
+To enable collaboration, persistence, or GitOps-style workflows, you should run your own DSOMM instance.
+
+DSOMM can be deployed in three primary ways:
+
+- Docker container
+- Amazon EC2
+- Local Angular application
+
+---
+
+
+## Running DSOMM as a Docker Container (Recommended)
+
+### Prerequisites
+- Docker installed
+
+### Steps
```bash
-wget https://raw.githubusercontent.com/devsecopsmaturitymodel/DevSecOps-MaturityModel-data/main/src/assets/YAML/generated/generated.yaml # or go to /circular-heatmap and download edited yaml (bottom right)
-docker run -p 8080:8080 -v /tmp/generated.yaml:/srv/assets/YAML/generated/generated.yaml wurstbrot/dsomm:latest
+docker pull wurstbrot/dsomm:latest
+docker run --rm -p 8080:8080 wurstbrot/dsomm:latest &
+```
+
+### Access
+```text
+http://localhost:8080
```
-.
+On macOS or Windows using docker-machine:
+```text
+http://192.168.99.100:8080
+```
-This approach also allows teams to perform self assessment with changes tracked in a repository.
+---
-## Amazon EC2 Instance
+## Running DSOMM on Amazon EC2
-1. In the _EC2_ sidenav select _Instances_ and click _Launch Instance_
-2. In _Step 1: Choose an Amazon Machine Image (AMI)_ choose an _Amazon
- Linux AMI_ or _Amazon Linux 2 AMI_
-3. In _Step 3: Configure Instance Details_ unfold _Advanced Details_ and
- copy the script below into _User Data_
-4. In _Step 6: Configure Security Group_ add a _Rule_ that opens port 80
- for HTTP
-5. Launch your instance
-6. Browse to your instance's public DNS
+1. Open the EC2 console and click **Launch Instance**
+2. Choose an **Amazon Linux AMI** or **Amazon Linux 2 AMI**
+3. In **Configure Instance Details**, expand **Advanced Details** and add the following to **User Data**:
```bash
#!/bin/bash
@@ -93,71 +200,270 @@ service docker start
docker run -d -p 80:8080 wurstbrot/dsomm:latest
```
-## Generating the `generated.yaml` File
+4. In **Security Groups**, allow inbound HTTP traffic on port 80
+5. Launch the instance
+6. Access DSOMM via the instance’s public DNS
+
+---
+
+## Running DSOMM from GitHub (Local Development)
+
+### Prerequisites
+- Node.js
+- Angular CLI
+
+### Steps
+```bash
+git clone https://github.com/wurstbrot/DevSecOps-MaturityModel
+cd DevSecOps-MaturityModel
+npm install
+ng serve
+```
+
+### Access
+```text
+http://localhost:4200
+```
+
+---
+
+## DSOMM Customization
+
+DSOMM is designed to be flexible and adaptable to different organizational structures, assessment contexts, and maturity models. Customization is achieved through YAML configuration files that are mounted into the DSOMM container at runtime.
+
+---
+
+### Teams and Groups
+
+To customize teams and groups, you can create your own `default/teams.yaml` file with unique team definitions. You can also download the teams file from the Teams page and selecting "Download Team Setup".
+
+Assessments within DSOMM can be based on either:
+- A **team**, or
+- A **specific application**
+
+These are collectively referred to as the **assessment context**. Depending on how you define contexts, you may want to group them hierarchically.
-The `generated.yaml` file is dynamically created during the build process. If you don’t see this file after setup, follow these steps to generate it:
+#### Common use cases for custom teams and groups
-**1. Clone the Required Repository:**
-The `generated.yaml` file is built via the DevSecOps-MaturityModel-data repository. Make sure you have cloned and set it up correctly.
+- Multiple applications (teams) belonging to a single overarching application
+- Multiple teams grouped under a larger department or business unit
-**2. Run the Build Command:**
-Navigate to the project directory and run the following command:
-- *Using npm:*
+#### Load a custom teams and groups file
-```sh
-npm run build
-````
+```bash
+docker run --rm \
+ -v /local/path/teams.yaml:/srv/assets/YAML/default/teams.yaml \
+ -p 8080:8080 \
+ wurstbrot/dsomm &
+```
+
+---
+
+### DSOMM Application Settings
+
+Application-level configuration is stored in the `meta.yaml` file. This file allows you to customize:
-- *Using yarn:*
+- Browser behavior
+- Data file names
+- Progress definitions
+- Language and localization options
+- Other application settings
-```sh
-yarn build
+#### Load custom application settings
+
+```bash
+docker run --rm \
+ -v /local/path/meta.yaml:/srv/assets/YAML/meta.yaml \
+ -p 8080:8080 \
+ wurstbrot/dsomm &
```
-*If the file is missing, ensure all dependencies are installed and that you have the correct access to the `DevSecOps-MaturityModel-data` repository.*
+---
-## Activity Definitions
-The definition of the activities are in the [data-repository](https://github.com/devsecopsmaturitymodel/DevSecOps-MaturityModel-data).
+### Custom DSOMM Model
-## Teams and Groups
-To customize these teams, you can create your own [meta.yaml](src/assets/YAML/meta.yaml) file with your unique team definitions.
+By default, DSOMM loads the standard maturity model. You can override this by supplying a custom `model.yaml` file.
-Assessments within the framework can be based on either a team or a specific application, which can be referred to as the context. Depending on how you define the context or teams, you may want to group them together.
+This allows you to:
+- Add, remove, or modify dimensions
+- Customize sub-dimensions
+- Define or remove activities
-Here are a couple of examples to illustrate this, in breakers the DSOMM word:
-- Multiple applications (teams) can belong to a single overarching team (application).
-- Multiple teams (teams) can belong to a larger department (group).
+#### Load a custom DSOMM model
-Feel free to create your own [meta.yaml](src/assets/YAML/meta.yaml) file to tailor the framework to your specific needs and mount it in your environment (e.g. kubernetes or docker).
-Here is an example to start docker with customized meta.yaml:
+```bash
+docker run --rm \
+ -v /local/path/custom-model.yaml:/srv/assets/YAML/default/model.yaml \
+ -p 8080:8080 \
+ wurstbrot/dsomm &
```
-# Customized meta.yaml
-cp src/assets/YAML/meta.yaml .
-docker run -v $(pwd)/meta.yaml:/srv/assets/YAML/meta.yaml -p 8080:8080 wurstbrot/dsomm
-
-# Customized meta.yaml and generated.yaml
-cp src/assets/YAML/meta.yaml .
-cp $(pwd)/src/assets/YAML/generated/generated.yaml .
-docker run -v $(pwd)/meta.yaml:/srv/assets/YAML/meta.yaml -v $(pwd)/generated.yaml:/srv/assets/YAML/generated/generated.yaml -p 8080:8080 wurstbrot/dsomm
+
+---
+
+### Team Progress Import and Restore
+
+The DSOMM application allows exporting the current assessment state via:
+
+**Overview → Download Team Progress**
+
+This produces a `team-progress.yaml` file, which can be used to restore progress when:
+- Switching between organizational assessments
+- Recovering from accidental browser resets
+- Rehydrating assessments in new environments
+
+> Progress can only be restored if it was previously exported.
+
+#### Load a saved team progress export
+
+```bash
+docker run --rm \
+ -v /local/path/team-progress.yaml:/srv/assets/YAML/team-progress.yaml \
+ -p 8080:8080 \
+ wurstbrot/dsomm &
```
-In the corresponding [dimension YAMLs](https://github.com/devsecopsmaturitymodel/DevSecOps-MaturityModel-data/tree/main/src/assets/YAML/default), use:
+---
+
+### Evidence and Team-Specific Implementation
+
+Within the dimension YAML files, activities can track implementation status and evidence per team.
+
+Example:
+
+```yaml
+teamsImplemented:
+ Default: false
+ B: true
+ C: true
+
+teamsEvidence:
+ B: All team members completed OWASP Secure Coding Dojo training on 2025-01-11.
+ C: |
+ The pentest report from 2025 has been split into Jira tasks under
+ [TODO-123](https://jira.example.com/issues/TODO-123).
+
+ _2025-04-01:_ All fixes of **critical** findings are deployed to production.
```
-[...]
- teamsImplemented:
- Default: false
- B: true
- C: true
- teamsEvidence:
- B: All team members completed OWASP Secure Coding Dojo training on 2025-01-11.
- C: |
- The pentest report from 2025 has been split into Jira tasks under
- [TODO-123](https://jira.example.com/issues/TODO-123).
-
- _2025-04-01:_ All fixes of **critical** findings are deployed to production.
+
+Notes:
+- The `|` character indicates a multi-line YAML block
+- Markdown syntax is supported within evidence fields
+- Evidence is displayed directly on the activity within the **Matrix** view
+
+---
+
+### Loading Multiple Custom Files at Once
+
+```bash
+docker run --rm \
+ -v /local/path/meta.yaml:/srv/assets/YAML/meta.yaml \
+ -v /local/path/teams.yaml:/srv/assets/YAML/default/teams.yaml \
+ -v /local/path/team-progress.yaml:/srv/assets/YAML/team-progress.yaml \
+ -v /local/path/custom-model.yaml:/srv/assets/YAML/default/model.yaml \
+ -p 8080:8080 \
+ wurstbrot/dsomm:latest &
```
-The `|` is yaml syntax to indicate that the evidence spans multiple lines. Markdown
-syntax can be used. The evidence is currently visible on the activity from the Matrix page.
+
+This approach enables:
+- Fully reproducible assessments
+- GitOps-style configuration management
+- Multi-team and multi-context maturity tracking
+
+
+
+---
+
+
+Understanding the DSOMM Framework
+
+# Understanding the DSOMM Framework
+
+DSOMM organizes security activities by **dimensions** and **maturity levels**.
+
+Each activity:
+- Represents a concrete security capability
+- Is assigned a maturity level
+- Can be marked as implemented per team
+- Can include documented evidence
+
+Example:
+- Centralized system logging → Maturity Level 1
+- Correlation of security events → Maturity Level 5
+
+Before starting, it is strongly recommended to review **Maturity Level 0**, which focuses on stakeholder alignment and foundational prerequisites.
+
+
+
+---
+
+
+DSOMM Dimensions
+
+# DSOMM Dimensions
+
+DSOMM groups activities into the following dimensions:
+
+- **Build and Deployment**
+ Security practices in CI/CD pipelines and deployment workflows
+
+- **Culture and Organization**
+ Organizational culture, training, and processes that support security
+
+- **Implementation**
+ Secure coding, infrastructure hardening, and configuration management
+
+- **Information Gathering**
+ Metrics, telemetry, threat intelligence, and risk data collection
+
+- **Test and Verification**
+ Security testing and validation to ensure continuous improvement
+
+
+
+---
+
+
+Evidence and Auditing
+
+# Evidence and Auditing
+
+For organizations that require evidence (e.g., for CISOs or auditors), DSOMM supports attaching evidence directly in YAML files.
+
+Evidence is defined in `generated.yaml` or `team-progress.yaml` files using the `teamsEvidence` attribute. Markdown is supported, and multi-line evidence can be provided using YAML block syntax.
+
+Evidence is displayed directly on the activity within the Matrix view.
+
+> Note: Evidence cannot currently be entered directly in the browser UI.
+
+
+
+---
+
+
+Local Storage Behavior
+
+# Local Storage Behavior
+
+By default:
+- DSOMM stores progress in browser localStorage
+- Clearing browser data will reset progress
+- Self-hosted deployments are recommended for persistence
+
+
+
+
+
+---
+
+# Community and Contribution
+
+DSOMM is a community-driven project.
+
+- Join `#dsomm` on OWASP Slack
+- Submit issues or pull requests on GitHub
+- Participate in workshops, talks, and working groups
+
+---
# Back link
@@ -174,8 +480,8 @@ syntax can be used. The evidence is currently visible on the activity from the M
* CAMS Categorization
* Adding assessment questions
-# Multilanguage support
-Multilanguage support is not given currently and not planned.
+# Multi-language support
+Multi-language support is not currently planned.
# Sponsors
@@ -197,4 +503,5 @@ The intellectual property (content in the _data_ folder) is licensed under Attri
An example attribution by changing the content:
> This work is based on the [OWASP DevSecOps Maturity Model](https://dsomm.owasp.org/).
-The OWASP DevSecOps Maturity Model and any contributions are Copyright © by Timo Pagel 2017-2022.
+The OWASP DevSecOps Maturity Model and any contributions are Copyright © by Timo Pagel 2017-2025.
+
diff --git a/src/assets/Markdown Files/README.md b/src/assets/Markdown Files/README.md
index fabed8af..b6a5fb69 100644
--- a/src/assets/Markdown Files/README.md
+++ b/src/assets/Markdown Files/README.md
@@ -1,183 +1,65 @@
-# Introduction
+# About DSOMM
-From a startup to a multinational corporation the software development industry is currently dominated by agile frameworks and product teams and as part of it DevOps strategies. It has been observed that during the implementation, security aspects are usually neglected or are at least not sufficient taken account of. It is often the case that standard safety requirements of the production environment are not utilized or applied to the build pipeline in the continuous integration environment with containerization or concrete docker. Therefore, the docker registry is often not secured which might result in the theft of the entire company’s source code.
+Modern software delivery is powered by agile teams, CI/CD pipelines, containerization, and cloud-native platforms. While these practices have dramatically increased delivery speed and scalability, security often fails to mature at the same pace.
-The OWASP DevSecOps Maturity Model provides opportunities to harden DevOps strategies and shows how these can be prioritized.
+In many organizations, security controls that are mandatory in production environments are inconsistently applied, or entirely missing, in build pipelines, container registries, and integration workflows. This gap introduces unnecessary risk, including exposed registries, vulnerable container images, weak pipeline controls, and, in severe cases, the loss of proprietary source code.
-With the help of DevOps strategies security can also be enhanced. For example, each component such as application libraries and operating system libraries in docker images can be tested for known vulnerabilities.
+The **OWASP DevSecOps Maturity Model (DSOMM)** exists to close this gap.
-Attackers are intelligent and creative, equipped with new technologies and purpose. Under the guidance of the forward-looking DevSecOps Maturity Model, appropriate principles and measures are at hand implemented which counteract the attacks.
+---
-# Usage
+## Why DSOMM Exists
-Go to https://dsomm.owasp.org.
+DSOMM provides a structured, opinionated maturity model that helps organizations systematically integrate security into DevOps practices - without sacrificing delivery velocity. It enables teams to:
-* _matrix_ shows the dimensions, subdimensions and activities are described.
-* _Implementation Levels_ can be used to show the current implementation level by clicking on the specific activities which have been performed (it is recommended to use a gitops-like flow)
-* _Mappings_ Shows mappings to other standards and provides the ability to download an excel sheet
-* _Usage_ describes how to use DSOMM
+- Assess their current DevSecOps maturity
+- Prioritize meaningful security improvements
+- Incrementally strengthen security capabilities across the software lifecycle
+- Align engineering, security, and leadership around a shared roadmap
-In this [video](https://www.youtube.com/watch?v=tX9RHZ_O5NU) Timo Pagel describes different strategic approaches for your secure DevOps strategy. The use OWASP DSOMM in combination with [OWASP SAMM](https//owaspsamm.org) is explained.
+Rather than treating security as a separate function or a final gate, DSOMM embeds security directly into how software is built, tested, and delivered.
-In case you have evidence or review questions to gather evidence, you can add the attribute "evidence" to an activity which will be attached to an activity to provide it to your CISO or your customer's CISO.
-You can switch on to show open TODO's for evidence by changing IS_SHOW_EVIDENCE_TODO to true 'bib.php' `define(IS_SHOW_EVIDENCE_TODO, true);`
+---
-This page uses the Browser's localStorage to store the state of the circular headmap.
+## The DSOMM Application
-# Changes
-Changes to the application are displayed at the release page of [DevSecOps-MaturityModel](https://github.com/devsecopsmaturitymodel/DevSecOps-MaturityModel-data/releases).
+The DSOMM Application operationalizes the maturity model by transforming abstract concepts into concrete, trackable activities. Teams can:
-Changes to the maturity model content are displayed at the release page of [DevSecOps-MaturityModel-data](https://github.com/devsecopsmaturitymodel/DevSecOps-MaturityModel-data/releases).
+- Visualize maturity across dimensions and sub-dimensions
+- Track implementation levels per activity
+- Document progress using a GitOps-style workflow
+- Attach evidence to activities for audit and executive reporting
+- Map DSOMM activities to other standards and frameworks
-# Community
-Join #dsomm in [OWASP Slack](https://owasp.slack.com/join/shared_invite/zt-g398htpy-AZ40HOM1WUOZguJKbblqkw#/).
-Create issues or even better Pull Requests in [github](https://github.com/wurstbrot/DevSecOps-MaturityModel/).
+This makes DSOMM equally valuable for engineers, security practitioners, auditors, and CISOs.
-# Slides and talks
-* [Video: OWASP (DevSecOps) Projects, 2021-04-28, OWASP Stammtisch Frankfurt](https://www.youtube.com/watch?v=8webiYnF56A)
-* [Video: DSOMM Enhancement Workshop at Open Security Summit, 2021-04-16](https://youtu.be/H2BA6gaeKBE)
-* [Video: Strategic Usage of the OWASP Software Assurance Maturity Model and the OWASP DevSecOps Maturity Model, OWASP Jakarta](https://m.youtube.com/watch?v=lLMLGIzl56M)
-* [Slides: DSOMM Overview](https://docs.google.com/presentation/d/1eQcE_AsR1g6uOVf3B2Ehh1g0cHvPknkdLY4BzMYatSw/edit?usp=sharing)
-* [Video: GitHub practical DSOMM snippet on twitch](https://www.twitch.tv/githubenterprise/clip/EsteemedTriumphantMinkFailFish)
-* [Blog: GitHub on DSOMM](https://github.blog/2020-08-06-achieving-devsecops-maturity-with-a-developer-first-community-driven-approach/) 2020
-* [Video: Benutzung vom OWASP DevSecOps Maturity Model (German)](https://vimeo.com/456523229)
-* [Online: OWASP DevSecOps Maturity Model - Culture (German)](https://www.meetup.com/de-DE/Breaking-Agile/) 2020-08-25
-* [Video: Usage of the OWASP DevSecOps Maturity Model](https://www.youtube.com/watch?v=tX9RHZ_O5NU), [OWASP Ottawa Chapter](https://www.meetup.com/de-DE/OWASP-Ottawa/events/272355636/), 2020-08-17
-* [Continuous Application Security Testing for Enterprise](https://docs.google.com/presentation/d/1dAewXIHgBEKHKwBPpM5N_G2eM6PRpduoGJrp6R6pNUI/edit?usp=sharing), DevOps Meetup Hamburg, 2019-09-26
-* [DevSecOps Maturity Model](https://docs.google.com/presentation/d/1zF7c_0cPYBO7LHcLNtEApQBB_qJugXgRQUyiwBKKtKk/edit?usp=sharing), Open Security Summit, near London, 2018
-* [Security in DevOps-Strategies](https://www.youtube.com/watch?v=gWjGWebWahE&t=448s), 28.09.2017, Hamburg, Germany
-* [DevSecOps Maturity Model](https://docs.google.com/presentation/d/1rrbyXqxy3LXAJNPFrVH99mj_BNaJKymMsXZItYArWEM/edit?usp=sharing), 2017
+---
-# Assessment
+## Security as an Enabler
-In case you would like to perform a DevSecOps assessment, the following tools are available:
+When implemented correctly, security strengthens DevOps rather than competing with it. Automated dependency scanning, container hardening, pipeline enforcement, and policy-driven controls are accelerators; not blockers.
-* Usage of the applicaton in a `container`.
-* Development of an export to [OWASP Maturity Models](https://github.com/OWASP/Maturity-Models) (recommended for assessments with a lot of teams)
-* Creation of your excel sheet (not recommended, you want to use DevOps, don't even try!)
+DSOMM helps teams adopt these practices deliberately, measurably, and sustainably.
-## Container
+---
-1. Install [Docker](https://www.docker.com)
-2. Run `docker pull wurstbrot/dsomm:latest && docker run --rm -p 8080:8080 wurstbrot/dsomm:latest`
-3. Browse to (on macOS and Windows browse to if you are using docker-machine instead
- of the native docker installation)
+## Built for Continuous Change
-For customized DSOMM, take a look at https://github.com/wurstbrot/DevSecOps-MaturityModel-custom. In case you would like to have perform an assessment for multiple teams, iterate from port 8080 to 8XXX, depending of the size of your team.
+Attackers evolve. Tooling advances. Threats adapt.
-You can download your current state from the circular heatmap and mount it again via
+DSOMM provides a forward-looking framework that allows organizations to respond with clarity instead of reaction-grounded in shared language, shared priorities, and continuous improvement.
-```bash
-wget https://raw.githubusercontent.com/devsecopsmaturitymodel/DevSecOps-MaturityModel-data/main/src/assets/YAML/generated/generated.yaml # or go to /circular-heatmap and download edited yaml (bottom right)
-docker run -p 8080:8080 -v /tmp/generated.yaml:/srv/assets/YAML/generated/generated.yaml wurstbrot/dsomm:latest
-```
+---
-.
-wget https://raw.githubusercontent.com/devsecopsmaturitymodel/DevSecOps-MaturityModel-data/main/src/assets/YAML/generated/generated.yaml # or go to /circular-heatmap and download edited yaml (bottom right)
-docker run -p 8080:8080 -v /tmp/generated.yaml:/srv/assets/YAML/generated/generated.yaml wurstbrot/dsomm:latest
-```
+## Open and Community-Driven
-.
+DSOMM is an open, community-driven project under the umbrella of the OWASP Foundation. It is designed to be transparent, adaptable, and practical at any scale-from startups to multinational enterprises.
-This approach also allows teams to perform self assessment with changes tracked in a repository.
+Contributions, feedback, and collaboration from the community are encouraged to ensure the model remains relevant and effective as DevSecOps practices evolve.
-## Amazon EC2 Instance
-1. In the _EC2_ sidenav select _Instances_ and click _Launch Instance_
-2. In _Step 1: Choose an Amazon Machine Image (AMI)_ choose an _Amazon
- Linux AMI_ or _Amazon Linux 2 AMI_
-3. In _Step 3: Configure Instance Details_ unfold _Advanced Details_ and
- copy the script below into _User Data_
-4. In _Step 6: Configure Security Group_ add a _Rule_ that opens port 80
- for HTTP
-5. Launch your instance
-6. Browse to your instance's public DNS
+---
-```bash
-#!/bin/bash
-service docker start
-docker run -d -p 80:8080 wurstbrot/dsomm:latest
-```
+## Usage
-## Activity Definitions
-The definition of the activities are in the [data-repository](https://github.com/devsecopsmaturitymodel/DevSecOps-MaturityModel-data).
-
-## Teams and Groups
-To customize these teams, you can create your own [meta.yaml](/assets/YAML/meta.yaml) file with your unique team definitions.
-
-Assessments within the framework can be based on either a team or a specific application, which can be referred to as the context. Depending on how you define the context or teams, you may want to group them together.
-
-Here are a couple of examples to illustrate this, in breakers the DSOMM word:
-- Multiple applications (teams) can belong to a single overarching team (application).
-- Multiple teams (teams) can belong to a larger department (group).
-
-Feel free to create your own [meta.yaml](/assets/YAML/meta.yaml) file to tailor the framework to your specific needs and mount it in your environment (e.g. kubernetes or docker).
-Here is an example to start docker with customized meta.yaml:
-```
-# Customized meta.yaml
-cp src/assets/YAML/meta.yaml .
-docker run -v $(pwd)/meta.yaml:/srv/assets/YAML/meta.yaml -p 8080:8080 wurstbrot/dsomm
-
-# Customized meta.yaml and generated.yaml
-cp src/assets/YAML/meta.yaml .
-cp $(pwd)/src/assets/YAML/generated/generated.yaml .
-docker run -v $(pwd)/meta.yaml:/srv/assets/YAML/meta.yaml -v $(pwd)/generated.yaml:/srv/assets/YAML/generated/generated.yaml -p 8080:8080 wurstbrot/dsomm
-```
-
-In the corresponding [dimension YAMLs](https://github.com/devsecopsmaturitymodel/DevSecOps-MaturityModel-data/tree/main/src/assets/YAML/default), use:
-```
-[...]
- teamsImplemented:
- Default: false
- B: true
- C: true
- teamsEvidence:
- B: All team members completed OWASP Secure Coding Dojo training on 2025-01-11.
- C: |
- The pentest report from 2025 has been split into Jira tasks under
- [TODO-123](https://jira.example.com/issues/TODO-123).
-
- _2025-04-01:_ All fixes of **critical** findings are deployed to production.
-```
-The `|` is yaml syntax to indicate that the evidence spans multiple lines. Markdown
-syntax can be used. The evidence is currently visible on the activity from the Matrix page.
-
-# Back link
-
-- [OWASP DevSecOps maturity model page](https://dsomm.owasp.org/)
-- [OWASP DevSecOps project page](https://owasp.org/www-project-devsecops-maturity-model/)
-- [OWASP](https://owasp.org)
-
-# Your help is needed to perform
-
-* Adding a manual on how to use DSOMM
-* Integration of Incident Response
-* DevSecOps Toolchain Categorization
-* App Sec Maturity Models Mapping
-* CAMS Categorization
-* Adding assessment questions
-
-# Multilanguage support
-Multilanguage support is not given currently and not planned.
-
-# Sponsors
-
-[](https://pagel.pro)
-
-[](https://apiiro.com/)
-
-[](https://www.heroku.com/open-source-credit-program)
-
-# Donations
-
-If you are using the model or you are inspired by it, want to help but don't want to create pull requests? You can donate at the [OWASP Project Wiki Page](https://owasp.org/donate/?reponame=www-project-devsecops-maturity-model&title=OWASP+Devsecops+Maturity+Model). Donations might be used for the design of logos/images/design or travels.
-
-# License
-
-This program is free software: you can redistribute it and/or modify it under the terms of the [GPL 3](https://www.gnu.org/licenses/) license.
-
-The intellectual property (content in the _data_ folder) is licensed under Attribution-ShareAlike.
-An example attribution by changing the content:
-> This work is based on the [OWASP DevSecOps Maturity Model](https://dsomm.owasp.org/).
-
-The OWASP DevSecOps Maturity Model and any contributions are Copyright © by Timo Pagel 2017-2022.
+For usage instructions, please see [Usage](/usage)
\ No newline at end of file
diff --git a/src/assets/Markdown Files/USAGE.md b/src/assets/Markdown Files/USAGE.md
index 9893d3ea..240f0329 100644
--- a/src/assets/Markdown Files/USAGE.md
+++ b/src/assets/Markdown Files/USAGE.md
@@ -1,63 +1,417 @@
-# DSOMM - DevSecOps Maturity Model
+
+DSOMM - DevSecOps Maturity Model
-## What is DSOMM?
-DSOMM is a framework that helps organizations to assess, improve and prioritize security activities in their software development cycle.
+# DSOMM – DevSecOps Maturity Model
-DSOMM is a project of the OWASP Foundation.
+The **DevSecOps Maturity Model (DSOMM)** is a framework designed to help organizations assess, prioritize, and continuously improve security practices within their software development and delivery lifecycle.
-## DSOMM vs OWASP SAMM
-[DSOMM](https://dsomm.owasp.org/) and [OWASP SAMM](https://owaspsamm.org/) are both frameworks that share a common goal of improving security.
+DSOMM is an open project of the **OWASP Foundation**, developed to provide practical, implementation-focused guidance for modern DevOps environments.
-**OWASP SAMM** is more focused on the overall maturity of an organization's software assurance and security practices, with a broader scope that includes governance, compliance, risk management, and secure software development.
+
-SAMM is written by security specialists for security specialists, focusing on security processes across the whole organizations.
+---
-**DSOMM** focuses on activities that integrate security directly into the DevOps workflows. DSOMM takes a more technical approach, going lower in the technology stack it provides a roadmap on how to systematically improve the security in the software development.
+
+What is DSOMM
-DSOMM is written for technical teams focused on implementing secure software.
+# What Is DSOMM?
-DSOMM has currently has a OWASP Lab status, while SAMM has a Flagship status.
+DSOMM helps organizations answer three fundamental questions:
-# How to use this DSOMM site
-The DSOMM application is a frontend only application, storing all progress in your local storage in your browser. If you delete your local storage, your progress will be gone, and you cannot share your saved progress with anyone else.
+- Where are we today in our DevSecOps maturity?
+- What security activities should we prioritize next?
+- How do we systematically improve security without slowing delivery?
-To do that, you need to install your own local DSOMM application.
+The model focuses on **concrete, technical activities** that integrate security directly into DevOps workflows such as CI/CD pipelines, containerization, infrastructure provisioning, and testing.
-You can export the progress of the different activities as a `generated.yaml` file, which you may import into your own site.
+Rather than prescribing abstract processes, DSOMM provides a **clear roadmap of actionable improvements** that teams can implement incrementally and measure over time.
+
-## How to setup your own DSOMM
-The DSOMM application can be run as a Docker image, an Amazon EC2 instance, or as a standalone Angular application using NodeJS. Please see [README.md](./usage/README) for further instructions.
+---
-The DSOMM application is currently still a lightweight frontend only application, without a backend to store changes of progress. Any changes are stored in the browser. However, as above, you can export the `generated.yaml` and update your own site with this.
+
+DSOMM vs OWASP SAMM
+# DSOMM vs OWASP SAMM
-# The DSOMM framework
-The DSOMM framework has a number of _activities_ grouped by _dimensions_ and _maturity levels_. E.g. the _Centralized system logging_ is a maturity level 1 activity in the _Logging_ dimension, while _Correlation of security events_ is considered level 5.
+DSOMM and **OWASP SAMM** share a common goal: improving software security maturity. However, they serve different audiences and use cases.
+**OWASP SAMM**:
+- Focuses on overall software assurance maturity
+- Covers governance, compliance, risk management, and organizational processes
+- Written primarily by security specialists for security programs
+- Takes a broad, organization-wide perspective
+**DSOMM**:
+- Focuses on embedding security directly into DevOps workflows
+- Operates lower in the technical stack (pipelines, containers, tooling)
+- Provides concrete implementation guidance for engineering teams
+- Is written for practitioners building and operating secure software systems
-## Before you start
-To prepare you for there are some activities that we recommend you do before you start using DSOMM. Getting the stakeholders onboard will ease your path.
+SAMM currently holds **OWASP Flagship** status, while DSOMM is an **OWASP Lab** project. The two models are complementary and are often used together.
-See [Maturity level 0](./usage/maturity-level-0) to learn about the important first steps.
+
+---
-## Dimensions
-The DSOMM framework categorizes its activities into dimensions, each representing a key area of the software development lifecycle where security can be integrated and matured.
+
+How the DSOMM Application Works
-Dimensions Overview:
- - **Build and Deployment**: Focuses on security practices in the CI/CD pipeline and deployment processes
- - **Culture and Organization**: Addresses organizational culture, education, and processes that support security initiatives.
- - **Implementation**: Covers secure coding and infrastructure hardening practices.
-- **Information Gathering**: Involves gathering data for threat analysis, risk assessment, and metrics collection.
-- **Test and Verification**: Focuses on testing practices to validate security measures and ensure continuous improvement.
+# How the DSOMM Application Works
-For detailed information on each dimension, refer to [Dimensions](./usage/dimensions).
+The DSOMM application is a **frontend-only web application**.
+## Community Instance (Quick Start)
+You can immediately explore DSOMM using the public community instance:
+https://dsomm.owasp.org
+Important notes:
+- All progress is stored in your browser’s localStorage
+- Clearing browser data will erase your progress
+- Progress cannot be shared directly with other users
-## Evidence
-If your CISO requires you to document evidence that an activity is completed, you can edit your `generated.yaml` file as documented in the [README.md](./usage/README) _Teams and Groups_. It is currently not possible to provide evidence directly in the browser.
+This mode is ideal for:
+- Learning DSOMM
+- Individual exploration
+- Lightweight, ad-hoc assessments
+
+
+
+---
+
+
+Running Your Own DSOMM Instance
+
+# Running Your Own DSOMM Instance
+
+To enable collaboration, persistence, or GitOps-style workflows, you should run your own DSOMM instance.
+
+DSOMM can be deployed in three primary ways:
+
+- Docker container
+- Amazon EC2
+- Local Angular application
+
+---
+
+
+## Running DSOMM as a Docker Container (Recommended)
+
+### Prerequisites
+- Docker installed
+
+### Steps
+```bash
+docker pull wurstbrot/dsomm:latest
+docker run --rm -p 8080:8080 wurstbrot/dsomm:latest &
+```
+
+### Access
+```text
+http://localhost:8080
+```
+
+On macOS or Windows using docker-machine:
+```text
+http://192.168.99.100:8080
+```
+
+---
+
+## Running DSOMM on Amazon EC2
+
+1. Open the EC2 console and click **Launch Instance**
+2. Choose an **Amazon Linux AMI** or **Amazon Linux 2 AMI**
+3. In **Configure Instance Details**, expand **Advanced Details** and add the following to **User Data**:
+
+```bash
+#!/bin/bash
+service docker start
+docker run -d -p 80:8080 wurstbrot/dsomm:latest
+```
+
+4. In **Security Groups**, allow inbound HTTP traffic on port 80
+5. Launch the instance
+6. Access DSOMM via the instance’s public DNS
+
+---
+
+## Running DSOMM from GitHub (Local Development)
+
+### Prerequisites
+- Node.js
+- Angular CLI
+
+### Steps
+```bash
+git clone https://github.com/wurstbrot/DevSecOps-MaturityModel
+cd DevSecOps-MaturityModel
+npm install
+ng serve
+```
+
+### Access
+```text
+http://localhost:4200
+```
+
+---
+
+## DSOMM Customization
+
+DSOMM is designed to be flexible and adaptable to different organizational structures, assessment contexts, and maturity models. Customization is achieved through YAML configuration files that are mounted into the DSOMM container at runtime.
+
+---
+
+### Teams and Groups
+
+To customize teams and groups, you can create your own `default/teams.yaml` file with unique team definitions. You can also download the teams file from the Teams page and selecting "Download Team Setup".
+
+Assessments within DSOMM can be based on either:
+- A **team**, or
+- A **specific application**
+
+These are collectively referred to as the **assessment context**. Depending on how you define contexts, you may want to group them hierarchically.
+
+#### Common use cases for custom teams and groups
+
+- Multiple applications (teams) belonging to a single overarching application
+- Multiple teams grouped under a larger department or business unit
+
+#### Load a custom teams and groups file
+
+```bash
+docker run --rm \
+ -v /local/path/teams.yaml:/srv/assets/YAML/default/teams.yaml \
+ -p 8080:8080 \
+ wurstbrot/dsomm &
+```
+
+---
+
+### DSOMM Application Settings
+
+Application-level configuration is stored in the `meta.yaml` file. This file allows you to customize:
+
+- Browser behavior
+- Data file names
+- Progress definitions
+- Language and localization options
+- Other application settings
+
+#### Load custom application settings
+
+```bash
+docker run --rm \
+ -v /local/path/meta.yaml:/srv/assets/YAML/meta.yaml \
+ -p 8080:8080 \
+ wurstbrot/dsomm &
+```
+
+---
+
+### Custom DSOMM Model
+
+By default, DSOMM loads the standard maturity model. You can override this by supplying a custom `model.yaml` file.
+
+This allows you to:
+- Add, remove, or modify dimensions
+- Customize sub-dimensions
+- Define or remove activities
+
+#### Load a custom DSOMM model
+
+```bash
+docker run --rm \
+ -v /local/path/custom-model.yaml:/srv/assets/YAML/default/model.yaml \
+ -p 8080:8080 \
+ wurstbrot/dsomm &
+```
+
+---
+
+### Team Progress Import and Restore
+
+The DSOMM application allows exporting the current assessment state via:
+
+**Overview → Download Team Progress**
+
+This produces a `team-progress.yaml` file, which can be used to restore progress when:
+- Switching between organizational assessments
+- Recovering from accidental browser resets
+- Rehydrating assessments in new environments
+
+> Progress can only be restored if it was previously exported.
+
+#### Load a saved team progress export
+
+```bash
+docker run --rm \
+ -v /local/path/team-progress.yaml:/srv/assets/YAML/team-progress.yaml \
+ -p 8080:8080 \
+ wurstbrot/dsomm &
+```
+
+---
+
+### Evidence and Team-Specific Implementation
+
+Within the dimension YAML files, activities can track implementation status and evidence per team.
+
+Example:
+
+```yaml
+teamsImplemented:
+ Default: false
+ B: true
+ C: true
+
+teamsEvidence:
+ B: All team members completed OWASP Secure Coding Dojo training on 2025-01-11.
+ C: |
+ The pentest report from 2025 has been split into Jira tasks under
+ [TODO-123](https://jira.example.com/issues/TODO-123).
+
+ _2025-04-01:_ All fixes of **critical** findings are deployed to production.
+```
+
+Notes:
+- The `|` character indicates a multi-line YAML block
+- Markdown syntax is supported within evidence fields
+- Evidence is displayed directly on the activity within the **Matrix** view
+
+---
+
+### Loading Multiple Custom Files at Once
+
+```bash
+docker run --rm \
+ -v /local/path/meta.yaml:/srv/assets/YAML/meta.yaml \
+ -v /local/path/teams.yaml:/srv/assets/YAML/default/teams.yaml \
+ -v /local/path/team-progress.yaml:/srv/assets/YAML/team-progress.yaml \
+ -v /local/path/custom-model.yaml:/srv/assets/YAML/default/model.yaml \
+ -p 8080:8080 \
+ wurstbrot/dsomm:latest &
+```
+
+This approach enables:
+- Fully reproducible assessments
+- GitOps-style configuration management
+- Multi-team and multi-context maturity tracking
+
+
+
+---
+
+
+Understanding the DSOMM Framework
+
+# Understanding the DSOMM Framework
+
+DSOMM organizes security activities by **dimensions** and **maturity levels**.
+
+Each activity:
+- Represents a concrete security capability
+- Is assigned a maturity level
+- Can be marked as implemented per team
+- Can include documented evidence
+
+Example:
+- Centralized system logging → Maturity Level 1
+- Correlation of security events → Maturity Level 5
+
+Before starting, it is strongly recommended to review **Maturity Level 0**, which focuses on stakeholder alignment and foundational prerequisites.
+
+
+
+---
+
+
+DSOMM Dimensions
+
+# DSOMM Dimensions
+
+DSOMM groups activities into the following dimensions:
+
+- **Build and Deployment**
+ Security practices in CI/CD pipelines and deployment workflows
+
+- **Culture and Organization**
+ Organizational culture, training, and processes that support security
+
+- **Implementation**
+ Secure coding, infrastructure hardening, and configuration management
+
+- **Information Gathering**
+ Metrics, telemetry, threat intelligence, and risk data collection
+
+- **Test and Verification**
+ Security testing and validation to ensure continuous improvement
+
+
+
+---
+
+
+Evidence and Auditing
+
+# Evidence and Auditing
+
+For organizations that require evidence (e.g., for CISOs or auditors), DSOMM supports attaching evidence directly in YAML files.
+
+Evidence is defined in `generated.yaml` or `team-progress.yaml` files using the `teamsEvidence` attribute. Markdown is supported, and multi-line evidence can be provided using YAML block syntax.
+
+Evidence is displayed directly on the activity within the Matrix view.
+
+> Note: Evidence cannot currently be entered directly in the browser UI.
+
+
+
+---
+
+
+Local Storage Behavior
+
+# Local Storage Behavior
+
+By default:
+- DSOMM stores progress in browser localStorage
+- Clearing browser data will reset progress
+- Self-hosted deployments are recommended for persistence
+
+
+
+---
+
+
+Community and Contribution
+
+# Community and Contribution
+
+DSOMM is a community-driven project.
+
+- Join `#dsomm` on OWASP Slack
+- Submit issues or pull requests on GitHub
+- Participate in workshops, talks, and working groups
+
+
+
+---
+
+
+License
+
+# License
+
+The DSOMM application is released under **GPL v3**.
+
+The maturity model content is licensed under **Creative Commons Attribution-ShareAlike**.
+
+Attribution example:
+
+> This work is based on the OWASP DevSecOps Maturity Model.
+
+
\ No newline at end of file