Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/SanMuzZzZz/LuaN1aoAgent/llms.txt

Use this file to discover all available pages before exploring further.

The agent communicates with tools through two channels: most tools are MCP tools served by tools/mcp_service.py, while a small set of local tools are handled directly inside core/executor.py without any MCP round-trip. Every tool returns a JSON string. The executor calls these tools during the Execution phase of the P-E-R loop.
Local tools bypass the MCP transport layer and are resolved in-process by the executor. Currently only query_causal_graph is a local tool. All other tools listed here are MCP tools served by tools/mcp_service.py.
shell_exec and python_exec execute arbitrary code on the host system with no sandbox isolation. Always run the agent inside an isolated, controlled environment.

​
Metacognitive tools

These tools do not perform external actions. They force the executor into structured thinking steps, improving reasoning quality and traceability.

​
think

Records a structured reasoning trace. Use this to analyze a situation before choosing an action, or to surface a knowledge gap when stuck.
​
analysis
string
required
A brief analysis of the current situation or context.
​
problem
string
required
The specific problem to solve or decision to make.
​
reasoning_steps
string[]
required
Ordered list of reasoning steps leading to the conclusion.
​
conclusion
string
required
The final conclusion or next action derived from the reasoning.
Return value 
{
  "result": "ok",
  "message": "结构化思考过程已记录。",
  "recorded_thought": {
    "type": "structured_thought",
    "timestamp": "2024-01-01T00:00:00Z",
    "analysis": "...",
    "problem": "...",
    "reasoning_steps": ["..."],
    "conclusion": "..."
  }
}
The last 50 think entries are retained in memory during a session. This history is not currently injected back into the executor prompt — the primary value is forcing structured deliberation before acting.

​
formulate_hypotheses

Systematically proposes attack hypotheses when the executor is stuck. Use this before trying a new approach to ensure the decision is explicit and traceable.
​
hypotheses
object[]
required
List of hypothesis objects. Each object must contain:
Return value 
{
  "success": true,
  "status": "Hypotheses recorded. Now, select your highest-confidence hypothesis and design an action to test it.",
  "hypotheses_record": {
    "type": "hypothesis_formulation",
    "timestamp": "2024-01-01T00:00:00Z",
    "hypotheses": [
      { "description": "The login form is vulnerable to time-based SQLi", "confidence": 0.75 }
    ]
  }
}

​
reflect_on_failure

Performs structured root-cause analysis after a tool call fails. The prompt instructs the executor to produce a corrected action immediately after calling this tool.
​
failed_action
object
required
The full action object that failed, including tool and params keys.
​
error_message
string
required
The exact error message returned by the failed tool.
Return value 
{
  "success": true,
  "status": "Reflection recorded. Now, you must analyze the failure in your 'thought' process and propose a corrected action.",
  "reflection_record": {
    "type": "failure_reflection",
    "timestamp": "2024-01-01T00:00:00Z",
    "failed_action": { "tool": "http_request", "params": {} },
    "error_message": "Connection Error"
  }
}

​
expert_analysis

Async. Escalates a hard problem to a dedicated LLM call configured with a world-class security researcher system prompt. Use after at least two failed retrieve_knowledge attempts, or for problems involving unknown algorithms, complex regex bypasses, or black-box protocol reversal.
​
question
string
required
A clear, specific question for the expert. Pseudocode is accepted.
​
context_data
string
default:""
Supporting data: code snippets, token strings, error messages, request/response samples, failed retrieval keywords.
Return value 
{
  "success": true,
  "provider": "openai",
  "model": "gpt-4o",
  "report": "<detailed expert analysis>",
  "metrics": {
    "prompt_tokens": 1024,
    "completion_tokens": 512,
    "total_tokens": 1536,
    "cost_cny": 0.02
  }
}
Error return (connection failure) 
{
  "success": false,
  "error_type": "CONNECTION",
  "error": "Unable to connect to LLM service: ...",
  "fix_suggestion": "Check network connection and LLM service status"
}
Attach all relevant evidence in context_data — failed retrieval queries, raw HTTP responses, source code fragments — so the expert can reach a precise diagnosis without back-and-forth.

​
Execution and control tools

​
complete_mission

