Clean up obsolete prompts, document sandbox configurations, and add GCE prerequisites

- Delete 4 obsolete prompts in reference/prompts/ while retaining system-researcher.md as canonical standalone prompt example.
- Document no-skill / custom system_prompt alternative in reference/README.md.
- Document golden-image prerequisites (passwordless sudo and python3 for isolation probe) in docs/gce_sandbox_setup.md.
- Document static-only, gvisor, microsandbox, and gce sandbox configurations with a comparison table in reference/README.md.
- Increase sandbox timeout_seconds default to 600s across workflow.json and documentation.
- Add fast preflight failure check in GceEnvironment for unconfigured default project placeholders (e.g. YOUR_PROJECT_ID).
- Add unit tests for no-skill prompt loading and placeholder project validation in reference/test_suite.py.

TAG=agy
CONV=3fecc2dd-b200-4a0c-b4c0-3a0868b5cc2a

Change-Id: If77748bc775a84411406604b750415de138dc933

Author: nickg-ca

reference/README.md

@@ -4,6 +4,31 @@ This directory contains a reference implementation of Mantis built directly on
 top of the **Agent Development Kit (ADK)** using the full suite of canonical
 **Mantis Skills** and **isolated sandboxed execution environments**.
 
+## Getting Started
+
+First, install python3-venv such as with `sudo apt install python3-venv`, then
+run the install script, and the Mantis pipeline as below. Before you do that,
+consider whether you want to use the default isolated GCE VM reproduction
+pipeline or whether you'd prefer another mechanism like gVisor/microsandbox or
+even static. Update `workflow.json` based on your choices. Ask a coding agent
+like antigravity or opencode or anything else to help you write a workflow
+configuration that works for you.
+
+```bash
+cd reference && ./install.sh
+export GOOGLE_CLOUD_PROJECT=your-gcp-project   # required: default model is vertex_ai/*
+gcloud auth application-default login  # if using ADC credentials
+./run.sh path/to/code            # a file or a directory
+```
+
+Once you have run it you can add the mantis-advise skill to your favorite coding
+agent and use that while developing your code to have your coding agent attempt
+to create fewer vulnerabilities. To try it manually you can run the script:
+
+```
+python3 scripts/advise.py --file path/to/file.py   # query accumulated knowledge
+```
+
 ## Core Pipeline Stages
 
 The pipeline in `workflow.json` orchestrates 16 canonical Mantis skills across
@@ -56,6 +81,80 @@ The reference harness implements ADK's `BaseEnvironment` interface:
   Networkless (`--network=none`), container-isolated filesystem at `/workspace`.
 - **`StaticOnlyEnvironment`**: Safe no-op environment for static-only scans.
 
+### Configuring the Sandbox Backend in `workflow.json`
+
+To change the sandbox backend, update the `"config.sandbox"` block in
+[`workflow.json`](workflow.json):
+
+#### 1. Static-Only (`"static-only"`)
+
+Zero dependencies. Dynamic exploit execution and patch testing are skipped.
+
+```json
+"sandbox": {
+  "type": "static-only"
+}
+```
+
+#### 2. gVisor (`"gvisor"`)
+
+Local OCI container isolation via Docker/Podman with gVisor `runsc` and
+`--network=none`.
+
+```json
+"sandbox": {
+  "type": "gvisor",
+  "options": {
+    "image": "mantis-sandbox:latest",
+    "runtime": "runsc",
+    "timeout_seconds": 600
+  }
+}
+```
+
+#### 3. MicroSandbox (`"microsandbox"`)
+
+In-process hardware microVM isolation via `libkrun` and `Network.none()`.
+
+```json
+"sandbox": {
+  "type": "microsandbox",
+  "options": {
+    "image": "mantis-sandbox:latest",
+    "timeout_seconds": 600
+  }
+}
+```
+
+#### 4. Hardened GCE VM (`"gce"`)
+
+Ephemeral cloud VM in an isolated VPC with link-local DNS blackholing.
+
+```json
+"sandbox": {
+  "type": "gce",
+  "options": {
+    "project": "YOUR_PROJECT_ID",
+    "zone": "us-central1-b",
+    "image": "mantis-sandbox-image",
+    "subnet": "mantis-isolated-subnet",
+    "workdir": "/workspace",
+    "tunnel_through_iap": true,
+    "no_service_account": true,
+    "no_external_ip": true,
+    "verify_isolation": true,
+    "timeout_seconds": 600
+  }
+}
+```
+
+| Sandbox Type         | Dynamic Execution | Prerequisites                                       |
+| :------------------- | :---------------: | :-------------------------------------------------- |
+| **`"static-only"`**  |        ❌         | None                                                |
+| **`"gvisor"`**       |        ✅         | Docker/Podman + `runsc` runtime                     |
+| **`"microsandbox"`** |        ✅         | Hardware virtualization (`/dev/kvm`)                |
+| **`"gce"`**          |        ✅         | GCP Project, Isolated VPC/Subnet, Custom Disk Image |
+
 ### Quickstart: Isolated GCE Sandbox Setup
 
 An automated setup script is provided at
