USER_GUIDE.md

CVE Explorer Pro User Guide v0.1.1

Table of Contents

1. Getting Started
2. Installation
3. Basic Usage
4. Advanced Features
5. API Reference
6. Examples
7. Best Practices
8. Troubleshooting

Getting Started

CVE Explorer Pro is a comprehensive Rust library and CLI tool designed for deep vulnerability analysis. Whether you're a security researcher, penetration tester, or developer, this tool provides sophisticated capabilities for understanding and analyzing Common Vulnerabilities and Exposures (CVEs).

What's New in v0.1.1

• Enhanced Code Quality: Removed mock-up code for improved reliability
• Better Error Handling: More robust error management and edge case handling
• Performance Improvements: Optimized analysis algorithms
• Comprehensive Documentation: Complete API documentation and examples

Installation

As a CLI Tool

cargo install cve_explorer_pro

As a Library

Add to your Cargo.toml:

[dependencies]
cve_explorer_pro = "0.1.1"

Requirements

• Rust 1.70.0 or later
• Internet connection for NVD API access
• Optional: NVD API key for higher rate limits

Basic Usage

Command Line Interface

The CLI provides three analysis modes:

1. Basic Analysis

cve-explorer --cve CVE-2021-34527

Provides:

• Root cause analysis
• Vulnerability categorization
• Basic severity assessment
• Prevention recommendations

2. Exploitation Analysis

cve-explorer --cve CVE-2021-34527 --mode exploitation

Provides:

• Attack surface mapping
• Entry point identification
• Privilege escalation analysis
• Proof-of-concept templates

3. Full Analysis

cve-explorer --cve CVE-2021-34527 --mode full

Combines both basic and exploitation analysis for comprehensive insights.

Output Formats

JSON Output

cve-explorer --cve CVE-2021-34527 --format json

Perfect for automation and integration with other tools.

Summary Format

cve-explorer --cve CVE-2021-34527 --format summary

Concise overview with key findings.

Detailed Format (Default)

cve-explorer --cve CVE-2021-34527 --format detailed

Human-readable comprehensive report.

Using with API Key

For enhanced rate limits (50 requests/30 seconds vs 5 requests/30 seconds):

cve-explorer --cve CVE-2021-34527 --api-key YOUR_NVD_API_KEY

Get your free API key at: https://nvd.nist.gov/developers/request-an-api-key

Advanced Features

Library Usage

Basic CVE Fetching and Analysis

use cve_explorer_pro::{CVEFetcher, RootCauseAnalyzer};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize fetcher
    let fetcher = CVEFetcher::new(Some("your_api_key".to_string()));
    
    // Fetch CVE data
    let cve = fetcher.fetch_cve("CVE-2021-34527").await?;
    
    // Analyze vulnerability
    let analyzer = RootCauseAnalyzer;
    let analysis = analyzer.analyze_vulnerability(&cve);
    
    println!("CVE ID: {}", cve.id);
    println!("Severity: {:?}", cve.cvss.as_ref().unwrap().severity);
    println!("Primary Cause: {:?}", analysis.primary_cause);
    
    Ok(())
}

Exploitation Path Analysis

use cve_explorer_pro::{CVEFetcher, ExploitationPathAnalyzer};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let fetcher = CVEFetcher::new(None);
    let cve = fetcher.fetch_cve("CVE-2021-34527").await?;
    
    // Perform exploitation analysis
    let exploit_analyzer = ExploitationPathAnalyzer;
    let exploitation = exploit_analyzer.analyze_exploitation_path(&cve);
    
    println!("Attack Complexity: {:.1}/10", exploitation.exploitation_complexity.overall_score);
    println!("Entry Points: {}", exploitation.attack_surface.entry_points.len());
    
    // Access proof-of-concept template
    if let Some(poc) = &exploitation.poc_template {
        println!("PoC Language: {}", poc.language);
        println!("Target Environment: {}", poc.target_environment);
    }
    
    Ok(())
}

Combined Analysis with JSON Output

