Core Concepts

Understanding the key components and terminology used in Xalgorix.

Agent

The agent is the core LLM-driven loop that plans and executes security tests. It receives targets and instructions, calls tools in a loop, processes results, and decides what to test next. The agent uses a system prompt that defines a 22-phase testing methodology.

Scan

A scan is a single testing run against one or more targets. Each scan has a unique ID, configuration, status, events, and optional findings. Scans can be started from the dashboard or CLI, and can be paused, resumed, stopped, or restarted.

Scan Modes

Xalgorix supports three scan modes:

• Single target — test one URL or host
• DAST — browser-driven application security testing
• Wildcard / multi — enumerate subdomains and scan each

Methodology

A 22-phase structured testing approach covering reconnaissance, vulnerability discovery, injection testing, access control, API testing, and reporting. Phases can be selected individually per scan.

Findings

Vulnerabilities discovered during a scan. Each finding has a severity (Critical/High/Medium/Low/INFO), CVSS score, evidence, and remediation guidance. Findings are used to generate PDF reports.

Tools

Xalgorix includes 14 built-in agent tools (terminal, browser, notes, reporting, etc.) and can invoke 85+ external security tools (nmap, nuclei, sqlmap, ffuf, etc.) through the terminal. Missing tools can be auto-installed when enabled.

Skills

Skills are specialized knowledge packages loaded into the agent's context. They contain expert-level payloads, bypass techniques, and methodology for specific vulnerability classes (XSS, SQLi, SSRF, etc.) or technologies (Django, Laravel, etc.).

LLM Provider

The AI model backend that powers the agent's reasoning. Xalgorix supports OpenAI, Anthropic, DeepSeek, Groq, Google Gemini, Ollama (local), MiniMax, and any custom OpenAI-compatible endpoint.

Responsible Usage

Xalgorix is a security testing tool. Use it responsibly and only on systems you are authorized to test.

Authorization Required

Only scan systems you own or have explicit written permission to test. Unauthorized scanning is illegal in most jurisdictions and violates the terms of service of most platforms.

Scope Control

• Define clear scope boundaries before starting a scan
• Use the "Out of Scope" field in the dashboard to exclude targets
• Use custom instructions to limit testing to specific vulnerability classes
• Review the agent's actions in the live feed during testing

Rate Limiting

Configure rate limits to match the engagement rules. Default rate limits are conservative (60 requests per 60-second window). Increase only if the target's policy allows it.

Safety Controls

• Destructive commands (rm -rf, DROP TABLE, etc.) are blocked by default
• The agent is instructed to use read-only exploitation techniques
• Time-based testing (SLEEP, WAITFOR) is preferred over destructive payloads
• A circuit breaker stops tools after 5 consecutive failures
• A watchdog monitors for stuck processes and enforces timeouts

Data Handling

• All scan data is stored locally on your machine
• No data is sent to external services except the configured LLM provider API
• API keys are stored in ~/.xalgorix.env — protect this file
• PDF reports may contain sensitive vulnerability details — handle accordingly

Installation

Install Xalgorix on Linux, macOS, or Windows (WSL).

Prerequisites

• Go 1.24.2+ — check with go version
• Node.js and npm — required for building the bundled React Web UI
• Linux recommended (also works on macOS and Windows via WSL)
• An LLM API key from a supported provider

Install with Go

This downloads and installs the latest pre-built binary. The binary includes the embedded Web UI.

Build from Source

The make build target builds the React Web UI into internal/web/static and then builds the Go binary. The result is at build/xalgorix.

To install the built binary system-wide:

Install Go (if needed)

Linux Setup

The primary supported platform. Install Go, then use either installation method above. Common security tools (nmap, nuclei, etc.) are auto-installed on demand when XALGORIX_ALLOW_AUTO_INSTALL is enabled.

macOS Setup

Install Go via Homebrew:

Then use the Go install or build-from-source method. Browser automation requires Chrome or Chromium.

Windows / WSL Setup

Xalgorix runs inside WSL (Windows Subsystem for Linux). Install a Linux distribution in WSL, then follow the Linux installation steps. Native Windows is not fully supported.

Updating Xalgorix

Xalgorix also auto-checks for updates on every start (throttled to once per 6 hours).

Verifying Install

Expected output: xalgorix v4.4.1 (or newer).

Uninstalling

