🛡️ AgenticPenTest

English | 简体中文 | 繁體中文 | Русский | Français | 日本語 | Deutsch

An LLM-driven red-team testing workbench for individual operators and local teams.

🎬 Chinese operation demo · 43 seconds · MP4

https://github.com/user-attachments/assets/8cd2723f-07e5-4fe8-ba8e-ac70b55676f5

Real UI actions with synthetic data: add an asset, select linked assets and save a plan. Task results are pre-seeded examples, not a live penetration test.

✨ Features

The Docker image includes MCP support. See the MCP setup guide for client configuration and permissions.

Module	Available capabilities
Workspaces and teams	Local login and first-admin setup; administrator/operator/viewer roles, invitations, welcome messages and password management; isolated personal data and shared team workspaces.
Dashboard	Asset, task, Agent and finding statistics; P0–P4 severity groups, candidate/confirmed states and filtered links into the corresponding records.
Asset management	CSV/TXT/JSON import templates, source uploads, canonical target grouping and deduplication; network, identity/credential, data, channel and personnel categories with task/evidence references.
Asset mapping	Saved ports, services, addresses and findings; mind-map, tree and star layouts, drag/zoom, minimap, fullscreen directory and collapse controls; persisted layout and color preferences.
Plans and tasks	Agent/workflow selection, quick/full depth and applicable checks; concurrent execution, tool-selection reasons, step details, searchable/formatted logs, retained results, interrupt/resume and task archive/trash.
Agent management	One Leader and eleven specialists, plus custom Agents; editable/resettable prompts, LLM translation, batch model assignment and explicit tool/workflow bindings.
LLM configuration	OpenAI Chat Completions/Responses, Anthropic and Gemini-compatible endpoints; custom Base URL, optional authenticated HTTP(S) proxies, connection tests and model discovery/manual IDs. SystemOne supports judgment tests, not text planning.
Tool management	Categories, search and pagination; file/ZIP upload and updates, source/runtime metadata, argument editing and execution preview, manual readiness checks and local or dependency-host adapters.
Cloud and hybrid assets	AWS, GCP, Azure and Alibaba Cloud China/International connections; official region selection, read-only assessment and hybrid correlation. Resource categories retain original service/type and documented meaning; search, category filters and configurable pagination (10 per page). Real cloud accounts remain unverified.
Threat modeling	Editable STRIDE architecture and data flows, linked assets, version history and risk tracking; LLM proposals require explicit human acceptance. Create validation-plan drafts and export JSON, Markdown or HTML.
C2 servers	SSH/SFTP and jump/proxy connections, tabbed terminals, background-session recovery, connection/command history, private/shared Markdown notes, tags/groups, port connectivity and IP location.
Listeners and sessions	Server/OS/port selection, start/stop/cancel, live state/logs and a service overview; supported reverse-connection presets and configured forward WebShell adapters.
Engagements	Target scope, time windows, allowed/denied techniques and stop conditions; timeline execution details, result filtering and conversion of recorded events into findings.
Controlled execution chains	Policy and budget checks, verification/approval cards, registered actions, rollback results and evidence. Requires AP_CHAIN_EXECUTION=on and configured, ready action executors.
PoC/Exploit and review	Finding-linked AI drafts, model/language selection and requirement refinement; code editing, search, save/export and review on a configured execution node with live output. Generated code still needs review and compatible dependencies.
Findings and reports	Finding filters, confirmation and retest evidence; six templates—pentest, assessment, audit, black-box, white-box and MITRE ATT&CK—with multilingual Markdown/HTML preview/export, bulk archive/trash operations and 30-day archive/7-day trash retention.
Settings and interface	Task/SSH/dependency/transfer limits, optional authenticated HTTP(S) proxies, database export and confirmed data reset; manual GitHub source-revision checks without automatic upgrades; seven UI languages and light/dark themes.
Developer MCP	stdio and Streamable HTTP, 36 typed tools, workspace/scoped credentials, expiry/revocation, OAuth PKCE, call auditing, idempotent mutations, task progress/cursor logs and saved job/report resources.

