chore: pre-BSides cleanup

game_of_everything/AGENT.md → AGENT.md

@@ -14,60 +14,74 @@ The project is in active rewrite. There are two parallel codebases:
 
 ## v2 Architecture
 
-v2 models scenarios as a directed graph of **entities** (exploitable vulnerabilities) connected by **typed edges** (attacker capabilities). See `docs/rewrite/entity_graph_model.md` for full spec.
+v2 models scenarios as a directed graph of **entities** (exploitable vulnerabilities) connected by **typed edges** (attacker capabilities). See `docs/architecture/entity_graph_model.md` for full spec.
 
-### Current State (Phase 2 complete, Phase 3 next)
+### Current State (Phases 0–4 complete, Phase 5 next)
 
 **What works now:**
-- Single entity → full construction crew (Engineer/Opus → Developer/Sonnet → Attacker/Sonnet) → deploy → L2 test → retry escalation
+- Full end-to-end single-system flow: `goe.flow run "..."` → plan → build all entities → package output
+- Multi-system flow: parallel builds across systems, `TopologyEnvironment`, `docker-compose.yml` + `chain_playbook.yaml`
+- L3 chain test gates overall success; `chain_attacker` synthesizes end-to-end procedures
+- Checkpoint/resume: `--resume output/.checkpoints/<run_id>/`
+- Artifacts/eval: opt-in LLM conversation persistence and evaluation suites
 - 3 runtimes: Express (Node.js 20), Flask (Python 3), Apache/PHP
 - 13 web vulnerability atoms (SQLi, CMDi, XSS, SSTI, file upload, path traversal, deserialization, etc.)
-- Confirmed passing: SQLi/Express, CMDi/Flask, SQLi/PHP, XSS-stored/PHP, XSS-admin-bot/Express
-- `python -m goe.planner "..."` → validated entity graph YAML (all planning agents use Sonnet)
-- Static validator (7 checks), BuildScheduler (topological ordering + value propagation)
+- Confirmed passing single entities: SQLi/Express, CMDi/Flask, SQLi/PHP, XSS-stored/PHP, XSS-admin-bot/Express
 
