DOCSEARCHbyAlgolia
Submit Docs

vulnx Documentation

repository·main·Indexed 25 days ago

https://github.com/projectdiscovery/vulnx

A modern CLI tool for exploring, searching, and analyzing vulnerability data. vulnx provides advanced query syntax with boolean logic, field-specific filtering, and range comparisons. It includes a flexible renderer package for creating custom JSON-based CLI layouts, support for JSON output, and integration with ProjectDiscovery Cloud for enhanced API limits.

Tokens
18.5K
Snippets
60
Records
92
Agent score
82%

What's inside vulnx

  1. Understand the vulnx project structure

    main

    The repository is organized as follows:

    • cmd/vulnx/: Main CLI application source.
    • cmd/integration-test/: Integration tests source.
    • pkg/runner/: Core application logic.
    • pkg/service/: API service layer.
    • pkg/types/: Type definitions.
    • pkg/tools/: CLI tools and MCP handlers.
    • pkg/utils/: Utility functions.
    • static/: Static assets.
    • scripts/: Build and development scripts.

  2. Renderer Formatting and Display Rules

    main

    The renderer applies several automatic formatting rules to ensure clean CLI output:

    Exposure Formatting

    • 0 is rendered as "unknown".
    • 1-999 is rendered as-is.
    • 1000+ uses a shorthand format (e.g., "~12.3K").

    Boolean and POC Formatting

    • Booleans: true becomes "✔", false becomes "✘".
    • POC Count: 0 becomes "✘", values >0 are rendered as the numeric value.

    List Truncation

    Lists (like authors, vendors, products, or tags) are truncated to a maximum of 3 items. Additional items are shown as a count suffix (e.g., "item1, item2, item3 +2").

    Age Urgency Indicators

    • ≤7 days: {age_in_days}d (NEW)
    • ≤30 days: {age_in_days}d (RECENT)
    • >30 days: {age_in_days}d (no indicator)

    Exploit Detection

    The renderer automatically detects if a vulnerability has been exploited by checking:

    1. POC sources for keywords: exploit, exploiting, exploitation, exploitable.
    2. Citation URLs for domains: exploit-db.com, exploitdb.com, metasploit.com.
    3. Description/Impact text for phrases like "exploited in the wild" or "actively exploited".

  3. Compare Git Hook, Pre-commit, and Manual script options

    main

    Choose the setup method that best fits your workflow:

    FeatureGit Hook (Option 1)Pre-commit Framework (Option 2)Manual Script (Option 3)
    Setup Complexity✅ Simple (make git-hooks)⚠️ Requires Python/pip✅ Simple
    Dependencies✅ Zero external deps❌ Requires pre-commit package✅ Zero deps
    Performance⚠️ Always runs all checks✅ Smart file filtering⚠️ Manual only
    Automation✅ Automatic on commit✅ Automatic on commit❌ Manual
    Team Consistency✅ One command setup✅ One command setup❌ Manual setup
    Advanced Features❌ Basic functionality✅ YAML config, updates❌ Basic

    Recommendations:

    • Git Hook: Best for simplicity and zero dependencies.
    • Pre-commit Framework: Best for advanced features and if Python is available.
    • Manual Script: Best for occasional use or debugging.

  4. Use the Vulnerability CLI Renderer

    main

    The renderer package provides a flexible system for rendering vulnerability search results in a CLI using a JSON-based layout configuration. It supports smart omission of empty fields, list truncation, and automatic formatting for booleans, numbers, and urgency indicators.

    To use the renderer, you must:

    1. Define a JSON layout containing LayoutLine objects.
    2. Parse the layout using ParseLayout.
    3. Convert your vulnx.Vulnerability objects into renderer.Entry objects using FromVulnerability.
    4. Call Render to generate the final string output.
    package main

import (
    "fmt"
    "log"

    "github.com/projectdiscovery/vulnx/pkg/tools/renderer"
    "github.com/projectdiscovery/vulnx"
)

func main() {
    // Define layout configuration
    layoutJSON := `[
        {
            "line": 1,
            "format": "[{doc_id}] {severity} - {title}",
            "omit_if": []
        },
        {
            "line": 2,
            "format": "↳ Authors: {authors} | Vuln Age: {age_in_days}d | EPSS: {epss_score} | CVSS: {cvss_score}",
            "omit_if": ["authors.length == 0", "epss_score == 0", "cvss_score == 0"]
        }
    ]`

    // Parse layout
    layout, err := renderer.ParseLayout([]byte(layoutJSON))
    if err != nil {
        log.Fatal(err)
    }

    // Convert vulnerability to entry
    entry := renderer.FromVulnerability(vuln)
    entries := []*renderer.Entry{entry}

    // Render output
    result := renderer.Render(entries, layout, 1, 1)
    fmt.Println(result)
}

  6. Get help and discover searchable fields

    main

    You can access help documentation for specific commands or explore available data fields using the following commands. Note that data exploration is subject to rate limits if no API key is configured.

    # Command help