AgenticPenTest displays an authorization acknowledgement and legal footer; administrators can manage the notice in system settings.

🚀 Deployment

🐳 1. Pull and run the Docker image

Docker Engine/Desktop, using Linux amd64 containers. No host Node.js or Python is required.

docker pull docker.io/johncoke/agenticpentest:latest
docker run -d --name agenticpentest --restart unless-stopped \
  -p 127.0.0.1:8765:8765 \
  -e PUBLIC_ORIGIN=http://127.0.0.1:8765 \
  -v agenticpentest-data:/var/lib/agenticpentest \
  -v agenticpentest-tools:/opt/agenticpentest-tools \
  docker.io/johncoke/agenticpentest:latest

http://127.0.0.1:8765 · Docker

🧩 2. Deploy with Docker Compose

This method uses the published image and persistent named volumes. Repository access is currently required to obtain the Compose file.

git clone https://github.com/AaronCaiii/AgenticPentest.git AgenticPenTest
cd AgenticPenTest
docker compose up -d --pull always --no-build

🛠️ 3. Install from source

Linux amd64 with Git and Python 3. The installer asks for an installation directory (default under /opt), port, LAN access and tool profile. It uses an existing supported Node.js or installs an isolated, checksum-verified runtime.

git clone https://github.com/AaronCaiii/AgenticPentest.git AgenticPenTest
cd AgenticPenTest
python3 scripts/install-source.py

Open the printed URL after initialization. A fresh instance asks you to create the first administrator; there is no default account or password. The authorization notice appears before account creation. Installer options, proxy and startup details.

🖼️ Interface preview

📸 Static screenshots

Dashboard	Asset management
Threat modeling	Tasks and evidence

🧭 First engagement

1. Select personal or team mode, configure/test an LLM profile, and assign models to Agents.
2. Install the tools you need, manually check readiness, then add/import assets or upload source material.
3. Create a plan or task, select its Agent, workflow and depth; configure an engagement/policy when controlled actions require it, then start execution.
4. Inspect steps and logs, follow linked assets/findings, resolve review gaps, and export a report. Interrupted work keeps its saved evidence.

🔌 MCP integration

Use an MCP client to manage assets, dispatch Agents, run tasks and read evidence through the same backend as the Web UI. There are 36 typed tools; each credential sees only the operations allowed by its permissions and account role.

🔑 Create a developer credential

Open System settings → Developer & MCP, choose the allowed personal/team spaces, default space, permissions and expiry, then confirm with your current password. Copy the credential when it appears: it is shown only once. Credentials last 1–90 days, with a 30-day default, and can be revoked from the same page.

Permissions	Operations
assets:read / assets:write	Read assets and observations / import, update or retire assets
agents:read / agents:write	Read Agents, model metadata and tool capabilities / change prompts and bindings
tasks:read / tasks:execute	Read plans, task progress and logs / create, start, interrupt or resume work
reports:read / reports:write	Read findings, templates and reports / generate and archive reports

Task execution requires an operator role; changing Agent configuration requires an administrator role. Personal permissions apply only to the member's own space. Enable the chosen Agent, bind its LLM and tools, and manually check tool readiness before starting work.

🔗 Connect your client

Streamable HTTP: use your workbench's actual URL followed by /mcp, with Authorization: Bearer <developer-credential>. An optional X-Workspace-Mode: personal or team header selects the default space; the tool's workspace argument takes precedence. Use HTTPS when accessing the service across an untrusted network. OAuth authorization-code authentication with S256 PKCE is also supported.

⚙️ Example HTTP client configuration

