Xalgorix

https://docs.xalgorix.com
Admin
Xalgorix is a self-hosted, open-source AI security testing platform for authorized penetration...
Tokens:9,033
Snippets:151
Trust Score:4.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Xalgorix via Go

Source: https://docs.xalgorix.com/

Downloads and installs the latest pre-built binary including the embedded Web UI.

```bash
GOPROXY=direct GOSUMDB=off go install github.com/xalgord/xalgorix/v4/cmd/xalgorix@latest
```

--------------------------------

### Install Go on Linux

Source: https://docs.xalgorix.com/

Downloads and configures the Go environment manually.

```bash
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 Go on macOS

Source: https://docs.xalgorix.com/

Installs Go using the Homebrew package manager.

```bash
brew install go
```

--------------------------------

### Example Configuration File

Source: https://docs.xalgorix.com/

A template for the ~/.xalgorix.env file demonstrating required and optional configuration settings.

```bash
# ~/.xalgorix.env  # Required XALGORIX_LLM=openai/gpt-4.1 XALGORIX_API_KEY=sk-your-key  # Optional — Custom API endpoint # XALGORIX_API_BASE=https://api.openai.com/v1  # Optional — Web search GEMINI_API_KEY=AIza...  # Optional — Discord alerts XALGORIX_DISCORD_WEBHOOK=https://discord.com/api/webhooks/... XALGORIX_DISCORD_MIN_SEVERITY=high  # Optional — AgentMail AGENTMAIL_POD=am_us_pod_47 AGENTMAIL_API_KEY=ak_...  # Optional — Dashboard auth XALGORIX_USERNAME=admin XALGORIX_PASSWORD=change-this-password  # Optional — Rate limiting XALGORIX_RATE_LIMIT_REQUESTS=60 XALGORIX_RATE_LIMIT_WINDOW=60
```

--------------------------------

### Install Built Binary System-wide

Source: https://docs.xalgorix.com/

Moves the compiled binary to the system path.

```bash
sudo install -m 755 build/xalgorix /usr/local/bin/xalgorix
```

--------------------------------

### Initialize Development Environment

Source: https://docs.xalgorix.com/

Commands to clone the repository, install dependencies, build the project, and run the application or tests.

```bash
# Clone the repository git clone https://github.com/xalgord/xalgorix.git cd xalgorix  # Install Web UI dependencies make webui-install  # Build everything (Web UI + Go binary) make build  # Run tests go test ./...  # Run from source go run ./cmd/xalgorix --web  # Run frontend dev server only make webui-dev
```

--------------------------------

### Verify Xalgorix Installation

Source: https://docs.xalgorix.com/

Checks the currently installed version of Xalgorix.

```bash
xalgorix --version
```

--------------------------------

### Launch Xalgorix Dashboard

Source: https://docs.xalgorix.com/

Starts the web interface on the default port.

```bash
xalgorix --web
```

--------------------------------

### Start the Xalgorix Web Dashboard

Source: https://docs.xalgorix.com/

Commands to launch the web interface with optional port and binding configurations.

```bash
xalgorix --web
```

```bash
xalgorix --web --port 8080
```

```bash
XALGORIX_USERNAME=admin XALGORIX_PASSWORD=change-this xalgorix --web --bind 0.0.0.0
```

--------------------------------

### Start Ollama Service

Source: https://docs.xalgorix.com/

Command to initialize the local Ollama server for local model execution.

```bash
ollama serve
```

--------------------------------

### System Service Management

Source: https://docs.xalgorix.com/

Commands for installing and managing Xalgorix as a systemd service.

```bash
sudo xalgorix --start
```

--------------------------------

### CLI Execution Examples

Source: https://docs.xalgorix.com/

Common command patterns for running scans, configuring the Web UI, and managing system services.

```bash
# Web UI on default port xalgorix --web  # Web UI on custom port xalgorix --web --port 8080  # Scan a single target xalgorix --target https://example.com  # Multiple targets xalgorix --target https://a.com --target https://b.com  # Custom model and instructions xalgorix --target https://app.example.com \   --model anthropic/claude-sonnet-4-20250514 \   --instruction "Focus on API vulnerabilities"  # Service mode sudo xalgorix --start sudo xalgorix --stop sudo xalgorix --restart xalgorix --uninstall
```

--------------------------------

### GET /api/status

Source: https://docs.xalgorix.com/

Get current global status.

```APIDOC
## GET /api/status

### Description
Get current global status.

### Method
GET