Signals that the top-level task goal has been fully achieved. Calling this tool writes a halt file to /tmp/{task_id}.halt, which the agent’s monitor loop detects to terminate all running subtasks immediately.
Call this tool only when you are 100% certain the top-level goal is met. This terminates the entire task and all parallel subtasks.
​
reason
string
required
Detailed explanation of why the mission is complete.
​
evidence
string
required
Key evidence: shell output, database contents, captured flag, API response, etc.
​
task_id
string
required
The current task’s unique ID (available in the executor’s context).
Return value 
{
  "success": true,
  "message": "任务完成信号已发送。终止文件中已记录理由和证据。"
}
Usage scenarios
  • Obtained shell access on the target system
  • Extracted sensitive data from a target database
  • Captured a CTF flag
  • Successfully demonstrated the existence of a critical vulnerability

​
query_causal_graph (local tool)

Queries the in-process causal graph directly without MCP transport. This zero-latency local tool lets the executor look up already-established evidence, confirmed vulnerabilities, and hypothesis state without making a network call.
This is a local tool — it does not appear in mcp.json and does not go through the MCP service. It is handled directly by core/executor.py via _handle_local_tool.
​
node_type
string
Filter results by node type. Common values: Evidence, Hypothesis, ConfirmedVulnerability, Exploit. If omitted, all node types are returned.
​
query
string
Substring search applied to the combined title, description, vulnerability, and hypothesis fields of each node. Case-insensitive. If omitted, all nodes matching the node_type filter are returned.
​
limit
number
default:"10"
Maximum number of nodes to return.
Return value 
{
  "success": true,
  "count": 2,
  "results": [
    {
      "id": "vuln_mysql_weak_pw",
      "node_type": "ConfirmedVulnerability",
      "title": "MySQL weak password",
      "description": "Port 3306 open; root login with empty password succeeded",
      "confidence": 0.95,
      "status": "confirmed",
      "evidence": "mysql -h 10.0.0.1 -u root returned shell access",
      "vulnerability": "Unauthorized MySQL root access"
    }
  ],
  "note": "查询参数: node_type='ConfirmedVulnerability', query='mysql', limit=10"
}

​
Network and HTTP tools

​
http_request

Async. The preferred method for all HTTP interactions. Backed by a persistent httpx.AsyncClient session that automatically manages cookies across requests.
Use http_request for single, exploratory requests. For repetitive testing (fuzzing, blind injection, brute force), use python_exec with a requests.Session instead.
​
url
string
required
The target URL.
​
method
string
default:"GET"
HTTP method: GET, POST, PUT, DELETE, PATCH, etc.
​
headers
object
default:"{}"
Request headers as key-value pairs. To send Cookie, Authorization, or X-Requested-With, you must specify them here explicitly.
​
data
string | object
Request body. Accepts a URL-encoded string or a dict of form fields.Content-Type resolution:
  • If headers contains Content-Type, it takes priority.
  • If data is a dict and Content-Type is application/json, the dict is serialized as JSON.
  • Otherwise defaults to application/x-www-form-urlencoded.
​
timeout
number
default:"10"
Request timeout in seconds. Default tool timeout is 60 s (overridden by TOOL_TIMEOUT_HTTP).
​
allow_redirects
boolean
default:"true"
Whether to follow HTTP redirects automatically. Accepts boolean or equivalent strings ("true", "false", "1", "0").
​
raw_mode
boolean
default:"false"
When true (POST/PUT/PATCH only), disables URL/form encoding and sends the body exactly as provided. Use this when payloads contain characters that must not be percent-encoded (e.g., XSS angle brackets).
Return value 
{
  "request": {
    "url": "https://example.com/login",
    "method": "POST",
    "headers": { "Content-Type": "application/x-www-form-urlencoded" },
    "data": "user=admin&pass=test",
    "raw_mode": false,
    "prepared_body_preview": "user=admin&pass=test",
    "encoding_mode": "form_urlencoded"
  },
  "response": {
    "status_code": 200,
    "reason": "OK",
    "headers": { "Set-Cookie": "session=abc123" },
    "content": "<html>...</html>",
    "content_length": 1024,
    "encoding": "utf-8",
    "url": "https://example.com/dashboard",
    "response_time_ms": 142.5
  },
  "metadata": {
    "redirects": 1,
    "final_url": "https://example.com/dashboard",
    "elapsed_seconds": 0.143,
    "cookies": { "session": "abc123" },
    "follow_redirects": true,
    "redirect_chain": [
      { "status_code": 302, "reason": "Found", "url": "https://example.com/login", "headers": {} }
    ]
  }
}

​
concurrency_test

