Customizing & Extending Vigolium

Documentation Index

Fetch the complete documentation index at: https://docs.vigolium.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Table of Contents

• Extension Points at a Glance
• 1. JavaScript Extensions
• 2. YAML Extensions
• 3. Custom Prompt Templates
• 4. Scanning Profiles
• 5. Scope Rules
• 6. Pre-Hooks and Post-Hooks
• 7. Agent Providers (Olium)
• 8. Configuration Overrides
• Decision Matrix

​

Extension Points at a Glance

​

1. JavaScript Extensions

​

What you can build

• Active modules — send payloads to insertion points (parameters, headers, cookies, paths) and analyze responses for vulnerabilities.
• Passive modules — analyze captured HTTP traffic without generating new requests.
• Pre-hooks — mutate requests before they reach scanner modules (inject auth headers, skip paths).
• Post-hooks — filter, tag, or escalate findings after detection.

​

Minimal example (active module)

module.exports = {
  id: "reflected-param-scanner",
  name: "Reflected Parameter Scanner",
  type: "active",
  severity: "medium",
  confidence: "firm",
  scanTypes: ["per_insertion_point"],

  scanPerInsertionPoint: function(ctx, insertion) {
    var canary = "VGNM" + vigolium.utils.randomString(8);
    var resp = vigolium.http.send(insertion.buildRequest(canary));

    if (resp && resp.body.indexOf(canary) !== -1) {
      return [{
        matched: canary,
        url: ctx.request.url,
        name: "Reflected parameter: " + insertion.name,
        severity: "medium",
        request: insertion.buildRequest(canary),
        response: resp.raw
      }];
    }
    return null;
  }
};

​

Available APIs

​

Setup

# vigolium-configs.yaml
audit:
  extensions:
    enabled: true
    extension_dir: ~/.vigolium/extensions/
    variables:
      auth_token: "Bearer eyJ..."

​

Pros

• No recompilation — drop a file and scan.
• Full API access — HTTP, database, AI, source code, parsing, and system utilities.
• AI-augmented scanning — use vigolium.agent.generatePayloads() and vigolium.agent.analyzeResponse() for LLM-powered detection.
• Rapid iteration — edit, save, rescan.
• Sandboxed execution — file I/O constrained to sandbox_dir, exec() gated behind config.

​

Cons

• Slower than Go — interpreted JS engine adds overhead per invocation.
• No Go standard library — limited to vigolium.* APIs, no arbitrary imports.
• Single-threaded per VM — each extension instance runs in its own VM (thread-safe via pooling, but no parallelism within a single extension).
• Limited debugging — no step-through debugger, vigolium.log.* is your main tool.

​

When to use

• You need a custom vulnerability check and don’t want to recompile.
• You want AI-augmented payload generation or response analysis.
• You need database or source code access in your check logic.
• You’re building organization-specific checks (e.g., custom header validation, business-logic flaws).

​

2. YAML Extensions

​

Minimal example (active module)

id: error-pattern-detector
name: Error Pattern Detector
type: active
severity: low
confidence: firm
scan_types: [per_request]

payloads:
  - "'"
  - "\" OR 1=1--"

matchers:
  - type: body
    regex: "(?i)(SQL syntax|mysql_fetch|ORA-\\d{5}|SQLSTATE\\[)"
  - type: body
    regex: "(?i)(Traceback \\(most recent call last\\)|at \\w+\\.java:\\d+)"

matchers_condition: or

finding:
  name: "Error-Based Information Leak"
  description: "Application returns verbose error messages that reveal implementation details"
  severity: low

​

YAML hook example (pre-hook)

id: auth-header-injector
name: Auth Header Injector
type: pre_hook

add_headers:
  Authorization: "Bearer ${AUTH_TOKEN}"
  X-Request-ID: "vgm-{{random}}"

skip_when:
  url_contains: ["/health", "/metrics"]

​

