From d4335a0dc4d3ef8504271075fe7ab9d2b400328a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 9 Mar 2026 14:40:51 +0000
Subject: [PATCH 1/3] Add pentest verification document system for Claude Code
 authorization

Adds a fillable verification.env config and verification.md template that
renders into an active authorization document (.claude/verification-active.md).
This provides the explicit written authorization Claude Code requires before
executing offensive security operations from prompt templates.

- verification.env: user-fillable engagement config (scope, targets, permissions)
- blhackbox/prompts/verification.md: authorization template with {{PLACEHOLDER}} tokens
- blhackbox/prompts/inject_verification.py: renders env values into active document
- Session-start hook auto-injects verification on Claude Code Web startup
- MCP get_template appends active verification as authorization context
- make inject-verification target for manual activation

https://claude.ai/code/session_01LurM5TE5bwMrPQsiXWgHSp
---
 .claude/hooks/session-start.sh           |   7 +
 .gitignore                               |   3 +
 CLAUDE.md                                |  37 +++++
 Makefile                                 |   7 +-
 blhackbox/mcp/server.py                  |  28 +++-
 blhackbox/prompts/__init__.py            |  13 ++
 blhackbox/prompts/inject_verification.py | 195 +++++++++++++++++++++++
 blhackbox/prompts/verification.md        | 171 ++++++++++++++++++++
 verification.env                         | 112 +++++++++++++
 9 files changed, 570 insertions(+), 3 deletions(-)
 create mode 100644 blhackbox/prompts/inject_verification.py
 create mode 100644 blhackbox/prompts/verification.md
 create mode 100644 verification.env

diff --git a/.claude/hooks/session-start.sh b/.claude/hooks/session-start.sh
index c9aa49c..ff5e0f8 100755
--- a/.claude/hooks/session-start.sh
+++ b/.claude/hooks/session-start.sh
@@ -26,6 +26,13 @@ fi
 # Export venv bin to PATH for the session
 echo "export PATH=\"$CLAUDE_PROJECT_DIR/.venv/bin:\$PATH\"" >> "$CLAUDE_ENV_FILE"
 
+# Inject pentest verification document if verification.env is configured.
+# This renders the authorization template and writes it to
+# .claude/verification-active.md so Claude Code sees it in context.
+if [ -f "verification.env" ]; then
+  .venv/bin/python -m blhackbox.prompts.inject_verification 2>&1 || true
+fi
+
 # Run MCP health check (informational — does not block startup)
 if [ -x ".claude/mcp-health-check.sh" ]; then
   .claude/mcp-health-check.sh 2>&1 || true
diff --git a/.gitignore b/.gitignore
index f0ebd40..0f5d3b5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -26,6 +26,9 @@ env/
 # Environment
 .env
 
