# 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.

![Uxarion CLI chat interface](./image.png)

---

## 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`, `rachidshade@gmail.com`, `github.com/rachidlaad`.

---

## Table of Contents

1. [Prerequisites](#prerequisites)
2. [Quick Start](#quick-start)
3. [Configuring API Access](#configuring-api-access)
4. [Running Uxarion](#running-uxarion)
5. [Practice Target: Suno Banking App](#practice-target-suno-banking-app)
6. [Outputs & Artifacts](#outputs--artifacts)
7. [Project Structure](#project-structure)
8. [Troubleshooting](#troubleshooting)
9. [Roadmap & Known Gaps](#roadmap--known-gaps)
10. [Community & Support](#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)

```bash
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

```bash
pip install uxarion
uxarion --addKey
uxarion
```

If `uxarion` is not found after install:

```bash
# 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)

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

### Manual Install (fallback)

```bash
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:
   ```bash
   uxarion --addKey sk-...
   ```
   Or prompt securely (no echo):
   ```bash
   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:
   ```dotenv
   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.

```bash
# 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](#outputs--artifacts)).

## Practice Target: Suno Banking App

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

```bash
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`](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](https://x.com/Rachid_LLLL)  
  Email: [rachidshade@gmail.com](mailto:rachidshade@gmail.com)  
  GitHub: [github.com/rachidlaad](https://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](./LICENSE).