YAML hook example (post-hook)

id: suppress-low-on-static
name: Suppress Low Findings on Static Assets
type: post_hook

drop_when:
  severity: [low, info]
  url_contains: ["/static/", "/assets/", ".css", ".js"]

escalate:
  when_url_contains: ["/admin", "/api/v1/auth"]
  bump_severity: true
  tag: sensitive_endpoint

​

Supported features

​

Pros

• Zero coding — pure declarative YAML.
• Fast to write — a payload list + matcher regex is often all you need.
• Easy to audit — non-technical team members can review rules.
• Same pipeline integration — loaded alongside JS extensions, same lifecycle.

​

Cons

• Limited logic — no conditionals, loops, or state beyond what matchers offer.
• No API access — no database queries, HTTP follow-ups, or AI calls (unless you use the script escape hatch, which is effectively JS).
• No multi-step checks — can’t chain requests or compare responses across steps.
• Coarser insertion control — payload injection is straightforward but you can’t dynamically generate payloads based on context.

​

When to use

• Simple signature-based detection (error strings, header patterns, status codes).
• Quick pre-hook rules (add auth headers, skip static assets).
• Post-hook filtering (suppress low-severity findings on static paths).
• When non-developers need to contribute scanning rules.

​

3. Custom Prompt Templates

​

Template format

---
id: my-custom-review
name: My Custom Review
description: What this template does
output_schema: findings    # or: http_records
variables:
  - SourceCode
  - Language
  - PreviousFindings
---

You are a security engineer. Analyze the following code for {{.Language}} vulnerabilities.

{{if .PreviousFindings}}
Previous findings to verify:
{{.PreviousFindings}}
{{end}}

Source code:
```
{{.SourceCode}}
```

Respond with JSON: {"findings": [...]}

​

Available template variables

​

Output schemas

{
  "findings": [{
    "title": "SQL Injection in login handler",
    "severity": "critical",
    "confidence": "certain",
    "file": "auth/login.go",
    "line": 42,
    "snippet": "db.Query(\"SELECT * FROM users WHERE id=\" + userID)",
    "cwe": "CWE-89",
    "tags": ["sqli"]
  }]
}

{
  "http_records": [{
    "method": "POST",
    "url": "https://api.example.com/users",
    "headers": {"Content-Type": "application/json"},
    "body": "{\"name\": \"test\"}",
    "notes": "Create user endpoint"
  }]
}

​

Preset templates

​

Setup

# Use a custom template
vigolium agent --prompt-template my-custom-review --repo /path/to/source

# Dry-run to see the rendered prompt
vigolium agent --prompt-template my-custom-review --repo /path/to/source --dry-run

​

Pros

• No code — Markdown files with template syntax.
• Context-aware — automatic enrichment with database findings, endpoints, scan stats.
• Multiple AI backends — works with Claude, Codex, OpenCode, Gemini, or any custom agent.
• Iterative refinement — autopilot and pipeline modes pass prior findings back for verification.
• Two output modes — emit findings for code review or HTTP records for endpoint discovery.

​

Cons

• AI dependency — requires a configured agent backend and API access.
• Non-deterministic — LLM output varies between runs; false positives require tuning.
• Latency — agent invocations are slower than pattern matching (seconds to minutes per run).
• Token costs — large codebases consume significant tokens per analysis.

​

When to use

• Code-level security review that needs semantic understanding (not just pattern matching).
• Generating HTTP test inputs from source code (route extraction, API fuzzing seeds).
• Framework-specific audits (Next.js, React, Django, Spring) where templates can embed domain knowledge.
• Iterative analysis where the agent refines findings across multiple passes.

​

4. Scanning Profiles

​

Format

# ~/.vigolium/profiles/aggressive.yaml
# description: Fast aggressive scan for CI/CD pipelines

scanning_strategy:
  default_strategy: deep