@@ -164,3 +263,23 @@ tools:
 When compiled by `core/graph_loader.py`, each skill is loaded via
 `google.adk.skills.load_skill_from_dir` and attached to the agent as a
 `SkillToolset` connected to the active sandboxed environment.
+
+### No-Skill / Custom System Prompt Alternative
+
+As an alternative to loading a canonical Mantis skill directory,
+`core/graph_loader.py` also supports configuring an agent node with a custom
+markdown prompt file via `system_prompt` (such as
+[`prompts/system-researcher.md`](prompts/system-researcher.md)):
+
+```json
+{
+  "id": "researcher",
+  "type": "agent",
+  "system_prompt": "prompts/system-researcher.md",
+  "tools": ["read_file", "write_file", "list_files", "report_findings", "get_findings"]
+}
+```
+
+When `system_prompt` is specified instead of `skill`, `core/graph_loader.py`
+loads the agent's instructions directly from the given file and attaches the
+specified tools directly to the agent without instantiating a `SkillToolset`.

reference/core/environments/gce_env.py

@@ -183,13 +183,24 @@ async def preflight(self) -> None:
                 f"sandbox type 'gce' requires '{self.gcloud_bin}' on PATH. "
                 "Install Google Cloud SDK or set sandbox.type to 'static-only'."
             )
+        if self.project and self.project.strip().upper() in {"YOUR_PROJECT_ID", "YOUR_PROJECT", "<YOUR_PROJECT_ID>"}:
+            raise ValueError(
+                f"GCE sandbox project is set to default placeholder '{self.project}'. "
+                "Update 'options.project' in workflow.json with your actual GCP Project ID, or configure sandbox.type to 'static-only' or 'microsandbox'."
+            )
         if not self.project:
             rc, out = self._run_gcloud(["config", "get-value", "project"])
             if rc != 0 or not out.strip() or "unset" in out:
                 raise ValueError(
                     "GCP project not specified for GCE VM sandbox. Set options.project or GOOGLE_CLOUD_PROJECT env."
                 )
-            self.project = out.strip()
+            resolved_proj = out.strip()
+            if resolved_proj.upper() in {"YOUR_PROJECT_ID", "YOUR_PROJECT", "<YOUR_PROJECT_ID>"}:
+                raise ValueError(
+                    f"GCE sandbox project is set to default placeholder '{resolved_proj}'. "
+                    "Update 'options.project' in workflow.json with your actual GCP Project ID, or configure sandbox.type to 'static-only' or 'microsandbox'."
+                )
+            self.project = resolved_proj
 
         rc, out = self._run_gcloud(["auth", "list", "--filter=status:ACTIVE", "--format=value(account)"])
         if rc != 0 or not out.strip():

reference/docs/gce_sandbox_setup.md

@@ -32,13 +32,56 @@ export DEV_BUILD_VM="my-dev-build-vm"
 
 ______________________________________________________________________
 
-## 1. Assessment Disk Image Creation
+## 1. Assessment Disk Image Creation & Golden Image Prerequisites
+
+Before capturing your golden assessment disk image from the source build VM,
+ensure the following prerequisites are installed and configured:
+
+### Golden Image Prerequisites
+
+1. **Passwordless `sudo` (`NOPASSWD`)**:
+
+   - During instance initialization, `GceEnvironment` provisions the guest
+     workspace directory via SSH (`core/environments/gce_env.py:269`):
+     ```bash
+     sudo mkdir -p /workspace && sudo chown -R $(whoami) /workspace
+     ```
+   - The SSH user connecting to the sandbox VM must have passwordless `sudo`
+     rights in `/etc/sudoers` or `/etc/sudoers.d/` (e.g. standard
+     `%sudo ALL=(ALL) NOPASSWD:ALL` or `%admin ALL=(ALL) NOPASSWD:ALL`).
+     Standard GCP Ubuntu LTS images configure this by default for the
+     provisioning user.
+
+2. **`python3` Interpreter**:
+
+   - `GceEnvironment` runs automated active in-guest security isolation audits
+     (`_verify_guest_isolation()` in `core/environments/gce_env.py:338`) by
+     piping a base64-encoded isolation verification script directly to
+     `python3`:
+     ```bash
+     echo '<probe_script>' | base64 -d | python3 -
+     ```
+   - Ensure `python3` (or `python3-minimal`) is installed on the image and
+     available in `PATH` (`/usr/bin/python3`). Without `python3`, instance
+     startup fails fail-closed during guest isolation verification.
+
+3. **Pre-Warmed Build Tools & Dependencies**:
+
+   - Because the isolated VPC has zero external internet routing and no Cloud
+     NAT, all compilers, build runtimes, package manager caches, test
+     frameworks, and dependencies needed to compile the target repository and
+     reproduce vulnerabilities must be pre-installed and pre-built on the VM
+     before capturing the disk image.
+
+### Image Capture Workflow
 
 1. Provision a development VM with all necessary build runtimes, compilers,
    package managers, and test suites.
