Skip to content

.copilot-instructions.md

Latest commit

 

History

History
189 lines (143 loc) · 6.01 KB

.copilot-instructions.md

File metadata and controls

189 lines (143 loc) · 6.01 KB

Copilot Instructions for OWASP WrongSecrets Binaries

This repository creates educational binary executables with intentionally hardcoded secrets for the OWASP WrongSecrets project. These binaries are used in CTF (Capture The Flag) challenges to teach security professionals about reverse engineering and binary analysis.

Repository Purpose & Context

  • Primary Goal: Generate cross-platform binaries with embedded secrets for security education
  • Target Audience: Security professionals, CTF participants, reverse engineering students
  • Supported Platforms: Linux (x64/ARM), macOS (Intel/ARM), Windows (x64), Musl Linux
  • Output: Static executables that can be analyzed to discover hardcoded secrets

Project Structure

Programming Languages & Directories

  • c/ - C implementations with basic, advanced, and challenge52 variants
  • cplus/ - C++ implementations
  • golang/ - Go implementations with CLI structure
  • rust/ - Rust implementations with Cargo workspace
  • dotnet/ - .NET/C# implementations
  • swift/ - Swift implementations

Key Files

  • generate_ctf_secrets.sh - Generates randomized secrets for CTF versions
  • quickbuild.sh - Local multi-platform build script (requires macOS with GCC)
  • test_ctf_generation.sh - Tests CTF secret generation functionality
  • .pre-commit-config.yaml - Automated code formatting configuration

Development Workflow

Before Making Changes

  1. Install pre-commit hooks: pip install pre-commit && pre-commit install
  2. Test basic compilation: gcc c/main.c -o test-binary
  3. Check existing workflows: Review .github/workflows/ for language-specific builds

Code Standards & Formatting

  • Rust: Automatically formatted with cargo fmt via pre-commit
  • Go: Automatically formatted with gofmt via pre-commit + go mod tidy
  • C/C++: Follow existing style, no automatic formatting configured
  • All code: Must pass pre-commit hooks before committing

Building & Testing

  • Local builds: Use appropriate language tools (make, cargo build, go build, dotnet build)
  • Cross-platform: Use quickbuild.sh (macOS) or GitHub Actions
  • CTF testing: Run ./test_ctf_generation.sh to verify CTF secret generation
  • CI/CD: Each language has dedicated GitHub Actions workflow

Security & Secrets Guidelines

Working with Intentional Vulnerabilities

  • By Design: Hardcoded secrets are INTENTIONAL - this is educational software
  • Secret Formats: Regular secrets use descriptive text, CTF secrets use format this is the secret in <language> : <random_hex>
  • Never: Remove or "fix" the intentional vulnerabilities - they're the educational content
  • CTF Generation: Use the provided script to generate randomized secrets for competitions

Best Practices

  • Keep hardcoded secrets clearly educational (not real credentials)
  • Maintain consistent secret formats across languages
  • Preserve the ability to analyze binaries with common reverse engineering tools
  • Document any new secret hiding techniques for educational purposes

Language-Specific Guidelines

C (directory: c/)

# Build basic version
cd c && make

# Build with custom flags
cd c && make CFLAGS+='-target x86_64-apple-macos12'

# Build advanced version  
cd c/advanced && make

Rust (directory: rust/)

# Format code (required before commit)
cargo fmt

# Build all targets
cargo build --release

# Run tests
cargo test

Go (directory: golang/)

# Format code (required before commit) 
gofmt -w .
go mod tidy

# Build binary
go build -o wrongsecrets-go

# Test compilation
go build ./...

.NET (directory: dotnet/)

# Build solution
dotnet build

# Publish for specific runtime
dotnet publish -r linux-x64 --self-contained

# Run tests (if present)
dotnet test

Docker & Cross-Compilation

Using Dockcross

The repository uses dockcross for cross-compilation:

# Example ARM Linux compilation
./dockcross-linux-arm64-lts bash -c '$CC c/main.c -o target/wrongsecrets-c-linux-arm'

Supported Platforms

  • Linux x64/ARM64
  • Windows x64 (static linking)
  • macOS Intel/ARM
  • Musl Linux (Alpine-compatible)

CTF Secret Generation

Regular vs CTF Versions

  • Regular: Human-readable secrets like "This is a hardcoded secret in C"
  • CTF: Randomized format: "this is the secret in c : a1b2c3d4e5f6"

Using the CTF System

# Generate CTF secrets (modifies source files)
./generate_ctf_secrets.sh generate

# Build CTF versions
# ... perform builds ...

# Restore original secrets
./generate_ctf_secrets.sh restore

# Test the entire process
./test_ctf_generation.sh

Common Tasks & Commands

Full Build Process

# Install dependencies
pip install pre-commit
pre-commit install

# Format code
pre-commit run --all-files

# Test basic compilation
gcc c/main.c -o test-binary
cd rust && cargo build
cd golang && go build

# Generate and test CTF versions
./test_ctf_generation.sh

Adding New Languages

  1. Create directory with source files containing hardcoded secrets
  2. Add GitHub Actions workflow in .github/workflows/compile_<language>.yml
  3. Update generate_ctf_secrets.sh to handle the new language's secret patterns
  4. Add build commands to quickbuild.sh
  5. Test both regular and CTF compilation

Troubleshooting

  • Build failures: Check GitHub Actions logs for specific platform issues
  • Secret generation: Ensure backup files exist before running CTF generation
  • Cross-compilation: Verify dockcross containers are available
  • Pre-commit: Run pre-commit run --all-files to fix formatting issues

Important Notes

⚠️ This repository contains intentional security vulnerabilities for educational purposes.

  • Do NOT deploy these binaries in production environments
  • Secrets are hardcoded by design - this is NOT a security bug
  • The repository is for learning about binary analysis and reverse engineering
  • Always restore original files after CTF generation testing