uxarion 0.1.0

Linux-first CLI and AI-driven pentesting orchestrator for Uxarion

Uxarion CLI – AI Pentesting Copilot

Official site: https://uxarion.com/

AI-assisted penetration testing for security researchers, red-teamers, and defenders. Uxarion CLI blends an autonomous command-loop agent with a rich terminal chat experience so you can plan, execute, and report findings faster on scoped targets.

Authorized Testing Only
Use this toolkit exclusively on systems you own or have written permission to assess. The maintainers assume no responsibility for misuse.

---

Why Uxarion?

• Autonomous AI Operator – The unified uxarion command plans reconnaissance, executes tasks, captures evidence, and writes concise reports.
• Terminal Chat UI – Rich-powered chat interface with streaming updates, context memory, a persistent “Running…” indicator, and quick actions for updating API keys on the fly.
• Built-In Training Target – The intentionally vulnerable Suno banking demo (Flask) lets you practice JWT tampering, SSRF, command injection, and file disclosure scenarios offline.
• Safety Guardrails – Command validator enforces allow-lists, scope restrictions, duplicate avoidance, and blocks destructive patterns.
• Friendly Builder – Crafted by Rachid Laadraoui. Connect & collaborate: X.com/@Rachid_LLLL, [e-mail], github.com/rachidlaad.

---

Table of Contents

1. Prerequisites
2. Quick Start
3. Configuring API Access
4. Running Uxarion
5. Practice Target: Suno Banking App
6. Outputs & Artifacts
7. Project Structure
8. Troubleshooting
9. Roadmap & Known Gaps
10. Community & Support

---

Prerequisites

• Operating System: Linux or WSL2 on Windows (Rich UI recommended in a true terminal).
• Python: 3.11 or newer.
• Required AI key:
  • OpenAI API key (GPT-5.2 default).
• Optional packages:
  pip install openai prompt_toolkit to unlock chat/UI extras.

---

Quick Start

30-Second Install (recommended)

git clone https://github.com/rachidlaad/Uxarion-CLI.git
cd Uxarion-CLI

# one command installer (pipx if available, otherwise local .venv + launcher)
./install.sh

# set your API key
uxarion --addKey

# start interactive chat
uxarion

Install from PyPI

pip install uxarion
uxarion --addKey
uxarion

If uxarion is not found after install:

# pipx installs
pipx ensurepath

# local launcher installs
export PATH="$HOME/.local/bin:$PATH"

Then open a new shell and retry.

One-line bootstrap (from GitHub)

curl -fsSL https://raw.githubusercontent.com/rachidlaad/Uxarion-CLI/main/install.sh | bash

Manual Install (fallback)

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .

Optional extras:

• fastapi + aioredis enable the experimental SSE API in uxarion_cli/ui/sse_api.py.
• prompt_toolkit adds enhanced line-editing inside the chat UI.
• requirements-suno.txt installs the vulnerable Suno target for local practice.

---

Configuring API Access

You can supply keys in three ways:

1. CLI key command (--addKey)
   Set or replace the key directly:

   uxarion --addKey sk-...
   

   Or prompt securely (no echo):

   uxarion --addKey
   

2. Interactive Quick Actions / chat command
   Launch chat UI (uxarion) and use either:

   • / → 1 (quick actions menu), or
   • /addkey (secure prompt), or
   • /addkey sk-... (inline set) The UI updates your environment and .env.

3. Manual .env update
   Create .env at the project root (or edit the existing file) and add:

   OPENAI_API_KEY=sk-...
   OPENAI_MODEL=gpt-5.2
   

   Reactivate your virtualenv or restart the CLI so changes take effect.

If no OpenAI key is present, the agent will stop with a clear “API key not configured” error before any commands run. If you start uxarion without a key, the wrapper now offers a first-run key setup prompt.

---

Running Uxarion

Uxarion uses one command name for all workflows.

# 1) No args -> interactive chat
uxarion

# 2) Args -> non-interactive run and exit
uxarion --prompt "Assess http://127.0.0.1:5000/api/diagnostics/ping for command injection and other exposures" \
  --max-commands 1

