Argus User Guide

中文文档

This guide covers everything you need to use Argus effectively — from configuration and the Web Console to prompt extensions, report interpretation, and troubleshooting.

Configuration
Web Console
Prompt Extension System
Browser Auth State Management
Reports & Execution
White-box Code Analysis
Black-white-box Correlation
Task Observability
Best Practices
Troubleshooting

Configuration

LLM Configuration

Argus needs an OpenAI Chat Completions-compatible LLM API. Configure it interactively:

argus config llm

This saves to the database (API key encrypted). You can manage multiple profiles later via the Web Console.

To verify connectivity:

argus llm check

Environment File Format

LLM_API_KEY=sk-your-key
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4o

Advanced Parameters

argus config llm --advanced

Additional settings: max tokens (default: 4096), temperature (default: 0), max retries (default: 3).

Server Configuration

Server settings live in config/server.yaml:

CORS origins — allowed frontend domains
Rate limiting — per-route request throttling
SSRF protection — allowed private LLM hosts
Observability — toggle request logging, audit, LLM traces
Scheduler concurrency — max concurrent tasks (default: 4)
WebSocket limits — max subscribers per event bus

Edit this file and restart argus serve for changes to take effect.

Model Configuration (via Web Console)

Multiple LLM provider configurations can be stored in SQLite with encrypted API keys:

Navigate to Models in the Web Console
Click Add Model and enter API endpoint, model name, and API key
Click Test Connection to verify
Assign the model config to a task when creating it

API keys are encrypted at rest using a Fernet key stored at config/.fernet_key. The key is auto-generated on first argus serve start.

Web Console

The Web Console is a Vue 3 SPA served by Argus at http://localhost:8000/ when running argus serve.

Building the Frontend

The frontend source is at frontend/. Build it before first launch:

cd frontend
pnpm install
pnpm build
cd ..
argus serve

After the initial build:

Python-only changes → just restart argus serve, no rebuild needed
Frontend changes → run pnpm build again, then restart argus serve

Pages

Dashboard

Shows an overview of projects and recent tasks with their status.

Projects

Manage test projects. Each project can have:

A name and description
Custom prompt extensions (see Prompt Extension System)
Associated tasks

Tasks

The task management center. Features:

Create task — set goal, URL, project association, model config, and prompt extensions
Task list — filter by status, project, search by goal; white-box tasks are listed with type whitebox
Task detail — tab layout depends on the task type:

Black-box tasks — three tabs:

Report Tab — View the HTML report inline with collapsible steps, screenshots, and issues.

Execution Timeline — See the full lifecycle: task created → queued → started → each Planner/Executor/Evaluator cycle → completed. Events stream in real-time via WebSocket. Persisted in SQLite's task_events table.

LLM Debug Tab — Inspect every LLM call made during the task:
- Phase, event, model, host, duration, token usage
- System Prompt
- Input Payload (full API request)
- Raw Response (full API response)
- Parsed Result (structured output after JSON parsing)
- Errors and parse failures
White-box tasks — an Analysis Report tab renders the analysis results (overview metrics, endpoints, interactive call graph viewer, findings, execution flows, feature clusters), plus a completeness banner and analyzer diagnostics panel; an Analysis Log tab shows the build/analysis progress. White-box tasks do not make LLM calls, so there is no LLM debug tab.

When a task has an associated correlation run, a Correlation tab shows endpoint evidence, finding evidence, and unmatched HTTP requests (see Black-white-box Correlation).

Models

Manage LLM provider configurations.

Prompt Extension System

Argus separates built-in prompts from user-defined business rules.

Architecture

Concatenation order:  Built-in → Project Extension → Task Extension

Built-in templates at argus_py/llm/prompts/ — hard contracts with input fields, output JSON schemas, and safety boundaries. Cannot be overridden.
Project extensions — custom rules stored in the project's parameters.prompt_extensions.{planner,evaluator}.
Task extensions — custom rules stored in the task's parameters.prompt_extensions.{planner,evaluator}, appended after project extensions.