scanning_pace:
  concurrency: 100
  rate_limit: 200
  max_per_host: 20
  audit:
    concurrency: 100
    max_duration: 60m

discovery:
  mode: files_and_dirs
  recursion:
    enabled: true
    max_depth: 8

spidering:
  max_depth: 0
  headless: true
  strategy: aggressive

audit:
  enabled_modules:
    active_modules:
      - all
    passive_modules:
      - all

​

Usage

# Use a named profile
vigolium scan --target https://example.com --scanning-profile aggressive

# Use a profile file path
vigolium scan --target https://example.com --scanning-profile /path/to/profile.yaml

​

Pros

• Reusable presets — define once, use across targets and teams.
• Composable — overlay on top of base config; only override what you need.
• No code — pure YAML.
• Team-friendly — share profiles in version control for consistent scan policies.

​

Cons

• Config-only — can’t add new scanning logic, only tune existing settings.
• No per-target logic — same profile applies to all targets in a scan.
• Limited validation — typos in field names silently ignored.

​

When to use

• You run different scan intensities for different contexts (CI/CD vs. full audit vs. quick check).
• You want to enforce consistent scan settings across a team.
• You need to toggle phases (e.g., skip discovery, only run passive modules).

​

5. Scope Rules

​

Configuration

# vigolium-configs.yaml
scope:
  applied_on_ingest: false     # enforce at ingest time or scan time

  host:
    include: ["*.example.com", "api.example.com"]
    exclude: ["staging.example.com"]

  path:
    include: ["/api/*"]
    exclude: ["/api/health", "/api/metrics", "/static/*"]

  status_code:
    include: ["2xx", "3xx"]    # exact, wildcard (2xx), range (400-499)
    exclude: ["404"]

  request_content_type:
    include: ["application/json*", "application/x-www-form-urlencoded*"]

  response_content_type:
    include: ["text/html*", "application/json*"]
    exclude: ["image/*", "font/*"]

  ignore_static_file: true     # auto-skip .jpg, .png, .css, etc.

​

Scope from extensions

// Check scope programmatically
if (vigolium.scan.isInScope("api.example.com", "/users")) {
  // proceed
}

// Read current scope
var scope = vigolium.scan.getScope();

// Modify scope at runtime
vigolium.scan.setScope({
  host: { include: ["*.example.com"], exclude: [] },
  path: { include: ["/api/*"], exclude: [] }
});

​

Pros

• Precision targeting — scan only what matters, skip noise.
• Multiple filter types — host globs, path patterns, status codes, content types, body strings.
• Runtime adjustable — extensions can modify scope during a scan.
• Safety net — prevents accidental scanning of out-of-scope systems.

​

Cons

• Config-only complexity — complex scope rules can be hard to debug.
• No request-level conditions — you can’t scope by request header values or authentication state (use pre-hooks for that).

​

When to use

• Restricting scans to specific subdomains or API paths.
• Excluding health checks, static assets, or third-party endpoints.
• Bug bounty programs with defined scope boundaries.
• Filtering by response characteristics (status codes, content types).

​

6. Pre-Hooks and Post-Hooks

​

Pre-hook use cases

​

Post-hook use cases

​

JS pre-hook example

module.exports = {
  id: "inject-session",
  name: "Session Injector",
  type: "pre_hook",

  execute: function(request) {
    return {
      headers: {
        "Cookie": "session=" + vigolium.config.session_token,
        "X-Correlation-ID": vigolium.utils.randomString(16)
      }
    };
  }
};

​

JS post-hook example (AI false positive filter)

module.exports = {
  id: "ai-fp-filter",
  name: "AI False Positive Filter",
  type: "post_hook",

  execute: function(result) {
    if (typeof vigolium.agent === "undefined") return result;

    var check = vigolium.agent.confirmFinding({
      name: result.info.name,
      request: result.request,
      response: result.response,
      matched: result.matched
    });

    if (!check.confirmed && check.confidence !== "low") {
      vigolium.log.info("Suppressed FP: " + result.info.name);
      return null; // drop the finding
    }
    return result;
  }
};

