|
| 1 | +# Project Specification: OWASP WrongSecrets |
| 2 | + |
| 3 | +## Overview |
| 4 | +OWASP WrongSecrets is a security training application focused on secret management challenges. The project is containerized and supports multiple deployment and development environments, including Docker, Kubernetes, Heroku, Fly.io, and Okteto. |
| 5 | +The application contains secrets and vulnerabilities for its users to find in order to learn about bad security practices. |
| 6 | + |
| 7 | +## Java context |
| 8 | + |
| 9 | +You are a Java developer that wants to use the latest LTS java syntax, using clean code that is easy to read, with coherent consistent classes. Yyou are a test driven developer that creates tests for everything that you build. |
| 10 | +you run tests every time that you are adding something new. |
| 11 | + |
| 12 | +--- |
| 13 | + |
| 14 | +## 1. Containerization & Docker |
| 15 | + |
| 16 | +### Dockerfiles |
| 17 | +- **Dockerfile**: Main build for the Java Spring Boot application. Uses multi-stage builds for optimized images. Supports build arguments for versioning and secret injection. |
| 18 | +- **Dockerfile.web**: Specialized for Heroku/Fly.io/CTF deployments, extends the main image and adds CTF-specific environment variables. |
| 19 | +- **Dockerfile_webdesktop** & **Dockerfile_webdesktopk8s**: Provide a web-based desktop environment with security tools for users, supporting both local and Kubernetes environments. |
| 20 | +- **k8s/challenge53/Dockerfile**: Custom Dockerfile for a specific challenge. |
| 21 | + |
| 22 | +### Build & Push Scripts |
| 23 | +- **.github/scripts/docker-create.sh**: Central script for building, tagging, and pushing Docker images. Supports different profiles (local, local-vault, kubernetes-vault, heroku, render, etc.) and multi-architecture builds via `docker buildx`. Handles secret injection using Docker BuildKit secrets. |
| 24 | +- **.github/scripts/docker-create-and-push.sh**: Automates building and pushing all containers. |
| 25 | + |
| 26 | +### Docker Compose |
| 27 | +- **src/main/resources/challenges/challenge-51/challenge51docker-compose.yml**: Used for challenge-specific multi-container orchestration. |
| 28 | + |
| 29 | +### Key Docker Concepts |
| 30 | +- Multi-stage builds for smaller images. |
| 31 | +- Use of ARG and ENV for secret and configuration injection. |
| 32 | +- BuildKit secrets for secure secret handling (with caveats for exposure). |
| 33 | +- Custom user and permissions for container security. |
| 34 | +- Support for both x86_64 and ARM64 architectures. |
| 35 | + |
| 36 | +--- |
| 37 | + |
| 38 | +## 2. Deployment Targets |
| 39 | + |
| 40 | +### Kubernetes |
| 41 | +- **k8s/**: Contains deployment manifests for running the app and challenges in Kubernetes clusters. |
| 42 | +- **k8s-vault-minikube-start.sh**: Script to start a local Vault instance in Minikube for development/testing. |
| 43 | +- **k8s/challenge53/Dockerfile**: Example of a challenge-specific container for Kubernetes. |
| 44 | + |
| 45 | +### Heroku |
| 46 | +- **heroku.yml**: Defines Heroku deployment configuration. |
| 47 | +- **Dockerfile.web**: Used for Heroku container builds. |
| 48 | + |
| 49 | +### Fly.io |
| 50 | +- **fly.toml**: Configuration for deploying the app to Fly.io using Docker images. |
| 51 | + |
| 52 | +### Okteto |
| 53 | +- **okteto/okteto.yml**: Defines development and deployment flows for Okteto cloud environments. |
| 54 | + |
| 55 | +### Render |
| 56 | +- **render.yaml**: Render.com deployment configuration. |
| 57 | + |
| 58 | +--- |
| 59 | + |
| 60 | +## 3. Development & Testing |
| 61 | + |
| 62 | +- **README.md**: Comprehensive instructions for local development, Docker usage, and running tests. |
| 63 | +- **pom.xml**: Maven build configuration for Java dependencies and plugins. |
| 64 | +- **cypress/**: End-to-end tests using Cypress, integrated with JUnit. |
| 65 | +- **.github/workflows/container_test.yml**: GitHub Actions workflow for automated container build and test. |
| 66 | + |
| 67 | +--- |
| 68 | + |
| 69 | +## 4. Security & Dependency Management |
| 70 | + |
| 71 | +- **OWASP Dependency-Check** and **CycloneDX**: Integrated for vulnerability and SBOM generation. |
| 72 | +- **.pre-commit-config.yaml**: Linting and security checks on commit. |
| 73 | + |
| 74 | +--- |
| 75 | + |
| 76 | +## 5. Agentic Plan for Containerization & Deployment |
| 77 | + |
| 78 | +### Step 1: Build |
| 79 | +- Use `./mvnw clean install` to build the Java application. |
| 80 | +- Use `.github/scripts/docker-create.sh` to build Docker images for different profiles (local, vault, k8s, etc.). |
| 81 | +- BuildKit secrets are injected at build time for certain challenges. |
| 82 | + |
| 83 | +### Step 2: Test |
| 84 | +- Run unit and integration tests via Maven. |
| 85 | +- Run Cypress E2E tests. |
| 86 | +- Use GitHub Actions for CI container builds and tests. |
| 87 | + |
| 88 | +### Step 3: Deploy |
| 89 | +- **Docker**: Run locally with `docker run -p 8080:8080 jeroenwillemsen/wrongsecrets:latest-no-vault`. |
| 90 | +- **Kubernetes**: Apply manifests from `k8s/` and use challenge-specific images as needed. |
| 91 | +- **Heroku/Fly.io/Render/Okteto**: Use respective configuration files for cloud deployment. |
| 92 | + |
| 93 | +### Step 4: Play/Operate |
| 94 | +- Access the app via browser (default port 8080 or 3000 for desktop). |
| 95 | +- Use the web desktop container for a pre-installed security tools environment. |
| 96 | + |
| 97 | +--- |
| 98 | + |
| 99 | +## 6. Key Files & Directories |
| 100 | +- `Dockerfile`, `Dockerfile.web`, `Dockerfile_webdesktop`, `Dockerfile_webdesktopk8s`, `k8s/challenge53/Dockerfile` |
| 101 | +- `.github/scripts/docker-create.sh`, `.github/scripts/docker-create-and-push.sh` |
| 102 | +- `k8s/`, `heroku.yml`, `fly.toml`, `okteto/okteto.yml`, `render.yaml` |
| 103 | +- `README.md`, `pom.xml`, `cypress/`, `.github/workflows/` |
| 104 | + |
| 105 | +--- |
| 106 | + |
| 107 | +## 7. References |
| 108 | +- [OWASP WrongSecrets GitHub](https://github.com/OWASP/wrongsecrets) |
| 109 | +- [Docker Hub](https://hub.docker.com/r/jeroenwillemsen/wrongsecrets) |
| 110 | +- [Project README](../README.md) |
| 111 | +description: |
| 112 | +globs: |
| 113 | +alwaysApply: false |
| 114 | +--- |
| 115 | + |
| 116 | +## 8. TODO: Test Coverage Improvements |
| 117 | + |
| 118 | +The following areas require additional or improved tests: |
| 119 | + |
| 120 | +- Ensure every challenge in `org.owasp.wrongsecrets.challenges` has a corresponding unit test in `src/test/java/org/owasp/wrongsecrets/challenges/`. |
| 121 | +- Add/expand tests for `SecurityConfig` and authentication flows (route protection, CSRF, login, etc.). |
| 122 | +- Add unit tests for `RuntimeEnvironment` logic, covering all environment and CTF settings. |
| 123 | +- Add tests for error handling and edge cases (invalid challenge IDs, misconfigured environments, missing secrets, etc.). |
| 124 | +- Expand integration tests for multi-component flows (challenge completion, scoring, UI updates). |
| 125 | +- Add tests for different Spring profiles (local, local-vault, kubernetes-vault, without-vault) to verify configuration-dependent behavior. |
| 126 | +- If REST APIs are exposed, add/expand tests for API endpoints and their OpenAPI/Swagger documentation. |
| 127 | +- Run a code coverage tool (e.g., JaCoCo) to identify and address untested classes and methods. |
0 commit comments