Each marker (## 业务扩展 / ## Business Extensions) in the built-in templates serves as the insertion point for extensions.

Usage via CLI

argus run --goal "..." --url "..." \
  --planner-extension ./my-rules/planner.md \
  --evaluator-extension ./my-rules/evaluator.md

Usage via Web Console

In the Project or Task create/edit dialog, expand the Prompt Extensions panel:

Two tabs: Planner and Evaluator
Markdown editor on the left, rendered preview on the right
A Preview Full System Prompt button at the bottom calls POST /argus/api/prompts/preview (with 600ms debounce) to show the concatenated built-in + project + task prompt

Example Extensions

Planner extension (for a specific app):

## Project-Specific Rules
- Dangerous button keywords: void, withdraw, open-account
- Login page is always at /auth/signin
- Do not click elements with class "disabled"

Evaluator extension:

## Evaluation Rules
- A "success" notification must contain a green checkmark icon
- Page title must contain "Dashboard" after login

Browser Auth State Management

For testing pages behind authentication, save the login state once and reuse it across tasks.

Save State

argus auth save --url "https://example.com/login"

This opens a headed browser. Log in manually, then press Enter in the terminal. The state (cookies, localStorage, sessionStorage) is saved to config/browser-states/<name>.json.

List Saved States

argus auth list

Reuse State

argus run --auth-state example.com \
  --goal "Check profile page loads correctly" \
  --url "https://example.com/profile"

The --auth-state parameter accepts either a state name (looked up in config/browser-states/) or a direct JSON file path.

Auth states contain session credentials. They are gitignored but should still be treated as sensitive — do not share debug bundles containing them.

Reports & Execution

Execution Flow

Planner (LLM) receives the goal and page snapshot, decides the next browser action
Executor runs the action via Playwright, captures a screenshot and DOM snapshot
Evaluator (LLM) judges whether the goal is achieved
If not satisfied, loop back to step 1 with updated context
On action failure, recovery logic re-observes the page and re-plans (up to 2 retries)
When done (success or exhaustion), generate HTML + JSON reports

Report Output

outputs/reports/<task_id>/
├── index.html      # Human-readable HTML report
└── report.json     # Structured JSON report

HTML Report Features:

Task summary, execution steps, step parameters, screenshots, issues, and errors
Failed steps are highlighted
Step parameters and screenshots are collapsible
Screenshots can be clicked to enlarge
Screenshots referenced via relative paths where possible

JSON Report contains the same data in a machine-readable format, suitable for downstream tools or APIs.

Report API

GET /argus/api/tasks/{task_id}/report    → HTML (default) or JSON (?format=json)

Screenshots

Each execution step captures a screenshot by default. Stored at:

outputs/screenshots/<task_id>/

Disable with --no-screenshot. When disabled, the Planner can still emit screenshot actions, but they are logged as skipped without saving an image.

White-box Code Analysis

Beyond browser testing, Argus can statically analyze Java codebases. The Python control plane snapshots the source (Git clone or local copy), delegates parsing to the Java Analyzer service (Spring Boot + JavaParser + Maven classpath resolution), and renders the results as reports.

Prerequisites

A reachable Java Analyzer service — default http://localhost:8081, override with ARGUS_JAVA_ANALYZER_URL. With Docker Compose, start it via --profile java.
The source path must be visible to the analyzer process and inside the allowed source roots (container deployments share a source volume; see the deployment guide).
Maven classpath resolution improves precision; without Maven the analysis falls back to source-only mode.

Running an Analysis

# Full analysis of a Git repository
argus analyze --repo https://github.com/user/project.git

# Local directory, endpoints only
argus analyze --source-path /path/to/project --scope endpoints

Scopes: all (default, full analysis), changed (incremental changes), modules (specified Maven modules), endpoints, callgraph, flows, clusters. See the CLI reference for all options.

Understanding Results

Result	Description
Endpoints	REST mappings: path, HTTP method, controller class/method, parameters
Call graph	Method-level graph keyed by `className#methodName`
Findings	Rule-based findings with severity
Execution flows	Traced execution paths through the code
Clusters	Feature clustering of related classes
Diagnostics	Parse failures and per-pass failures/degradations

Optional passes (flows, clusters) degrade gracefully when they fail — degradations are recorded in the diagnostics and surfaced as a completeness warning in the report rather than failing the task.

Black-white-box Correlation

During black-box runs Argus captures HTTP request evidence (method, normalized path, status, timing) for every request the browser issues. Correlation runs match this evidence against the REST endpoints extracted by white-box analysis, linking UI behavior to server-side code paths.

How It Works

A correlation run is created for a black-box run and pinned to a desired source snapshot and analysis config
Once a white-box analysis is bound, captured HTTP requests are matched against extracted endpoints
Matching results are stored as endpoint evidence and finding evidence, with unmatched requests listed explicitly

Viewing Correlation Results

Web Console — tasks with a correlation run show a Correlation tab with endpoint evidence, finding evidence, and unmatched request tables
REST API — GET /argus/api/correlation-runs/{id} (plus summary, attempts, and evidence endpoints); bind or re-run matching via bind-analysis, retry, and recalculate

A correlation run is only as fresh as its bound source snapshot. If the analyzed source no longer matches what the black-box run exercised, the alignment status flags the mismatch instead of silently returning stale results.

Task Observability

Argus provides rich observability into task execution.

Execution Timeline

Every task lifecycle event is recorded in SQLite's task_events table:

Task created, queued, started, completed
Each Planner/Executor/Evaluator cycle
Browser actions and their results
Report generation

Get via API:

GET /argus/api/tasks/{task_id}/events

Or view in the Web Console's Execution Timeline tab (real-time via WebSocket).

LLM Call Traces

Every LLM invocation (Planner and Evaluator) is recorded with full context:

Phase, event type, model, host, duration, token usage
Full System Prompt
Input Payload (the API request body)
Raw Response (the API response body)
Parsed Result (after JSON extraction)
Errors and parse failures

Stored as JSONL:

outputs/traces/<task_id>.jsonl