​

Pros

• Pipeline integration — runs automatically on every request/finding.
• Composable — multiple hooks chain sequentially.
• Both JS and YAML — simple rules in YAML, complex logic in JS.
• Non-invasive — doesn’t modify module code.

​

Cons

• Sequential overhead — hooks run on the hot path; slow hooks slow everything.
• Order-dependent — hook execution order matters but isn’t always obvious.
• Pre-hooks can’t see responses — they only have access to the outbound request.

​

When to use

• You need to inject authentication into every request (pre-hook).
• You want to suppress known false positives across all modules (post-hook).
• You need to tag or route findings based on URL patterns (post-hook).
• AI-powered confirmation of findings before reporting (post-hook).

​

7. Agent Providers (Olium)

​

Built-in providers

​

Configuring a provider

# vigolium-configs.yaml
agent:
  olium:
    provider: anthropic-api-key
    model: claude-opus-4-7
    llm_api_key: ${ANTHROPIC_API_KEY}
    reasoning_effort: medium       # codex providers only
    max_tokens: 1000000
    max_turns: 32
    max_concurrent: 4              # global cap on simultaneous provider calls
    call_timeout_sec: 600

vigolium agent query --prompt-template security-code-review --source ./app \
  --provider anthropic-api-key --model claude-opus-4-7

vigolium agent autopilot -t https://example.com \
  --provider claude-oauth --oauth-token "$ANTHROPIC_API_KEY"

vigolium ol --provider openai-api-key --llm-api-key "$OPENAI_API_KEY"

Server-side workloads: the REST API does not mirror these per-invocation flags. The server resolves the provider once from agent.olium.* and reuses it across requests so prompt caches stay stable.

​

Tool registry

​

LLM config (for JS extensions only)

agent:
  llm:
    provider: anthropic    # or openai
    model: claude-sonnet-4-20250514
    api_key_env: ANTHROPIC_API_KEY
    max_tokens: 4096
    temperature: 0.0
    cache_size: 256        # LRU cache; 0 = disabled
    cache_ttl: 300         # seconds

​

Pros

• Five providers — pick the credential model that fits (OAuth for ChatGPT Plus / Claude Max, API keys for raw API access, CLI shellout for claude-code-cli).
• Single in-process runtime — no subprocess startup overhead, prompt caching is reused across phases that share an engine.
• Per-invocation overrides — every CLI subcommand exposes --provider, --model, --oauth-cred, --oauth-token, --llm-api-key.
• Global concurrency cap — max_concurrent keeps tier-1 plans from hitting 429s under fan-out.

​

Cons

• Provider lock-in to supported drivers — only the five drivers above are recognised; arbitrary custom CLIs are not pluggable as backends anymore.
• Cost — LLM API calls still have token costs; --token-budget (autopilot) caps the spend.

​

When to use

• Always — every agent subcommand goes through olium. The choice you actually make is which provider and model, not whether to use olium.

​

8. Configuration Overrides

​

Key configuration sections

​

Environment variable expansion

database:
  postgres:
    password: ${VIGOLIUM_DB_PASSWORD}

agent:
  llm:
    api_key_env: ANTHROPIC_API_KEY

​

Pros

• Comprehensive — controls every scanner behavior.
• Environment-aware — variable expansion for secrets.
• Layered — base config + profiles + CLI flags, in order of precedence.

​

Cons

• No logic — pure configuration, can’t express conditional behavior.
• Silent failures — unrecognized keys are ignored, not flagged.
• Single file — large configs can become unwieldy.

​

When to use

• Tuning scan speed and resource usage for your infrastructure.
• Selecting which modules run by default.
• Configuring database, notifications, and OAST.
• Setting organization-wide defaults.

​

Decision Matrix