### Endpoint
/api/status
```

--------------------------------

### WebSocket Client Implementation

Source: https://docs.xalgorix.com/

Basic client setup to connect to the WebSocket, parse incoming messages, and handle disconnection events.

```javascript
const ws = new WebSocket("ws://127.0.0.1:9137/ws"); ws.onmessage = (event) => {   const data = JSON.parse(event.data);   console.log(`[${data.type}]`, data.content || data.toolName); }; ws.onclose = () => console.log("Disconnected — will auto-reconnect");
```

--------------------------------

### POST /api/scan

Source: https://docs.xalgorix.com/

Start or save a scan.

```APIDOC
## POST /api/scan

### Description
Start or save a scan.

### Method
POST

### Endpoint
/api/scan
```

--------------------------------

### GET /api/scans/:id

Source: https://docs.xalgorix.com/

Get detail for a specific scan.

```APIDOC
## GET /api/scans/:id

### Description
Get detail for a specific scan.

### Method
GET

### Endpoint
/api/scans/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the scan.
```

--------------------------------

### GET /api/scans

Source: https://docs.xalgorix.com/

List all scans.

```APIDOC
## GET /api/scans

### Description
List all scans.

### Method
GET

### Endpoint
/api/scans
```

--------------------------------

### GET /api/report/:id

Source: https://docs.xalgorix.com/

Download a PDF report for a scan.

```APIDOC
## GET /api/report/:id

### Description
Download a PDF report for a scan.

### Method
GET

### Endpoint
/api/report/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the scan.
```

--------------------------------

### WebSocket Event Payload Structure

Source: https://docs.xalgorix.com/

Example JSON structure for a tool_call event received over the WebSocket.

```json
{   "type": "tool_call",   "toolName": "terminal_execute",   "toolArgs": {"command": "nmap -sV -sC --top-ports 200 example.com"},   "agentId": "agent_1715784000000000000",   "timestamp": "2026-05-14T12:00:00Z",   "totalTokens": 15420 }
```

--------------------------------

### Build Xalgorix from Source

Source: https://docs.xalgorix.com/

Clones the repository and builds the React Web UI and Go binary.

```bash
git clone https://github.com/xalgord/xalgorix.git cd xalgorix make build
```

--------------------------------

### Basic CLI Usage

Source: https://docs.xalgorix.com/

Commands for launching the Web UI or initiating a scan.

```bash
xalgorix --web                  # Start Web UI (port 9137) xalgorix --target <url>         # Run CLI scan
```

--------------------------------

### Execute Test Suites

Source: https://docs.xalgorix.com/

Commands for running Go tests with various flags and CI configurations.

```bash
# All tests go test ./...  # With coverage go test ./... -cover  # With race detector go test ./... -race  # Full CI pipeline make test-ci
```

--------------------------------

### Configure Environment Variables

Source: https://docs.xalgorix.com/

Commands to edit the configuration file and set the required LLM provider and API key.

```bash
nano ~/.xalgorix.env
```

```bash
XALGORIX_LLM=openai/gpt-4.1 XALGORIX_API_KEY=sk-your-api-key
```

--------------------------------

### Configure Custom OpenAI-Compatible Endpoint

Source: https://docs.xalgorix.com/

Set environment variables to connect to any provider exposing an OpenAI-compatible /v1/chat/completions endpoint.

```bash
XALGORIX_LLM=custom/security-model XALGORIX_API_BASE=https://your-provider.example/v1 XALGORIX_API_KEY=your_provider_api_key
```

--------------------------------

### Update Xalgorix

Source: https://docs.xalgorix.com/

Updates the binary via the built-in command or by reinstalling via Go.

```bash
# Self-update from the binary xalgorix --update  # Or reinstall via Go GOPROXY=direct GOSUMDB=off go install github.com/xalgord/xalgorix/v4/cmd/xalgorix@latest
```

--------------------------------

### Project Directory Structure

Source: https://docs.xalgorix.com/

Overview of the Xalgorix source code organization.

```text
xalgorix/ ├── cmd/xalgorix/           # CLI entry point │   └── main.go             # Argument parsing, service management ├── internal/ │   ├── agent/              # Core agent loop, hooks, system prompt │   ├── config/             # Configuration loading │   ├── llm/                # Multi-provider LLM client │   ├── proxy/              # Proxy routing │   ├── ratelimit/          # Rate limiting │   ├── resources/          # Resource-aware limits │   ├── scanctx/            # Per-session scan context │   ├── tools/              # Built-in tools │   │   ├── terminal/       # Shell command execution │   │   ├── browser/        # Headless Chrome (rod) │   │   ├── pageagent/      # Page-level JS execution │   │   ├── fileedit/       # File creation/editing │   │   ├── notes/          # Note-taking tool │   │   ├── reporting/      # Vulnerability reporting │   │   ├── finish/         # Scan completion │   │   ├── python/         # Python script execution │   │   ├── websearch/      # Web search │   │   ├── agentmail/      # Email integration │   │   ├── agentsgraph/    # Sub-agent spawning │   │   └── skills/         # Skill loading │   ├── web/                # HTTP server, WebSocket, API │   │   ├── server.go       # Main server │   │   ├── autonomous.go   # Scan orchestration │   │   ├── report.go       # Report generation │   │   ├── settings_env.go # Environment settings │   │   └── static/         # Embedded Web UI assets │   └── tui/                # Terminal UI (banner) ├── webui/                  # React Web UI source ├── docs/                   # Internal docs └── tools.md                # Supported tools list
```

--------------------------------

### Execute a CLI scan with custom instructions

Source: https://docs.xalgorix.com/

Provides specific testing focus and constraints to the agent during the scan process.

```bash
xalgorix --target https://app.example.com \   --instruction "Focus on SQL injection, IDOR, and auth bypass. Avoid destructive tests."
```

--------------------------------

### Authenticate with Xalgorix API

Source: https://docs.xalgorix.com/

Use this request to authenticate when XALGORIX_USERNAME and XALGORIX_PASSWORD are configured.

```bash
curl -X POST http://127.0.0.1:9137/api/auth/login \
   -H "Content-Type: application/json" \
   -d '{"username":"admin","password":"your-password"}'
