LuaN1ao Security Agent
A traceable graph-reasoning runtime for authorized penetration testing.
Per-dimension scores and reasoning
Evidence shows: least privilege is reasonably addressed through sandbox isolation and permission controls (Docker containers run as UID 1000, no capabilities, read-only root filesystem, network namespace isolation), but lacks fine-grained permission control at the tool-call level. User confirmation exists but is weak: CLI startup requires explicit --scope and --goal, but no step-by-step confirmation or approval mechanism during execution. Data flow transparency is good: events, graph deltas, artifacts are persisted, but lacks full visualization of data flow. Sensitive data handling is good: credentials stored with 0600 permissions and non-searchable, but no mention of encryption at rest. Dependency security is average: some dependencies are pinned, but no vulnerability scanning or supply chain security measures. External effects are controlled: network traffic is managed through proxy and gateway, but no rollback mechanism. Rollback is weak: only session resume, no operation-level rollback. Source attribution is average: no clear author or maintainer information, only team mention.
Evidence shows: self-consistency is good, README aligns with code structure, tests cover core functionality. Dependency availability is average: relies on multiple third-party libraries, but no availability guarantees or mirrors. Failure messages are good: tests verify clear error messages like 'No part of the delta was accepted'.
Evidence shows: target audience is clear (security researchers), scenarios cover authorized penetration testing. Capability boundaries are clear: target scope limited via --scope and --goal, toolset is restricted. Trigger precision is good: structured tools and schema validation ensure precise triggering. Environment fit is good: supports macOS and Linux, but Windows not validated.
Evidence shows: information architecture is clear, README structure is complete. Install notes are detailed, including dependencies and build steps. Naming stability is average: project name and version are clear, but no API stability guarantee. Examples and FAQ are good: quick start and CLI options provided. Known limitations are clear: e.g., Windows not validated. License is AGPL-3.0, but no copyright notice. Versioning and changelog missing: no CHANGELOG provided. Maintenance responsibility unclear: no maintainer info or contribution guide.
Evidence shows: output usability is good: multiple output formats like JSONL and TUI. Marginal value is high: innovative features like causal graph reasoning and evidence preservation. Cost-benefit is good: automated pentesting saves effort, but requires LLM API and Docker resources.
Evidence shows: claim traceability is good: README claims features, code and tests support. Cross-source corroboration is average: relies solely on single repository, no external validation. Fact-inference separation is good: clearly distinguishes hypotheses from confirmed vulnerabilities.
- This agent is an autonomous penetration testing tool; must be used in authorized environments only, otherwise may violate laws.
- Third-party skill collections (e.g., pentest-skills) may contain malicious content; review required.
- No rollback mechanism provided; operational mistakes may lead to irreversible consequences.
- No dependency vulnerability scanning; supply chain risks need attention.
What does this agent do, and when should you use it?
LuaN1aoAgent v2 is a TypeScript and Pi SDK rewrite for autonomous, authorized security research. It separates Planner, Executor, and Observer responsibilities: the Planner manages a task graph, Executors run bounded tasks in isolated workspaces, and Supervisor and Projector handle control decisions and graph projection independently. The runtime persists execution events, artifacts, task, reasoning, and operation graphs, with both a terminal timeline and an authenticated Web Workbench for inspection. Executors can perform workspace inspection, controlled shell execution, web and vulnerability research, browser rendering, and route management; Docker is the recommended isolation and transparent-gateway backend. It fits security teams with authorized targets, an isolated execution environment, and an OpenAI-compatible LLM service—not unrestricted testing of production systems.
A user starts a run with npm start -- --goal ... --scope ...; the Controller invokes the Planner to maintain the Task Graph and admits dependency-ready work, including independent tasks that can run in parallel. Each Executor receives a TaskEnvelope and can use read, grep, find, ls, bash, web_fetch, web_search, vulnerability_search, browser_render, artifact_read, and artifact_write in a task-specific workspace, then completes or checkpoints through task_result_submit. Pi events are normalized into the ExecutionLog, large outputs are stored as content-addressed artifacts, and the Projector uses graph_delta_submit to produce evidence-backed Reasoning Graph and Operation Graph updates; the Supervisor uses control_submit to continue, checkpoint, stop, or return control to the Planner. Runs can emit final JSON or JSONL event streams, while the Web Workbench exposes graphs, events, artifacts, and traffic history.
- An internal red team assessing an explicitly authorized web service and needing reconnaissance, validation, and evidence retained in one auditable session.
- A security researcher testing a lab or CTF environment who needs to keep public CVE leads distinct from validation against the target.
- A security team running several independent authorized testing tasks in parallel while using a dependency graph to govern follow-up validation.
- An analyst who needs to inspect Agent intent, tool calls, and artifacts live in a terminal or review persisted execution records in a browser.
- A tester reaching authorized internal targets through Docker Gateway, SSH, or Chisel routes while retaining connection and traffic evidence.
What are this agent's strengths and limitations?
- Planner, Executor, Supervisor, and Projector have explicit boundaries, keeping task topology, low-level tool actions, and semantic graph projection separate.
- The reasoning graph connects Evidence, Hypothesis, Vulnerability, and Exploit; confirmed vulnerabilities and successful exploits require evidence references.
- Each task retains an isolated workspace and same-task Pi session lineage, while dependency-aware scheduling supports concurrent independent work.
- Execution logs, artifacts, graph deltas, and network traffic are durable and reviewable through both the terminal and authenticated Web Workbench.
- v2 requires Node.js 25+ and is validated only for macOS and Linux; Windows is not a validated v2 release target.
- It requires an OpenAI-compatible LLM API; the full Brave search API path needs
BRAVE_SEARCH_API_KEYorBRAVE_API_KEY, while higher NVD limits need the optionalNVD_API_KEY. - Executors can run shell commands and interact with network services, so the documentation requires an isolated host, VM, or container and explicitly authorized targets.
- Docker is the recommended transparent Gateway backend; explicit Docker mode fails closed if Docker or a required image is unavailable, and reproducible public v2 benchmarks are not yet published.
How do you install or deploy this agent?
Requires macOS or Linux, Node.js 25+, and an OpenAI-compatible LLM API. Clone and build the repository:
git clone https://github.com/SanMuzZzZz/LuaN1aoAgent.git
cd LuaN1aoAgent
npm ci
npm run buildFor the recommended Docker backend, also run:
npm run build:executor-image
npm run build:network-imageCreate an uncommitted .env in the repository root:
LLM_API_KEY=your-api-key
LLM_API_BASE_URL=https://api.openai.com/v1
LLM_DEFAULT_MODEL=your-model-id
LLM_API_TYPE=openai-completionsLLM_API_TYPE may instead be openai-responses.
How do you use this agent?
Start a new session with an explicitly authorized target and scope:
npm start -- --goal "Assess http://<authorized-routable-host>:8080 within authorized scope" --scope "Only http://<authorized-routable-host>:8080" --max-cycles 8 --max-parallel-tasks 2An interactive terminal timeline starts automatically on a TTY. Use --json for final JSON or --jsonl for the durable event stream. Resume one unfinished session with npm start -- --resume 20260720-080000Z-a1b2c3d4; do not include --goal or --scope when resuming. To inspect a session in the browser, run npm run web -- --runtime-dir .agent-runtime/sessions/<session> --port 8787 and open http://127.0.0.1:8787.
How does this agent compare with similar options?
The repository contrasts v2 with its v1 branch and v1.0.0 release: v1 uses Python and a Planner/Executor/Reflector shared reflection loop, while v2 uses TypeScript + Pi SDK, Planner/Executor/Observer roles, task/reasoning/operation graphs, task-scoped sessions, and an authenticated runtime observability interface. The repository explicitly says v1 benchmark results are not automatically attributable to v2.
FAQ
Can I use it against any public target?
What does a run retain?
.agent-runtime/sessions/<session>/, including state.sqlite, execution.jsonl, graph-deltas.jsonl, artifacts, task sandboxes, Pi session lineage, and traffic data.Can it run without Docker?
workspace development fallback. Docker is the recommended backend, and an explicitly selected Docker mode fails closed when Docker or a required image is unavailable.