| --- |
| title: Purple Team Code Workbench |
|
|
| emoji: 🛠️ |
|
|
| colorFrom: purple |
| colorTo: indigo |
|
|
| sdk: streamlit |
| sdk_version: 1.57.0 |
|
|
| python_version: "3.11" |
|
|
| app_file: app.py |
|
|
| pinned: true |
|
|
| license: apache-2.0 |
|
|
| short_description: AI workbench for purple-team security workflows. |
|
|
| tags: |
| - cybersecurity |
| - purple-team |
| - defensive-security |
| - ai-security |
| - streamlit |
| - llm |
| - red-team |
| - blue-team |
| - security-research |
| - transformers |
| - generative-ai |
|
|
| models: |
| - DeepHat/DeepHat-V1-7B |
| - HauhauCS/Gemma-4-E4B-Uncensored-HauhauCS-Aggressive |
| - meta-llama/Meta-Llama-3-8B-Instruct |
|
|
| suggested_hardware: cpu-upgrade |
| suggested_storage: small |
|
|
| thumbnail: >- |
| https://cdn-uploads.huggingface.co/production/uploads/67c714e90b99a2332e310979/L02-prFfHa7eBZGVf4uvR.jpeg |
| --- |
| |
| # Purple Team Code Workbench |
|
|
| <p align="center"> |
| <img src="https://cdn-uploads.huggingface.co/production/uploads/67c714e90b99a2332e310979/L02-prFfHa7eBZGVf4uvR.jpeg" width="720" alt="Purple Team Code Workbench Banner"/> |
| </p> |
|
|
| <p align="center"> |
| <strong> |
| Streamlit-powered code generation and workflow orchestration |
| surface for authorized purple-team operations. |
| </strong> |
| </p> |
| |
| <p align="center"> |
| <img alt="Python" src="https://img.shields.io/badge/python-3.11%2B-blue"> |
| <img alt="Streamlit" src="https://img.shields.io/badge/streamlit-1.57.0-red"> |
| <img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-green"> |
| <img alt="Security" src="https://img.shields.io/badge/focus-purple--team-purple"> |
| </p> |
|
|
| --- |
|
|
| ## Overview |
|
|
| Purple Team Code Workbench is an AI-assisted cybersecurity experimentation environment designed for defensive researchers, purple-team operators, and security engineers. |
|
|
| The platform combines: |
|
|
| - LLM-driven code generation |
| - Workflow prototyping |
| - Adversarial simulation |
| - Structured findings management |
| - Report generation |
| - Human-in-the-loop operational control |
|
|
| inside a lightweight Streamlit interface. |
|
|
| This repository currently includes a working starter implementation with a scope gate, workflow prompt builder, structured findings manager, hash-linked evidence ledger, model profile panel, and Markdown report export. It is designed to run locally or as a Hugging Face Streamlit Space without requiring a GPU. |
|
|
| The architecture emphasizes modular orchestration, reproducible workflows, and human-supervised operational control. |
|
|
| The platform focuses on: |
|
|
| - Authorized assessment workflows |
| - Defensive and adversarial simulation support |
| - Code generation for security operations |
| - Evidence handling and finding management |
| - Prompt-assisted workflow acceleration |
| - Report artifact generation |
| - Research and analysis augmentation |
|
|
| The system is intentionally structured around controlled workflows rather than unrestricted autonomous execution. |
|
|
| --- |
|
|
| ## Why Purple Team? |
|
|
| Purple-team methodology combines offensive security simulation with defensive validation and detection engineering. |
|
|
| This workbench is designed to support collaborative workflows between: |
|
|
| - security researchers |
| - defenders |
| - detection engineers |
| - SOC analysts |
| - incident responders |
| - application security teams |
|
|
| The focus is operational learning, validation, and resilience improvement rather than isolated offensive capability. |
|
|
| --- |
|
|
| ## Safety & Intended Use |
|
|
| Purple Team Code Workbench is intended for: |
|
|
| - Authorized security testing |
| - Defensive security research |
| - Secure software experimentation |
| - Educational cybersecurity workflows |
| - Purple-team simulation and analysis |
|
|
| This project is not intended for: |
|
|
| - Unauthorized access |
| - Malware deployment |
| - Credential theft |
| - Persistence mechanisms |
| - Destructive operations |
| - Autonomous offensive activity |
|
|
| Users are responsible for complying with applicable laws, organizational policies, and authorization requirements. |
|
|
| --- |
|
|
| ## Non-Goals |
|
|
| This project is not intended to provide: |
|
|
| - autonomous offensive operations |
| - malware automation |
| - persistence tooling |
| - uncontrolled exploitation workflows |
| - credential harvesting systems |
|
|
| --- |
|
|
| ## Model Roles |
|
|
| | Model | Purpose | |
| |---|---| |
| | HauhauCS/Gemma-4-E4B-Uncensored-HauhauCS-Aggressive | Experimental reasoning and adversarial simulation support | |
| | DeepHat/DeepHat-V1-7B | Security-oriented coding and workflow assistance | |
| | meta-llama/Meta-Llama-3-8B-Instruct | General reasoning and structured instruction following | |
|
|
| --- |
|
|
| ## Runtime Environment |
|
|
| - Python 3.11 |
| - Streamlit 1.57.0 |
| - pandas |
| - CPU-compatible deployment |
| - Optional GPU acceleration if model inference is added later |
| - Hugging Face Streamlit Space compatibility |
|
|
| The included starter app is intentionally lightweight. It can run locally or inside a Hugging Face Space without requiring a GPU. |
|
|
| --- |
|
|
| ## Core Design Principles |
|
|
| ### Scope-First Architecture |
|
|
| Every workflow begins with explicit authorization and target definition. |
|
|
| The system is designed to reduce: |
|
|
| - accidental scope drift |
| - unsafe automation |
| - uncontrolled execution paths |
| - ambiguous operational state |
|
|
| --- |
|
|
| ### Human-in-the-Loop Control |
|
|
| The workbench assists analysts and engineers rather than replacing operational judgment. |
|
|
| Generation ≠ execution. |
|
|
| All generated output should be reviewed before use. |
|
|
| --- |
|
|
| ### Evidence-Centric Workflow |
|
|
| Outputs are treated as operational artifacts: |
|
|
| - findings |
| - prompts |
| - code snippets |
| - reports |
| - remediation notes |
| - validation records |
|
|
| The system emphasizes traceability and reproducibility over opaque AI behavior. |
|
|
| A tragically rare design choice in modern software tooling. |
|
|
| --- |
|
|
| ## Features |
|
|
| ### Current Capabilities |
|
|
| - Streamlit-based UI |
| - Scope-gated workflow controls |
| - Security code generation surface |
| - Passive recon helpers |
| - Structured findings management |
| - Markdown report export |
| - Multi-model workflow support |
| - Hugging Face Space deployment compatibility |
| - CPU-compatible starter runtime |
| - Session-state based local workflow records |
| - JSON, CSV, and Markdown exports |
|
|
| --- |
|
|
| ### Included Starter Files |
|
|
| The current starter package contains: |
|
|
| | File | Purpose | |
| |---|---| |
| | `app.py` | Main Streamlit application | |
| | `requirements.txt` | Python dependencies | |
| | `README.md` | Hugging Face Space metadata and project documentation | |
| | `.streamlit/config.toml` | Theme and server defaults | |
|
|
| The app does **not** call external model APIs by default. The configured model list is used as a profile/routing layer so inference can be added later without hiding provider behavior inside the UI. Because invisible API calls are how dashboards become haunted. |
|
|
| --- |
|
|
| ### Planned Capabilities |
|
|
| - Workflow templates |
| - Prompt chaining |
| - Agent orchestration |
| - Typed finding schemas |
| - Multi-provider inference routing |
| - Local LLM runtime support |
| - Evidence graphing |
| - Drift-aware execution state |
| - Report diff/version tracking |
| - LangGraph integration |
| - MCP-compatible tool surfaces |
|
|
| --- |
|
|
| ## Supported Models |
|
|
| Current configured models: |
|
|
| | Model | Purpose | |
| |---|---| |
| | HauhauCS/Gemma-4-E4B-Uncensored-HauhauCS-Aggressive | Experimental coding and reasoning | |
| | DeepHat/DeepHat-V1-7B | Security-oriented generation workflows | |
| | Meta-Llama-3-8B-Instruct | General-purpose assistant workflows | |
|
|
| Model availability depends on provider access and deployment configuration. |
|
|
| --- |
|
|
| ## Repository Structure |
|
|
| Current starter package: |
|
|
| ```text |
| . |
| ├── app.py |
| ├── requirements.txt |
| ├── README.md |
| └── .streamlit/ |
| └── config.toml |
| ``` |
|
|
| Recommended expanded structure: |
|
|
| ```text |
| . |
| ├── app.py |
| ├── requirements.txt |
| ├── README.md |
| ├── assets/ |
| ├── workflows/ |
| ├── prompts/ |
| ├── reports/ |
| ├── utils/ |
| ├── components/ |
| └── tests/ |
| ``` |
|
|
| Recommended modularization: |
|
|
| | Directory | Purpose | |
| |---|---| |
| | workflows/ | Workflow orchestration logic | |
| | prompts/ | Prompt templates and chains | |
| | reports/ | Generated report artifacts | |
| | utils/ | Shared utilities | |
| | components/ | Streamlit UI components | |
| | assets/ | Static images and branding | |
| | tests/ | Unit tests and workflow validation checks | |
|
|
| --- |
|
|
| ## Installation |
|
|
| ### Local Development |
|
|
| Clone the repository: |
|
|
| ```bash |
| git clone https://github.com/your-org/purple-team-code-workbench.git |
| cd purple-team-code-workbench |
| ``` |
|
|
| Create a virtual environment: |
|
|
| ```bash |
| python -m venv .venv |
| ``` |
|
|
| Activate the environment: |
|
|
| #### Linux/macOS |
|
|
| ```bash |
| source .venv/bin/activate |
| ``` |
|
|
| #### Windows PowerShell |
|
|
| ```powershell |
| .venv\Scripts\Activate.ps1 |
| ``` |
|
|
| #### Windows Command Prompt |
|
|
| ```cmd |
| .venv\Scripts\activate.bat |
| ``` |
|
|
| Install dependencies: |
|
|
| ```bash |
| pip install -r requirements.txt |
| ``` |
|
|
| Run the application: |
|
|
| ```bash |
| streamlit run app.py |
| ``` |
|
|
| --- |
|
|
| ## Hugging Face Spaces Deployment |
|
|
| This repository is compatible with: |
|
|
| - Hugging Face Streamlit Spaces |
| - CPU deployments |
| - OAuth-enabled Spaces |
| - External inference providers |
|
|
| The README front matter already includes Space metadata: |
|
|
| ```yaml |
| sdk: streamlit |
| sdk_version: 1.57.0 |
| python_version: "3.11" |
| app_file: app.py |
| license: apache-2.0 |
| suggested_hardware: cpu-upgrade |
| suggested_storage: small |
| ``` |
|
|
| Basic deployment path: |
|
|
| 1. Create a new Hugging Face Space. |
| 2. Select **Streamlit** as the SDK. |
| 3. Upload `app.py`, `requirements.txt`, `README.md`, and `.streamlit/config.toml`. |
| 4. Confirm the Space builds against Python 3.11 and Streamlit 1.57.0. |
| 5. Add secrets only if external inference providers are integrated later. |
|
|
| --- |
|
|
| ## Inference Providers |
|
|
| The starter app does not include live inference calls by default. |
|
|
| Future provider integrations may use: |
|
|
| - Hugging Face Inference Providers |
| - External API routing |
| - Local runtime configuration |
| - OAuth authentication state |
| - Deployment hardware constraints |
|
|
| Recommended provider design: |
|
|
| - keep API keys in environment variables or Space secrets |
| - separate provider logic from UI components |
| - log model profile, prompt template, and output metadata |
| - avoid storing secrets in reports, findings, or exported prompt artifacts |
| - treat model output as untrusted until reviewed |
|
|
| --- |
|
|
| ## Recommended Operational Controls |
|
|
| If deploying in production environments: |
|
|
| - Require authentication |
| - Log workflow activity |
| - Separate trusted/untrusted prompts |
| - Sandbox execution environments |
| - Restrict outbound networking |
| - Validate generated artifacts |
| - Maintain immutable audit trails |
| - Enforce scoped execution policies |
| - Require approval before provider calls |
| - Prevent secrets from entering exported reports |
| - Separate draft generation from operational action |
|
|
| --- |
|
|
| ## Example Workflow |
|
|
| ```text |
| Scope Definition |
| ↓ |
| Passive Recon |
| ↓ |
| Evidence Collection |
| ↓ |
| Finding Classification |
| ↓ |
| Code / Prompt Generation |
| ↓ |
| Human Validation |
| ↓ |
| Report Export |
| ``` |
|
|
| --- |
|
|
| ## Data Handling |
|
|
| By default, the starter app stores records in Streamlit session state. |
|
|
| That means: |
|
|
| - records persist only for the active session |
| - exports should be downloaded before closing or refreshing the session |
| - no database is configured by default |
| - no external telemetry is implemented by default |
|
|
| For production use, add explicit persistence through a controlled backend such as SQLite, PostgreSQL, Supabase, or another approved datastore. |
|
|
| --- |
|
|
| ## Exported Artifacts |
|
|
| The current app can export: |
|
|
| - workflow prompts as Markdown |
| - findings as JSON |
| - findings as CSV |
| - findings as Markdown |
| - evidence ledger as JSON |
| - full report as Markdown |
|
|
| All exported artifacts should be reviewed before use in client reports, internal tickets, detection engineering tasks, or remediation workflows. |
|
|
| --- |
|
|
| ## Testing & Quality Checks |
|
|
| Suggested local checks: |
|
|
| ```bash |
| python -m py_compile app.py |
| streamlit run app.py |
| ``` |
|
|
| Recommended future checks: |
|
|
| ```bash |
| python -m pip install ruff pytest bandit pip-audit |
| ruff check . |
| bandit -r . |
| pip-audit |
| pytest |
| ``` |
|
|
| For now, the starter package is intentionally small, so the primary validation path is syntax checking plus manual UI testing. |
|
|
| --- |
|
|
| ## Development Roadmap |
|
|
| ### Phase 1 |
|
|
| - Scope-gated workflows |
| - Findings management |
| - Report export |
| - Prompt surface |
| - Evidence ledger |
|
|
| ### Phase 2 |
|
|
| - Agent coordination |
| - Structured memory |
| - Typed contracts |
| - Multi-model routing |
|
|
| ### Phase 3 |
|
|
| - Drift-aware orchestration |
| - Evidence graphs |
| - Policy enforcement engine |
| - Autonomous validation loops |
|
|
| --- |
|
|
| ## Contributing |
|
|
| Contributions should prioritize: |
|
|
| - clarity |
| - safety |
| - reproducibility |
| - deterministic behavior |
| - typed interfaces |
| - operational traceability |
|
|
| Before submitting: |
|
|
| - run linting |
| - validate workflows |
| - document assumptions |
| - avoid opaque automation behavior |
| - confirm no unsafe workflow bypasses were introduced |
| - keep generated content reviewable by humans |
|
|
| --- |
|
|
| ## License |
|
|
| Licensed under the Apache 2.0 License. |
|
|
| See the LICENSE file for details. |
|
|
| --- |
|
|
| ## Disclaimer |
|
|
| This project is provided for authorized security research, defensive engineering, and educational purposes only. |
|
|
| The maintainers assume no liability for misuse, unauthorized deployment, or operational damage caused by derivative implementations. |
|
|
| Generated outputs may contain inaccuracies, insecure assumptions, or incomplete implementations. |
|
|
| Human review is required before production or operational use. |
|
|
| --- |
|
|
| ## Acknowledgements |
|
|
| Built with: |
|
|
| - Streamlit |
| - Hugging Face |
| - Python Software Foundation |
|
|
| Inspired by structured operational engineering, purple-team methodology, and the stubborn belief that security tooling should behave like systems engineering rather than ritual magic. |