vulnx --help                           # All commands overview
vulnx search --help                    # Search command help

# Data exploration
vulnx filters                          # Show all searchable fields
vulnx search help                      # Detailed search fields
vulnx analyze help                     # Available analyze fields

  7. Common search patterns for security research and compliance

    main

    The following patterns are useful for common security workflows:

    Security Research:

    • Find vulnerability families using string searches.
    • Find exploitation research using is_poc:true and sorting by epss_score.

    Compliance & Reporting:

    • Generate reports by filtering by vendor and year, then exporting to JSON.
    • Perform risk assessments using vulnx analyze.
    • Limit output to specific fields using --fields to reduce payload size.
    # Find vulnerability families
vulnx search "'buffer overflow' && severity:high"
vulnx search "description:'SQL injection'" --limit 100

# Exploitation research
vulnx search "is_poc:true && cvss_score:>9.0" --sort-desc epss_score
vulnx search "tags:rce && is_template:true"

# Generate compliance reports
vulnx search "affected_products.vendor:microsoft && cve_created_at:2024" \
  --output microsoft_2024_vulns.json

# Risk assessment data
vulnx analyze -f severity -q "is_remote:true"
vulnx search "severity:critical" --fields cve_id,cvss_score,epss_score

  8. Install golangci-lint

    main

    Installing golangci-lint is highly recommended for comprehensive linting during the pre-commit process.

    macOS:

    brew install golangci-lint

    Linux:

    curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin

    Windows:

    go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
    # macOS
brew install golangci-lint

# Linux
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin

# Windows
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

  9. Perform date-based vulnerability searches

    main

    When querying date fields, you must use comparison operators (>=, >, <, <=). Supported date formats include year (2024), year-month (2024-01), and full date (2024-01-15).

    Single date comparisons:

    • cve_created_at:>=2024 (CVEs from 2024 onward)
    • cve_created_at:<2024 (CVEs before 2024)
    • cve_created_at:>2024-06-01 (CVEs after June 1, 2024)

    Date ranges and age-based queries:

    • Use && to combine date constraints for specific ranges.
    • Use age_in_days for relative time queries.
    # CVEs from January 2024 only
vulnx search "cve_created_at:>=2024-01-01 && cve_created_at:<2024-02-01"

# High CVSS CVEs from 2024
vulnx search "cvss_score:>8.0 && cve_created_at:>=2024"

# Recent vulnerabilities (age-based)
vulnx search "age_in_days:<30"            # Last 30 days
vulnx search "age_in_days:>365"           # Older than 1 year

  10. Set up local quality checks using the Pre-commit Framework

    main

    If you require advanced features like smart file filtering and YAML configuration, use the pre-commit framework. This requires Python and pip to be installed on your system.

    1. Install the pre-commit package:
      pip install pre-commit
    2. Install the hooks using the provided Makefile:
      make pre-commit

    Once installed, pre-commit will run automatically on every git commit.

    pip install pre-commit
make pre-commit

  11. Optimize queries using effective field usage

    main

    To improve search precision and efficiency, target specific fields instead of using generic terms. You can target specific vendors or products using dot notation (e.g., affected_products.vendor) and combine multiple criteria using logical operators like &&.

    # Target specific vendors/products
vulnx search "affected_products.vendor:microsoft"
vulnx search "affected_products.product:windows"

# Combine multiple criteria efficiently
vulnx search "severity:critical && is_remote:true && is_poc:true"

# Use comparison operators for scores
vulnx search "cvss_score:>8.0"
vulnx search "cvss_score:<9.0"

  12. Manage API limits and automation best practices

    main

    When automating vulnx in scripts, follow these best practices to avoid rate limits and ensure reliability:

    • Rate Limiting: Implement delays (e.g., sleep 1) between consecutive commands in scripts.
    • Batching: Use --limit and --output to handle large datasets in chunks.
    • Silent Mode: Use --silent to suppress banners in automated environments.
    • Structured Data: Use --output with JSON for easy parsing with tools like jq.
    • Pagination: Handle large datasets using --limit and --offset.
    # Implement delays in scripts
vulnx search "query1" && sleep 1 && vulnx search "query2"

# Use batch operations efficiently
vulnx search "large_query" --limit 1000 --output batch1.json