-2. Build your target repository on the VM to warm all local build caches,
+2. Confirm that passwordless `sudo` and `python3` are configured as described
+   above.
+3. Build your target repository on the VM to warm all local build caches,
    dependencies, and artifacts.
-3. Capture a custom disk image from the source build VM:
+4. Capture a custom disk image from the source build VM:
 
 ```bash
 gcloud compute images create "${IMAGE_NAME}" \

reference/prompts/system-calibrator.md

@@ -960,15 +960,22 @@ async def test_gce_sandbox_lifecycle_and_security_hardening(self):
                     await sb_no_proj.preflight()
                 self.assertIn("GCP project not specified", str(ctx_proj.exception))
 
-        # 2c. Fails when no active gcloud authentication
+        # 2c. Fails when GCP project is set to default placeholder (e.g. YOUR_PROJECT_ID)
+        sb_placeholder = GceSandbox(project="YOUR_PROJECT_ID", gcloud_bin="/usr/bin/gcloud")
+        with patch("shutil.which", return_value="/usr/bin/gcloud"):
+            with self.assertRaises(ValueError) as ctx_ph:
+                await sb_placeholder.preflight()
+            self.assertIn("default placeholder 'YOUR_PROJECT_ID'", str(ctx_ph.exception))
+
+        # 2d. Fails when no active gcloud authentication
         sb_auth_fail = GceSandbox(project="test-proj", gcloud_bin="/usr/bin/gcloud")
         sb_auth_fail._run_gcloud = MagicMock(return_value=(0, ""))
         with patch("shutil.which", return_value="/usr/bin/gcloud"):
             with self.assertRaises(RuntimeError) as ctx_auth:
                 await sb_auth_fail.preflight()
             self.assertIn("No active Google Cloud authentication found", str(ctx_auth.exception))
 
-        # 2d. Preflight passes when active account is found
+        # 2e. Preflight passes when active account is found
         sb_pass = GceSandbox(project="test-proj", gcloud_bin="/usr/bin/gcloud")
         sb_pass._run_gcloud = MagicMock(return_value=(0, "user@example.com\n"))
         with patch("shutil.which", return_value="/usr/bin/gcloud"):
@@ -2434,6 +2441,67 @@ def test_advise_cli_script_execution(self):
         finally:
             shutil.rmtree(temp_dir)
 
+    def test_no_skill_system_prompt_loading_and_execution(self):
+        """Validates loading an agent configured with system_prompt (prompts/system-researcher.md) without a skill."""
+        temp_dir = tempfile.mkdtemp()
+        try:
+            prompt_src = os.path.join(os.path.dirname(__file__), "prompts", "system-researcher.md")
+            self.assertTrue(os.path.exists(prompt_src), "prompts/system-researcher.md must exist as canonical no-skill example")
+
+            prompts_dir = os.path.join(temp_dir, "prompts")
+            os.makedirs(prompts_dir, exist_ok=True)
+            shutil.copy(prompt_src, os.path.join(prompts_dir, "system-researcher.md"))
+
+            workflow_def = {
+                "name": "no_skill_workflow",
+                "nodes": [
+                    {
+                        "id": "researcher",
+                        "type": "agent",
+                        "system_prompt": "prompts/system-researcher.md",
+                        "tools": ["read_file", "report_findings"]
+                    }
+                ],
+                "edges": [
+                    {"from": "START", "to": "researcher"}
+                ]
+            }
+            wf_path = os.path.join(temp_dir, "workflow.json")
+            with open(wf_path, "w") as f:
+                json.dump(workflow_def, f)
+
+            with patch.dict(os.environ, {"VERTEXAI_PROJECT": "test-project"}):
+                wf, cfg = load_workflow_from_json(wf_path)
+                self.assertIsNotNone(wf)
+                self.assertEqual(len(wf.edges), 1)
+                self.assertEqual(wf.edges[0].to_node.name, "researcher")
+                with open(prompt_src, "r", encoding="utf-8") as f:
+                    expected_instructions = f.read()
+                self.assertEqual(wf.edges[0].to_node.instruction, expected_instructions)
+
+            # Test fail-fast when system_prompt points to a missing file
+            bad_wf_def = {
+                "nodes": [
+                    {
+                        "id": "researcher_bad",
+                        "type": "agent",
+                        "system_prompt": "prompts/non_existent.md"
+                    }
+                ],
+                "edges": [
+                    {"from": "START", "to": "researcher_bad"}
+                ]
+            }
+            bad_wf_path = os.path.join(temp_dir, "bad_workflow.json")
+            with open(bad_wf_path, "w") as f:
+                json.dump(bad_wf_def, f)
+
+            with self.assertRaises(ValueError) as ctx:
+                load_workflow_from_json(bad_wf_path)
+            self.assertIn("System prompt not found", str(ctx.exception))
+        finally:
+            shutil.rmtree(temp_dir)
+
 
 if __name__ == "__main__":
     unittest.main()

reference/prompts/system-patcher.md

@@ -18,7 +18,7 @@
         "no_service_account": true,
         "no_external_ip": true,
         "verify_isolation": true,
-        "timeout_seconds": 60
+        "timeout_seconds": 600
       }
     }
   },