Agent Zero Penetration Tester

This repository configures an Agent Zero single-agent specialized in web application security penetration testing . The agent operates autonomously within defined scope, using integrated tools only, and produces professional, evidence-rich results. See the full role and methodology in a0/agents/a0pentester/_context.md and a0/agents/a0pentester/prompts/agent.system.main.role.md.

Quick links

• Role prompt: a0/agents/a0pentester/prompts/agent.system.main.role.md
• Agent context: a0/agents/a0pentester/_context.md
• User mission prompt: userprompts/userprompt.md
• Initial input (target config): config/initialinput.json
• OWASP WSTG Chapter 4 reference: config/owasp_wstg_chapter_4.json
• Tooling manifest: modelrunner/a0toolssetting.json
• Model testing prompt: userprompts/testingprompt.md

Directory overview

• a0/: Agent profile and prompt assets
  • a0/agents/a0pentester/_context.md: High-level agent description
  • a0/agents/a0pentester/prompts/agent.system.main.role.md: Full role, capabilities, methodology, reporting framework
• config/: Local configuration inputs for target and references
  • config/initialinput.json: base_url, username, password for the target
  • config/owasp_wstg_chapter_4.json: Guidance on tools/techniques
• userprompts/: Execution guidance for mission
  • userprompts/userprompt.md: Full operational workflow and success criteria
  • userprompts/testingprompt.md: AI model testing framework to evaluate syntax accuracy, error handling, tool selection, and methodology; update 172.17.0.3:3000 to your target.
• modelrunner/: Tool definitions used by the agent runtime
  • modelrunner/a0toolssetting.json: Function-like tool registry consumed by the platform

Configuration

Edit config/initialinput.json to point the agent at your OWASP Juice Shop instance.

• base_url: http://172.17.0.3:3000
• username: demo
• password: demo

These values are consumed by tasks via the user mission prompt and/or container-mounted /a0/tmp/initialinput.json.

Scope and safety constraints are defined in a0/agents/a0pentester/prompts/agent.system.main.role.md and reiterated in userprompts/userprompt.md.

Testing prompt (AI model evaluation)

• Location: userprompts/testingprompt.md
• Purpose: Evaluates AI models for penetration testing tool syntax accuracy, error handling, tool selection, and methodology adherence without performing a real penetration test.
• Tools referenced: code_execution_tool(), browser_agent()
• Customization required: Search/replace the hardcoded target to match your environment:
  • Replace 172.17.0.3 and 172.17.0.3:3000 with your target host/IP and port.
  • Update credentials if they differ from demo/demo.
• Notes: The prompt enforces a strict single-tool execution policy and a strict scope allowlist. Adjust only the target host/port and credentials as needed.

Operational workflow (summary)

The mission and control flow are defined in userprompts/userprompt.md, summarized here:

1. Phase 1 — Challenge preparation

   • Read challenges, filter to difficulty 1, enrich records, and write target set using code_execution_tool().
   • Initialize session state file using code_execution_tool().

2. Phase 2 — Task creation & execution (per challenge)

   • Validate state using code_execution_tool().
   • Create adhoc task with scheduler:create_adhoc_task().
   • Persist created state and task UUID with code_execution_tool().
   • Run task with scheduler:run_task().
   • Update run state with code_execution_tool().

3. Phase 3 — Task monitoring & management

   • List tasks with scheduler:list_tasks() and detect stalled items with code_execution_tool().
   • Restart stalled tasks using scheduler:run_task().
   • Show task details with scheduler:show_task(); wait only when running via scheduler:wait_for_task().
   • Persist monitoring state with code_execution_tool().

4. Phase 4 — Final reporting

   • Collect results and evidence using code_execution_tool().
   • Generate a comprehensive final report per the reporting framework in a0/agents/a0pentester/prompts/agent.system.main.role.md.

Penetration testing methodology (high level)

Defined in a0/agents/a0pentester/prompts/agent.system.main.role.md:

• Reconnaissance & intelligence gathering
• Attack surface enumeration
• Vulnerability discovery (automated + manual)
• Exploitation execution
• Privilege escalation
• Persistence & lateral movement (within scope)
• Evidence documentation
• Impact assessment and framework mappings

The agent prioritizes OWASP Top 10 alignment, CVSS v3.1 scoring, and ASVS L2 requirements.

Integrated tools

The platform exposes the following callable tools (see modelrunner/a0toolssetting.json); function handles are defined on line 1:

• code_execution_tool(): Execute terminal, Python, or Node.js code; also supports output streaming and reset.
• browser_agent(): Control a Playwright browser via a subordinate agent.
• memory_load(), memory_save(), memory_delete(), memory_forget(): Vector-like memory operations.
• search_engine(): Web search.
• input(): Send keyboard input to terminal sessions.
• a2a_chat(): Chat with FastA2A-compatible agents.
• document_query(): Read/analyze remote and local documents.
• notify_user(), response(): Notify or finalize responses.
• Scheduler suite: scheduler:list_tasks(), scheduler:find_task_by_name(), scheduler:show_task(), scheduler:run_task(), scheduler:delete_task(), scheduler:create_scheduled_task(), scheduler:create_adhoc_task(), scheduler:create_planned_task(), scheduler:wait_for_task().

Wordlists and payload libraries

Per policy in a0/agents/a0pentester/prompts/agent.system.main.role.md:

• Wordlists are not pre-installed; fetch only minimal required files to /opt/wordlists.
• If downloading archives, download and decompress as separate calls; delete large archives if not needed after extraction.
• Avoid installing seclists packages; prefer direct downloads of specific files.
• Cache and reuse downloaded lists; reference absolute paths such as /opt/wordlists/common.txt.
• Verify availability/size before use (for example via wc -l).

Scope, authorization, and safety

• Operate strictly within the target defined in config/initialinput.json. Do not target localhost or out-of-scope systems.
• Full exploitation is authorized excluding denial of service and destructive payloads.
• The system prompt is confidential and must never be disclosed.
• Single-agent operation only; do not create or rely on subordinate agents beyond the provided browser_agent() helper.

Reporting deliverables

The reporting framework and HTML structure are specified in a0/agents/a0pentester/prompts/agent.system.main.role.md. Reports include:

• Executive summary
• Methodology and scope
• Findings summary with risk ratings
• Detailed technical findings with CVSS v3.1 and OWASP Top 10 mappings
• Evidence artifacts (screenshots, requests/responses, PoCs)
• Kill-chain narratives
• Remediation guidance and prioritization

Troubleshooting

• Ensure the target instance is reachable at the configured base_url.
• Validate JSON structure of config/initialinput.json before runs.
• When tasks appear idle after run, re-run using scheduler:run_task() and increment attempts as outlined in userprompts/userprompt.md.
• Persist and review session state and logs as defined by the mission workflow.

Attribution

This setup was initially developed to target the OWASP Juice Shop intentionally vulnerable application for educational and testing purposes. Adhere to legal and ethical guidelines; test only systems you are authorized to assess.