Add penetration testing authorization & verification system

[valITino]

Summary

Implements a comprehensive authorization and verification system for blhackbox that requires explicit written permission before executing any penetration testing activities. Users must fill in engagement details, scope, and authorized activities in a configuration file, which is then rendered into an active verification document that Claude Code loads as authorization context.

Key Changes

• New verification injection system (blhackbox/prompts/inject_verification.py):

  • Parses verification.env configuration file with engagement details
  • Validates required fields (engagement ID, dates, targets, signatory, etc.)
  • Checks authorization status and expiration dates
  • Renders verification.md template by substituting {{PLACEHOLDER}} tokens
  • Writes active document to .claude/verification-active.md (git-ignored)
  • Provides detailed error messages for validation failures

• Verification document template (blhackbox/prompts/verification.md):

  • 6-section authorization document with placeholders for engagement details
  • Section 1: Engagement identification and contacts
  • Section 2: Scope definition (in-scope targets, exclusions, engagement type)
  • Section 3: Authorized activities (recon, scanning, exploitation, etc.) with toggles
  • Section 4: Testing window and emergency contacts
  • Section 5: Legal compliance and standards
  • Section 6: Digital signature and authorization confirmation

• Configuration template (verification.env):

  • User-fillable configuration with all required fields
  • Organized by section matching the verification document
  • Includes examples and format guidance
  • Status field (AUTHORIZATION_STATUS) must be set to ACTIVE to enable testing

• MCP server integration (blhackbox/mcp/server.py):

  • Modified _do_get_template() to automatically append active verification document
  • Shows warning if no active verification exists, with setup instructions
  • Verification is loaded via new load_verification() helper function

• Prompt utilities (blhackbox/prompts/__init__.py):

  • Added load_verification() function to read rendered active document

• Session automation (.claude/hooks/session-start.sh):

  • Automatically runs inject-verification on Claude Code session start if verification.env exists

• Build system (Makefile):

  • Added make inject-verification target to render verification document

• Documentation:

  • Comprehensive "Authorization & Verification" section in README with step-by-step setup
  • Example for self-authorized lab testing
  • Updated project structure documentation
  • Added verification details to CLAUDE.md for Claude Code developers

• Git configuration (.gitignore):

  • Ignores .claude/verification-active.md to prevent committing engagement details

Implementation Details

• Validation enforces all required fields before activation, preventing incomplete authorizations
• Expiration date checking prevents use of expired authorizations
• Template rendering uses simple regex substitution for {{KEY}} patterns
• Active document is automatically appended to all pentest templates loaded via MCP
• Clear error messages guide users through setup if verification is missing or invalid
• System is designed to be legally defensible by requiring explicit written authorization before any offensive testing

https://claude.ai/code/session_01LurM5TE5bwMrPQsiXWgHSp