use cve_explorer_pro::{CVEFetcher, RootCauseAnalyzer, ExploitationPathAnalyzer, display_json_output};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let fetcher = CVEFetcher::new(None);
    let cve = fetcher.fetch_cve("CVE-2021-34527").await?;
    
    // Perform both analyses
    let analyzer = RootCauseAnalyzer;
    let analysis = analyzer.analyze_vulnerability(&cve);
    
    let exploit_analyzer = ExploitationPathAnalyzer;
    let exploitation = exploit_analyzer.analyze_exploitation_path(&cve);
    
    // Output as JSON
    display_json_output(&cve, Some(&analysis), Some(&exploitation))?;
    
    Ok(())
}

API Reference

Core Structures

CVE

The main data structure representing a vulnerability:

• id: CVE identifier (e.g., "CVE-2021-34527")
• description: Detailed vulnerability description
• cvss: CVSS scoring information
• exploitability: Exploitation characteristics
• remediation: Patch and mitigation information

RootCauseAnalysis

Results of vulnerability root cause analysis:

• primary_cause: Main vulnerability category
• contributing_factors: Additional factors
• architectural_flaws: Design-level issues
• prevention_recommendations: Remediation advice

ExploitationAnalysis

Results of exploitation path analysis:

• attack_surface: Entry points and interfaces
• exploitation_complexity: Difficulty scoring
• privilege_escalation_chain: Attack progression
• poc_template: Proof-of-concept code template

Key Methods

CVEFetcher::new(api_key: Option) -> Self

Creates a new CVE fetcher with optional API key.

CVEFetcher::fetch_cve(cve_id: &str) -> Result<CVE, CVEError>

Fetches CVE data from the NVD API.

RootCauseAnalyzer::analyze_vulnerability(cve: &CVE) -> RootCauseAnalysis

Performs root cause analysis on a CVE.

ExploitationPathAnalyzer::analyze_exploitation_path(cve: &CVE) -> ExploitationAnalysis

Analyzes exploitation paths and attack surfaces.

Examples

Example 1: Security Research Workflow

use cve_explorer_pro::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let cves = vec!["CVE-2021-34527", "CVE-2020-1472", "CVE-2019-0708"];
    let fetcher = CVEFetcher::new(None);
    let analyzer = RootCauseAnalyzer;
    
    for cve_id in cves {
        println!("\n=== Analyzing {} ===", cve_id);
        
        match fetcher.fetch_cve(cve_id).await {
            Ok(cve) => {
                let analysis = analyzer.analyze_vulnerability(&cve);
                
                println!("Severity: {:?}", cve.cvss.as_ref().unwrap().severity);
                println!("Primary Cause: {:?}", analysis.primary_cause);
                println!("Contributing Factors: {}", analysis.contributing_factors.len());
                
                // Check if high-risk
                if cve.cvss.as_ref().unwrap().base_score >= 7.0 {
                    println!("⚠️  HIGH RISK vulnerability detected!");
                }
            }
            Err(e) => eprintln!("Error analyzing {}: {}", cve_id, e),
        }
    }
    
    Ok(())
}

Example 2: Automated Report Generation

use cve_explorer_pro::*;
use std::fs::File;
use std::io::Write;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let fetcher = CVEFetcher::new(None);
    let cve = fetcher.fetch_cve("CVE-2021-34527").await?;
    
    let analyzer = RootCauseAnalyzer;
    let analysis = analyzer.analyze_vulnerability(&cve);
    
    let exploit_analyzer = ExploitationPathAnalyzer;
    let exploitation = exploit_analyzer.analyze_exploitation_path(&cve);
    
    // Generate report
    let mut report = File::create("vulnerability_report.txt")?;
    
    writeln!(report, "CVE ANALYSIS REPORT")?;
    writeln!(report, "===================")?;
    writeln!(report, "CVE ID: {}", cve.id)?;
    writeln!(report, "Severity: {:?}", cve.cvss.as_ref().unwrap().severity)?;
    writeln!(report, "CVSS Score: {:.1}", cve.cvss.as_ref().unwrap().base_score)?;
    writeln!(report, "Primary Cause: {:?}", analysis.primary_cause)?;
    writeln!(report, "Exploitation Complexity: {:.1}/10", exploitation.exploitation_complexity.overall_score)?;
    writeln!(report, "Attack Surface Entry Points: {}", exploitation.attack_surface.entry_points.len())?;
    
    println!("Report generated: vulnerability_report.txt");
    
    Ok(())
}

