| --- |
| title: redteampentestlab |
| emoji: "🛡️" |
| colorFrom: red |
| colorTo: yellow |
| sdk: docker |
| app_port: 8000 |
| pinned: false |
| --- |
| |
| # redteampentestlab |
|
|
| redteampentestlab is an OpenEnv-compatible reinforcement learning environment for automated penetration testing simulation. The agent must solve realistic pentest chains by executing actions in the correct order and collecting CTF-style flags. |
|
|
| ## Environment Description |
|
|
| The environment exposes a FastAPI server through OpenEnv and simulates three pentesting missions: |
|
|
| 1. Easy: Web Application Recon |
| 2. Medium: SQLi to RCE |
| 3. Hard: APT Multi-Stage Compromise |
|
|
| Each mission has: |
|
|
| - A target host or network |
| - A required ordered action chain |
| - Step-level rewards for partial progress |
| - A completion reward and a hidden flag |
|
|
| The reward design is shaped for RL training signals and remains strictly between 0 and 1. |
|
|
| ## Action Space |
|
|
| The action model accepts one of the following values: |
|
|
| - scan |
| - enumerate |
| - exploit |
| - escalate |
| - c2 |
| - cleanup |
|
|
| ## Observation Space |
|
|
| Each step returns an observation with: |
|
|
| - target_ip: current host or subnet under assessment |
| - current_state: BRIEFING, IN_PROGRESS, SUCCESS, INVALID, ORDER_VIOLATION, or REPEAT |
| - output: realistic pentest tool-style output for the executed action |
| - difficulty: easy, medium, or hard |
| - reward: scalar reward signal (strictly 0 < reward < 1) |
| - done: episode termination flag |
|
|
| ## State Space |
|
|
| Environment state includes: |
|
|
| - episode: episode counter |
| - task: active task name |
| - progress: normalized task completion value between 0.0 and 1.0 |
|
|
| ## Setup Instructions |
|
|
| ### Option A: pip |
|
|
| ```bash |
| pip install -r requirements.txt |
| uvicorn server.app:app --host 0.0.0.0 --port 8000 |
| ``` |
|
|
| ### Option B: uv |
|
|
| ```bash |
| uv sync |
| uv run uvicorn server.app:app --host 0.0.0.0 --port 8000 |
| ``` |
|
|
| ### Validate OpenEnv |
|
|
| ```bash |
| openenv validate |
| openenv validate --url http://localhost:8000 --json --verbose |
| ``` |
|
|
| ### Validate Decimal Bounds |
|
|
| ```bash |
| python task_validation.py |
| ``` |
|
|
| ## Inference and Grading |
|
|
| Run baseline inference: |
|
|
| ```bash |
| python inference.py |
| ``` |
|
|
| Run grader: |
|
|
| ```bash |
| python inference.py > out.txt && python grader.py out.txt |
| ``` |
|
|
| Inference also writes a structured pentest report to pentest_report.json. |
| |
| ## Environment Variables |
| |
| - API_BASE_URL (default: https://api.openai.com/v1) - API endpoint for the LLM |
| - MODEL_NAME (default: o3-mini) - Model identifier used for inference (OpenAI o3-mini) |
| - OPENAI_API_KEY (required) - OpenAI API key; if not set, falls back to HF_TOKEN |
| - HF_TOKEN (required if OPENAI_API_KEY not set) - Alternative API key environment variable |
|
|
| **Note:** At least one of OPENAI_API_KEY or HF_TOKEN must be set, or the inference will fail at startup. |
| |
| ## Docker |
| |
| ```bash |
| docker build -t redteampentestlab . |
| docker run -p 8000:8000 redteampentestlab |
| ``` |