{
  "mcpServers": {
    "agenticpentest": {
      "type": "http",
      "url": "https://workbench.example/mcp",
      "headers": {
        "Authorization": "Bearer <developer-credential>",
        "X-Workspace-Mode": "personal"
      }
    }
  }
}

This is a generic example: adapt transport names, configuration keys and secret storage to your MCP client. The detailed guide includes a JavaScript SDK example. A browser login cookie is not an MCP credential.

stdio: install Node.js ≥22.19 and this project's dependencies on the client machine, then configure the bridge below. The bridge connects to the running workbench; it does not create another database or scheduler.

⚙️ Example stdio client configuration

{
  "mcpServers": {
    "agenticpentest": {
      "command": "node",
      "args": ["<project-directory>/scripts/mcp-stdio.mjs"],
      "env": {
        "AP_MCP_URL": "https://workbench.example/mcp",
        "AP_MCP_TOKEN": "<developer-credential>",
        "AP_MCP_WORKSPACE": "personal"
      }
    }
  }
}

Replace the script path, URL and credential. On Windows, use an absolute script path with forward slashes or escaped backslashes. Use the client's protected environment/secret configuration rather than committing tokens. AP_MCP_WORKSPACE must be a space allowed by the credential; omit it to use the credential's default.

▶️ Run a task and retrieve its evidence

1. Inspect capabilities_list, agents_list, models_list and tools_list.
2. Import your authorized lab assets with assets_import; importing does not start a scan.
3. Call jobs_create with the returned asset ID and selected Agent ID. It creates a draft by default (startNow: false); explicitly call jobs_start to run it.
4. Poll jobs_get for progress and jobs_logs for output. Pass the returned data.nextCursor as after on the next log request; each page contains at most 200 entries.
5. Read observations_list and findings_list, then use reports_generate and reports_get to retrieve a report.

All write tools require an idempotencyKey (8–120 letters, numbers or _.:-). Retry the same operation with the same key and input to avoid duplicates. Updates also require the current record version; see the guide for each tool's _rev/rev field. Disconnecting the client does not stop an accepted task: use jobs_interrupt or jobs_cancel; saved evidence is retained.

MCP calls obey the same installation-bound network policy as the UI and tool processes. A signed network authorization file is not a developer token, and MCP has no network-unlock operation. NETWORK_TARGET_RESTRICTED means the target is outside the permitted scope; NETWORK_EXECUTOR_UNSUPPORTED or NETWORK_REMOTE_EXECUTOR_UNSUPPORTED means that execution path cannot enforce the policy. See network restrictions for setup and authorization.

Detailed MCP guide: runnable examples, scopes, tool parameters, OAuth and troubleshooting · 中文指南.

🏗️ Architecture

Layer	Implementation
Frontend	JavaScript SPA, Vue 3 / Element Plus widgets, xterm.js
Backend	Node.js ES modules, HTTP/NDJSON APIs, in-process queue and execution adapters
MCP	Streamable HTTP endpoint and stdio bridge; typed domain operations, scoped grants, OAuth and auditing
Database	SQLite WAL, workspace isolation, encrypted connection secrets, hashed developer tokens and local evidence files

Dockerfile    Container image build
compose.yaml  Deployment with the published image
src/          Backend, execution adapters and MCP service
frontend/     Widget source
public/       Served UI and generated bundles
i18n/         Translation source
config/       Agent presets, tool recipes and migration baselines
scripts/      Build, installation, maintenance and stdio bridge
tests/        Feature tests and isolated fixtures
docs/         Guides, translated READMEs and screenshots
deploy/       Container runtime helpers

Architecture details.

🤝 Documentation and contributions

• Cloud inventory, account sites and resource classification
• Threat modeling workflow and first-release scope
• MCP developer integration
• Complete usage and legal guide
• User guides
• Setup and data configuration
• Development and translations
• PR / Issue guidelines

Git does not include databases, model/SSH keys or test history. Initialization preserves existing data; back up SQLite and data/master.key outside Git.