This removes the binary and systemd service. Data directories are preserved:

• ~/.xalgorix/ — configuration and skills
• ~/xalgorix-data/ — scan data and reports

To remove all data: rm -rf ~/.xalgorix ~/xalgorix-data

Quickstart

Get from zero to your first local dashboard scan in under 5 minutes.

Step 1 — Install Xalgorix

Verify: xalgorix --version

Step 2 — Configure LLM Provider

Add your provider and key:

Step 3 — Start the Dashboard

Expected output:

Step 4 — Open the Web UI

Navigate to http://127.0.0.1:9137 in your browser. The dashboard is bound to localhost by default.

Step 5 — Start a Scan

1. Click New Scan in the dashboard
2. Enter a target URL you own (e.g., https://example.com)
3. Select scan mode (Single target is fine for first run)
4. Click Start Scan

Step 6 — Monitor Live Feed

The Overview page shows live scan progress. Switch to the Scan Detail or Live Feed view to see individual tool calls, agent messages, and findings in real time.

Step 7 — Review Findings

After the scan completes, go to the Findings page to see discovered vulnerabilities sorted by severity. Each finding includes evidence, CVSS score, and remediation guidance.

Step 8 — Generate Report

From the scan detail page, click Download Report to get a branded PDF. You can set a company name and upload a logo in Settings for branded reports.

Common First-Run Errors

First Scan

Detailed walkthrough of running your first scan and understanding the output.

Choosing a Target

Use a target you own or have explicit permission to test. Good first targets:

• A local web application running on localhost
• A test environment you control
• A deliberately vulnerable app (DVWA, Juice Shop, etc.)

CLI Scan

CLI Scan with Custom Instructions

Dashboard Scan

1. Open http://127.0.0.1:9137
2. Go to Settings and confirm the LLM provider and API key
3. Click New Scan
4. Enter the target URL
5. Select scan mode and methodology phases (optional)
6. Click Start Scan

Understanding Scan Output

During a scan, the agent:

1. Reconnaissance — discovers subdomains, ports, endpoints, technologies
2. Vulnerability testing — tests parameters for injection, access control, business logic flaws
3. Verification — confirms findings with exploitation proof
4. Reporting — generates findings and PDF report

The live feed shows each tool call, result, and agent decision in real time.

Scan Lifecycle

Web Dashboard

The local Web UI for managing scans, viewing findings, and configuring Xalgorix.

Starting the Dashboard

Dashboard Pages

New Scan

From the dashboard, click New Scan to configure:

• Target URL or host
• Scan mode (Single, DAST, Wildcard/multi)
• Methodology phase selection
• Severity filters
• Custom instructions
• Company name and logo for reports
• Target list upload (.txt file, one per line)

Authentication

Prefer XALGORIX_PASSWORD_HASH (bcrypt) for production deployments.

Bulk Scan Management

The Scans page supports row selection, select all, and bulk delete. You can also resume, restart, pause, or stop individual scans from the scan detail page.

WebSocket Status

The dashboard connects to ws://127.0.0.1:9137/ws for live events. If the connection drops, the dashboard shows a disconnection indicator and automatically reconnects.

CLI Reference

Complete command-line flag reference for Xalgorix.

Usage

Flags

Examples

Service Mode

Install Xalgorix as a systemd service for persistent operation:

View logs: journalctl -u xalgorix -f

Service commands: --stop, --restart, --uninstall

Scan Modes

Xalgorix supports three scan modes for different testing scenarios.

Single Target

Tests the exact target you provide. Best for a known URL or host. Runs the full 22-phase methodology against one target.

DAST

Dynamic Application Security Testing. Browser-driven testing for web applications, authentication flows, forms, and runtime behavior.

Wildcard / Multi-target

Enumerates subdomains and scans each discovered target individually. The most comprehensive mode.

When to Use Each Mode

Safety Considerations

• Wildcard scans can generate significant traffic — configure rate limits appropriately
• DAST scans use browser automation — ensure Chrome/Chromium is available
• Multi-target scans may take hours — use the service mode for long-running scans

Findings

How findings are created, classified, and managed in Xalgorix.

How Findings are Created

Findings are created when the agent calls the report_vulnerability tool during a scan. The agent must provide exploitation proof, CVSS score, and verification method. Findings without manual verification are rejected by the finish gatekeeper hook.

Severity Model

Evidence

Each finding includes:

• Exploitation proof (command output, HTTP request/response)
• Verification method (exploited, time_based, error_based, reflected, etc.)
• CVSS 3.1 vector string
• Affected endpoint and parameter
• Remediation guidance

Finding Lifecycle

1. Discovered — Agent detects a potential vulnerability
2. Verified — Agent confirms with exploitation proof
3. Reported — Agent calls report_vulnerability
4. Included in Report — Finding appears in PDF report

False Positives

The agent is instructed to verify findings manually before reporting. Scanner-only findings without manual exploitation proof are rejected. However, false positives may still occur. Review findings critically and verify independently.

Best Practices

• Review all findings in the dashboard after scan completion
• Verify critical findings independently before including in reports
• Use severity filters in the dashboard to focus on high-impact findings
• Export findings via PDF report for client delivery

Reports

PDF report generation, contents, branding, and export.

PDF Report Generation

Reports are generated as PDF files using the go-pdf/fpdf library. They are created when a scan completes and are available from the scan detail page and the Reports page.

Report Contents

• Executive Summary — Vulnerability counts by severity
• Target and Scan Metadata — Target URL, scan date, mode, model used
• Severity and CVSS Overview — Distribution chart
• Verified Findings — Each finding with CVSS score, evidence, PoC, and remediation
• Technical Analysis — Detailed exploitation steps
• Proof of Concept — Commands, scripts, or HTTP requests
• Remediation Guidance — Recommended fixes per finding

Branding

You can customize reports with:

• Company/Target name — Appears on cover page and headers
• Logo — Upload via Settings or POST /api/upload-logo

Logos are stored in ~/xalgorix-data/logos/.

Downloading Reports

Storage

Reports are stored at:

Troubleshooting PDF Generation

Environment Variables

Complete reference for all Xalgorix configuration variables.

Config File Location

Xalgorix loads configuration from these files (in order, later files override):

1. /etc/xalgorix.env
2. /home/<sudo-user>/.xalgorix.env (when launched through sudo)
3. ~/.xalgorix.env
4. Environment variables already present in the process

Required Variables

LLM Settings

Web and Security

Integrations

Rate Limits and Proxy

Runtime and Browser

Telemetry

Full Example Config

LLM Providers

Supported providers, configuration, and troubleshooting.

Supported Providers

When XALGORIX_API_BASE is empty, Xalgorix infers the API endpoint from the model prefix:

Custom OpenAI-Compatible Endpoints

Any provider that exposes an OpenAI-compatible /v1/chat/completions endpoint works.

Provider-Specific Notes

OpenAI

Uses the standard /v1/chat/completions endpoint with Bearer token auth. Supports streaming.

Anthropic

Uses /v1/messages endpoint with x-api-key header. Max tokens set to 8192. System prompt is passed as a top-level field.

Google Gemini

Uses /v1beta/models/MODEL:generateContent (or streamGenerateContent for streaming). Auth via x-goog-api-key header. GEMINI_API_KEY enables web search enrichment separately.

Ollama (Local)

Runs entirely locally. Requires Ollama installed and a model pulled. Set XALGORIX_LLM=ollama/<model-name>. No API key needed for local Ollama, but set XALGORIX_API_KEY=dummy to pass validation.

Troubleshooting Provider Errors

Rate Limits

Configuring rate limits for the dashboard API and outbound requests.

Dashboard Rate Limits

The Web UI API has built-in rate limiting to prevent abuse:

WebSocket connections, static files, and dashboard read operations (GET requests for scan lists, status, etc.) are exempt from rate limiting.

Outbound Request Rate Limits

Controls how fast Xalgorix sends requests to target systems:

These are enforced by the internal rate limiter using a token bucket algorithm. Adjust based on your engagement rules and target capacity.

LLM Provider Rate Limits

When the LLM provider returns HTTP 429 (rate limited), Xalgorix waits 30 minutes before retrying. This is intentional — it avoids burning through retries and respects provider limits. The scan automatically resumes after the wait.

Integrations

External service integrations for notifications, email, and proxy.

Discord Alerts

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

The XALGORIX_DISCORD_MIN_SEVERITY variable filters alerts. Set to high to only receive High and Critical findings. Valid values: critical, high, medium, low, info.

AgentMail

AgentMail provides temporary email inboxes for testing sign-up flows, email verification, and OTP flows. The agent can create inboxes, receive verification emails, and complete registration flows automatically.

Usage in custom instructions: the agent uses the agentmail tool to create inboxes and wait for emails during authenticated testing workflows.

Caido Proxy

Integration with Caido for HTTP request capture and replay during scans.

Set CAIDO_PORT=0 (default) for auto-detection.

Testing Integrations

Methodology

Xalgorix organizes testing into 22 phases. Phases can be selected individually per scan from the dashboard.

Phase List

Phase Selection

The dashboard lets you select which phases to run. This is useful for:

• Recon-only scans — Select only Phase 1 and 22 (report)
• Injection-focused scans — Select Phases 1, 2, 5, 6, 20, 22
• Full methodology — Leave all phases selected (default)

How Phase Progress Appears in Dashboard

The Scan Detail page shows phase progress as the scan runs. Each phase is tracked based on the agent's tool calls and actions. The progress indicator shows which phase is currently active and which phases have been completed.

Tools

Xalgorix includes 14 built-in agent tools and supports 85+ external security tools.

Built-in Agent Tools

External Security Tools

Xalgorix can invoke 85+ external tools through the terminal_execute tool. These are organized by category:

Recon & Subdomain Enumeration (15)

subfinder, findomain, assetfinder, dnsx, amass, gospider, katana, hakrawler, gau, waybackurls, paramspider, crt.sh, bufferover, webarchive, shuffledns

HTTP & Scanning (15)

httpx, nuclei, gobuster, ffuf, feroxbuster, dirsearch, dirb, nikto, wfuzz, whatweb, wappalyzer, builtwith, wpscan, joomscan, cmsmap

Exploitation (15)

sqlmap, nmap, masscan, naabu, arp-scan, netdiscover, responder, impacket, secretdump, evilwinrm, hydra, medusa, john, hashcat, crackmapexec

Information Gathering (10)

theHarvester, metagoofil, spiderfoot, recon-ng, maltego, gh, git-dumper, gittools, trufflehog, gitleaks

Security Scanning (10)

zaproxy, burpsuite, semgrep, bandit, brakeman, gosec, sonarqube, owasp-zap, mitmproxy, sslyze

WAF & Protection (5)

wafw00f, whatwaf, bountycheck, subjack, nuclei-templates

Utilities (15)

curl, wget, jq, git, python3, pip, scrapling, xurl, qsreplace, unfurl, anew, gron, httprobe, httpx, notify

Auto-Install

When XALGORIX_ALLOW_AUTO_INSTALL is enabled (default for root), missing tools are automatically installed via the appropriate package manager:

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

Architecture

Technical overview of Xalgorix's internal components and data flow.

Components

Data Flow

User Input (Dashboard / CLI)
    │
    ▼
Go Backend (HTTP + WebSocket)
    │
    ▼
Agent Engine
    │
    ├──► LLM Client ──► Provider API (OpenAI / Anthropic / etc.)
    │         │
    │         ▼
    │    Response + Tool Calls
    │
    ├──► Tool Registry ──► Built-in Tools (browser, terminal, notes, ...)
    │         │
    │         └──► External Tools (nmap, nuclei, sqlmap, ...)
    │
    ├──► Hooks (stuck detection, finish gating, WAF detection, ...)
    │
    ▼
Findings ──► PDF Report Generator ──► report.pdf
    │
    ├──► Discord Webhook (if configured)
    │
    └──► Dashboard (via WebSocket events)

Data Storage

Scan data is stored on disk so the dashboard can recover after refresh or restart.

Skills Directory

Skills are loaded from the embedded filesystem or the local skills directory. The read_skill tool injects skill content into the agent's context.

API Reference

REST API endpoints for programmatic control of Xalgorix.

Scan Endpoints

Instance Endpoints

Upload Endpoints

Settings Endpoints

Queue Endpoints

Auth Endpoints

Other Endpoints

Authentication

When XALGORIX_USERNAME and XALGORIX_PASSWORD (or XALGORIX_PASSWORD_HASH) are configured, all API endpoints require authentication. Login via POST /api/auth/login with a JSON body:

Error Format

HTTP status codes: 200 (success), 400 (bad request), 401 (unauthorized), 404 (not found), 429 (rate limited), 500 (server error).

WebSocket Events

Real-time event streaming via WebSocket for live scan monitoring.

Connection

The WebSocket endpoint is at /ws. No authentication is required for WebSocket connections when the dashboard is on localhost (loopback binding).

Event Types

Event Payload Example

Reconnect Behavior

The dashboard frontend automatically reconnects if the WebSocket connection drops. A disconnection indicator is shown while reconnecting. Events that occur during disconnection are buffered server-side and can be retrieved via GET /api/instances/:id/events.

Example Client

Troubleshooting

Common issues and their solutions.

Installation Issues

Dashboard Issues

Scan Issues

Integration Issues

Permission Issues

FAQ

Frequently asked questions about Xalgorix.

Is Xalgorix free?

Yes. Xalgorix is open-source under the MIT license. There are no SaaS fees, per-scan charges, or usage limits. You pay only for your LLM provider API usage.

Is it self-hosted?

Yes. Xalgorix runs entirely on your machine. No data is sent to external services except the configured LLM provider API.

Does it require an API key?

Yes. You need an API key from a supported LLM provider (OpenAI, Anthropic, DeepSeek, Groq, Google, MiniMax). Ollama can run locally without an API key — set XALGORIX_API_KEY=dummy to pass validation.

Which LLMs are supported?

OpenAI, Anthropic, DeepSeek, Groq, Google Gemini, Ollama (local), MiniMax, and any custom OpenAI-compatible endpoint. See LLM Providers.

Can I use local models?

Yes, via Ollama. Install Ollama, pull a model (e.g., ollama pull llama3), and set XALGORIX_LLM=ollama/llama3. Local models may produce lower quality results than cloud models for security testing tasks.

Can I use it for bug bounty?

Yes. Xalgorix is designed for authorized testing workflows including bug bounty. Use custom instructions to follow program rules and scope restrictions.

Does it replace manual testing?

No. Xalgorix assists with structured testing workflows, but findings should be verified manually. It does not guarantee finding every vulnerability.

Is the dashboard safe to expose publicly?

The dashboard binds to 127.0.0.1 by default. To expose it externally, you must configure authentication (XALGORIX_USERNAME and XALGORIX_PASSWORD). Use XALGORIX_PASSWORD_HASH (bcrypt) for production. Consider using a reverse proxy with TLS for external access.

Can it resume scans?

Yes. The dashboard supports pause, resume, restart, and stop actions on running scans. Scan state is persisted to disk.

Does it generate reports?

Yes. PDF reports are generated automatically when a scan completes. Reports include executive summary, findings with CVSS scores, exploitation proof, and remediation guidance. Reports support custom branding.

What platforms are supported?

Linux is the primary platform. macOS and Windows (via WSL) are also supported. Docker support is not currently available.

How accurate are findings?

The agent is instructed to verify findings with exploitation proof before reporting. Scanner-only findings without manual verification are rejected. However, false positives may occur. Always verify findings independently.

Contributing

How to contribute to Xalgorix development and documentation.

Development Setup

Project Structure

Adding Tools

Tools are registered in internal/tools/. Each tool has a Register function that adds it to the global registry. To add a new tool:

1. Create a new package under internal/tools/
2. Implement the Tool struct with Name, Description, Parameters, and Execute function
3. Call reg.Register() in your Register function
4. Call your Register function from agent.go

Adding LLM Providers

LLM provider support is in internal/llm/client.go. The resolveEndpoint method handles provider detection and URL construction. To add a new provider:

1. Add the provider's API base to the providerBases map
2. Add any special request/response handling in doChat and ChatStream
3. Update the provider prefix documentation

Running Tests

Submitting PRs

• Fork the repository and create a feature branch
• Write tests for new functionality
• Ensure go test ./... passes
• Run go vet ./... and go mod tidy
• Submit a pull request with a clear description

Reporting Issues

Report bugs and feature requests at github.com/xalgord/xalgorix/issues.

Changelog

Version history and notable changes.

v4.4.1 (Current)

• Current stable release
• 22-phase methodology with selectable phases
• Web dashboard with live feed, scan management, and settings
• Multi-provider LLM support (8 providers + custom endpoints)
• AgentMail integration for email verification flows
• Discord webhook notifications
• PDF report generation with branding
• Resource-aware instance limits
• Loopback-only binding with authentication for external access
• Auto-update check (throttled to 6 hours)
• Systemd service mode
• Proxy support with rotation

Breaking Changes