Xalgorix/Docs/Overview

Getting Started

Xalgorix is the most comprehensive open-source autonomous penetration testing platform. It combines the power of AI with 85+ security tools to deliver enterprise-grade pentesting — completely free.

What is Xalgorix?

Xalgorix is an AI-powered autonomous pentesting agent. Give it a target URL, and it will:

Automatically discover subdomains, endpoints, and parameters
Run 85+ security tools across a 20-phase methodology
Find exploitable vulnerabilities with precision
Generate professional PDF reports
Send Discord alerts on findings

Key Highlights

Feature	Description
Autonomous	No human intervention needed. Set a target, watch it work.
AI-Powered	Leverages LLMs (GPT, Claude, DeepSeek, Gemini) for intelligent decisions.
100% Free	No SaaS, no per-scan fees, no limits. MIT licensed.
Self-Hosted	Your data never leaves your machine.
Web UI	Dark mode dashboard with live feed, chat, and token tracking.
Multi-LLM	7+ providers: OpenAI, Anthropic, DeepSeek, Google, Groq, Ollama, MiniMax.

Quick Overview

# Install
GOPROXY=direct go install -v github.com/xalgord/xalgorix/v4/cmd/xalgorix@latest

# Configure (~/.xalgorix.env)
XALGORIX_LLM=openai/gpt-5.4
XALGORIX_API_KEY=sk-your-key

# Run
xalgorix --web

Installation

Install Xalgorix via Go, build from source, or use the pre-built binary.

Requirements

Go 1.24+ — Check with go version
Linux recommended (also works on macOS, WSL)
An LLM API key (OpenAI, Anthropic, etc.)

Install Go (if needed)

# Quick install Go 1.24 on Linux
sudo rm -rf /usr/local/go
wget -q https://go.dev/dl/go1.24.2.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.24.2.linux-amd64.tar.gz && rm go1.24.2.linux-amd64.tar.gz
export PATH=/usr/local/go/bin:$HOME/go/bin:$PATH

Install via Go (Recommended)

GOPROXY=direct go install -v github.com/xalgord/xalgorix/v4/cmd/xalgorix@latest

Build from Source

git clone https://github.com/xalgord/xalgorix.git
cd xalgorix
make install

Update

# Option 1: Self-update
xalgorix --update

# Option 2: Reinstall latest
GOPROXY=direct go install -v github.com/xalgord/xalgorix/v4/cmd/xalgorix@latest

Xalgorix also auto-updates on every start, so you're always running the latest version.

Systemd Service

# Install and start as a systemd service
xalgorix --start

# Other service commands
xalgorix --stop
xalgorix --restart
xalgorix --uninstall

Configuration

All configuration is done via the ~/.xalgorix.env file. Xalgorix will refuse to start if required variables are missing.

Required Variables

Variable	Description	Example
`XALGORIX_LLM`	Model name with provider prefix	`openai/gpt-5.4`
`XALGORIX_API_KEY`	Your LLM API key	`sk-...`

Minimal Configuration

# ~/.xalgorix.env
XALGORIX_LLM=openai/gpt-5.4
XALGORIX_API_KEY=sk-your-api-key

Optional — API Base

Variable	Description	Example
`XALGORIX_API_BASE`	API base URL (auto-detected from provider)	`https://api.openai.com/`

Optional — Web Search

Variable	Description
`GEMINI_API_KEY`	Google Gemini API key for web search. Falls back to Brave/Google/Bing/DuckDuckGo scraping.

Optional — Model Settings

Variable	Default	Description
`XALGORIX_REASONING_EFFORT`	`high`	Reasoning effort: low, medium, high
`XALGORIX_LLM_MAX_RETRIES`	`5`	Max retries on API failure
`XALGORIX_MEMORY_COMPRESSOR_TIMEOUT`	`60`	Context compression timeout (seconds)
`XALGORIX_MAX_ITERATIONS`	`0`	Max iterations (0 = unlimited)

Optional — Integrations

Variable	Description
`XALGORIX_DISCORD_WEBHOOK`	Discord webhook URL for alerts
`XALGORIX_USERNAME`	Dashboard username (enables auth)
`XALGORIX_PASSWORD`	Dashboard password

Optional — Rate Limiting