# 3) Optional: run task, then continue in chat
uxarion --prompt "Quick recon on https://example.com" --max-commands 3 --chat-after

# 4) Environment sanity check
uxarion --doctor

Workflow highlights

• No args starts interactive chat immediately.
• With task flags (--prompt, --max-commands, etc.), Uxarion runs directly and exits.
• Add --chat-after to continue in interactive chat after a direct run.
• In chat, use /help, /settings, /exec <cmd>, /clear, /context, /addkey.
• Evidence and reports stream into the terminal; the final report is saved to disk (see Outputs).

Practice Target: Suno Banking App

Suno is a deliberately vulnerable Flask application that mirrors common web flaws without relying on SQL injection.

pip install -r requirements-suno.txt
python -m suno_app.app
# Suno runs at http://127.0.0.1:5000 by default

Intentional weaknesses:

• JWT role escalation (/auth/login & /dashboard)
• Command injection (/api/diagnostics/ping)
• SSRF (/api/preview)
• Path traversal (/files/download)

See README_SUNO.md for walkthrough goals. Point the agent at http://127.0.0.1:5000 for an end-to-end practice run.

---

Outputs & Artifacts

• Run reports: stored in .uxarion_runs/<run_id>/report.md plus a session run_result.json. If you prefer to keep the working tree clean, delete or move these after review.
• Evidence snippets: extracted lines attached to each observation to speed up report authoring.
• Console transcript: use uxarion_chat.log if you capture terminal output (ignored by git).

---

Project Structure

├── uxarion.py                  # Unified command entry point (chat/direct/--chat-after)
├── uxarion_cli.py              # Single-shot autonomous agent & CLI
├── install.sh                  # First-time installer (recommended)
├── uxarion_cli/                # Package (chat UI, orchestrator shim, helpers)
│   ├── core/orchestrator.py    # Bridges CLI orchestrator to single-shot agent
│   ├── ui/chat_ui.py          # Rich chat interface with spinner + quick actions
│   ├── ui/interactive_ui.py    # Menu-driven UI
│   ├── ui/sse_api.py           # SSE API stubs (requires optional components)
│   └── tools/                  # Safety / sandbox helpers (minimal in this fork)
├── requirements.txt            # Dependency list for quick installs
├── suno_app/                   # Vulnerable banking demo target
├── README.md                   # (you are here)
├── README_SUNO.md              # Suno target details
└── orchestration_flow.md       # Legacy architecture notes

---

Troubleshooting

Symptom	Likely Cause	Fix
RuntimeError: OPENAI_API_KEY not configured	Missing API key	Set key via quick actions or .env
openai.RateLimitError (429)	Account out of quota	Add billing credits or reduce request volume and retry
Spinner disappears instantly	Fixed in latest release – update to ensure spinner persists until completion
Commands rejected with out-of-scope host(s)	Scope validator parsing host from URL/headers	Add --scope flag, adjust objective, or remove out-of-scope headers
No output from Suno endpoints	Target app not running	Start python -m suno_app.app and ensure port matches your scope

---

Roadmap & Known Gaps

• REST/SSE orchestration server and graph memory backends are currently stubbed. Contributions welcome if you want to revive the full distributed orchestration pipeline.
• Secure sandbox module enforces validations but does not containerize tools. Integrate Docker or remote sandboxes for untrusted targets.
• More reporting templates (PDF/HTML) and remediation guidance are planned.
• Additional practice targets (beyond Suno) are in development.

---

Community & Support

• Builder: Rachid Laadraoui
  X/Twitter: @Rachid_LLLL
  Email: [e-mail]
  GitHub: github.com/rachidlaad
• Have feedback or want to collaborate? Open an issue, share ideas, or reach out directly. Bug fixes, new features, and target scenarios are all welcome.
• If Uxarion CLI helps your security workflow, star the repo so more researchers and defenders can discover this AI pentesting copilot.

Stay safe and stay ethical.

License

Uxarion CLI is licensed under the Apache License 2.0. See LICENSE.