Summary

LuaN1ao (鸾鸟) is an advanced, autonomous penetration testing agent designed to emulate human security expert cognitive processes. It addresses the limitations of traditional rule-based tools by integrating a P-E-R (Planner-Executor-Reflector) Agent Collaboration Framework with Causal Graph Reasoning. This enables dynamic, evidence-driven attack path planning and adaptation, offering a significant leap towards truly autonomous cybersecurity assessments for security professionals and researchers.

How It Works

The core of LuaN1ao is the P-E-R framework, which separates penetration testing intelligence into distinct Planner, Executor, and Reflector roles, fostering a robust decision-making loop. This is augmented by Causal Graph Reasoning, which constructs explicit, traceable, and confidence-quantified decision chains based on evidence, preventing LLM hallucinations. Task planning is managed dynamically via a Directed Acyclic Graph (DAG) structure using the Plan-on-Graph (PoG) approach, allowing for real-time adaptation to discovered information and obstacles.

Quick Start & Requirements

• Installation: Clone the repository, create a Python virtual environment, and install dependencies using pip install -r requirements.txt.
• Prerequisites: Python 3.10+, an OpenAI-compatible LLM API key and endpoint (supports GPT-4o, DeepSeek, Claude-3.5, etc.), minimum 4GB RAM (8GB+ recommended), and an internet connection.
• Setup: Requires cloning the PayloadsAllTheThings knowledge base into knowledge_base/ and running python -m rag_kdprepare in the rag/ directory to build the vector index.
• Running: Start the Web Server (python -m web.server) and then run an agent task from a new terminal (python agent.py --goal "..." --task-name "...").
• Links: GitHub Repository, CONTRIBUTING.md, 中文版 README.

Highlighted Details

• P-E-R Agent Collaboration Framework: Decouples cognitive roles for specialized planning, execution, and auditing.
• Causal Graph Reasoning: Ensures evidence-first, traceable, and hallucination-free decision-making.
• Plan-on-Graph (PoG): Dynamic DAG-based task planning with real-time adaptation and parallel task scheduling.
• Model Context Protocol (MCP): Unified integration and scheduling of diverse tools (HTTP, shell, Python, meta-cognitive LLM tools).
• RAG Knowledge Enhancement: Leverages vector retrieval for efficient access to security knowledge bases like PayloadsAllTheThings.
• Web Visualization: Provides real-time monitoring of task graph evolution and logs.
• Human-in-the-Loop (HITL) Mode: Allows expert supervision, intervention, and plan modification via Web UI or CLI.

Maintenance & Community

The project welcomes contributions via GitHub Issues and Discussions. Specific details on active maintainers, sponsorships, or dedicated community channels (e.g., Slack/Discord) are not explicitly detailed in the README.

Licensing & Compatibility

Licensed under the Apache License 2.0. This license permits commercial use and integration with closed-source projects, provided the terms of the license are followed.

Limitations & Caveats

LuaN1ao includes high-privilege tools (shell_exec, python_exec) that pose significant risks. It is strongly recommended to run the agent within isolated environments like Docker containers or VMs, with network and data isolation. The tool is strictly intended for authorized security testing and educational purposes; unauthorized use is illegal and carries severe legal and technical risks. It must not be used on production environments.