Variable	Default	Description
`XALGORIX_RATE_LIMIT_REQUESTS`	`60`	Requests per window
`XALGORIX_RATE_LIMIT_WINDOW`	`60`	Window in seconds

Optional — Browser

Variable	Default	Description
`XALGORIX_DISABLE_BROWSER`	`false`	Set to `true` to disable browser automation

Full Configuration Example

# ~/.xalgorix.env — Full configuration

# Required
XALGORIX_LLM=openai/gpt-5.4
XALGORIX_API_KEY=sk-your-key

# Optional — Custom API endpoint
# XALGORIX_API_BASE=https://api.openai.com/

# Optional — Web search
GEMINI_API_KEY=AIza...

# Optional — Discord alerts
XALGORIX_DISCORD_WEBHOOK=https://discord.com/api/webhooks/...

# Optional — Dashboard auth
XALGORIX_USERNAME=admin
XALGORIX_PASSWORD=your-secure-password

# Optional — Rate limiting
XALGORIX_RATE_LIMIT_REQUESTS=60
XALGORIX_RATE_LIMIT_WINDOW=60

Quick Start

Get Xalgorix up and running in under 2 minutes.

Step 1 — Install

GOPROXY=direct go install -v github.com/xalgord/xalgorix/v4/cmd/xalgorix@latest

Step 2 — Configure

nano ~/.xalgorix.env

Add your LLM provider and API key:

XALGORIX_LLM=openai/gpt-5.4
XALGORIX_API_KEY=sk-your-key

Step 3 — Run

# Web UI (recommended)
xalgorix --web

# Or CLI mode
xalgorix --target https://example.com

The Web UI launches at http://localhost:1337 by default. Change the port with --port 8080.

Web UI Guide

Xalgorix includes a full-featured dark mode Web UI dashboard with live feed, chat, and scan management.

Launching the Web UI

xalgorix --web
# Or with custom port
xalgorix --web --port 8080

Dashboard Features

Feature	Usage
Single Scan	Enter URL, click Start
DAST Scan	Select "DAST" mode for deep URL vuln testing
Wildcard Scan	Select "Wildcard" for subdomain enum + scan each
Multi-Target	Upload a `.txt` file with one target per line
Severity Filter	Check only Critical/High to skip Low/Info
Out of Scope	Exclude specific targets from testing
Custom Instructions	Tell Xalgorix what to focus on
LLM Provider	Switch providers in settings
Discord	Add webhook for real-time alerts

Example Custom Instructions

# Focus on specific vulns
"Focus on SQL Injection and IDOR. Skip XSS."

# Authenticated testing
"Login with: admin@email.com / Password123"

# Bug bounty rules
"This is a HackerOne program. Out of scope: DoS, social engineering."

# Internal network
"Scan 10.0.0.0/24. Focus on SMB and database services."

Authentication

Protect your dashboard with optional login:

# Add to ~/.xalgorix.env
XALGORIX_USERNAME=admin
XALGORIX_PASSWORD=your-secure-password

CLI Reference

Complete command-line flag reference for Xalgorix.

All Flags

Flag	Alias	Description
`--web`	`-w`	Launch the Web UI dashboard
`--port`	`-p`	Web UI port (default: 1337)
`--target`	`-t`	Target URL, IP, or local path (repeatable)
`--instruction`	`-i`	Custom instructions for the agent
`--model`	`-m`	LLM model (overrides XALGORIX_LLM)
`--update`	`-up`	Update to latest version
`--version`	`-v`	Show version
`--start`	—	Install and start as systemd service
`--stop`	—	Stop the service
`--restart`	—	Restart the service
`--uninstall`	—	Remove from system
`--help`	`-h`	Show help

Usage Examples

# Launch web UI
xalgorix --web

# Scan a target from CLI
xalgorix --target https://example.com

# Multiple targets
xalgorix --target https://a.com --target https://b.com

# Custom model + instructions
xalgorix --target https://example.com --model anthropic/claude-sonnet-4.6 -i "Focus on API vulns"

Scan Modes

Xalgorix supports three scan modes, each designed for different testing scenarios.

Single Scan

Scan a single URL or target with full vulnerability testing using the 20-phase methodology. Best for quick assessments of individual targets.

DAST Scan

Deep Application Security Testing. Designed for thorough web application testing:

