![[TCH]Top-RankedIntelligent Pentest Project](/rasida8899/LuaN1aoAgent/raw/main/imgs/tch.png)
🧠 Think Like Human Experts • 📊 Dynamic Graph Planning • 🔄 Learn From Failures • 🎯 Evidence-Driven Decisions
🚀 Quick Start • ✨ Core Innovations • 🏗️ System Architecture • 🗓️ Roadmap
LuaN1ao (鸾鸟) is a next-generation Autonomous Penetration Testing Agent powered by Large Language Models (LLMs).
Traditional automated scanning tools rely on predefined rules and struggle with complex real-world scenarios. LuaN1ao breaks through these limitations by innovatively integrating the P-E-R (Planner-Executor-Reflector) Agent Collaboration Framework with Causal Graph Reasoning technology.
LuaN1ao simulates the thinking patterns of human security experts:
- 🎯 Strategic Planning: Dynamically plan attack paths based on global situational awareness
- 🔍 Evidence-Driven: Build rigorous "Evidence-Hypothesis-Validation" logical chains
- 🔄 Continuous Evolution: Learn from failures and autonomously adjust tactical strategies
- 🧠 Cognitive Loop: Form a complete cognitive cycle of planning-execution-reflection
From information gathering to vulnerability exploitation, LuaN1ao elevates penetration testing from "automated tools" to an "autonomous agent".
💡 More demos coming soon!
LuaN1ao decouples penetration testing thinking into three independent yet collaborative cognitive roles, forming a complete decision-making loop:
-
🧠 Planner
- Strategic Brain: Dynamic planning based on global graph awareness
- Adaptive Capability: Identify dead ends and automatically generate alternative paths
- Graph Operation Driven: Output structured graph editing instructions rather than natural language
- Parallel Scheduling: Automatically identify parallelizable tasks based on topological dependencies
-
⚙️ Executor
- Tactical Execution: Focus on single sub-task tool invocation and result analysis
- Tool Orchestration: Unified scheduling of security tools via MCP (Model Context Protocol)
- Context Compression: Intelligent message history management to avoid token overflow
- Fault Tolerance: Automatic handling of network transient errors and tool invocation failures
-
⚖️ Reflector
- Audit Analysis: Review task execution and validate artifact effectiveness
- Failure Attribution: L1-L4 level failure pattern analysis to prevent repeated errors
- Intelligence Generation: Extract attack intelligence and build knowledge accumulation
- Termination Control: Judge goal achievement or task entrapment
Key Advantages: Role separation avoids the "split personality" problem of single agents. Each component focuses on its core responsibilities and collaborates via event bus.
LuaN1ao rejects blind guessing and LLM hallucinations, constructing explicit causal graphs to drive testing decisions:
graph LR
E[🔍 Evidence<br/>Evidence Node] -->|Support| H[💭 Hypothesis<br/>Hypothesis Node]
H -->|Validation| V[⚠️ Vulnerability<br/>Vulnerability Node]
V -->|Exploitation| X[💥 Exploit<br/>Exploit Node]
Core Principles:
- Evidence First: Any hypothesis requires explicit prior evidence support
- Confidence Quantification: Each causal edge has a confidence score to avoid blind advancement
- Traceability: Complete recording of reasoning chains for failure tracing and experience reuse
- Hallucination Prevention: Mandatory evidence validation, rejecting unfounded attacks
Example Scenario:
Evidence: Port scan discovers 3306/tcp open
↓ (Confidence 0.8)
Hypothesis: Target runs MySQL service
↓ (Validation successful)
Vulnerability: MySQL weak password/unauthorized access
↓ (Attempt exploitation)
Exploit: mysql -h target -u root -p [brute-force/empty password]
Say goodbye to static task lists. LuaN1ao models penetration testing plans as dynamically evolving Directed Acyclic Graphs (DAGs):
Core Features:
- Graph Operation Language: Planner outputs standardized graph editing operations (
ADD_NODE,UPDATE_NODE,DEPRECATE_NODE) - Real-time Adaptation: Task graphs deform in real-time with testing progress
- Discover new ports → Automatically mount service scanning subgraphs
- Encounter WAF → Insert bypass strategy nodes
- Path blocked → Automatically prune or branch planning
- Topological Dependency Management: Automatically identify and parallelize independent tasks based on DAG topology
- State Tracking: Each node contains a state machine (
pending,in_progress,completed,failed,deprecated)
Comparison with Traditional Planning:
| Feature | Traditional Task List | Plan-on-Graph |
|---|---|---|
| Structure | Linear list | Directed graph |
| Dependency Management | Manual sorting | Topological auto-sorting |
| Parallel Capability | None | Auto-identify parallel paths |
| Dynamic Adjustment | Regenerate | Local graph editing |
| Visualization | Difficult | Native support (Web UI) |
Visualization Example: Start the Web Server to view the task graph evolution in real-time in the browser.
LuaN1ao achieves unified integration and scheduling of tools through the Model Context Protocol (MCP):
- HTTP/HTTPS Requests: Support for custom headers, proxies, timeout control
- Shell Command Execution: Securely encapsulated system command invocation (containerized execution recommended)
- Python Code Execution: Dynamic execution of Python scripts for complex logic processing
- Metacognitive Tools:
think(deep thinking),hypothesize(hypothesis generation),reflect(experience summarization) - Task Control:
halt_task(early task termination)
💡 Extensibility: New tools can be easily integrated via
mcp.json(e.g., Metasploit, Nuclei, Burp Suite API)
- Vector Retrieval: Efficient knowledge base retrieval based on FAISS
- Domain Knowledge: Integration of PayloadsAllTheThings and other open-source security knowledge bases
- Dynamic Learning: Continuous addition of custom knowledge documents
The Web UI is now a standalone service powered by a database, enabling persistent task monitoring and management.
- Real-time Monitoring: Browser view of dynamic task graph evolution and live logs.
- Node Details: Click nodes to view execution logs, artifacts, state transitions.
- Task Management: Create, abort, and delete historical tasks.
- Data Persistence: All task data is stored in SQLite (
luan1ao.db), preserving history across restarts.
LuaN1ao Agent supports a Human-in-the-Loop (HITL) mode, allowing experts to supervise and intervene in the decision-making process.
- Enable: Set
HUMAN_IN_THE_LOOP=truein.env. - Approval: The agent pauses after generating a plan (initial or dynamic), waiting for human approval via Web UI or CLI.
- Modification: Experts can reject or directly modify the plan (JSON editing) before execution.
- Injection: Supports real-time injection of new sub-tasks via the Web UI ("Active Intervention").
Interaction Methods:
- Web UI: Approval modal pops up automatically. Use "Modify" to edit plans or "Add Task" button to inject tasks.
- CLI: Prompts with
HITL >. Typeyto approve,nto reject, ormto modify (opens system editor).
-
Experience Self-Evolution
- Cross-task long-term memory
- Automatic extraction of successful attack patterns into vector library
- Intelligent recommendations based on historical experience
-
Human-in-the-Loop Mode
- Pre-high-risk operation confirmation mechanism
- Runtime task graph editing interface (Graph Injection)
- Expert intervention and strategy injection
-
Tool Ecosystem Expansion
- Integration of Metasploit RPC interface
- Support for Nuclei, Xray, AWVS scanners
- Docker sandboxed tool execution environment
-
Multimodal Capabilities
- Image recognition (CAPTCHA, screenshot analysis)
- Traffic analysis (PCAP file parsing)
- Collaborative Agent Network: Multi-agent distributed collaboration
- Reinforcement Learning Integration: Autonomous optimization of attack strategies through environmental interaction, achieving self-evolution and strategy convergence of agents in complex scenarios
- Compliance Report Generation: Automatic generation of compliant penetration testing reports
| Component | Requirements | Notes |
|---|---|---|
| Operating System | Linux (recommended) / macOS / Windows (WSL2) | Recommended to run in isolated environments |
| Python | 3.10+ | Requires support for asyncio and type hints |
| LLM API | OpenAI compatible format | Supports GPT-4o, DeepSeek, Claude-3.5, etc. |
| Memory | Minimum 4GB, recommended 8GB+ | RAG services and LLM inference require memory |
| Network | Internet connection | Access to LLM APIs and knowledge base updates |
⚠️ Security Notice: LuaN1ao includes high-privilege tools likeshell_execandpython_exec. Strongly recommend running in Docker containers or virtual machines to avoid potential risks to the host system.
# Clone repository
git clone https://github.com/SanMuzZzZz/LuaN1aoAgent.git
cd LuaN1aoAgent
# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate # Linux/macOS
# Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt💡 For complete installation and troubleshooting guide, please refer to QUICKSTART.md
# Copy configuration template
cp .env.example .env
# Edit .env file
nano .env # or use your preferred editorCore Configuration Items:
# LLM API Configuration (required)
LLM_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
LLM_API_BASE_URL=https://api.openai.com/v1
# Recommended to use powerful models for better results
LLM_DEFAULT_MODEL=gpt-4o
LLM_PLANNER_MODEL=gpt-4o # Planner requires strong reasoning capability
LLM_EXECUTOR_MODEL=gpt-4o
LLM_REFLECTOR_MODEL=gpt-4o
OUTPUT_MODE=default # simple/default/debugLuaN1ao relies on the RAG (Retrieval-Augmented Generation) system to obtain the latest security knowledge. The knowledge base needs to be initialized before the first run:
# 1. Clone PayloadsAllTheThings knowledge base
mkdir -p knowledge_base
git clone https://github.com/swisskyrepo/PayloadsAllTheThings \
knowledge_base/PayloadsAllTheThings
# 2. Build vector index (takes a few minutes)
python -m rag.rag_kdprepareKnowledge Base Description: PayloadsAllTheThings contains rich attack payloads, bypass techniques, and vulnerability exploitation methods, making it a valuable resource for penetration testing.
The system now runs as two separate processes: the Web Server (dashboard) and the Agent (worker). They communicate via a local SQLite database (luan1ao.db).
Start the persistent web interface first. This process should remain running.
python -m web.serverOpen your browser and visit: http://localhost:8088
Open a new terminal window and run the agent. The agent will execute the task, write logs to the database, and exit when finished. The Web UI will update in real-time.
# Basic usage
python agent.py \
--goal "Perform comprehensive web security testing on http://testphp.vulnweb.com" \
--task-name "demo_test"
# Enable --web flag to print the task URL
python agent.py \
--goal "Scan localhost" \
--task-name "local_scan" \
--web- Real-time: Use the Web UI (http://localhost:8088) to monitor progress.
- Archives: Task history is persisted in the database. Logs and metrics are also saved in
logs/TASK-NAME/TIMESTAMP/:
logs/demo_test/20250204_120000/
├── run_log.json # Complete execution log (includes all P-E-R interactions)
├── metrics.json # Performance metrics and statistics
└── console_output.log # Formatted console output
┌─────────────────────────────────────────────────────────┐
│ User Goal │
│ "Perform comprehensive penetration testing" │
└────────────────────────┬────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ P-E-R Cognitive Layer │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Planner │ ───> │ Executor │ ───> │Reflector │ │
│ │ │ │ │ │ │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │
│ └──────────────────┴──────────────────┘ │
│ ▲ │
│ │ LLM API Calls │
└─────────────────────────┼────────────────────────────────┘
│
┌─────────────────────────┴────────────────────────────────┐
│ Core Engine │
│ ┌────────────────────────────────────────────────┐ │
│ │ GraphManager │ │
│ │ • Task Graph Management (DAG) │ │
│ │ • State Tracking and Updates │ │
│ │ • Topological Sorting and Dependency Resolution│ │
│ │ • Parallel Task Scheduling │ │
│ └────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────┐ │
│ │ Database Layer (SQLite) │ │
│ │ • Persistence for Tasks, Graphs, Logs │ │
│ │ • Decoupled State Management │ │
│ └────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────┐ │
│ │ EventBroker (Global) │ │
│ │ • Inter-component Communication │ │
│ │ • Event Publishing/Subscription │ │
│ └────────────────────────────────────────────────┘ │
└─────────────────────────┬────────────────────────────────┘
│
┌─────────────────────────┴────────────────────────────────┐
│ Capability Layer │
│ ┌────────────────────┐ ┌──────────────────────────┐ │
│ │ RAG Knowledge │ │ MCP Tool Server │ │
│ │ Service │ │ │ │
│ │ • FAISS Vector Retrieval│ • http_request │ │
│ │ • Knowledge Document Parsing│ • shell_exec │ │
│ │ • Similarity Search │ • python_exec │ │
│ │ │ • think/hypothesize │ │
│ └────────────────────┘ │ • halt_task │ │
│ └──────────────────────────┘ │
└──────────────────────────────────────────────────────────┘
sequenceDiagram
participant U as User
participant P as Planner
participant G as GraphManager
participant E as Executor
participant R as Reflector
participant DB as SQLite DB
participant W as Web UI
U->>P: Input Goal
P->>G: Initialize Task Graph
G->>DB: Persist Initial State
W->>DB: Poll for Updates (SSE)
loop P-E-R Cycle
P->>G: Analyze graph, generate graph edit operations
G->>G: Update graph structure
G->>DB: Sync Updates
G->>E: Assign pending sub-tasks
E->>E: Execute Tools
E->>DB: Log Events
E->>R: Request reflection
R->>R: Analyze success/failure
R->>G: Update node status
G->>DB: Sync Updates
end
LuaN1aoAgent/
├── agent.py # Main entry point, P-E-R cycle control
├── requirements.txt # Project dependencies
├── pyproject.toml # Project configuration and code quality tool settings
├── mcp.json # MCP tool service configuration
├── .env # Environment variables configuration (manual creation required)
│
├── conf/ # Configuration module
│ ├── config.py # Core configuration items (LLM, scenarios, parameters)
│ └── __init__.py
│
├── core/ # Core engine
│ ├── planner.py # Planner implementation
│ ├── executor.py # Executor implementation
│ ├── reflector.py # Reflector implementation
│ ├── graph_manager.py # Graph manager
│ ├── events.py # Event bus
│ ├── console.py # Console output management
│ ├── data_contracts.py # Data contract definitions
│ ├── tool_manager.py # Tool manager
│ ├── intervention.py # Human-in-the-Loop manager
│ ├── database/ # Database persistence layer
│ │ ├── models.py # SQLAlchemy models
│ │ └── utils.py # DB utilities
│ └── prompts/ # Prompt template system
│
├── llm/ # LLM abstraction layer
│ ├── llm_client.py # LLM client (unified interface)
│ └── __init__.py
│
├── rag/ # RAG knowledge enhancement
│ ├── knowledge_service.py # FastAPI knowledge service
│ ├── rag_client.py # RAG client
│ ├── rag_kdprepare.py # Knowledge base index construction
│ ├── markdown_chunker.py # Document chunking
│ └── model_manager.py # Embedding model management
│
├── tools/ # Tool integration layer
│ ├── mcp_service.py # MCP service implementation
│ ├── mcp_client.py # MCP client
│ └── __init__.py
│
├── web/ # Web UI
│ ├── server.py # Web dashboard server
│ ├── static/ # Frontend assets
│ └── templates/ # HTML templates
│
├── knowledge_base/ # Knowledge base directory (manual creation required)
│ └── PayloadsAllTheThings/ # Security knowledge base (clone required)
│
└── logs/ # Runtime logs and metrics
└── TASK-NAME/
└── TIMESTAMP/
├── run_log.json
├── metrics.json
└── console_output.log
By using LuaN1ao, you acknowledge and agree to the following terms:
- Explicit Authorization Required: You MUST obtain explicit written authorization from system owners before testing any systems, networks, or applications.
- Scope Limitation: Testing activities must be strictly limited to the authorized scope and must not exceed authorized boundaries.
- Educational & Research Use: This tool is suitable for cybersecurity education, academic research, and authorized security assessments.
- Comply with Laws: You are solely responsible for ensuring that your use of this tool complies with all applicable local, national, and international laws and regulations.
- Legal Consequences: Unauthorized penetration testing is ILLEGAL and may result in criminal prosecution, civil lawsuits, and substantial fines.
- Personal Liability: Users assume full responsibility for all legal consequences arising from improper use of this tool.
- Responsible Disclosure: Discovered security vulnerabilities should follow Responsible Disclosure principles.
- Professional Standards: Use of this tool must comply with professional security research standards and industry best practices.
- Confidentiality Obligations: Respect the privacy and confidentiality of any vulnerabilities discovered during testing; do not disclose or exploit them without authorization.
This software MUST NOT be used for:
- ❌ Unauthorized access to computer systems, networks, or data
- ❌ Malicious attacks, destruction, or service disruption
- ❌ Theft, tampering, or destruction of data
- ❌ Any illegal or criminal activities
- ❌ Privacy violations or breach of confidentiality agreements
- ❌ Corporate espionage or unfair competition
- High-Privilege Tools: LuaN1ao includes high-privilege tools such as
shell_execandpython_execwith the capability to execute arbitrary system commands and code. - Potential Destructiveness: Improper use may cause irreversible damage to target systems, including but not limited to:
- System crashes or service interruptions
- Data loss or corruption
- Configuration file modifications
- Security mechanism compromise
- Mandatory Isolation: Strongly recommended to run in the following isolated environments:
- Docker containers (recommended)
- Dedicated virtual machines (VMware, VirtualBox, KVM, etc.)
- Completely isolated sandbox environments
- Network Isolation: Test environments should be physically or logically isolated from production networks.
- Data Isolation: Do not run on systems containing real user data or sensitive information.
- No Production Use: Never run LuaN1ao on production environments, critical business systems, or systems containing sensitive data.
- Test Environments Only: Use only in dedicated test, development, or sandbox environments.
- Provided "AS IS": This software is provided "AS IS" without warranty of any kind, express or implied.
- No Fitness Warranty: No warranty of merchantability, fitness for a particular purpose, or non-infringement.
- No Results Guarantee: No guarantee that the software will discover all vulnerabilities or achieve expected results.
THE AUTHORS AND CONTRIBUTORS EXPRESSLY DISCLAIM ALL LIABILITY FOR MISUSE OF THIS SOFTWARE.
Under no circumstances shall developers, contributors, or copyright holders be liable for:
- ✗ Any direct, indirect, incidental, special, punitive, or consequential damages arising from use or inability to use this software
- ✗ Unauthorized system access or data breaches
- ✗ System damage, data loss, or business interruption
- ✗ Legal proceedings, fines, or other legal consequences
- ✗ Loss of goodwill, profits, or other economic losses
- ✗ Even if advised of the possibility of such damages
- Independent Judgment: Users have complete autonomy and judgment in the decision to use this tool.
- Assumption of Risk: All risks of using this software are assumed by the user.
- Full Responsibility: Users assume full responsibility for all actions using this tool and their consequences.
By downloading, installing, configuring, or using LuaN1ao, you expressly represent that:
- ✅ You have completely read and fully understand all terms of this disclaimer
- ✅ You agree to be bound by this disclaimer
- ✅ You commit to use this tool only within authorized scope
- ✅ You understand and accept all risks of using this tool
- ✅ You acknowledge that developers are not liable for any of your usage actions
If you do not agree to any of the above terms, immediately cease using this software and delete all related files.
We welcome all forms of contributions! Whether reporting bugs, suggesting new features, improving documentation, or submitting code.
- Report Issues: Submit bug reports or feature requests on the Issues page
- Submit Code: Fork the repository, create a branch, and submit a Pull Request
- Improve Documentation: Correct errors, supplement explanations, add examples
- Share Experience: Share usage experiences and best practices in Discussions
For detailed contribution processes and code standards, please refer to CONTRIBUTING.md.
This project is licensed under the Apache License 2.0.
Copyright 2025 LuaN1ao (鸾鸟) Project Contributors
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
- GitHub Issues: Submit Issues
- GitHub Discussions: Join Discussions
- Email: 1614858685x@gmail.com
- WeChat: SanMuzZzZzZz
If LuaN1ao has been helpful to you, please give us a Star ⭐!