Skip to content

ARCHITECTURE_OVERVIEW.md

Latest commit

 

History

History
160 lines (121 loc) · 5.37 KB

ARCHITECTURE_OVERVIEW.md

File metadata and controls

160 lines (121 loc) · 5.37 KB

Architecture Overview

This document provides a quick reference for understanding the WrongSecrets project structure, testing patterns, build process, and key configuration files.

Project Structure

Core Package Organization

src/main/java/org/owasp/wrongsecrets/
├── challenges/                    # Challenge implementations and controllers
│   ├── cloud/                    # Cloud provider specific challenges (AWS, GCP, Azure)
│   ├── docker/                   # Docker-based challenges
│   ├── kubernetes/               # Kubernetes and Vault challenges
│   ├── Challenge.java            # Core challenge interface
│   ├── FixedAnswerChallenge.java # Abstract class for static answer challenges
│   └── ChallengesController.java # REST API endpoints for challenges
├── oauth/                        # OAuth authentication components
├── asciidoc/                     # Documentation generation utilities
├── canaries/                     # Security canary implementations
├── definitions/                  # Challenge definitions and metadata
└── [Core Application Files]      # Main application, security config, etc.

Key Responsibilities by Package

  • challenges/ - All challenge logic, grouped by deployment technology
  • oauth/ - GitHub OAuth integration for user authentication
  • asciidoc/ - AsciiDoc documentation generation and processing
  • canaries/ - Security monitoring and detection mechanisms
  • definitions/ - Challenge metadata, descriptions, and configuration

Testing Patterns

Test Organization

src/test/java/org/owasp/wrongsecrets/
├── challenges/                   # Challenge-specific unit tests
│   ├── cloud/                   # Cloud challenge tests
│   ├── docker/                  # Docker challenge tests
│   └── kubernetes/              # Kubernetes challenge tests
├── ChallengesControllerTest.java # API endpoint tests
├── SecurityConfigTest.java      # Security configuration tests
└── [Other Component Tests]      # Individual component unit tests

Test Types

  1. Unit Tests - Individual challenge logic testing (74+ test files)
  2. Integration Tests - Controller and API endpoint testing
  3. E2E Tests - Cypress tests in src/test/e2e/cypress/
  4. Container Tests - Docker and Kubernetes deployment validation

Test Naming Convention

  • Challenge tests: Challenge[Number]Test.java (e.g., Challenge44Test.java)
  • Controller tests: [Controller]Test.java (e.g., ChallengesControllerTest.java)
  • Component tests: [Component]Test.java

Build Process Overview

Maven → Docker Workflow

  1. Maven Build (pom.xml)

    • Spring Boot 4.x application
    • Dependencies managed through Spring Boot parent POM
    • Plugins: AsciiDoctor, Checkstyle, PMD, SpotBugs

  2. Docker Images

    • Dockerfile - Main application container
    • Dockerfile.web - Web-only variant (no vault dependencies)
    • Dockerfile_webdesktop - Desktop application variant
    • Dockerfile_webdesktopk8s - Kubernetes desktop variant

  3. Build Commands

    ./mvnw clean compile           # Compile sources
./mvnw test                    # Run unit tests
./mvnw package                 # Create JAR
docker build -t wrongsecrets . # Build container

Version Management

  • Version defined in pom.xml and synchronized across Dockerfiles
  • Automated version extraction in GitHub Actions
  • Snapshot versions for development, release versions for production

Key Configuration Files

Application Configuration

File Purpose
pom.xml Maven build configuration, dependencies, plugins
src/main/resources/application.properties Spring Boot application configuration
config/fbctf.yml Facebook CTF integration configuration

Code Quality & Standards

File Purpose
config/checkstyle/ Java code style rules and enforcement
config/zap/ OWASP ZAP security scanning configuration
.pre-commit-config.yaml Pre-commit hooks for code quality
eslint.config.mjs JavaScript/TypeScript linting rules

CI/CD Configuration

File Purpose
.github/workflows/ GitHub Actions workflow definitions
renovate.json Automated dependency updates
commitlint.config.js Commit message format enforcement

Deployment Configuration

File Purpose
heroku.yml Heroku deployment configuration
fly.toml Fly.io deployment configuration
render.yaml Render.com deployment configuration
app.json Heroku app configuration
k8s/ Kubernetes deployment manifests

Platform-Specific

Directory Purpose
aws/ AWS-specific deployment files and documentation
gcp/ Google Cloud Platform deployment configuration
azure/ Microsoft Azure deployment setup
okteto/ Okteto Kubernetes platform configuration

Development Environment Setup

Prerequisites

  • Java 25
  • Maven 3.9+
  • Docker
  • Node.js (for frontend dependencies)

Quick Setup

# Clone and build
git clone <repository>
cd wrongsecrets
./mvnw clean compile

# Run locally
./mvnw spring-boot:run

# Run tests
./mvnw test

For detailed setup instructions, see CONTRIBUTING.md.