Crawl the target to discover all endpoints
Parameter discovery and fuzzing
Nuclei scanning on all discovered URLs
Manual exploitation attempts on promising findings

Wildcard Scan

The most comprehensive mode. Performs full subdomain enumeration, then scans each subdomain individually:

Passive subdomain enumeration (subfinder, assetfinder, crt.sh)
Active subdomain enumeration (amass, brute-force)
DNS resolution on all discovered subdomains
Each live subdomain gets a full individual scan
DAST-level testing on each target

Wildcard scans can take a long time depending on the number of subdomains discovered. Use the queue system to manage long-running scans.

LLM Providers

Xalgorix supports 7+ LLM providers out of the box, plus any custom OpenAI-compatible endpoint.

Supported Providers

Provider	Prefix	Example Models	Auto-Detected Endpoint
OpenAI	`openai/`	gpt-5.4, gpt-5.4, o1, o3	https://api.openai.com/v1
Anthropic	`anthropic/`	claude-opus-4.6, claude-sonnet-4.6	https://api.anthropic.com
DeepSeek	`deepseek/`	deepseek-v3, deepseek-v3	https://api.deepseek.com/v1
Google	`google/`	gemini-3.1-pro, gemini-2.0-flash	https://generativelanguage.googleapis.com/v1
Groq	`groq/`	llama-4, qwen3, mixtral	https://api.groq.com/openai/v1
Ollama	`ollama/`	llama4, qwen3 (local)	http://localhost:11434/v1
MiniMax	`minimax/`	M3, Text-01	https://api.minimax.io/v1

Custom Providers

To use any OpenAI-compatible provider, set a custom prefix and API base:

XALGORIX_LLM=custom/my-model
XALGORIX_API_KEY=your-key
XALGORIX_API_BASE=https://your-custom-llm.com/v1

Tools (85+)

Complete catalog of 85+ security tools that Xalgorix integrates with. All tools are auto-installed when needed.

Recon & Subdomain Enumeration (15 tools)

#	Tool	Purpose
1	subfinder	Passive subdomain enumeration
2	findomain	Subdomain discovery
3	assetfinder	Find related subdomains
4	dnsx	DNS resolution & bruteforce
5	amass	Subdomain enumeration
6	gospider	Web spidering
7	katana	Next-gen crawling
8	hakrawler	Web crawling
9	gau	Get All URLs
10	waybackurls	Wayback Machine URLs
11	paramspider	Parameter discovery
12	crt.sh	Certificate transparency
13	bufferover	DNS enumeration
14	webarchive	Historical URLs
15	shuffledns	DNS bruteforce

HTTP & Scanning (15 tools)

#	Tool	Purpose
1	httpx	HTTP probing
2	nuclei	Vulnerability scanning
3	gobuster	Directory busting
4	ffuf	Fuzzing
5	feroxbuster	Recursive fuzzing
6	dirsearch	Web path scanning
7	nikto	Web server scanning
8	whatweb	Web technology fingerprint
9	wpscan	WordPress scanner
10	sqlmap	SQL injection testing

Exploitation (15 tools)

#	Tool	Purpose
1	nmap	Port & service scanning
2	masscan	Fast port scanner
3	naabu	Fast port scanner
4	hydra	Password cracking
5	john	Password cracking
6	hashcat	GPU password cracking
7	impacket	Windows exploitation
8	responder	LLMNR/NBTNS spoofing
9	crackmapexec	Network exploitation
10	dalfox	XSS scanner

Agent Built-in Tools

Tool	Description
terminal_execute	Run shell commands with auto-install
browser	Browser automation (headless Chrome)
playwright	Browser control for testing
websearch	Web search via Gemini/Brave/Google/Bing
notes	Track findings and endpoints
reporting	Generate PDF reports
thinking	AI reasoning and planning
finish	Complete and summarize scan

Auto-Install

Xalgorix automatically installs any missing tools when needed. Supported package managers:

Go — go install
APT — apt install
PIP — pip install
Cargo — cargo install
Gem — gem install
NPM — npm install

20-Phase Methodology

Xalgorix follows a comprehensive, systematic approach to penetration testing.