```

--------------------------------

### Configure Dashboard Authentication

Source: https://docs.xalgorix.com/

Environment variables for setting dashboard credentials in the configuration file.

```bash
# ~/.xalgorix.env
XALGORIX_USERNAME=admin
XALGORIX_PASSWORD=your-secure-password
```

--------------------------------

### Uninstall Xalgorix

Source: https://docs.xalgorix.com/

Removes the binary and systemd service, while preserving data directories.

```bash
xalgorix --uninstall
```

--------------------------------

### Execute a basic CLI scan

Source: https://docs.xalgorix.com/

Initiates a scan against a specified target URL using the command line interface.

```bash
xalgorix --target https://your-target.example.com
```

--------------------------------

### Configure Discord Webhook

Source: https://docs.xalgorix.com/

Set the webhook URL and minimum severity level for Discord notifications in the environment file.

```bash
# ~/.xalgorix.env XALGORIX_DISCORD_WEBHOOK=https://discord.com/api/webhooks/... XALGORIX_DISCORD_MIN_SEVERITY=high
```

--------------------------------

### POST /api/auth/login

Source: https://docs.xalgorix.com/

Authenticate with username and password.

```APIDOC
## POST /api/auth/login

### Description
Authenticate with username and password.

### Method
POST

### Endpoint
/api/auth/login

### Request Body
- **username** (string) - Required
- **password** (string) - Required
```

--------------------------------

### Configure Caido Proxy

Source: https://docs.xalgorix.com/

Set the Caido port and API token for HTTP request capture and replay.

```bash
# ~/.xalgorix.env CAIDO_PORT=8080 CAIDO_API_TOKEN=your-caido-token
```

--------------------------------

### Xalgorix System Architecture Diagram

Source: https://docs.xalgorix.com/

Visual representation of the Xalgorix stack, spanning from the user interface layer down to external tool integrations.

```text
┌──────────────────────────────────────────────────────────────┐
│                        USER LAYER                            │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────────┐  │
│  │  Web UI  │  │   CLI    │  │ REST API │  │  Discord   │  │
│  │Dashboard │  │ Terminal │  │ Endpoints│  │  Webhook   │  │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └─────┬──────┘  │
└───────┼──────────────┼────────────┼───────────────┼─────────┘
        └──────────────┼────────────┼───────────────┘
                       ▼            ▼
┌──────────────────────────────────────────────────────────────┐
│                        CORE LAYER                            │
│  ┌─────────────────────────────────────────────────────┐     │
│  │  Go Backend (HTTP + WebSocket + Queue + Config)     │     │
│  └────────────────────────┬────────────────────────────┘     │
│  ┌────────────────────────┼────────────────────────────┐     │
│  │  Agent Engine (LLM Client + Tool Executor + Hooks)  │     │
│  └────────────────────────┼────────────────────────────┘     │
└───────────────────────────┼──────────────────────────────────┘
                            ▼