Use the Bug report / Feature request issue forms and PR template. Include reproduction steps, environment and relevant validation; remove credentials and private target data.

✉️ Authorization and contact

Teams, companies and individuals who need to extend the AgenticPenTest network scope can apply at [email protected]:

1. In System settings → Network restrictions, export the installation request JSON.
2. Email the file with your name or organization, intended use, requested CIDRs and validity period.
3. Import the installation-bound signed authorization file returned by the author on the same settings page.

Do not send passwords, tokens or signing private keys. Network authorization does not replace permission from the target owner.

For secondary development or integration, contact the author for a network authorization file or support, and comply with applicable local laws. Use, modification and distribution of the source remain subject to the MIT license and applicable third-party licenses.

We reply to authorization requests within 24 hours. Copy the template below and attach the installation request JSON.

📧 Email template

Subject: [AgenticPenTest authorization request] <name or organization>

Name / organization:
Contact email:
Intended use:
Installation ID:
Requested network scope (CIDRs, or all IPv4/IPv6 networks):
Requested validity period:
Target-owner authorization / testing scope summary:
Attachment: installation request JSON exported from System settings → Network restrictions

I will use AgenticPenTest within the target owner’s authorization and comply with applicable laws.
Do not attach passwords, API tokens, signing private keys or sensitive target data.

Business cooperation and sponsorship: contact [email protected]. Sponsorship helps support continued development and maintenance.

⚖️ Responsible use and license

Obtain target-owner authorization before testing, stay within its scope and comply with local laws. Unlawful use is prohibited; users are responsible for the consequences of their use. AgenticPenTest displays an authorization acknowledgement and legal footer.

Project-owned code is licensed under MIT. Third-party tools retain their own licenses.

• Network scope and signed installation unlock

☁️ Codespaces experience

Create a Codespace, wait for environment checks, dependency installation and initialization, then open port 8765 in the Ports panel. Read the authorization notice and create your own administrator; no default credentials are provided. Restarting preserves the database and installation identity.

This is a development experience, not permanent hosting. Keep the forwarded port Private. No maintainer network, credentials or proxy is required. Tools and cloud SDKs are not downloaded automatically. Without the trusted host guard, guarded tool and remote execution remain blocked; a license does not bypass this requirement. UI, asset management, manual threat modeling and report workflows are available; LLM/cloud operations need your own configuration. Verified in a real GitHub Codespace: automatic installation/build/initialization, private HTTPS forwarding, the 10-second authorization reader, administrator creation, asset import, refresh persistence, task/MCP public-target rejection, loopback HTTP and fail-closed tool execution. The optional GitHub port-trust screen appears before the application. Cloud accounts and external LLM providers remain unverified. Stop/delete the Codespace when finished; deletion removes its local data. GitHub quotas and billing apply.

python3 .devcontainer/lifecycle.py setup
python3 .devcontainer/lifecycle.py start

Execution support in the default Codespace

Execution path	Status
Agent scheduling and built-in HTTP / DNS / TLS	Supported for reachable internal targets; requires your LLM configuration
Subprocess tools, including Nmap and uploaded executables	Blocked: trusted host guard unavailable
Remote commands, SSH terminals, listeners and WebShell execution	Blocked: equivalent remote policy enforcement unavailable

The tested container has no systemd system service manager, read-only cgroups and denied namespace creation. Installing a systemd package alone cannot enable the guard. Environment checks record these prerequisites in reports/codespaces/environment.json; System settings → Network restrictions shows the supported transports and blocked execution paths. Internal means networks reachable from the Codespace; 127.0.0.1 is the Codespace itself. Full tool execution requires a Linux deployment with a registered, kernel-verified guard. Do not expose the Docker socket or disable the policy as a workaround.

⭐ Star History

💜 Sponsorship

Support continued development and maintenance of AgenticPenTest on Afdian.

💜 Support on Afdian