Async. Sends multiple requests simultaneously using asyncio.gather to test for race conditions, TOCTOU vulnerabilities, and atomic lock failures.
​
url
string
required
Target URL.
​
method
string
default:"GET"
HTTP method.
​
data
string
default:"{}"
Request body as a JSON string. Parsed to a dict if valid JSON.
​
headers
string
default:"{}"
Request headers as a JSON string.
​
concurrent_count
number
default:"10"
Number of simultaneous requests. Maximum is 50 to prevent accidental DoS.
Return value 
{
  "success": true,
  "total_requests": 10,
  "successful_responses": 9,
  "errors": 1,
  "status_distribution": { "200": 8, "500": 1 },
  "length_distribution": { "512": 8 },
  "detailed_results_sample": [
    { "index": 0, "status": 200, "length": 512 }
  ]
}

​
Shell and scripting tools

​
shell_exec

Async. Executes a shell command in a subprocess, streaming stdout+stderr in real time. Do not use this tool to call tools that are already exposed as MCP tools (e.g., dirsearch).
​
command
string
required
The shell command to execute (e.g., "ls -al /var/www").
Return value (success) 
{ "success": true, "output": "total 48\ndrwxr-xr-x ...", "error": "" }
Return value (failure) 
{
  "success": false,
  "output": "bash: nmap: command not found",
  "error_type": "MISSING_TOOL",
  "message": "Command 'nmap ...' returned non-zero exit status 127.",
  "fix_suggestion": "The command or tool does not exist. Choose an alternative from the available tools."
}
error_type values
ValueMeaning
RUNTIMENon-zero exit for a general reason
MISSING_TOOLCommand or binary not found
SYNTAXInvalid argument syntax detected

​
python_exec

Async. Executes a Python script in a thread pool executor. The script runs with a pre-populated session (requests.Session) that inherits cookies from the shared httpx session. Cookie changes made inside the script are synced back to the global session after execution.
Do not use python_exec to make HTTP requests directly with requests.get/post. For HTTP calls, use http_request. Use python_exec only for computation, data transformation, or systematic testing loops that need requests.Session.
​
script
string
required
A self-contained Python script. Use print() to produce output. The execution environment pre-injects requests, session (a requests.Session with inherited cookies), and json.
Return value (success) 
{ "success": true, "output": "admin:password123\n", "error": "" }
Return value (failure) 
{
  "success": false,
  "output": "",
  "error_type": "SYNTAX",
  "message": "Python Syntax Error: invalid syntax (<string>, line 3)",
  "fix_suggestion": "Review the Python code for syntax errors."
}
error_type values
ValueMeaning
SYNTAXPython SyntaxError
IMPORTMissing module
RUNTIMEException raised during execution
A concurrency lock serializes python_exec calls to prevent sys.stdout patching conflicts. Parallel subtasks calling python_exec at the same time will queue.

​
Knowledge tools

​
retrieve_knowledge

