🛡️ prowler-test-lab

This organization is a purpose-built playground for validating Prowler's GitHub provider and any tooling that needs predictable, real-world GitHub states. It contains a curated mix of repositories that cover both "good" and "bad" security configurations so we can exercise pass/fail paths deterministically.

---

🎯 Top-Level Goals

• 🔍 Exercise Prowler's GitHub checks across authentication modes, org-level controls, and repo protections
• ⚠️ Provide deterministic failure cases (legacy/public repos) alongside compliant baselines
• 🚀 Offer a single command to rebuild the org state and execute the full regression matrix

All automation for this org lives in the repo we cloned from prowler-cloud/prowler, specifically scripts/github_test_plan.py.

---

📁 Repositories in the Org

• 🟢 platform-secure (public) — "golden path" repo. Branch protection enabled, CODEOWNERS present, Dependabot and Secret Scanning on
• 🔴 frontend-legacy (private) — intentionally misconfigured. No branch protection, no CODEOWNERS, security analysis disabled
• ✅ public-library (public) — compliant public example. SECURITY.md present, branch protection enabled, secret scanning on
• ❌ public-legacy (public) — public repo with deliberate gaps. Missing branch protection and SECURITY.md to trigger failures
• 📦 archived-reference (archived private) — covers the "inactive but archived" case with a snapshot repo

A security team is created when the automation has permission; all CODEOWNERS entries point to that team.

---

🏃‍♂️ Running the Test Harness

1. 📂 cd into your local clone of prowler

2. 🔑 Export the org-owner PAT:

   export PROWLER_LAB_PAT=<classic PAT with admin:org, repo, workflow, read:org, read:packages>

3. 🔐 Make sure the GitHub App credentials are present (created under PROWLER-LAB-APP2):

   ls ~/git/prowler-lab-app2.2025-09-26.private-key.pem

4. ⚡ Execute the harness:

   poetry run python scripts/github_test_plan.py \
     --org prowler-test-lab \
     --app-id 2022378 \
     --app-key-path ~/git/prowler-lab-app2.2025-09-26.private-key.pem

This will:

• ✨ Ensure each repository exists with the expected configuration
• 🔄 Reset org defaults (write permission baseline, MFA disabled)
• 🧪 Run the full Prowler matrix (PAT, GitHub App, org controls, repo checks, ASFF export, filtered severity run)
• 📝 Write human-readable results to output/github_test_plan_summary.md
• 💾 Drop individual CSV/JSON outputs per check into output/

⚠️ Note: MFA enforcement (org-wide 2FA) cannot be enabled because the org is on the free plan. The harness logs the 404 and records GH-ORG-02 as "Skipped".

---

📊 Interpreting Results

The summary file lists each test ID, status, and a short note:

• ✅ PASS means the check matched expectations
• ❌ FAIL indicates drift—for example, platform-secure currently fails repository_default_branch_requires_linear_history. Flip "Require linear history" on the main branch to restore a pass
• ⏭️ "Skipped" entries are intentional (lack of plan features)

Raw findings live in the CSV output for that test (e.g., output/GH-REP-SECURE-01.csv).

---

⚙️ Adjusting the Baseline

• 🆕 To add new scenarios: update scripts/github_test_plan.py (create another repo block, add expectations in run_all)
• 🔄 To reset the org: rerun the script; it idempotently reconciles repo settings
• 🧹 To clean outputs: remove the output/GH-* artifacts before re-running

---

🔐 Credentials at a Glance

• 🎫 PAT: exported as PROWLER_LAB_PAT, must be a classic token with the scopes listed above
• 🤖 GitHub App: PROWLER-LAB-APP2, App ID 2022378, private key at ~/git/prowler-lab-app2.2025-09-26.private-key.pem

---

💡 Feel free to tailor the repositories or expectations to your tooling needs, but keep the README updated so new contributors know the intended shape of the org.