Troubleshooting

Common issues encountered when using Vigolium and their solutions.

WAF/Rate Limiting Blocking Scans

Symptoms: Many requests return 403/429 status codes, scan results are incomplete, or the target becomes unresponsive.

Solutions:

Reduce concurrency to slow down request volume:

vigolium scan -t https://example.com -c 10

Apply a rate limit (requests 每 second):

vigolium scan -t https://example.com -r 50

Use the lite strategy, which uses fewer payloads and a less aggressive scanning profile:

vigolium scan -t https://example.com --strategy lite

You can combine these options for heavily protected targets:

vigolium scan -t https://example.com --strategy lite -c 5 -r 20

Browser Not Found (Spidering)

Symptoms: Spidering phase fails with errors about missing Chromium or browser binary.

Solutions:

Chromium is automatically downloaded on first use to ~/.cache/spitolas/chromium-<version>/. If this download is blocked by network restrictions:

1. Use make deps-chrome to build with an embedded Chromium binary.
2. Alternatively, skip the spidering phase entirely:

vigolium scan -t https://example.com --skip spidering

Scope Mismatch (No Results)

Symptoms: 扫描 completes but produces zero findings or skips all requests.

Solutions:

Verify the target URL matches 配置的 scope. The scanner only tests URLs that fall within the defined scope.

Check 当前 scope configuration:

vigolium project config

Explicitly set the scope to include your target by updating the config:

vigolium config set scope.host.include "*.example.com"

Ensure the target URL scheme (http vs https) and hostname match what the scope expects. Subdomains are not included 默认情况下 unless a wildcard pattern is used.

OAST Not Working

Symptoms: No out-of-band findings are reported, even for vulnerabilities that typically produce OAST（带外交互） interactions (e.g., blind SSRF, blind XXE).

Solutions:

OAST（带外交互） requires outbound DNS and HTTP connectivity from the target application to the OAST（带外交互） callback server. 检查:

1. The scanned application can make outbound DNS queries.
2. The scanned application can make outbound HTTP requests.
3. No firewall rules block these outbound connections.

OAST（带外交互） is optional. The scanner still produces findings without it using in-band detection methods. OAST（带外交互） adds an extra layer of detection for blind/out-of-band vulnerabilities, but its absence does not prevent the scanner from working.

High Memory Usage on Large Targets

Symptoms: The scanner process consumes excessive memory, the system becomes slow, or the process is killed by the OS.

Solutions:

Use the lite strategy to reduce the number of payloads and checks:

vigolium scan -t https://example.com --strategy lite

Run only the dynamic-assessment phase to skip discovery and spidering, which can generate large numbers of URLs:

vigolium scan -t https://example.com --only dynamic-assessment

Reduce concurrency to limit the number of in-flight requests and queued items:

vigolium scan -t https://example.com -c 5

Skip discovery to avoid large wordlist-based scans that produce many URLs:

vigolium scan -t https://example.com --skip discovery

Scan Takes Too Long

Symptoms: 扫描 runs for hours without completing, or appears stuck in a particular phase.

Solutions:

Use the lite strategy for faster scans with fewer checks:

vigolium scan -t https://example.com --strategy lite

Limit discovery time to prevent long-running content discovery:

vigolium scan -t https://example.com --discover-max-time 5m

Limit spidering time:

vigolium scan -t https://example.com --spider-max-time 5m

Run only the dynamic-assessment phase if you already have traffic recorded:

vigolium scan -t https://example.com --only dynamic-assessment

Combine options for the fastest possible scan:

vigolium scan -t https://example.com --strategy lite --skip discovery --skip spidering

Database Issues

Symptoms: Errors related to database access, corrupted data, or migration failures.

Solutions:

The default database is SQLite, stored at ~/.vigolium/vigolium.db.

To switch to a different database location:

vigolium scan --target https://example.com --db /path/to/other.db

要重置 the database and start fresh:

vigolium db clean

For production deployments, consider using PostgreSQL 而不是 SQLite. Configure the database connection in vigolium-configs.yaml or 通过 the --db flag with a PostgreSQL connection string.

Agent Mode Not Working

Symptoms: vigolium agent commands fail with errors about missing backends, connection issues, or authentication failures.

Solutions:

1. Check backend configuration. Agent backends are configured in the agent section of vigolium-configs.yaml. The default backend (claude) uses the SDK protocol and requires the claude CLI in PATH:

agent:
  default_agent: claude
  backends:
    claude:
      command: claude
      protocol: sdk

1. Ensure the coding agent CLI is installed. The default claude backend requires the Claude Code CLI. Other backends require their respective CLIs:

# Verify Claude CLI is available
claude --version

1. Check API keys. Ensure the required API keys are set as environment variables (e.g., ANTHROPIC_API_KEY for Claude, OPENAI_API_KEY for Codex).

2. Verify session directory permissions. Agent sessions are stored under ~/.vigolium/agent-sessions/ 默认情况下 (configurable 通过 agent.sessions_dir in vigolium-configs.yaml). Ensure this directory is writable.

Permission Denied on Build

Symptoms: make build or make install fails with permission errors when writing to $GOPATH/bin.

Solutions:

Ensure $GOPATH/bin exists and is writable:

mkdir -p "$(go env GOPATH)/bin"
chmod u+w "$(go env GOPATH)/bin"

Always use make build 而不是 go build. Direct go build bypasses version injection and may produce incorrect binaries:

# Correct
make build

# Incorrect - do not use
go build -o vigolium .

The make build command outputs the binary to bin/vigolium and installs it to $GOPATH/bin. If you only need the binary locally without installation, the built binary is available at bin/vigolium after running make build.