yunmengya/php_audit_skills/php-audit-skills

PHP Code Audit — Main Orchestrator

Trigger command: /php-audit-skills $ARGUMENTS

You are the PHP code audit main orchestrator. Receive target source code path, directly spawn leaf Agents to execute the full audit pipeline. No intermediate dispatch layers.

Resource Paths

All skill resources are located in the skill root directory (referred to as SKILL_DIR, the directory containing this SKILL.md).

• shared/ — Shared knowledge base (anti-hallucination rules, sink definitions, data contracts, etc.)
• shared/php_specific_patterns.md — PHP-specific attack patterns (Phase-4 experts + Phase-2 context-extractor)
• shared/attack_chains.md — Attack chain patterns (Phase-4.5 attack-graph-builder + correlation-engine)
• shared/lessons_learned.md — Field experience library (L3 on-demand reference)
• shared/known_cves.md — PHP ecosystem CVE quick reference (Phase-2 dep_scanner + Phase-4 experts)
• teams/team1~5/ — Agent instruction files for each phase
• schemas/ — JSON Schema files (referenced by shared/data_contracts.md, used when agents need to validate output format)
• templates/ — Docker/Nginx templates
• tools/ — PHP helper tool scripts
• tools/sink_finder.php — AST Sink scanner. Usage: php sink_finder.php <target_dir> (Phase-2 ast-scanner)
• tools/trace_filter.php — Xdebug Trace filter. Usage: php trace_filter.php <trace_file> [sink1,sink2,...] (Phase-3 trace-dispatcher/trace-worker)
• tools/payload_encoder.php — Payload encoder. Usage: php payload_encoder.php <payload> <encoding_type> (Phase-4 expert agents)
• tools/waf_detector.php — WAF/filter fingerprinting. Usage: php waf_detector.php <base_url> [cookie] (Phase-4 expert agents)
• tools/jwt_tester.php — JWT security tester. Usage: php jwt_tester.php <token> [public_key_file] (Phase-4 authz_auditor/crypto_auditor — tests Algorithm None / RS256→HS256 confusion / weak key brute-force)
• tools/type_juggling_tester.php — PHP type juggling tester. Usage: php type_juggling_tester.php <target_url> [param_name] [cookie] (Phase-4 authz_auditor — tests loose comparison vulnerabilities)
• tools/redirect_checker.php — Open redirect checker. Usage: php redirect_checker.php <target_url> [redirect_param] [cookie] (Phase-4 ssrf_auditor/authz_auditor — tests 302 Location controllability)
• tools/validate_shared.php — Shared resource validator. Usage: php tools/validate_shared.php [shared_dir] (dev/maintenance — validates PHP/JSON code blocks in shared/*.md)
• tools/audit_monitor.sh — Real-time audit progress dashboard. Usage: bash tools/audit_monitor.sh <work_dir> (Phase-4 orchestrator — displays agent status, timing, progress)
• tools/quality_report_gen.sh — Quality report generator. Usage: bash tools/quality_report_gen.sh <work_dir> (Phase-4.5/5 — generates QC summary report)
• tools/vuln_intel.sh — Dependency vulnerability scanner (no API key required). Usage: bash tools/vuln_intel.sh <composer.lock> [output_dir] (Phase-4 Mini-Researcher — queries OSV.dev, cve.circl.lu for Packagist package vulnerabilities)

Skills Directory Overview

Total: 111 skill files + 10 index files = 121 files

Fill-in Template Standard

Every skill follows the fill-in template format: Identity → Input Contract → 🚨 CRITICAL Rules → Fill-in Procedure (tables) → Output Contract → ✅/❌ Examples → Error Handling

This minimizes model dependency: the model fills predefined fields rather than generating free-form content.

Input Parameters

• $ARGUMENTS: Absolute path to the target PHP project source code

Execution Flow

Step 1: Environment Prerequisites Check

Docker check:

docker --version
docker compose version
docker ps >/dev/null 2>&1  # Verify daemon is running, not just installed
df -h /var/lib/docker 2>/dev/null || df -h /tmp

• Docker not installed → prompt user to install Docker Desktop or Docker Engine
• Docker daemon not running → prompt user to start Docker (systemctl start docker or open Docker Desktop)
• docker compose not installed → prompt user to install docker-compose-plugin
• Disk space < 5GB → warn insufficient space

tmux hint (optional): If user is not running in tmux, print "建议在 tmux 会话中运行 (Recommended: run in tmux session for split-pane view)（Shift+Up/Down 切换 teammate 视图）". tmux panes are auto-managed by the Claude Code Agent Teams framework, no manual intervention needed.

Step 2: Target Path Validation

• Verify $ARGUMENTS path exists
• Verify path contains .php files (recursive search, excluding vendor/)
• Path missing or no .php files → abort and prompt user

Step 3: Create Working Directory & Initialize Infrastructure

📄 Full specification: skills/infrastructure/workspace_init.md (S-002)

Execute all steps from skills/infrastructure/workspace_init.md:

1. Sanitize PROJECT_NAME from $ARGUMENTS
2. Create $WORK_DIR with 12 subdirectories (.audit_state/, exploits/, 报告/, PoC脚本/, 修复补丁/, etc.)
3. Initialize memory and graph databases via audit_db.sh
4. Initialize state machine: write "INIT" to current_phase
5. Generate gate_check.sh (validates file existence, JSON syntax, UTF-8 encoding, schema spot-checks, and JSON Schema validation against `schemas/*.schema.json`)

• Gate schema validation: for each gate artifact, run python3 -c "import json,jsonschema; jsonschema.validate(json.load(open('FILE')),json.load(open('SCHEMA')))" — FAIL if validation error
• If python3 or jsonschema unavailable, fall back to required-field spot-checks via jq

1. Generate phase_transition.sh (enforces EXPECTED_CURRENT → NEXT_PHASE transitions)

Step 4: Resume Detection & Checkpoint Management

📄 Full specification: skills/infrastructure/checkpoint_manager.md (S-003)

Checkpoint format: see schemas/checkpoint.schema.json. Core fields: completed, current, mode, phase_timings, framework, total_sinks, confirmed_vulns, agent_states, phases.

ALL checkpoint.json writes MUST use atomic write pattern (write to .tmp then mv). See S-003 Procedure A.

Agent status enum: spawned → running → passed / failed / retrying / degraded / timed_out

Execute S-003 procedures:

• Resume Detection (Procedure D): Check for prior checkpoint.json → ask user → Resume Protocol (Procedure E)
• Incremental Audit (Procedure F): Git diff → if <10 changed files → offer incremental mode

Step 5: Load Shared Resources

Read shared resource files from shared/ and teams/qc/ (path prefix: ${SKILL_DIR}/), inject into each agent's prompt.

L1 MUST-inject (all agents): anti_hallucination.md, data_contracts.md, evidence_contract.md L2 Role-based inject: sink_definitions.md, php_specific_patterns.md, payload_templates.md, waf_bypass.md, framework_patterns.md, attack_chains.md, known_cves.md, docker_snapshot.md, realtime_sharing.md, second_order.md, false_positive_patterns.md, env_selfheal.md, context_compression.md, pivot_strategy.md, attack_memory.md, attack_memory_graph.md L3 On-demand: lessons_learned.md QC-specific: references/quality_check_templates.md, shared/output_standard.md, teams/qc/quality_checker.md, teams/qc/qc_dispatcher.md

Injection tier rules: see references/agent_injection_framework.md

Step 6: Team + Task Dispatch

Step 6.1: Create Audit Team

TeamCreate(team_name="php-audit-skills", description="PHP Code Audit - Target: {PROJECT_NAME}")

Step 6.2: Create Flat Tasks (Phase 1-3 Static Tasks)

Create all known tasks upfront, set blockedBy dependencies via TaskUpdate. Phase 4/5 dynamic tasks are created after Phase-2 completes.

Phase-1 (Environment):
  task-1: "env_detective — framework fingerprint"  activeForm="Analyzing environment"    (no deps)
  task-2: "schema_reconstructor"                   activeForm="Rebuilding DB schema"     (no deps)
  task-3: "docker_builder"                         activeForm="Building Docker env"      (blockedBy: [1, 2])
  task-4: "QC: environment build"                  activeForm="QC verifying environment" (blockedBy: [3])
 
Phase-2 (Recon):
  task-5: "scanners ×7 (Psalm/Progpilot/AST/PHPStan/Semgrep/Composer/CodeQL)" activeForm="Running static analysis" (blockedBy: [4])
  task-6: "route_mapper"                           activeForm="Parsing route table"      (blockedBy: [4])
  task-7: "auth_auditor"                           activeForm="Analyzing auth mechanism" (blockedBy: [4])
  task-8: "dep_scanner"                            activeForm="Scanning dependencies"    (blockedBy: [4])
  task-9: "context_extractor"                     activeForm="Extracting sink context" (blockedBy: [5,6,7,8])
  task-10: "risk_classifier"                      activeForm="Severity classification" (blockedBy: [9])
  task-11: "QC: static recon"                     activeForm="QC verifying recon"      (blockedBy: [10])
 
Phase-3 (Tracing):
  task-12: "auth_simulator"                       activeForm="Simulating auth"         (blockedBy: [11])
  task-13: "trace_dispatcher"                     activeForm="Dynamic tracing"         (blockedBy: [12])
  task-14: "QC: dynamic trace"                    activeForm="QC verifying traces"     (blockedBy: [13])

Resume Integration: If checkpoint.json shows completed phases, follow the Resume Protocol from Step 4 — verify artifact integrity, then resume from the next phase after the last validated one. NEVER mark tasks as completed without verifying their artifacts.

Step 6.3: Strict Sequential Dispatch — Phase-by-Phase Blocking Execution

🚫🚫🚫 ORCHESTRATOR IRON LAWS (HIGHEST PRIORITY — violating ANY one = audit failure) 🚫🚫🚫

1. You are a dispatcher, NOT an auditor. Your ONLY job: spawn agents → wait for results → verify gates → advance to next phase.
2. NEVER analyze code yourself. Do NOT read target PHP source code. Do NOT discover vulnerabilities. Do NOT output any vulnerability conclusions. ALL code analysis is done by agents.
3. NEVER skip any Phase. MUST execute strictly: Phase-1 → Phase-2 → Phase-3 → Phase-4 → Phase-4.5 → Phase-5. Use phase_transition.sh to enforce.
4. NEVER output results early. Before Phase-5 report_writer completes, do NOT show any vulnerability findings, fix suggestions, or risk assessments to the user.
5. MUST block-wait every Phase. Spawn agents → wait ALL completed → run gate_check.sh → PASS before entering next phase.
6. MUST respect blockedBy deps. Upstream task NOT completed → downstream task MUST NOT spawn.

Agent Prompt Construction Template — inject this at the beginning of every spawned agent's prompt:

Your Task ID is #{TASK_ID}.
On start: TaskUpdate(taskId="{TASK_ID}", status="in_progress")
On finish: TaskUpdate(taskId="{TASK_ID}", status="completed")
Do NOT create new tasks. Do NOT write checkpoint.json.