┌──────────────────────────────────────────────────────────────┐
│                        TOOL LAYER                            │
│  terminal │ browser │ pageagent │ python │ websearch │ notes │
│  reporting│ finish  │ fileedit  │ proxy  │ agentmail │ skills│
│           │ agentsgraph (sub-agent spawning)                 │
└──────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌──────────────────────────────────────────────────────────────┐
│                   EXTERNAL TOOLS (85+)                       │
│  subfinder │ nuclei │ nmap │ sqlmap │ ffuf │ httpx │ ...    │
└──────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌──────────────────────────────────────────────────────────────┐
│                   INTEGRATION LAYER                          │
│  OpenAI │ Anthropic │ DeepSeek │ Groq │ Gemini │ Ollama     │
│  MiniMax │ Discord │ AgentMail │ Caido │ Custom endpoints   │
└──────────────────────────────────────────────────────────────┘
```

--------------------------------

### Configure AgentMail

Source: https://docs.xalgorix.com/

Define the AgentMail pod and API key in the environment file to enable temporary inbox functionality.

```bash
# ~/.xalgorix.env AGENTMAIL_POD=am_us_pod_47 AGENTMAIL_API_KEY=ak_...
```

--------------------------------

### Download Report via API

Source: https://docs.xalgorix.com/

Command to download a generated PDF report for a specific scan ID.

```bash
curl http://127.0.0.1:9137/api/report/{scan-id} -o report.pdf
```

--------------------------------

### Test Discord Webhook

Source: https://docs.xalgorix.com/

Verify the Discord integration by sending a test message using curl.

```bash
# Test Discord webhook curl -X POST "$XALGORIX_DISCORD_WEBHOOK" \   -H "Content-Type: application/json" \   -d '{"content": "Test alert from Xalgorix"}'
```

--------------------------------

### Remove Xalgorix Data

Source: https://docs.xalgorix.com/

Deletes configuration, skills, and scan data directories.

```bash
rm -rf ~/.xalgorix ~/xalgorix-data
```

--------------------------------

### WebSocket Connection Endpoint

Source: https://docs.xalgorix.com/

The default WebSocket URL used by the dashboard for real-time event streaming.

```text
ws://127.0.0.1:9137/ws
```

--------------------------------

### WebSocket Connection

Source: https://docs.xalgorix.com/

The WebSocket endpoint provides real-time event streaming. No authentication is required when the dashboard is accessed via localhost.

```APIDOC
## WebSocket /ws

### Description
Connect to the WebSocket server to receive real-time scan events. The connection is unauthenticated when using loopback binding.

### Endpoint
ws://127.0.0.1:9137/ws

### Event Types
- **thinking**: Agent iteration start. Fields: content (iteration number), totalTokens.
- **tool_call**: Tool execution start. Fields: toolName, toolArgs.
- **tool_result**: Tool execution result. Fields: toolName, toolResult.output, toolResult.error.
- **message**: Agent text message. Fields: content, totalTokens.
- **error**: Error event. Fields: content (error description).
- **finished**: Scan completed. Fields: content (summary).

### Response Example
{
  "type": "tool_call",
  "toolName": "terminal_execute",
  "toolArgs": {"command": "nmap -sV -sC --top-ports 200 example.com"},
  "agentId": "agent_1715784000000000000",
  "timestamp": "2026-05-14T12:00:00Z",
  "totalTokens": 15420
}
```

--------------------------------

### POST /api/stop

Source: https://docs.xalgorix.com/

Stop all running scans.

```APIDOC
## POST /api/stop

### Description
Stop all running scans.

### Method
POST

### Endpoint
/api/stop
```

--------------------------------

### API Error Response Format

Source: https://docs.xalgorix.com/

Standard JSON structure returned when an API request fails.

```json
{"error": "description of the error"}
```

--------------------------------

### Upload Logo API

Source: https://docs.xalgorix.com/

Endpoint for uploading a custom logo to be used in generated reports.

```http
POST /api/upload-logo
```

--------------------------------

### DELETE /api/scans/:id

Source: https://docs.xalgorix.com/

Delete a scan and its report data.

```APIDOC
## DELETE /api/scans/:id

### Description
Delete a scan and its report data.

### Method
DELETE

### Endpoint
/api/scans/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the scan.
```
Tokens:
Raw