pentesting 0.73.6 → 0.73.8

package/README.md

@@ -1,12 +1,15 @@
 <div align="center">
 
-<img src="https://api.iconify.design/game-icons:fizzing-flask.svg?color=%232496ED" width="80" height="80" alt="Pentesting Agent" />
+<a href="https://agnusdei1207.github.io/brainscience/pentesting/">
+  <img src="https://api.iconify.design/game-icons:fizzing-flask.svg?color=%232496ED" width="80" height="80" alt="Pentesting Agent" />
+</a>
 
 # pentesting
 > **Autonomous Offensive Security AI Agent**
 
-[![npm](https://img.shields.io/badge/npm-pentesting-2496ED)](https://www.npmjs.org/package/pentesting)
-[![docker](https://img.shields.io/badge/docker-pentesting-2496ED)](https://hub.docker.com/r/agnusdei1207/pentesting)
+[![npm](https://img.shields.io/badge/npm-pentesting-CB3837?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/pentesting)
+[![docker](https://img.shields.io/badge/docker-pentesting-2496ED?style=flat-square&logo=docker&logoColor=white)](https://hub.docker.com/r/agnusdei1207/pentesting)
+[![docs](https://img.shields.io/badge/docs-brainscience-10B981?style=flat-square&logo=readthedocs&logoColor=white)](https://agnusdei1207.github.io/brainscience/pentesting/)
 
 </div>
 
@@ -30,48 +33,26 @@
 
 ## Purpose
 
-Pentesting support tool. Can autonomously execute network penetration tests or assist with generic Capture The Flag (CTF) challenges (such as Reverse Engineering, Cryptography, and binary analysis) without requiring a specific network target.
+Autonomous network penetration testing and CTF assistant. Supports offensive security workflows including recon, exploit, and post-exploitation.
 
 ## Quick Start
 
-### z.ai — GLM Coding Plan Max (Recommended)
-
-Web search is included in the subscription — **no separate Search API key required**.
-
-If you want the repository default start path, export your env vars locally and run:
-
-```bash
-export PENTEST_API_KEY="your_z_ai_key"
-export PENTEST_BASE_URL="https://api.z.ai/api/anthropic"
-export PENTEST_MODEL="glm-4.7"
-npm run start
-```
-
-`npm run start -- -t 10.10.10.5` passes CLI arguments through to the container entrypoint.
-Use `npm run start:local` only if you explicitly want the non-container Node runtime.
+### 🐳 Docker (Recommended)
 
 ```bash
 docker run -it --rm \
-  -e PENTEST_API_KEY="your_z_ai_key" \
+  -e PENTEST_API_KEY="your_key" \
   -e PENTEST_BASE_URL="https://api.z.ai/api/anthropic" \
   -e PENTEST_MODEL="glm-4.7" \
   agnusdei1207/pentesting
 ```
 
-Enable container Tor mode by adding `-e PENTEST_TOR=true` to the same `docker run` command.
-
-### External Search API (Optional)
-
-For providers other than z.ai, or to use a dedicated search backend.
+### 🐉 Kali Linux (Native)
 
 ```bash
-docker run -it --rm \
-  -e PENTEST_API_KEY="your_api_key" \
-  -e PENTEST_BASE_URL="https://open.bigmodel.cn/api/paas/v4" \
-  -e PENTEST_MODEL="glm-4-plus" \
-  -e SEARCH_API_KEY="your_brave_api_key" \
-  -e SEARCH_API_URL="https://api.search.brave.com/res/v1/web/search" \
-  agnusdei1207/pentesting
+npm install -g pentesting
+export PENTEST_API_KEY="your_key"
+pentesting
 ```
 
 ### Environment Variables
@@ -79,38 +60,10 @@ docker run -it --rm \
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `PENTEST_API_KEY` | ✅ | LLM API key |
-| `PENTEST_BASE_URL` | ❌ | Custom API endpoint (web search auto-enabled when URL contains `z.ai`) |
-| `PENTEST_MODEL` | ❌ | Model override (defaults depend on provider/runtime; examples use `glm-4.7`) |
-| `SEARCH_API_KEY` | ❌ | External search API key (not needed with z.ai) |
-| `SEARCH_API_URL` | ❌ | External search API URL (not needed with z.ai) |
-| `PENTEST_SCOPE_MODE` | ❌ | Scope mode override: `advisory` or `enforce` |
-| `PENTEST_APPROVAL_MODE` | ❌ | Approval mode override: `advisory` or `require_auto_approve` |
-| `PENTEST_TOR` | ❌ | Container-only Tor mode. When `true`, the Docker entrypoint starts Tor and launches the agent through `proxychains4` |
-
-Safety defaults:
-
-- Containerized runtime defaults to `PENTEST_SCOPE_MODE=advisory` and `PENTEST_APPROVAL_MODE=advisory`.
-- Non-container runtime defaults to `PENTEST_SCOPE_MODE=enforce` and `PENTEST_APPROVAL_MODE=require_auto_approve`.
-- Explicit env vars override those defaults.
-
-Tor notes:
-
-- Tor is supported only in the containerized runtime.
-- There is no in-app `/tor` toggle. Enable it at container startup with `-e PENTEST_TOR=true`.
-- Non-container runs ignore `PENTEST_TOR`, so local host execution stays on direct networking.
-
-### Developer Verification
-
-```bash
-npm run verify
-npm run verify:docker
-```
-
-- `npm run verify` now runs typecheck, tests, and build.
-- `npm run verify:docker` builds the image and launches the Docker TUI path through `test.sh`.
-- `npm run check` prunes Docker state, runs tests and build, rebuilds the local image, and then launches the Docker TUI path.
-- `npm run check:clean` runs `npm run check:ci` after an explicit `docker system prune -af --volumes`.
-
+| `PENTEST_BASE_URL` | ❌ | API endpoint (z.ai auto-enables web search) |
+| `PENTEST_MODEL` | ❌ | Model (default: `glm-4.7`) |
+| `SEARCH_API_KEY` | ❌ | External search key (not needed for z.ai) |
+| `PENTEST_TOR` | ❌ | Enable Tor (`true`, Docker only) |
 ---
 
 ## Issue
@@ -134,124 +87,3 @@ we don't stop until the flag is captured.
 <br/>
 
 </div>
-
----
-
-## Research References
-
-This section collects representative papers matched to the design themes reflected in `pentesting`.
-
-It is an inference-based reconstruction from topic overlap, not a verbatim personal reading log.
-
-### Mapping
-
-- Offensive security agent papers inform the autonomous pentest workflow.
-- Planner-executor and heterogeneous collaboration papers inform task decomposition and coordination.
-- Multi-agent orchestration papers inform role separation, delegation, and control topology.
-- Benchmark and evaluation papers inform capability framing and validation strategy.
-
-### Offensive Security Agents
-
-1. [PentestGPT: Evaluating and Harnessing Large Language Models for Automated Penetration Testing](https://www.usenix.org/conference/usenixsecurity24/presentation/deng)  
-   USENIX Security 2024  
-   Relevance: autonomous pentest loop and operator-assist workflow.
-
-2. [D-CIPHER: Dynamic Collaborative Intelligent Agents with Planning and Heterogeneous Execution for Enhanced Reasoning in Offensive Security](https://arxiv.org/abs/2502.10931)  
-   arXiv 2025  
-   Relevance: collaborative offensive agents, planning, and heterogeneous execution roles.
-
-3. [Towards Automated Software Security Testing: Augmenting Penetration Testing through LLMs](https://conf.researchr.org/room/ssbse-2023/fse-2023-venue-golden-gate-c1)  
-   ESEC/FSE 2023  
-   Relevance: LLM-augmented penetration testing as a software engineering workflow.
-
-4. [LLMs as Hackers: Autonomous Linux Privilege Escalation Attacks](https://arxiv.org/abs/2310.11409)  
-   arXiv 2023  
-   Relevance: offensive autonomy in post-exploitation and privilege escalation.
-
-5. [Can LLMs Hack Enterprise Networks? Autonomous Assumed Breach Penetration-Testing Active Directory Networks](https://arxiv.org/abs/2502.04227)  
-   arXiv 2025  
-   Relevance: enterprise network movement and AD-focused agent behavior.
-
-6. [LLM Agents can Autonomously Hack Websites](https://arxiv.org/abs/2402.06664)  
-   arXiv 2024  
-   Relevance: web exploitation agents and end-to-end task execution.
-
-7. [LLM Agents can Autonomously Exploit One-day Vulnerabilities](https://arxiv.org/abs/2404.08144)  
-   arXiv 2024  
-   Relevance: exploit execution against known-vulnerability targets.
-
-8. [Teams of LLM Agents can Exploit Zero-Day Vulnerabilities](https://arxiv.org/abs/2406.01637)  
-   arXiv 2024  
-   Relevance: multi-agent offensive workflows for harder vulnerability exploitation.
-
-9. [AutoPentester: An LLM Agent-based Framework for Automated Pentesting](https://arxiv.org/abs/2510.05605)  
-   arXiv 2025  
-   Relevance: explicit automated pentesting framework alignment.
-
-### Benchmarks and Cyber Evaluation
-
-10. [AutoPenBench: A Vulnerability Testing Benchmark for Generative Agents](https://aclanthology.org/2025.emnlp-industry.114/)  
-    EMNLP Industry 2025  
-    Relevance: benchmark framing for generative vulnerability-testing agents.
-
-11. [Training Language Model Agents to Find Vulnerabilities with CTF-Dojo](https://arxiv.org/abs/2508.18370)  
-    arXiv 2025  
-    Relevance: CTF-grounded vulnerability discovery and training/eval setup.
-
-12. [Cybench: A Framework for Evaluating Cybersecurity Capabilities and Risks of Language Models](https://arxiv.org/abs/2408.08926)  
-    arXiv 2024  
-    Relevance: evaluation of cybersecurity capability and misuse risk.
-
-13. [CyberGym: Evaluating AI Agents' Cybersecurity Capabilities with Real-World Vulnerabilities at Scale](https://arxiv.org/abs/2506.02548)  
-    arXiv 2025  
-    Relevance: large-scale realistic vulnerability evaluation.
-
-14. [CyberSecEval 2: A Wide-Ranging Cybersecurity Evaluation Suite for Large Language Models](https://arxiv.org/abs/2404.13161)  
-    arXiv 2024  
-    Relevance: broad cyber eval framing and safety measurement.
-
-15. [When LLMs Meet Cybersecurity: A Systematic Literature Review](https://arxiv.org/abs/2405.03644)  
-    arXiv 2024  
-    Relevance: survey grounding across offensive and defensive use cases.
-
-16. [Large Language Models in Cybersecurity: State-of-the-Art](https://arxiv.org/abs/2402.00891)  
-    arXiv 2024  
-    Relevance: landscape overview for positioning the project.
-
-### Multi-Agent Collaboration and Orchestration
-
-17. [A Survey on Large Language Model based Autonomous Agents](https://arxiv.org/abs/2308.11432)  
-    arXiv 2023  
-    Relevance: agent architecture baseline and terminology.
-
-18. [Large Language Model based Multi-Agents: A Survey of Progress and Challenges](https://arxiv.org/abs/2402.01680)  
-    arXiv 2024  
-    Relevance: multi-agent coordination patterns and failure modes.
-
-19. [AutoGen: Enabling Next-Gen LLM Applications via Multi-Agent Conversation](https://arxiv.org/abs/2308.08155)  
-    arXiv 2023  
-    Relevance: role-based dialogue and tool-using multi-agent orchestration.
-
-20. [MetaGPT: Meta Programming for A Multi-Agent Collaborative Framework](https://arxiv.org/abs/2308.00352)  
-    arXiv 2023  
-    Relevance: structured role decomposition and pipeline-style collaboration.
-
-21. [ChatDev: Communicative Agents for Software Development](https://aclanthology.org/2024.acl-long.810/)  
-    ACL 2024  
-    Relevance: communication protocol and software-task role separation.
-
-22. [CAMEL: Communicative Agents for "Mind" Exploration of Large Language Model Society](https://arxiv.org/abs/2303.17760)  
-    arXiv 2023  
-    Relevance: agent role prompting and cooperative interaction patterns.
-
-23. [AgentVerse: Facilitating Multi-Agent Collaboration and Exploring Emergent Behaviors](https://arxiv.org/abs/2308.10848)  
-    arXiv 2023  
-    Relevance: multi-agent environment framing and emergent collaboration.
-
-24. [Scaling Large-Language-Model-based Multi-Agent Collaboration](https://arxiv.org/abs/2406.07155)  
-    arXiv 2024  
-    Relevance: scale behavior and coordination bottlenecks.
-
-25. [Multi-Agent Collaboration via Evolving Orchestration](https://arxiv.org/abs/2505.19591)  
-    arXiv 2025  
-    Relevance: orchestration policy evolution and adaptive coordination.

package/dist/{agent-tool-3Y7YKMCZ.js → agent-tool-Y6CG5KRL.js}

@@ -5,7 +5,7 @@ import {
   createContextExtractor,
   getLLMClient,
   getShellSupervisorLifecycleSnapshot
-} from "./chunk-HSZZHAGX.js";
+} from "./chunk-DN7INJ7C.js";
 import {
   AGENT_ROLES,
   EVENT_TYPES,
@@ -13,7 +13,7 @@ import {
   TOOL_NAMES,
   getProcessOutput,
   listBackgroundProcesses
-} from "./chunk-4HG57VDC.js";
+} from "./chunk-26G2YIOA.js";
 import {
   DETECTION_PATTERNS,
   PROCESS_EVENTS,

package/dist/{chunk-4HG57VDC.js → chunk-26G2YIOA.js}

@@ -347,7 +347,7 @@ var INPUT_PROMPT_PATTERNS = [
 ];
 
 // src/shared/constants/agent.ts
-var APP_VERSION = "0.73.6";
+var APP_VERSION = "0.73.8";
 var APP_DESCRIPTION = "Autonomous Penetration Testing AI Agent";
 var LLM_ROLES = {
   SYSTEM: "system",
@@ -3829,6 +3829,25 @@ var StateSerializer = class {
     }
   }
   static formatDelegatedTasks(state3, lines) {
+    const activeExecution = state3.getActiveDelegatedExecution();
+    if (activeExecution) {
+      const worker = activeExecution.workerType ? ` worker:${activeExecution.workerType}` : "";
+      const resume = activeExecution.resumeTaskId ? ` resume:${activeExecution.resumeTaskId}` : "";
+      lines.push(`Delegated Execution [running]: ${activeExecution.task}${worker}${resume}`);
+      if (activeExecution.target) {
+        lines.push(`  target: ${activeExecution.target}`);
+      }
+      if (activeExecution.context) {
+        lines.push(`  context: ${activeExecution.context}`);
+      }
+      if (activeExecution.parentTaskId || activeExecution.rootTaskId) {
+        const chainParts = [
+          activeExecution.parentTaskId ? `parent:${activeExecution.parentTaskId}` : "",
+          activeExecution.rootTaskId ? `root:${activeExecution.rootTaskId}` : ""
+        ].filter(Boolean);
+        lines.push(`  chain: ${chainParts.join(" ")}`);
+      }
+    }
     const activeTasks = state3.getActiveDelegatedTasks();
     if (activeTasks.length === 0) return;
     lines.push(`Delegated Tasks (${activeTasks.length} active):`);
@@ -3993,6 +4012,7 @@ function saveState(state3) {
     currentPhase: state3.getPhase(),
     missionSummary: state3.getMissionSummary(),
     missionChecklist: state3.getMissionChecklist(),
+    activeDelegatedExecution: state3.getActiveDelegatedExecution(),
     delegatedTasks: state3.getDelegatedTasks()
   };
   const sessionFile = join5(sessionsDir, FILE_PATTERNS.session());
@@ -4064,6 +4084,9 @@ function loadState(state3) {
     if (snapshot.missionChecklist?.length > 0) {
       state3.restoreMissionChecklist(snapshot.missionChecklist);
     }
+    if (snapshot.activeDelegatedExecution) {
+      state3.restoreActiveDelegatedExecution(snapshot.activeDelegatedExecution);
+    }
     if (Array.isArray(snapshot.delegatedTasks)) {
       for (const task of snapshot.delegatedTasks) {
         state3.restoreDelegatedTask(task);

package/dist/{chunk-HSZZHAGX.js → chunk-DN7INJ7C.js}

@@ -64,7 +64,7 @@ import {
   startBackgroundProcess,
   stopBackgroundProcess,
   writeFileContent
-} from "./chunk-4HG57VDC.js";
+} from "./chunk-26G2YIOA.js";
 import {
   DETECTION_PATTERNS,
   HEALTH_CONFIG,
@@ -8264,6 +8264,7 @@ var SharedState = class {
    */
   currentObjective = null;
   delegatedTasks = [];
+  activeDelegatedExecution = null;
   constructor() {
     this.targetState = new TargetState(this.attackGraph);
     this.findingState = new FindingState();
@@ -8290,6 +8291,7 @@ var SharedState = class {
     this.artifacts = [];
     this.currentObjective = null;
     this.delegatedTasks = [];
+    this.activeDelegatedExecution = null;
     this.lastReflection = "";
     this.lastTriageMemo = "";
   }
@@ -8407,6 +8409,40 @@ var SharedState = class {
   getTimeStatus() {
     return this.sessionState.getTimeStatus();
   }
+  startDelegatedExecution(execution) {
+    const now = Date.now();
+    const parentTask = execution.resumeTaskId ? this.delegatedTasks.find((existing) => existing.id === execution.resumeTaskId) : void 0;
+    const activeExecution = {
+      id: generatePrefixedId("delegated_exec"),
+      task: execution.task,
+      target: execution.target,
+      context: execution.context,
+      resumeTaskId: execution.resumeTaskId,
+      parentTaskId: execution.resumeTaskId || void 0,
+      rootTaskId: parentTask ? parentTask.rootTaskId || parentTask.id : execution.resumeTaskId || void 0,
+      workerType: execution.workerType,
+      status: "running",
+      startedAt: now,
+      updatedAt: now
+    };
+    this.activeDelegatedExecution = activeExecution;
+    return activeExecution;
+  }
+  restoreActiveDelegatedExecution(execution) {
+    this.activeDelegatedExecution = execution;
+  }
+  clearActiveDelegatedExecution(executionId) {
+    if (!this.activeDelegatedExecution) {
+      return;
+    }
+    if (executionId && this.activeDelegatedExecution.id !== executionId) {
+      return;
+    }
+    this.activeDelegatedExecution = null;
+  }
+  getActiveDelegatedExecution() {
+    return this.activeDelegatedExecution ? { ...this.activeDelegatedExecution } : null;
+  }
   recordDelegatedTask(task) {
     const now = Date.now();
     const parentTask = task.resumeTaskId ? this.delegatedTasks.find((existing) => existing.id === task.resumeTaskId) : void 0;
@@ -11897,42 +11933,91 @@ After completion: record key loot/findings from the sub-agent output to canonica
         workerType: params["worker_type"],
         resumeTaskId: params["resume_task_id"]
       };
-      const { AgentTool } = await import("./agent-tool-3Y7YKMCZ.js");
-      const executor = new AgentTool(state, events, scopeGuard, approvalGate);
-      const result = await executor.execute(input);
-      state.recordDelegatedTask({
+      const activeExecution = state.startDelegatedExecution({
         task: input.task,
         target: input.target,
         context: input.context,
-        resumeTaskId: input.resumeTaskId,
         workerType: input.workerType,
-        status: result.status,
-        summary: result.summary,
-        tried: result.tried,
-        findings: result.findings,
-        loot: result.loot,
-        sessions: result.sessions,
-        assets: result.assets,
-        suggestedNext: result.suggestedNext,
-        waitingOn: result.waitingOn,
-        resumeHint: result.resumeHint,
-        nextWorkerType: result.nextWorkerType
+        resumeTaskId: input.resumeTaskId
+      });
+      events.emit({
+        type: EVENT_TYPES.DELEGATE,
+        timestamp: Date.now(),
+        data: {
+          fromAgent: "main",
+          toAgent: input.workerType || "general",
+          task: input.task,
+          dangerLevel: "delegated",
+          reason: input.context,
+          executionId: activeExecution.id,
+          workerType: input.workerType,
+          resumeTaskId: input.resumeTaskId,
+          parentTaskId: activeExecution.parentTaskId,
+          rootTaskId: activeExecution.rootTaskId
+        }
       });
-      const lines = [
-        `[Status] ${result.status}`,
-        `[Summary] ${result.summary}`,
-        result.findings.length ? `[Findings] ${result.findings.join(" | ")}` : "",
-        result.loot.length ? `[Loot] ${result.loot.join(" | ")}` : "",
-        result.sessions.length ? `[Sessions] ${result.sessions.join(", ")}` : "",
-        result.assets.length ? `[Assets] ${result.assets.join(" | ")}` : "",
-        result.tried.length ? `[Tried] ${result.tried.join(" | ")}` : "",
-        input.resumeTaskId ? `[ResumedFrom] ${input.resumeTaskId}` : "",
-        result.waitingOn ? `[Waiting] ${result.waitingOn}` : "",
-        result.resumeHint ? `[Resume] ${result.resumeHint}` : "",
-        result.nextWorkerType ? `[NextWorker] ${result.nextWorkerType}` : "",
-        result.suggestedNext ? `[Next] ${result.suggestedNext}` : ""
-      ].filter(Boolean);
-      return { success: true, output: lines.join("\n") };
+      const { AgentTool } = await import("./agent-tool-Y6CG5KRL.js");
+      const executor = new AgentTool(state, events, scopeGuard, approvalGate);
+      try {
+        const result = await executor.execute(input);
+        const record = state.recordDelegatedTask({
+          task: input.task,
+          target: input.target,
+          context: input.context,
+          resumeTaskId: input.resumeTaskId,
+          workerType: input.workerType,
+          status: result.status,
+          summary: result.summary,
+          tried: result.tried,
+          findings: result.findings,
+          loot: result.loot,
+          sessions: result.sessions,
+          assets: result.assets,
+          suggestedNext: result.suggestedNext,
+          waitingOn: result.waitingOn,
+          resumeHint: result.resumeHint,
+          nextWorkerType: result.nextWorkerType
+        });
+        events.emit({
+          type: EVENT_TYPES.DELEGATE_RESULT,
+          timestamp: Date.now(),
+          data: {
+            agent: input.workerType || "general",
+            output: result.summary,
+            findings: result.findings.length,
+            targets: 0,
+            iterations: result.tried.length,
+            isCompleted: result.status !== "waiting" && result.status !== "running",
+            taskId: record.id,
+            parentTaskId: record.parentTaskId,
+            rootTaskId: record.rootTaskId,
+            workerType: record.workerType,
+            status: result.status,
+            summary: result.summary,
+            waitingOn: result.waitingOn,
+            resumeHint: result.resumeHint,
+            nextWorkerType: result.nextWorkerType,
+            executionId: activeExecution.id
+          }
+        });
+        const lines = [
+          `[Status] ${result.status}`,
+          `[Summary] ${result.summary}`,
+          result.findings.length ? `[Findings] ${result.findings.join(" | ")}` : "",
+          result.loot.length ? `[Loot] ${result.loot.join(" | ")}` : "",
+          result.sessions.length ? `[Sessions] ${result.sessions.join(", ")}` : "",
+          result.assets.length ? `[Assets] ${result.assets.join(" | ")}` : "",
+          result.tried.length ? `[Tried] ${result.tried.join(" | ")}` : "",
+          input.resumeTaskId ? `[ResumedFrom] ${input.resumeTaskId}` : "",
+          result.waitingOn ? `[Waiting] ${result.waitingOn}` : "",
+          result.resumeHint ? `[Resume] ${result.resumeHint}` : "",
+          result.nextWorkerType ? `[NextWorker] ${result.nextWorkerType}` : "",
+          result.suggestedNext ? `[Next] ${result.suggestedNext}` : ""
+        ].filter(Boolean);
+        return { success: true, output: lines.join("\n") };
+      } finally {
+        state.clearActiveDelegatedExecution(activeExecution.id);
+      }
     }
   };
 }