#	Phase	Description
01	Recon	Subdomains, ports, directories
02	Vuln Scan	Nuclei, nmap scripts
03	Content	Fuzzing, backups, admin panels
04	SSL/TLS	Cipher suites, certificates, headers
05	Auth	SQLi login, brute-force, OAuth
06	Injection	XSS, SQLi, Command, XXE, SSTI
07	SSRF	Param fuzzing, cloud metadata
08	IDOR	Access control, privilege escalation
09	API	GraphQL, REST, rate limiting
10	Upload	Extension bypass, webshells
11	RCE	Deserialization, Log4j
12	Race	TOCTOU, business logic
13	Takeover	Subdomain, CNAME
14	Email	SPF, DKIM, DMARC
15	Cloud	S3, Azure, GCP, K8s
16	WebSocket	Origin, injection
17	CMS	WordPress, Joomla, Drupal
18	Links	Broken link hijacking
19	Supply Chain	JS libs, dependencies
20	Report	JSON + PDF generation

Architecture

Technical overview of Xalgorix's system architecture and internal components.

System Overview

┌────────────────────────────────────────────────────────┐
│                     USER LAYER                         │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│  │  Web UI  │ │   CLI    │ │   API    │ │ Discord  │ │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
└───────┼──────────���──┼───────────┼─────────────┼───────┘
        └─────────────┼───────────┼─────────────┘
                      ▼           ▼
┌────────────────────────────────────────────────────────┐
│                     CORE LAYER                         │
│  ┌──────────────────────────────────────────────────┐  │
│  │              WEB SERVER (Go)                     │  │
│  │  HTTP Server │ WebSocket │ Queue Mgr │ Config    │  │
│  └──────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────┐  │
│  │              AGENT ENGINE                        │  │
│  │  LLM Client │ Tool Exec │ State │ Memory Mgr    │  │
│  └──────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────┘
                      │
                      ▼
┌────────────────────────────────────────────────────────┐
│                    TOOL LAYER                          │
│  RECON      │ SCANNING   │ EXPLOIT    │ UTILITY       │
│  subfinder  │ nuclei     │ sqlmap     │ terminal      │
│  amass      │ nmap       │ dalfox     │ browser       │
│  katana     │ ffuf       │ hydra      │ websearch     │
└────────────────────────────────────────────────────────┘
                      │
                      ▼
┌────────────────────────────────────────────────────────┐
│                INTEGRATION LAYER                       │
│  OpenAI │ Anthropic │ DeepSeek │ Google │ Exploit-DB  │
│  NIST NVD │ Discord │ Caido Proxy                     │
└────────────────────────────────────────────────────────┘

Directory Structure

xalgorix/
├── cmd/xalgorix/          # CLI entry point
├── internal/
│   ├── agent/             # Core agent loop
│   ├── config/            # Configuration
│   ├── llm/               # LLM client & parser
│   ├── tools/             # 11 built-in tools
│   │   ├── terminal/      # Command execution
│   │   ├── browser/       # Headless Chrome
│   │   ├── python/        # Python scripts
│   │   ├── reporting/     # Vulnerability reports
│   │   └── ...
│   ├── web/
│   │   ├── server.go      # HTTP + WebSocket
│   │   └── static/        # Web UI (HTML/CSS/JS)
│   └── tui/               # Terminal UI
└── skills/                # Vulnerability knowledge

Data Storage

~/xalgorix-data/
└── target.com/
    └── 2026-01-15/
        └── example.com_abc123/
            └── scan.json
    └── queue_state.json

30-day auto-cleanup
Survives page refresh
Queue resume after restart

Skills System

Skills are specialized knowledge packages that enhance Xalgorix agents with deep expertise in specific vulnerability types, technologies, and testing methodologies.

How Skills Work

When an agent is created, it can load up to 5 specialized skills relevant to the specific subtask. Skills are dynamically injected into the agent's system prompt for deep, contextual expertise.

Skill Categories

Category	Purpose
/vulnerabilities	Advanced techniques for auth bypasses, business logic, race conditions
/frameworks	Framework-specific testing: Django, Express, FastAPI, Next.js
/technologies	Supabase, Firebase, Auth0, payment gateways
/protocols	GraphQL, WebSocket, OAuth patterns
/cloud	AWS, Azure, GCP, Kubernetes security
/reconnaissance	Advanced information gathering and enumeration
/custom	Community-contributed specialized skills

Creating Custom Skills

A good skill includes:

