Skip to content

Commit 2f29e13

Browse files
apenlorapenlor
authored
docs(readme): update main README for phase 7 completion (#18)
1 parent 2fa86a1 commit 2f29e13

File tree

1 file changed

+28
-172
lines changed

1 file changed

+28
-172
lines changed

‎README.md‎

Lines changed: 28 additions & 172 deletions
Original file line numberDiff line numberDiff line change
@@ -1,189 +1,45 @@
11
# Spring Boot Security & Observability Lab
22

3-
This repository is a hands-on lab designed to demonstrate the architectural evolution of a modern Java application. We
4-
will build a system from the ground up, starting with a secure monolith and progressively refactoring it into a fully
5-
observable, distributed system using cloud-native best practices.
3+
This is an advanced, hands-on lab demonstrating the architectural evolution of a modern Java application. We will build
4+
a system from the ground up, starting with a secure monolith and progressively refactoring it into a fully observable,
5+
distributed system using cloud-native best practices.
66

77
---
88

9-
## Lab Progress: Phase 7 - Continuous Security Integration (DevSecOps)
9+
## Workshop Guide: The Evolutionary Phases
1010

11-
The `main` branch currently represents the completed state of **Phase 7**.
11+
This lab is structured in distinct, self-contained phases. The `main` branch always represents the latest completed
12+
phase. To explore a previous phase's code and detailed documentation, use the links below.
1213

13-
* **Git Tag for this Phase:** `v7.0-continuous-security`
14-
15-
### Objective
16-
17-
The goal of this phase was to "shift left" security, embedding a comprehensive and automated security testing pipeline
18-
directly into our CI/CD workflow. This phase transforms our development process from one where security is a manual or
19-
late-stage activity into a true DevSecOps model, where security checks are an integral, automated part of every code
20-
change. Build a high-assurance delivery pipeline that catches vulnerabilities early and automatically.
21-
22-
### Key Concepts Demonstrated
23-
24-
* **Multi-Layered Security Pipeline:** Implementing a defense-in-depth strategy with three distinct, automated security
25-
gates in our GitHub Actions workflow.
26-
* **Software Composition Analysis (SCA):** Using the **OWASP Dependency-Check** Maven plugin to automatically scan all
27-
third-party libraries for known vulnerabilities (CVEs), addressing supply chain risk.
28-
* **Container Image Scanning:** Using **Trivy** to scan our final Docker images (`resource-server`, `web-client`) for
29-
vulnerabilities in the underlying operating system and system libraries.
30-
* **Dynamic Application Security Testing (DAST):** Using the **OWASP ZAP** baseline scanner to perform a live, running
31-
scan of the `resource-server`'s API contract, identifying runtime and configuration-related security issues.
32-
* **API Contract Generation:** Integrating **SpringDoc OpenAPI** to automatically generate an OpenAPI v3 specification,
33-
providing a machine-readable contract for the DAST scanner.
34-
* **Automated Security Gates:** Configuring the CI pipeline to **fail the build** if any of the scanners detect a high
35-
or critical severity vulnerability, creating an automated quality gate.
36-
* **CI/CD Debugging & Remediation:** Demonstrating a realistic workflow of a security gate catching a legitimate
37-
vulnerability (`CVE-2025-58056`) and implementing a remediation by overriding a transitive
38-
dependency (`Netty`) in the parent POM.
39-
* **Portable CI/CD Scripting:** Creating an orchestration script (`run-zap-scan.sh`) that is
40-
environment-aware, working seamlessly in both local development environments and the ephemeral GitHub Actions runners.
41-
42-
### Architecture Overview
43-
44-
Phase 7 integrates a new set of security tools directly into our existing CI/CD pipeline, creating a feedback loop that
45-
informs developers of vulnerabilities before code is merged.
46-
47-
```mermaid
48-
graph TD
49-
subgraph "Developer's Machine"
50-
Dev[Developer] -- "1. git push" --> Branch
51-
end
52-
53-
subgraph "GitHub Actions CI/CD Pipeline"
54-
PR[Pull Request] -- "2. Triggers Workflow" --> Workflow
55-
56-
subgraph "Workflow Jobs"
57-
Job1[Build, Test & SCA]
58-
Job2[Build & Scan Docker Images]
59-
Job3[DAST Scan]
60-
end
61-
62-
Workflow --> Job1
63-
Job1 --> Job2
64-
Job1 --> Job3
65-
66-
subgraph "Security Gates"
67-
SCA[OWASP Dependency-Check]
68-
Trivy[Trivy Image Scan]
69-
ZAP[OWASP ZAP DAST Scan]
70-
end
71-
72-
Job1 -- "Runs" --> SCA
73-
Job2 -- "Runs" --> Trivy
74-
Job3 -- "Runs" --> ZAP
75-
end
76-
77-
subgraph "Outcome"
78-
SCA -- "3. Reports CVEs" --> Result
79-
Trivy -- "3. Reports Image Flaws" --> Result
80-
ZAP -- "3. Reports API Flaws" --> Result
81-
Result{Build Succeeded / Failed} -- "4. Feedback" --> PR
82-
end
83-
```
84-
85-
1. **[OWASP Dependency-Check](pom.xml):** The `dependency-check-maven` plugin is now integrated into our parent POM and
86-
bound to the `verify` lifecycle phase. This automatically executes an SCA scan on every CI run.
87-
2. **[Trivy](.github/workflows/ci.yml):** The `aquasecurity/trivy-action` is added to our workflow. It runs immediately
88-
after the `docker buildx build` command, scanning the newly created image before it could ever be pushed to a
89-
registry.
90-
3. **[OWASP ZAP](scripts/run-zap-scan.sh):** The new orchestration script is responsible for starting a live,
91-
production-like environment (`postgres`, `keycloak`, `resource-server`) and running the `zaproxy/zap-stable`
92-
container against the application's OpenAPI endpoint.
14+
| Phase | Description & Key Concepts | Code & Docs (at tag) | Key Pull Requests |
15+
|:-----------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
16+
| **1. The Secure Monolith** | A standalone service that issues and validates its own JWTs. Concepts: `AuthenticationManager`, custom `JwtAuthenticationFilter`, `jjwt` library, and a foundational CI pipeline. | [`v1.0-secure-monolith`](https://github.com/apenlor/spring-boot-security-observability-lab/tree/v1.0-secure-monolith) | [#2](https://github.com/apenlor/spring-boot-security-observability-lab/pull/2), [#3](https://github.com/apenlor/spring-boot-security-observability-lab/pull/3), [#4](https://github.com/apenlor/spring-boot-security-observability-lab/pull/4) |
17+
| **2. Observing the Monolith** | The service is containerized and orchestrated via `docker-compose`. Concepts: Micrometer, Prometheus, Grafana, custom metrics, and automated dashboard provisioning. | [`v2.0-observable-monolith`](https://github.com/apenlor/spring-boot-security-observability-lab/tree/v2.0-observable-monolith) | [#6](https://github.com/apenlor/spring-boot-security-observability-lab/pull/6) |
18+
| **3. Evolving to Federated Identity** | The system is refactored into a multi-service architecture with an external IdP. Concepts: Keycloak, OIDC, OAuth2 Client (`web-client`) vs. Resource Server, Traefik reverse proxy, service-to-service security. | [`v3.0-federated-identity`](https://github.com/apenlor/spring-boot-security-observability-lab/tree/v3.0-federated-identity) | [#8](https://github.com/apenlor/spring-boot-security-observability-lab/pull/8) |
19+
| **4. Tracing a Distributed System** | Services are instrumented with the OpenTelemetry agent to generate traces. Concepts: Tempo, agent-based instrumentation, W3C Trace Context, Service Graphs, and a hybrid PUSH/PULL metrics architecture. | [`v4.0-distributed-tracing`](https://github.com/apenlor/spring-boot-security-observability-lab/tree/v4.0-distributed-tracing) | [#10](https://github.com/apenlor/spring-boot-security-observability-lab/pull/10) |
20+
| **5. Correlated Logs & Access Auditing** | The three pillars of observability are complete (metrics, traces, logs). Alloy is the unified collection agent. Concepts: Loki, Grafana Alloy, Docker service discovery, structured JSON logs, AOP-based auditing, trace-to-log correlation, and detailed audit metrics. | [`v5.0-correlated-logs-auditing`](https://github.com/apenlor/spring-boot-security-observability-lab/tree/v5.0-correlated-logs-auditing) | [#12](https://github.com/apenlor/spring-boot-security-observability-lab/pull/12) |
21+
| **6. Proactive Alerting** | The system transitions from passive to proactive monitoring. Concepts: Alertmanager, declarative PromQL alert rules, alerting on technical vs. security metrics, and a UI-driven test harness. | [`v6.0-proactive-alerting`](https://github.com/apenlor/spring-boot-security-observability-lab/tree/v6.0-proactive-alerting) | [#14](https://github.com/apenlor/spring-boot-security-observability-lab/pull/14) |
22+
| **7. Continuous Security Integration** | "Shift left" security by embedding automated scanning into the CI/CD pipeline. Concepts: SCA (OWASP Dependency-Check), Container Scanning (Trivy), DAST (OWASP ZAP), and automated vulnerability remediation. | [`v7.0-continuous-security`](https://github.com/apenlor/spring-boot-security-observability-lab/tree/v7.0-continuous-security) | [#17](https://github.com/apenlor/spring-boot-security-observability-lab/pull/17) |
23+
| **8. Advanced Secret Management** | _Upcoming..._ | - | - |
9324

9425
---
9526

96-
### Key Configuration Details
97-
98-
#### 1. Vulnerability Remediation as Code
27+
## How to Follow This Lab
9928

100-
A core part of this phase was not just *finding* vulnerabilities, but *fixing* them. After the SCA scan correctly
101-
identified `CVE-2025-58056` in a transitive Netty dependency, we implemented a remediation in our root [
102-
`pom.xml`](pom.xml):
103-
104-
```xml
105-
<!-- In <dependencyManagement> -->
106-
<dependency>
107-
<groupId>io.netty</groupId>
108-
<artifactId>netty-bom</artifactId>
109-
<version>4.1.126.Final</version> <!-- The patched version -->
110-
<type>pom</type>
111-
<scope>import</scope>
112-
</dependency>
113-
<dependency>
114-
<groupId>org.springframework.boot</groupId>
115-
<artifactId>spring-boot-dependencies</artifactId>
116-
...
117-
</dependency>
118-
```
119-
120-
By importing the `netty-bom` **before** the `spring-boot-dependencies` BOM, we force Maven to use our specified secure
121-
version for all Netty artifacts.
122-
123-
#### 2. CI/CD Scripting
124-
125-
The [`run-zap-scan.sh`](scripts/run-zap-scan.sh) script was designed to be portable and resilient. It solves several
126-
classic CI/CD challenges:
127-
128-
* **Docker Compose V1 vs V2:** It auto-detects whether to use `docker compose` or `docker-compose`.
129-
* **Environment Configuration:** It detects if it's running in GitHub Actions and creates a `.env` file from a
130-
committed, CI-specific template (`.env.ci`) to ensure a reproducible environment.
131-
* **File Permissions:** It correctly handles Linux file permission issues between the CI runner and the Docker container
132-
by adjusting permissions on the mounted reports directory.
29+
1. **Start with the `main` branch** to see the latest state of the project.
30+
2. To go back in time, use the **"Code & Docs" link** for a specific phase. This will show you the `README.md` for that
31+
phase, which contains the specific instructions and examples for that version of the code.
32+
3. To understand the *"why"* behind the changes, review the **Key Pull Requests** for each phase.
13333

13434
---
13535

136-
## Local Development & Quick Start
137-
138-
The prerequisites and setup are the same as in previous phases.
139-
140-
1. **Configure Local Hostnames (One-Time Setup, if not already done):**
141-
```
142-
127.0.0.1 keycloak.local
143-
```
144-
2. **Create and Configure Your Environment File:**
145-
```bash
146-
cp .env.example .env
147-
# ...then edit .env to add your WEB_CLIENT_SECRET from Keycloak.
148-
```
149-
3. **Build and run the entire stack:**
150-
```bash
151-
docker-compose up --build -d
152-
```
153-
4. **Access the Services:**
154-
* **Web Client Application:** [http://localhost:8082](http://localhost:8082)
155-
* **Swagger UI (New):** [http://localhost:8081/swagger-ui.html](http://localhost:8081/swagger-ui.html)
156-
* **OpenAPI Spec (New):** [http://localhost:8081/v3/api-docs](http://localhost:8081/v3/api-docs)
157-
* **Keycloak Admin Console:** [http://keycloak.local](http://keycloak.local) (Login with `admin`/`admin`)
158-
* **Prometheus UI:** [http://localhost:9090](http://localhost:9090)
159-
* **Alertmanager UI:** [http://localhost:9093](http://localhost:9093)
160-
* **Grafana UI:** [http://localhost:3000](http://localhost:3000)
161-
162-
---
163-
164-
## Validating the New Security Features
165-
166-
You can run the exact same scans that the CI pipeline does on your local machine.
167-
168-
1. **Run the SCA Scan:**
169-
```bash
170-
./mvnw clean verify
171-
```
172-
This will run all tests and the dependency-check scan. After it completes (the first run will be slow), you can find
173-
the HTML report at `resource-server/target/dependency-check-report.html`.
174-
175-
2. **Run the DAST Scan:**
176-
```bash
177-
# First, ensure all services are stopped
178-
docker-compose down -v
36+
## Running the Project
17937

180-
# Run the orchestration script
181-
./scripts/run-zap-scan.sh
182-
```
183-
The script will start the necessary services, run the scan, and shut them down. The report will be available at `reports/zap-report.html`.
38+
To run the application and see usage examples for the **current phase**, please refer to the detailed instructions in
39+
its tagged `README.md` file.
18440

185-
#### Stop the Environment
41+
**[>> Go to instructions for the current phase:
42+
`v7.0-continuous-security` <<](https://github.com/apenlor/spring-boot-security-observability-lab/tree/v7.0-continuous-security?tab=readme-ov-file#local-development--quick-start)
43+
**
18644

187-
```bash
188-
docker-compose down -v
189-
```
45+
As the lab progresses, this link will always be updated to point to the latest completed phase.

0 commit comments

Comments
 (0)