Customizing & Extending Vigolium

​

Table of Contents

• Extension Points at a Glance
• 1. JavaScript Extensions
• 2. YAML Extensions
• 3. Go Modules
• 4. Custom Prompt Templates
• 5. Scanning Profiles
• 6. Scope Rules
• 7. Pre-Hooks and Post-Hooks
• 8. Agent Backends
• 9. 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. Go Modules

​

Module interfaces

type Module interface {
    ID() string
    Name() string
    Description() string
    ShortDescription() string
    ConfirmationCriteria() string
    Severity() severity.Severity
    Confidence() severity.Confidence
    ScanScopes() ScanScope
    CanProcess(ctx *httpmsg.HttpRequestResponse) bool
}

type ActiveModule interface {
    Module
    AllowedInsertionPointTypes() InsertionPointTypeSet
    ScanPerInsertionPoint(ctx, ip, httpClient, scanCtx) ([]*ResultEvent, error)
    ScanPerRequest(ctx, httpClient, scanCtx) ([]*ResultEvent, error)
    ScanPerHost(ctx, httpClient, scanCtx) ([]*ResultEvent, error)
}

type PassiveModule interface {
    Module
    Scope() PassiveScanScope
    ScanPerRequest(ctx, scanCtx) ([]*ResultEvent, error)
    ScanPerHost(ctx, scanCtx) ([]*ResultEvent, error)
}

​

Creating a module

1. Create a package under pkg/modules/active/ or pkg/modules/passive/.
2. Embed modkit.BaseActiveModule or modkit.BasePassiveModule for defaults.
3. Implement scan methods for your declared scopes.
4. Register in pkg/modules/default_registry.go.

package my_check

import (
    "github.com/vigolium/vigolium/pkg/modules/modkit"
    "github.com/vigolium/vigolium/pkg/output"
    // ...
)

type Module struct {
    modkit.BaseActiveModule
}

func New() *Module {
    return &Module{
        BaseActiveModule: modkit.NewBaseActiveModule(
            "my-check",
            "My Custom Check",
            "Detailed description of what this checks",
            "One-line summary",
            "How the vulnerability is confirmed",
            severity.High,
            severity.Firm,
            modkit.ScanScopeInsertionPoint,
            modkit.AllParamTypes,
        ),
    }
}

func (m *Module) ScanPerInsertionPoint(
    ctx *httpmsg.HttpRequestResponse,
    ip httpmsg.InsertionPoint,
    httpClient *http.Requester,
    scanCtx *modkit.ScanContext,
) ([]*output.ResultEvent, error) {
    // Your scanning logic here
    return nil, nil
}

​

Scan scope options

​

Pros

• Maximum performance — compiled Go, no interpreter overhead, runs in the concurrent worker pool.
• Full internal access — HTTP client with middleware, deduplication manager, OAST callbacks, mutation engine, baseline caching.
• Type safety — compile-time checks, IDE support, Go testing ecosystem.
• First-class integration — same lifecycle as built-in modules, automatic pipeline wiring.

​

Cons

• Requires recompilation — every change needs make build.
• Go knowledge required — must understand Go, the module interfaces, and internal types.
• Slower iteration — compile-test cycle is heavier than drop-in JS/YAML.
• Tighter coupling — changes to internal APIs may require module updates.

​

When to use

• Performance-critical checks that run on every request or insertion point.
• Checks that need deep integration with Vigolium internals (OAST, mutation engine, dedup).
• You’re contributing to the core scanner or building a permanent module.
• Checks requiring complex multi-step logic with full concurrency support.

​

4. 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.

​

5. 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).

​

6. 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).

​

7. 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).

​

8. Agent Backends

​

Built-in backends

​

Adding a custom backend

# vigolium-configs.yaml
agent:
  backends:
    my-agent:
      command: my-tool
      args: ["--json", "--security-mode"]
      description: "My custom security agent"
      protocol: pipe        # pipe: prompt on stdin, output on stdout
      env:
        MY_API_KEY: "${MY_API_KEY}"

vigolium agent --agent my-agent --prompt-template security-code-review --repo /path/to/code

​

Protocols

​

Warm sessions

agent:
  warm_session:
    enable: true
    idle_timeout: 300    # seconds before killing idle session
    max_sessions: 2      # concurrent sessions per agent

​

LLM config (for JS extensions)

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

• Any AI model — plug in any CLI tool as a backend.
• Two protocols — simple pipe for basic tools, ACP for full agent capabilities.
• Session pooling — warm sessions reduce latency for iterative analysis.
• Environment isolation — per-agent env vars, scoped file access.

​

Cons

• External dependency — requires installing and configuring the agent CLI.
• Cost — AI API calls have token costs.
• Latency — subprocess startup + LLM inference is slower than local checks.

​

When to use

• You have a preferred AI model or a fine-tuned security model you want to integrate.
• You’re building a custom tool that produces structured security findings.
• You need agent capabilities beyond what the built-in backends provide.

​

9. 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