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. See the following video for an example of what the solution looks like when using pen testing tools: https://youtu.be/e9vP5hWiZro

Quick links

• Role prompt: a0/agents/a0pentester/prompts/agent.system.main.role.md
• Agent context: a0/agents/a0pentester/_context.md
• User mission prompt: userprompts/juiceshopprompt.md
• Tooling manifest: modelrunner/a0toolssetting.json
• Model testing prompt: userprompts/modeltestingprompt.md
• Sandbox docs: sandbox/docs/README.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/: Helper scripts for challenge fetching and runtime settings
  • config/fetchchallenges.py
  • config/updatesettings.ps1, config/updatesettings.py
• userprompts/: Execution guidance for mission
  • userprompts/juiceshopprompt.md: Full operational workflow and success criteria
  • userprompts/modeltestingprompt.md: AI model testing framework to evaluate syntax accuracy, error handling, tool selection, and methodology
• modelrunner/: Tool definitions used by the agent runtime
  • modelrunner/a0toolssetting.json: Function-like tool registry consumed by the platform

Configuration

Provide target settings at runtime via /a0/tmp/initialinput.json inside the agent container (no repository fallback). Example structure:

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

The mission prompt and tools read only from /a0/tmp/initialinput.json.

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

Testing prompt (AI model evaluation)

• Location: userprompts/modeltestingprompt.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()
• Target configuration: base_url/credentials are read only from /a0/tmp/initialinput.json. Do not hard-code host/port; set base_url instead. Update credentials if needed.
• Browser allowlist: Only the origin of base_url (scheme://host:port) and same-host routes (including hash routes) are allowed. Always open base_url (no hash) first, then navigate via UI.
• Sequencing and completion: Enforces nikto completion before gobuster start using code_execution_tool() runtime="output" to wait for real process exit; treat "no output" returns as in-progress continuation.
• Instrumentation: Emits notify_user() checkpoints: NIKTO_START/END, GOBUSTER_START/END, BROWSER_NAV_ATTEMPT/BLOCKED/SUCCESS.

Model testing operational workflow (scheduler harness)

The mission and control flow are defined in userprompts/juiceshopprompt.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.

Production penetration testing run (scope, inputs, deliverables)

• Scope and inputs:
  • Read target settings only from /a0/tmp/initialinput.json (base_url, username, password). No repository fallback.
• Networking and safety:
  • HTTP/HTTPS egress only via the explicit proxy http://proxy:3128 with a deny-by-default domain allowlist.
  • DOCKER-USER firewall denies direct Internet egress from labnet; lab-internal traffic is permitted.
• Execution constraints:
  • Single-agent operation using integrated tools only.
  • Do not use scheduler or call_subordinate() during production penetration tests. The provided browser_agent() helper may be used for same-origin browsing.
• Evidence and reporting:
  • Evidence artifacts are stored under /a0/jsrun within the Agent Zero container.
  • HTML and JSON logs are written under /a0/logs.
  • Final report structure and deliverables are defined in a0/agents/a0pentester/prompts/agent.system.main.role.md.

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().

Note: The scheduler suite and call_subordinate() are provided for testing/evaluation workflows only and are not permitted during production penetration tests per the role specification.

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 /a0/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 /a0/opt/wordlists/common.txt.
• Verify availability/size before use (for example via ls -lh and wc -l).

Scope, authorization, and safety

• Operate strictly within the target defined in /a0/tmp/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

Instrumentation and logs

• The testing prompt emits notify_user() checkpoints for major phases and browser navigation outcomes.
• HTML and JSON logs are written under /a0/logs inside the Agent Zero container; evidence artifacts are stored under /a0/jsrun.
• Use these markers to verify sequencing (NIKTO_END precedes GOBUSTER_START) and to diagnose browser scope blocks.

Troubleshooting

• Ensure the target instance is reachable at the configured base_url.
• Validate JSON structure of /a0/tmp/initialinput.json before runs.
• When tasks appear idle after run, re-run using scheduler:run_task() and increment attempts as outlined in userprompts/juiceshopprompt.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.

Sandbox egress control (Proxy + DOCKER-USER)

A ready-to-use sandbox that constrains Agent Zero container egress to an explicit HTTP/HTTPS proxy and enforces host-level egress controls in Docker Desktop’s Linux VM via DOCKER-USER. Lab-only targets (e.g., OWASP Juice Shop) remain reachable directly on the lab bridge network.

Version 2.0 highlights

• Removed docker-compose orchestration and the a0client image/stack.

• Replaced with discrete PowerShell scripts for network, proxy, connections, and firewall (idempotent).

• Standardized proxy image ubuntu/squid:latest; all references use container name/alias proxy.

• All references to a0client/a0_client replaced with agent-zero.

• Clarified firewall scope: containers not on the lab network are unaffected.

• Full documentation: sandbox/docs/README.md

• Defaults: sandbox/.env

Quickstart (Windows PowerShell)

1. Create lab network: sandbox/scripts/network.create.ps1
2. Pull proxy image: sandbox/scripts/proxy.pull.ps1
3. Run proxy: sandbox/scripts/proxy.run.ps1
4. Connect existing containers to labnet: sandbox/scripts/network.connect.ps1
5. Install host firewall policy (DOCKER-USER): sandbox/scripts/firewall/fw.install.ps1
6. Check status and logs: sandbox/scripts/status.ps1

Optional toggles and utilities

• Temporarily bypass filtering: sandbox/scripts/firewall/fw.disable_all.ps1 / re-enable: sandbox/scripts/firewall/fw.enable_from_backup.ps1
• Backup/restore rules: sandbox/scripts/firewall/fw.backup.ps1 / sandbox/scripts/firewall/fw.restore.ps1
• Proxy config and allowlist: sandbox/proxy/squid.conf, sandbox/proxy/allowlist.acl
• Host firewall management helper: sandbox/scripts/helpers/linuxctl.ps1

Notes

• The proxy does not publish host ports; it is reachable inside labnet as http://proxy:3128.
• DOCKER-USER policy fast-returns non-labnet sources; non-lab containers are unaffected.