Example 3: Integration with Monitoring Systems

use cve_explorer_pro::*;
use serde_json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let fetcher = CVEFetcher::new(std::env::var("NVD_API_KEY").ok());
    
    // Monitor specific CVEs
    let watch_list = vec!["CVE-2021-34527", "CVE-2020-1472"];
    
    for cve_id in watch_list {
        match fetcher.fetch_cve(cve_id).await {
            Ok(cve) => {
                let analyzer = RootCauseAnalyzer;
                let analysis = analyzer.analyze_vulnerability(&cve);
                
                // Create alert payload
                let alert = serde_json::json!({
                    "cve_id": cve.id,
                    "severity": cve.cvss.as_ref().unwrap().severity,
                    "score": cve.cvss.as_ref().unwrap().base_score,
                    "primary_cause": analysis.primary_cause,
                    "timestamp": chrono::Utc::now(),
                    "requires_attention": cve.cvss.as_ref().unwrap().base_score >= 7.0
                });
                
                println!("Alert payload: {}", serde_json::to_string_pretty(&alert)?);
                
                // Here you would send to your monitoring system
                // send_alert_to_monitoring_system(&alert).await?;
            }
            Err(e) => eprintln!("Failed to fetch {}: {}", cve_id, e),
        }
    }
    
    Ok(())
}

Best Practices

1. API Key Management

• Always use environment variables for API keys
• Never hardcode API keys in source code
• Consider rate limiting in production applications

let api_key = std::env::var("NVD_API_KEY").ok();
let fetcher = CVEFetcher::new(api_key);

2. Error Handling

• Always handle potential network failures
• Implement retry logic for critical applications
• Log errors appropriately

match fetcher.fetch_cve(cve_id).await {
    Ok(cve) => {
        // Process CVE
    }
    Err(CVEError::NetworkError(e)) => {
        eprintln!("Network error: {}. Retrying...", e);
        // Implement retry logic
    }
    Err(CVEError::NotFound) => {
        eprintln!("CVE {} not found", cve_id);
    }
    Err(e) => {
        eprintln!("Unexpected error: {}", e);
    }
}

3. Performance Optimization

• Cache CVE data when analyzing multiple related vulnerabilities
• Use batch processing for large datasets
• Consider async processing for concurrent analysis

4. Security Considerations

• Validate CVE IDs before processing
• Sanitize output when displaying analysis results
• Be cautious when executing generated proof-of-concept code

Troubleshooting

Common Issues

1. Rate Limiting

Problem: Getting rate limited by NVD API

Solution:

• Obtain and use an API key
• Implement proper delays between requests
• Use exponential backoff for retries

2. Network Connectivity

Problem: Network timeouts or connection failures

Solution:

• Check internet connectivity
• Verify firewall settings allow HTTPS traffic
• Implement timeout and retry mechanisms

3. Invalid CVE IDs

Problem: CVE not found errors

Solution:

• Verify CVE ID format (CVE-YYYY-NNNN)
• Check if CVE exists in NVD database
• Ensure CVE is published (not reserved)

4. JSON Parsing Errors

Problem: Failed to parse NVD response

Solution:

• Check if NVD API format has changed
• Verify network response is complete
• Update to latest library version

Debug Mode

Enable debug logging for troubleshooting:

env_logger::init();
log::debug!("Fetching CVE: {}", cve_id);

Getting Help

• Issues: Report bugs at GitHub Issues
• Documentation: Visit docs.rs
• Examples: Check the examples/ directory in the repository

---

CVE Explorer Pro v0.1.1 - Enhanced security analysis for the modern threat landscape