Advanced techniques — Non-obvious methods specific to the domain
Practical examples — Working payloads and test cases
Validation methods — Confirm findings, avoid false positives
Context-specific insights — Version nuances, edge cases
YAML frontmatter — name and description fields

API Reference

REST API endpoints for programmatic control of Xalgorix scans.

Scan Endpoints

Method	Endpoint	Description
`POST`	`/api/scan`	Start a new scan
`POST`	`/api/stop`	Stop current scan
`GET`	`/api/status`	Get current status
`GET`	`/api/scans`	List all scans
`GET`	`/api/scans/:id`	Get scan details
`GET`	`/api/report/:id`	Download PDF report

Queue Endpoints

Method	Endpoint	Description
`GET`	`/api/queue/status`	Check interrupted queue
`POST`	`/api/queue/resume`	Resume interrupted scan
`POST`	`/api/queue/clear`	Clear scan queue

Settings Endpoints

Method	Endpoint	Description
`GET`	`/api/settings/rate-limit`	Get rate limit config
`POST`	`/api/settings/rate-limit`	Update rate limit config

Safety & Security

Xalgorix includes multiple safety mechanisms to prevent destructive actions.

Blocked Commands

# Filesystem destruction
❌ rm -rf /  |  rm -rf ~  |  mkfs  |  dd

# SQL destruction
❌ DROP TABLE  |  DELETE FROM  |  UPDATE (bulk)

# System commands
❌ shutdown  |  reboot  |  halt  |  poweroff

# Code destruction
❌ shutil.rmtree  |  os.remove

Encoding Bypass Detection

Xalgorix detects obfuscated destructive commands:

Technique	Example
Base64	`echo cm0gL3JmIC8= \| base64 -d`
Hex	`\x72\x6d\x20\x2d\x72\x66`
URL	`%72%6d%20%2d%72%66`

Circuit Breaker

After 5 consecutive failures, a tool is temporarily blocked for 60 seconds to prevent wasting time and resources.

Rate Limiting

Configurable rate limiting protects your IP from being blocked by target services. Default: 60 requests per 60-second window.

Integrations

Xalgorix integrates with several external services for notifications, security testing, and authentication.

Discord Alerts

Get real-time notifications for scan start, vulnerability discovery, and completion.

# Add to ~/.xalgorix.env
XALGORIX_DISCORD_WEBHOOK=https://discord.com/api/webhooks/...

Caido Proxy

Integration with Caido for HTTP request capture and replay:

Auto-installs Caido if not present
Auto-starts if not running
HTTP request capture during scans
Request replay and modification

CAIDO_PORT=8080
CAIDO_API_TOKEN=your-caido-token

AgentMail

Built-in email system for automated testing of sign-up flows and OTP verification.

# Example instruction for authenticated testing
"AgentMail credentials: api_key=xxx, email=user@agentmail.to"

PDF Reports

Xalgorix auto-generates professional pentest reports in PDF format.

Report Contents

Cover page — Target name and scan date
Executive summary — Vulnerability counts by severity
Vulnerability details — CVSS scoring, proof-of-concept, remediation steps
Tested endpoints — All URLs and endpoints tested
Methodology — Phases applied during the scan
Legal disclaimer — Standard pentest disclaimer

Downloading Reports

Reports are available via the Web UI or API:

# Via API
curl http://localhost:1337/api/report/{scan-id} -o report.pdf

FAQ

Frequently asked questions about Xalgorix.

Is Xalgorix free?

Yes, 100% free and open source under the MIT license. No SaaS, no per-scan fees, no limits.

What LLM should I use?

For best results, use GPT-5.4 or Claude Opus 4.6. For budget-friendly options, DeepSeek-V3 or Groq (free tier) work well.

Can I use it for bug bounty?

Yes! Xalgorix is designed for bug bounty programs. Use custom instructions to follow program rules and scope.

Does it work on internal networks?

Yes. You can scan IPs, CIDR ranges, and internal services. Use Ollama for local LLM if you need air-gapped operation.

How do I update?

Run xalgorix --update or reinstall via Go. Xalgorix also auto-updates on every start.

Where is scan data stored?

In ~/xalgorix-data/. Data is organized by target and date with 30-day auto-cleanup.

Can I contribute?

Yes! Pull requests are welcome. See the GitHub repository for contribution guidelines.

← Previous

—