-**What's next (Phase 3):**
-- Flow orchestrator: graph → build all entities → package output
-- `goe run "..."` CLI end-to-end
-- Deliverable: user request → validated deploy script + playbook
+**What's next (Phase 5 — Polish and Parity):**
+- Atom integration into construction crew (engineer receives relevant atoms via RAG)
+- EC2 deploy (port v1's `ec2_deploy.py`)
+- Cost optimization, observability, preset apps
 
 ### Key Components
 
 ```
 goe/
   bedrock.py              Direct boto3 Bedrock wrapper (no crewAI)
   build.py                Single-entity pipeline + CLI entry point
-  construction_crew/      Engineer → Developer → Attacker agents
+  construction_crew/      Engineer → Developer → Attacker agents (+ chain_attacker)
   executor/               Procedure DSL runner (HTTP, shell, browser)
   runtimes/               Deterministic deploy script generation
   retry/                  Diagnostician + escalation router
   container/              TestEnvironment adapter over v1 Docker tools
   graph/                  EntityGraph, validator (7 checks), topology, BuildScheduler
-  planner/                design_systems, plan_entities, specify_entities, connect_edges, resolve, pipeline
+  planner/                design_systems, plan_killchain, plan_entities, specify_entities, connect_edges, resolve, pipeline
+  flow/                   Orchestrator (plan → build → package), CLI entry point, checkpoint/resume
+  packaging/              deploy.sh + playbook.yaml + README generation
+  metrics/                MetricsSession, token/latency/cost instrumentation
+  artifacts/              Opt-in LLM conversation + file persistence
+  eval/                   Evaluation suites (build, planning, full)
+  services/               Shared service helpers
 ```
 
 ### Running v2
 
 ```bash
-# Plan an attack graph from natural language (requires AWS creds)
+# Full end-to-end run (requires AWS creds + Docker)
 cd game_of_everything
+.venv/bin/python -m goe.flow run "web app with SQL injection that leaks credentials"
+.venv/bin/python -m goe.flow run --verbose "SSH server with weak credentials and SUID privesc"
+.venv/bin/python -m goe.flow run --resume output/.checkpoints/<run_id>/
+
+# Re-test an existing output directory (no LLM — deploys in Docker and runs playbook)
+.venv/bin/python -m goe.flow test output/<run_id>/
+
+# Plan only (Steps 0–3, outputs graph YAML)
 .venv/bin/python -m goe.planner "web app with SQL injection leading to credential theft"
-.venv/bin/python -m goe.planner "..." --output graph.yaml --verbose
 
 # Build a single entity end-to-end
 .venv/bin/python -m goe.build --spec tests/fixtures/entities/sqli_express.yaml
 
-# Run the entity test suite (requires Docker + AWS creds)
-.venv/bin/pytest tests/test_build.py -v -m "llm and docker" -k "sqli"
-
 # Fast unit tests (no Docker, no LLM)
-.venv/bin/pytest tests/test_bedrock.py tests/test_runtimes.py -v
-.venv/bin/pytest tests/test_graph_models.py tests/test_topology.py tests/test_validator.py tests/test_build_scheduler.py tests/test_resolve.py tests/test_planner.py -v
+.venv/bin/python -m pytest -m "not docker and not llm"
+
+# Full test suite (requires Docker + AWS creds)
+.venv/bin/python -m pytest tests/
 ```
 
 ### Procedure DSL
 
-Attack procedures are YAML files with a strict schema. Actions: `http_request`, `exec_attacker`, `exec_attacker_bg` (detached background), `exec_target`, `listen`, `sleep`, browser actions (`navigate`, `click`, `fill_and_submit`, `evaluate`, etc.). See `docs/rewrite/goe_rewrite.md` for full DSL reference.
+Attack procedures are YAML files with a strict schema. Actions: `http_request`, `exec_attacker`, `exec_attacker_bg` (detached background), `exec_target`, `listen`, `sleep`, browser actions (`navigate`, `click`, `fill_and_submit`, `evaluate`, etc.). See `docs/architecture/v2_spec.md` for the full DSL reference.
 
 ### Runtime Templates
 
@@ -104,13 +118,13 @@ v1 uses crewAI Flow with a multi-agent pipeline. See `CLAUDE.md` for full v1 doc
 
 ## Implementation Roadmap
 
-See `docs/rewrite/implementation_plan.md` for the full phased plan with status.
+See `docs/architecture/v2_implementation_plan.md` for the full phased plan with status.
 
 | Phase | Status | Deliverable |
 |-------|--------|-------------|
 | 0 — Foundation | ✅ Complete | Models, executor, container adapter |
 | 1 — Construction Crew | ✅ Complete | Single entity E2E with retry |
-| 2 — Graph Planning | ✅ Complete | `goe plan "..."` → valid entity graph |
-| 3 — E2E Single System | ⬜ Planned | `goe run "..."` → deploy script + playbook |
-| 4 — Multi-System | ⬜ Planned | docker-compose + chain test |
-| 5 — Polish | ⬜ Planned | Atom RAG, EC2, cost optimization |
+| 2 — Graph Planning | ✅ Complete | `goe.planner "..."` → valid entity graph |
+| 3 — E2E Single System | ✅ Complete | `goe.flow run "..."` → deploy script + playbook |
+| 4 — Multi-System | ✅ Complete | docker-compose + chain test |
+| 5 — Polish and Parity | ⬜ Planned | Atom RAG, EC2, cost optimization, preset apps |

game_of_everything/CLAUDE.md → CLAUDE.md

@@ -2,6 +2,8 @@
 
 Guidance for Claude Code when working with this repository.
 
+> **Working directory**: all commands below are relative to `game_of_everything/` unless noted otherwise.
+
 ---
 
 ## GoE v2 (`goe/`) — Active Development Branch: `goe-rewrite`

CONTRIBUTING.md

@@ -0,0 +1,175 @@
+# Contributing to Game of Everything
+
+We welcome contributions from the broader community — whether you are fixing a bug, adding a new atom, or improving documentation.
+
+---
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Reporting Issues](#reporting-issues)
+- [Contributing Changes](#contributing-changes)
+  - [Branching](#branching)
+  - [Commit Messages](#commit-messages)
+  - [Pull Requests](#pull-requests)
+- [Development Setup](#development-setup)
+- [Running Tests](#running-tests)
+- [Project Areas](#project-areas)
+- [Research & Attribution](#research--attribution)
+
+---
+
+## Code of Conduct
+
+This project is a research and educational effort. All contributors are expected to engage respectfully and constructively. Harassment, discrimination, or hostile behavior of any kind will not be tolerated.
+
+---
+
+## Getting Started
+
+1. **Fork** the repository and clone your fork locally.
+2. Follow the [setup instructions in the README](README.md#installation) to install dependencies and configure your environment.
+3. Confirm your setup works by running the test suite (see [Running Tests](#running-tests)).
+4. Find something to work on — open issues, items labeled `good first issue`, or reach out to a maintainer.
+
+---
+
+## Reporting Issues
+
+Before opening a new issue, search existing issues to avoid duplicates.
+
+When filing a bug, include:
+- A clear, descriptive title
+- Steps to reproduce (including the prompt/scenario used if applicable)
+- Expected vs. actual behavior
+- Relevant log output (found in `output/<timestamp>.log`) — redact any credentials or AWS keys
+- Environment: OS, Python version, Docker version, AWS region
+
+For feature requests, describe the use case and the problem it solves rather than jumping straight to a proposed solution.
+
+---
+
+## Contributing Changes
+
+### Branching
+
+Branch off `main` for new work. Use the same `type/short-description` pattern used elsewhere in this repo:
+
+```
+feat/add-postgres-atom
+fix/chain-test-edge-propagation
+docs/update-contributing
+chore/bump-boto3
+```
+
+### Commit Messages
+
+Follow the [Conventional Commits](https://www.conventionalcommits.org/) format already established in this repository:
+
+```
+type(scope): short imperative description
+```
+
+| Type | When to use |
+|---|---|
+| `feat` | New feature or capability |
+| `fix` | Bug fix |
+| `docs` | Documentation only |
+| `test` | Adding or updating tests |
+| `refactor` | Code restructure with no behavior change |
+| `chore` | Build, deps, tooling, CI |
+
+**Examples from this repo:**
+```
+feat(tui): tui added + diagnostician improvements
+fix(attacker_container): ensure attacker container has necessary tools for testing loop
+docs(CLAUDE.md): update for Phase 4 completion + Phase 5 roadmap
+test(procedures): tests for basic execution, SSH logins, step chaining, and SUID privesc
+```
+
+Keep the subject line under 72 characters. Use the body for _why_, not _what_.
+
+### Pull Requests
+
+- Target `main` unless a maintainer directs otherwise.
+- PR titles follow the same `type(scope): description` format as commits.
+- Keep PRs focused — one logical change per PR.
+- Fill out the PR description with a summary of what changed and why.
+- All CI checks must pass before review.
+- At least one maintainer approval is required to merge.
+
+For large changes (new pipeline phase, new runtime, significant refactor), open an issue or draft PR first to discuss the approach before investing significant time.
+
+---
+
+## Development Setup
+
+```bash
+cd game_of_everything
+uv sync
+source .venv/bin/activate
+```
+
+Configure your environment:
+
+```bash
+cp goe.toml.example goe.toml
+# Fill in AWS credentials and model settings
+```
+
+Verify Bedrock access and ingest the RAG atom database before running the full pipeline:
+
+```bash
+python scripts/bedrock_access.py \
+  us.anthropic.claude-sonnet-4-6-20251001-v1:0 \
+  us.anthropic.claude-opus-4-6-v1:0 \
+  amazon.titan-embed-text-v2:0
+python scripts/rag_gen.py
+```
+
+See the [README](README.md) for full setup and command documentation.
+
+---
+
+## Running Tests
+
+The test suite is split by marker to separate fast unit tests from slow Docker/LLM tests:
+
+```bash
+# Fast unit tests (no Docker, no AWS)
+.venv/bin/python -m pytest -m "not docker and not llm"
+
+# Docker integration tests (~1-3 min each)
+.venv/bin/python -m pytest -m docker
+
+# Full suite (requires Docker + AWS credentials)
+.venv/bin/python -m pytest tests/
+```
+
+New features should include corresponding tests. Bug fixes should include a test that would have caught the bug.
+
+---
+
+## Project Areas
+
+| Area | Location | Notes |
+|---|---|---|
+| planner | `goe/planner/` | NL → EntityGraph; LLM prompts in `prompts/` |
+| construction crew | `goe/construction_crew/` | Engineer / Developer / Attacker agents |
+| flow & orchestration | `goe/flow/` | Run/resume pipeline, chain test |
+| retry & diagnostics | `goe/retry/` | Failure categorization and agent routing |
+| Misconfig/privesc atoms | `atoms/` | Markdown + YAML frontmatter |
+| Web vulnerability atoms | `atoms/web_vulnerabilities/` | Markdown + YAML frontmatter |
+| Runtime templates | `goe/runtimes/templates/` | Per-runtime install/start/healthcheck |
+| Docker images | `docker/` | Target and attacker Dockerfiles |
+
+When adding a new atom or runtime, follow the patterns documented in [CLAUDE.md](CLAUDE.md).
+
+---
+
+## Research & Attribution
+
+If you use this project in academic work, please cite it appropriately and reach out to the maintainers — we welcome collaboration and co-authorship opportunities with researchers building on this work.
+
+Contributions are accepted under the project's [GPLv3 license](LICENSE). By submitting a pull request you agree that your contributions will be licensed under the same terms.

README.md

@@ -18,7 +18,7 @@ Game of Everything is an agentic framework for building vulnerable cybersecurity
 - AWS account with access to **Amazon Bedrock** (Claude Sonnet/Opus models + `amazon.titan-embed-text-v2:0`)
 
 > **Bedrock model access**: Enable the following models in your AWS Bedrock console before first use:
-> `us.anthropic.claude-sonnet-4-6`, `us.anthropic.claude-opus-4-6-v1`, `amazon.titan-embed-text-v2:0`
+> `us.anthropic.claude-sonnet-4-6-20251001-v1:0`, `us.anthropic.claude-opus-4-6-v1:0`, `amazon.titan-embed-text-v2:0`
 
 ---
 
@@ -61,11 +61,12 @@ secret_access_key = ""
 region            = "us-east-1"
 
 [models]
-default = "anthropic.claude-sonnet-4-6"   # default Bedrock model for all agents
+# Use the full cross-region inference profile ID
+default = "us.anthropic.claude-sonnet-4-6-20251001-v1:0"
 
 [models.overrides]
-# Per-agent overrides — keys match agent names in config/agents.yaml
-# app_generation_agent = "anthropic.claude-opus-4-6-v1"
+# Per-role overrides — keys match role names in goe/config.py
+# engineer = "us.anthropic.claude-opus-4-6-v1:0"
 
 [deploy]
 instance_type     = "t3.medium"
@@ -74,12 +75,17 @@ security_group_id = ""        # auto-created if blank
 subnet_id         = ""        # auto-selected if blank
 ```
 
-Environment variables override toml values: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`, `GOE_DEFAULT_MODEL`, `GOE_MODEL_<AGENT_NAME>`.
+Environment variables override toml values: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`, `GOE_DEFAULT_MODEL`, `GOE_MODEL_<ROLE_NAME>`.
 
-### Verify Bedrock Access
+### Enable Bedrock Model Access
+
+Run this once per AWS account to accept model agreements and request entitlements:
 
 ```bash
-python scripts/bedrock_access.py
+python scripts/bedrock_access.py \
+  us.anthropic.claude-sonnet-4-6-20251001-v1:0 \
+  us.anthropic.claude-opus-4-6-v1:0 \
+  amazon.titan-embed-text-v2:0
 ```
 
 ---
@@ -130,7 +136,7 @@ crewai run
 | `--deploy ec2` | — | After generation, deploy the scenario to AWS EC2 |
 | `--review` | off | After script generation, pause for interactive per-box review before deploying |
 | `--ec2-region REGION` | `us-east-1` | AWS region for EC2 deployment |
-| `--ec2-instance-type TYPE` | `t3.medium` | EC2 instance type |
+| `--ec2-instance-type TYPE` | `t3.small` | EC2 instance type |
 | `--ec2-attacker-cidr CIDR` | `$GOE_ATTACKER_CIDR` | Your IP in CIDR notation — required for `--deploy ec2` |
 | `--ec2-ttl-hours N` | `4` | Auto-destroy TTL in hours (`0` = no auto-destroy) |
 
@@ -164,7 +170,7 @@ goe-deploy output/20260418_200538_<scenario_slug> --attacker-cidr 203.0.113.5/32
 |---|---|
 | `output_dir` (positional) | Path to the output directory containing `playbook.json` and `*_deploy.sh` files |
 | `--region REGION` | AWS region (default: `$GOE_EC2_REGION` or `us-east-1`) |
-| `--instance-type TYPE` | EC2 instance type (default: `$GOE_EC2_INSTANCE_TYPE` or `t3.medium`) |
+| `--instance-type TYPE` | EC2 instance type (default: `$GOE_EC2_INSTANCE_TYPE` or `t3.small`) |
 | `--attacker-cidr CIDR` | Your IP in CIDR notation — required |
 | `--ttl-hours N` | Auto-destroy TTL in hours (default: `$GOE_EC2_TTL_HOURS` or `4`) |
 
@@ -200,10 +206,10 @@ plot
 Pre-build the attacker container to separate build failures from test failures:
 
 ```bash
-python -m game_of_everything.main build_attacker_image
+build_attacker
 ```
 
-Per-runtime target images (`goe-target-express`, `goe-target-flask`, `goe-target-php`) and the browser sidecar image (`goe-browser`) are built automatically on first use. Images are cached for 7 days.
+All images (`goe-attacker`, `goe-target-express`, `goe-target-flask`, `goe-target-php`, `goe-browser`) are built on first use and skipped on subsequent runs if they already exist locally.
 
 ---