Async. Performs semantic search over the local knowledge base (attack techniques, WAF bypass methods, vulnerability exploitation guides, tool usage references). Queries are sent to the knowledge service HTTP API.
​
query
string
required
Search query using specific technical terms (e.g., "LFI path traversal", "SQL injection WAF bypass").
​
top_k
number
default:"5"
Number of top results to return. Range: 1–10.
​
service_url
string
Knowledge service URL. Defaults to KNOWLEDGE_SERVICE_URL from config (typically http://127.0.0.1:8081).
Return value 
{
  "success": true,
  "query": "SQL injection WAF bypass",
  "total_results": 3,
  "results": [
    {
      "id": "doc_abc123",
      "snippet": "Use space2comment tamper script to bypass keyword filters...",
      "score": 0.92
    }
  ]
}
Use precise technical vocabulary. "LFI path traversal" retrieves far more relevant results than "file vulnerability".

​
distill_knowledge

Async. Writes a newly discovered insight into the permanent skill library (AgentSkills). Call this immediately after successfully overcoming a challenge, not just at the end of a task.
​
insight_summary
string
required
Detailed summary of the insight. Should include: problem background, obstacles encountered, specific bypass/exploitation method (including payloads), and analysis of why the approach succeeded.
Return value 
{
  "success": true,
  "message": "知识已成功送入蒸馏器，相应的技能文档已更新或创建。"
}
Async. Searches DuckDuckGo for vulnerability details, CVE disclosures, exploit techniques, or general documentation. Falls back to direct HTML scraping if the duckduckgo-search package is not installed.
​
query
string
required
Search query (e.g., "CVE-2023-1234 exploit github", "SQL injection WAF bypass techniques").
​
num_results
number
default:"5"
Number of results to return. Maximum recommended: 10.
Return value 
{
  "success": true,
  "query": "CVE-2023-3452 exploit",
  "results": [
    {
      "title": "CVE-2023-3452 - Canto RFI",
      "body": "The Canto plugin for WordPress is vulnerable to Remote File Inclusion...",
      "href": "https://www.exploit-db.com/exploits/51826"
    }
  ]
}

​
Security scanner tools

​
sqlmap_tool

Async. Runs sqlmap to detect and exploit SQL injection vulnerabilities. Always uses --batch --random-agent flags for non-interactive execution.
​
url
string
Target URL with injectable parameter (e.g., "http://target.com/page.php?id=1"). Either url or raw_request_file is required.
​
raw_request_file
string
Path to a file containing a raw HTTP request (alternative to url). Useful when the injection point is in a POST body or a custom header.
​
tamper
string
Comma-separated tamper script names (e.g., "space2comment,randomcase"). Used to bypass WAF/IDS filters.
​
level
number
default:"1"
Test thoroughness level (1–5). Higher values test more injection points and payloads.
​
risk
number
default:"1"
Risk of tests (1–3). Higher values include potentially destructive payloads.
​
dbms
string
Force the backend DBMS (e.g., "mysql", "postgresql"). Skips DBMS detection.
​
extra_args
string
Additional sqlmap CLI arguments passed through shlex.split (e.g., "--dump -T users").
Return value 
{
  "success": true,
  "command": "sqlmap -u http://target.com/page.php?id=1 --batch --random-agent --level 2",
  "stdout": "[INFO] testing connection to the target URL...\n[INFO] GET parameter 'id' is vulnerable!",
  "stderr": "",
  "returncode": 0
}
Timeout: 600 seconds (configurable via TOOL_TIMEOUT_SQLMAP).

​
dirsearch_scan

Async. Runs dirsearch to enumerate web directories and files. Incompatible arguments across dirsearch versions are automatically filtered and replaced.
​
url
string
required
Target URL (e.g., "http://target.com:8080").
​
extensions
string
default:"php,html,js,txt"
Comma-separated list of file extensions to scan for.
​
extra_args
string
default:""
Additional dirsearch CLI arguments. Note: --recursive-level and --recursion-level are automatically replaced with -r for version compatibility.
Return value 
{ "success": true, "output": "[200] /admin/login.php\n[403] /backup/\n", "error": "" }
Timeout: 300 seconds (configurable via TOOL_TIMEOUT_DIRSEARCH).

​
Exploit intelligence tools

​
search_exploit

Async. Queries NVD (National Vulnerability Database) and Exploit-DB for known vulnerabilities and public exploit code. Use this when you identify a software component and its version number.
​
keywords
string
required
Search terms (e.g., "canto wordpress 3.0.4", "apache 2.4.49").
​
cve_id
string
Optional direct CVE lookup (e.g., "CVE-2023-3452").
​
max_results
number
default:"10"
Maximum number of results to return.
Return value 
{
  "status": "success",
  "query": "canto wordpress 3.0.4",
  "sources_checked": ["NVD", "Exploit-DB"],
  "vulnerabilities": [
    {
      "cve_id": "CVE-2023-3452",
      "description": "The Canto plugin is vulnerable to Remote File Inclusion...",
      "severity": "CRITICAL",
      "cvss_score": 9.8,
      "affected_versions": ["<= 3.0.4"],
      "references": ["https://www.exploit-db.com/exploits/51826"],
      "exploit_available": true,
      "edb_id": "51826"
    }
  ],
  "total_found": 1
}

​
view_exploit

Async. Reads the full source of an Exploit-DB exploit using searchsploit. Use after search_exploit returns an edb_id.
​
edb_id
string
Exploit-DB ID (e.g., "51826"). Either edb_id or path is required.
​
path
string
Direct local filesystem path to an exploit file.
​
max_lines
number
default:"200"
Maximum lines of exploit code to return.
Return value 
{
  "status": "success",
  "edb_id": "51826",
  "title": "WordPress Plugin Canto 3.0.4 - Remote File Inclusion (RFI)",
  "path": "/usr/share/exploitdb/exploits/php/webapps/51826.py",
  "content": "#!/usr/bin/env python3\n...",
  "total_lines": 87,
  "file_type": "py",
  "key_info": {
    "vulnerable_endpoints": ["/wp-content/plugins/canto/includes/lib/download.php"],
    "http_method": "GET",
    "cve": "CVE-2023-3452"
  }
}

​
Payload server tools

These tools manage a lightweight HTTP server for OOB (out-of-band) callbacks in RFI, XXE, and SSRF scenarios.

​
start_payload_server

Async. Starts a background HTTP server on a randomly chosen port in the range 18000–18999 (or a specified port). All incoming requests are logged.
​
routes
object[]
required
Route configuration list. Each entry:
​
port
number
Specific port to listen on. If omitted, a free port in 18000–18999 is selected automatically.
Return value 
{
  "status": "started",
  "server_id": "ps_a3f9c1b2",
  "port": 18234,
  "server_url": "http://10.0.0.5:18234",
  "routes_configured": ["/wp-admin/admin.php"],
  "message": "Payload server started. Use 10.0.0.5:18234 as your callback address."
}

​
stop_payload_server

Async. Stops a running payload server.
​
server_id
string
required
The server_id returned by start_payload_server.

​
get_payload_server_logs

Async. Retrieves all requests received by a payload server. Use this to confirm OOB callbacks (SSRF/XXE).
​
server_id
string
required
The server_id returned by start_payload_server.
Return value 
{
  "status": "success",
  "server_id": "ps_a3f9c1b2",
  "request_count": 1,
  "requests": [
    {
      "timestamp": "2024-01-01T12:00:01.000000",
      "client": "192.168.1.10",
      "request": "GET /wp-admin/admin.php",
      "headers": { "Host": "10.0.0.5:18234" }
    }
  ]
}

​
list_payload_servers

Async. Lists all currently active payload servers.

​
Nuclei scanner tools

​
nuclei_scan

Async. Runs Nuclei template-based vulnerability scanning against a target.
A full scan without template filters can take 2–3 minutes. Always specify templates, tags, or severity to limit scan scope.
​
target
string
required
Target URL (e.g., "http://localhost:8080").
​
templates
string
Template path or name (e.g., "cves/2023/CVE-2023-3452.yaml" or "wordpress").
​
severity
string
Comma-separated severity filter: critical, high, medium, low, info.
​
tags
string
Comma-separated tag filter (e.g., "cve,wordpress,rce").
​
timeout
number
default:"180"
Total scan timeout in seconds.
​
rate_limit
number
default:"150"
Maximum requests per second.
​
concurrency
number
default:"25"
Number of concurrent template executions.
Return value 
{
  "status": "success",
  "target": "http://localhost:8080",
  "findings": [
    {
      "template_id": "CVE-2023-3452",
      "name": "Canto Plugin RFI",
      "severity": "critical",
      "type": "http",
      "matched_at": "http://localhost:8080/wp-content/plugins/canto/...",
      "description": "Remote File Inclusion in Canto plugin <= 3.0.4",
      "cve_id": ["CVE-2023-3452"],
      "reference": ["https://www.exploit-db.com/exploits/51826"],
      "extracted": [],
      "curl_command": "curl -X GET ..."
    }
  ],
  "summary": {
    "total_findings": 1,
    "by_severity": { "critical": 1 }
  }
}

​
nuclei_list_templates

Async. Lists available Nuclei templates, with optional filtering by search terms, tags, and severity.
​
search
string
Keyword filter (e.g., "wordpress canto", "CVE-2023").
​
tags
string
Tag filter.
​
severity
string
Severity filter.
​
limit
number
default:"20"
Maximum number of templates to return.

​
Tool timeouts

Default tool-level timeouts are configured in conf/config.py and can be overridden with environment variables.
ToolDefault timeoutEnvironment variable
sqlmap_tool600 sTOOL_TIMEOUT_SQLMAP
nuclei_scan300 sTOOL_TIMEOUT_NUCLEI
dirsearch_scan300 sTOOL_TIMEOUT_DIRSEARCH
python_exec300 sTOOL_TIMEOUT_PYTHON
concurrency_test180 sTOOL_TIMEOUT_CONCURRENCY
shell_exec120 sTOOL_TIMEOUT_SHELL
http_request60 sTOOL_TIMEOUT_HTTP
expert_analysis60 sTOOL_TIMEOUT_EXPERT
web_search30 sTOOL_TIMEOUT_WEB_SEARCH
think / formulate_hypotheses / reflect_on_failure30 sTOOL_TIMEOUT_THINK etc.
retrieve_knowledge15 sTOOL_TIMEOUT_RETRIEVE