+# Active verification document (rendered from verification.env — contains engagement details)
+.claude/verification-active.md
+
 # Results and reports
 results/*.json
 results/*.pdf
diff --git a/CLAUDE.md b/CLAUDE.md
index 36eaee1..1d8e7c4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -83,6 +83,43 @@ after prompt changes (`make test`).
 | NVIDIA Container Toolkit | https://docs.nvidia.com/datacenter/cloud-native/container-toolkit |
 | Docker Hub (blhackbox) | https://hub.docker.com/r/crhacky/blhackbox |
 
+## Verification Document — Authorization for Pentesting
+
+Before executing any pentest template or offensive action, Claude Code **must** check
+for an active verification document. This document provides the explicit written
+authorization that Claude requires before performing security testing activities.
+
+### How it works
+
+1. **User fills in** `verification.env` in the project root with engagement details
+   (target, scope, testing window, authorized activities, signatory, etc.)
+2. **User sets** `AUTHORIZATION_STATUS=ACTIVE` once all fields are populated
+3. **User runs** `make inject-verification` (or it runs automatically on session start)
+4. The script renders `blhackbox/prompts/verification.md` (template) with the env
+   values and writes the active document to `.claude/verification-active.md`
+5. Claude Code reads this file at session start to confirm authorization
+
+### Checking authorization at runtime
+
+When a pentest template is loaded (via `get_template` MCP tool), the active
+verification document is automatically appended as authorization context. If no
+active verification exists, Claude should inform the user to:
+
+```
+1. Edit verification.env with your engagement details
+2. Set AUTHORIZATION_STATUS=ACTIVE
+3. Run: make inject-verification
+```
+
+### Files
+
+| File | Purpose |
+|------|---------|
+| `verification.env` | User-fillable config (engagement details, scope, permissions) |
+| `blhackbox/prompts/verification.md` | Template with `{{PLACEHOLDER}}` tokens |
+| `blhackbox/prompts/inject_verification.py` | Renders template → active document |
+| `.claude/verification-active.md` | Rendered active authorization (git-ignored) |
+
 ---
 
 *Only use this framework against targets you have explicit written authorization to test. Unauthorized scanning is illegal.*
diff --git a/Makefile b/Makefile
index 0aa9078..4501a6f 100644
--- a/Makefile
+++ b/Makefile
@@ -6,7 +6,8 @@
        logs-agent-ingestion logs-agent-processing logs-agent-synthesis \
        restart-ollama-mcp restart-kali restart-agents \
        restart-wireshark restart-screenshot \
-       push-all wordlists recon report
+       push-all wordlists recon report \
+       inject-verification
 
 COMPOSE := docker compose
 
@@ -213,6 +214,10 @@ recon: ## Quick recon example (requires TARGET env var)
 report: ## Generate report for a session (requires SESSION env var)
 	blhackbox report --session $(SESSION) --format pdf
 
+# ── Verification ─────────────────────────────────────────────────
+inject-verification: ## Render verification.env into active authorization document
+	python -m blhackbox.prompts.inject_verification
+
 # ── Build and push (Docker Hub: crhacky/blhackbox) ──────────────
 push-all: ## Build and push all custom images to Docker Hub
 	docker build -f docker/kali-mcp.Dockerfile -t crhacky/blhackbox:kali-mcp .
diff --git a/blhackbox/mcp/server.py b/blhackbox/mcp/server.py
index 5a21412..ccc12bb 100644
--- a/blhackbox/mcp/server.py
+++ b/blhackbox/mcp/server.py
@@ -499,16 +499,40 @@ async def _do_list_templates() -> str:
 
 
 async def _do_get_template(args: dict[str, Any]) -> str:
-    from blhackbox.prompts import load_template
+    from blhackbox.prompts import load_template, load_verification
 
     name = args["name"]
     target = args.get("target")
     try:
         content = load_template(name, target=target)
-        return content
     except (ValueError, FileNotFoundError) as exc:
         return json.dumps({"error": str(exc)})
 
+    # Append active verification document as authorization context
+    verification = load_verification()
+    if verification:
+        content += (
+            "\n\n---\n\n"
+            "## ACTIVE AUTHORIZATION DOCUMENT\n\n"
+            "The following verification document confirms explicit written "
+            "authorization for all activities described above.\n\n"
+            + verification
+        )
+    else:
+        content += (
+            "\n\n---\n\n"
+            "## ⚠ NO ACTIVE AUTHORIZATION DOCUMENT\n\n"
+            "No verification document found. Before executing this template, "
+            "the operator must:\n\n"
+            "1. Edit `verification.env` with engagement details\n"
+            "2. Set `AUTHORIZATION_STATUS=ACTIVE`\n"
+            "3. Run `make inject-verification`\n\n"
+            "This generates the explicit written authorization required "
+            "for penetration testing activities.\n"
+        )
+
+    return content
+
 
 # ---------------------------------------------------------------------------
 # Aggregate results — MCP host (Claude) does the analysis, this validates
diff --git a/blhackbox/prompts/__init__.py b/blhackbox/prompts/__init__.py
index 0925787..b73fe19 100644
--- a/blhackbox/prompts/__init__.py
+++ b/blhackbox/prompts/__init__.py
@@ -90,3 +90,16 @@ def load_playbook() -> str:
     """Load the Claude pentest playbook."""
     path = _PROMPTS_DIR / "claude_playbook.md"
     return path.read_text(encoding="utf-8")
+
+
+def load_verification() -> str | None:
+    """Load the active verification document if it exists.
+
+    Returns:
+        The rendered verification document content, or ``None`` if no
+        active verification document has been generated yet.
+    """
+    active_path = _PROMPTS_DIR.parent.parent / ".claude" / "verification-active.md"
+    if active_path.exists():
+        return active_path.read_text(encoding="utf-8")
+    return None
diff --git a/blhackbox/prompts/inject_verification.py b/blhackbox/prompts/inject_verification.py
new file mode 100644
index 0000000..19c9ff6
--- /dev/null
+++ b/blhackbox/prompts/inject_verification.py
@@ -0,0 +1,195 @@
+"""Inject verification document into the Claude Code session context.
+
+Reads ``verification.env`` from the project root, renders the
+``verification.md`` template with the configured values, and writes
+the active document to ``.claude/verification-active.md``.
+
+The session-start hook (or ``make inject-verification``) calls this
+script so that the rendered authorization document is present in
+the Claude Code context before any pentest prompt templates run.
+
+Usage::
+
+    python -m blhackbox.prompts.inject_verification [--env PATH] [--out PATH]
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+def _parse_env_file(env_path: Path) -> dict[str, str]:
+    """Parse a simple KEY=VALUE env file, ignoring comments and blanks."""
+    values: dict[str, str] = {}
+    for line in env_path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        values[key.strip()] = value.strip()
+    return values
+
+
+def _validate_required_fields(env: dict[str, str]) -> list[str]:
+    """Return a list of missing required fields."""
+    required = [
+        "AUTHORIZATION_STATUS",
+        "ENGAGEMENT_ID",
+        "AUTHORIZATION_DATE",
+        "EXPIRATION_DATE",
+        "AUTHORIZING_ORGANIZATION",
+        "TESTER_NAME",
+        "TARGET_1",
+        "TESTING_START",
+        "TESTING_END",
+        "SIGNATORY_NAME",
+        "SIGNATURE_DATE",
+    ]
+    return [f for f in required if not env.get(f)]
+
+
+def _check_expiration(env: dict[str, str]) -> str | None:
+    """Return an error message if the authorization has expired."""
+    exp = env.get("EXPIRATION_DATE", "")
+    if not exp:
+        return None
+    try:
+        exp_date = datetime.strptime(exp, "%Y-%m-%d").replace(tzinfo=timezone.utc)
+        if exp_date < datetime.now(timezone.utc):
+            return f"Authorization expired on {exp}."
+    except ValueError:
+        return f"Invalid EXPIRATION_DATE format: {exp!r} (expected YYYY-MM-DD)."
+    return None
+
+
+def render_verification(env: dict[str, str], template_text: str) -> str:
+    """Replace ``{{PLACEHOLDER}}`` tokens in the template with env values."""
+    def _replace(match: re.Match[str]) -> str:
+        key = match.group(1)
+        return env.get(key, match.group(0))
+
+    return re.sub(r"\{\{(\w+)\}\}", _replace, template_text)
+
+
+def inject(
+    env_path: Path | None = None,
+    out_path: Path | None = None,
+) -> dict[str, Any]:
+    """Run the full injection pipeline.
+
+    Returns:
+        Dict with ``status``, ``output_path``, and optional ``warnings``.
+    """
+    project_root = Path(__file__).resolve().parents[2]
+
+    if env_path is None:
+        env_path = project_root / "verification.env"
+    if out_path is None:
+        out_path = project_root / ".claude" / "verification-active.md"
+
+    result: dict[str, Any] = {"warnings": []}
+
+    # --- Read env ---
+    if not env_path.exists():
+        return {
+            "status": "error",
+            "message": (
+                f"verification.env not found at {env_path}. "
+                "Copy verification.env and fill in your engagement details."
+            ),
+        }
+
+    env = _parse_env_file(env_path)
+
+    # --- Check status ---
+    status = env.get("AUTHORIZATION_STATUS", "PENDING").upper()
+    if status != "ACTIVE":
+        return {
+            "status": "inactive",
+            "message": (
+                "AUTHORIZATION_STATUS is not ACTIVE. "
+                "Set AUTHORIZATION_STATUS=ACTIVE in verification.env "
+                "after filling in all fields."
+            ),
+        }
+
+    # --- Validate required fields ---
+    missing = _validate_required_fields(env)
+    if missing:
+        return {
+            "status": "error",
+            "message": (
+                f"Missing required fields in verification.env: {', '.join(missing)}. "
+                "Fill in all required fields before activating."
+            ),
+        }
+
+    # --- Check expiration ---
+    exp_err = _check_expiration(env)
+    if exp_err:
+        return {"status": "expired", "message": exp_err}
+
+    # --- Read template ---
+    template_path = Path(__file__).parent / "verification.md"
+    if not template_path.exists():
+        return {
+            "status": "error",
+            "message": f"Verification template not found: {template_path}",
+        }
+
+    template_text = template_path.read_text(encoding="utf-8")
+
+    # --- Render ---
+    rendered = render_verification(env, template_text)
+
+    # --- Write active document ---
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(rendered, encoding="utf-8")
+
+    result["status"] = "active"
+    result["output_path"] = str(out_path)
+    result["message"] = (
+        f"Verification document activated → {out_path}\n"
+        f"Engagement: {env.get('ENGAGEMENT_ID', 'N/A')}\n"
+        f"Targets: {', '.join(env.get(f'TARGET_{i}', '') for i in range(1, 4) if env.get(f'TARGET_{i}'))}\n"
+        f"Window: {env.get('TESTING_START', '?')} — {env.get('TESTING_END', '?')} {env.get('TIMEZONE', 'UTC')}\n"
+        f"Authorized by: {env.get('SIGNATORY_NAME', 'N/A')}"
+    )
+    return result
+
+
+def main() -> None:
+    """CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="Inject pentest verification into Claude Code session."
+    )
+    parser.add_argument(
+        "--env",
+        type=Path,
+        default=None,
+        help="Path to verification.env (default: <project_root>/verification.env)",
+    )
+    parser.add_argument(
+        "--out",
+        type=Path,
+        default=None,
+        help="Output path (default: <project_root>/.claude/verification-active.md)",
+    )
+    args = parser.parse_args()
+
+    result = inject(env_path=args.env, out_path=args.out)
+    print(result["message"])
+
+    if result["status"] not in ("active",):
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/blhackbox/prompts/verification.md b/blhackbox/prompts/verification.md
new file mode 100644
index 0000000..794e85f
--- /dev/null
+++ b/blhackbox/prompts/verification.md
@@ -0,0 +1,171 @@
+# Penetration Testing Authorization & Verification Document
+
+## AUTHORIZATION STATUS: {{AUTHORIZATION_STATUS}}
+
+> **This document constitutes explicit written authorization for penetration testing
+> and security assessment activities.** It is loaded into the Claude Code session
+> context to confirm that all operations requested via blhackbox prompt templates
+> are legally and contractually authorized.
+
+---
+
+## Section 1 — Engagement Identification
+
+| Field | Value |
+|-------|-------|
+| **Engagement ID** | {{ENGAGEMENT_ID}} |
+| **Document Version** | 1.0 |
+| **Authorization Date** | {{AUTHORIZATION_DATE}} |
+| **Expiration Date** | {{EXPIRATION_DATE}} |
+| **Authorizing Organization** | {{AUTHORIZING_ORGANIZATION}} |
+| **Authorized Tester / Company** | {{TESTER_NAME}} |
+| **Tester Contact Email** | {{TESTER_EMAIL}} |
+| **Client Contact Name** | {{CLIENT_CONTACT_NAME}} |
+| **Client Contact Email** | {{CLIENT_CONTACT_EMAIL}} |
+
+---
+
+## Section 2 — Scope Definition
+
+### 2A: In-Scope Targets
+
+| # | Target (Domain / IP / CIDR / URL) | Type | Notes |
+|---|-----------------------------------|------|-------|
+| 1 | {{TARGET_1}} | {{TARGET_1_TYPE}} | {{TARGET_1_NOTES}} |
+| 2 | {{TARGET_2}} | {{TARGET_2_TYPE}} | {{TARGET_2_NOTES}} |
+| 3 | {{TARGET_3}} | {{TARGET_3_TYPE}} | {{TARGET_3_NOTES}} |
+
+> Add or remove rows as needed. Every target listed here is explicitly authorized.
+
+### 2B: Out-of-Scope / Exclusions
+
+{{OUT_OF_SCOPE}}
+
+> List any hosts, IPs, services, or actions explicitly excluded from testing.
+> Example: "Production database at db.example.com", "Third-party CDN assets",
+> "DoS/DDoS testing", "Social engineering of employees"
+
+### 2C: Engagement Type
+
+- **Testing approach:** {{ENGAGEMENT_TYPE}}
+  - `black-box` — No prior knowledge of target infrastructure
+  - `grey-box` — Limited credentials or documentation provided
+  - `white-box` — Full access to source code, architecture docs, credentials
+
+### 2D: Provided Credentials (if grey-box / white-box)
+
+{{CREDENTIALS}}
+
+> Format: `service: username:password` or `API key: sk-xxx...`
+> Write "N/A" for black-box engagements.
+
+---
+
+## Section 3 — Authorized Activities
+
+The following activities are explicitly authorized for all in-scope targets:
+
+### 3A: Permitted Testing Activities
+
+- [{{PERMIT_RECON}}] **Reconnaissance** — Passive and active information gathering (OSINT, DNS, WHOIS, subdomain enumeration, certificate transparency)
+- [{{PERMIT_SCANNING}}] **Scanning** — Port scanning, service detection, vulnerability scanning, technology fingerprinting
+- [{{PERMIT_ENUMERATION}}] **Enumeration** — Directory discovery, parameter fuzzing, CMS detection, web application mapping
+- [{{PERMIT_EXPLOITATION}}] **Exploitation** — Active exploitation of discovered vulnerabilities including SQL injection, XSS, RCE, LFI, SSRF, authentication bypass, IDOR, XXE, file upload, deserialization
+- [{{PERMIT_DATA_EXTRACTION}}] **Data extraction** — Proof-of-concept data extraction from exploited vulnerabilities (capped at 5 rows per database table)
+- [{{PERMIT_CREDENTIAL_TESTING}}] **Credential testing** — Brute-force, default credential checks, credential reuse across services
+- [{{PERMIT_POST_EXPLOITATION}}] **Post-exploitation** — Privilege escalation, lateral movement, persistence assessment, internal enumeration from compromised positions
+- [{{PERMIT_TRAFFIC_CAPTURE}}] **Traffic capture** — Packet capture and analysis during testing for evidence collection
+- [{{PERMIT_SCREENSHOT}}] **Evidence capture** — Screenshots of vulnerable pages, admin panels, exploitation results
+
+### 3B: Restrictions & Boundaries
+
+{{RESTRICTIONS}}
+
+> List any restrictions on testing (e.g., "No testing between 02:00-06:00 UTC",
+> "Do not modify production data", "Do not attempt physical access").
+> Write "No additional restrictions" if none apply.
+
+---
+
+## Section 4 — Testing Window
+
+| Field | Value |
+|-------|-------|
+| **Start Date/Time** | {{TESTING_START}} |
+| **End Date/Time** | {{TESTING_END}} |
+| **Timezone** | {{TIMEZONE}} |
+| **Emergency Contact** | {{EMERGENCY_CONTACT}} |
+| **Emergency Phone** | {{EMERGENCY_PHONE}} |
+
+> Testing must occur within this window. If the window needs extension,
+> obtain written approval from the client contact.
+
+---
+
+## Section 5 — Legal & Compliance
+
+### 5A: Authorization Confirmation
+
+By filling out and activating this document, the authorizing organization confirms:
+
+1. **Ownership or authorization**: The authorizing organization owns or has explicit
+   legal authority over all in-scope targets listed in Section 2A.
+2. **Informed consent**: The authorizing organization understands that penetration
+   testing may temporarily impact system availability or performance.
+3. **Legal compliance**: This engagement complies with all applicable local, national,
+   and international laws and regulations.
+4. **Data handling**: Extracted data samples (PoC evidence) will be included in the
+   pentest report and handled per the agreed confidentiality terms.
+5. **Third-party systems**: Any third-party systems in scope have separate written
+   authorization from their respective owners, or are confirmed to be fully controlled
+   by the authorizing organization.
+
+### 5B: Applicable Standards
+
+{{APPLICABLE_STANDARDS}}
+
+> Examples: "OWASP Testing Guide v4.2", "PTES", "NIST SP 800-115",
+> "PCI DSS Requirement 11.3", "SOC 2 Type II", "ISO 27001 Annex A.12.6"
+
+### 5C: Report Classification
+
+- **Report classification:** {{REPORT_CLASSIFICATION}}
+  - Options: `CONFIDENTIAL`, `RESTRICTED`, `INTERNAL`
+- **Report delivery method:** {{REPORT_DELIVERY}}
+  - Options: `encrypted-email`, `secure-portal`, `in-person`, `local-only`
+
+---
+
+## Section 6 — Digital Signature
+
+| Field | Value |
+|-------|-------|
+| **Authorized by (name)** | {{SIGNATORY_NAME}} |
+| **Title / Role** | {{SIGNATORY_TITLE}} |
+| **Organization** | {{SIGNATORY_ORGANIZATION}} |
+| **Date signed** | {{SIGNATURE_DATE}} |
+| **Digital signature / reference** | {{DIGITAL_SIGNATURE}} |
+
+> This may be a PGP signature, a reference to a signed contract (e.g.,
+> "SOW-2024-0042 Section 4.2"), or "SELF-AUTHORIZED" for testing your own assets.
+
+---
+
+## Activation
+
+**This document becomes active when:**
+
+1. All `{{PLACEHOLDER}}` fields above are filled in with real values
+2. The `verification.env` configuration file is populated with matching values
+3. The `AUTHORIZATION_STATUS` field at the top reads `ACTIVE`
+4. The testing window (Section 4) includes the current date
+
+**When active, this document provides explicit written authorization for Claude Code
+to execute all permitted activities (Section 3A) against all in-scope targets
+(Section 2A) using the blhackbox MCP framework and prompt templates.**
+
+---
+
+*This authorization document is generated by the blhackbox framework.
+Unauthorized testing is illegal. Only use against targets you have explicit
+written authorization to test.*
diff --git a/verification.env b/verification.env
new file mode 100644
index 0000000..7ce5aca
--- /dev/null
+++ b/verification.env
@@ -0,0 +1,112 @@
+# ┌──────────────────────────────────────────────────────────────────────┐
+# │  BLHACKBOX — Penetration Testing Authorization Configuration        │
+# │                                                                      │
+# │  Fill in ALL fields below, then run:                                 │
+# │    make inject-verification                                          │
+# │  or:                                                                 │
+# │    python -m blhackbox.prompts.inject_verification                   │
+# │                                                                      │
+# │  This generates the active verification document that gets loaded    │
+# │  into your Claude Code session as explicit written authorization.    │
+# └──────────────────────────────────────────────────────────────────────┘
+
+# ── Section 1: Engagement Identification ─────────────────────────────
+# Set to ACTIVE when all fields are filled and testing is authorized.
+AUTHORIZATION_STATUS=PENDING
+
+# Unique engagement identifier (e.g., "PENTEST-2026-001", "SOW-2026-042")
+ENGAGEMENT_ID=
+
+# Date this authorization was granted (YYYY-MM-DD)
+AUTHORIZATION_DATE=
+
+# Date this authorization expires (YYYY-MM-DD)
+EXPIRATION_DATE=
+
+# Organization that owns or controls the target assets
+AUTHORIZING_ORGANIZATION=
+
+# Person or company performing the test
+TESTER_NAME=
+TESTER_EMAIL=
+
+# Client-side point of contact
+CLIENT_CONTACT_NAME=
+CLIENT_CONTACT_EMAIL=
+
+# ── Section 2: Scope Definition ──────────────────────────────────────
+# In-scope targets. Add up to 10. Leave unused slots empty.
+# Format: domain.com, 10.0.0.0/24, https://app.example.com
+TARGET_1=
+TARGET_1_TYPE=
+TARGET_1_NOTES=
+
+TARGET_2=
+TARGET_2_TYPE=
+TARGET_2_NOTES=
+
+TARGET_3=
+TARGET_3_TYPE=
+TARGET_3_NOTES=
+
+# Explicitly excluded from testing (comma-separated or "None")
+OUT_OF_SCOPE=None
+
+# Engagement type: black-box, grey-box, white-box
+ENGAGEMENT_TYPE=black-box
+
+# Credentials for grey-box/white-box (or "N/A")
+CREDENTIALS=N/A
+
+# ── Section 3: Authorized Activities ─────────────────────────────────
+# Mark each with "x" to permit or leave blank to deny.
+# Example: PERMIT_RECON=x   (permitted)
+#          PERMIT_RECON=     (not permitted)
+PERMIT_RECON=x
+PERMIT_SCANNING=x
+PERMIT_ENUMERATION=x
+PERMIT_EXPLOITATION=x
+PERMIT_DATA_EXTRACTION=x
+PERMIT_CREDENTIAL_TESTING=x
+PERMIT_POST_EXPLOITATION=x
+PERMIT_TRAFFIC_CAPTURE=x
+PERMIT_SCREENSHOT=x
+
+# Additional restrictions (free text, or "No additional restrictions")
+RESTRICTIONS=No additional restrictions
+
+# ── Section 4: Testing Window ────────────────────────────────────────
+# Format: YYYY-MM-DD HH:MM
+TESTING_START=
+TESTING_END=
+TIMEZONE=UTC
+
+# Who to call if something goes wrong during testing
+EMERGENCY_CONTACT=
+EMERGENCY_PHONE=
+
+# ── Section 5: Legal & Compliance ────────────────────────────────────
+# Applicable standards (comma-separated)
+APPLICABLE_STANDARDS=OWASP Testing Guide v4.2, PTES
+
+# Report classification: CONFIDENTIAL, RESTRICTED, INTERNAL
+REPORT_CLASSIFICATION=CONFIDENTIAL
+
+# How the report will be delivered: encrypted-email, secure-portal, in-person, local-only
+REPORT_DELIVERY=local-only
+
+# ── Section 6: Digital Signature ─────────────────────────────────────
+# Name of the person authorizing this engagement
+SIGNATORY_NAME=
+
+# Title or role (e.g., "CISO", "CTO", "Asset Owner")
+SIGNATORY_TITLE=
+
+# Organization of the signatory
+SIGNATORY_ORGANIZATION=
+
+# Date signed (YYYY-MM-DD)
+SIGNATURE_DATE=
+
+# Digital signature reference (PGP sig, contract ref, or "SELF-AUTHORIZED")
+DIGITAL_SIGNATURE=

From 153d046a9838b68e6775994c20d23f1c864a9ea6 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 9 Mar 2026 14:54:35 +0000
Subject: [PATCH 2/3] docs: add Authorization & Verification section to README

Document the full verification document workflow: how to fill in
verification.env, activate it, inject it, and how it integrates
with pentest templates and the session-start hook. Includes
step-by-step setup, validation rules, file reference table, and
a self-authorized lab testing example. Updates Project Structure,
Makefile Shortcuts, Security Notes, and Installation sections.

https://claude.ai/code/session_01LurM5TE5bwMrPQsiXWgHSp
---
 README.md | 152 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 151 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 0a22bd0..f5e1069 100644
--- a/README.md
+++ b/README.md
@@ -35,6 +35,7 @@
 - [Docker Hub Images](#docker-hub-images)
 - [Neo4j (Optional)](#neo4j-optional)
 - [GPU Support for Ollama (Optional)](#gpu-support-for-ollama-optional)
+- [Authorization & Verification](#authorization--verification)
 - [Security Notes](#security-notes)
 - [Project Structure](#project-structure)
 - [License](#license)
@@ -152,6 +153,19 @@ docker compose pull
 docker compose up -d
 ```
 
+**Set up authorization (required before running pentests):**
+
+```bash
+# 5. Edit verification.env with your engagement details
+nano verification.env
+# Set AUTHORIZATION_STATUS=ACTIVE after filling in all fields
+
+# 6. Render the active verification document
+make inject-verification
+```
+
+See [Authorization & Verification](#authorization--verification) for full details.
+
 **Verify everything is running:**
 
 ```bash
@@ -625,6 +639,7 @@ make logs-ollama-mcp       # Tail Ollama MCP logs (requires --profile ollama)
 make logs-agent-ingestion  # Tail Ingestion Agent logs (requires --profile ollama)
 make logs-agent-processing # Tail Processing Agent logs (requires --profile ollama)
 make logs-agent-synthesis  # Tail Synthesis Agent logs (requires --profile ollama)
+make inject-verification   # Render verification.env → active authorization document
 make push-all              # Build and push all images to Docker Hub
 ```
 
@@ -708,12 +723,143 @@ inference for the preprocessing pipeline.
 
 ---
 
+## Authorization & Verification
+
+Before running any pentest template, blhackbox requires an **active verification
+document** — explicit written authorization that confirms you have permission to
+test the target. Without it, Claude Code will refuse to execute offensive actions
+and prompt you to set one up.
+
+### How it works
+
+```
+verification.env          You fill in engagement details (target, scope,
+    │                     testing window, authorized activities, signatory)
+    │
+    ▼
+inject_verification.py    Renders the template with your values
+    │
+    ▼
+verification.md           Template with {{PLACEHOLDER}} tokens
+    │
+    ▼
+.claude/verification-     Active document loaded into Claude Code session.
+  active.md               Automatically appended to every pentest template.
+```
+
+When you load a pentest template (via the `get_template` MCP tool), the active
+verification document is automatically appended as authorization context. If no
+active verification exists, Claude will tell you to set one up.
+
+### Step-by-step setup
+
+**1. Edit `verification.env`** in the project root:
+
+```bash
+# Open the file in your editor
+nano verification.env    # or vim, code, etc.
+```
+
+Fill in **all** fields across the 6 sections:
+
+| Section | What to fill in |
+|---------|----------------|
+| **1. Engagement ID** | `ENGAGEMENT_ID`, `AUTHORIZATION_DATE`, `EXPIRATION_DATE`, `AUTHORIZING_ORGANIZATION`, `TESTER_NAME`, `TESTER_EMAIL`, `CLIENT_CONTACT_NAME`, `CLIENT_CONTACT_EMAIL` |
+| **2. Scope** | `TARGET_1` through `TARGET_3` (with `_TYPE` and `_NOTES`), `OUT_OF_SCOPE`, `ENGAGEMENT_TYPE`, `CREDENTIALS` |
+| **3. Activities** | Toggle each `PERMIT_*` field (`x` = allowed, blank = denied): recon, scanning, enumeration, exploitation, data extraction, credential testing, post-exploitation, traffic capture, screenshots |
+| **4. Testing Window** | `TESTING_START`, `TESTING_END`, `TIMEZONE`, `EMERGENCY_CONTACT`, `EMERGENCY_PHONE` |
+| **5. Legal** | `APPLICABLE_STANDARDS`, `REPORT_CLASSIFICATION`, `REPORT_DELIVERY` |
+| **6. Signature** | `SIGNATORY_NAME`, `SIGNATORY_TITLE`, `SIGNATORY_ORGANIZATION`, `SIGNATURE_DATE`, `DIGITAL_SIGNATURE` |
+
+**2. Activate** — set the status field at the top of the file:
+
+```bash
+AUTHORIZATION_STATUS=ACTIVE
+```
+
+**3. Inject** — render the active document:
+
+```bash
+make inject-verification
+```
+
+Or directly:
+
+```bash
+python -m blhackbox.prompts.inject_verification
+```
+
+On success, you'll see:
+
+```
+Verification document activated → .claude/verification-active.md
+Engagement: PENTEST-2026-001
+Targets: example.com, 10.0.0.0/24
+Window: 2026-03-01 09:00 — 2026-03-31 17:00 UTC
+Authorized by: Jane Smith
+```
+
+**4. Start your session** — Claude Code will automatically pick up the
+verification document. On Claude Code Web, the session-start hook runs
+`inject-verification` automatically if `verification.env` exists.
+
+### Validation rules
+
+The injection script validates before rendering:
+
+- `AUTHORIZATION_STATUS` must be `ACTIVE`
+- All required fields must be filled (`ENGAGEMENT_ID`, `AUTHORIZATION_DATE`, `EXPIRATION_DATE`, `AUTHORIZING_ORGANIZATION`, `TESTER_NAME`, `TARGET_1`, `TESTING_START`, `TESTING_END`, `SIGNATORY_NAME`, `SIGNATURE_DATE`)
+- `EXPIRATION_DATE` must not be in the past
+
+If any check fails, the script exits with an error message explaining what to fix.
+
+### Files involved
+
+| File | Purpose |
+|------|---------|
+| `verification.env` | User-fillable config with engagement details, scope, and permissions |
+| `blhackbox/prompts/verification.md` | Template with `{{PLACEHOLDER}}` tokens |
+| `blhackbox/prompts/inject_verification.py` | Renders the template into the active document |
+| `.claude/verification-active.md` | Rendered active authorization (git-ignored) |
+
+### Example: self-authorized lab testing
+
+For testing your own assets (lab, CTF, etc.):
+
+```bash
+# In verification.env:
+AUTHORIZATION_STATUS=ACTIVE
+ENGAGEMENT_ID=LAB-2026-001
+AUTHORIZATION_DATE=2026-03-09
+EXPIRATION_DATE=2026-12-31
+AUTHORIZING_ORGANIZATION=My Lab
+TESTER_NAME=Your Name
+TESTER_EMAIL=you@example.com
+TARGET_1=192.168.1.0/24
+TARGET_1_TYPE=network
+TARGET_1_NOTES=Home lab network
+TESTING_START=2026-03-09 00:00
+TESTING_END=2026-12-31 23:59
+SIGNATORY_NAME=Your Name
+SIGNATORY_TITLE=Asset Owner
+SIGNATORY_ORGANIZATION=My Lab
+SIGNATURE_DATE=2026-03-09
+DIGITAL_SIGNATURE=SELF-AUTHORIZED
+```
+
+Then run `make inject-verification` and start your Claude Code session.
+
+---
+
 ## Security Notes
 
 - **Docker socket**: MCP Gateway (optional) and Portainer mount
   `/var/run/docker.sock`. This grants effective root on the host. Never expose
   ports 8080 or 9443 to the public internet.
-- **Authorization**: Ensure you have written permission before scanning any target.
+- **Authorization**: Set up a [verification document](#authorization--verification) before
+  running any pentest template. Claude Code will not execute offensive actions without
+  an active authorization. The rendered document (`.claude/verification-active.md`)
+  is git-ignored and never committed.
 - **Neo4j**: Set a strong password in `.env`. Never use defaults in production.
 - **Agent containers** (optional Ollama pipeline): Communicate only on the
   internal `blhackbox_net` Docker network. No ports are exposed to the host.
@@ -728,8 +874,10 @@ inference for the preprocessing pipeline.
 blhackbox/
 ├── .claude/
 │   ├── settings.json               # Claude Code hooks config
+│   ├── verification-active.md      # Rendered authorization doc (git-ignored)
 │   └── hooks/
 │       └── session-start.sh        # auto-setup for web sessions
+├── verification.env                 # Pentest authorization config (edit before testing)
 ├── .mcp.json                        # MCP server config (Claude Code Web)
 ├── docker/
 │   ├── kali-mcp.Dockerfile          # Kali Linux + Metasploit Framework
@@ -766,6 +914,8 @@ blhackbox/
 │   │   └── graph.py
 │   ├── prompts/
 │   │   ├── claude_playbook.md       # pentest playbook for MCP host
+│   │   ├── verification.md          # authorization template ({{PLACEHOLDER}} tokens)
+│   │   ├── inject_verification.py   # renders template → active document
 │   │   └── agents/
 │   │       ├── ingestionagent.md
 │   │       ├── processingagent.md

From cb76d94d1df23dfd86d65931703d09f74aec2bcd Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 9 Mar 2026 15:29:36 +0000
Subject: [PATCH 3/3] fix: resolve ruff lint errors in inject_verification.py

- UP017: Replace `timezone.utc` with `datetime.UTC` alias
- E501: Break long f-string lines under 100 chars

https://claude.ai/code/session_01LurM5TE5bwMrPQsiXWgHSp
---
 blhackbox/prompts/inject_verification.py | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/blhackbox/prompts/inject_verification.py b/blhackbox/prompts/inject_verification.py
index 19c9ff6..c74d746 100644
--- a/blhackbox/prompts/inject_verification.py
+++ b/blhackbox/prompts/inject_verification.py
@@ -18,7 +18,7 @@
 import argparse
 import re
 import sys
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
 
@@ -61,8 +61,8 @@ def _check_expiration(env: dict[str, str]) -> str | None:
     if not exp:
         return None
     try:
-        exp_date = datetime.strptime(exp, "%Y-%m-%d").replace(tzinfo=timezone.utc)
-        if exp_date < datetime.now(timezone.utc):
+        exp_date = datetime.strptime(exp, "%Y-%m-%d").replace(tzinfo=UTC)
+        if exp_date < datetime.now(UTC):
             return f"Authorization expired on {exp}."
     except ValueError:
         return f"Invalid EXPIRATION_DATE format: {exp!r} (expected YYYY-MM-DD)."
@@ -158,8 +158,13 @@ def inject(
     result["message"] = (
         f"Verification document activated → {out_path}\n"
         f"Engagement: {env.get('ENGAGEMENT_ID', 'N/A')}\n"
-        f"Targets: {', '.join(env.get(f'TARGET_{i}', '') for i in range(1, 4) if env.get(f'TARGET_{i}'))}\n"
-        f"Window: {env.get('TESTING_START', '?')} — {env.get('TESTING_END', '?')} {env.get('TIMEZONE', 'UTC')}\n"
+        f"Targets: {', '.join(
+            env.get(f'TARGET_{i}', '')
+            for i in range(1, 4)
+            if env.get(f'TARGET_{i}')
+        )}\n"
+        f"Window: {env.get('TESTING_START', '?')} — "
+        f"{env.get('TESTING_END', '?')} {env.get('TIMEZONE', 'UTC')}\n"
         f"Authorized by: {env.get('SIGNATORY_NAME', 'N/A')}"
     )
     return result