Skip to content

Commit ae8837b

Browse files
commjoencommjoen
authored
Merge pull request #2117 from OWASP/copilot/fix-2116
docs: Add comprehensive documentation for AI agent efficiency
2 parents c95f2a6 + 5384f38 commit ae8837b

File tree

4 files changed

+647
-4
lines changed

4 files changed

+647
-4
lines changed

‎CONTRIBUTING.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ This document describes how you can contribute to WrongSecrets. Please read it c
77

88
**Table of Contents**
99

10+
- [Quick Start for Contributors](#quick-start-for-contributors)
1011
- [How to Contribute to the Project](#how-to-contribute-to-the-project)
1112
- [How to set up your Contributor Environment](#how-to-set-up-your-contributor-environment)
1213
- [How to get your PR Accepted](#how-to-get-your-pr-accepted)
@@ -16,6 +17,77 @@ This document describes how you can contribute to WrongSecrets. Please read it c
1617
- [Pictorial Guide on how to get started with the project in IntelliJ IDEA](#How-to-get-started-with-the-project-in-IntelliJ-IDEA)
1718
- [How to add a Challenge](#how-to-add-a-challenge)
1819

20+
## Quick Start for Contributors
21+
22+
New to the project? Get up and running quickly with these essential steps:
23+
24+
### 🚀 Immediate Setup (5 minutes)
25+
26+
```bash
27+
# 1. Clone the repository
28+
git clone https://github.com/OWASP/wrongsecrets.git
29+
cd wrongsecrets
30+
31+
# 2. Build and verify everything works
32+
./mvnw clean compile
33+
./mvnw test -Dtest=ChallengesControllerTest
34+
35+
# 3. Run the application locally
36+
./mvnw spring-boot:run
37+
# Visit http://localhost:8080 to see the app running
38+
```
39+
40+
### 📚 Essential Reading (10 minutes)
41+
42+
Before diving in, familiarize yourself with:
43+
44+
1. **[Architecture Overview](docs/ARCHITECTURE_OVERVIEW.md)** - Project structure and key components
45+
2. **[Development Patterns](docs/DEVELOPMENT_PATTERNS.md)** - Code patterns and conventions
46+
3. **[How to add a Challenge](#how-to-add-a-challenge)** (this document) - Challenge creation guide
47+
48+
### 🛠️ Development Workflow
49+
50+
1. **Check existing issues** - Look for `help wanted` or `good first issue` labels
51+
2. **Create a feature branch** - `git checkout -b feature/your-feature-name`
52+
3. **Make small, focused changes** - Follow the patterns in existing code
53+
4. **Test your changes** - Run relevant tests before submitting
54+
5. **Submit a PR** - Include clear description and link to related issue
55+
56+
### 🔧 Common Development Commands
57+
58+
```bash
59+
# Build and test
60+
./mvnw clean compile test
61+
62+
# Run specific test
63+
./mvnw test -Dtest=Challenge44Test
64+
65+
# Run with specific profile
66+
./mvnw spring-boot:run -Dspring.profiles.active=docker
67+
68+
# Check code style
69+
./mvnw checkstyle:check
70+
71+
# Format code (if pre-commit hooks configured)
72+
pre-commit run --all-files
73+
```
74+
75+
### 💡 Quick Tips
76+
77+
- **Challenges are in** `src/main/java/org/owasp/wrongsecrets/challenges/`
78+
- **Tests mirror source structure** in `src/test/java/`
79+
- **Most challenges extend** `FixedAnswerChallenge` for simple cases
80+
- **Use existing patterns** - check similar challenges for guidance
81+
- **Environment detection** is handled automatically via `RuntimeEnvironment`
82+
83+
### 🆘 Getting Help
84+
85+
- **Slack**: Join the OWASP Slack and find the #project-wrongsecrets channel
86+
- **GitHub Discussions**: Ask questions in the repository discussions
87+
- **Issues**: Comment on existing issues or create new ones for questions
88+
89+
---
90+
1991
## How to Contribute to the project
2092

2193
There are a couple of ways on how you can contribute to the project:

‎docs/ARCHITECTURE_OVERVIEW.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# Architecture Overview
2+
3+
This document provides a quick reference for understanding the WrongSecrets project structure, testing patterns, build process, and key configuration files.
4+
5+
## Project Structure
6+
7+
### Core Package Organization
8+
9+
```
10+
src/main/java/org/owasp/wrongsecrets/
11+
├── challenges/ # Challenge implementations and controllers
12+
│ ├── cloud/ # Cloud provider specific challenges (AWS, GCP, Azure)
13+
│ ├── docker/ # Docker-based challenges
14+
│ ├── kubernetes/ # Kubernetes and Vault challenges
15+
│ ├── Challenge.java # Core challenge interface
16+
│ ├── FixedAnswerChallenge.java # Abstract class for static answer challenges
17+
│ └── ChallengesController.java # REST API endpoints for challenges
18+
├── oauth/ # OAuth authentication components
19+
├── asciidoc/ # Documentation generation utilities
20+
├── canaries/ # Security canary implementations
21+
├── definitions/ # Challenge definitions and metadata
22+
└── [Core Application Files] # Main application, security config, etc.
23+
```
24+
25+
### Key Responsibilities by Package
26+
27+
- **`challenges/`** - All challenge logic, grouped by deployment technology
28+
- **`oauth/`** - GitHub OAuth integration for user authentication
29+
- **`asciidoc/`** - AsciiDoc documentation generation and processing
30+
- **`canaries/`** - Security monitoring and detection mechanisms
31+
- **`definitions/`** - Challenge metadata, descriptions, and configuration
32+
33+
## Testing Patterns
34+
35+
### Test Organization
36+
37+
```
38+
src/test/java/org/owasp/wrongsecrets/
39+
├── challenges/ # Challenge-specific unit tests
40+
│ ├── cloud/ # Cloud challenge tests
41+
│ ├── docker/ # Docker challenge tests
42+
│ └── kubernetes/ # Kubernetes challenge tests
43+
├── ChallengesControllerTest.java # API endpoint tests
44+
├── SecurityConfigTest.java # Security configuration tests
45+
└── [Other Component Tests] # Individual component unit tests
46+
```
47+
48+
### Test Types
49+
50+
1. **Unit Tests** - Individual challenge logic testing (74+ test files)
51+
2. **Integration Tests** - Controller and API endpoint testing
52+
3. **E2E Tests** - Cypress tests in `src/test/e2e/cypress/`
53+
4. **Container Tests** - Docker and Kubernetes deployment validation
54+
55+
### Test Naming Convention
56+
57+
- Challenge tests: `Challenge[Number]Test.java` (e.g., `Challenge44Test.java`)
58+
- Controller tests: `[Controller]Test.java` (e.g., `ChallengesControllerTest.java`)
59+
- Component tests: `[Component]Test.java`
60+
61+
## Build Process Overview
62+
63+
### Maven → Docker Workflow
64+
65+
1. **Maven Build** (`pom.xml`)
66+
- Spring Boot 3.x application
67+
- Dependencies managed through Spring Boot parent POM
68+
- Plugins: AsciiDoctor, Checkstyle, PMD, SpotBugs
69+
70+
2. **Docker Images**
71+
- `Dockerfile` - Main application container
72+
- `Dockerfile.web` - Web-only variant (no vault dependencies)
73+
- `Dockerfile_webdesktop` - Desktop application variant
74+
- `Dockerfile_webdesktopk8s` - Kubernetes desktop variant
75+
76+
3. **Build Commands**
77+
```bash
78+
./mvnw clean compile # Compile sources
79+
./mvnw test # Run unit tests
80+
./mvnw package # Create JAR
81+
docker build -t wrongsecrets . # Build container
82+
```
83+
84+
### Version Management
85+
86+
- Version defined in `pom.xml` and synchronized across Dockerfiles
87+
- Automated version extraction in GitHub Actions
88+
- Snapshot versions for development, release versions for production
89+
90+
## Key Configuration Files
91+
92+
### Application Configuration
93+
94+
| File | Purpose |
95+
|------|---------|
96+
| `pom.xml` | Maven build configuration, dependencies, plugins |
97+
| `src/main/resources/application.properties` | Spring Boot application configuration |
98+
| `config/fbctf.yml` | Facebook CTF integration configuration |
99+
100+
### Code Quality & Standards
101+
102+
| File | Purpose |
103+
|------|---------|
104+
| `config/checkstyle/` | Java code style rules and enforcement |
105+
| `config/zap/` | OWASP ZAP security scanning configuration |
106+
| `.pre-commit-config.yaml` | Pre-commit hooks for code quality |
107+
| `eslint.config.mjs` | JavaScript/TypeScript linting rules |
108+
109+
### CI/CD Configuration
110+
111+
| File | Purpose |
112+
|------|---------|
113+
| `.github/workflows/` | GitHub Actions workflow definitions |
114+
| `renovate.json` | Automated dependency updates |
115+
| `commitlint.config.js` | Commit message format enforcement |
116+
117+
### Deployment Configuration
118+
119+
| File | Purpose |
120+
|------|---------|
121+
| `heroku.yml` | Heroku deployment configuration |
122+
| `fly.toml` | Fly.io deployment configuration |
123+
| `render.yaml` | Render.com deployment configuration |
124+
| `app.json` | Heroku app configuration |
125+
| `k8s/` | Kubernetes deployment manifests |
126+
127+
### Platform-Specific
128+
129+
| Directory | Purpose |
130+
|-----------|---------|
131+
| `aws/` | AWS-specific deployment files and documentation |
132+
| `gcp/` | Google Cloud Platform deployment configuration |
133+
| `azure/` | Microsoft Azure deployment setup |
134+
| `okteto/` | Okteto Kubernetes platform configuration |
135+
136+
## Development Environment Setup
137+
138+
### Prerequisites
139+
140+
- Java 21+
141+
- Maven 3.8+
142+
- Docker
143+
- Node.js (for frontend dependencies)
144+
145+
### Quick Setup
146+
147+
```bash
148+
# Clone and build
149+
git clone <repository>
150+
cd wrongsecrets
151+
./mvnw clean compile
152+
153+
# Run locally
154+
./mvnw spring-boot:run
155+
156+
# Run tests
157+
./mvnw test
158+
```
159+
160+
For detailed setup instructions, see [CONTRIBUTING.md](../CONTRIBUTING.md).

0 commit comments

Comments
 (0)